@wildorder/nightshift 0.5.0 → 0.7.0

package/dist/run-program.js

@@ -7,10 +7,16 @@ import { resolveSummary, summaryContract } from "./agent-summary.js";
 import { authorProgram } from "./author.js";
 import { decisionContract, decisionFingerprint, extractDecisions, } from "./decision.js";
 import { appendLedgerEvents, readDecisionLedger, } from "./decision-ledger.js";
-import { reviewDecisions } from "./decider-review.js";
+import { escalatedRecords, renderRecord, } from "./decision-view.js";
+import { reviewDecisions, triageFindings } from "./decider-review.js";
+import { fingerprint } from "./findings.js";
 import { findCycles, stableTopologicalOrder } from "./graph.js";
-import { extractFindings, findingsContract, findingsToLedgerEvents, renderPassReport, reviewerAbsentOutcome, runReviewPass, } from "./review-pass.js";
+import { extractFindings, findingsContract, findingsToLedgerEvents, hasRoutableEvidence, locateInRepo, renderPassReport, reviewerAbsentOutcome, runReviewPass, verifyEvidence, } from "./review-pass.js";
 import { loadManifest, saveManifest, } from "./manifest.js";
+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";
 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;
@@ -33,6 +39,15 @@ export const defaultGitOps = {
             return undefined;
         }
     },
