Design: linked PR health — wire into queue hot path vs. reconcile job (removed in 0.4.1 re-cut)

[joryirving]

Context

During the 0.4.1 re-cut audit, the linked-pr-health module (src/lib/linked-pr-health.ts, added in #273 "expose linked PR health on issue queues and board items") was found to be dead code — computeLinkedPrHealth / computeLinkedPrHealthBatch / enrichQueueItemsWithPrHealth were imported only by their own test file and wired into no real request path. The PR shipped the library but never connected it to the agent queue or board views it was named after.

To keep the re-cut clean and the release notes honest, the module and its test were removed (−629 lines). This issue tracks the deferred design decision: should linked PR health be a real feature, and if so, where should it run?

Important

This is a design decision that needs further deliberation before re-implementing. Removal was a conservative choice for the release, not a rejection of the feature.

The core trade-off: where does the enrichment run?

Computing linked PR health requires per-PR GitHub data that the cheap list endpoints don't return:

• reviewDecision (aggregate review state) — GraphQL, or derived from the per-PR reviews endpoint
• mergeStateStatus / mergeable_state — only on the single-PR GET, not the list endpoint
• check-run / status-context failures — another per-PR fetch

So enrichment costs N extra GitHub API calls per PR. Where we pay that cost is the decision:

Option A — Agent queue hot path (what #273's title implied)

Enrich queue items inline in GET /api/agents/[agentName]/queue.

• ➕ Health is live at the moment a worker picks work.
• ➖ The queue is polled frequently by every worker → multiplies API calls, risks secondary rate limits, and adds latency to a hot path. Needs caching/TTL + rate-limit strategy to be viable.

Option B — Reconcile / scheduled job (where related logic now lives)

Compute health during the periodic reconcile and persist the signal on the issue, so the queue reads it for free.

• ➕ Bounded, predictable API cost; off the hot path.
• ➖ Signal is as fresh as the reconcile cadence (minutes), not real-time. Requires a schema field to persist health/needsFollowup.

Option C — Hybrid

Persist via reconcile (B) + optional on-demand refresh for a single item when an operator/worker explicitly asks.

Related work already shipped in the 0.4.1 re-cut

The underlying review-decision/merge-state logic is not lost — equivalent enrichment now runs in the reconcile path (a scheduled job, Option B-ish), feeding checkPrHealth:

• fetchPullRequestHealthSignals(repo, prNumber) in src/lib/github.ts — per-PR mergeable_state + a review decision derived from the reviews endpoint.
• src/app/api/issues/reconcile/route.ts enriches each issue-linked open PR before checkPrHealth runs (previously it always saw null signals and reported healthy — see the companion fix).

So if we choose Option B, much of the data-fetching is already in place and linked-pr-health's normalization layer could be reintroduced on top of it rather than rebuilt from scratch.

Decisions needed

1. Is linked PR health a feature we want to expose in the UI/queue at all?
2. If yes: Option A, B, or C?
3. If it touches the queue: what caching/TTL + rate-limit budget is acceptable on that hot path?
4. If persisted: what does the schema field look like (raw signals vs. a computed needsFollowup + reasons)?

Pointers

• Removed module (recoverable from git history): src/lib/linked-pr-health.ts, src/lib/linked-pr-health.test.ts
• Original feature PR: feat(issues): expose linked PR health on issue queues and board items #273
• Existing consumers of the same signals: checkPrHealth in src/lib/issue-reconciliation.ts

---

Note: the second half of audit finding #6 was a clean fix (no deliberation needed)

BLOCKED checkpoints previously did not require blockerReason (the parser only type-checked it). That was tightened in the re-cut to reject missing/empty reasons with a 400 — documented contract now enforced. Mentioned here only so the full "#6" scope is captured; no further action required on that part.

[joryirving]

My recommendation: implement this as Option B first, with Option C as a later enhancement.

Concretely:

• Reconcile computes linked PR health on a bounded cadence.
• Persist a compact health snapshot on the Issue row.
• Queue and board endpoints read the persisted health instead of doing live GitHub calls.
• Add an explicit one-issue/on-demand refresh later if operators/workers need freshness.

I would avoid putting per-PR GitHub fetches in GET /api/agents/[agentName]/queue by default. The queue is a hot path and is polled by workers, so live enrichment there risks latency and secondary rate limits.

Before exposing this to agents, I would also tighten the health semantics:

• actionable needs_work: changes requested, merge conflict/dirty, failing required checks
• informational only: behind, blocked, unknown, pending

That keeps agents from being sent back into PRs where there may not be anything useful to do yet.

One related finding from the current reconcile code: reconcile/route.ts claims to fetch open and merged PRs, but fetchPullRequests() currently fetches only state=open, so merged-PR reconciliation may not be doing what the comment says. That should probably be tracked separately from this design issue.

[joryirving]

The "fetches all PRs (open and merged) but fetchPullRequests() is state=open only" bug noted above is fixed in #284.

Root cause confirmed: open PRs always have merged_at = null, so mergedPrsMap / mergedFixingIssues were always empty and the documented "merged PR fixes issue → close it on GitHub" path (reconcile purpose #1) never fired. #284 adds a bounded fetchClosedPullRequests() and feeds both open + closed PRs into reconcile, leaving fetchPullRequests() open-only since the sync routes depend on that for board state.

⚠️ Behavior note carried over to #284: reviving this means the first reconcile run after deploy will auto-close open issues whose merged PR branch encodes the issue number (issue-123).