@cluesmith/codev 3.1.2 → 3.1.4

package/dist/agent-farm/commands/workspace-recover.d.ts

@@ -0,0 +1,74 @@
+import type { ProjectState } from '../../commands/porch/types.js';
+import type { DbTerminalSession } from '../servers/tower-types.js';
+export interface WorkspaceRecoverOptions {
+    apply?: boolean;
+    maxAge?: number;
+    includeStale?: boolean;
+    yes?: boolean;
+}
+export type IneligibleReason = 'terminal' | 'unsupported_protocol' | 'worktree_missing' | 'shellper_alive' | 'stale';
+export type EligibilityResult = {
+    eligible: true;
+} | {
+    eligible: false;
+    reason: IneligibleReason;
+};
+export interface EligibilityInputs {
+    state: ProjectState;
+    builderInfo: BuilderInfo | null;
+    sessions: DbTerminalSession[];
+    worktreeExists: boolean;
+    ageDays: number;
+    maxAgeDays: number;
+    includeStale: boolean;
+    isProcessAlive: (pid: number) => boolean;
+    socketExists: (socket: string) => boolean;
+}
+/**
+ * Pure predicate — no I/O. All filesystem and process probes happen in the
+ * caller and are passed in via `isProcessAlive` and `socketExists`. This keeps
+ * the predicate trivially unit-testable.
+ *
+ * On terminal_sessions and the "no row" case:
+ *   Tower's reconciliation deletes terminal_sessions rows whose shellper can't
+ *   be reconnected (tower-terminals.ts:485-711). That runs on Tower startup,
+ *   which is exactly what happens between a machine reboot and the user
+ *   invoking `workspace recover`. By the time recovery runs, the rows for
+ *   dead builders have already been pruned. So "no matching session row"
+ *   is the COMMON case for any builder that needs revival — not a reason to
+ *   skip. The row is only useful here as a positive "still alive" signal.
+ *
+ * Predicate order (cheap structural checks first):
+ *   1. terminal phase
+ *   2. unsupported protocol family
+ *   3. worktree missing on disk
+ *   4. any matching session row is alive  → known still running, leave alone
+ *   5. stale (older than maxAge, unless includeStale)
+ *   6. otherwise → revive
+ */
+export declare function evaluateEligibility(inputs: EligibilityInputs): EligibilityResult;
+export interface BuilderInfo {
+    builderId: string;
+    issueArg: string;
+    cliProtocol: string;
+}
+/**
+ * Derive the inputs needed to invoke `afx spawn <issueArg> --resume --protocol <cliProtocol>`
+ * and the SQLite `role_id` to look up the builder's terminal session.
+ *
+ * Returns null for protocols that cannot be cleanly resumed via the spawn CLI
+ * (experiment/maintain/task/legacy spider/etc) — callers should skip those
+ * projects with an `unsupported_protocol` reason.
+ */
+export declare function deriveBuilderInfo(state: ProjectState): BuilderInfo | null;
+/**
+ * Resolve the builder's worktree path on disk, handling both the Spec-653
+ * ID-only layout and the legacy title-suffixed form.
+ *
+ * Returns null when the project's protocol isn't revivable (no defined worktree
+ * naming) or when no matching directory exists.
+ */
+export declare function resolveWorktreePath(buildersDir: string, state: ProjectState): string | null;
+export declare function formatRelativeAge(iso: string): string;
+export declare function workspaceRecover(options?: WorkspaceRecoverOptions): Promise<void>;
+//# sourceMappingURL=workspace-recover.d.ts.map

package/dist/agent-farm/commands/workspace-recover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-recover.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/commands/workspace-recover.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAcnE,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,sBAAsB,GACtB,kBAAkB,GAClB,gBAAgB,GAChB,OAAO,CAAC;AAEZ,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAClB;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAElD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;CAC3C;AAuBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,CAyBhF;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,GAAG,IAAI,CAiBzE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAkB3F;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAcrD;AA6DD,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,IAAI,CAAC,CAoH3F"}

package/dist/agent-farm/commands/workspace-recover.js