+    async currentBranch(cwd) {
+        try {
+            const { stdout } = await execFileAsync("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd });
+            return stdout.trim();
+        }
+        catch {
+            return undefined;
+        }
+    },
     async commitAll(cwd, message) {
         await execFileAsync("git", ["add", "-A"], { cwd });
         try {
@@ -128,6 +143,37 @@ function decisionsRuledOnSection(records) {
     lines.push("");
     return lines;
 }
+/**
+ * A human-decided finding is binding on the next run, same as a
+ * human-decided decision — but the label's force is origin-specific, so the
+ * brief renders the *instruction* each label binds, never a bare label
+ * (SC-16). `fix-now` is a required correction; `accept` forbids reopening
+ * the settled limitation; `escalate` is degenerate for a human ruling — the
+ * human is the escalation target — so it binds no implementer instruction,
+ * exactly as an escalated-but-unruled finding renders none.
+ */
+function findingsRuledOnSection(records) {
+    const lines = [];
+    for (const record of records) {
+        if (record.status !== "human-decided")
+            continue;
+        if (record.humanChosen === "fix-now") {
+            lines.push(`- **${record.subject}** — binding: the human ruled \`fix-now\` — ` +
+                `${record.humanReason}. This is a required correction: address ` +
+                "the cited defect in this workstream; it is not optional.");
+        }
+        else if (record.humanChosen === "accept") {
+            lines.push(`- **${record.subject}** — binding: the human ruled \`accept\` — ` +
+                `${record.humanReason}. This is a settled known limitation: do ` +
+                "not reopen, re-litigate, or attempt to fix it.");
+        }
+        // A human `escalate` ruling (or any other label) binds no implementer
+        // instruction — the human is the escalation target, not a fix to build.
+    }
+    if (lines.length === 0)
+        return [];
+    return ["## Findings ruled on", "", ...lines, ""];
+}
 function implementerBrief(manifest, workstream, spec, ledger, priorFailure) {
     const roster = manifest.workstreams
         .map((entry) => {
@@ -137,6 +183,7 @@ function implementerBrief(manifest, workstream, spec, ledger, priorFailure) {
         .join("\n");
     const relevantDecisions = ledger.decisions.filter((record) => record.workstream === workstream.id &&
         (record.status === "human-decided" || record.status === "ratified"));
+    const relevantFindings = ledger.findings.filter((record) => record.workstream === workstream.id && record.status === "human-decided");
     return [
         `# Workstream ${workstream.id}: ${workstream.name}`,
         "",
@@ -149,6 +196,7 @@ function implementerBrief(manifest, workstream, spec, ledger, priorFailure) {
         roster,
         "",
         ...decisionsRuledOnSection(relevantDecisions),
+        ...findingsRuledOnSection(relevantFindings),
         ...(priorFailure
             ? [
                 "## Previous attempt failed",
@@ -216,10 +264,16 @@ export async function runProgram(options) {
     const git = options.git ?? defaultGitOps;
     const log = options.log ?? ((line) => console.log(line));
     const now = options.now ?? (() => new Date());
-    let manifest = await loadManifest(root, options.programId);
+    let manifest;
+    try {
+        manifest = await loadManifest(root, options.programId);
+    }
+    catch (error) {
+        throw new CouldNotStartError(error.message, { cause: error });
+    }
     const resolvedAgent = resolveAgent(config);
     if (!resolvedAgent) {
-        throw new Error("No implementer configured. Set the `agent` block in nightshift.config.json.");
+        throw new CouldNotStartError("No implementer configured. Set the `agent` block in nightshift.config.json.");
     }
     const agent = resolvedAgent;
     const recovery = resolveRecoveryAgent(config);
@@ -236,7 +290,7 @@ export async function runProgram(options) {
     if (cycles.length > 0) {
         // A cyclic graph cannot be ordered; this is a planning defect, not a
         // decision the runner can take. Terminate with the diagnosis.
-        throw new Error(`Dependency cycle(s) in the manifest: ${cycles
+        throw new CouldNotStartError(`Dependency cycle(s) in the manifest: ${cycles
             .map((cycle) => cycle.join(" -> "))
             .join("; ")}. Re-plan with /plan-program.`);
     }
@@ -256,11 +310,49 @@ export async function runProgram(options) {
             workstream.status === "in_progress" ||
             workstream.status === "parked");
         if (dirty.length > 0 && !resuming) {
-            throw new Error(`The working tree has uncommitted changes the run would sweep into its commits:\n` +
+            throw new CouldNotStartError(`The working tree has uncommitted changes the run would sweep into its commits:\n` +
                 dirty.map((path) => `  ${path}`).join("\n") +
                 `\nCommit or stash them, then re-run.`);
         }
+        // A run always commits to the program's own branch — never the default
+        // branch, and never another program's branch, since the runner commits
+        // with `git add -A` and a mismatched worktree would sweep this program's
+        // work onto the wrong branch. These refuse before authorProgram below
+        // spawns the first agent; --force is the explicit escape hatch.
+        if (!options.force) {
+            const currentBranch = await git.currentBranch(root);
+            const branchCommand = `nightshift branch ${options.programId}`;
+            const expectedBranch = programBranchName(options.programId);
+            if (currentBranch === undefined) {
+                throw new CouldNotStartError(`HEAD is detached; a run must be on this program's branch ` +
+                    `\`${expectedBranch}\`. Create or switch to it with ` +
+                    `\`${branchCommand}\`, or re-run with --force.`);
+            }
+            const defaultBranch = await detectDefaultBranch(root);
+            if (currentBranch === defaultBranch) {
+                throw new CouldNotStartError(`Refusing to run on the default branch \`${defaultBranch}\`; a ` +
+                    `program run commits to its own branch. Switch with ` +
+                    `\`${branchCommand}\`, or re-run with --force.`);
+            }
+            if (currentBranch !== expectedBranch) {
+                throw new CouldNotStartError(`This run is for \`${options.programId}\`, whose branch is ` +
+                    `\`${expectedBranch}\`, but HEAD is \`${currentBranch}\`. Switch ` +
+                    `with \`${branchCommand}\`, or re-run with --force.`);
+            }
+        }
     }
+    // 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
+    // honest rather than per-stage. A resumed run starts a fresh set and
+    // legitimately re-reviews an earlier run's subjects.
+    const reviewed = new Set();
+    // Subject ids the decider actually ruled on this run — a strict subset of
+    // `reviewed` (a subject can be sent but the invocation fail or return no
+    // parseable verdict). This, not `reviewed`, is the run-local basis for the
+    // report's "this run" triage ratio — see decider-review.ts's doc comment
+    // on `triaged`.
+    const triaged = new Set();
     // Authoring runs before building: every workstream whose spec is missing
     // gets one, in dependency order, before anything is implemented. It
     // reloads the manifest afterward because authoring may have merged
@@ -273,6 +365,8 @@ export async function runProgram(options) {
         git,
         log,
         now,
+        reviewed,
+        triaged,
     });
     manifest = await loadManifest(root, options.programId);
     // Loaded once so every brief in this run projects the same picture of
@@ -322,13 +416,20 @@ export async function runProgram(options) {
         }
     }
     const ledger = await readDecisionLedger(root, options.programId);
-    const escalations = ledger.decisions.filter((decision) => decision.status === "escalated");
+    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 reportPath = join(root, "docs", "programs", `${options.programId}-run-report.md`);
-    await writeFile(reportPath, renderRunReport(manifest, results, ledger.decisions, escalations, authorResult, now()), "utf8");
+    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"]);
     }
@@ -413,18 +514,17 @@ export async function runProgram(options) {
                 // The manifest's single commit field records the workstream's final
                 // verified state — after any kept fix, that is the fix commit, not
                 // the earlier green one.
-                const finalCommit = critique?.finalCommit ?? c0;
+                let finalCommit = critique?.finalCommit ?? c0;
                 // Findings anchor to c0 (the green, pre-critique commit) — the
                 // honest rollback point — while the decider below diffs from
                 // baseCommit (pre-workstream), so it sees the whole workstream.
                 const findingEvents = findingsToLedgerEvents({
                     workstreamId: workstream.id,
-                    findings: critique?.outcome.open ?? [],
+                    findings: (critique?.outcome.open ?? []).filter(hasRoutableEvidence),
                     ...(c0 === undefined ? {} : { baseCommit: c0 }),
                     now,
                 });
                 await appendLedgerEvents(root, options.programId, findingEvents);
-                const findingDecisions = findingEvents.flatMap((event) => event.kind === "decision-recorded" ? [event.decision] : []);
                 // The commit's own sha cannot be part of the tree it commits, so the
                 // manifest records it only now — swept forward into whatever commits
                 // next. Replay reads the manifest's current state, not the commit
@@ -433,7 +533,24 @@ export async function runProgram(options) {
                 if (finalCommit !== undefined)
                     workstream.commit = finalCommit;
                 await saveManifest(root, options.programId, manifest);
-                await reviewWorkstreamDecisions(workstream.id, [...parsed.decisions, ...findingDecisions], baseCommit);
+                await reviewWorkstreamDecisions(workstream.id, parsed.decisions, baseCommit);
+                // Findings are triaged against the pre-workstream diff (baseCommit),
+                // the same one the decider reviews decisions against — c0/finalCommit
+                // are the fix loop's own rollback anchors, a different thing.
+                await reviewWorkstreamFindings(workstream.id, findingEvents, baseCommit);
+                // A fix-now triage drives exactly one bounded fix attempt, here —
+                // after the triage that produced it, before the run advances. Only
+                // reachable when there is a green commit to attempt from and a
+                // decider that could have produced a fix-now verdict in the first
+                // place (SC-13).
+                if (finalCommit !== undefined && decider) {
+                    const driven = await driveFixNowFindings(workstream, spec, critique?.outcome.open ?? [], finalCommit);
+                    if (driven !== finalCommit) {
+                        finalCommit = driven;
+                        workstream.commit = finalCommit;
+                        await saveManifest(root, options.programId, manifest);
+                    }
+                }
                 if (critique)
                     base.testCritique = critique.outcome;
                 base.testCritiqueDiffClipped = critique?.diffClipped ?? false;
@@ -484,10 +601,99 @@ export async function runProgram(options) {
             agentRunner,
             git,
             isRepository,
+            reviewed,
+            triaged,
             now,
             log,
         });
     }
+    function reviewWorkstreamFindings(workstreamId, findings, baseCommit) {
+        return triageFindings({
+            root,
+            programId: options.programId,
+            manifest,
+            workstreamId,
+            findings,
+            baseCommit,
+            decider,
+            agentRunner,
+            git,
+            isRepository,
+            reviewed,
+            triaged,
+            now,
+            log,
+        });
+    }
+    /**
+     * Drives the one bounded fix attempt a `fix-now` triage earns (WS-06).
+     * Selects findings from the ledger projection — never from any in-memory
+     * disposition — so a human-decided finding (status `"human-decided"`, not
+     * `"fix-now"`) is never handed to the fix seam (SC-14). A workstream's
+     * `fix-now` findings are fixed together, in one `attemptFix` call, then
+     * recorded as one `finding-fix-attempted` event per finding id — a ledger
+     * entry, never a re-triage (SC-14). Returns the (possibly unchanged) green
+     * commit; never throws, never blocks the run (SC-15).
+     */
+    async function driveFixNowFindings(workstream, spec, openFindings, greenCommit) {
+        const ledger = await readDecisionLedger(root, options.programId);
+        const fixNowIds = new Set(ledger.findings
+            .filter((record) => record.workstream === workstream.id && record.status === "fix-now")
+            .map((record) => record.id));
+        if (fixNowIds.size === 0)
+            return greenCommit;
+        const toFix = [];
+        const matchedIds = [];
+        for (const candidate of openFindings) {
+            const id = fingerprint({ ...candidate, workstreamId: workstream.id });
+            if (!fixNowIds.has(id))
+                continue;
+            toFix.push(candidate);
+            matchedIds.push(id);
+        }
+        // An id triaged fix-now but absent from the open set (should not
+        // happen — it is where the id came from) is skipped, fail-open.
+        if (toFix.length === 0)
+            return greenCommit;
+        const fix = await attemptFix({
+            root,
+            programId: options.programId,
+            workstream,
+            spec,
+            config,
+            agentRunner,
+            verifyRunner,
+            git,
+            agent,
+            findings: toFix,
+            greenCommit,
+            label: "fix-now fix",
+            log,
+        });
+        // "kept" only when the attempt both verified clean and actually landed a
+        // commit — a clean-but-empty attempt is a decline, not a fix, and must
+        // reach the human exactly like a failed verification does.
+        const kept = fix.outcome === "kept" && fix.commit !== undefined;
+        const note = kept
+            ? fix.summary
+            : fix.outcome === "kept"
+                ? `${fix.summary} (the attempt verified clean but made no change; no fix landed)`
+                : `${fix.summary} (fix failed verification and was discarded: ${fix.failure})`;
+        const events = matchedIds.map((id) => ({
+            kind: "finding-fix-attempted",
+            at: now().toISOString(),
+            id,
+            outcome: kept ? "kept" : "failed",
+            note,
+            ...(kept && fix.commit !== undefined ? { commit: fix.commit } : {}),
+            attemptedBy: "implementer",
+        }));
+        await appendLedgerEvents(root, options.programId, events);
+        log(kept
+            ? `${workstream.id}: fix-now fix verified and committed`
+            : `${workstream.id}: fix-now fix failed and was escalated — ${note}`);
+        return kept ? fix.greenCommit : greenCommit;
+    }
 }
 /** Undefined means the attempt verified clean; otherwise the diagnosis. */
 async function verifyAttempt(config, verifyRunner, root, agentExitCode) {
@@ -675,6 +881,55 @@ function testCritiqueFixBrief(workstream, spec, findings) {
         summaryContract(),
     ].join("\n");
 }
+/**
+ * The fix seam, in full: one brief carrying every finding, one implementer
+ * invocation, one verification, one commit on green or one reset on
+ * failure. Never invokes a reviewer and never loops — the caller owns
+ * whether (and how many times) this is called.
+ */
+async function attemptFix(options) {
+    const { root, programId, workstream, spec, config, agentRunner, verifyRunner, git, agent, findings, greenCommit, label, } = options;
+    const brief = testCritiqueFixBrief(workstream, spec, findings);
+    const invocation = await invokeAgent(agentRunner, agent, brief, root);
+    const summary = resolveSummary(invocation.output).text;
+    const failure = await verifyAttempt(config, verifyRunner, root, invocation.exitCode);
+    if (failure === undefined) {
+        // The runner's own pending ledger and manifest writes under
+        // docs/programs sit uncommitted in the tree until the run's final
+        // commit — appended by earlier steps in this very workstream (findings,
+        // triage) or by an earlier workstream in the same run. A plain
+        // `git add -A` would otherwise sweep that bookkeeping into this fix's
+        // commit and make a genuine no-op look like a landed fix. Only a change
+        // outside docs/programs counts as the implementer having done anything;
+        // with none, skip committing — the pending bookkeeping stays for a
+        // later commit to pick up, nothing is lost.
+        const dirty = await git.dirtyPaths(root);
+        const meaningfulChange = dirty.some((path) => !path.replaceAll("\\", "/").startsWith("docs/programs/"));
+        const commit = meaningfulChange
+            ? await git.commitAll(root, `nightshift(${programId}): ${workstream.id} ${label}`)
+            : undefined;
+        return {
+            outcome: "kept",
+            greenCommit: commit ?? greenCommit,
+            ...(commit === undefined ? {} : { commit }),
+            summary,
+        };
+    }
+    // The same uncommitted bookkeeping the clean path guards against sweeping
+    // into a commit is, on this path, what a whole-tree `git reset --hard`
+    // would silently throw away: by the time a fix-now attempt runs, this
+    // workstream's finding-recorded, finding-triaged and decision-reviewed
+    // events are on disk and not yet committed. Resetting without them would
+    // erase the finding this very attempt is about to report a failure on —
+    // and the `finding-fix-attempted` event appended afterwards would project
+    // against nothing, so the escalation would never reach the human (SC-15).
+    // Preserve the journal across the rollback exactly as `decide`'s replay
+    // does; the run's final commit picks it up.
+    const snapshot = await snapshotProgramsDir(root);
+    await git.resetHard(root, greenCommit);
+    await restoreProgramsDir(root, snapshot);
+    return { outcome: "failed", greenCommit, summary, failure };
+}
 /**
  * The test-critique driver: wires WS-01's bounded review loop to the two
  * briefs above, and owns the green-state invariant (SC-07) — a closure
@@ -689,6 +944,7 @@ async function runTestCritique(options) {
     if (!reviewer) {
         return { outcome: reviewerAbsentOutcome(), finalCommit: greenCommit, diffClipped };
     }
+    const locate = (file) => locateInRepo(root, file);
     const review = async (_round, priorOpen) => {
         const rawDiff = baseCommit !== undefined ? await git.diffSince(root, baseCommit) : "";
         const diff = clipForReview(rawDiff, "diff");
@@ -698,24 +954,33 @@ async function runTestCritique(options) {
         const brief = testCritiqueReviewerBrief(manifest, workstream, clippedSpec.text, diff.text, priorOpen);
         const invocation = await invokeAgent(agentRunner, reviewer, brief, root);
         const parsed = extractFindings(invocation.output);
+        const findings = verifyEvidence(parsed.findings, locate);
         const ran = invocation.exitCode === 0 && hasFindingsBlock(invocation.output);
-        return { findings: parsed.findings, errors: parsed.errors, ran };
+        return { findings, errors: parsed.errors, ran };
     };
     const respond = async (_round, findings) => {
-        const brief = testCritiqueFixBrief(workstream, spec, findings);
-        const invocation = await invokeAgent(agentRunner, agent, brief, root);
-        const summary = resolveSummary(invocation.output).text;
-        const failure = await verifyAttempt(config, verifyRunner, root, invocation.exitCode);
-        if (failure === undefined) {
-            const next = await git.commitAll(root, `nightshift(${manifest.program.id}): ${workstream.id} test critique fix`);
-            if (next !== undefined)
-                greenCommit = next;
+        const fix = await attemptFix({
+            root,
+            programId: manifest.program.id,
+            workstream,
+            spec,
+            config,
+            agentRunner,
+            verifyRunner,
+            git,
+            agent,
+            findings,
+            greenCommit,
+            label: "test critique fix",
+            log,
+        });
+        greenCommit = fix.greenCommit;
+        if (fix.outcome === "kept") {
             log(`${workstream.id}: test critique fix verified and committed`);
-            return { note: `${summary} (fix verified and committed)` };
+            return { note: `${fix.summary} (fix verified and committed)` };
         }
-        await git.resetHard(root, greenCommit);
-        log(`${workstream.id}: test critique fix failed verification and was discarded — ${failure}`);
-        return { note: `${summary} (fix failed verification and was discarded; the green state was preserved)` };
+        log(`${workstream.id}: test critique fix failed verification and was discarded — ${fix.failure}`);
+        return { note: `${fix.summary} (fix failed verification and was discarded; the green state was preserved)` };
     };
     const outcome = await runReviewPass({ review, respond });
     return { outcome, finalCommit: greenCommit, diffClipped };
@@ -751,7 +1016,128 @@ function renderSpecsSection(authorResult) {
     }
     return lines;
 }
-function renderRunReport(manifest, results, decisions, escalations, authorResult, at) {
+/**
+ * By subject + message + first evidence location — the dedup key for
+ * collecting minor/advisory findings into known-limitations. Deliberately
+ * looser than `findings.ts`'s `fingerprint` (which is identity across
+ * review rounds): here two textually distinct findings about the same
+ * subject and location are still worth listing once.
+ */
+function limitationKey(finding) {
+    const first = finding.evidence[0];
+    const location = first === undefined
+        ? ""
+        : first.kind === "location"
+            ? `${first.file}:${first.startLine}`
+            : first.kind === "concern"
+                ? first.named
+                : `${first.metric}:${first.value}`;
+    return `${finding.subject}|${finding.message}|${location}`;
+}
+function renderRawFinding(finding, workstreamLabel, sinceFixed) {
+    const suffix = sinceFixed ? " (raised, since fixed)" : "";
+    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.
+ */
+function collectPassLimitations(outcome, workstreamLabel) {
+    if (!outcome)
+        return [];
+    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) {
+        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));
+    }
+    return lines;
+}
+/**
+ * One aggregated section (SC-07): every minor/advisory finding raised
+ * anywhere in the run, every finding the decider accepted, any finding
+ * still awaiting triage or already ruled on by a human, the outcome of
+ * 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) {
+    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`)),
+    ];
+    const acceptedFindings = ledger.findings.filter((record) => record.status === "accepted");
+    const openFindings = ledger.findings.filter((record) => record.status === "open");
+    const humanDecidedFindings = ledger.findings.filter((record) => record.status === "human-decided");
+    const fixNowFindings = ledger.findings.filter((record) => record.status === "fix-now");
+    const hasFindingsContent = passLimitations.length > 0 ||
+        acceptedFindings.length > 0 ||
+        openFindings.length > 0 ||
+        humanDecidedFindings.length > 0;
+    if (!hasFindingsContent) {
+        lines.push("No known limitations were recorded.", "");
+    }
+    else {
+        if (passLimitations.length > 0) {
+            lines.push("Minor and advisory findings raised during review:", "", ...passLimitations, "");
+        }
+        if (acceptedFindings.length > 0) {
+            lines.push("Accepted as known limitations:", "");
+            for (const record of acceptedFindings) {
+                lines.push(...renderRecord(record, { density: "compact", programId }), "");
+            }
+        }
+        if (openFindings.length > 0) {
+            lines.push("Recorded, not yet triaged:", "");
+            for (const record of openFindings) {
+                lines.push(...renderRecord(record, { density: "compact", programId }), "");
+            }
+        }
+        if (humanDecidedFindings.length > 0) {
+            lines.push("Ruled by the human:", "");
+            for (const record of humanDecidedFindings) {
+                lines.push(...renderRecord(record, { density: "compact", programId }), "");
+            }
+        }
+    }
+    if (fixNowFindings.length > 0) {
+        lines.push("Fix-now attempts:", "");
+        for (const record of fixNowFindings) {
+            if (record.fixAttempt?.outcome === "kept") {
+                const commitPart = record.fixAttempt.commit
+                    ? ` (commit \`${record.fixAttempt.commit}\`)`
+                    : "";
+                lines.push(`- **${record.subject}** — fixed in the run${commitPart}: ${record.fixAttempt.note}`, "");
+            }
+            else {
+                lines.push(`- **${record.subject}** — fix-now triaged; outcome pending.`, "");
+            }
+        }
+    }
+    const triagedCount = triagedThisRun.size;
+    const escalatedThisRunCount = escalated.filter((record) => triagedThisRun.has(record.id)).length;
+    lines.push(`The decider triaged ${triagedCount} subject${triagedCount === 1 ? "" : "s"} this run; ` +
+        `${escalatedThisRunCount} ${escalatedThisRunCount === 1 ? "was" : "were"} escalated.`, "");
+    return lines;
+}
+export function renderRunReport(manifest, results, ledger, triagedThisRun, authorResult, at) {
+    const programId = manifest.program.id;
     const built = results.filter((result) => result.outcome.status === "complete" ||
         result.outcome.status === "skipped").length;
     const lines = [
@@ -763,12 +1149,16 @@ function renderRunReport(manifest, results, decisions, escalations, authorResult
         "",
         ...renderSpecsSection(authorResult),
     ];
-    if (escalations.length > 0) {
-        lines.push("## Needs your attention", "", "The decider reviewed these choices and believes you might decide", "differently. Each is anchored to the commit before it was made:", "");
-        for (const record of escalations) {
-            lines.push(`### ${record.decision.title} (${record.id})`, "", `- **Workstream:** ${record.workstream}`, `- **Chosen:** ${record.decision.chosen}`, `- **Decider says:** ${record.reviewRationale ?? "(no rationale recorded)"}`, ...(record.baseCommit
-                ? [`- **To revisit:** roll back to \`${record.baseCommit}\` and re-run.`]
-                : []), "");
+    const escalated = escalatedRecords(ledger);
+    if (escalated.length > 0) {
+        lines.push("## Needs your attention", "", "The decider reviewed these choices and findings and believes you", "might decide differently. Each is self-contained below: why it is", "here, the alternatives, and a command to flip it if you disagree.", "");
+        for (const record of escalated) {
+            lines.push(...renderRecord(record, { density: "full", programId }));
+            if ("origin" in record &&
+                record.origin === "finding" &&
+                record.fixAttempt?.outcome === "failed") {
+                lines.push(`- **Fix attempt:** ${record.fixAttempt.note}`, "");
+            }
         }
     }
     const failures = results.filter((result) => result.outcome.status === "failed" || result.outcome.status === "parked");
@@ -797,23 +1187,17 @@ function renderRunReport(manifest, results, decisions, escalations, authorResult
         }
     }
     lines.push("");
-    if (decisions.length > 0) {
-        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.", "");
-        for (const record of decisions) {
-            const alternatives = record.decision.options
-                .filter((option) => option.label !== record.decision.chosen)
-                .map((option) => option.label)
-                .join(", ");
-            lines.push(`### ${record.decision.title} (${record.id}) — ${record.status}`, "", `- **Workstream:** ${record.workstream}${record.oneWay ? " · **one-way door**" : ""}`, `- **Context:** ${record.decision.context}`, `- **Chosen:** ${record.decision.chosen} — ${record.decision.rationale}`, `- **Alternatives:** ${alternatives === "" ? "(none listed)" : alternatives}`, ...(record.reviewRationale
-                ? [`- **Decider:** ${record.reviewRationale}`]
-                : []), ...(record.baseCommit
-                ? [`- **Anchor commit:** \`${record.baseCommit}\``]
-                : []), "");
-        }
+    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) {
+        lines.push("None surfaced.", "");
     }
     else {
-        lines.push("## Decisions made along the way", "", "None surfaced.", "");
+        for (const record of settledDecisions) {
+            lines.push(...renderRecord(record, { density: "compact", programId }), "");
+        }
     }
+    lines.push(...renderKnownLimitations(results, authorResult, ledger, escalated, triagedThisRun, programId));
     const decisionErrors = results.flatMap((result) => result.decisionErrors);
     if (decisionErrors.length > 0) {
         lines.push("## Decision blocks the runner could not read", "", ...decisionErrors.map((error) => `- ${error}`), "");