@wildorder/nightshift 0.16.0 → 0.18.0

package/dist/run-program.js

@@ -1,26 +1,46 @@
 import { execFile } from "node:child_process";
-import { readFile, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { defaultAgentRunner, defaultVerifyRunner, describeAgent, invokeAgent, resolveAgent, resolveAuthorAgent, resolveDeciderAgent, resolveRecoveryAgent, resolveReviewerAgent, tail, } from "./agent-runner.js";
+import { describeSessionDecline, spawnWithSessionContinuity, SESSION_CONTINUATION_PREAMBLE, } from "./agent-session.js";
 import { resolveSummary, summaryContract } from "./agent-summary.js";
-import { authorProgram } from "./author.js";
+import { prepareAuthoring } from "./author.js";
 import { decisionContract, decisionFingerprint, extractDecisions, } from "./decision.js";
 import { appendLedgerEvents, denialFingerprint, readDecisionLedger, } from "./decision-ledger.js";
 import { escalatedRecords, renderDenial, 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, hasRoutableEvidence, locateInRepo, renderPassReport, reviewerAbsentOutcome, runReviewPass, verifyEvidence, } from "./review-pass.js";
+import { extractFindings, findingsContract, findingsToLedgerEvents, hasRoutableEvidence, locateInRepo, renderPassReport, reviewerAbsentOutcome, runReviewPass, verifyEvidence, TEST_CRITIQUE_CYCLES, TEST_CRITIQUE_CYCLE_NOTE, } from "./review-pass.js";
+import { createVerifyCache, runnerOwnedVerifyPaths } from "./verify-cache.js";
 import { loadManifest, manifestMergeCount, saveManifest, } from "./manifest.js";
 import { detectDefaultBranch, programBranchName } from "./program-branch.js";
 import { defaultPrerequisiteRunner, runPreflight, } from "./preflight.js";
-import { restoreProgramsDir, snapshotProgramsDir } from "./programs-dir.js";
 import { buildPermitsContext } from "./permits.js";
 import { CouldNotStartError } from "./exit-codes.js";
+import { clippedInputPoint, createBriefBuilder, promptComponentSizePoints, } from "./prompt-telemetry.js";
+import { NOOP_RUN_RECORDER, readPriorRunId, recordWorkstreamReady, recordWorkstreamScheduled, recordWorkstreamWaiting, RunRecorder, } from "./run-analytics.js";
+import { renderAnalyticsSection } from "./run-analytics-report.js";
+import { drainProgramWrites, programWriteKey } from "./write-queue.js";
+import { schedulerLog, workstreamLog } from "./run-log.js";
+import { createMutex } from "./concurrency.js";
+import { normalizeMaxParallel, runReadySet } from "./scheduler.js";
+import { defaultWorktreeOps, isRunnerOwnedArtifactPath, resolveWorktreeBase, retainedRefName, worktreeBranchName, worktreeBranchPrefix, worktreeInstallCommand, worktreePathFor, } from "./worktree.js";
 import { runReportPath } from "./report-path.js";
 import { AS_BUILT_PATH, runWholeProgramReview, renderWholeProgramReview, } from "./whole-program-review.js";
+import { runCausalAnalysis, renderCausalAnalysisSection, } from "./causal-analysis.js";
 const execFileAsync = promisify(execFile);
+/** The attempt-loop seat label to its stage (WS-02) — the role-derived
+ *  `STAGE_FOR_ROLE` default in `agent-runner.ts` cannot distinguish these
+ *  three, since `agent` drives both `implementer` and `informed-retry`. */
+const STAGE_FOR_SEAT = {
+    implementer: "implementer",
+    recovery: "recovery",
+    "informed retry": "informed-retry",
+};
 /** 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;
 /**
@@ -133,8 +153,13 @@ export const defaultGitOps = {
             return undefined;
         }
     },
-    async commitAll(cwd, message) {
-        await execFileAsync("git", ["add", "-A"], { cwd });
+    async commitAll(cwd, message, excludePaths) {
+        if (excludePaths && excludePaths.length > 0) {
+            await execFileAsync("git", ["add", "-A", "--", ":(top)", ...excludePaths.map((path) => `:(top,exclude)${path}`)], { cwd });
+        }
+        else {
+            await execFileAsync("git", ["add", "-A"], { cwd });
+        }
         try {
             await execFileAsync("git", ["commit", "-m", message], { cwd });
         }
@@ -151,7 +176,12 @@ export const defaultGitOps = {
     async commitPaths(cwd, message, paths) {
         await execFileAsync("git", ["add", "--", ...paths], { cwd });
         try {
-            await execFileAsync("git", ["commit", "-m", message], { cwd });
+            // The trailing pathspec is load-bearing, not decoration: without it
+            // this commits the *whole* index, sweeping in anything else staged in
+            // `cwd` at the time (an unrelated human `git add`, or the runner's own
+            // residue from a prior failed commit) — the same hazard squashIntegrate
+            // guards against for the workstream integration commit (WS-02 §2, §3.5).
+            await execFileAsync("git", ["commit", "-m", message, "--", ...paths], { cwd });
         }
         catch (error) {
             const output = String(error.stdout ?? "");
@@ -168,7 +198,10 @@ export const defaultGitOps = {
     },
     async diffSince(cwd, commit) {
         try {
-            const { stdout } = await execFileAsync("git", ["diff", commit, "--", ".", ":!docs/programs"], { cwd, maxBuffer: 10 * 1024 * 1024 });
+            // `:(top)`-anchored pathspecs are repo-root-relative regardless of
+            // `cwd` — in a worktree, "repo root" is the worktree root, exactly the
+            // tree a reviewer or decider spawned there should see (WS-02).
+            const { stdout } = await execFileAsync("git", ["diff", commit, "--", ":(top)", ":(top,exclude)docs/programs"], { cwd, maxBuffer: 10 * 1024 * 1024 });
             return stdout;
         }
         catch {
@@ -177,11 +210,20 @@ export const defaultGitOps = {
     },
     async dirtyPaths(cwd) {
         try {
-            const { stdout } = await execFileAsync("git", ["status", "--porcelain"], { cwd });
-            return stdout
-                .split(/\r?\n/u)
-                .filter((line) => line.trim() !== "")
-                .map((line) => line.slice(3).trim());
+            const { stdout } = await execFileAsync("git", ["status", "--porcelain", "-z"], { cwd });
+            // NUL-delimited so quoted and non-ASCII names come back verbatim and
+            // compare equal to `changedPaths`' `-z` output. A rename or copy entry
+            // carries its original path as a second token, which is skipped.
+            const tokens = stdout.split("\0").filter((token) => token !== "");
+            const paths = [];
+            for (let index = 0; index < tokens.length; index += 1) {
+                const token = tokens[index];
+                const code = token.slice(0, 2);
+                paths.push(token.slice(3));
+                if (code.includes("R") || code.includes("C"))
+                    index += 1;
+            }
+            return paths;
         }
         catch {
             return [];
@@ -223,7 +265,76 @@ export const defaultGitOps = {
     async createRef(cwd, ref, commit) {
         await execFileAsync("git", ["update-ref", ref, commit], { cwd });
     },
+    async deleteRef(cwd, ref) {
+        try {
+            await execFileAsync("git", ["update-ref", "-d", ref], { cwd });
+        }
+        catch {
+            // Already absent — nothing to delete.
+        }
+    },
+    async treeHash(cwd, exclude) {
+        let tmpDir;
+        try {
+            tmpDir = await mkdtemp(join(tmpdir(), "nightshift-verify-cache-"));
+            const indexFile = join(tmpDir, "index");
+            const env = { ...process.env, GIT_INDEX_FILE: indexFile };
+            await execFileAsync("git", ["read-tree", "HEAD"], { cwd, env });
+            await execFileAsync("git", ["add", "-A", "--", ":/"], { cwd, env });
+            if (exclude.length > 0) {
+                await execFileAsync("git", ["rm", "--cached", "-q", "--ignore-unmatch", "--", ...exclude], { cwd, env });
+            }
+            const { stdout } = await execFileAsync("git", ["write-tree"], { cwd, env });
+            return stdout.trim();
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            if (tmpDir !== undefined) {
+                try {
+                    await rm(tmpDir, { recursive: true, force: true });
+                }
+                catch {
+                    // Best-effort cleanup; a leftover temp dir is not a correctness
+                    // issue and must not mask the hash result above.
+                }
+            }
+        }
+    },
 };
+/**
+ * Fail-open span wrapper for a runner-owned git-and-persistence operation
+ * (WS-02): opens a span, awaits `fn`, closes it `success` on completion or
+ * `interrupted` on a throw (re-thrown unchanged, via `finally`) — this
+ * module's stage functions already guard the *run* error a wrapped call can
+ * raise, so this wrapper only ever adds an observation, never changes what
+ * the caller sees. `evidenceFor`, when given, derives an evidence reference
+ * from the successful result (e.g. a commit sha) rather than every call
+ * needing to know the schema's evidence-kind vocabulary itself. Shared by
+ * `run-program.ts`'s own git/manifest/ledger call sites and imported by
+ * `author.ts` and `decider-review.ts` for theirs, so every runner-owned
+ * commit, large diff, and manifest/ledger persist is instrumented through
+ * one implementation.
+ */
+export async function timed(recorder, dims, fn, evidenceFor) {
+    const span = recorder.span(dims);
+    let result;
+    try {
+        result = await fn();
+    }
+    catch (error) {
+        span.close({ outcome: "interrupted" });
+        throw error;
+    }
+    const evidence = evidenceFor?.(result);
+    span.close({ outcome: "success", ...(evidence && evidence.length > 0 ? { evidence } : {}) });
+    return result;
+}
+/** `timed`'s `evidenceFor` for a git commit call: a defined, non-empty sha becomes a `commit` evidence ref; "nothing to commit" (`undefined`) carries none. */
+export function commitEvidence(sha) {
+    return sha === undefined ? undefined : [{ kind: "commit", locality: "local", ref: sha }];
+}
 /**
  * Ledger decisions for one workstream, projected into its brief. A
  * human-decided record is binding — the implementer is told to build that
@@ -311,6 +422,13 @@ function shellPolicySection(shellPolicy) {
         "",
     ];
 }
+/**
+ * Builds the implementer's brief, byte-for-byte identical to the plain
+ * `array.join("\n")` this produced before WS-03 — but through a
+ * `BriefBuilder` so every line is also classified into an SC-07 prompt
+ * component, with `components` summing exactly to the joined brief's byte
+ * length.
+ */
 function implementerBrief(manifest, workstream, spec, ledger, shellPolicy, priorFailure, priorDiagnosis) {
     const roster = manifest.workstreams
         .map((entry) => {
@@ -321,64 +439,46 @@ function implementerBrief(manifest, workstream, spec, ledger, shellPolicy, prior
     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}`,
-        "",
-        `Program: ${manifest.program.id} — ${manifest.program.name}`,
-        "",
-        "You are implementing exactly one workstream of a larger program. The",
-        "full roster, so you know what exists and do not rebuild another",
-        "workstream's work (conform only to your declared dependencies):",
-        "",
-        roster,
-        "",
-        ...decisionsRuledOnSection(relevantDecisions),
-        ...findingsRuledOnSection(relevantFindings),
-        ...(priorFailure
-            ? [
-                "## Previous attempt failed",
-                "",
-                "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.",
-                "",
-            ]
-            : []),
-        "## Specification",
-        "",
-        spec.trim(),
-        "",
-        "## Rules",
-        "",
-        "- Never commit; the runner owns commits and commits only verified work.",
-        "- Follow the repository's AGENTS.md if present.",
-        "- Run the project's checks yourself as you work; the runner verifies",
-        "  independently afterwards and your claim of success is never trusted",
-        "  without it.",
-        "",
-        ...shellPolicySection(shellPolicy),
-        decisionContract(),
-        "",
-        summaryContract(),
-    ].join("\n");
+    const builder = createBriefBuilder();
+    builder.push("framing", `# Workstream ${workstream.id}: ${workstream.name}`, "");
+    builder.push("program-narrative", `Program: ${manifest.program.id} — ${manifest.program.name}`);
+    builder.push("framing", "", "You are implementing exactly one workstream of a larger program. The", "full roster, so you know what exists and do not rebuild another", "workstream's work (conform only to your declared dependencies):", "");
+    builder.push("roster", roster);
+    builder.push("framing", "");
+    builder.push("ledger-rulings", ...decisionsRuledOnSection(relevantDecisions), ...findingsRuledOnSection(relevantFindings));
+    builder.push("prior-diagnostics", ...(priorFailure
+        ? [
+            "## Previous attempt failed",
+            "",
+            "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.",
+            "",
+        ]
+        : []));
+    builder.push("framing", "## Specification", "");
+    builder.push("workstream-spec", spec.trim());
+    builder.push("framing", "", "## Rules", "", "- Never commit; the runner owns commits and commits only verified work.", "- Follow the repository's AGENTS.md if present, with one exception,", "  stated next.", "- Run only the checks that cover what you changed — the tests for the", "  code you touched, and the command that was failing if you were given", "  a failure above. Do not run the project's full build/type-check/test/", "  lint suite: the runner runs it in full after you and gates on the", "  result, so a full run of your own is duplicated work, not extra", "  safety. This overrides AGENTS.md's \"verify before claiming", "  completion\" directive for this spawn only. Your claim of success is", "  never trusted either way, so you are not being asked to prove", "  anything here — only to catch your own mistakes early.", "- You are working in a dedicated git worktree on a per-workstream", "  branch. Do not switch branches, and do not edit `docs/programs/` —", "  those are the runner's own artifacts and changes to them are", "  discarded.", "");
+    builder.push("runner-instructions", ...shellPolicySection(shellPolicy), decisionContract(), "", summaryContract());
+    return { brief: builder.join(), components: builder.components() };
 }
 /** Known `docs/programs/` artifact suffixes, longest-specific first is not required — each is checked independently. */
 const DOCS_PROGRAMS_SUFFIXES = [
@@ -386,6 +486,7 @@ const DOCS_PROGRAMS_SUFFIXES = [
     "-manifest.json",
     "-run-report.md",
     "-decisions.jsonl",
+    "-run-analytics.json",
 ];
 /**
  * The program id a planning-artifact path belongs to, or undefined when the
@@ -492,6 +593,522 @@ async function permissionsStartupLines(config, permits, agent, recovery, decider
     }
     return lines;
 }
+/**
+ * Reaps every worktree and per-workstream branch this program created,
+ * driven by `git worktree list --porcelain` filtered on the branch prefix —
+ * never on path, since git realpath-resolves the paths it reports (WS-02,
+ * §3.7). Runs on every run, not only a resume: a crashed prior run leaves the
+ * same debris. Retained `refs/nightshift/…` commits are never touched — they
+ * are the forensic record a human needs to salvage a parked integration.
+ */
+export async function reapProgramWorktrees(root, programId, worktrees, log, 
+/** Workstreams already `complete` in the manifest: their leftover
+ *  worktree (a crash between integration and cleanup) holds nothing the
+ *  program branch lacks, so it is reaped without salvage. */
+completeWorkstreamIds = new Set()) {
+    const prefix = worktreeBranchPrefix(programId);
+    const reaped = [];
+    const salvaged = [];
+    const list = await worktrees.list(root);
+    for (const info of list) {
+        const short = info.branch?.startsWith("refs/heads/")
+            ? info.branch.slice("refs/heads/".length)
+            : info.branch;
+        if (short === undefined || !short.startsWith(prefix))
+            continue;
+        const ref = await salvageWorktree(root, programId, short, info, worktrees, completeWorkstreamIds);
+        if (ref !== undefined)
+            salvaged.push(ref);
+        await worktrees.remove(root, info.path);
+        await worktrees.deleteBranch(root, short);
+        reaped.push(short);
+    }
+    await worktrees.prune(root);
+    const orphanBranches = await worktrees.branchesUnder(root, prefix);
+    for (const branch of orphanBranches) {
+        await worktrees.deleteBranch(root, branch);
+        if (!reaped.includes(branch))
+            reaped.push(branch);
+    }
+    if (salvaged.length > 0) {
+        log(`worktrees: salvaged unintegrated work from a prior run before reaping — inspect with ` +
+            `\`git log <ref>\` or \`git worktree add <path> <ref>\`: ${salvaged.join(", ")}`);
+    }
+    if (reaped.length > 0) {
+        log(`worktrees: reaped ${reaped.length} leftover branch(es) from a prior run: ${reaped.join(", ")}`);
+    }
+}
+/**
+ * Preserves a leftover worktree's work before it is reaped — the
+ * reversibility contract: a resume must never destroy the only copy of a
+ * failed attempt that the run report just told the human to inspect.
+ * Everything in the worktree is committed onto its own branch and, when
+ * that head is not already reachable from the program branch, pinned under
+ * `refs/nightshift/<program>/<workstream>-wip`. Returns the ref, or undefined
+ * when nothing needed salvaging (the workstream is complete, the directory
+ * is gone, or the `WorktreeOps` double has no salvage seam). Never throws:
+ * salvage is best-effort and must not block the run.
+ */
+async function salvageWorktree(root, programId, shortBranch, info, worktrees, completeWorkstreamIds) {
+    if (!worktrees.commitEverything || !worktrees.updateRef || !worktrees.isAncestor)
+        return undefined;
+    if (info.prunable === true)
+        return undefined;
+    const workstreamId = shortBranch.slice(worktreeBranchPrefix(programId).length);
+    if (workstreamId === "")
+        return undefined;
+    const lowered = new Set([...completeWorkstreamIds].map((id) => id.toLowerCase()));
+    if (lowered.has(workstreamId))
+        return undefined;
+    try {
+        const head = await worktrees.commitEverything(info.path, `nightshift(${programId}): salvaged work in progress for ${workstreamId}`);
+        if (head === undefined)
+            return undefined;
+        if (await worktrees.isAncestor(root, head, "HEAD"))
+            return undefined;
+        const ref = `${retainedRefName(programId, workstreamId)}-wip`;
+        await worktrees.updateRef(root, ref, head);
+        return ref;
+    }
+    catch {
+        return undefined;
+    }
+}
+const INSTALL_TRIGGER_NAMES = [
+    "package.json",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lockb",
+    "bun.lock",
+];
+/** True when any path in `paths` is (or ends with) a file that can change a worktree's installed dependencies (WS-02, §3.5 step 1). */
+function touchesInstallFiles(paths) {
+    return paths.some((path) => INSTALL_TRIGGER_NAMES.some((name) => path === name || path.endsWith(`/${name}`)));
+}
+/**
+ * Runs a worktree's dependency install command, when a lockfile is present
+ * in the worktree root itself (WS-02, §3.3) — attributed to the caller's
+ * open `worktree-setup` span. A worktree with no lockfile installs nothing
+ * and is not a failure.
+ */
+async function installWorktreeDependencies(worktreeRoot, setupRunner, log) {
+    const installCommand = worktreeInstallCommand(worktreeRoot);
+    if (installCommand === undefined) {
+        log("worktree: no lockfile — dependencies not installed");
+        return { ok: true };
+    }
+    let result;
+    try {
+        result = await setupRunner(installCommand, worktreeRoot);
+    }
+    catch (error) {
+        return { ok: false, reason: `dependency install could not run: ${error.message}` };
+    }
+    if (result.exitCode !== 0) {
+        return {
+            ok: false,
+            reason: `dependency install (\`${installCommand}\`) failed:\n${tail(result.output, 1500)}`,
+        };
+    }
+    log(`worktree: installed dependencies (${installCommand})`);
+    return { ok: true };
+}
+export async function prepareWorktree(args) {
+    const { root, programId, workstreamId, worktrees, worktreeBase, setupRunner, log, programTip } = args;
+    const branch = worktreeBranchName(programId, workstreamId);
+    const path = worktreePathFor(worktreeBase.base, programId, workstreamId, worktreeBase.repoHash);
+    try {
+        // Idempotent belt-and-braces against a crash-leftover from this same
+        // run; cross-run leftovers are reaped at run start.
+        await worktrees.remove(root, path);
+        await worktrees.deleteBranch(root, branch);
+        // `remove` is a no-op for a directory git no longer lists (a prior
+        // `worktree prune` after a crash); `add` would then refuse with
+        // "already exists". The path is program-owned, so clearing it is safe.
+        await rm(path, { recursive: true, force: true });
+        await worktrees.add(root, path, branch, programTip);
+    }
+    catch (error) {
+        await worktrees.remove(root, path);
+        await worktrees.deleteBranch(root, branch);
+        return { ok: false, reason: `could not create the worktree: ${error.message}`, created: false };
+    }
+    log(`worktree: created at ${path}`);
+    const install = await installWorktreeDependencies(path, setupRunner, log);
+    if (!install.ok) {
+        return { ok: false, reason: install.reason, created: true, cwd: path, branch };
+    }
+    return { ok: true, cwd: path, branch };
+}
+/**
+ * One integration attempt: discard runner debris, merge the program branch
+ * forward when its tip has moved, re-verify the merged tree, then squash
+ * onto the program branch as one path-limited commit (WS-02, §3.5). Never
+ * throws; every failure mode is a typed result the caller decides what to do
+ * with (retain and recover, or report).
+ */
+async function attemptIntegration(args) {
+    const { root, programId, workstreamId, workstreamName, cwd, branch, finalCommit, worktrees, git, config, verifyRunner, setupRunner, scope, log, rootIndexMutex, rosterTaskFiles, } = args;
+    // The full refname, not the short branch name: `refs/nightshift/<p>/<ws>`
+    // (the retained ref) and `refs/heads/nightshift/<p>/<ws>` (this branch)
+    // are distinct refs that never collide, but git's own short-name
+    // disambiguation tries `refs/<name>` *before* `refs/heads/<name>` — a bare
+    // `nightshift/<p>/<ws>` passed to `git diff`/`git merge --squash` resolves
+    // ambiguously and can silently pick the retained ref instead of the
+    // branch. Every revision-parsing use below is spelled out in full; only
+    // `deleteBranch`, which operates on `refs/heads/` by construction, uses
+    // the short name.
+    const branchRef = `refs/heads/${branch}`;
+    // Steps 0-1: discard runner debris, then merge the program branch forward
+    // when its tip is not already an ancestor of this worktree's own commit.
+    const mergeSpan = scope.span({ stage: "integration", workstream: workstreamId });
+    const discarded = await worktrees.discardRunnerArtifacts(cwd);
+    if (discarded.length > 0) {
+        log(`integration: discarded agent edit(s) under docs/programs: ${discarded.join(", ")}`);
+    }
+    const tipNow = await worktrees.resolveCommit(root, "HEAD");
+    if (tipNow === undefined) {
+        mergeSpan.close({ outcome: "failed" });
+        return { ok: false, kind: "tip-unresolvable" };
+    }
+    let mergeRan = false;
+    if (!(await git.isAncestor(cwd, tipNow, finalCommit))) {
+        mergeRan = true;
+        const mergeResult = await worktrees.mergeInto(cwd, tipNow, `nightshift(${programId}): merge program branch into ${workstreamId}`);
+        if (!mergeResult.ok) {
+            await worktrees.abortMerge(cwd);
+            mergeSpan.close({ outcome: "failed" });
+            return { ok: false, kind: "conflict", output: mergeResult.output, tipNow };
+        }
+        log("integration: merged the program branch forward");
+        const changedByMerge = await worktrees.changedPaths(cwd, finalCommit, "HEAD");
+        if (touchesInstallFiles(changedByMerge)) {
+            const install = await installWorktreeDependencies(cwd, setupRunner, log);
+            if (!install.ok) {
+                mergeSpan.close({ outcome: "failed" });
+                return { ok: false, kind: "install", output: install.reason, tipNow };
+            }
+        }
+    }
+    mergeSpan.close({ outcome: "success" });
+    // Step 2: re-verify, but only when the merge actually ran — an unmoved tip
+    // means the tree is byte-identical to the one that just verified green.
+    if (mergeRan) {
+        log("integration: verifying the merged tree");
+        const verifyFailure = await verifyAttempt(config, verifyRunner, cwd, root, 0, scope, "verification-command", {
+            programId,
+            phase: "integration",
+            workstream: workstreamId,
+            ...(args.verifyCache ? { cache: args.verifyCache } : {}),
+        });
+        if (verifyFailure !== undefined) {
+            return { ok: false, kind: "verify", output: verifyFailure, tipNow };
+        }
+    }
+    // Step 3: squash onto the program branch, in the root checkout.
+    const squashSpan = scope.span({ stage: "integration", workstream: workstreamId });
+    const incoming = await worktrees.changedPaths(root, tipNow, branchRef);
+    if (incoming.length === 0) {
+        squashSpan.close({ outcome: "success" });
+        log("integration: nothing to integrate — the branch matches the tip");
+        return { ok: true };
+    }
+    // WS-05 §3.7.1: everything from here on runs inside `rootIndexMutex`,
+    // which (together with `integrationMutex`, already held by the caller for
+    // this whole flow) makes the re-resolved tip below stable for the rest of
+    // this step. The only thing that can have moved the program-branch tip
+    // since `tipNow` was resolved above is an authoring commit — it takes no
+    // `integrationMutex` and must not (§3.7) — so a movement here is always
+    // exactly that, never a sibling integration.
+    return await rootIndexMutex.runExclusive(async () => {
+        const tipAtSquash = await worktrees.resolveCommit(root, "HEAD");
+        if (tipAtSquash === undefined) {
+            squashSpan.close({ outcome: "failed" });
+            return { ok: false, kind: "tip-unresolvable" };
+        }
+        const movedPaths = tipAtSquash === tipNow ? [] : await worktrees.changedPaths(root, tipNow, tipAtSquash);
+        if (movedPaths.length > 0) {
+            // Branch 3: the movement collides with this workstream's own paths, or
+            // touches something an authoring commit has no business touching —
+            // never proceed past a movement like that; land it unverified would be
+            // exactly the unproven integration SC-02 forbids.
+            const intersecting = movedPaths.filter((path) => incoming.includes(path));
+            const disallowed = movedPaths.filter((path) => !isRunnerOwnedArtifactPath(path) && !rosterTaskFiles.has(path));
+            if (intersecting.length > 0 || disallowed.length > 0) {
+                squashSpan.close({ outcome: "failed" });
+                const parts = [];
+                if (intersecting.length > 0) {
+                    parts.push(`path(s) this workstream also touched: ${intersecting.join(", ")}`);
+                }
+                if (disallowed.length > 0) {
+                    parts.push(`path(s) outside the runner's own artifacts or a roster spec file: ${disallowed.join(", ")}`);
+                }
+                return {
+                    ok: false,
+                    kind: "moved",
+                    tipNow,
+                    tipAtSquash,
+                    output: `the program branch moved from \`${tipNow}\` to \`${tipAtSquash}\` while this ` +
+                        `workstream was integrating (an authoring commit landed); ${parts.join("; ")}.`,
+                };
+            }
+        }
+        // Branch 2 (movedPaths non-empty but disjoint from `incoming` and every
+        // path runner-owned or a roster spec file) falls through to the same
+        // squash as branch 1 (no movement) — only the post-condition below
+        // differs, relaxed to the subset form §3.7.1 requires.
+        const dirtyAtRoot = new Set(await git.dirtyPaths(root));
+        const overlap = incoming.filter((path) => dirtyAtRoot.has(path));
+        if (overlap.length > 0) {
+            squashSpan.close({ outcome: "failed" });
+            return {
+                ok: false,
+                kind: "refused",
+                output: `the workstream changed path(s) already uncommitted at the root checkout: ${overlap.join(", ")}`,
+                tipNow,
+            };
+        }
+        const squash = await worktrees.squashIntegrate(root, branchRef, `nightshift(${programId}): ${workstreamId} ${workstreamName}`, incoming);
+        if (!squash.ok) {
+            squashSpan.close({ outcome: "failed" });
+            return { ok: false, kind: "refused", output: squash.output, tipNow };
+        }
+        if (squash.commit !== undefined) {
+            // Post-condition: the integrated tree equals the branch's tree, up to
+            // paths the concurrent tip movement (if any) already explains — a
+            // path list that produced the commit was incomplete, or a movement
+            // that collided, is worse than a failed integration.
+            const remaining = await worktrees.changedPaths(root, squash.commit, branchRef);
+            const unexplained = remaining.filter((path) => !movedPaths.includes(path));
+            if (unexplained.length > 0) {
+                squashSpan.close({ outcome: "failed" });
+                return {
+                    ok: false,
+                    kind: "refused",
+                    output: `the integration commit's tree does not match the branch's: ${unexplained.join(", ")}`,
+                    tipNow,
+                };
+            }
+        }
+        squashSpan.close({ outcome: "success" });
+        log(squash.commit !== undefined
+            ? `integration: integrated as \`${squash.commit}\``
+            : "integration: nothing to commit");
+        return { ok: true, ...(squash.commit === undefined ? {} : { commit: squash.commit }) };
+    });
+}
+function integrationFailureText(result, finalCommit) {
+    if (result.kind === "tip-unresolvable") {
+        return "cannot resolve the program-branch tip";
+    }
+    // Every branch below names both commits the recovery brief and the
+    // outcome reason need: the verified commit this worktree built, and the
+    // program-branch tip it could not be reconciled with (WS-02 §3.6 step 6).
+    // "conflict" was the only kind that did this until the coverage review
+    // caught that a red integration verify, a failed post-merge reinstall, or
+    // a refused squash all left a diagnosis that named neither.
+    const verb = result.kind === "conflict"
+        ? `merging the program branch (now at \`${result.tipNow}\`) into the verified commit \`${finalCommit}\` conflicted`
+        : result.kind === "verify"
+            ? `the merged tree (program branch now at \`${result.tipNow}\`, verified commit \`${finalCommit}\`) failed re-verification`
+            : result.kind === "install"
+                ? `reinstalling dependencies after merging the program branch (now at \`${result.tipNow}\`) into the verified commit \`${finalCommit}\` failed`
+                // "moved" (WS-05 §3.7.1): a concurrent authoring commit moved the
+                // tip during this integration's own squash step, colliding with
+                // this workstream's paths or touching something it should not
+                // have — named by both shas, never retried in place.
+                : result.kind === "moved"
+                    ? `landing the verified commit \`${finalCommit}\` (scheduled from tip \`${result.tipNow}\`) conflicted with an authoring commit that landed during integration (program branch now at \`${result.tipAtSquash}\`)`
+                    : `the squash integration of the verified commit \`${finalCommit}\` onto the program branch (now at \`${result.tipNow}\`) failed`;
+    return `${verb}:\n${result.output}`;
+}
+function integrationRecoveryBrief(workstream, finalCommit, retainedRef, tipNow, failureText) {
+    return [
+        `# Integration recovery: ${workstream.id} ${workstream.name}`,
+        "",
+        "This workstream's build already verified green, as commit",
+        `\`${finalCommit}\`, reachable from this worktree as \`${retainedRef}\` — `,
+        "`git show`, `git diff`, and `git cherry-pick` against that ref all",
+        "work from here even though it is not checked out. Since then, the",
+        `program branch moved to a new tip, \`${tipNow}\`, and landing the`,
+        "verified work on top of it failed:",
+        "",
+        failureText,
+        "",
+        "Your job is to land the workstream's *intent* on top of the current",
+        "tip — not to reproduce the old commit byte for byte. Resolve whatever",
+        "conflicted, or fix whatever the merged tree's verification found,",
+        "however that takes: editing the code, editing the tests the failed",
+        "attempt wrote, or both.",
+        "",
+        "You are working in a dedicated git worktree on a per-workstream",
+        "branch. Never commit — the runner owns commits and verifies your fix",
+        "itself. Do not switch branches, and do not edit `docs/programs/` —",
+        "those are the runner's own artifacts and changes to them are",
+        "discarded.",
+        "",
+        summaryContract(),
+    ].join("\n");
+}
+/**
+ * Integrates one green worktree onto the program branch (WS-02, §3.5-§3.6):
+ * one attempt, and on failure, exactly one bounded recovery attempt in a
+ * fresh worktree from the current tip, briefed with both commits and the
+ * failure. The verified commit is retained under `refs/nightshift/` on
+ * every path, before any mutation, and deleted again only once this
+ * function returns success.
+ */
+export async function integrateWorkstream(args) {
+    const { root, programId, workstream, cwd, branch, finalCommit, worktrees, git, config, verifyRunner, setupRunner, agentRunner, permits, recoveryAgent, worktreeBase, scope, log, transcriptSink, rootIndexMutex, rosterTaskFiles, } = args;
+    const ref = retainedRefName(programId, workstream.id);
+    const cleanup = [{ path: cwd, branch }];
+    // Full refname, not the short branch name: see attemptIntegration's own
+    // note on why a bare short name can resolve ambiguously once a
+    // same-named `refs/nightshift/...` ref exists (e.g. left over from a
+    // prior run's failed integration of this same workstream).
+    await git.createRef(root, ref, `refs/heads/${branch}`);
+    const first = await attemptIntegration({
+        root,
+        programId,
+        workstreamId: workstream.id,
+        workstreamName: workstream.name,
+        cwd,
+        branch,
+        finalCommit,
+        worktrees,
+        git,
+        config,
+        verifyRunner,
+        setupRunner,
+        ...(args.verifyCache ? { verifyCache: args.verifyCache } : {}),
+        scope,
+        log,
+        rootIndexMutex,
+        rosterTaskFiles,
+    });
+    if (first.ok) {
+        return { ok: true, ...(first.commit === undefined ? {} : { commit: first.commit }), transcripts: [], cleanup };
+    }
+    const firstReason = integrationFailureText(first, finalCommit);
+    log(`integration: ${firstReason}`);
+    const recoveryBranch = `${worktreeBranchName(programId, workstream.id)}-integration`;
+    const recoveryPath = worktreePathFor(worktreeBase.base, programId, `${workstream.id}-integration`, worktreeBase.repoHash);
+    const transcripts = [];
+    const recoveryTip = await worktrees.resolveCommit(root, "HEAD");
+    if (recoveryTip === undefined) {
+        return {
+            ok: false,
+            reason: `${firstReason}\n\nRecovery could not start: the program-branch tip could not be resolved.`,
+            retainedRef: ref,
+            worktreePaths: [cwd],
+            transcripts,
+        };
+    }
+    try {
+        await worktrees.remove(root, recoveryPath);
+        await worktrees.deleteBranch(root, recoveryBranch);
+        await worktrees.add(root, recoveryPath, recoveryBranch, recoveryTip);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `${firstReason}\n\nRecovery could not start: the recovery worktree could not be ` +
+                `created (${error.message}).`,
+            retainedRef: ref,
+            worktreePaths: [cwd],
+            transcripts,
+        };
+    }
+    cleanup.push({ path: recoveryPath, branch: recoveryBranch });
+    const install = await installWorktreeDependencies(recoveryPath, setupRunner, log);
+    if (!install.ok) {
+        return {
+            ok: false,
+            reason: `${firstReason}\n\nRecovery could not start: ${install.reason}`,
+            retainedRef: ref,
+            worktreePaths: [cwd, recoveryPath],
+            transcripts,
+        };
+    }
+    const cause = first.kind === "verify" || first.kind === "install" ? "integration-verify" : "integration-conflict";
+    const failureTipNow = first.kind === "tip-unresolvable" ? recoveryTip : first.tipNow;
+    const brief = integrationRecoveryBrief(workstream, finalCommit, ref, failureTipNow, firstReason);
+    let invocation;
+    try {
+        invocation = await invokeAgent(agentRunner, recoveryAgent, brief, recoveryPath, permits, "recoveryAgent", transcriptSink("integration-recovery"), scope, { stage: "recovery", workstream: workstream.id, attemptSeat: "integration recovery", attemptReason: cause });
+        if (invocation.transcript)
+            transcripts.push(invocation.transcript);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `${firstReason}\n\nThe recovery agent could not be spawned: ${error.message}`,
+            retainedRef: ref,
+            worktreePaths: [cwd, recoveryPath],
+            transcripts,
+        };
+    }
+    const recoveryVerifyFailure = await verifyAttempt(config, verifyRunner, recoveryPath, root, invocation.exitCode, scope, "verification-command", {
+        programId,
+        phase: "integration-recovery",
+        workstream: workstream.id,
+        role: "recoveryAgent",
+        attemptSeat: "integration recovery",
+    });
+    if (recoveryVerifyFailure !== undefined) {
+        return {
+            ok: false,
+            reason: `${firstReason}\n\nThe recovery attempt failed verification: ${recoveryVerifyFailure}`,
+            retainedRef: ref,
+            worktreePaths: [cwd, recoveryPath],
+            transcripts,
+        };
+    }
+    const recoveryCommit = await git.commitAll(recoveryPath, `nightshift(${programId}): ${workstream.id} integration recovery`, ["docs/programs"]);
+    if (recoveryCommit === undefined) {
+        return {
+            ok: false,
+            reason: `${firstReason}\n\nThe recovery attempt verified green but produced no change.`,
+            retainedRef: ref,
+            worktreePaths: [cwd, recoveryPath],
+            transcripts,
+        };
+    }
+    await git.createRef(root, ref, `refs/heads/${recoveryBranch}`);
+    const second = await attemptIntegration({
+        root,
+        programId,
+        workstreamId: workstream.id,
+        workstreamName: workstream.name,
+        cwd: recoveryPath,
+        branch: recoveryBranch,
+        finalCommit: recoveryCommit,
+        worktrees,
+        git,
+        config,
+        verifyRunner,
+        setupRunner,
+        ...(args.verifyCache ? { verifyCache: args.verifyCache } : {}),
+        scope,
+        log,
+        rootIndexMutex,
+        rosterTaskFiles,
+    });
+    if (second.ok) {
+        return { ok: true, ...(second.commit === undefined ? {} : { commit: second.commit }), transcripts, cleanup };
+    }
+    // Do not recurse — one bounded recovery attempt only (§3.6).
+    const secondReason = integrationFailureText(second, recoveryCommit);
+    return {
+        ok: false,
+        reason: `${firstReason}\n\nThe recovery attempt also failed to integrate: ${secondReason}\n\n` +
+            `The recovery's own verified commit is \`${recoveryCommit}\`, retained as \`${ref}\`.`,
+        retainedRef: ref,
+        worktreePaths: [cwd, recoveryPath],
+        transcripts,
+    };
+}
 /**
  * The decide-and-continue runner.
  *
@@ -525,8 +1142,67 @@ async function runProgramWith(options, permits) {
     const agentRunner = options.agentRunner ?? defaultAgentRunner;
     const verifyRunner = options.verifyRunner ?? defaultVerifyRunner;
     const git = options.git ?? defaultGitOps;
-    const log = options.log ?? ((line) => console.log(line));
+    // One cache per run (WS-09, SC-14): an identical tree — everything the
+    // verify commands can read except this program's own six bookkeeping
+    // files (§3.3.2) — is never verified twice. No global, no module state: a
+    // second `runProgram` in the same process gets its own cache.
+    const verifyCache = createVerifyCache({
+        git,
+        commands: config.verify,
+        exclude: runnerOwnedVerifyPaths(options.programId),
+    });
+    const worktrees = options.worktrees ?? defaultWorktreeOps;
+    // A separate default from `verifyRunner` on purpose (WS-02, §3.3): tests
+    // stub `verifyRunner` to always return green, and reusing it for the
+    // worktree install step would make a failed install look like a success.
+    const setupRunner = options.setupRunner ?? defaultVerifyRunner;
+    // Resolved once, inside the isRepository branch below, and read from every
+    // workstream flow via closure (WS-02) — undefined when this is not a git
+    // repository, where no worktree is ever created (§3.9).
+    let worktreeBase;
+    const baseLog = options.log ?? ((line) => console.log(line));
+    const log = baseLog;
     const now = options.now ?? (() => new Date());
+    const monotonic = options.monotonic ?? (() => performance.now());
+    // Read before anything durable happens (a plain read, safe before the
+    // could-not-start gate): a prior finalized artifact's run id becomes this
+    // run's `parentRunId`, so a resumed invocation carries explicit lineage
+    // instead of silently blending its elapsed time with a prior attempt
+    // (SC-14). Created here — before the gate — so pre-gate stages (preflight,
+    // baseline verification) can be buffered in memory; it stays disarmed,
+    // writing nothing durable, until `arm()` is called below.
+    const priorRunId = await readPriorRunId(root, options.programId);
+    const recorder = options.recorder ??
+        RunRecorder.create({
+            clock: { now, monotonic },
+            root,
+            programId: options.programId,
+            ...(priorRunId === undefined ? {} : { parentRunId: priorRunId }),
+            log,
+        });
+    // The run-level reference span (WS-01's own; the fourth reference span
+    // alongside the three named seams — see the WS-01/WS-02 emission-boundary
+    // decision). Opened here, at the very first monotonic tick this function
+    // can observe — before preflight, before baseline verification, before the
+    // could-not-start gate — so it covers the true run start, not merely the
+    // portion after arming. `span()` buffers in memory regardless of arm
+    // state, so a could-not-start throw before `arm()` simply discards it,
+    // same as every other pre-gate observation (SC-02). Its bucket is
+    // `unattributed` by construction — see STAGE_BUCKET's doc comment.
+    //
+    // It is deliberately never closed on the normal-completion path (see the
+    // `report-commit` span below for why): the reconciled numbers stop at the
+    // pre-render snapshot (SC-03, SC-14), but the run's true end is the report
+    // commit, and closing this span before the report is written and
+    // committed would stamp an end that has not happened — exactly the defect
+    // an earlier version of
+    // this design had, closing here and silently excluding the trailing write
+    // and commit from every span instead of from just this one. Leaving it
+    // open is not a special case for that fix: it is the same "true end not
+    // observed" semantics the schema already uses for a crashed run, applied
+    // honestly to the one boundary this recorder can never observe closing
+    // even on success.
+    const runSpan = recorder.span({ stage: "run" });
     let manifest;
     try {
         manifest = await loadManifest(root, options.programId);
@@ -613,7 +1289,7 @@ async function runProgramWith(options, permits) {
         // interrupted, whose own leftover work is exactly what a resume needs.
         // The runner's own artifacts under docs/programs/ are exempt: they are
         // output, not work in progress.
-        const dirty = (await git.dirtyPaths(root)).filter((path) => !path.replaceAll("\\", "/").startsWith("docs/programs/"));
+        const dirty = (await git.dirtyPaths(root)).filter((path) => !isRunnerOwnedArtifactPath(path));
         if (dirty.length > 0 && !resuming) {
             throw new CouldNotStartError(`The working tree has uncommitted changes the run would sweep into its commits:\n` +
                 dirty.map((path) => `  ${path}`).join("\n") +
@@ -622,7 +1298,7 @@ async function runProgramWith(options, permits) {
         // 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
+        // work onto the wrong branch. These refuse before the pipeline below
         // spawns the first agent; --force is the explicit escape hatch.
         if (!options.force) {
             const currentBranch = await git.currentBranch(root);
@@ -645,6 +1321,26 @@ async function runProgramWith(options, permits) {
                     `with \`${branchCommand}\`, or re-run with --force.`);
             }
         }
+        // Every worktree and per-workstream branch this program left behind —
+        // a crashed prior run, not only an ordinary resume — is reaped before
+        // anything else runs (WS-02, §3.7). Retained `refs/nightshift/…` commits
+        // are the forensic record a human needs to salvage a parked
+        // integration and are never touched here.
+        await reapProgramWorktrees(root, options.programId, worktrees, log, new Set(manifest.workstreams.filter((w) => w.status === "complete").map((w) => w.id)));
+        worktreeBase = await resolveWorktreeBase(root, options.worktreeBaseDir);
+        log(`worktrees: ${worktreeBase.base}` +
+            (worktreeBase.usedFallback ? " (OS-temp fallback — the sibling location was not writable)" : ""));
+        // A resumed run's own leftover work no longer sits in the root tree a
+        // workstream's build reads from — that tree is now a fresh worktree from
+        // the program-branch tip. Said once, plainly, rather than discovered
+        // later as "my edit vanished" (WS-02, §3.7).
+        if (resuming && dirty.length > 0) {
+            log("warning: the working tree has uncommitted change(s) that a " +
+                "worktree-isolated build will not see (it starts from the " +
+                "program-branch tip), and an integration may refuse if a " +
+                "workstream also touches the same path(s):\n" +
+                dirty.map((path) => `  ${path}`).join("\n"));
+        }
     }
     // HEAD as it stood before the run's first agent ran — the whole-program
     // review stage's fallback diff base (see resolveProgramDiffBase) when a
@@ -654,8 +1350,10 @@ async function runProgramWith(options, permits) {
     // The run's own identity — distinct from runStartCommit, which two
     // invocations can share (the same commit) or lack entirely (no
     // repository). Stamped on each `prerequisite-verified` ledger event so the
-    // ledger records which run verified a prerequisite.
-    const runId = now().toISOString();
+    // ledger records which run verified a prerequisite. Promoted from the
+    // recorder's identity (SC-14) rather than minted separately, so the ledger
+    // and the analytics artifact always carry the same run id.
+    const runId = recorder.runId;
     // Preflight: every *pending* prerequisite's verifyCommand executes here —
     // before baseline verification and before any agent spawns (SC-03). This
     // mutates manifest.prerequisites in memory (pending -> satisfied on a met
@@ -670,6 +1368,7 @@ async function runProgramWith(options, permits) {
         runId,
         runStartCommit,
         log,
+        recorder,
     });
     // Baseline verification: the verify suite on the untouched tree, before
     // the first agent is spawned. A red baseline on a fresh start means the
@@ -690,7 +1389,7 @@ async function runProgramWith(options, permits) {
     let baselineFingerprint;
     if (Object.keys(config.verify).length > 0) {
         log("baseline: running the verify commands on the untouched tree");
-        const baselineFailure = await verifyAttempt(config, verifyRunner, root, 0);
+        const baselineFailure = await verifyAttempt(config, verifyRunner, root, root, 0, recorder, "baseline-verification", { programId: options.programId, phase: "baseline", cache: verifyCache });
         if (baselineFailure === undefined) {
             log("baseline: clean");
         }
@@ -715,10 +1414,14 @@ async function runProgramWith(options, permits) {
     // makes the only crash-between-writes residue a harmless idempotent
     // duplicate event, never a lost one. A could-not-start throw above has
     // already unwound the process before reaching here, so an exit-3 run
-    // mutates neither the manifest nor the ledger.
+    // mutates neither the manifest nor the ledger — nor, from this line on, the
+    // analytics artifact: `arm()` enables the recorder's durable writes, so a
+    // could-not-start run leaves no working log and no finalized artifact
+    // (SC-02).
+    recorder.arm();
     if (preflight.events.length > 0) {
-        await appendLedgerEvents(root, options.programId, preflight.events);
-        await saveManifest(root, options.programId, manifest, { log });
+        await timed(recorder, { stage: "ledger-persist" }, () => appendLedgerEvents(root, options.programId, preflight.events));
+        await timed(recorder, { stage: "manifest-persist" }, () => saveManifest(root, options.programId, manifest, { log }));
     }
     // Subject ids already sent to the decider this run — shared across the
     // authoring and build stages (a run is one process) and across the
@@ -732,671 +1435,1166 @@ async function runProgramWith(options, permits) {
     // 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
-    // discovered dependency edges or parked workstreams it could not author.
-    const authorResult = await authorProgram({
-        cwd: options.cwd,
-        programId: options.programId,
-        config,
-        agentRunner,
-        permits,
-        git,
-        log,
-        now,
-        reviewed,
-        triaged,
-    });
-    manifest = await loadManifest(root, options.programId);
-    // Loaded once so every brief in this run projects the same picture of
-    // human-decided and ratified choices; decisions this run itself journals
-    // are picked up fresh by `readDecisionLedger` at the end, for escalations.
-    const ledgerAtStart = await readDecisionLedger(root, options.programId);
-    const ordered = stableTopologicalOrder(manifest.workstreams);
-    const results = [];
-    // Every workstream whose spec authoring failed or parked. Seeds `blocked`
-    // below (their briefs would be missing a producer's spec) and also guards
-    // the awaiting_human branch in the build loop: an authoring failure must
-    // never be repainted as a planned wait — see that branch's own comment.
-    const authoringFailed = new Set(authorResult.results
-        .filter((entry) => entry.outcome.status === "failed" || entry.outcome.status === "parked")
-        .map((entry) => entry.id));
-    const blocked = new Set(authoringFailed);
-    // The awaiting cone: every workstream directly referencing an unmet
-    // prerequisite, plus everything transitively downstream of one — the same
-    // downstream-cone machinery failure isolation uses, with the semantics
-    // inverted (no agent spawned, no retry, no diagnosis; see the build loop).
-    const unmetPrerequisiteIds = new Set(preflight.checks.filter((check) => !check.met).map((check) => check.id));
-    const directlyAwaiting = new Set(manifest.workstreams
-        .filter((workstream) => workstream.prerequisites.some((id) => unmetPrerequisiteIds.has(id)))
-        .map((workstream) => workstream.id));
-    const awaitingCone = new Set([
-        ...directlyAwaiting,
-        ...downstreamCone(manifest.workstreams, [...directlyAwaiting]),
-    ]);
-    // Set when a workstream's verify failure reproduced the pre-run baseline:
-    // the environment is broken, so every remaining workstream parks instead
-    // of spending its budget on the same crash.
-    let environmentalHalt = false;
-    for (const workstream of ordered) {
-        if (workstream.status === "complete") {
-            results.push({
-                id: workstream.id,
-                name: workstream.name,
-                outcome: { status: "skipped", reason: "already complete" },
-                decisionIds: [],
-                decisionErrors: [],
-            });
-            continue;
-        }
-        if (environmentalHalt) {
-            workstream.status = "parked";
-            results.push({
-                id: workstream.id,
-                name: workstream.name,
-                outcome: {
-                    status: "parked",
-                    reason: "the run halted on an environmental verification failure; parked, not attempted",
-                },
-                decisionIds: [],
-                decisionErrors: [],
-            });
-            continue;
-        }
-        // Authoring failures take precedence over awaiting: a workstream whose
-        // spec authoring failed or parked must fall through to the `blocked`
-        // branch below and render as the genuine failure it is, never be
-        // repainted `awaiting_human` — an authoring failure has no other
-        // representation in `results` than that branch's own `parked` result, so
-        // rewriting it here would erase the only trace of it and the run would
-        // wrongly look like a pure intermission. A workstream that is merely
-        // downstream of a *build* failure and also in the awaiting cone still
-        // resolves to awaiting_human here; that is safe because the build
-        // failure self-reports `failed` in `results`, so the run is classified a
-        // partial regardless (see the intermission classification below).
-        if (awaitingCone.has(workstream.id) && !authoringFailed.has(workstream.id)) {
-            workstream.status = "awaiting_human";
-            await saveManifest(root, options.programId, manifest, { log });
-            const ownUnmet = workstream.prerequisites.filter((id) => unmetPrerequisiteIds.has(id));
-            const reason = ownUnmet.length > 0
-                ? `waiting on human prerequisite ${ownUnmet.join(", ")}; not attempted.`
-                : "an upstream workstream is awaiting a human prerequisite; not attempted.";
-            results.push({
-                id: workstream.id,
-                name: workstream.name,
-                outcome: { status: "awaiting_human", reason },
-                decisionIds: [],
-                decisionErrors: [],
-            });
-            continue;
-        }
-        if (blocked.has(workstream.id)) {
-            workstream.status = "parked";
-            results.push({
-                id: workstream.id,
-                name: workstream.name,
-                outcome: {
-                    status: "parked",
-                    reason: "an upstream dependency failed; parked, not attempted",
-                },
-                decisionIds: [],
-                decisionErrors: [],
-            });
-            continue;
-        }
-        const result = await runWorkstream(workstream);
-        results.push(result);
-        if (result.environmental === true)
-            environmentalHalt = true;
-        if (result.outcome.status === "failed") {
-            // Failure isolation: park the downstream cone, keep building the rest.
-            for (const id of downstreamCone(manifest.workstreams, [workstream.id])) {
-                blocked.add(id);
-            }
-        }
-    }
-    const complete = results.every((result) => result.outcome.status === "complete" ||
-        result.outcome.status === "skipped");
-    const anyAwaiting = results.some((result) => result.outcome.status === "awaiting_human");
-    const anyFailedOrParked = results.some((result) => result.outcome.status === "failed" || result.outcome.status === "parked");
-    // Author-stage failures are counted too: an authoring failure the awaiting
-    // guard did NOT catch — e.g. a workstream that authored fine but sits
-    // downstream of an authoring failure — must still sink the intermission.
-    // Same set that seeded `blocked`/guarded the awaiting branch above;
-    // classifying on it here as well makes "any genuine failure => ordinary
-    // partial" true independent of how the cone painted it.
-    const anyAuthoringFailure = authorResult.results.some((entry) => entry.outcome.status === "failed" || entry.outcome.status === "parked");
-    // A planned intermission: nothing failed anywhere (build or authoring), at
-    // least one workstream is waiting on a human, and not everything built. A
-    // genuine failure makes it an ordinary partial instead — the human should
-    // read a diagnosis, not a checklist.
-    const intermission = !complete && anyAwaiting && !anyFailedOrParked && !anyAuthoringFailure;
-    manifest.program.status = complete
-        ? "complete"
-        : intermission
-            ? "awaiting_human"
-            : "partial";
-    await saveManifest(root, options.programId, manifest, { log });
-    const wholeProgram = await runWholeProgramStage({
-        root,
-        programId: options.programId,
-        manifest,
-        config,
-        agentRunner,
-        permits,
-        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);
-    // 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.
+    // Everything from here through the run's return is wrapped in one more
+    // level of function nesting so a thrown crash still finalizes the
+    // analytics artifact before control leaves (SC-02) without pulling any of
+    // this region's locals out of scope of the stage functions declared after
+    // its `return` (they are hoisted declarations inside `runProgramBody`,
+    // exactly as they were inside `runProgramWith` before this wrapping).
+    // `finalize()` is fail-open and cannot itself throw or mask the original
+    // error. On the normal path the artifact is finalized explicitly, below,
+    // before the report is written and committed, so it rides into the same
+    // `docs/programs` commit as the report; this catch exists only for the
+    // crash path.
     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, preflight, options.resumeCommand, manifestMergeCount(root, options.programId) > mergesAtStart), "utf8");
-        if (isRepository) {
-            await git.commitPaths(root, `nightshift(${options.programId}): run report and decision ledger`, ["docs/programs"]);
-        }
+        return await runProgramBody();
     }
     catch (error) {
-        log(`run report: could not write or commit ${reportPath}: ${error.message}`);
+        const finalizeStart = monotonic();
+        await recorder.finalize();
+        recorder.point({
+            kind: "analytics-overhead",
+            coverage: "observed",
+            value: monotonic() - finalizeStart,
+            unit: "ms",
+            label: "finalize",
+        });
+        throw error;
     }
-    log(`run report: ${reportPath}`);
-    return {
-        programId: options.programId,
-        complete,
-        intermission,
-        workstreams: results,
-        escalations,
-        reportPath,
-        wholeProgramReview: wholeProgram,
-    };
-    async function runWorkstream(workstream) {
-        const base = {
-            id: workstream.id,
-            name: workstream.name,
-            outcome: { status: "failed", reason: "not attempted" },
-            decisionIds: [],
-            decisionErrors: [],
-            buildAgentCommand: describeAgent(agent),
-        };
-        /** Every build-role spawn's transcript, for the report's per-workstream
-         *  Commands subsection (WS-02). Reviewer/decider spawns are excluded. */
-        function recordTranscript(transcript) {
-            if (transcript)
-                (base.transcripts ??= []).push(transcript);
-        }
-        /** Names the JSONL file under build-logs/<programId>/, distinctly per spawn label. */
-        function transcriptSink(label) {
-            return { root, programId: options.programId, label: `${workstream.id}-${label}`, log };
-        }
-        let spec;
-        try {
-            spec = await readFile(join(root, workstream.taskFile), "utf8");
+    async function runProgramBody() {
+        // WS-05 §3.7: the total lock order for this whole run. `integrationMutex`
+        // (WS-04's, unchanged) is held across a whole integration attempt,
+        // including its re-verify pass, deliberately for minutes at a time.
+        // `rootIndexMutex` (new) is held only for the git-index operations at
+        // `root`: authoring's spec commits (inside `prepareAuthoring`), an
+        // integration's step-3 tip re-resolve and squash (§3.7.1), and the final
+        // report commit below. Beneath both sits the WS-01 write queue
+        // (`enqueueProgramWrite`). Never taken in any other order, and never
+        // nested with `src/author.ts`'s own `graphMutex` (its merge critical
+        // section), which takes no git operation at all.
+        const integrationMutex = createMutex();
+        const rootIndexMutex = createMutex();
+        // WS-05 §3.1: one dependency graph with two kinds of node instead of a
+        // barrier between two loops. `prepareAuthoring` throws for exactly the
+        // reasons `authorProgram` threw before this workstream — no author agent
+        // configured, a cyclic manifest, an unknown `--from` id — and does so
+        // before any agent spawns. The manifest object is this run's single
+        // shared one (§3.4): authoring mutates and persists *this* object, so the
+        // build scheduler sees a discovered dependency edge or a `specStatus`
+        // transition the instant an author makes it, and no post-authoring reload
+        // is needed or performed.
+        const pipeline = await prepareAuthoring({
+            cwd: options.cwd,
+            programId: options.programId,
+            config,
+            agentRunner,
+            permits,
+            git,
+            log,
+            now,
+            reviewed,
+            triaged,
+            recorder,
+            runSpan,
+            monotonic,
+            manifest,
+            rootIndexMutex,
+            ...(options.maxParallel === undefined ? {} : { maxParallel: options.maxParallel }),
+        });
+        // Every workstream's `taskFile` — one of the two path shapes a concurrent
+        // authoring commit may safely have touched while an integration was in
+        // flight (§3.7.1); fixed for the whole run, since only `dependencies`
+        // mutate during authoring, never a workstream's own `taskFile`.
+        const rosterTaskFiles = new Set(manifest.workstreams.map((workstream) => workstream.taskFile));
+        const rosterIds = new Set(manifest.workstreams.map((workstream) => workstream.id));
+        // The awaiting cone: every workstream directly referencing an unmet
+        // prerequisite, plus everything transitively downstream of one — the same
+        // downstream-cone machinery failure isolation uses, with the semantics
+        // inverted (no agent spawned, no retry, no diagnosis; see `dispositionOf`).
+        // `directlyAwaiting` is fixed for the run (authoring never mutates
+        // `prerequisites`); its downstream cone is recomputed live on every call
+        // (§3.5) — a dependency edge an author discovers mid-run can still route a
+        // workstream into this cone after the run started.
+        const unmetPrerequisiteIds = new Set(preflight.checks.filter((check) => !check.met).map((check) => check.id));
+        const directlyAwaiting = new Set(manifest.workstreams
+            .filter((workstream) => workstream.prerequisites.some((id) => unmetPrerequisiteIds.has(id)))
+            .map((workstream) => workstream.id));
+        function isAwaiting(id) {
+            return (directlyAwaiting.has(id) ||
+                downstreamCone(manifest.workstreams, [...directlyAwaiting]).has(id));
         }
-        catch {
-            base.outcome = {
-                status: "parked",
-                reason: `spec not found at ${workstream.taskFile}`,
-            };
-            return base;
+        // Every workstream whose spec authoring failed or parked, and every
+        // workstream whose *build* failed — grown live as author and build items
+        // settle (§3.5), never frozen at a barrier that no longer exists.
+        // `isBlocked` recomputes the downstream cone of both sets on every call:
+        // by the time `build:X` is admissible, every ancestor's `author` item
+        // *and* `build` item has already settled (`build:X` depends on `build:D`
+        // for every roster dependency `D`, which itself depends on `author:D`), so
+        // the live sets contain everything that could possibly block `X` at that
+        // instant — the correctness lemma this replaces WS-04's frozen `blocked`
+        // set with.
+        const authoringFailed = new Set();
+        const buildFailed = new Set();
+        function isBlocked(id) {
+            return (authoringFailed.has(id) ||
+                downstreamCone(manifest.workstreams, [...authoringFailed, ...buildFailed]).has(id));
         }
-        workstream.status = "in_progress";
-        await saveManifest(root, options.programId, manifest, { log });
-        const baseCommit = isRepository
-            ? await git.currentCommit(root)
-            : undefined;
-        let priorFailure;
-        let priorDiagnosis;
-        let implementerFingerprint;
-        const attempts = [
-            { agent, label: "implementer", role: "agent" },
-        ];
-        if (recovery && !recovery.borrowedImplementer) {
-            attempts.push({ agent: recovery.agent, label: "recovery", role: "recoveryAgent" });
-            // 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", role: "agent" });
-        }
-        for (const [index, attempt] of attempts.entries()) {
-            log(`${workstream.id} ${workstream.name}: ${attempt.label} attempt`);
-            const brief = implementerBrief(manifest, workstream, spec, ledgerAtStart, config.permits?.policy, priorFailure, priorDiagnosis);
-            let invocation;
-            let spawnFailure;
-            try {
-                invocation = await invokeAgent(agentRunner, attempt.agent, brief, root, permits, attempt.role, transcriptSink(attempt.label.replaceAll(" ", "-")));
-            }
-            catch (error) {
-                // The agent process never started — its command is wrong, missing,
-                // or unrunnable. Nothing was built; this is the captured
-                // silent-exit incident (SC-12). Make it a diagnosed failure via the
-                // existing retry/park machinery below, never a process exit.
-                spawnFailure =
-                    `the ${attempt.label} agent could not be spawned: ` +
-                        `${error.message}. The configured command ` +
-                        `\`${describeAgent(attempt.agent)}\` did not start, so nothing was built.`;
-                invocation = { exitCode: 1, output: "" };
-            }
-            recordTranscript(invocation.transcript);
-            const summary = resolveSummary(invocation.output);
-            base.summary = summary.text;
-            await journalDenials(workstream.id, attempt.label, invocation.transcript, summary.needsPermission);
-            const parsed = extractDecisions(invocation.output);
-            base.decisionErrors.push(...parsed.errors);
-            await journalDecisions(workstream, parsed.decisions, baseCommit);
-            base.decisionIds = parsed.decisions.map((decision) => decisionFingerprint(workstream.id, decision));
-            let failure = await verifyAttempt(config, verifyRunner, root, invocation.exitCode);
-            // Deterministic protocol failures the runner can see without a model:
-            // no diagnosis is spent on them, because no read of the tree could add
-            // anything to what the runner already knows.
-            let deterministicFailure = false;
-            // A spawn failure takes precedence over whatever verifyAttempt saw
-            // (the untouched tree can verify green on its own) — no reviewer
-            // diagnosis is spent reading an empty diff.
-            if (spawnFailure !== undefined) {
-                failure = spawnFailure;
-                deterministicFailure = true;
-            }
-            // A brief that never reached the agent's stdin means the process
-            // crashed at startup — whatever it printed was not an answer to the
-            // brief, even when it exited 0.
-            if (failure === undefined && invocation.inputError !== undefined) {
-                failure =
-                    `the brief could not be delivered to the agent's stdin ` +
-                        `(${invocation.inputError}) — the agent likely crashed at startup, ` +
-                        `so its reply answered nothing.`;
-                deterministicFailure = true;
-            }
-            // A green verify over an unchanged tree is just the baseline passing
-            // again, not built work. Without this, an agent that crashes at
-            // startup while exiting 0 (or replies without working) sweeps only
-            // the runner's own in_progress manifest write into a metadata-only
-            // commit and walks through the gate as "complete". A reply that never
-            // produces the work is a protocol failure, not an empty result.
-            if (failure === undefined && isRepository) {
-                const dirty = await git.dirtyPaths(root);
-                const meaningful = dirty.some((path) => !path.replaceAll("\\", "/").startsWith("docs/programs/"));
-                if (!meaningful) {
-                    failure =
-                        "the attempt verified green but changed nothing outside " +
-                            "docs/programs/ — nothing was built, and the passing verify was " +
-                            "the untouched baseline. A no-op attempt is a protocol failure " +
-                            "(the agent may have crashed at startup or replied without " +
-                            "working), not a completed workstream.";
-                    deterministicFailure = true;
-                }
+        // Set when a workstream's verify failure reproduced the pre-run baseline:
+        // the environment is broken, so every remaining workstream parks instead
+        // of spending its budget on the same crash — in *both* phases (§3.6):
+        // in-flight authoring finishes and commits its spec, in-flight builds
+        // finish and integrate, but no not-yet-dispatched author or build
+        // launches. Mutated only from the scheduler's `launchBuild`, after a
+        // result is in hand — the same place today's serial loop mutated it.
+        let environmentalHalt = false;
+        /**
+         * WS-04's five-branch cascade (minus the `runWorkstream` branch, which is
+         * the absence of a short-circuit), extracted so the scheduler's `classify`
+         * can consult it on every pass without re-implementing it. Precedence is
+         * load-bearing and unchanged: complete, then environmental halt, then
+         * awaiting (guarded against repainting an authoring failure), then
+         * blocked. Evaluated at dispatch time, when every dependency's `build`
+         * item has already settled (admissibility requires it), so `isBlocked` is
+         * as authoritative here as it was over WS-04's frozen `blocked` set
+         * (WS-05 §3.5).
+         */
+        function dispositionOf(workstream) {
+            if (workstream.status === "complete") {
+                return {
+                    kind: "short-circuit",
+                    outcome: { status: "skipped", reason: "already complete" },
+                    persist: false,
+                };
             }
-            if (failure === undefined) {
-                let c0;
-                if (isRepository) {
-                    // Unlike the authoring, run-report, and replay commits, this one
-                    // stays a whole-tree sweep: an implementing agent touches whatever
-                    // files the work required, and that set is exactly what the
-                    // runner cannot know in advance. c0 is the green anchor the test
-                    // critique's fix loop resets to on a failing fix (SC-07).
-                    c0 = await git.commitAll(root, `nightshift(${options.programId}): ${workstream.id} ${workstream.name}`);
-                }
-                const critique = isRepository && c0 !== undefined
-                    ? await runTestCritique({
-                        root,
-                        manifest,
-                        workstream,
-                        spec,
-                        config,
-                        agentRunner,
-                        permits,
-                        verifyRunner,
-                        git,
-                        reviewer,
-                        agent,
-                        baseCommit,
-                        greenCommit: c0,
-                        now,
-                        log,
-                        transcriptSink,
-                    })
-                    : undefined;
-                // 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.
-                let finalCommit = critique?.finalCommit ?? c0;
-                if (critique && critique.stageErrors.length > 0) {
-                    (base.stageErrors ??= []).push(...critique.stageErrors);
-                }
-                for (const transcript of critique?.transcripts ?? [])
-                    recordTranscript(transcript);
-                // 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 ?? []).filter(hasRoutableEvidence),
-                    ...(c0 === undefined ? {} : { baseCommit: c0 }),
-                    now,
-                });
-                await appendLedgerEvents(root, options.programId, findingEvents);
-                // 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
-                // that last touched it, so this lag is harmless.
-                workstream.status = "complete";
-                if (finalCommit !== undefined)
-                    workstream.commit = finalCommit;
-                await saveManifest(root, options.programId, manifest, { log });
-                {
-                    const spawnErrors = await reviewWorkstreamDecisions(workstream.id, parsed.decisions, baseCommit);
-                    if (spawnErrors.length > 0)
-                        (base.stageErrors ??= []).push(...spawnErrors);
-                }
-                // 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.
-                {
-                    const spawnErrors = await reviewWorkstreamFindings(workstream.id, findingEvents, baseCommit);
-                    if (spawnErrors.length > 0)
-                        (base.stageErrors ??= []).push(...spawnErrors);
-                }
-                // 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, transcriptSink("fix-now-fix"));
-                    recordTranscript(driven.transcript);
-                    if (driven.spawnError !== undefined) {
-                        (base.stageErrors ??= []).push(driven.spawnError);
-                    }
-                    if (driven.commit !== finalCommit) {
-                        finalCommit = driven.commit;
-                        workstream.commit = finalCommit;
-                        await saveManifest(root, options.programId, manifest, { log });
-                    }
-                }
-                if (critique)
-                    base.testCritique = critique.outcome;
-                base.testCritiqueDiffClipped = critique?.diffClipped ?? false;
-                base.outcome = {
-                    status: "complete",
-                    ...(finalCommit === undefined ? {} : { commit: finalCommit }),
+            if (environmentalHalt) {
+                return {
+                    kind: "short-circuit",
+                    status: "parked",
+                    outcome: {
+                        status: "parked",
+                        reason: "the run halted on an environmental verification failure; parked, not attempted",
+                    },
+                    persist: false,
                 };
-                return base;
             }
-            priorFailure = failure;
-            log(`${workstream.id}: ${attempt.label} attempt failed — ${failure}`);
-            // A failure identical to the pre-run baseline (up to counts and
-            // timings) was there before any workstream ran: environmental, not
-            // this workstream's work. No retry or diagnosis is spent on it, and
-            // the caller halts the run — every later workstream would be charged
-            // for the same broken environment. Workstreams resumed with their own
-            // leftover failure in the tree are exempt (see resumedIds).
-            if (baselineFingerprint !== undefined &&
-                !resumedIds.has(workstream.id) &&
-                failureFingerprint(failure) === baselineFingerprint) {
-                workstream.status = "failed";
-                await saveManifest(root, options.programId, manifest, { log });
-                {
-                    const spawnErrors = await reviewWorkstreamDecisions(workstream.id, parsed.decisions, baseCommit);
-                    if (spawnErrors.length > 0)
-                        (base.stageErrors ??= []).push(...spawnErrors);
-                }
-                base.environmental = true;
-                base.outcome = {
-                    status: "failed",
-                    reason: failure +
-                        "\n\nThis failure is identical (up to counts and timings) to the " +
-                        "verification failure recorded on the untouched tree before the " +
-                        "run began — the environment was broken before this workstream " +
-                        "ran. No retry was spent, and the run halted here.",
+            // Authoring failures take precedence over awaiting: a workstream whose
+            // spec authoring failed or parked must fall through to the `isBlocked`
+            // branch below and render as the genuine failure it is, never be
+            // repainted `awaiting_human` — an authoring failure has no other
+            // representation in `results` than that branch's own `parked` result, so
+            // rewriting it here would erase the only trace of it and the run would
+            // wrongly look like a pure intermission. A workstream that is merely
+            // downstream of a *build* failure and also in the awaiting cone still
+            // resolves to awaiting_human here; that is safe because the build
+            // failure self-reports `failed` in `results`, so the run is classified a
+            // partial regardless (see the intermission classification below).
+            if (isAwaiting(workstream.id) && !authoringFailed.has(workstream.id)) {
+                const ownUnmet = workstream.prerequisites.filter((id) => unmetPrerequisiteIds.has(id));
+                const reason = ownUnmet.length > 0
+                    ? `waiting on human prerequisite ${ownUnmet.join(", ")}; not attempted.`
+                    : "an upstream workstream is awaiting a human prerequisite; not attempted.";
+                return {
+                    kind: "short-circuit",
+                    status: "awaiting_human",
+                    outcome: { status: "awaiting_human", reason },
+                    persist: true,
                 };
-                return base;
             }
-            // 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, { log });
-                // The work stays in the tree for a resume; decisions made on the way
-                // to a failure are still journaled and still reviewable.
-                {
-                    const spawnErrors = await reviewWorkstreamDecisions(workstream.id, parsed.decisions, baseCommit);
-                    if (spawnErrors.length > 0)
-                        (base.stageErrors ??= []).push(...spawnErrors);
-                }
-                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,
+            if (isBlocked(workstream.id)) {
+                return {
+                    kind: "short-circuit",
+                    status: "parked",
+                    outcome: {
+                        status: "parked",
+                        reason: "an upstream dependency failed; parked, not attempted",
+                    },
+                    persist: false,
                 };
-                return base;
             }
-            if (attempt.label === "implementer") {
-                implementerFingerprint = failureFingerprint(failure);
+            return { kind: "build" };
+        }
+        // `classify` and `settle` are two separate scheduler calls, and `settle`
+        // runs on a later microtask — a naive `settle` that recomputes
+        // `dispositionOf` could observe a different answer than the one that sent
+        // it there (a sibling can flip `environmentalHalt` in between). Memoising
+        // the dispatching pass's answer and having `settle` read it back avoids
+        // the hazard entirely rather than reasoning about it (WS-04, §3.2).
+        const dispositionCache = new Map();
+        function dispositionFor(workstream) {
+            const fresh = dispositionOf(workstream);
+            dispositionCache.set(workstream.id, fresh);
+            return fresh;
+        }
+        async function applyShortCircuit(workstream) {
+            const disposition = dispositionCache.get(workstream.id);
+            if (disposition === undefined || disposition.kind !== "short-circuit") {
+                // Unreachable: the scheduler only calls `settle` for an item whose
+                // `classify` call (via `dispositionFor`) just returned "settle".
+                throw new Error(`applyShortCircuit called for ${workstream.id} without a cached short-circuit disposition`);
             }
-            // 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. Deterministic failures (no-op, undelivered brief) are
-            // never diagnosed: the runner already knows exactly what happened,
-            // and a reviewer read of an empty diff could only muddy it.
-            if (reviewer && !deterministicFailure) {
-                const diagnosed = await diagnoseFailure({
-                    root,
-                    manifest,
-                    workstream,
-                    spec,
-                    agentRunner,
-                    permits,
-                    reviewer,
-                    git,
-                    baseCommit,
-                    failure,
-                    observe: transcriptSink(`diagnose-${attempt.label.replaceAll(" ", "-")}`),
-                });
-                priorDiagnosis = diagnosed.diagnosis;
-                if (diagnosed.spawnError !== undefined) {
-                    (base.stageErrors ??= []).push(diagnosed.spawnError);
-                    log(`${workstream.id}: ${diagnosed.spawnError}`);
-                }
-                await journalDenials(workstream.id, "reviewer", diagnosed.transcript);
+            if (disposition.status !== undefined)
+                workstream.status = disposition.status;
+            if (disposition.persist) {
+                await timed(recorder, { stage: "manifest-persist" }, () => saveManifest(root, options.programId, manifest, { log }));
             }
-            else {
-                priorDiagnosis = undefined;
+            return {
+                id: workstream.id,
+                name: workstream.name,
+                outcome: disposition.outcome,
+                decisionIds: [],
+                decisionErrors: [],
+            };
+        }
+        const byId = new Map();
+        const cap = normalizeMaxParallel(options.maxParallel);
+        const schedLog = schedulerLog(baseLog);
+        schedLog(`pipelining authoring and building over ${manifest.workstreams.length} workstream(s)` +
+            (cap === Infinity ? "" : `, at most ${cap} flow(s) at a time`));
+        const authorItems = manifest.workstreams.map((workstream) => ({
+            id: `author:${workstream.id}`,
+            phase: "author",
+            workstream,
+            get dependencies() {
+                return workstream.dependencies.map((id) => `author:${id}`);
+            },
+        }));
+        const buildItems = manifest.workstreams.map((workstream) => ({
+            id: `build:${workstream.id}`,
+            phase: "build",
+            workstream,
+            get dependencies() {
+                return [`author:${workstream.id}`, ...workstream.dependencies.map((id) => `build:${id}`)];
+            },
+        }));
+        // Authors first, then builds, both in manifest order (§3.1): `runReadySet`
+        // breaks ties by this input order, so at `cap: 1` every author drains
+        // before any build is even considered — the pipeline rebuilds today's
+        // barrier exactly rather than approximating it (§3.10).
+        const items = [...authorItems, ...buildItems];
+        // Settle instants, keyed by phased-item id, for the `spec-pending` wait
+        // measurement below (§3.8); the scheduler does not expose these itself.
+        const settledAt = new Map();
+        const schedulerStart = monotonic();
+        async function launchAuthor(item) {
+            const result = await pipeline.authorWorkstream(item.workstream);
+            settledAt.set(item.id, monotonic());
+            if (result.outcome.status === "failed" || result.outcome.status === "parked") {
+                authoringFailed.add(item.workstream.id);
             }
-            if (priorDiagnosis !== undefined) {
-                (base.failureDiagnoses ??= []).push({
-                    attempt: attempt.label,
-                    verdict: priorDiagnosis,
-                });
-                log(`${workstream.id}: reviewer diagnosed the ${attempt.label} failure`);
+        }
+        // The only path by which an author item settles without running (§3.6): a
+        // halt-parked author never ran, so `specStatus` is left exactly as it
+        // stood, and it does not enter `authoringFailed` — a downstream workstream
+        // reports the halt reason, never "an upstream dependency's authoring
+        // failed".
+        async function settleHaltedAuthor(item) {
+            pipeline.haltAuthorWorkstream(item.workstream, "the run halted on an environmental verification failure; parked, not attempted");
+            settledAt.set(item.id, monotonic());
+        }
+        async function settleBuild(item) {
+            byId.set(item.workstream.id, await applyShortCircuit(item.workstream));
+            settledAt.set(item.id, monotonic());
+        }
+        async function launchBuild(item) {
+            const workstream = item.workstream;
+            // The scheduling instant (WS-04, §3.5): resolved first, with no
+            // `await` between the read and the `workstream-scheduled` emission, so
+            // no sibling can integrate in between — the point and the sha
+            // therefore describe the same instant by construction. The per-flow
+            // ledger read (§3.4) goes strictly after this emission, and nothing
+            // else is inserted between them, so WS-04's
+            // `scheduled − ready === concurrency-cap` identity stays exact.
+            const scheduledFrom = isRepository
+                ? await worktrees.resolveCommit(root, "HEAD")
+                : undefined;
+            recordWorkstreamScheduled(recorder, workstream.id);
+            const ledger = await readDecisionLedger(root, options.programId);
+            const result = await runWorkstream(workstream, ledger, scheduledFrom === undefined ? {} : { scheduledFrom });
+            byId.set(workstream.id, result);
+            settledAt.set(item.id, monotonic());
+            if (result.environmental === true && !environmentalHalt) {
+                environmentalHalt = true;
+                schedLog("environmental verification failure — halting further dispatch");
+                schedLog("[run] the halt stops dispatch in both phases — in-flight authoring finishes " +
+                    "and commits its spec, in-flight builds finish and integrate, and every " +
+                    "not-yet-dispatched author or build parks with the halt reason");
+            }
+            if (result.outcome.status === "failed" || result.outcome.status === "parked") {
+                // A parked build (no spec on disk) leaves its dependents without a
+                // producer just as a failure does; both seed the downstream cone.
+                buildFailed.add(workstream.id);
             }
         }
-        return base;
-    }
-    async function journalDecisions(workstream, decisions, baseCommit) {
-        const events = decisions.map((decision) => ({
-            kind: "decision-recorded",
-            at: now().toISOString(),
-            id: decisionFingerprint(workstream.id, decision),
-            workstream: workstream.id,
-            decision,
-            ...(baseCommit === undefined ? {} : { baseCommit }),
-            decidedBy: "implementer",
-        }));
-        await appendLedgerEvents(root, options.programId, events);
-        for (const decision of decisions) {
-            log(`${workstream.id} decision: ${decision.title} -> ${decision.chosen}`);
-        }
-    }
-    /**
-     * Journals `permission-denied` events for one spawn (WS-03) — every
-     * workstream-attributed spawn calls this once, passing its own transcript
-     * and (for build roles only) the agent's `needsPermission` self-reports.
-     * A no-op when the spawn produced neither.
-     */
-    async function journalDenials(workstreamId, attempt, transcript, needsPermission = []) {
-        const events = buildDenialEvents(workstreamId, attempt, transcript?.denials ?? [], needsPermission, config.permits?.deny ?? [], now().toISOString());
-        if (events.length === 0)
-            return;
-        await appendLedgerEvents(root, options.programId, events);
-        for (const event of events) {
-            if (event.kind !== "permission-denied")
+        /** Emits `spec-pending` (§3.8): the wait between when this workstream's
+         *  build *could* have become ready — the latest settle of any roster
+         *  dependency's build item, or the scheduler's start when it has none —
+         *  and the instant it actually did. Authors emit no `workstream-ready`;
+         *  that point means "a build is ready" and must stay unique per
+         *  workstream. */
+        function onBuildReady(item) {
+            const readyAt = monotonic();
+            const depsReadyAt = item.workstream.dependencies
+                .filter((id) => rosterIds.has(id))
+                .reduce((latest, id) => Math.max(latest, settledAt.get(`build:${id}`) ?? schedulerStart), schedulerStart);
+            recordWorkstreamReady(recorder, item.workstream.id);
+            const waited = readyAt - depsReadyAt;
+            if (waited > 0) {
+                recordWorkstreamWaiting(recorder, item.workstream.id, { cause: "spec-pending", waitedMs: waited });
+            }
+        }
+        /** Emits `author-concurrency-cap` (§3.8) — the authoring half of the
+         *  shared `--max-parallel` budget, distinct from `concurrency-cap` so
+         *  per-(workstream, cause) uniqueness and WS-04's
+         *  `scheduled − ready === concurrency-cap` identity both stay exact. */
+        function onAuthorLaunch(item, cappedMs) {
+            if (cappedMs > 0) {
+                recordWorkstreamWaiting(recorder, item.workstream.id, {
+                    cause: "author-concurrency-cap",
+                    waitedMs: cappedMs,
+                });
+            }
+        }
+        await runReadySet({
+            items,
+            cap,
+            monotonic,
+            classify: (item) => item.phase === "author"
+                // The one short-circuit an author item has: the environmental halt
+                // (§3.6). Authoring has no other short-circuit — the cone parks are
+                // WS-03's own, inside `handle`.
+                ? environmentalHalt
+                    ? "settle"
+                    : "launch"
+                : dispositionFor(item.workstream).kind === "build"
+                    ? "launch"
+                    : "settle",
+            launch: (item) => (item.phase === "author" ? launchAuthor(item) : launchBuild(item)),
+            settle: (item) => (item.phase === "author" ? settleHaltedAuthor(item) : settleBuild(item)),
+            onAdmissible: (item) => {
+                if (item.phase === "build")
+                    onBuildReady(item);
+            },
+            onLaunch: (item, cappedMs) => {
+                if (item.phase === "author") {
+                    onAuthorLaunch(item, cappedMs);
+                }
+                else if (cappedMs > 0) {
+                    recordWorkstreamWaiting(recorder, item.workstream.id, { cause: "concurrency-cap", waitedMs: cappedMs });
+                }
+            },
+        });
+        const authorResult = pipeline.finish();
+        // Wall-clock completion order is not deterministic; `ordered` is.
+        // Computed only now, after the drain (WS-05 §3.9) — never before it, since
+        // an author discovering a dependency mid-run can still change the graph
+        // this walks. Rebuilding `results` from it is what keeps every existing
+        // positional assertion (`results[0]`, `results[1]`, …) green under an
+        // unbounded default. `runReadySet`'s settle-in-`finally` makes a missing
+        // id impossible; filtered defensively anyway per SC-12's fail-open rule.
+        const ordered = stableTopologicalOrder(manifest.workstreams);
+        const results = [];
+        for (const workstream of ordered) {
+            const result = byId.get(workstream.id);
+            if (result === undefined) {
+                schedLog(`warning: ${workstream.id} produced no result — omitted from the report`);
                 continue;
-            log(`${workstreamId} ${attempt}: denied \`${event.command}\` (${event.source})`);
+            }
+            results.push(result);
         }
-    }
-    function reviewWorkstreamDecisions(workstreamId, decisions, baseCommit) {
-        return reviewDecisions({
+        const complete = results.every((result) => result.outcome.status === "complete" ||
+            result.outcome.status === "skipped");
+        const anyAwaiting = results.some((result) => result.outcome.status === "awaiting_human");
+        const anyFailedOrParked = results.some((result) => result.outcome.status === "failed" || result.outcome.status === "parked");
+        // Author-stage failures are counted too: an authoring failure the awaiting
+        // guard did NOT catch — e.g. a workstream that authored fine but sits
+        // downstream of an authoring failure — must still sink the intermission.
+        // Same set that seeded `blocked`/guarded the awaiting branch above;
+        // classifying on it here as well makes "any genuine failure => ordinary
+        // partial" true independent of how the cone painted it.
+        const anyAuthoringFailure = authorResult.results.some((entry) => entry.outcome.status === "failed" || entry.outcome.status === "parked");
+        // A planned intermission: nothing failed anywhere (build or authoring), at
+        // least one workstream is waiting on a human, and not everything built. A
+        // genuine failure makes it an ordinary partial instead — the human should
+        // read a diagnosis, not a checklist.
+        const intermission = !complete && anyAwaiting && !anyFailedOrParked && !anyAuthoringFailure;
+        manifest.program.status = complete
+            ? "complete"
+            : intermission
+                ? "awaiting_human"
+                : "partial";
+        await timed(recorder, { stage: "manifest-persist" }, () => saveManifest(root, options.programId, manifest, { log }));
+        const wholeProgram = await runWholeProgramStage({
             root,
             programId: options.programId,
             manifest,
-            workstreamId,
-            decisions,
-            baseCommit,
-            decider,
+            config,
             agentRunner,
             permits,
             git,
             isRepository,
+            results,
+            authorResult,
+            runStartCommit,
+            decider,
             reviewed,
-            onTranscript: (transcript) => journalDenials(workstreamId, "decider", transcript),
             triaged,
             now,
             log,
-            observe: { root, programId: options.programId, label: `${workstreamId}-decider-decision`, log },
+            recorder,
         });
-    }
-    function reviewWorkstreamFindings(workstreamId, findings, baseCommit) {
-        return triageFindings({
+        const ledger = await readDecisionLedger(root, options.programId);
+        const escalations = escalatedRecords(ledger);
+        // Runs after the ledger read above, so its brief already sees this run's
+        // own whole-program findings/rulings, and before report assembly, so its
+        // section renders next to WS-04's own (§3.2 of the WS-05 spec). Read-only
+        // and fail-open: nothing here can change `results`, `ledger`, the run's
+        // outcome, or the exit code.
+        const causalAnalysis = await runCausalAnalysisStage({
             root,
             programId: options.programId,
             manifest,
-            workstreamId,
-            findings,
-            baseCommit,
-            decider,
+            config,
             agentRunner,
             permits,
             git,
             isRepository,
-            reviewed,
-            observe: { root, programId: options.programId, label: `${workstreamId}-decider-finding`, log },
-            onTranscript: (transcript) => journalDenials(workstreamId, "decider", transcript),
-            triaged,
-            now,
+            results,
+            runStartCommit,
+            ledger,
             log,
+            recorder,
         });
-    }
-    /**
-     * 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, observe) {
-        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 { commit: 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);
+        const reportPath = runReportPath(root, options.programId);
+        // Under concurrency (WS-02+) this is what guarantees no manifest or
+        // ledger write is still in flight while docs/programs is staged below;
+        // today, with nothing concurrent, it is a no-op that must exist anyway.
+        await drainProgramWrites(programWriteKey(root, options.programId));
+        // Rendering is the last stage the recorder can actually observe (SC-03):
+        // captured as its own span, nested under the run span, rather than folded
+        // silently into it. Kept in its own try/catch, separate from the write and
+        // commit below, so a rendering bug still lets `finalize()` run and still
+        // lets the write/commit attempt proceed against whatever report content
+        // *is* available — a rendering failure is a logged line, not a thrown run,
+        // exactly like the write/commit failure path below (SC-05, SC-12).
+        let reportContent;
+        try {
+            const reportSpan = recorder.span({ stage: "report-assembly" });
+            // `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.
+            // Computed before renderRunReport (§3.2/§3.9): renderAnalyticsSection is
+            // WS-04's own never-throwing isolation boundary, so an analytics bug can
+            // never propagate into this try's catch below and leave reportContent
+            // undefined — which would suppress the entire report (SC-13). The
+            // recorder's snapshot, not the finalized file, is the only artifact that
+            // exists at this point in the sequence (finalize() runs later, below).
+            // Passed as a thunk, not called eagerly here: `recorder.snapshot()` is
+            // documented as non-throwing, but evaluating it as a plain argument would
+            // run it *before* renderAnalyticsSection's own try/catch is reached, so a
+            // violation of that contract would still escape this boundary.
+            const analyticsSection = renderAnalyticsSection(() => recorder.snapshot());
+            // The causal section's own "observed measurements" layer is rendered
+            // from a *later* snapshot than the one the analyzer was briefed with
+            // (`causalAnalysis` above) — one that now includes the analyzer's own
+            // `causal-analysis` span — exactly as WS-04's own section above it does.
+            // The two differ by exactly the analyzer's own cost; the section states
+            // that boundary explicitly (§3.2).
+            const causalAnalysisSection = renderCausalAnalysisSection(causalAnalysis.outcome, () => recorder.snapshot());
+            reportContent = renderRunReport(manifest, results, ledger, triaged, authorResult, now(), wholeProgram, preflight, options.resumeCommand, manifestMergeCount(root, options.programId) > mergesAtStart, analyticsSection, causalAnalysisSection);
+            reportSpan.close({ outcome: "success" });
         }
-        // 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 { commit: greenCommit };
-        const fix = await attemptFix({
-            root,
-            programId: options.programId,
-            workstream,
-            spec,
-            config,
-            agentRunner,
-            permits,
-            verifyRunner,
-            git,
-            agent,
-            findings: toFix,
-            greenCommit,
-            label: "fix-now fix",
-            log,
-            now,
-            observe,
+        catch (error) {
+            log(`run report: could not render ${reportPath}: ${error.message}`);
+        }
+        // The `report-commit` span (the stage STAGE_BUCKET already reserves for
+        // exactly this) covers writing the report to disk and committing
+        // docs/programs, nested explicitly under `runSpan` rather than the
+        // implicit stack, since `reportSpan` above has already closed and popped
+        // itself. Both this span and its parent `runSpan` are opened/left open
+        // rather than closed here, because the write and the commit they describe
+        // happen *after* `finalize()` below persists this very artifact — closing
+        // them now would stamp an `endOffsetMs` that is a lie the moment the write
+        // or commit takes any measurable time at all. An absent `endOffsetMs` is
+        // exactly the schema's existing "true end not observed" semantics; the
+        // run's actual outcome classification is recorded as a point observation
+        // instead of a span-close result, since it — unlike an interval's end — is
+        // a fact already known at this instant.
+        runSpan.child({ stage: "report-commit" });
+        recorder.point({
+            kind: "run-outcome",
+            coverage: "observed",
+            dimensions: { stage: "run", outcome: complete ? "success" : intermission ? "no-op" : "failed" },
         });
-        // "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}`);
-        const resultCommit = kept ? fix.greenCommit : greenCommit;
+        // Finalized once every stage the recorder can observe closing has closed
+        // (report-assembly above; report-commit and run intentionally remain
+        // open — see above). Still runs before the report is written and
+        // committed, so the artifact rides into the same `docs/programs` commit
+        // (SC-02, SC-14). Fail-open: never throws, never delays or blocks the
+        // report below.
+        const finalizeStart = monotonic();
+        await recorder.finalize();
+        // `finalize()` seals the point/span arrays before its own duration is
+        // known, so an overhead measure around it can never live in the artifact
+        // it measures (§3.4.d) — emitted after, as a non-conserved sidecar-only
+        // point: no `stage`, never summed into any bucket.
+        recorder.point({
+            kind: "analytics-overhead",
+            coverage: "observed",
+            value: monotonic() - finalizeStart,
+            unit: "ms",
+            label: "finalize",
+        });
+        // 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.
+        if (reportContent !== undefined) {
+            try {
+                await writeFile(reportPath, reportContent, "utf8");
+                if (isRepository) {
+                    // Guarded by `rootIndexMutex` (WS-05 §3.7) like every other git-index
+                    // operation at root; by this point the unified scheduler has fully
+                    // drained, so nothing else can be contending for it, but the lock
+                    // discipline is stated once and applied everywhere rather than
+                    // special-cased at the one call site that "happens to" run alone.
+                    await rootIndexMutex.runExclusive(() => git.commitPaths(root, `nightshift(${options.programId}): run report and decision ledger`, ["docs/programs"]));
+                }
+                // A best-effort forensic breadcrumb for the one boundary the
+                // already-committed canonical artifact can never describe: `point()`
+                // still appends to the gitignored sidecar once armed even though
+                // `finalize()` has already run, and never touches the canonical JSON
+                // again, so the working tree stays clean after a normal run.
+                recorder.point({
+                    kind: "report-commit-result",
+                    coverage: "observed",
+                    dimensions: { stage: "report-commit", outcome: "success" },
+                });
+            }
+            catch (error) {
+                log(`run report: could not write or commit ${reportPath}: ${error.message}`);
+                recorder.point({
+                    kind: "report-commit-result",
+                    coverage: "observed",
+                    dimensions: { stage: "report-commit", outcome: "failed" },
+                });
+            }
+        }
+        log(`run report: ${reportPath}`);
         return {
-            commit: resultCommit,
-            ...(fix.spawnError === undefined ? {} : { spawnError: fix.spawnError }),
-            ...(fix.transcript === undefined ? {} : { transcript: fix.transcript }),
+            programId: options.programId,
+            complete,
+            intermission,
+            workstreams: results,
+            escalations,
+            reportPath,
+            wholeProgramReview: wholeProgram,
+            causalAnalysis,
         };
+        async function runWorkstream(workstream, 
+        /**
+         * The decision ledger, read once per build flow (WS-05 §3.4) rather
+         * than once for the whole run — a build's brief then sees every
+         * decision journalled before it started, including its own
+         * dependencies' authoring, without breaking WS-04's
+         * `scheduled − ready === concurrency-cap` identity (the read happens
+         * strictly after the `workstream-scheduled` emission, in the caller).
+         */
+        ledger, flowOptions = {}) {
+            // Explicit parenting (WS-01 §3.3): every span/point this flow opens
+            // parents to the run span itself, never to whatever happens to be open
+            // on the implicit stack — the seam future concurrent workstreams (WS-04)
+            // stand on. `[WS-xx] `-prefixes every line this flow logs.
+            const scope = runSpan.scope({ workstream: workstream.id });
+            const log = workstreamLog(baseLog, workstream.id);
+            const base = {
+                id: workstream.id,
+                name: workstream.name,
+                outcome: { status: "failed", reason: "not attempted" },
+                decisionIds: [],
+                decisionErrors: [],
+                buildAgentCommand: describeAgent(agent),
+            };
+            /** Every build-role spawn's transcript, for the report's per-workstream
+             *  Commands subsection (WS-02). Reviewer/decider spawns are excluded. */
+            function recordTranscript(transcript) {
+                if (transcript)
+                    (base.transcripts ??= []).push(transcript);
+            }
+            /** Names the JSONL file under build-logs/<programId>/, distinctly per spawn label. */
+            function transcriptSink(label) {
+                return { root, programId: options.programId, label: `${workstream.id}-${label}`, log };
+            }
+            let spec;
+            try {
+                spec = await readFile(join(root, workstream.taskFile), "utf8");
+            }
+            catch {
+                base.outcome = {
+                    status: "parked",
+                    reason: `spec not found at ${workstream.taskFile}`,
+                };
+                return base;
+            }
+            workstream.status = "in_progress";
+            await timed(scope, { stage: "manifest-persist" }, () => saveManifest(root, options.programId, manifest, { log }));
+            // One read, not two (WS-04, §3.5): the program-branch tip is the
+            // worktree's base *and* the decision anchor (`baseCommit`) — the same
+            // fact under two names, resolved through `WorktreeOps`, never
+            // `GitOps.currentCommit`. Concurrently, a second independent read here
+            // could observe a sibling's integration land in between, giving this
+            // workstream a `baseCommit` newer than the tree its worktree was
+            // actually built from — the reviewer and decider would then see a
+            // sibling's change as though this workstream had deleted it. Preferring
+            // `flowOptions.scheduledFrom` when present means the scheduler's own
+            // read (taken with no `await` before its `workstream-scheduled`
+            // emission) is the only read on every scheduled path; the fallback here
+            // exists only for the one caller with no scheduling instant to offer.
+            const programTip = isRepository
+                ? (flowOptions.scheduledFrom ?? (await worktrees.resolveCommit(root, "HEAD")))
+                : undefined;
+            const baseCommit = programTip;
+            // The worktree lifecycle (WS-02, §3.3): every in-progress workstream
+            // builds in its own dedicated worktree on its own branch, created from
+            // the program-branch tip, never in the root checkout. `cwd` is what
+            // every build-role spawn, verify command, and workstream-owned git
+            // operation below uses from here on; `root` stays reserved for the
+            // manifest, ledger, transcripts, and verify-output evidence.
+            let cwd = root;
+            let worktreeBranchOfThis;
+            if (isRepository) {
+                if (worktreeBase === undefined) {
+                    // Unreachable in production (worktreeBase is always resolved inside
+                    // the isRepository branch above, before any workstream runs) —
+                    // guarded rather than asserted so a future refactor fails loudly.
+                    throw new Error("worktree base was never resolved for a git repository run");
+                }
+                // Routed through the same `PrepareWorktreeResult` shape and the same
+                // failure handling below as a real `prepareWorktree` failure, rather
+                // than a second early-return with its own `saveManifest` call —
+                // the tip could not resolve, so there is nothing to build from, but
+                // that is still exactly one more reason a worktree could not be
+                // prepared (WS-04, §3.5).
+                const prepared = programTip === undefined
+                    ? { ok: false, reason: "cannot resolve the program-branch tip", created: false }
+                    : await prepareWorktree({
+                        root,
+                        programId: options.programId,
+                        workstreamId: workstream.id,
+                        worktrees,
+                        worktreeBase,
+                        setupRunner,
+                        log,
+                        programTip,
+                    });
+                if (!prepared.ok) {
+                    workstream.status = "failed";
+                    if (prepared.created)
+                        base.worktreePath = prepared.cwd;
+                    base.outcome = { status: "failed", reason: prepared.reason };
+                    await timed(scope, { stage: "manifest-persist" }, () => saveManifest(root, options.programId, manifest, { log }));
+                    return base;
+                }
+                cwd = prepared.cwd;
+                worktreeBranchOfThis = prepared.branch;
+                base.worktreePath = cwd;
+            }
+            let priorFailure;
+            let priorDiagnosis;
+            let implementerFingerprint;
+            // WS-08: last-wins across every attempt in this workstream's build —
+            // the fix seats resume whichever attempt most recently reported a
+            // session id, which is the attempt whose commit they are fixing.
+            // Capturing on every attempt (including recovery) is not resuming: the
+            // recovery seat still spawns fresh; its handle is only ever a candidate
+            // for the fix seats, subject to invokeAgent's provider/invocation checks.
+            let buildSession;
+            const attempts = [
+                { agent, label: "implementer", role: "agent" },
+            ];
+            if (recovery && !recovery.borrowedImplementer) {
+                attempts.push({ agent: recovery.agent, label: "recovery", role: "recoveryAgent" });
+                // 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", role: "agent" });
+            }
+            for (const [index, attempt] of attempts.entries()) {
+                log(`${workstream.name}: ${attempt.label} attempt`);
+                const { brief, components } = implementerBrief(manifest, workstream, spec, ledger, config.permits?.policy, priorFailure, priorDiagnosis);
+                for (const point of promptComponentSizePoints(components, { role: attempt.role })) {
+                    scope.point(point);
+                }
+                // Why this repetition happened (WS-02, SC-05/SC-06): the first attempt
+                // is always `initial`; a later seat is `informed-by-diagnosis` when the
+                // prior attempt's failure was read by the reviewer, else a plain
+                // `verify-failure` retry (a deterministic failure skips diagnosis —
+                // see below — so the next seat still spawns, just undiagnosed).
+                const seatStage = STAGE_FOR_SEAT[attempt.label] ?? "implementer";
+                const attemptReason = index === 0 ? "initial" : priorDiagnosis !== undefined ? "informed-by-diagnosis" : "verify-failure";
+                /** This attempt's eventual `attempt-outcome` disposition (WS-02, §3.3)
+                 *  — distinct from the spawn span's own success/failed outcome (an
+                 *  undelivered-brief or green-but-empty attempt spawns "successfully"
+                 *  but disposes as `no-op`/`discarded`). Set once, at the point each
+                 *  failure reason is detected below; `undefined` means the attempt was
+                 *  kept. */
+                let dispositionOutcome;
+                const emitAttemptOutcome = (outcome, reasonOverride) => {
+                    scope.point({
+                        kind: "attempt-outcome",
+                        coverage: "observed",
+                        dimensions: {
+                            stage: seatStage,
+                            workstream: workstream.id,
+                            role: attempt.role,
+                            attemptSeat: attempt.label,
+                            attemptIndex: index,
+                            attemptReason: reasonOverride ?? attemptReason,
+                            outcome,
+                        },
+                    });
+                };
+                let invocation;
+                let spawnFailure;
+                try {
+                    invocation = await invokeAgent(agentRunner, attempt.agent, brief, cwd, permits, attempt.role, transcriptSink(attempt.label.replaceAll(" ", "-")), scope, { stage: seatStage, workstream: workstream.id, attemptSeat: attempt.label, attemptIndex: index, attemptReason });
+                    if (invocation.session)
+                        buildSession = invocation.session;
+                }
+                catch (error) {
+                    // The agent process never started — its command is wrong, missing,
+                    // or unrunnable. Nothing was built; this is the captured
+                    // silent-exit incident (SC-12). Make it a diagnosed failure via the
+                    // existing retry/park machinery below, never a process exit.
+                    spawnFailure =
+                        `the ${attempt.label} agent could not be spawned: ` +
+                            `${error.message}. The configured command ` +
+                            `\`${describeAgent(attempt.agent)}\` did not start, so nothing was built.`;
+                    invocation = { exitCode: 1, output: "" };
+                }
+                recordTranscript(invocation.transcript);
+                const summary = resolveSummary(invocation.output);
+                base.summary = summary.text;
+                await journalDenials(workstream.id, attempt.label, invocation.transcript, summary.needsPermission, scope);
+                const parsed = extractDecisions(invocation.output);
+                base.decisionErrors.push(...parsed.errors);
+                await journalDecisions(workstream, parsed.decisions, baseCommit, scope);
+                base.decisionIds = parsed.decisions.map((decision) => decisionFingerprint(workstream.id, decision));
+                let failure = await verifyAttempt(config, verifyRunner, cwd, root, invocation.exitCode, scope, "verification-command", {
+                    programId: options.programId,
+                    phase: `post-${attempt.label.replaceAll(" ", "-")}`,
+                    workstream: workstream.id,
+                    role: attempt.role,
+                    attemptSeat: attempt.label,
+                    attemptIndex: index,
+                    cache: verifyCache,
+                });
+                // Deterministic protocol failures the runner can see without a model:
+                // no diagnosis is spent on them, because no read of the tree could add
+                // anything to what the runner already knows.
+                let deterministicFailure = false;
+                // A spawn failure takes precedence over whatever verifyAttempt saw
+                // (the untouched tree can verify green on its own) — no reviewer
+                // diagnosis is spent reading an empty diff.
+                if (spawnFailure !== undefined) {
+                    failure = spawnFailure;
+                    deterministicFailure = true;
+                    dispositionOutcome = "failed";
+                }
+                // A brief that never reached the agent's stdin means the process
+                // crashed at startup — whatever it printed was not an answer to the
+                // brief, even when it exited 0.
+                if (failure === undefined && invocation.inputError !== undefined) {
+                    failure =
+                        `the brief could not be delivered to the agent's stdin ` +
+                            `(${invocation.inputError}) — the agent likely crashed at startup, ` +
+                            `so its reply answered nothing.`;
+                    deterministicFailure = true;
+                    dispositionOutcome = "no-op";
+                }
+                // A green verify over an unchanged tree is just the baseline passing
+                // again, not built work. Without this, an agent that crashes at
+                // startup while exiting 0 (or replies without working) sweeps only
+                // the runner's own in_progress manifest write into a metadata-only
+                // commit and walks through the gate as "complete". A reply that never
+                // produces the work is a protocol failure, not an empty result.
+                if (failure === undefined && isRepository) {
+                    const dirty = await git.dirtyPaths(cwd);
+                    const meaningful = dirty.some((path) => !isRunnerOwnedArtifactPath(path));
+                    if (!meaningful) {
+                        failure =
+                            "the attempt verified green but changed nothing outside " +
+                                "docs/programs/ — nothing was built, and the passing verify was " +
+                                "the untouched baseline. A no-op attempt is a protocol failure " +
+                                "(the agent may have crashed at startup or replied without " +
+                                "working), not a completed workstream.";
+                        deterministicFailure = true;
+                        dispositionOutcome = "discarded";
+                    }
+                }
+                // A genuine verify failure (not spawn/inputError/green-empty) disposes
+                // as `failed`, same as every other undetermined failure reason.
+                if (failure !== undefined && dispositionOutcome === undefined) {
+                    dispositionOutcome = "failed";
+                }
+                if (failure === undefined) {
+                    let c0;
+                    if (isRepository) {
+                        // Unlike the authoring, run-report, and replay commits, this one
+                        // stays a whole-tree sweep: an implementing agent touches whatever
+                        // files the work required, and that set is exactly what the
+                        // runner cannot know in advance. c0 is the green anchor the test
+                        // critique's fix loop resets to on a failing fix (SC-07).
+                        c0 = await timed(scope, { stage: "git-commit", workstream: workstream.id }, () => git.commitAll(cwd, `nightshift(${options.programId}): ${workstream.id} ${workstream.name}`, ["docs/programs"]), commitEvidence);
+                    }
+                    // Captured before the pass runs so a fallback's report line can name
+                    // the producer's command (§3.11) — an approximation good for the
+                    // common one-round case; a later round's true producer is whichever
+                    // round most recently resumed, which the pass itself tracks
+                    // internally but does not need to surface here.
+                    const criticEnteringSession = buildSession;
+                    const critique = isRepository && c0 !== undefined
+                        ? await runTestCritique({
+                            root,
+                            cwd,
+                            manifest,
+                            workstream,
+                            spec,
+                            config,
+                            agentRunner,
+                            permits,
+                            verifyRunner,
+                            git,
+                            reviewer,
+                            agent,
+                            deciderConfigured: decider !== undefined,
+                            baseCommit,
+                            greenCommit: c0,
+                            now,
+                            log,
+                            transcriptSink,
+                            recorder: scope,
+                            verifyCache,
+                            triage: (events, triageBaseCommit) => reviewWorkstreamFindings(workstream.id, cwd, events, triageBaseCommit, scope),
+                            ...(buildSession ? { buildSession } : {}),
+                        })
+                        : undefined;
+                    if (critique?.continuity) {
+                        (base.sessionContinuity ??= []).push(...critique.continuity.map((continuity) => ({
+                            seat: "test critique fix",
+                            continuity,
+                            producerCommand: criticEnteringSession?.command,
+                            seatCommand: agent.command,
+                        })));
+                    }
+                    // The workstream's own final verified commit, in its worktree —
+                    // after any kept fix, that is the fix commit, not the earlier green
+                    // one; already includes any triaged fix-now commit, since the merged
+                    // fix runs inside the critique loop itself (WS-09). Not what lands
+                    // in the manifest: under WS-02 that is the *integration* commit,
+                    // recorded only after integration succeeds, below.
+                    const finalCommit = critique?.finalCommit ?? c0;
+                    if (critique && critique.stageErrors.length > 0) {
+                        (base.stageErrors ??= []).push(...critique.stageErrors);
+                    }
+                    for (const transcript of critique?.transcripts ?? [])
+                        recordTranscript(transcript);
+                    {
+                        const spawnErrors = await reviewWorkstreamDecisions(workstream.id, cwd, parsed.decisions, baseCommit, scope);
+                        if (spawnErrors.length > 0)
+                            (base.stageErrors ??= []).push(...spawnErrors);
+                    }
+                    if (critique)
+                        base.testCritique = critique.outcome;
+                    base.testCritiqueDiffClipped = critique?.diffClipped ?? false;
+                    // Integration (WS-02, §3.5-§3.6): the last thing this flow does on
+                    // the green path. Not reached when this is not a git repository —
+                    // there is nothing to integrate, and `finalCommit`/`cwd` are already
+                    // the root's own.
+                    if (!isRepository || finalCommit === undefined) {
+                        workstream.status = "complete";
+                        if (finalCommit !== undefined)
+                            workstream.commit = finalCommit;
+                        await timed(scope, { stage: "manifest-persist" }, () => saveManifest(root, options.programId, manifest, { log }));
+                        base.outcome = {
+                            status: "complete",
+                            ...(finalCommit === undefined ? {} : { commit: finalCommit }),
+                        };
+                        emitAttemptOutcome("success");
+                        return base;
+                    }
+                    const recoveryAgentForIntegration = recovery && !recovery.borrowedImplementer ? recovery.agent : agent;
+                    // Serialised through the one run-scoped integration mutex (WS-04,
+                    // §3.5): the mutex spans the whole call, including the merge-forward
+                    // and its re-verify inside `integrateWorkstream` — not just the
+                    // final squash — because the merge-forward is the proof that the
+                    // squash is a fast-forward, and a sibling landing between them would
+                    // void that proof.
+                    const mutexWaitStart = monotonic();
+                    const integration = await integrationMutex.runExclusive(async () => {
+                        const mutexWaitedMs = monotonic() - mutexWaitStart;
+                        if (mutexWaitedMs > 0) {
+                            recordWorkstreamWaiting(recorder, workstream.id, {
+                                cause: "integration-mutex",
+                                waitedMs: mutexWaitedMs,
+                            });
+                        }
+                        return integrateWorkstream({
+                            root,
+                            programId: options.programId,
+                            workstream,
+                            cwd,
+                            branch: worktreeBranchOfThis ?? worktreeBranchName(options.programId, workstream.id),
+                            finalCommit,
+                            worktrees,
+                            git,
+                            config,
+                            verifyRunner,
+                            setupRunner,
+                            verifyCache,
+                            agentRunner,
+                            permits,
+                            recoveryAgent: recoveryAgentForIntegration,
+                            worktreeBase: worktreeBase,
+                            scope,
+                            log,
+                            transcriptSink,
+                            rootIndexMutex,
+                            rosterTaskFiles,
+                        });
+                    });
+                    for (const transcript of integration.transcripts)
+                        recordTranscript(transcript);
+                    if (integration.ok) {
+                        workstream.status = "complete";
+                        if (integration.commit !== undefined)
+                            workstream.commit = integration.commit;
+                        await timed(scope, { stage: "manifest-persist" }, () => saveManifest(root, options.programId, manifest, { log }));
+                        for (const { path, branch: cleanupBranch } of integration.cleanup) {
+                            await worktrees.remove(root, path);
+                            await worktrees.deleteBranch(root, cleanupBranch);
+                        }
+                        await git.deleteRef(root, retainedRefName(options.programId, workstream.id));
+                        delete base.worktreePath;
+                        base.outcome = {
+                            status: "complete",
+                            ...(integration.commit === undefined ? {} : { commit: integration.commit }),
+                        };
+                        emitAttemptOutcome("success");
+                        return base;
+                    }
+                    workstream.status = "failed";
+                    await timed(scope, { stage: "manifest-persist" }, () => saveManifest(root, options.programId, manifest, { log }));
+                    base.retainedRef = integration.retainedRef;
+                    base.outcome = {
+                        status: "failed",
+                        reason: `${integration.reason}\n\nWorktree(s) retained: ${integration.worktreePaths.join(", ")}.`,
+                    };
+                    emitAttemptOutcome("success");
+                    return base;
+                }
+                priorFailure = failure;
+                log(`${attempt.label} attempt failed — ${failure}`);
+                // A failure identical to the pre-run baseline (up to counts and
+                // timings) was there before any workstream ran: environmental, not
+                // this workstream's work. No retry or diagnosis is spent on it, and
+                // the caller halts the run — every later workstream would be charged
+                // for the same broken environment. Workstreams resumed with their own
+                // leftover failure in the tree are exempt (see resumedIds).
+                if (baselineFingerprint !== undefined &&
+                    !resumedIds.has(workstream.id) &&
+                    failureFingerprint(failure) === baselineFingerprint) {
+                    workstream.status = "failed";
+                    await timed(scope, { stage: "manifest-persist" }, () => saveManifest(root, options.programId, manifest, { log }));
+                    {
+                        const spawnErrors = await reviewWorkstreamDecisions(workstream.id, cwd, parsed.decisions, baseCommit, scope);
+                        if (spawnErrors.length > 0)
+                            (base.stageErrors ??= []).push(...spawnErrors);
+                    }
+                    base.environmental = true;
+                    base.outcome = {
+                        status: "failed",
+                        reason: failure +
+                            "\n\nThis failure is identical (up to counts and timings) to the " +
+                            "verification failure recorded on the untouched tree before the " +
+                            "run began — the environment was broken before this workstream " +
+                            "ran. No retry was spent, and the run halted here.",
+                    };
+                    emitAttemptOutcome("failed", "environmental");
+                    return base;
+                }
+                // 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 timed(scope, { stage: "manifest-persist" }, () => saveManifest(root, options.programId, manifest, { log }));
+                    // The work stays in the retained worktree (a resume salvages it to a
+                    // `refs/nightshift/…-wip` ref before reaping); decisions made on the
+                    // way to a failure are still journaled and still reviewable.
+                    {
+                        const spawnErrors = await reviewWorkstreamDecisions(workstream.id, cwd, parsed.decisions, baseCommit, scope);
+                        if (spawnErrors.length > 0)
+                            (base.stageErrors ??= []).push(...spawnErrors);
+                    }
+                    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,
+                    };
+                    emitAttemptOutcome(stuck ? "failed" : (dispositionOutcome ?? "failed"), stuck ? "stuck" : undefined);
+                    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. Deterministic failures (no-op, undelivered brief) are
+                // never diagnosed: the runner already knows exactly what happened,
+                // and a reviewer read of an empty diff could only muddy it.
+                if (reviewer && !deterministicFailure) {
+                    const diagnosed = await diagnoseFailure({
+                        cwd,
+                        manifest,
+                        workstream,
+                        spec,
+                        agentRunner,
+                        permits,
+                        reviewer,
+                        git,
+                        baseCommit,
+                        failure,
+                        attemptSeat: attempt.label,
+                        attemptIndex: index,
+                        observe: transcriptSink(`diagnose-${attempt.label.replaceAll(" ", "-")}`),
+                        recorder: scope,
+                    });
+                    priorDiagnosis = diagnosed.diagnosis;
+                    if (diagnosed.spawnError !== undefined) {
+                        (base.stageErrors ??= []).push(diagnosed.spawnError);
+                        log(diagnosed.spawnError);
+                    }
+                    await journalDenials(workstream.id, "reviewer", diagnosed.transcript, [], scope);
+                }
+                else {
+                    priorDiagnosis = undefined;
+                }
+                if (priorDiagnosis !== undefined) {
+                    (base.failureDiagnoses ??= []).push({
+                        attempt: attempt.label,
+                        verdict: priorDiagnosis,
+                    });
+                    log(`reviewer diagnosed the ${attempt.label} failure`);
+                }
+                emitAttemptOutcome(dispositionOutcome ?? "failed");
+            }
+            return base;
+        }
+        async function journalDecisions(workstream, decisions, baseCommit, 
+        /** The workstream flow's span scope (SC-09) — see reviewWorkstreamDecisions. */
+        flowScope = recorder) {
+            const log = workstreamLog(baseLog, workstream.id);
+            const events = decisions.map((decision) => ({
+                kind: "decision-recorded",
+                at: now().toISOString(),
+                id: decisionFingerprint(workstream.id, decision),
+                workstream: workstream.id,
+                decision,
+                ...(baseCommit === undefined ? {} : { baseCommit }),
+                decidedBy: "implementer",
+            }));
+            await timed(flowScope, { stage: "ledger-persist", workstream: workstream.id }, () => appendLedgerEvents(root, options.programId, events));
+            for (const decision of decisions) {
+                log(`decision: ${decision.title} -> ${decision.chosen}`);
+            }
+        }
+        /**
+         * Journals `permission-denied` events for one spawn (WS-03) — every
+         * workstream-attributed spawn calls this once, passing its own transcript
+         * and (for build roles only) the agent's `needsPermission` self-reports.
+         * A no-op when the spawn produced neither.
+         */
+        async function journalDenials(workstreamId, attempt, transcript, needsPermission = [], flowScope = recorder) {
+            const log = workstreamLog(baseLog, workstreamId);
+            const events = buildDenialEvents(workstreamId, attempt, transcript?.denials ?? [], needsPermission, config.permits?.deny ?? [], now().toISOString());
+            if (events.length === 0)
+                return;
+            await timed(flowScope, { stage: "ledger-persist", workstream: workstreamId }, () => appendLedgerEvents(root, options.programId, events));
+            for (const event of events) {
+                if (event.kind !== "permission-denied")
+                    continue;
+                log(`${attempt}: denied \`${event.command}\` (${event.source})`);
+            }
+        }
+        function reviewWorkstreamDecisions(workstreamId, cwd, decisions, baseCommit, 
+        /** The workstream flow's span scope (SC-09): decider spans parent here,
+         *  never to whatever span another concurrent flow happens to have open. */
+        flowScope = recorder) {
+            const log = workstreamLog(baseLog, workstreamId);
+            return reviewDecisions({
+                root,
+                cwd,
+                programId: options.programId,
+                manifest,
+                workstreamId,
+                decisions,
+                baseCommit,
+                decider,
+                agentRunner,
+                permits,
+                git,
+                isRepository,
+                reviewed,
+                onTranscript: (transcript) => journalDenials(workstreamId, "decider", transcript, [], flowScope),
+                triaged,
+                now,
+                log,
+                observe: { root, programId: options.programId, label: `${workstreamId}-decider-decision`, log },
+                recorder: flowScope,
+            });
+        }
+        function reviewWorkstreamFindings(workstreamId, cwd, findings, baseCommit, flowScope = recorder) {
+            const log = workstreamLog(baseLog, workstreamId);
+            return triageFindings({
+                root,
+                cwd,
+                programId: options.programId,
+                manifest,
+                workstreamId,
+                findings,
+                baseCommit,
+                decider,
+                agentRunner,
+                permits,
+                git,
+                isRepository,
+                reviewed,
+                observe: { root, programId: options.programId, label: `${workstreamId}-decider-finding`, log },
+                onTranscript: (transcript) => journalDenials(workstreamId, "decider", transcript, [], flowScope),
+                triaged,
+                now,
+                log,
+                recorder: flowScope,
+            });
+        }
     }
 }
 /**
@@ -1487,6 +2685,7 @@ function notBuiltRoster(results, authorResult) {
  */
 export async function runWholeProgramStage(args) {
     const { root, programId, manifest, config, agentRunner, permits, git, isRepository, results, authorResult, runStartCommit, decider, reviewed, triaged, now, log, fs, } = args;
+    const recorder = args.recorder ?? NOOP_RUN_RECORDER;
     const errors = [];
     let commit;
     let commitSkipped = false;
@@ -1508,7 +2707,9 @@ export async function runWholeProgramStage(args) {
     try {
         safeLog("whole-program review: starting");
         const base = await resolveProgramDiffBase({ root, git, isRepository, runStartCommit });
-        const diff = base === undefined ? "" : await git.diffSince(root, base);
+        const diff = base === undefined
+            ? ""
+            : await timed(recorder, { stage: "git-diff" }, () => git.diffSince(root, base));
         const notBuilt = notBuiltRoster(results, authorResult);
         const reviewCommit = isRepository ? await git.currentCommit(root) : undefined;
         outcome = await runWholeProgramReview({
@@ -1523,6 +2724,7 @@ export async function runWholeProgramStage(args) {
             ...(notBuilt.length === 0 ? {} : { notBuilt }),
             ...(fs === undefined ? {} : { fs }),
             log,
+            recorder,
         });
         safeLog(outcome.status === "refreshed"
             ? `whole-program review: refreshed ${AS_BUILT_PATH}` +
@@ -1532,7 +2734,7 @@ export async function runWholeProgramStage(args) {
         if (outcome.writtenPaths.length > 0) {
             if (isRepository) {
                 try {
-                    commit = await git.commitPaths(root, `nightshift(${programId}): as-built snapshot`, outcome.writtenPaths);
+                    commit = await timed(recorder, { stage: "as-built-snapshot" }, () => git.commitPaths(root, `nightshift(${programId}): as-built snapshot`, outcome.writtenPaths), commitEvidence);
                 }
                 catch (error) {
                     errors.push(`could not commit the as-built snapshot: ${error.message}`);
@@ -1554,7 +2756,7 @@ export async function runWholeProgramStage(args) {
         }
         else {
             try {
-                await appendLedgerEvents(root, programId, events);
+                await timed(recorder, { stage: "ledger-persist", workstream: WHOLE_PROGRAM_SUBJECT }, () => appendLedgerEvents(root, programId, events));
                 journaled = true;
                 findingIds = events.map((event) => event.id);
             }
@@ -1580,6 +2782,7 @@ export async function runWholeProgramStage(args) {
                     triaged,
                     now,
                     log,
+                    recorder,
                 });
                 errors.push(...spawnErrors);
             }
@@ -1599,16 +2802,263 @@ export async function runWholeProgramStage(args) {
         errors,
     };
 }
-/** Undefined means the attempt verified clean; otherwise the diagnosis. */
-async function verifyAttempt(config, verifyRunner, root, agentExitCode) {
+function causalAnalysisStageFailure(reason) {
+    return {
+        ran: false,
+        status: "analyzer-error",
+        reason,
+        unresolvedQuestions: [],
+        parseErrors: [],
+        inputClipped: false,
+    };
+}
+/**
+ * Projects the run's own `WorkstreamResult[]` into WS-05's narrow,
+ * causal-analysis-owned timeline shape (mirrors `notBuiltRoster`'s mapping
+ * pattern) — `causal-analysis.ts` cannot import `WorkstreamResult` itself
+ * without creating a cycle back into this module.
+ */
+function causalAnalysisTimeline(results) {
+    return results.map((result) => ({
+        id: result.id,
+        name: result.name,
+        status: result.outcome.status,
+        ...(result.outcome.status === "complete" ? {} : { reason: result.outcome.reason }),
+        ...(result.failureDiagnoses === undefined ? {} : { failureDiagnoses: result.failureDiagnoses }),
+        ...(result.testCritique === undefined
+            ? {}
+            : {
+                testCritique: {
+                    stopReason: result.testCritique.stopReason,
+                    roundsRun: result.testCritique.roundsRun,
+                    openSubjects: result.testCritique.open.map((finding) => finding.subject),
+                    resolvedSubjects: result.testCritique.resolved.map((finding) => finding.subject),
+                    fixesRun: result.testCritique.fixesRun,
+                    cyclesAllotted: result.testCritique.cyclesAllotted,
+                },
+            }),
+    }));
+}
+/**
+ * The end-of-run causal-analysis stage (WS-05): resolves the same diff base
+ * the whole-program stage uses, takes the analytics snapshot *before*
+ * spawning the analyzer (so it never reasons about its own cost, §3.2),
+ * calls the never-throwing pass exactly once, and returns its outcome. Every
+ * risky step gets its own catch so a stage failure is a sentence in the
+ * report, never a change to the run's outcome (SC-13) — 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. Read-only: writes no file, journals
+ * no ledger event, and is never a gate.
+ */
+export async function runCausalAnalysisStage(args) {
+    const { root, programId, manifest, config, agentRunner, permits, git, isRepository, results, runStartCommit, ledger, log, } = args;
+    const recorder = args.recorder ?? NOOP_RUN_RECORDER;
+    const errors = [];
+    let outcome = causalAnalysisStageFailure("the causal analysis stage did not complete");
+    const safeLog = (line) => {
+        try {
+            log(line);
+        }
+        catch (error) {
+            errors.push(`the causal analysis logger failed: ${error.message}`);
+        }
+    };
+    try {
+        safeLog("causal analysis: starting");
+        const base = await resolveProgramDiffBase({ root, git, isRepository, runStartCommit });
+        const diff = base === undefined
+            ? ""
+            : await timed(recorder, { stage: "git-diff" }, () => git.diffSince(root, base));
+        // Taken before the analyzer spawns (§3.2 of the WS-05 spec): the pass is
+        // briefed from the run as it stood at this instant, so it never reasons
+        // about its own review time.
+        const snapshot = recorder.snapshot();
+        // The program document's own narrative — SC-12 requires the analyzer to
+        // consume the plan, not just the manifest's roster/success-criteria
+        // fields. Read fail-open: a missing or unreadable document is an honest
+        // gap in the brief, never a thrown stage (SC-13).
+        const programNarrative = await readFile(join(root, "docs", "programs", `${programId}-program.md`), "utf8").catch(() => undefined);
+        // Every workstream's own spec file — SC-12 requires the analyzer to
+        // consume the specifications themselves, not merely a path to them. Read
+        // fail-open per workstream: a missing or unreadable spec is an honest
+        // gap for that workstream, never a thrown stage (SC-13).
+        const workstreamSpecs = await Promise.all(manifest.workstreams.map(async (workstream) => {
+            const spec = await readFile(join(root, workstream.taskFile), "utf8").catch(() => undefined);
+            return {
+                id: workstream.id,
+                name: workstream.name,
+                taskFile: workstream.taskFile,
+                ...(spec === undefined ? {} : { spec }),
+            };
+        }));
+        outcome = await runCausalAnalysis({
+            root,
+            programId,
+            manifest,
+            config,
+            agentRunner,
+            permits,
+            recorder,
+            snapshot,
+            ledger,
+            workstreams: causalAnalysisTimeline(results),
+            diff,
+            workstreamSpecs,
+            ...(base === undefined ? {} : { baseCommit: base }),
+            ...(programNarrative === undefined ? {} : { programNarrative }),
+            log,
+        });
+        safeLog(`causal analysis: ${outcome.status}${outcome.reason ? ` — ${outcome.reason}` : ""}`);
+    }
+    catch (error) {
+        errors.push(`the causal analysis stage failed unexpectedly: ${error.message}`);
+    }
+    return { outcome, errors };
+}
+/**
+ * Fail-open durable write of one *executed* verify command's captured output
+ * (WS-02, SC-05) to a gitignored `build-logs/<programId>/verify/` file,
+ * returned as a `transcript` evidence ref for that command's span. Never
+ * throws: a write failure (full disk, EACCES) simply omits the evidence ref,
+ * never the span or the run (SC-13).
+ */
+async function writeVerifyOutputEvidence(root, programId, label, output) {
+    try {
+        const dir = join(root, "build-logs", programId, "verify");
+        await mkdir(dir, { recursive: true });
+        const fileName = `${label}-${randomBytes(4).toString("hex")}.log`;
+        await writeFile(join(dir, fileName), output, "utf8");
+        return {
+            kind: "transcript",
+            locality: "local",
+            ref: `build-logs/${programId}/verify/${fileName}`,
+            note: "verify output",
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Runs every configured verify command once, first non-zero wins — same
+ * behavior as before WS-02, but the emission model changed (§3.4.a): rather
+ * than one span for the whole pass, this emits one `verification-command` /
+ * `baseline-verification` span per *executed* command, as depth-1 tiling
+ * siblings (never a pass wrapper), so repeated full-suite cost and its
+ * evidence are visible per command. A non-zero `agentExitCode` runs no
+ * commands and emits no span at all — that attempt's failure is already
+ * carried by its own `attempt-outcome` point (§3.3), so there is no
+ * verification observation to fabricate. A command short-circuited by an
+ * earlier command's failure is likewise absent, never a measured zero.
+ * `stage` distinguishes the untouched-tree baseline check (preflight bucket)
+ * from every configured command that follows an agent's own attempt
+ * (verification bucket); `phase` names the invocation (`baseline`,
+ * `post-implementer`, `test-critique-fix`, …) as each command span's
+ * `attemptReason`. `programId`, when given, durably writes each executed
+ * command's captured output as `transcript` evidence; a caller with no
+ * `programId` (a bare test double) simply carries no evidence ref.
+ * `role`/`attemptSeat`/`attemptIndex` carry the triggering attempt's own
+ * dimensions (SC-05/SC-06) so a repeated verify pass can be uniquely
+ * correlated back to the attempt that provoked it, not just its phase.
+ */
+async function verifyAttempt(config, verifyRunner, 
+/** The tree the verify commands actually run against (WS-02) — a
+ *  workstream's worktree during a build, `root` for the baseline. Also the
+ *  tree the verify cache keys on (WS-09) — see the `cwd-in-key` decision. */
+cwd, 
+/** Where verify-output evidence is written (WS-02) — always `root`, so a
+ *  worktree never contains runner-owned transcripts. */
+evidenceRoot, agentExitCode, recorder = NOOP_RUN_RECORDER, stage = "verification-command", opts = {}) {
     if (agentExitCode !== 0) {
         return `agent exited with code ${agentExitCode}`;
     }
-    for (const [name, command] of Object.entries(config.verify)) {
-        const result = await verifyRunner(command, root);
+    const { programId, phase, workstream, role, attemptSeat, attemptIndex, cache } = opts;
+    const commands = Object.entries(config.verify);
+    if (commands.length === 0)
+        return undefined;
+    const cacheDims = {
+        stage,
+        ...(phase === undefined ? {} : { attemptReason: phase }),
+        ...(workstream === undefined ? {} : { workstream }),
+    };
+    const key = await cache?.keyFor(cwd);
+    const hit = key === undefined ? undefined : cache?.get(key);
+    if (hit !== undefined) {
+        for (const [name] of commands) {
+            const span = recorder.span({
+                stage,
+                verifyCommand: name,
+                ...(phase === undefined ? {} : { attemptReason: phase }),
+                ...(workstream === undefined ? {} : { workstream }),
+                ...(role === undefined ? {} : { role }),
+                ...(attemptSeat === undefined ? {} : { attemptSeat }),
+                ...(attemptIndex === undefined ? {} : { attemptIndex }),
+            });
+            const cached = hit.evidence.get(name);
+            const evidence = cached && cached.length > 0
+                ? cached.map((ref) => ({
+                    ...ref,
+                    note: `verify output (cached from the ${hit.phase} pass)`,
+                }))
+                : undefined;
+            span.close({ outcome: "skipped", ...(evidence ? { evidence } : {}) });
+        }
+        recorder.point({
+            kind: "verify-cache",
+            coverage: "observed",
+            label: "hit",
+            detail: hit.phase,
+            dimensions: cacheDims,
+        });
+        return undefined;
+    }
+    if (key !== undefined) {
+        recorder.point({ kind: "verify-cache", coverage: "observed", label: "miss", dimensions: cacheDims });
+    }
+    const evidenceByCommand = new Map();
+    for (const [name, command] of commands) {
+        const span = recorder.span({
+            stage,
+            verifyCommand: name,
+            ...(phase === undefined ? {} : { attemptReason: phase }),
+            ...(workstream === undefined ? {} : { workstream }),
+            ...(role === undefined ? {} : { role }),
+            ...(attemptSeat === undefined ? {} : { attemptSeat }),
+            ...(attemptIndex === undefined ? {} : { attemptIndex }),
+        });
+        let result;
+        try {
+            result = await verifyRunner(command, cwd);
+        }
+        catch (error) {
+            span.close({ outcome: "failed" });
+            throw error;
+        }
+        const evidenceRef = programId === undefined
+            ? undefined
+            : await writeVerifyOutputEvidence(evidenceRoot, programId, `${phase ?? stage}-${name}`, result.output);
+        const evidence = evidenceRef ? [evidenceRef] : undefined;
         if (result.exitCode !== 0) {
+            span.close({ outcome: "failed", ...(evidence ? { evidence } : {}) });
             return `verify \`${name}\` (${command}) exited ${result.exitCode}:\n${tail(result.output, 1500)}`;
         }
+        span.close({ outcome: "success", ...(evidence ? { evidence } : {}) });
+        evidenceByCommand.set(name, evidence ?? []);
+    }
+    if (key !== undefined && cache !== undefined) {
+        const settled = await cache.keyFor(cwd);
+        if (settled === key) {
+            cache.set(key, { evidence: evidenceByCommand, phase: phase ?? stage });
+        }
+        else {
+            recorder.point({
+                kind: "verify-cache",
+                coverage: "observed",
+                label: "not-cached",
+                detail: "commands-changed-the-tree",
+                dimensions: cacheDims,
+            });
+        }
     }
     return undefined;
 }
@@ -1692,12 +3142,24 @@ function failureDiagnosisBrief(manifest, workstream, spec, diff, failure) {
  * undefined and the retry proceeds on the raw verify output alone.
  */
 async function diagnoseFailure(options) {
-    const { root, manifest, workstream, spec, agentRunner, permits, reviewer, git, baseCommit, failure, observe } = 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 { cwd, manifest, workstream, spec, agentRunner, permits, reviewer, git, baseCommit, failure, observe } = options;
+    const recorder = options.recorder ?? NOOP_RUN_RECORDER;
+    const rawDiff = baseCommit !== undefined
+        ? await timed(recorder, { stage: "git-diff", workstream: workstream.id }, () => git.diffSince(cwd, baseCommit))
+        : "";
+    const clippedSpec = clipForReview(spec, "spec");
+    const clippedDiff = clipForReview(rawDiff, "diff");
+    recorder.point(clippedInputPoint("failure-diagnosis-spec", spec, clippedSpec.text, { role: "reviewerAgent" }));
+    recorder.point(clippedInputPoint("failure-diagnosis-diff", rawDiff, clippedDiff.text, { role: "reviewerAgent" }));
+    const brief = failureDiagnosisBrief(manifest, workstream, clippedSpec.text, clippedDiff.text, failure);
     let invocation;
     try {
-        invocation = await invokeAgent(agentRunner, reviewer, brief, root, permits, "reviewerAgent", observe);
+        invocation = await invokeAgent(agentRunner, reviewer, brief, cwd, permits, "reviewerAgent", observe, recorder, {
+            stage: "failure-diagnosis",
+            workstream: workstream.id,
+            ...(options.attemptSeat === undefined ? {} : { attemptSeat: options.attemptSeat }),
+            ...(options.attemptIndex === undefined ? {} : { attemptIndex: options.attemptIndex }),
+        });
     }
     catch (error) {
         return {
@@ -1828,27 +3290,61 @@ function findingEvidenceLine(finding) {
         .join("; ");
     return evidence === "" ? "" : `  Evidence: ${evidence}`;
 }
-/**
- * The implementer's fix re-brief: this round's triaged findings in prose,
- * inviting judgment rather than demanding compliance — the manual workflow's
- * own framing (WS-03 design §2). Never asks the implementer to commit or to
- * echo a block back.
- */
-function testCritiqueFixBrief(workstream, spec, findings) {
-    const findingsList = findings.map((finding) => [
+function findingsListLines(findings) {
+    return findings.map((finding) => [
         `- **${finding.severity}** (${finding.category}) ${finding.subject}: ${finding.message}`,
         findingEvidenceLine(finding),
     ]
         .filter((line) => line !== "")
         .join("\n"));
+}
+/**
+ * The implementer's fix re-brief (WS-09 §3.5.1): `binding` is the decider's
+ * `fix-now` triage — a required correction — and `advisory` is everything
+ * else the reviewer raised this cycle, left to the fixer's judgment. Never
+ * asks the implementer to commit or to echo a block back.
+ */
+function testCritiqueFixBrief(workstream, spec, binding, advisory, resumed, deciderConfigured) {
+    const bindingSection = binding.length > 0
+        ? [
+            "## The decider ruled: fix these now",
+            "",
+            "An independent reviewer raised these and the decider triaged them",
+            "as worth one bounded fix attempt before the run proceeds. Apply",
+            "them.",
+            "",
+            ...findingsListLines(binding),
+            "",
+        ]
+        : [];
+    const advisorySection = advisory.length > 0
+        ? [
+            "## Also raised, for your judgment",
+            "",
+            ...(deciderConfigured
+                ? [
+                    "The reviewer raised these too. The decider did not mark them",
+                    "for an immediate fix. Weigh them and apply what you agree",
+                    "with.",
+                ]
+                : [
+                    "No decider is configured for this run, so none of these were",
+                    "triaged. Weigh them and apply what you agree with.",
+                ]),
+            "",
+            ...findingsListLines(advisory),
+            "",
+        ]
+        : [];
     return [
         `# Your tests for ${workstream.id}: ${workstream.name} were reviewed`,
         "",
+        ...(resumed ? [SESSION_CONTINUATION_PREAMBLE] : []),
         "An independent reviewer read the diff you produced — implementation",
-        "and tests together — and raised the following:",
-        "",
-        ...findingsList,
+        "and tests together.",
         "",
+        ...bindingSection,
+        ...advisorySection,
         "## Specification",
         "",
         spec.trim(),
@@ -1862,12 +3358,26 @@ function testCritiqueFixBrief(workstream, spec, findings) {
         "",
         "Never commit — the runner owns commits, verifies your fix itself, and",
         "either keeps it or discards it depending on whether it actually",
-        "verifies. Reply in prose, not a block: what you fixed and what you",
-        "declined, and why.",
+        "verifies. Run only the tests that cover what you changed; the runner",
+        "runs the project's full verify suite after you and gates on it, which",
+        "overrides AGENTS.md's \"verify before claiming completion\" directive",
+        "for this spawn. Reply in prose, not a block: what you fixed and what",
+        "you declined, and why.",
+        "",
+        "You are working in a dedicated git worktree on a per-workstream",
+        "branch. Do not switch branches, and do not edit `docs/programs/` —",
+        "those are the runner's own artifacts and changes to them are",
+        "discarded.",
         "",
         summaryContract(),
     ].join("\n");
 }
+/** Sorted `dirtyPaths` + `untrackedPaths`, joined, for the §3.6
+ *  before/after comparison a fix seat's resumed-spawn fallback guards on. */
+async function treeFingerprint(git, cwd) {
+    const [dirty, untracked] = await Promise.all([git.dirtyPaths(cwd), git.untrackedPaths(cwd)]);
+    return [...dirty].sort().join("\n") + "\u0000" + [...untracked].sort().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
@@ -1875,21 +3385,80 @@ function testCritiqueFixBrief(workstream, spec, findings) {
  * whether (and how many times) this is called.
  */
 async function attemptFix(options) {
-    const { root, programId, workstream, spec, config, agentRunner, permits, verifyRunner, git, agent, findings, greenCommit, label, log, now, observe, } = options;
-    const brief = testCritiqueFixBrief(workstream, spec, findings);
+    const { root, cwd, programId, workstream, spec, config, agentRunner, permits, verifyRunner, git, agent, binding, advisory, deciderConfigured, greenCommit, label, log, now, observe, stage, attemptReason, attemptIndex, } = options;
+    const recorder = options.recorder ?? NOOP_RUN_RECORDER;
     let invocation;
+    let session;
+    let continuity;
+    const preSpawnTree = options.buildSession ? await treeFingerprint(git, cwd) : undefined;
     try {
-        invocation = await invokeAgent(agentRunner, agent, brief, root, permits, "agent", observe);
+        const spawned = await spawnWithSessionContinuity({
+            resume: options.buildSession,
+            spawn: (resume, resumed) => {
+                const brief = testCritiqueFixBrief(workstream, spec, binding, advisory, resumed, deciderConfigured);
+                return invokeAgent(agentRunner, agent, brief, cwd, permits, "agent", observe, recorder, { stage, workstream: workstream.id, attemptSeat: label, attemptIndex, attemptReason }, resume === undefined ? {} : { handle: resume });
+            },
+            untouched: async () => preSpawnTree !== undefined && (await treeFingerprint(git, cwd)) === preSpawnTree,
+            log,
+            observeContinuity: (result) => {
+                continuity = result;
+                try {
+                    recorder.point({
+                        kind: "session-continuity",
+                        coverage: "observed",
+                        label: result.mode,
+                        ...(result.declineReason ? { detail: result.declineReason } : {}),
+                        dimensions: { stage, workstream: workstream.id, role: "agent", attemptSeat: label, attemptIndex, attemptReason },
+                    });
+                }
+                catch (error) {
+                    log(`run-analytics: session continuity point failed: ${error.message}`);
+                }
+            },
+        });
+        invocation = spawned.result;
+        session = spawned.result.session;
+        continuity = spawned.continuity;
     }
     catch (error) {
+        // A rethrow out of `spawnWithSessionContinuity` (WS-08 §3.6) means a
+        // resumed spawn threw *and* it had already touched the tree — the one
+        // case where reaching this catch does not mean "nothing was built".
+        // Reset defensively so a half-applied fix is never left standing; a
+        // plain spawn failure (no resume attempted, or the tree is unchanged)
+        // makes this a no-op reset to the state already there.
+        if (preSpawnTree !== undefined) {
+            try {
+                await git.resetHard(cwd, greenCommit);
+            }
+            catch {
+                // Best-effort: the green state may already be intact, or the reset
+                // itself failed for an unrelated reason; either way this must not
+                // mask the original spawn error being reported below.
+            }
+        }
         const spawnError = `the ${label} implementer could not be spawned: ${error.message}; ` +
             "the fix was not attempted and the green state was preserved.";
+        recorder.point({
+            kind: "attempt-outcome",
+            coverage: "observed",
+            dimensions: {
+                stage,
+                workstream: workstream.id,
+                role: "agent",
+                attemptSeat: label,
+                attemptIndex,
+                attemptReason,
+                outcome: "failed",
+            },
+        });
         return {
             outcome: "failed",
             greenCommit,
             summary: "(fix not attempted — the implementer could not be spawned)",
             failure: spawnError,
             spawnError,
+            ...(continuity ? { continuity } : {}),
         };
     }
     const transcript = invocation.transcript;
@@ -1897,14 +3466,37 @@ async function attemptFix(options) {
     const summary = resolvedSummary.text;
     const denialEvents = buildDenialEvents(workstream.id, label, transcript?.denials ?? [], resolvedSummary.needsPermission, config.permits?.deny ?? [], now().toISOString());
     if (denialEvents.length > 0) {
-        await appendLedgerEvents(root, programId, denialEvents);
+        await timed(recorder, { stage: "ledger-persist", workstream: workstream.id }, () => appendLedgerEvents(root, programId, denialEvents));
         for (const event of denialEvents) {
             if (event.kind !== "permission-denied")
                 continue;
-            log(`${workstream.id} ${label}: denied \`${event.command}\` (${event.source})`);
+            log(`${label}: denied \`${event.command}\` (${event.source})`);
         }
     }
-    const failure = await verifyAttempt(config, verifyRunner, root, invocation.exitCode);
+    const failure = await verifyAttempt(config, verifyRunner, cwd, root, invocation.exitCode, recorder, "verification-command", {
+        programId,
+        phase: stage,
+        workstream: workstream.id,
+        role: "agent",
+        attemptSeat: label,
+        attemptIndex,
+        ...(options.verifyCache ? { cache: options.verifyCache } : {}),
+    });
+    const emitOutcome = (outcome) => {
+        recorder.point({
+            kind: "attempt-outcome",
+            coverage: "observed",
+            dimensions: {
+                stage,
+                workstream: workstream.id,
+                role: "agent",
+                attemptSeat: label,
+                attemptIndex,
+                attemptReason,
+                outcome,
+            },
+        });
+    };
     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
@@ -1915,33 +3507,38 @@ async function attemptFix(options) {
         // 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 dirty = await git.dirtyPaths(cwd);
+        const meaningfulChange = dirty.some((path) => !isRunnerOwnedArtifactPath(path));
         const commit = meaningfulChange
-            ? await git.commitAll(root, `nightshift(${programId}): ${workstream.id} ${label}`)
+            ? await timed(recorder, { stage: "git-commit", workstream: workstream.id }, () => git.commitAll(cwd, `nightshift(${programId}): ${workstream.id} ${label}`, ["docs/programs"]), commitEvidence)
             : undefined;
+        emitOutcome(commit === undefined ? "discarded" : "success");
         return {
             outcome: "kept",
             greenCommit: commit ?? greenCommit,
             ...(commit === undefined ? {} : { commit }),
             summary,
             ...(transcript === undefined ? {} : { transcript }),
+            ...(session === undefined ? {} : { session }),
+            ...(continuity === undefined ? {} : { continuity }),
         };
     }
-    // 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, ...(transcript === undefined ? {} : { transcript }) };
+    // A worktree hazard the pre-WS-02 code guarded against with a
+    // snapshot/restore of docs/programs no longer exists: the runner writes
+    // nothing under docs/programs in a worktree, so a whole-tree
+    // `git reset --hard` here throws away nothing the run's journal at `root`
+    // depends on.
+    await git.resetHard(cwd, greenCommit);
+    emitOutcome("failed");
+    return {
+        outcome: "failed",
+        greenCommit,
+        summary,
+        failure,
+        ...(transcript === undefined ? {} : { transcript }),
+        ...(session === undefined ? {} : { session }),
+        ...(continuity === undefined ? {} : { continuity }),
+    };
 }
 /**
  * The test-critique driver: wires WS-01's bounded review loop to the two
@@ -1951,11 +3548,16 @@ async function attemptFix(options) {
  * failure), so a review can never turn green work red.
  */
 async function runTestCritique(options) {
-    const { root, manifest, workstream, spec, config, agentRunner, permits, verifyRunner, git, reviewer, agent, baseCommit, now, log, transcriptSink, } = options;
+    const { root, cwd, manifest, workstream, spec, config, agentRunner, permits, verifyRunner, git, reviewer, agent, deciderConfigured, baseCommit, now, log, transcriptSink, triage, } = options;
+    const recorder = options.recorder ?? NOOP_RUN_RECORDER;
     let greenCommit = options.greenCommit;
     let diffClipped = false;
     const stageErrors = [];
     const transcripts = [];
+    // WS-08: last-wins across every fix round this pass runs — the next
+    // round resumes whichever round most recently reported a session id.
+    let buildSession = options.buildSession;
+    const continuity = [];
     if (!reviewer) {
         return {
             outcome: reviewerAbsentOutcome(),
@@ -1963,19 +3565,24 @@ async function runTestCritique(options) {
             diffClipped,
             stageErrors,
             transcripts,
+            ...(buildSession ? { buildSession } : {}),
         };
     }
-    const locate = (file) => locateInRepo(root, file);
-    const review = async (_round, priorOpen) => {
-        const rawDiff = baseCommit !== undefined ? await git.diffSince(root, baseCommit) : "";
+    const locate = (file) => locateInRepo(cwd, file);
+    const review = async (round, priorOpen) => {
+        const rawDiff = baseCommit !== undefined
+            ? await timed(recorder, { stage: "git-diff", workstream: workstream.id }, () => git.diffSince(cwd, baseCommit))
+            : "";
         const diff = clipForReview(rawDiff, "diff");
         const clippedSpec = clipForReview(spec, "spec");
         if (diff.clipped || clippedSpec.clipped)
             diffClipped = true;
+        recorder.point(clippedInputPoint("test-critique-diff", rawDiff, diff.text, { role: "reviewerAgent" }));
+        recorder.point(clippedInputPoint("test-critique-spec", spec, clippedSpec.text, { role: "reviewerAgent" }));
         const brief = testCritiqueReviewerBrief(manifest, workstream, clippedSpec.text, diff.text, priorOpen);
         let invocation;
         try {
-            invocation = await invokeAgent(agentRunner, reviewer, brief, root, permits, "reviewerAgent", transcriptSink("test-critique-reviewer"));
+            invocation = await invokeAgent(agentRunner, reviewer, brief, cwd, permits, "reviewerAgent", transcriptSink("test-critique-reviewer"), recorder, { workstream: workstream.id, attemptIndex: round });
         }
         catch (error) {
             // Fail open, matching the existing reviewer-error path: no findings
@@ -1987,11 +3594,11 @@ async function runTestCritique(options) {
         if (invocation.transcript) {
             const denialEvents = buildDenialEvents(workstream.id, "reviewer", invocation.transcript.denials, [], config.permits?.deny ?? [], now().toISOString());
             if (denialEvents.length > 0) {
-                await appendLedgerEvents(root, manifest.program.id, denialEvents);
+                await timed(recorder, { stage: "ledger-persist", workstream: workstream.id }, () => appendLedgerEvents(root, manifest.program.id, denialEvents));
                 for (const event of denialEvents) {
                     if (event.kind !== "permission-denied")
                         continue;
-                    log(`${workstream.id} reviewer: denied \`${event.command}\` (${event.source})`);
+                    log(`reviewer: denied \`${event.command}\` (${event.source})`);
                 }
             }
         }
@@ -2000,9 +3607,56 @@ async function runTestCritique(options) {
         const ran = invocation.exitCode === 0 && hasFindingsBlock(invocation.output);
         return { findings, errors: parsed.errors, ran };
     };
-    const respond = async (_round, findings) => {
+    const respond = async (cycle, findings) => {
+        // Step 1: record. Every routable finding this cycle raised reaches the
+        // ledger — not a post-fix residue (WS-09 §3.5), anchored to the same
+        // durable pre-workstream commit the decider's own diff uses, so a
+        // rendered reference still resolves after this workstream's worktree
+        // and branch are gone (see the comment on `diffSince`'s docs/programs
+        // exclusion for the same worktree-lifetime concern).
+        const routable = findings.filter(hasRoutableEvidence);
+        const events = findingsToLedgerEvents({
+            workstreamId: workstream.id,
+            findings: routable,
+            ...(baseCommit === undefined ? {} : { baseCommit }),
+            now,
+        });
+        await timed(recorder, { stage: "ledger-persist", workstream: workstream.id }, () => appendLedgerEvents(root, manifest.program.id, events));
+        // Step 2: triage — one decider spawn per routed finding, before the fix.
+        stageErrors.push(...(await triage(events, baseCommit)));
+        // Step 3: split. Read the ledger projection *after* triage so this
+        // cycle's `finding-triaged` events are visible. A `human-decided`
+        // finding is dropped entirely — never handed to the fix seam
+        // (`run-program.ts` §2.3/§3.6's invariant, preserved); a `fix-now`
+        // finding with no fix attempt on it yet is binding; everything else
+        // (open, accepted, escalated, or no ledger record at all — an
+        // advisory-only or unverifiable finding) is advisory.
+        const ledger = await readDecisionLedger(root, manifest.program.id);
+        const recordsById = new Map(ledger.findings.map((record) => [record.id, record]));
+        const binding = [];
+        const bindingIds = [];
+        const advisory = [];
+        for (const finding of findings) {
+            const id = fingerprint({ ...finding, workstreamId: workstream.id });
+            const record = recordsById.get(id);
+            if (record?.status === "human-decided")
+                continue;
+            if (record?.status === "fix-now" && record.fixAttempt === undefined) {
+                binding.push(finding);
+                bindingIds.push(id);
+            }
+            else {
+                advisory.push(finding);
+            }
+        }
+        // Step 4: fix. Skipped only when every finding this cycle raised was
+        // already human-decided.
+        if (binding.length === 0 && advisory.length === 0) {
+            return { note: "every finding this cycle raised was already human-decided; no fix pass ran" };
+        }
         const fix = await attemptFix({
             root,
+            cwd,
             programId: manifest.program.id,
             workstream,
             spec,
@@ -2012,27 +3666,83 @@ async function runTestCritique(options) {
             verifyRunner,
             git,
             agent,
-            findings,
+            binding,
+            advisory,
+            deciderConfigured,
             greenCommit,
             label: "test critique fix",
             log,
             now,
             observe: transcriptSink("test-critique-fix"),
+            stage: "test-critique-fix",
+            attemptReason: "triaged-findings",
+            attemptIndex: cycle,
+            recorder,
+            ...(options.verifyCache ? { verifyCache: options.verifyCache } : {}),
+            ...(buildSession ? { buildSession } : {}),
         });
         greenCommit = fix.greenCommit;
         if (fix.transcript)
             transcripts.push(fix.transcript);
         if (fix.spawnError !== undefined)
             stageErrors.push(fix.spawnError);
+        if (fix.session)
+            buildSession = fix.session;
+        if (fix.continuity)
+            continuity.push(fix.continuity);
+        // Step 5: journal the fix-now outcome. One `finding-fix-attempted` per
+        // binding id, exactly `driveFixNowFindings`'s old rule: "kept" requires
+        // both a clean verify and a landed commit — a clean-but-empty attempt is
+        // a decline, not a fix. The merged fix also covers `advisory` findings
+        // in the same spawn, so a commit does not prove any one binding finding
+        // was addressed (the ledger projection already disclaims per-finding
+        // proof); the note is prefixed with the binding subjects so a human
+        // reading the ledger sees both the instruction and the reply, never
+        // inferred from the fixer's prose.
+        if (bindingIds.length > 0) {
+            const kept = fix.outcome === "kept" && fix.commit !== undefined;
+            const bindingSubjects = binding.map((finding) => finding.subject).join(", ");
+            const note = kept
+                ? `(fix-now: ${bindingSubjects}) ${fix.summary}`
+                : fix.outcome === "kept"
+                    ? `(fix-now: ${bindingSubjects}) ${fix.summary} (the attempt verified clean but made no change; no fix landed)`
+                    : `(fix-now: ${bindingSubjects}) ${fix.summary} (fix failed verification and was discarded: ${fix.failure})`;
+            const fixNowEvents = bindingIds.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 timed(recorder, { stage: "ledger-persist", workstream: workstream.id }, () => appendLedgerEvents(root, manifest.program.id, fixNowEvents));
+            log(kept
+                ? "fix-now finding(s) verified and committed"
+                : `fix-now finding(s) failed and were escalated — ${note}`);
+        }
         if (fix.outcome === "kept") {
-            log(`${workstream.id}: test critique fix verified and committed`);
+            log("test critique fix verified and committed");
             return { note: `${fix.summary} (fix verified and committed)` };
         }
-        log(`${workstream.id}: test critique fix failed verification and was discarded — ${fix.failure}`);
+        log(`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, stageErrors, transcripts };
+    const outcome = await runReviewPass({
+        cycles: TEST_CRITIQUE_CYCLES,
+        cycleNote: TEST_CRITIQUE_CYCLE_NOTE,
+        review,
+        respond,
+    });
+    return {
+        outcome,
+        finalCommit: greenCommit,
+        diffClipped,
+        stageErrors,
+        transcripts,
+        ...(buildSession ? { buildSession } : {}),
+        ...(continuity.length > 0 ? { continuity } : {}),
+    };
 }
 function renderSpecsSection(authorResult) {
     if (authorResult.results.length === 0)
@@ -2067,7 +3777,7 @@ function renderSpecsSection(authorResult) {
             lines.push(...notes.map((note) => `- ${note}`), "");
         }
         if (entry.specCritique) {
-            lines.push(...renderPassReport("Spec critique", entry.specCritique), "");
+            lines.push(...renderPassReport("Spec critique", entry.specCritique, "runner spec check"), "");
         }
     }
     return lines;
@@ -2314,6 +4024,25 @@ function renderWorkstreamCommands(result) {
     }
     return lines;
 }
+/**
+ * States a fix seat's session-resume fallback where a human will see it
+ * (WS-08 §3.11) — nothing is added when every requesting seat resumed
+ * cleanly, so a clean run's report is unchanged.
+ */
+function renderSessionContinuityFallbacks(result) {
+    const lines = [];
+    for (const entry of result.sessionContinuity ?? []) {
+        if (entry.continuity.mode !== "fresh" || entry.continuity.declineReason === undefined)
+            continue;
+        const reason = describeSessionDecline(entry.continuity.declineReason, {
+            producerCommand: entry.producerCommand,
+            seatCommand: entry.seatCommand,
+        });
+        lines.push(`  - The ${entry.seat} could not continue the implementer's session (${reason}); ` +
+            "a fresh agent applied the findings instead.");
+    }
+    return lines;
+}
 /**
  * The program-level `## Commands denied` section (SC-12): every
  * `permission-denied` ledger record, grouped by workstream in the run's own
@@ -2350,7 +4079,11 @@ function renderCommandsDeniedSection(results, ledger, programId) {
     }
     return lines;
 }
-export function renderRunReport(manifest, results, ledger, triagedThisRun, authorResult, at, wholeProgram, preflight, resumeCommand, manifestAmended) {
+export function renderRunReport(manifest, results, ledger, triagedThisRun, authorResult, at, wholeProgram, preflight, resumeCommand, manifestAmended, 
+/** Pre-rendered "Where the time went" lines (WS-04), computed and isolated by the caller via `renderAnalyticsSection`. Omitted entirely, this function's output is unchanged from before WS-04. */
+analyticsSection, 
+/** Pre-rendered "Why the time went there" lines (WS-05), computed and isolated by the caller via `renderCausalAnalysisSection`. Omitted entirely, this function's output is unchanged from before WS-05. */
+causalAnalysisSection) {
     const programId = manifest.program.id;
     const built = results.filter((result) => result.outcome.status === "complete" ||
         result.outcome.status === "skipped").length;
@@ -2395,6 +4128,12 @@ export function renderRunReport(manifest, results, ledger, triagedThisRun, autho
             for (const diagnosis of result.failureDiagnoses ?? []) {
                 lines.push(`**Reviewer diagnosis (after the ${diagnosis.attempt} attempt):**`, "", diagnosis.verdict, "");
             }
+            if (result.worktreePath !== undefined) {
+                lines.push(`Worktree retained at \`${result.worktreePath}\`.`, "");
+            }
+            if (result.retainedRef !== undefined) {
+                lines.push(`Verified commit retained at \`${result.retainedRef}\`.`, "");
+            }
             const workstreamDenials = ledger.denials.filter((denial) => denial.workstream === result.id);
             if (workstreamDenials.length > 0) {
                 lines.push("Commands denied: " +
@@ -2428,6 +4167,7 @@ export function renderRunReport(manifest, results, ledger, triagedThisRun, autho
         if (result.outcome.status === "complete" || result.outcome.status === "failed") {
             lines.push(...renderWorkstreamCommands(result));
         }
+        lines.push(...renderSessionContinuityFallbacks(result));
     }
     lines.push("");
     if (wholeProgram !== undefined) {
@@ -2459,6 +4199,12 @@ export function renderRunReport(manifest, results, ledger, triagedThisRun, autho
             "workstream's own outcome is unaffected, but the reason it fell " +
             "open belongs here.", "", ...stageErrors.map((error) => `- ${error}`), "");
     }
+    if (analyticsSection !== undefined) {
+        lines.push(...analyticsSection);
+    }
+    if (causalAnalysisSection !== undefined) {
+        lines.push(...causalAnalysisSection);
+    }
     return lines.join("\n");
 }
 //# sourceMappingURL=run-program.js.map