[Bugfix #901] Skip stale post-merge prReady rows in NeedsAttentionList

codev/projects/bugfix-901-needs-attention-surfaces-build/status.yaml

@@ -0,0 +1,17 @@
+id: bugfix-901
+title: needs-attention-surfaces-build
+protocol: bugfix
+phase: pr
+plan_phases: []
+current_plan_phase: null
+gates:
+ pr:
+ status: approved
+ requested_at: '2026-05-28T02:13:21.360Z'
+ approved_at: '2026-05-28T18:59:18.179Z'
+iteration: 1
+build_complete: false
+history: []
+started_at: '2026-05-28T01:48:37.300Z'
+updated_at: '2026-05-28T18:59:18.179Z'
+pr_ready_for_human: false

codev/state/bugfix-901_thread.md

@@ -0,0 +1,41 @@
+# bugfix-901 — Needs Attention surfaces post-merge builders
+
+## Investigation
+
+Issue #901: After PR merge, builder still surfaces under Needs Attention with stale `prReady: true`. Two interacting problems documented in the issue:
+
+1. **Data hazard** (already fixed by #888): v3.1.4 re-set `pr_ready_for_human=true` on terminal `pr→verified` advance. In-flight builders that crossed that boundary still carry the stale `true` in status.yaml. Self-corrects for new builders.
+2. **Consumer-side gap** (this fix): `NeedsAttentionList.buildItems` (packages/dashboard/src/components/NeedsAttentionList.tsx:108) defensive fallback emits a row for any `b.prReady === true` builder whose PR isn't in `prs[]`. The intent was cache-miss defense (PR #874 iter-2). But merged PRs are also absent from `prs[]` (which lists open PRs only) — the same code path fires wrongly.
+
+The data we need is already fetched: `overview.ts:911` calls `fetchMergedPRsCached(workspaceRoot)` and uses the result internally to enrich `recentlyClosed[]` with `prUrl`. It just isn't exposed on `OverviewData` for `NeedsAttentionList` to cross-reference.
+
+## Approach
+
+Minimal fix:
+
+1. Add `recentlyMergedIssueIds: string[]` to `OverviewData` (`packages/types/src/api.ts`). Just the issue-ID set — that's all the consumer needs.
+2. Populate it in `overview.ts` from the already-fetched `mergedPRs` via `parseLinkedIssue`.
+3. Plumb through `NeedsAttentionList`'s `buildItems` signature and use it to gate the defensive fallback emit.
+4. Update tests: regression test + clarify the defensive test's setup.
+
+PR-loop is untouched — it iterates open PRs only, so already correct.
+
+## Implementation notes
+
+- The codev package defines its OWN `OverviewData` interface (`packages/codev/src/agent-farm/servers/overview.ts:156`) in addition to the shared one in `packages/types/src/api.ts`. Both needed updating — otherwise the local tsc check fails with `Object literal may only specify known properties` even though the wire type is correct. Worth noting if anyone wonders why the change touches two type declarations.
+- The merged-PR projection runs unconditionally even when `closed === null` (the existing recentlyClosed block early-outs). This is intentional — the consumer needs the merged-issue set independent of whether the closed-issue enrichment succeeded.
+- `recentlyMergedIssueIds: readonly string[]` in the React prop with a default of `[]` so the change is backwards-compatible for any tests/callers that don't (yet) pass it.
+
+## PR
+
+PR #902 opened. CMAP-3 (gemini/codex/claude) ran in parallel via consult.
+
+## CMAP-3 result
+
+All three: **APPROVE / HIGH / no key issues**. Iter-1 outputs persisted at
+`codev/projects/bugfix-901-needs-attention-surfaces-build/bugfix-901-pr-iter1-{gemini,codex,claude}.txt`.
+Claude flagged a non-blocking style nit (two existing `buildItems(prs, builders)`
+test calls rely on the new default param instead of passing `[]` explicitly) —
+left as-is. PR body updated with the verdict table.
+
+Notifying architect + running `porch done bugfix-901` to request the pr gate.

packages/codev/src/agent-farm/__tests__/overview.test.ts

@@ -1878,6 +1878,38 @@ describe('overview', () => {
 
  expect(data.recentlyClosed).toHaveLength(1);
  expect(data.recentlyClosed[0].prUrl).toBeUndefined();
+ // Issue #901: null merged-PR fetch should still yield an empty array,
+ // not undefined, so NeedsAttentionList's `?? []` doesn't have to absorb
+ // an inconsistent shape.
+ expect(data.recentlyMergedIssueIds).toEqual([]);
+ });
+
+ it('exposes recentlyMergedIssueIds for merged-PR consumers (Issue #901)', async () => {
+ mockFetchMergedPRs.mockResolvedValue([
+ { number: 150, title: '[Bugfix #100] Fix the bug', url: 'https://github.com/org/repo/pull/150', body: 'Fixes #100', createdAt: '2026-01-02T00:00:00Z', mergedAt: new Date().toISOString() },
+ { number: 151, title: '[Spec 200] Add feature', url: 'https://github.com/org/repo/pull/151', body: 'Closes #200', createdAt: '2026-01-02T00:00:00Z', mergedAt: new Date().toISOString() },
+ { number: 152, title: 'No linked issue', url: 'https://github.com/org/repo/pull/152', body: 'Cleanup', createdAt: '2026-01-02T00:00:00Z', mergedAt: new Date().toISOString() },
+ ]);
+
+ const cache = new OverviewCache();
+ const data = await cache.getOverview(tmpDir);
+
+ expect(new Set(data.recentlyMergedIssueIds)).toEqual(new Set(['100', '200']));
+ });
+
+ it('deduplicates recentlyMergedIssueIds when the same issue has multiple merged PRs', async () => {
+ // A follow-up PR can land while the original sits in the 24h merged
+ // window — both PRs reference the same `Fixes #N`. The consumer wants
+ // a SET of issue IDs, not a multi-bag, so the dedup is load-bearing.
+ mockFetchMergedPRs.mockResolvedValue([
+ { number: 150, title: '[Bugfix #100] First attempt', url: 'https://github.com/org/repo/pull/150', body: 'Fixes #100', createdAt: '2026-01-02T00:00:00Z', mergedAt: new Date().toISOString() },
+ { number: 151, title: '[Bugfix #100] Follow-up', url: 'https://github.com/org/repo/pull/151', body: 'Fixes #100', createdAt: '2026-01-02T01:00:00Z', mergedAt: new Date().toISOString() },
+ ]);
+
+ const cache = new OverviewCache();
+ const data = await cache.getOverview(tmpDir);
+
+ expect(data.recentlyMergedIssueIds).toEqual(['100']);
  });
 
  it('enriches issueId from DB issue_number for unknown protocols (#664)', async () => {

packages/codev/src/agent-farm/servers/overview.ts

@@ -158,6 +158,13 @@ export interface OverviewData {
  pendingPRs: PROverview[];
  backlog: BacklogItem[];
  recentlyClosed: RecentlyClosedItem[];
+ /**
+ * Issue IDs of PRs merged in the recent window (24h, matching
+ * `fetchRecentMergedPRs`). Consumers cross-reference this against a
+ * builder's `issueId` to skip stale post-merge `prReady` rows (Issue #901).
+ * Empty array when the forge call fails or yields no merge-linked rows.
+ */
+ recentlyMergedIssueIds: string[];
  /** Auto-detected forge login of the current user (via the user-identity concept). */
  currentUser?: string;
  errors?: { prs?: string; issues?: string };
@@ -996,7 +1003,24 @@ export class OverviewCache {
  });
  }
 
- const result: OverviewData = { builders, pendingPRs, backlog, recentlyClosed };
+ // 6. Project merged-PR linked-issue IDs for consumers (Issue #901).
+ // NeedsAttentionList uses this set to skip the cache-miss defensive
+ // emit for prReady builders whose PR is correctly absent from
+ // pendingPRs because the PR has been merged. Empty when the forge
+ // call fails (mergedPRs === null) or returned no merge-linked rows.
+ const recentlyMergedIssueIds: string[] = [];
+ if (mergedPRs) {
+ const seen = new Set<string>();
+ for (const pr of mergedPRs) {
+ const linkedIssue = parseLinkedIssue(pr.body || '', pr.title);
+ if (linkedIssue !== null && !seen.has(linkedIssue)) {
+ seen.add(linkedIssue);
+ recentlyMergedIssueIds.push(linkedIssue);
+ }
+ }
+ }
+
+ const result: OverviewData = { builders, pendingPRs, backlog, recentlyClosed, recentlyMergedIssueIds };
  if (currentUser) {
  result.currentUser = currentUser;
  }

packages/dashboard/__tests__/NeedsAttentionList.test.tsx

@@ -189,6 +189,11 @@ describe('NeedsAttentionList buildItems — PR gating (issue #844)', () => {
  // the realistic shape, the original gate-loop early-out filtered the
  // builder before the prReady check could fire. Architect-side CMAP
  // caught this; the loop now checks prReady BEFORE the !b.blocked skip.
+ //
+ // Issue #901: the defensive emit is only correct when the PR is missing
+ // for a "still open" reason (cache / pagination / transient failure).
+ // recentlyMergedIssueIds is the merged-PR-issue set; this test must NOT
+ // include the builder's issueId there, or the row is correctly skipped.
  const prs: OverviewPR[] = [];
  const startedAt = new Date('2026-01-05T12:00:00Z').toISOString();
  const builders = [
@@ -205,7 +210,7 @@ describe('NeedsAttentionList buildItems — PR gating (issue #844)', () => {
  }),
  ];
 
- const items = buildItems(prs, builders);
+ const items = buildItems(prs, builders, []);
  const row = items.find(i => i.key === 'gate-bugfix-42');
 
  expect(row).toBeDefined();
@@ -214,6 +219,37 @@ describe('NeedsAttentionList buildItems — PR gating (issue #844)', () => {
  expect(row!.waitingSince).toBe(startedAt);
  });
 
+ it('does NOT surface a prReady builder whose PR has been merged (Issue #901)', () => {
+ // After PR merge, the PR is correctly absent from `prs` (open-only) and
+ // the builder may still carry stale `prReady: true` in status.yaml — the
+ // v3.1.4 line-453 setter wrote it on terminal `pr → verified` advance;
+ // PR #888 fixed that but in-flight builders that crossed the v3.1.4 →
+ // v3.1.5 boundary keep the stale value. Cross-referencing the builder's
+ // issueId against recentlyMergedIssueIds suppresses the stale row
+ // without a one-shot migration.
+ const prs: OverviewPR[] = [];
+ const builders = [
+ makeBuilder({
+ id: 'spir-1842',
+ issueId: '1842',
+ protocol: 'spir',
+ phase: 'verified',
+ blocked: null,
+ blockedGate: null,
+ blockedSince: null,
+ startedAt: new Date('2026-01-05T12:00:00Z').toISOString(),
+ prReady: true,
+ }),
+ ];
+
+ // Merged-PR set includes 1842 — its PR is gone for a reason (merged),
+ // not for a transient failure.
+ const items = buildItems(prs, builders, ['1842']);
+
+ expect(items.find(i => i.key === 'gate-spir-1842')).toBeUndefined();
+ expect(items).toHaveLength(0);
+ });
+
  it('still surfaces a prReady gated builder (AIR/SPIR shape) when its PR is missing from prs', () => {
  // Gate-bearing variant — preserves the iter-1 coverage but with the
  // expectation explicitly tied to the gate-blocked shape.

packages/dashboard/src/components/NeedsAttentionList.tsx

@@ -3,6 +3,14 @@ import type { OverviewPR, OverviewBuilder } from '../lib/api.js';
 interface NeedsAttentionListProps {
  prs: OverviewPR[];
  builders: OverviewBuilder[];
+ /**
+ * Issue IDs of recently-merged PRs (Issue #901). Used to distinguish
+ * "PR missing from `prs` because of cache miss / pagination" (surface
+ * the defensive row) from "PR missing because it has been merged"
+ * (skip — there is nothing left for the human to do). Defaults to an
+ * empty array for callers that haven't been wired up yet.
+ */
+ recentlyMergedIssueIds?: readonly string[];
 }
 
 interface AttentionItem {
@@ -40,8 +48,13 @@ function timeAgo(dateStr: string): string {
  return `${days}d`;
 }
 
-export function buildItems(prs: OverviewPR[], builders: OverviewBuilder[]): AttentionItem[] {
+export function buildItems(
+ prs: OverviewPR[],
+ builders: OverviewBuilder[],
+ recentlyMergedIssueIds: readonly string[] = [],
+): AttentionItem[] {
  const items: AttentionItem[] = [];
+ const mergedIssueIdSet = new Set(recentlyMergedIssueIds);
 
  // A PR is genuinely waiting on a human only after the builder finishes CMAP
  // for the PR-creating phase. Issue #872 made this a canonical `prReady`
@@ -105,7 +118,15 @@ export function buildItems(prs: OverviewPR[], builders: OverviewBuilder[]): Atte
  // transient API failure). Surface anyway so we don't silently drop a real
  // human-action signal. blockedSince may be absent for gateless protocols
  // (BUGFIX) — fall back to startedAt so the waiting chip still renders.
+ //
+ // Skip when the builder's PR has been MERGED (Issue #901): pendingPRs
+ // lists open PRs only, so a merged PR is correctly absent — emitting the
+ // defensive row would surface a stale "PR review" item for work that's
+ // already shipped. The data hazard from v3.1.4 → v3.1.5 left some
+ // in-flight builders with stale `pr_ready_for_human: true` in
+ // status.yaml; this filter masks them without a one-shot migration.
  if (b.prReady) {
+ if (b.issueId && mergedIssueIdSet.has(b.issueId)) continue;
  const label = b.issueId ? `#${b.issueId}` : b.id;
  items.push({
  key: `gate-${b.id}`,
@@ -139,8 +160,8 @@ export function buildItems(prs: OverviewPR[], builders: OverviewBuilder[]): Atte
  return items;
 }
 
-export function NeedsAttentionList({ prs, builders }: NeedsAttentionListProps) {
- const items = buildItems(prs, builders);
+export function NeedsAttentionList({ prs, builders, recentlyMergedIssueIds }: NeedsAttentionListProps) {
+ const items = buildItems(prs, builders, recentlyMergedIssueIds);
 
  if (items.length === 0) {
  return <p className="work-empty">Nothing needs attention</p>;

packages/dashboard/src/components/WorkView.tsx

@@ -121,6 +121,7 @@ export function WorkView({ state, onRefresh, onSelectTab }: WorkViewProps) {
  <NeedsAttentionList
  prs={overview?.pendingPRs ?? []}
  builders={overview?.builders ?? []}
+ recentlyMergedIssueIds={overview?.recentlyMergedIssueIds ?? []}
  />
  )}
  </section>

packages/types/src/api.ts

@@ -247,6 +247,16 @@ export interface OverviewData {
  pendingPRs: OverviewPR[];
  backlog: OverviewBacklogItem[];
  recentlyClosed: OverviewRecentlyClosed[];
+ /**
+ * Issue IDs of PRs merged in the recent window (matches the
+ * `fetchRecentMergedPRs` 24h window in the overview server). Consumers
+ * cross-reference this against a builder's `issueId` to detect post-merge
+ * builders whose status.yaml may still carry stale `prReady: true` — used
+ * by `NeedsAttentionList` to skip the cache-miss defensive emit when the
+ * PR is correctly absent from `pendingPRs` because it has been merged
+ * (Issue #901). Empty array when the forge call fails or returns no rows.
+ */
+ recentlyMergedIssueIds: string[];
  /** Auto-detected GitHub login of the current user (via the user-identity forge concept). */
  currentUser?: string;
  errors?: { prs?: string; issues?: string };