@wildorder/nightshift 0.7.2 → 0.9.0

package/dist/run-program.js

@@ -17,6 +17,7 @@ import { detectDefaultBranch, programBranchName } from "./program-branch.js";
 import { restoreProgramsDir, snapshotProgramsDir } from "./programs-dir.js";
 import { CouldNotStartError } from "./exit-codes.js";
 import { runReportPath } from "./report-path.js";
+import { AS_BUILT_PATH, runWholeProgramReview, renderWholeProgramReview, } from "./whole-program-review.js";
 const execFileAsync = promisify(execFile);
 /** Matches every wording git uses to report an empty commit attempt. */
 const NOTHING_TO_COMMIT = /nothing to commit|nothing added to commit|no changes added to commit/u;
@@ -111,6 +112,15 @@ export const defaultGitOps = {
             return false;
         }
     },
+    async mergeBase(cwd, a, b) {
+        try {
+            const { stdout } = await execFileAsync("git", ["merge-base", a, b], { cwd });
+            return stdout.trim();
+        }
+        catch {
+            return undefined;
+        }
+    },
     async resetHard(cwd, commit) {
         await execFileAsync("git", ["reset", "--hard", commit], { cwd });
     },
@@ -174,7 +184,7 @@ function findingsRuledOnSection(records) {
         return [];
     return ["## Findings ruled on", "", ...lines, ""];
 }