@@ -0,0 +1,307 @@
+// workspace recover — revive builders whose shellper died (e.g. machine reboot).
+// Issue #829. Dry-run by default; --apply actually respawns.
+import { spawn } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { getConfig } from '../utils/index.js';
+import { logger } from '../utils/logger.js';
+import { buildAgentName, stripLeadingZeros } from '../utils/agent-names.js';
+import { processExists, getTerminalSessionsForWorkspace } from '../servers/tower-terminals.js';
+import { closeGlobalDb } from '../db/index.js';
+import { listAllProjects } from '../../commands/porch/state.js';
+import { confirm } from '../../lib/cli-prompts.js';
+const TERMINAL_PHASES = new Set(['verified', 'complete']);
+const DEFAULT_MAX_AGE_DAYS = 7;
+// Protocols that `afx spawn <id> --resume --protocol <name>` can revive cleanly:
+// issue-driven families with a positional issue arg and a stable worktree layout.
+// `experiment` / `maintain` / `task` / bare protocol-mode builders can't be
+// resumed by ID through spawn.ts and are skipped with `unsupported_protocol`.
+// (Legacy `spider` is also excluded — it was retired long ago, and any stray
+// project still carrying that protocol value should be treated as unsupported.)
+const REVIVABLE_PROTOCOLS = new Set(['spir', 'aspir', 'air', 'pir', 'bugfix']);
+/**
+ * Liveness rule per row (Gemini cmap finding):
+ *   - shellper_pid known + alive → ALIVE
+ *   - shellper_pid known + dead  → DEAD (socket is ignored; the OS doesn't clean
+ *                                   ~/.codev/run/ on reboot, so a stale socket
+ *                                   would otherwise falsely mark the row alive
+ *                                   and defeat the primary recovery use case)
+ *   - shellper_pid null + socket file exists → ALIVE (legacy / pre-PID rows)
+ *   - shellper_pid null + no socket → DEAD
+ */
+function isSessionAlive(session, isProcessAlive, socketExists) {
+    if (session.shellper_pid !== null) {
+        return isProcessAlive(session.shellper_pid);
+    }
+    return session.shellper_socket !== null && socketExists(session.shellper_socket);
+}
+/**
+ * Pure predicate — no I/O. All filesystem and process probes happen in the
+ * caller and are passed in via `isProcessAlive` and `socketExists`. This keeps
+ * the predicate trivially unit-testable.
+ *
+ * On terminal_sessions and the "no row" case:
+ *   Tower's reconciliation deletes terminal_sessions rows whose shellper can't
+ *   be reconnected (tower-terminals.ts:485-711). That runs on Tower startup,
+ *   which is exactly what happens between a machine reboot and the user
+ *   invoking `workspace recover`. By the time recovery runs, the rows for
+ *   dead builders have already been pruned. So "no matching session row"
+ *   is the COMMON case for any builder that needs revival — not a reason to
+ *   skip. The row is only useful here as a positive "still alive" signal.
+ *
+ * Predicate order (cheap structural checks first):
+ *   1. terminal phase
+ *   2. unsupported protocol family
+ *   3. worktree missing on disk
+ *   4. any matching session row is alive  → known still running, leave alone
+ *   5. stale (older than maxAge, unless includeStale)
+ *   6. otherwise → revive
+ */
+export function evaluateEligibility(inputs) {
+    const { state, builderInfo, sessions, worktreeExists, ageDays, maxAgeDays, includeStale, isProcessAlive, socketExists, } = inputs;
+    if (TERMINAL_PHASES.has(state.phase)) {
+        return { eligible: false, reason: 'terminal' };
+    }
+    if (builderInfo === null) {
+        return { eligible: false, reason: 'unsupported_protocol' };
+    }
+    if (!worktreeExists) {
+        return { eligible: false, reason: 'worktree_missing' };
+    }
+    // If ANY matching session looks alive, treat the builder as alive. Duplicates
+    // can occur when a prior recovery left a dead row behind (terminal_sessions
+    // has no UNIQUE constraint on role_id) — the cautious read is "alive."
+    if (sessions.some(s => isSessionAlive(s, isProcessAlive, socketExists))) {
+        return { eligible: false, reason: 'shellper_alive' };
+    }
+    if (!includeStale && ageDays > maxAgeDays) {
+        return { eligible: false, reason: 'stale' };
+    }
+    return { eligible: true };
+}
+/**
+ * Derive the inputs needed to invoke `afx spawn <issueArg> --resume --protocol <cliProtocol>`
+ * and the SQLite `role_id` to look up the builder's terminal session.
+ *
+ * Returns null for protocols that cannot be cleanly resumed via the spawn CLI
+ * (experiment/maintain/task/legacy spider/etc) — callers should skip those
+ * projects with an `unsupported_protocol` reason.
+ */
+export function deriveBuilderInfo(state) {
+    if (!REVIVABLE_PROTOCOLS.has(state.protocol)) {
+        return null;
+    }
+    if (state.protocol === 'bugfix') {
+        const numericId = state.id.replace(/^bugfix-/, '');
+        return {
+            builderId: buildAgentName('bugfix', numericId),
+            issueArg: numericId,
+            cliProtocol: 'bugfix',
+        };
+    }
+    return {
+        builderId: buildAgentName('spec', state.id, state.protocol),
+        issueArg: stripLeadingZeros(state.id),
+        cliProtocol: state.protocol,
+    };
+}
+/**
+ * Resolve the builder's worktree path on disk, handling both the Spec-653
+ * ID-only layout and the legacy title-suffixed form.
+ *
+ * Returns null when the project's protocol isn't revivable (no defined worktree
+ * naming) or when no matching directory exists.
+ */
+export function resolveWorktreePath(buildersDir, state) {
+    const info = deriveBuilderInfo(state);
+    if (info === null)
+        return null;
+    const idOnlyName = `${info.cliProtocol}-${info.issueArg}`;
+    const idOnlyPath = join(buildersDir, idOnlyName);
+    if (existsSync(idOnlyPath) && existsSync(join(idOnlyPath, '.git'))) {
+        return idOnlyPath;
+    }
+    if (!existsSync(buildersDir))
+        return null;
+    const prefix = `${info.cliProtocol}-${info.issueArg}-`;
+    for (const entry of readdirSync(buildersDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !entry.name.startsWith(prefix))
+            continue;
+        const candidate = join(buildersDir, entry.name);
+        if (existsSync(join(candidate, '.git')))
+            return candidate;
+    }
+    return null;
+}
+export function formatRelativeAge(iso) {
+    const ms = Date.now() - Date.parse(iso);
+    if (Number.isNaN(ms) || ms < 0)
+        return '—';
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    // Round UP rather than down so the label aligns with --max-age semantics:
+    // anything strictly older than 24h prints as "2d ago" (not "1d ago"), so
+    // a row labelled "1d ago" is actually within --max-age 1 (≤ 24h exact).
+    // Use ms rather than the floored `hours` to preserve sub-hour precision —
+    // 24h + 1s must ceil to 2 days, not 1.
+    const days = Math.ceil(ms / 86_400_000);
+    return `${days}d ago`;
+}
+function reasonLabel(reason) {
+    switch (reason) {
+        case 'terminal': return 'terminal';
+        case 'unsupported_protocol': return 'unsupported protocol';
+        case 'worktree_missing': return 'worktree missing';
+        case 'shellper_alive': return 'shellper alive';
+        case 'stale': return 'stale';
+    }
+}
+function printPreview(rows) {
+    const widths = [6, 9, 12, 14, 10, 20];
+    logger.row(['ID', 'PROTOCOL', 'PHASE', 'UPDATED', 'STATUS', 'REASON'], widths);
+    logger.row(['─'.repeat(6), '─'.repeat(9), '─'.repeat(12), '─'.repeat(14), '─'.repeat(10), '─'.repeat(20)], widths);
+    for (const row of rows) {
+        const status = row.eligibility.eligible
+            ? chalk.green('revive')
+            : chalk.gray('skip');
+        const reason = row.eligibility.eligible ? '—' : reasonLabel(row.eligibility.reason);
+        logger.row([
+            row.state.id,
+            row.state.protocol,
+            row.state.phase,
+            formatRelativeAge(row.state.updated_at),
+            status,
+            reason,
+        ], widths);
+    }
+}
+async function respawnBuilder(info) {
+    // Use the current node binary and CLI entry point so the respawn invocation
+    // matches the install method this command was started under (npm global,
+    // npx, dev script, etc.) instead of relying on PATH lookup of 'afx'.
+    await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(process.execPath, [process.argv[1], 'spawn', info.issueArg, '--resume', '--protocol', info.cliProtocol], { stdio: 'inherit' });
+        child.on('error', rejectPromise);
+        child.on('exit', (code) => {
+            if (code === 0)
+                resolvePromise();
+            else
+                rejectPromise(new Error(`afx spawn exited with code ${code}`));
+        });
+    });
+}
+export async function workspaceRecover(options = {}) {
+    const config = getConfig();
+    const maxAgeDays = options.maxAge ?? DEFAULT_MAX_AGE_DAYS;
+    const includeStale = options.includeStale ?? false;
+    const apply = options.apply ?? false;
+    logger.header(`Workspace Recover${apply ? '' : ' (dry-run)'}`);
+    logger.kv('Workspace', config.workspaceRoot);
+    if (!includeStale)
+        logger.kv('Max age', `${maxAgeDays} day(s)`);
+    logger.blank();
+    const projects = listAllProjects(config.workspaceRoot, {
+        onParseError: (statusPath, err) => {
+            logger.debug(`Skipped unparseable ${statusPath}: ${err instanceof Error ? err.message : String(err)}`);
+        },
+    });
+    if (projects.length === 0) {
+        logger.info('No porch projects found.');
+        return;
+    }
+    let sessions;
+    try {
+        sessions = getTerminalSessionsForWorkspace(config.workspaceRoot);
+    }
+    finally {
+        closeGlobalDb();
+    }
+    // role_id has no UNIQUE constraint in the schema, so collect every matching
+    // row per builder id rather than collapsing to last-write-wins.
+    const sessionsByRoleId = new Map();
+    for (const s of sessions) {
+        if (s.type !== 'builder' || !s.role_id)
+            continue;
+        const bucket = sessionsByRoleId.get(s.role_id);
+        if (bucket)
+            bucket.push(s);
+        else
+            sessionsByRoleId.set(s.role_id, [s]);
+    }
+    const allRows = projects.map(({ state }) => {
+        const builderInfo = deriveBuilderInfo(state);
+        const matchingSessions = builderInfo ? sessionsByRoleId.get(builderInfo.builderId) ?? [] : [];
+        const worktreePath = resolveWorktreePath(config.buildersDir, state);
+        const ageDays = (Date.now() - Date.parse(state.updated_at)) / 86_400_000;
+        const eligibility = evaluateEligibility({
+            state, builderInfo,
+            sessions: matchingSessions,
+            worktreeExists: worktreePath !== null,
+            ageDays, maxAgeDays, includeStale,
+            isProcessAlive: processExists,
+            socketExists: existsSync,
+        });
+        return { state, builderInfo, worktreePath, eligibility, ageDays };
+    });
+    // By default the preview hides projects beyond the recency window — for a
+    // large workspace the stale tail dominates the table and obscures the few
+    // rows the operator actually cares about. --include-stale shows everything.
+    const visibleRows = includeStale
+        ? allRows
+        : allRows.filter(r => r.ageDays <= maxAgeDays);
+    const hiddenStaleCount = allRows.length - visibleRows.length;
+    printPreview(visibleRows);
+    if (hiddenStaleCount > 0) {
+        logger.blank();
+        logger.info(`${hiddenStaleCount} project(s) older than ${maxAgeDays} day(s) hidden. Pass --include-stale to show them.`);
+    }
+    const eligible = allRows.filter((r) => r.eligibility.eligible && r.builderInfo !== null);
+    logger.blank();
+    if (hiddenStaleCount > 0) {
+        logger.kv('Eligible', `${eligible.length} / ${visibleRows.length} visible (${allRows.length} scanned)`);
+    }
+    else {
+        logger.kv('Eligible', `${eligible.length} / ${allRows.length}`);
+    }
+    if (eligible.length === 0) {
+        logger.info(apply ? 'Nothing to revive.' : 'Nothing would be revived.');
+        return;
+    }
+    if (!apply) {
+        logger.info(`Run with --apply to respawn ${eligible.length} builder(s).`);
+        return;
+    }
+    if (!options.yes) {
+        const proceed = await confirm(`Proceed to respawn ${eligible.length} builder(s)?`, false);
+        if (!proceed) {
+            logger.info('Aborted.');
+            return;
+        }
+    }
+    let succeeded = 0;
+    let failed = 0;
+    for (const row of eligible) {
+        logger.blank();
+        logger.info(`Respawning ${row.builderInfo.builderId} (issue ${row.builderInfo.issueArg}, ${row.builderInfo.cliProtocol})...`);
+        try {
+            await respawnBuilder(row.builderInfo);
+            succeeded++;
+        }
+        catch (err) {
+            failed++;
+            logger.error(`Failed to respawn ${row.builderInfo.builderId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    logger.blank();
+    logger.kv('Respawned', String(succeeded));
+    if (failed > 0) {
+        logger.kv('Failed', String(failed));
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=workspace-recover.js.map

package/dist/agent-farm/commands/workspace-recover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-recover.js","sourceRoot":"","sources":["../../../src/agent-farm/commands/workspace-recover.ts"],"names":[],"mappings":"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"}

package/dist/agent-farm/servers/overview.d.ts

@@ -60,6 +60,18 @@ export interface BuilderOverview {
      * an inline attribution tag when the workspace hosts more than one architect.
      */
     spawnedByArchitect: string | null;
+    /**
+     * Canonical "PR is waiting on a human reviewer" signal (Issue #872). True the
+     * moment porch transitions out of the CMAP-emitting state for the PR-creating
+     * phase, for ALL bundled protocols. Computed from `pr_ready_for_human` in
+     * status.yaml when present; otherwise falls back to the v3.1.3 derived logic
+     * (`blocked === 'PR review'` || BUGFIX `phase === 'verified'`) so in-flight
+     * projects from before this field shipped continue to surface correctly.
+     *
+     * Consumers (dashboard NeedsAttentionList, VSCode tree) gate on this flag
+     * instead of deriving from the protocol-specific gate shape themselves.
+     */
+    prReady: boolean;
 }
 export interface PROverview {
     id: string;
@@ -121,6 +133,13 @@ interface ParsedStatus {
     gateApprovedAt: Record<string, string>;
     planPhases: PlanPhase[];
     startedAt: string;
+    /**
+     * Mirror of porch's `pr_ready_for_human` status.yaml field (Issue #872).
+     * `null` when the field is absent in the yaml (legacy state from before
+     * the field shipped) so `derivePrReady` can choose between the explicit
+     * value and the v3.1.3 fallback derivation.
+     */
+    prReadyForHuman: boolean | null;
 }
 /**
  * Parse a porch status.yaml file into structured data.
@@ -153,6 +172,24 @@ export declare function detectBlockedGate(parsed: ParsedStatus): string | null;
  * Keep this list in sync with `detectBlocked`'s `gateLabels` keys.
  */
 export declare function detectBlockedSince(parsed: ParsedStatus): string | null;
+/**
+ * Compute the canonical "PR ready for human review" signal for a builder
+ * (Issue #872). Prefers porch's explicit `pr_ready_for_human` field in
+ * status.yaml when present; otherwise falls back to the v3.1.3 derivation so
+ * builders whose state.yaml pre-dates the field continue to surface.
+ *
+ * Fallback derivation:
+ *   - `blocked === 'PR review'` — protocols with a `pr` gate (AIR/SPIR/ASPIR/PIR)
+ *     that reached the human-bottleneck state under v3.1.3 logic.
+ *   - BUGFIX `phase === 'verified'` — the v3.1.3 gap this canonical signal
+ *     closes. BUGFIX has no `pr` gate, so its post-CMAP state is `verified`
+ *     with no gate-pending signal; the fallback adds this case so in-flight
+ *     BUGFIX builders aren't dropped from Needs Attention.
+ *
+ * Once porch has written `pr_ready_for_human` to status.yaml the fallback no
+ * longer fires for that project — the explicit field is authoritative.
+ */
+export declare function derivePrReady(parsed: ParsedStatus): boolean;
 /**
  * Compute total idle time (ms) from gate wait periods.
  * Includes completed gate waits (requested_at → approved_at) and

package/dist/agent-farm/servers/overview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overview.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/servers/overview.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"overview.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/servers/overview.ts"],"names":[],"mappings":"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"}

package/dist/agent-farm/servers/overview.js

@@ -27,6 +27,7 @@ export function parseStatusYaml(content) {
         gateApprovedAt: {},
         planPhases: [],
         startedAt: '',
+        prReadyForHuman: null,
     };
     const lines = content.split('\n');
     let section = 'none';
@@ -70,6 +71,12 @@ export function parseStatusYaml(content) {
             section = 'none';
             continue;
         }
+        const prReadyMatch = line.match(/^pr_ready_for_human:\s*(true|false)\s*$/);
+        if (prReadyMatch) {
+            result.prReadyForHuman = prReadyMatch[1] === 'true';
+            section = 'none';
+            continue;
+        }
         // Section headers
         if (/^gates:\s*$/.test(line)) {
             if (currentPlanPhase) {
@@ -285,6 +292,34 @@ export function detectBlockedSince(parsed) {
     }
     return null;
 }
+/**
+ * Compute the canonical "PR ready for human review" signal for a builder
+ * (Issue #872). Prefers porch's explicit `pr_ready_for_human` field in
+ * status.yaml when present; otherwise falls back to the v3.1.3 derivation so
+ * builders whose state.yaml pre-dates the field continue to surface.
+ *
+ * Fallback derivation:
+ *   - `blocked === 'PR review'` — protocols with a `pr` gate (AIR/SPIR/ASPIR/PIR)
+ *     that reached the human-bottleneck state under v3.1.3 logic.
+ *   - BUGFIX `phase === 'verified'` — the v3.1.3 gap this canonical signal
+ *     closes. BUGFIX has no `pr` gate, so its post-CMAP state is `verified`
+ *     with no gate-pending signal; the fallback adds this case so in-flight
+ *     BUGFIX builders aren't dropped from Needs Attention.
+ *
+ * Once porch has written `pr_ready_for_human` to status.yaml the fallback no
+ * longer fires for that project — the explicit field is authoritative.
+ */
+export function derivePrReady(parsed) {
+    if (parsed.prReadyForHuman !== null)
+        return parsed.prReadyForHuman;
+    // Fallback: v3.1.3 logic + BUGFIX case.
+    const prGatePending = parsed.gates['pr'] === 'pending' && !!parsed.gateRequestedAt['pr'];
+    if (prGatePending)
+        return true;
+    if (parsed.protocol === 'bugfix' && parsed.phase === 'verified')
+        return true;
+    return false;
+}
 /**
  * Compute total idle time (ms) from gate wait periods.
  * Includes completed gate waits (requested_at → approved_at) and
@@ -450,6 +485,7 @@ export function discoverBuilders(workspaceRoot) {
                 idleMs: 0,
                 lastDataAt: null,
                 spawnedByArchitect: null,
+                prReady: false,
             });
             continue;
         }
@@ -503,6 +539,7 @@ export function discoverBuilders(workspaceRoot) {
                         idleMs: computeIdleMs(parsed),
                         lastDataAt: null,
                         spawnedByArchitect: null,
+                        prReady: derivePrReady(parsed),
                     });
                     found = true;
                     break;
@@ -535,6 +572,7 @@ export function discoverBuilders(workspaceRoot) {
                 idleMs: 0,
                 lastDataAt: null,
                 spawnedByArchitect: null,
+                prReady: false,
             });
         }
     }