fix(mcp): preserve bounded portfolio handoffs

Author: morluto

internal/app/mcp_authored_sync.go

@@ -60,6 +60,7 @@ func (s *Service) syncAuthoredPullRequests(ctx context.Context, in authoredPullR
 	discovered := 0
 	incomplete := false
 	requestCapped := false
+	boundedByLimit := false
 	for discovered < in.Limit {
 		if requests+1 > in.MaxRequests {
 			requestCapped, incomplete = true, true
@@ -90,7 +91,11 @@ func (s *Service) syncAuthoredPullRequests(ctx context.Context, in authoredPullR
 				break
 			}
 		}
-		if !result.Page.HasNext || discovered >= in.Limit {
+		if discovered >= in.Limit {
+			boundedByLimit = result.Page.HasNext || result.Total > discovered
+			break
+		}
+		if !result.Page.HasNext {
 			break
 		}
 		page = result.Page.NextPage
@@ -141,6 +146,9 @@ func (s *Service) syncAuthoredPullRequests(ctx context.Context, in authoredPullR
 	close(jobs)
 	wg.Wait()
 	status := "complete"
+	if boundedByLimit {
+		status = "partial"
+	}
 	completed := 0
 	for _, result := range results {
 		requests += result.Requests

internal/app/mcp_job_artifacts.go

@@ -270,7 +270,7 @@ func portfolioResultRefs(values []string) []mcpcontract.ThreadRef {
 		if err != nil || number <= 0 {
 			continue
 		}
-		fullName := value[:marker]
+		fullName := strings.TrimSuffix(value[:marker], "/pull_request")
 		slash := strings.IndexByte(fullName, '/')
 		if slash <= 0 || slash == len(fullName)-1 {
 			continue

internal/app/mcp_jobs.go

@@ -191,17 +191,15 @@ func jobResultStatus(job *contracts.JobResult) string {
 }
 
 func portfolioReadFollowUpArguments(request mcpcontract.SyncPortfolioInput, login string, references []string) *mcpcontract.ListPullRequestPortfolioInput {
+	if request.Selection == "explicit" {
+		return &mcpcontract.ListPullRequestPortfolioInput{PullRequests: portfolioResultRefs(references), View: "compact"}
+	}
 	limit := request.Limit
 	state := request.State
 	if request.Selection == "authored" {
 		if login != "" {
 			return &mcpcontract.ListPullRequestPortfolioInput{Authors: []string{login}, State: state, Limit: limit, View: "compact"}
 		}
-	} else {
-		state = "all"
-		if limit == 0 || limit > len(references) {
-			limit = len(references)
-		}
 	}
 	if limit == 0 {
 		limit = 20

internal/app/mcp_jobs_test.go

@@ -136,6 +136,23 @@ func TestPortfolioFollowUpUsesPortfolioReadArguments(t *testing.T) {
 	}
 }
 
+func TestExplicitPortfolioFollowUpPreservesExactReferences(t *testing.T) {
+	t.Parallel()
+	job := &contracts.JobResult{
+		Kind: jobKindSyncPullRequestPortfolio, Status: "succeeded",
+		Request: `{"selection":"explicit","pull_requests":[{"owner":"acme","repo":"rocket","kind":"pull_request","number":7}]}`,
+		Result:  `{"status":"complete","pull_requests":["acme/rocket/pull_request#7"],"refreshed":1,"discovery_status":"complete"}`,
+	}
+	_, follow := jobArtifactsAndFollowUp(job, 1)
+	if follow == nil || follow.Action.ListPortfolio == nil || len(follow.Action.ListPortfolio.PullRequests) != 1 {
+		t.Fatalf("portfolio handoff = %+v", follow)
+	}
+	ref := follow.Action.ListPortfolio.PullRequests[0]
+	if ref.Owner != "acme" || ref.Repo != "rocket" || ref.Kind != "pull_request" || ref.Number != 7 {
+		t.Fatalf("exact portfolio handoff = %+v", ref)
+	}
+}
+
 func TestIndexJobPreservesFailuresAndBindsCompletedArtifactsToSnapshot(t *testing.T) {
 	t.Parallel()
 	job := &contracts.JobResult{

internal/app/mcp_portfolio_test.go

@@ -148,3 +148,29 @@ func TestPullRequestPortfolioKeepsComputingMergeabilityUnknown(t *testing.T) {
 		t.Fatalf("portfolio = %+v", out)
 	}
 }
+
+func TestPullRequestPortfolioExactSelectionDoesNotSubstituteNewerPullRequests(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	svc := newSearchTestService(t)
+	now := time.Unix(1000, 0).UTC()
+	repo, err := svc.corpus.UpsertRepository(ctx, corpus.Repository{Owner: "acme", Name: "rocket"}, `{}`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := svc.corpus.UpsertThread(ctx, corpus.Thread{RepositoryID: repo.ID, Kind: corpus.ThreadKindPullRequest, Number: 1, State: "open", Title: "selected", Author: "alice", SourceUpdatedAt: now}, `{}`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := svc.corpus.UpsertThread(ctx, corpus.Thread{RepositoryID: repo.ID, Kind: corpus.ThreadKindPullRequest, Number: 2, State: "open", Title: "newer unrelated", Author: "alice", SourceUpdatedAt: now.Add(time.Second)}, `{}`); err != nil {
+		t.Fatal(err)
+	}
+	out, err := (&MCPReader{svc}).ListPullRequestPortfolio(ctx, mcpcontract.ListPullRequestPortfolioInput{
+		PullRequests: []mcpcontract.ThreadRef{{Owner: "acme", Repo: "rocket", Kind: "pull_request", Number: 1}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out.Status != "partial" || len(out.PullRequests) != 1 || out.PullRequests[0].Number != 1 || len(out.UnavailablePullRequests) != 0 {
+		t.Fatalf("exact portfolio = %+v", out)
+	}
+}

internal/app/mcp_scalable_reads.go

@@ -257,6 +257,20 @@ func (r *MCPReader) ListPullRequestPortfolio(ctx context.Context, in mcpcontract
 	if len(in.Authors) > 1 {
 		return mcpcontract.ListPullRequestPortfolioOutput{}, errors.New("authors must contain at most one item")
 	}
+	if len(in.PullRequests) > 0 {
+		if len(in.PullRequests) > 100 {
+			return mcpcontract.ListPullRequestPortfolioOutput{}, errors.New("pull_requests must contain at most 100 items")
+		}
+		if len(in.Authors) > 0 || in.State != "" || in.Limit != 0 {
+			return mcpcontract.ListPullRequestPortfolioOutput{}, errors.New("pull_requests cannot be combined with authors, state, or limit")
+		}
+		if err := rejectDuplicateThreadRefs(in.PullRequests); err != nil {
+			return mcpcontract.ListPullRequestPortfolioOutput{}, err
+		}
+		if err := validatePullRequestRefs(in.PullRequests, "pull_requests"); err != nil {
+			return mcpcontract.ListPullRequestPortfolioOutput{}, err
+		}
+	}
 	if in.State == "" {
 		in.State = "open"
 	}
@@ -269,10 +283,10 @@ func (r *MCPReader) ListPullRequestPortfolio(ctx context.Context, in mcpcontract
 	if in.View != "compact" && in.View != "full" {
 		return mcpcontract.ListPullRequestPortfolioOutput{}, errors.New("view must be compact or full")
 	}
-	if in.Limit == 0 {
+	if in.Limit == 0 && len(in.PullRequests) == 0 {
 		in.Limit = 20
 	}
-	if in.Limit < 1 || in.Limit > 100 {
+	if len(in.PullRequests) == 0 && (in.Limit < 1 || in.Limit > 100) {
 		return mcpcontract.ListPullRequestPortfolioOutput{}, errors.New("limit must be between 1 and 100")
 	}
 	c, err := r.openReadOnlyCorpus(ctx)
@@ -283,11 +297,7 @@ func (r *MCPReader) ListPullRequestPortfolio(ctx context.Context, in mcpcontract
 	if err != nil {
 		return mcpcontract.ListPullRequestPortfolioOutput{}, err
 	}
-	author := ""
-	if len(in.Authors) > 0 {
-		author = strings.TrimSpace(in.Authors[0])
-	}
-	page, err := c.ListPullRequestPortfolioPage(ctx, author, in.State, in.Limit)
+	page, unavailable, err := portfolioPage(ctx, c, in)
 	if err != nil {
 		return mcpcontract.ListPullRequestPortfolioOutput{}, err
 	}
@@ -296,7 +306,11 @@ func (r *MCPReader) ListPullRequestPortfolio(ctx context.Context, in mcpcontract
 	if err != nil {
 		return mcpcontract.ListPullRequestPortfolioOutput{}, err
 	}
-	out := mcpcontract.ListPullRequestPortfolioOutput{Status: "complete", View: in.View, RuleVersion: "portfolio.v2", GeneratedAt: formatTime(r.now()), PullRequests: make([]mcpcontract.PullRequestPortfolioItem, 0, len(page.PullRequests)), Total: page.Total, Truncated: page.Truncated, SnapshotToken: snapshotIdentity(in.SnapshotToken, revision)}
+	out := mcpcontract.ListPullRequestPortfolioOutput{Status: "complete", View: in.View, RuleVersion: "portfolio.v2", GeneratedAt: formatTime(r.now()), PullRequests: make([]mcpcontract.PullRequestPortfolioItem, 0, len(page.PullRequests)), Total: page.Total, Truncated: page.Truncated, UnavailablePullRequests: unavailable, SnapshotToken: snapshotIdentity(in.SnapshotToken, revision)}
+	if len(unavailable) > 0 {
+		out.Status = "partial"
+		out.Recovery = recoveryPlan("portfolio_items_unavailable", "Some exact pull requests are not present in the local corpus. Refresh those exact pull requests, then reread the portfolio.", mcpcontract.RecoveryAction(mcpcontract.SyncPortfolioInput{Selection: "explicit", PullRequests: append([]mcpcontract.ThreadRef(nil), unavailable...)}))
+	}
 	for _, storedPR := range page.PullRequests {
 		item, err := portfolioItem(storedPR, r.now(), readSet, format)
 		if err != nil {
@@ -319,6 +333,51 @@ func (r *MCPReader) ListPullRequestPortfolio(ctx context.Context, in mcpcontract
 	return out, nil
 }
 
+func portfolioPage(ctx context.Context, c *corpus.Corpus, in mcpcontract.ListPullRequestPortfolioInput) (corpus.PortfolioPage, []mcpcontract.ThreadRef, error) {
+	if len(in.PullRequests) == 0 {
+		author := ""
+		if len(in.Authors) > 0 {
+			author = strings.TrimSpace(in.Authors[0])
+		}
+		page, err := c.ListPullRequestPortfolioPage(ctx, author, in.State, in.Limit)
+		return page, nil, err
+	}
+	repositoryKeys := make([]corpus.RepositoryKey, 0, len(in.PullRequests))
+	for _, ref := range in.PullRequests {
+		repositoryKeys = append(repositoryKeys, corpus.RepositoryKey{Owner: ref.Owner, Name: ref.Repo})
+	}
+	repositories, err := c.GetRepositoriesBatch(ctx, repositoryKeys)
+	if err != nil {
+		return corpus.PortfolioPage{}, nil, err
+	}
+	threadKeys := make([]corpus.ThreadKey, 0, len(in.PullRequests))
+	for _, ref := range in.PullRequests {
+		if repository := repositories[corpus.RepositoryKey{Owner: ref.Owner, Name: ref.Repo}]; repository != nil {
+			threadKeys = append(threadKeys, corpus.ThreadKey{RepositoryID: repository.ID, Kind: corpus.ThreadKindPullRequest, Number: ref.Number})
+		}
+	}
+	threads, err := c.GetThreadsBatch(ctx, threadKeys)
+	if err != nil {
+		return corpus.PortfolioPage{}, nil, err
+	}
+	page := corpus.PortfolioPage{PullRequests: make([]corpus.PortfolioPullRequest, 0, len(in.PullRequests)), Total: len(in.PullRequests)}
+	unavailable := make([]mcpcontract.ThreadRef, 0)
+	for _, ref := range in.PullRequests {
+		repository := repositories[corpus.RepositoryKey{Owner: ref.Owner, Name: ref.Repo}]
+		if repository == nil {
+			unavailable = append(unavailable, ref)
+			continue
+		}
+		thread := threads[corpus.ThreadKey{RepositoryID: repository.ID, Kind: corpus.ThreadKindPullRequest, Number: ref.Number}]
+		if thread == nil {
+			unavailable = append(unavailable, ref)
+			continue
+		}
+		page.PullRequests = append(page.PullRequests, corpus.PortfolioPullRequest{Owner: repository.Owner, Repo: repository.Name, Thread: *thread})
+	}
+	return page, unavailable, nil
+}
+
 type portfolioReadSet struct {
 	coverage     map[corpus.ThreadFacetKey]*corpus.Coverage
 	observations map[corpus.ThreadFacetKey]corpus.FacetObservationBatch

internal/app/sync_budget_test.go

@@ -16,6 +16,7 @@ type authoredHeaderReader struct {
 	listRequests     int
 	prDetailRequests int
 	now              time.Time
+	searchResult     github.AuthoredPullRequestSearchResult
 }
 
 func (r *authoredHeaderReader) GetRepository(context.Context, string, string) (github.Repository, github.RateInfo, error) {
@@ -61,12 +62,42 @@ func (*authoredHeaderReader) GetAuthenticatedIdentity(context.Context) (github.I
 }
 
 func (r *authoredHeaderReader) SearchAuthoredPullRequests(context.Context, github.AuthoredPullRequestSearchOptions) (github.AuthoredPullRequestSearchResult, error) {
+	if r.searchResult.Items != nil {
+		return r.searchResult, nil
+	}
 	return github.AuthoredPullRequestSearchResult{Items: []github.Issue{
 		{RepositoryOwner: "owner", RepositoryName: "repo", Kind: github.ThreadKindPullRequest, Number: 2, State: "open", Title: "first", CreatedAt: r.now, UpdatedAt: r.now},
 		{RepositoryOwner: "owner", RepositoryName: "repo", Kind: github.ThreadKindPullRequest, Number: 3, State: "open", Title: "second", CreatedAt: r.now, UpdatedAt: r.now},
 	}}, nil
 }
 
+func TestAuthoredPullRequestSyncReportsItemLimitTruncation(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
+	svc, err := New(paths, "test", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = svc.Close() }()
+	if _, err := svc.Init(ctx); err != nil {
+		t.Fatal(err)
+	}
+	now := time.Date(2026, 8, 8, 0, 0, 0, 0, time.UTC)
+	svc.SetGitHubReader(&authoredHeaderReader{now: now, searchResult: github.AuthoredPullRequestSearchResult{
+		Items: []github.Issue{{RepositoryOwner: "owner", RepositoryName: "repo", Kind: github.ThreadKindPullRequest, Number: 2, State: "open", Title: "first", CreatedAt: now, UpdatedAt: now}},
+		Total: 2,
+		Page:  github.PageInfo{HasNext: true, NextPage: 2},
+	}})
+	out, err := svc.syncAuthoredPullRequests(ctx, authoredPullRequestSyncOptions{State: "open", Limit: 1, MaxRequests: 20}, func(string, string) error { return nil })
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out.Status != "partial" || out.SearchIncomplete || out.RequestCapped || len(out.PullRequestTargets) != 1 {
+		t.Fatalf("bounded discovery = %+v", out)
+	}
+}
+
 func TestAuthoredPullRequestSyncReusesSearchHeadersWithoutNPlusOne(t *testing.T) {
 	t.Parallel()
 	ctx := context.Background()

internal/mcpcontract/scalable_contracts.go

@@ -502,11 +502,12 @@ type SyncCIFailuresInput struct {
 
 // ListPullRequestPortfolioInput filters and bounds the stored pull-request portfolio.
 type ListPullRequestPortfolioInput struct {
-	Authors       []string `json:"authors,omitempty" jsonschema:"Zero or one author login"`
-	State         string   `json:"state,omitempty" jsonschema:"open, closed, or all"`
-	Limit         int      `json:"limit,omitempty" jsonschema:"Maximum pull requests from 1 to 100; defaults to 20"`
-	View          string   `json:"view,omitempty" jsonschema:"compact or full; defaults to compact"`
-	SnapshotToken string   `json:"snapshot_token,omitempty" jsonschema:"Optional immutable corpus snapshot token from a previous offline read"`
+	Authors       []string    `json:"authors,omitempty" jsonschema:"Zero or one author login"`
+	PullRequests  []ThreadRef `json:"pull_requests,omitempty" jsonschema:"One to 100 exact pull requests; cannot be combined with authors, state, or limit"`
+	State         string      `json:"state,omitempty" jsonschema:"open, closed, or all"`
+	Limit         int         `json:"limit,omitempty" jsonschema:"Maximum pull requests from 1 to 100; defaults to 20"`
+	View          string      `json:"view,omitempty" jsonschema:"compact or full; defaults to compact"`
+	SnapshotToken string      `json:"snapshot_token,omitempty" jsonschema:"Optional immutable corpus snapshot token from a previous offline read"`
 }
 
 // PullRequestPortfolioItem contains source-backed PR facts and a deterministic
@@ -546,15 +547,16 @@ type PullRequestPortfolioItem struct {
 
 // ListPullRequestPortfolioOutput contains a deterministic portfolio projection.
 type ListPullRequestPortfolioOutput struct {
-	Status        string                     `json:"status"`
-	View          string                     `json:"view"`
-	RuleVersion   string                     `json:"rule_version"`
-	GeneratedAt   string                     `json:"generated_at"`
-	PullRequests  []PullRequestPortfolioItem `json:"pull_requests"`
-	Total         int                        `json:"total"`
-	Truncated     bool                       `json:"truncated"`
-	SnapshotToken string                     `json:"snapshot_token"`
-	Recovery      *RecoveryPlan              `json:"recovery,omitempty"`
+	Status                  string                     `json:"status"`
+	View                    string                     `json:"view"`
+	RuleVersion             string                     `json:"rule_version"`
+	GeneratedAt             string                     `json:"generated_at"`
+	PullRequests            []PullRequestPortfolioItem `json:"pull_requests"`
+	Total                   int                        `json:"total"`
+	Truncated               bool                       `json:"truncated"`
+	UnavailablePullRequests []ThreadRef                `json:"unavailable_pull_requests,omitempty"`
+	SnapshotToken           string                     `json:"snapshot_token"`
+	Recovery                *RecoveryPlan              `json:"recovery,omitempty"`
 }
 
 // PortfolioSubjectInput identifies local candidate state for offline overlap analysis.

internal/mcpserver/portfolio.go

@@ -10,10 +10,10 @@ import (
 )
 
 func (s *Server) listPullRequestPortfolio(ctx context.Context, _ *mcp.CallToolRequest, in mcpcontract.ListPullRequestPortfolioInput) (*mcp.CallToolResult, mcpcontract.ListPullRequestPortfolioOutput, error) {
-	if in.State == "" {
+	if len(in.PullRequests) == 0 && in.State == "" {
 		in.State = "open"
 	}
-	if in.Limit == 0 {
+	if len(in.PullRequests) == 0 && in.Limit == 0 {
 		in.Limit = 20
 	}
 	if in.View == "" {

internal/mcpserver/scalable.go

@@ -335,6 +335,8 @@ func (s *Server) registerScalable() {
 		setDefault(sc, "limit", 20)
 		setEnum(sc, "view", "compact", "full")
 		setDefault(sc, "view", "compact")
+		setArrayBounds(sc, "pull_requests", 1, 100)
+		constrainPullRequestRefs(sc, "pull_requests")
 	}), output: outputSchema[mcpcontract.ListPullRequestPortfolioOutput]("Offline pull-request portfolio with explainable attention states."), handler: s.listPullRequestPortfolio})
 	addCatalogTool(s, catalogTool[mcpcontract.SearchPullRequestFeedbackInput, mcpcontract.SearchPullRequestFeedbackOutput]{name: mcpcontract.ToolSearchPullRequestFeedback, title: "Search exact pull-request comments by commenter login", description: "Use this offline search after github.index_pull_request_feedback and jobs.get when you need exact feedback_author, PR state, merge state, channel, resolution, review-state, anchor, date, or body filters. It reads only the local normalized feedback projection and never contacts GitHub or writes corpus state. Matches preserve exact comment and thread identities; incomplete discovery or facets return partial/unknown coverage with a typed recovery action, not a false empty result.", annotations: readOnly, supportedBy: supports[PullRequestFeedbackSearcher], input: inputSchema[mcpcontract.SearchPullRequestFeedbackInput](func(sc *schemaBuilder) {
 		setEnum(sc, "state", "open", "closed", "all")