-function implementerBrief(manifest, workstream, spec, ledger, priorFailure) {
+function implementerBrief(manifest, workstream, spec, ledger, priorFailure, priorDiagnosis) {
     const roster = manifest.workstreams
         .map((entry) => {
         const scope = entry.scope?.summary ?? entry.name;
@@ -201,10 +211,25 @@ function implementerBrief(manifest, workstream, spec, ledger, priorFailure) {
             ? [
                 "## Previous attempt failed",
                 "",
-                "A previous attempt at this workstream failed. Its diagnosis:",
+                "A previous attempt at this workstream failed. The verify output:",
                 "",
                 priorFailure,
                 "",
+                ...(priorDiagnosis
+                    ? [
+                        "An independent reviewer read the failing tree before you were",
+                        "spawned. Its diagnosis:",
+                        "",
+                        priorDiagnosis,
+                        "",
+                        "The tests in the tree were written by the failed attempt, not",
+                        "by a human. When the diagnosis says an assertion is wrong,",
+                        "rewrite or delete that assertion rather than bending the",
+                        "implementation to satisfy it — the spec, not the failing",
+                        "test, is the contract.",
+                        "",
+                    ]
+                    : []),
                 "Start from the diagnosis; the working tree may already contain",
                 "partial work from that attempt.",
                 "",
@@ -284,8 +309,8 @@ export async function runProgram(options) {
         ? `decider: ${describeAgent(decider)}`
         : "decider: none configured — implementer defaults will stand unratified");
     log(reviewer
-        ? `test critique reviewer: ${describeAgent(reviewer)}`
-        : "test critique reviewer: none configured — test critique disabled");
+        ? `reviewer (test critique, whole-program review): ${describeAgent(reviewer)}`
+        : "reviewer: none configured — test critique and the whole-program review are disabled");
     const cycles = findCycles(manifest.workstreams);
     if (cycles.length > 0) {
         // A cyclic graph cannot be ordered; this is a planning defect, not a
@@ -341,6 +366,11 @@ export async function runProgram(options) {
             }
         }
     }
+    // HEAD as it stood before the run's first agent ran — the whole-program
+    // review stage's fallback diff base (see resolveProgramDiffBase) when a
+    // resumed run's merge-base with the default branch is unavailable or
+    // equal to HEAD.
+    const runStartCommit = isRepository ? await git.currentCommit(root) : undefined;
     // Subject ids already sent to the decider this run — shared across the
     // authoring and build stages (a run is one process) and across the
     // decision and finding paths, so "once per subject per run" (SC-10) is
@@ -415,23 +445,51 @@ export async function runProgram(options) {
             }
         }
     }
-    const ledger = await readDecisionLedger(root, options.programId);
-    const escalations = escalatedRecords(ledger);
     const complete = results.every((result) => result.outcome.status === "complete" ||
         result.outcome.status === "skipped");
     manifest.program.status = complete ? "complete" : "partial";
     await saveManifest(root, options.programId, manifest);
+    const wholeProgram = await runWholeProgramStage({
+        root,
+        programId: options.programId,
+        manifest,
+        config,
+        agentRunner,
+        git,
+        isRepository,
+        results,
+        authorResult,
+        runStartCommit,
+        decider,
+        reviewed,
+        triaged,
+        now,
+        log,
+    });
+    const ledger = await readDecisionLedger(root, options.programId);
+    const escalations = escalatedRecords(ledger);
     const reportPath = runReportPath(root, options.programId);
-    await writeFile(reportPath, 
-    // `triaged` is the run-local set of subject ids the decider actually
-    // ruled on this run (built up across the authoring and build stages,
-    // see its declaration above) — exactly the `triagedThisRun` basis the
-    // "this run" triage ratio needs, since the projected ledger carries no
-    // run identifier of its own. It excludes ids that were merely sent but
-    // whose invocation failed or returned no valid verdict.
-    renderRunReport(manifest, results, ledger, triaged, authorResult, now()), "utf8");
-    if (isRepository) {
-        await git.commitPaths(root, `nightshift(${options.programId}): run report and decision ledger`, ["docs/programs"]);
+    // Every workstream verdict, `complete`, and the exit-code mapping are
+    // already settled above; writing and committing the report is bookkeeping
+    // that must not be able to reject `runProgram` after the fact (SC-05,
+    // SC-12) — a full disk or an EISDIR here is a logged line, not a thrown
+    // run.
+    try {
+        await writeFile(reportPath, 
+        // `triaged` is the run-local set of subject ids the decider actually
+        // ruled on this run (built up across the authoring, build, and
+        // whole-program stages, see its declaration above) — exactly the
+        // `triagedThisRun` basis the "this run" triage ratio needs, since the
+        // projected ledger carries no run identifier of its own. It excludes
+        // ids that were merely sent but whose invocation failed or returned no
+        // valid verdict.
+        renderRunReport(manifest, results, ledger, triaged, authorResult, now(), wholeProgram), "utf8");
+        if (isRepository) {
+            await git.commitPaths(root, `nightshift(${options.programId}): run report and decision ledger`, ["docs/programs"]);
+        }
+    }
+    catch (error) {
+        log(`run report: could not write or commit ${reportPath}: ${error.message}`);
     }
     log(`run report: ${reportPath}`);
     return {
@@ -440,6 +498,7 @@ export async function runProgram(options) {
         workstreams: results,
         escalations,
         reportPath,
+        wholeProgramReview: wholeProgram,
     };
     async function runWorkstream(workstream) {
         const base = {
@@ -466,15 +525,25 @@ export async function runProgram(options) {
             ? await git.currentCommit(root)
             : undefined;
         let priorFailure;
+        let priorDiagnosis;
+        let implementerFingerprint;
         const attempts = [
             { agent, label: "implementer" },
         ];
         if (recovery && !recovery.borrowedImplementer) {
             attempts.push({ agent: recovery.agent, label: "recovery" });
+            // The third seat exists only when a reviewer can inform it. An
+            // uninformed retry has already been spent (recovery); running the
+            // roster again blind is a coin flip the ledger should hear about
+            // instead. Alternation is deliberate — the implementer returns with
+            // the reviewer's diagnosis in hand, a composition neither prior
+            // attempt had.
+            if (reviewer)
+                attempts.push({ agent, label: "informed retry" });
         }
         for (const [index, attempt] of attempts.entries()) {
             log(`${workstream.id} ${workstream.name}: ${attempt.label} attempt`);
-            const brief = implementerBrief(manifest, workstream, spec, ledgerAtStart, priorFailure);
+            const brief = implementerBrief(manifest, workstream, spec, ledgerAtStart, priorFailure, priorDiagnosis);
             const invocation = await invokeAgent(agentRunner, attempt.agent, brief, root);
             const summary = resolveSummary(invocation.output);
             base.summary = summary.text;
@@ -562,15 +631,57 @@ export async function runProgram(options) {
             }
             priorFailure = failure;
             log(`${workstream.id}: ${attempt.label} attempt failed — ${failure}`);
-            if (index === attempts.length - 1) {
+            // The informed retry is spent only when the diagnosed recovery attempt
+            // moved the failure at all. A failure reproduced identically after a
+            // diagnosis says the roster is stuck, not unlucky — that belongs in
+            // the ledger, not in a third spawn.
+            const stuck = attempt.label === "recovery" &&
+                index < attempts.length - 1 &&
+                implementerFingerprint !== undefined &&
+                failureFingerprint(failure) === implementerFingerprint;
+            if (index === attempts.length - 1 || stuck) {
                 workstream.status = "failed";
                 await saveManifest(root, options.programId, manifest);
                 // The work stays in the tree for a resume; decisions made on the way
                 // to a failure are still journaled and still reviewable.
                 await reviewWorkstreamDecisions(workstream.id, parsed.decisions, baseCommit);
-                base.outcome = { status: "failed", reason: failure };
+                base.outcome = {
+                    status: "failed",
+                    reason: stuck
+                        ? failure +
+                            "\n\nThe recovery attempt, briefed with a reviewer diagnosis, " +
+                            "reproduced the implementer's failure (identical up to counts " +
+                            "and timings), so the final retry was not spent."
+                        : failure,
+                };
                 return base;
             }
+            if (attempt.label === "implementer") {
+                implementerFingerprint = failureFingerprint(failure);
+            }
+            // Diagnose the failure for the next attempt's brief. Overwrites any
+            // prior diagnosis — a read of an older failure must not be pinned to
+            // a newer one.
+            priorDiagnosis = reviewer
+                ? await diagnoseFailure({
+                    root,
+                    manifest,
+                    workstream,
+                    spec,
+                    agentRunner,
+                    reviewer,
+                    git,
+                    baseCommit,
+                    failure,
+                })
+                : undefined;
+            if (priorDiagnosis !== undefined) {
+                (base.failureDiagnoses ??= []).push({
+                    attempt: attempt.label,
+                    verdict: priorDiagnosis,
+                });
+                log(`${workstream.id}: reviewer diagnosed the ${attempt.label} failure`);
+            }
         }
         return base;
     }
@@ -695,6 +806,192 @@ export async function runProgram(options) {
         return kept ? fix.greenCommit : greenCommit;
     }
 }
+/**
+ * Resolves the program's diff base for the whole-program review: the
+ * merge-base with the default branch, when it exists and differs from HEAD
+ * (the program's real branch point — the same range a pull request shows a
+ * human); otherwise `runStartCommit`, when it differs from HEAD (a
+ * `--force` run made directly on the default branch, where the merge-base is
+ * HEAD itself); otherwise `undefined` — an ordinary outcome, not a failure.
+ */
+export async function resolveProgramDiffBase(args) {
+    const { root, git, isRepository, runStartCommit } = args;
+    if (!isRepository)
+        return undefined;
+    const head = await git.currentCommit(root);
+    if (head === undefined)
+        return undefined;
+    const defaultBranch = await detectDefaultBranch(root);
+    const base = await git.mergeBase(root, defaultBranch, head);
+    if (base !== undefined && base !== head)
+        return base;
+    if (runStartCommit !== undefined && runStartCommit !== head)
+        return runStartCommit;
+    return undefined;
+}
+/** The synthetic workstream id whole-program findings are journaled under (SC-07). */
+export const WHOLE_PROGRAM_SUBJECT = "whole-program";
+function emptyWholeProgramSeverityCounts() {
+    return { blocker: 0, major: 0, minor: 0, advisory: 0 };
+}
+/** The placeholder outcome for the (practically unreachable) case where the stage's own body throws before the pass ever runs. */
+function stageFailureOutcome(reason) {
+    return {
+        ran: false,
+        status: "reviewer-error",
+        refreshed: false,
+        writtenPaths: [],
+        findings: [],
+        errors: [],
+        severityCounts: emptyWholeProgramSeverityCounts(),
+        lengthOverrun: false,
+        missingLimitations: [],
+        inputClipped: false,
+        reason,
+    };
+}
+/** Failed and parked workstreams only (SC-08) — a `skipped` result means already complete, i.e. built. */
+function notBuiltRoster(results, authorResult) {
+    const authorById = new Map(authorResult.results.map((entry) => [entry.id, entry]));
+    const notBuilt = [];
+    for (const result of results) {
+        const outcome = result.outcome;
+        if (outcome.status !== "failed" && outcome.status !== "parked")
+            continue;
+        const authorOutcome = authorById.get(result.id)?.outcome;
+        const reason = authorOutcome !== undefined &&
+            (authorOutcome.status === "failed" || authorOutcome.status === "parked")
+            ? `${outcome.reason} (spec authoring: ${authorOutcome.reason})`
+            : outcome.reason;
+        notBuilt.push({
+            id: result.id,
+            name: result.name,
+            status: outcome.status,
+            reason,
+        });
+    }
+    return notBuilt;
+}
+/**
+ * The end-of-run whole-program review stage: establishes the diff base,
+ * calls WS-01's never-throwing pass exactly once, commits exactly what it
+ * wrote, and routes its findings through the existing findings path. Every
+ * risky step around the pass gets its own catch so a stage failure is a
+ * sentence in the report, never a change to the run's outcome (SC-05,
+ * SC-12) — see the outer catch below for the belt-and-braces case where a
+ * bug in this function's own body throws before the pass has even run.
+ */
+export async function runWholeProgramStage(args) {
+    const { root, programId, manifest, config, agentRunner, git, isRepository, results, authorResult, runStartCommit, decider, reviewed, triaged, now, log, fs, } = args;
+    const errors = [];
+    let commit;
+    let commitSkipped = false;
+    let findingIds = [];
+    let outcome = stageFailureOutcome("the whole-program review stage did not complete");
+    // The caller's log callback is itself a risky step — it is not this
+    // stage's own code and can throw (a full log file, a broken transport).
+    // Both of the stage's own lines go through this wrapper rather than `log`
+    // directly, so a throwing logger costs one sentence in `errors` and never
+    // aborts the commit or the findings routing that follow it.
+    const safeLog = (line) => {
+        try {
+            log(line);
+        }
+        catch (error) {
+            errors.push(`the whole-program review logger failed: ${error.message}`);
+        }
+    };
+    try {
+        safeLog("whole-program review: starting");
+        const base = await resolveProgramDiffBase({ root, git, isRepository, runStartCommit });
+        const diff = base === undefined ? "" : await git.diffSince(root, base);
+        const notBuilt = notBuiltRoster(results, authorResult);
+        const reviewCommit = isRepository ? await git.currentCommit(root) : undefined;
+        outcome = await runWholeProgramReview({
+            root,
+            programId,
+            manifest,
+            config,
+            agentRunner,
+            diff,
+            ...(base === undefined ? {} : { baseCommit: base }),
+            ...(notBuilt.length === 0 ? {} : { notBuilt }),
+            ...(fs === undefined ? {} : { fs }),
+            log,
+        });
+        safeLog(outcome.status === "refreshed"
+            ? `whole-program review: refreshed ${AS_BUILT_PATH}` +
+                (outcome.archivedTo ? ` (archived to ${outcome.archivedTo})` : "")
+            : `whole-program review: ${outcome.status}` +
+                (outcome.reason ? ` — ${outcome.reason}` : ""));
+        if (outcome.writtenPaths.length > 0) {
+            if (isRepository) {
+                try {
+                    commit = await git.commitPaths(root, `nightshift(${programId}): as-built snapshot`, outcome.writtenPaths);
+                }
+                catch (error) {
+                    errors.push(`could not commit the as-built snapshot: ${error.message}`);
+                }
+            }
+            else {
+                commitSkipped = true;
+            }
+        }
+        const events = findingsToLedgerEvents({
+            workstreamId: WHOLE_PROGRAM_SUBJECT,
+            findings: outcome.findings.filter(hasRoutableEvidence),
+            ...(reviewCommit === undefined ? {} : { baseCommit: reviewCommit }),
+            now,
+        });
+        let journaled = false;
+        if (events.length === 0) {
+            journaled = true;
+        }
+        else {
+            try {
+                await appendLedgerEvents(root, programId, events);
+                journaled = true;
+                findingIds = events.map((event) => event.id);
+            }
+            catch (error) {
+                errors.push(`could not journal the whole-program findings: ${error.message}`);
+            }
+        }
+        if (journaled && events.length > 0) {
+            try {
+                await triageFindings({
+                    root,
+                    programId,
+                    manifest,
+                    workstreamId: WHOLE_PROGRAM_SUBJECT,
+                    findings: events,
+                    baseCommit: reviewCommit,
+                    decider,
+                    agentRunner,
+                    git,
+                    isRepository,
+                    reviewed,
+                    triaged,
+                    now,
+                    log,
+                });
+            }
+            catch (error) {
+                errors.push(`the decider failed to triage the whole-program findings: ${error.message}`);
+            }
+        }
+    }
+    catch (error) {
+        errors.push(`the whole-program review stage failed unexpectedly: ${error.message}`);
+    }
+    return {
+        outcome,
+        ...(commit === undefined ? {} : { commit }),
+        commitSkipped,
+        findingIds,
+        errors,
+    };
+}
 /** Undefined means the attempt verified clean; otherwise the diagnosis. */
 async function verifyAttempt(config, verifyRunner, root, agentExitCode) {
     if (agentExitCode !== 0) {
@@ -730,6 +1027,73 @@ function clipForReview(text, label) {
 function hasFindingsBlock(output) {
     return /```findings/u.test(output);
 }
+/**
+ * Two verify failures are "the same failure" when they differ only in
+ * numbers — counts, timings, durations, and line offsets are the volatile
+ * parts of test-runner output. Deterministic on purpose: whether a retry
+ * changed anything is not a judgment call to hand a model.
+ */
+function failureFingerprint(failure) {
+    return failure.replace(/\d+/gu, "#");
+}
+function failureDiagnosisBrief(manifest, workstream, spec, diff, failure) {
+    return [
+        `# Failure diagnosis: ${workstream.id} ${workstream.name}`,
+        "",
+        `Program: ${manifest.program.id} — ${manifest.program.name}`,
+        "",
+        "An implementation attempt for this workstream just failed verification.",
+        "You wrote none of it. Before another attempt is spent, decide what is",
+        "actually wrong: the tests, the implementation, or both. The attempt",
+        "wrote its own tests, so a failing assertion is exactly as suspect as",
+        "the code under it.",
+        "",
+        "Begin your reply with one line:",
+        "",
+        "    Verdict: test-wrong | code-wrong | both | unclear",
+        "",
+        "then explain in at most three short paragraphs, quoting the specific",
+        "assertion or code at fault. If a test asserts something the spec never",
+        "promises — a literal string that reads like a description of a",
+        "requirement rather than output the code could produce — say so plainly",
+        "and name the line. Do not modify any file; your reply is the only",
+        "artifact.",
+        "",
+        "## Specification",
+        "",
+        spec.trim(),
+        "",
+        "## Diff of the failing attempt (uncommitted, against the pre-workstream tree)",
+        "",
+        "```diff",
+        diff,
+        "```",
+        "",
+        "## Verify output",
+        "",
+        failure,
+        "",
+    ].join("\n");
+}
+/**
+ * The test-critique reviewer's read of a *failing* tree, taken before a
+ * retry is spent. The post-green critique can only ever see tests that
+ * already passed, so a wrong assertion written by the implementer is
+ * invisible to every party on the red path: both attempts treat the test as
+ * ground truth and try to satisfy it. This read is what makes a retry
+ * informed rather than blind. Fails open: any reviewer misbehavior returns
+ * undefined and the retry proceeds on the raw verify output alone.
+ */
+async function diagnoseFailure(options) {
+    const { root, manifest, workstream, spec, agentRunner, reviewer, git, baseCommit, failure } = options;
+    const rawDiff = baseCommit !== undefined ? await git.diffSince(root, baseCommit) : "";
+    const brief = failureDiagnosisBrief(manifest, workstream, clipForReview(spec, "spec").text, clipForReview(rawDiff, "diff").text, failure);
+    const invocation = await invokeAgent(agentRunner, reviewer, brief, root);
+    if (invocation.exitCode !== 0)
+        return undefined;
+    const text = invocation.output.trim();
+    return text === "" ? undefined : tail(text, 2000);
+}
 function successCriteriaLines(manifest) {
     if (manifest.successCriteria.length === 0) {
         return ["None recorded in the manifest."];
@@ -1039,36 +1403,36 @@ function renderRawFinding(finding, workstreamLabel, sinceFixed) {
     return `- **${finding.subject}** (${finding.severity}, ${workstreamLabel}) — ${finding.message}${suffix}`;
 }
 /**
- * A pass's minor/advisory findings, `open` and `resolved` alike (SC-07's
- * "every ... raised" — a finding the writer fixed was still raised),
- * deduped within the pass's own union so a finding present in both (should
- * WS-02's own dedup ever let that happen) is not double-listed.
+ * Minor/advisory findings from one list, deduped by subject/message/location.
+ * Shared by `collectPassLimitations` (a pass's `open` and `resolved` findings)
+ * and the whole-program review's flat `Finding[]`.
  */
-function collectPassLimitations(outcome, workstreamLabel) {
-    if (!outcome)
-        return [];
+function collectLimitationLines(findings, label, sinceFixed = false) {
     const seen = new Set();
     const lines = [];
-    for (const finding of outcome.open) {
-        if (finding.severity !== "minor" && finding.severity !== "advisory")
-            continue;
-        const key = limitationKey(finding);
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        lines.push(renderRawFinding(finding, workstreamLabel, false));
-    }
-    for (const finding of outcome.resolved) {
+    for (const finding of findings) {
         if (finding.severity !== "minor" && finding.severity !== "advisory")
             continue;
         const key = limitationKey(finding);
         if (seen.has(key))
             continue;
         seen.add(key);
-        lines.push(renderRawFinding(finding, workstreamLabel, true));
+        lines.push(renderRawFinding(finding, label, sinceFixed));
     }
     return lines;
 }
+/**
+ * A pass's minor/advisory findings, `open` and `resolved` alike (SC-07's
+ * "every ... raised" — a finding the writer fixed was still raised).
+ */
+function collectPassLimitations(outcome, workstreamLabel) {
+    if (!outcome)
+        return [];
+    return [
+        ...collectLimitationLines(outcome.open, workstreamLabel),
+        ...collectLimitationLines(outcome.resolved, workstreamLabel, true),
+    ];
+}
 /**
  * One aggregated section (SC-07): every minor/advisory finding raised
  * anywhere in the run, every finding the decider accepted, any finding
@@ -1076,11 +1440,14 @@ function collectPassLimitations(outcome, workstreamLabel) {
  * every fix-now attempt, and the run-local triage ratio. Fail-open
  * throughout — an empty run renders a plain statement, never nothing.
  */
-function renderKnownLimitations(results, authorResult, ledger, escalated, triagedThisRun, programId) {
+function renderKnownLimitations(results, authorResult, ledger, escalated, triagedThisRun, programId, wholeProgram) {
     const lines = ["## Known limitations", ""];
     const passLimitations = [
         ...results.flatMap((result) => collectPassLimitations(result.testCritique, `${result.id} test critique`)),
         ...authorResult.results.flatMap((entry) => collectPassLimitations(entry.specCritique, `${entry.id} spec critique`)),
+        ...(wholeProgram
+            ? collectLimitationLines(wholeProgram.outcome.findings, "whole-program review")
+            : []),
     ];
     const acceptedFindings = ledger.findings.filter((record) => record.status === "accepted");
     const openFindings = ledger.findings.filter((record) => record.status === "open");
@@ -1125,6 +1492,10 @@ function renderKnownLimitations(results, authorResult, ledger, escalated, triage
                     : "";
                 lines.push(`- **${record.subject}** — fixed in the run${commitPart}: ${record.fixAttempt.note}`, "");
             }
+            else if (record.workstream === WHOLE_PROGRAM_SUBJECT) {
+                lines.push(`- **${record.subject}** — from the whole-program review, triaged ` +
+                    "`fix-now`: carried to the next run; nothing was fixed in this one.", "");
+            }
             else {
                 lines.push(`- **${record.subject}** — fix-now triaged; outcome pending.`, "");
             }
@@ -1136,7 +1507,54 @@ function renderKnownLimitations(results, authorResult, ledger, escalated, triage
         `${escalatedThisRunCount} ${escalatedThisRunCount === 1 ? "was" : "were"} escalated.`, "");
     return lines;
 }
-export function renderRunReport(manifest, results, ledger, triagedThisRun, authorResult, at) {
+/** The commit fact WS-01's outcome cannot know — sha and paths, or why there is none. */
+function commitFactLines(wholeProgram) {
+    const { commit, commitSkipped, outcome } = wholeProgram;
+    if (commit !== undefined) {
+        return [`Committed as \`${commit}\`: ${outcome.writtenPaths.join(", ")}.`];
+    }
+    if (outcome.writtenPaths.length === 0) {
+        return ["No commit — nothing was written."];
+    }
+    if (commitSkipped) {
+        return [
+            "Written to the working tree but not committed: this is not a git repository.",
+        ];
+    }
+    return ["The snapshot was written, but committing it failed — see the stage error below."];
+}
+/**
+ * A whole-program finding this stage journaled that the decider triaged
+ * `fix-now` this run. Keys on `findingIds` (this run's own journaling), not
+ * on `record.workstream` — that broader statement is §3.7's, in
+ * `renderKnownLimitations`, and applies across runs.
+ */
+function carriedFixNowLines(wholeProgram, ledger) {
+    if (wholeProgram.findingIds.length === 0)
+        return [];
+    const ids = new Set(wholeProgram.findingIds);
+    const carried = ledger.findings.filter((record) => ids.has(record.id) && record.status === "fix-now");
+    if (carried.length === 0)
+        return [];
+    return carried.map((record) => `Triaged \`fix-now\`: **${record.subject}** — carried to the next run; nothing was fixed in this one.`);
+}
+/**
+ * The `## Whole-program review` section: delegates its body to WS-01's own
+ * renderer verbatim, and adds only what that module cannot know — the commit
+ * fact, this run's carried fix-now findings, and this stage's own errors.
+ */
+function renderWholeProgramSection(wholeProgram, ledger) {
+    const lines = ["## Whole-program review", ""];
+    lines.push(...renderWholeProgramReview(wholeProgram.outcome));
+    lines.push(...commitFactLines(wholeProgram));
+    lines.push(...carriedFixNowLines(wholeProgram, ledger));
+    if (wholeProgram.errors.length > 0) {
+        lines.push(...wholeProgram.errors.map((error) => `Stage error: ${error}`));
+    }
+    lines.push("");
+    return lines;
+}
+export function renderRunReport(manifest, results, ledger, triagedThisRun, authorResult, at, wholeProgram) {
     const programId = manifest.program.id;
     const built = results.filter((result) => result.outcome.status === "complete" ||
         result.outcome.status === "skipped").length;
@@ -1168,7 +1586,11 @@ export function renderRunReport(manifest, results, ledger, triagedThisRun, autho
             const reason = result.outcome.status === "failed" || result.outcome.status === "parked"
                 ? result.outcome.reason
                 : "";
-            lines.push(`### ${result.id} ${result.name} — ${result.outcome.status}`, "", reason, "", `Retry after fixing: \`npx --yes @wildorder/nightshift run ${manifest.program.id}\``, "(completed workstreams are skipped automatically).", "");
+            lines.push(`### ${result.id} ${result.name} — ${result.outcome.status}`, "", reason, "");
+            for (const diagnosis of result.failureDiagnoses ?? []) {
+                lines.push(`**Reviewer diagnosis (after the ${diagnosis.attempt} attempt):**`, "", diagnosis.verdict, "");
+            }
+            lines.push(`Retry after fixing: \`npx --yes @wildorder/nightshift run ${manifest.program.id}\``, "(completed workstreams are skipped automatically).", "");
         }
     }
     lines.push("## Workstreams", "");
@@ -1177,6 +1599,13 @@ export function renderRunReport(manifest, results, ledger, triagedThisRun, autho
         if (result.summary) {
             lines.push(`  - ${result.summary.replace(/\s+/gu, " ").trim()}`);
         }
+        if (result.outcome.status === "complete") {
+            for (const diagnosis of result.failureDiagnoses ?? []) {
+                const oneLine = diagnosis.verdict.replace(/\s+/gu, " ").trim();
+                const head = oneLine.length > 300 ? `${oneLine.slice(0, 300)}…` : oneLine;
+                lines.push(`  - Recovered: the ${diagnosis.attempt} attempt failed and the reviewer diagnosed it before a later attempt went green — ${head}`);
+            }
+        }
         if (result.testCritique) {
             for (const line of renderPassReport("Test critique", result.testCritique)) {
                 lines.push(line === "" ? "" : `  ${line}`);
@@ -1187,6 +1616,9 @@ export function renderRunReport(manifest, results, ledger, triagedThisRun, autho
         }
     }
     lines.push("");
+    if (wholeProgram !== undefined) {
+        lines.push(...renderWholeProgramSection(wholeProgram, ledger));
+    }
     const settledDecisions = ledger.decisions.filter((record) => record.status !== "escalated");
     lines.push("## Decisions made along the way", "", "Every judgment call an agent surfaced, with its review status.", "Anything here can be revisited: roll back to the anchor commit and", "re-run, or just say which option you want changed.", "");
     if (settledDecisions.length === 0) {
@@ -1197,7 +1629,7 @@ export function renderRunReport(manifest, results, ledger, triagedThisRun, autho
             lines.push(...renderRecord(record, { density: "compact", programId }), "");
         }
     }
-    lines.push(...renderKnownLimitations(results, authorResult, ledger, escalated, triagedThisRun, programId));
+    lines.push(...renderKnownLimitations(results, authorResult, ledger, escalated, triagedThisRun, programId, wholeProgram));
     const decisionErrors = results.flatMap((result) => result.decisionErrors);
     if (decisionErrors.length > 0) {
         lines.push("## Decision blocks the runner could not read", "", ...decisionErrors.map((error) => `- ${error}`), "");