@wildorder/nightshift 0.13.0 → 0.14.0

package/dist/run-program.js

@@ -2,27 +2,109 @@ import { execFile } from "node:child_process";
 import { readFile, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { promisify } from "node:util";
-import { defaultAgentRunner, defaultVerifyRunner, describeAgent, invokeAgent, resolveAgent, resolveDeciderAgent, resolveRecoveryAgent, resolveReviewerAgent, tail, } from "./agent-runner.js";
+import { defaultAgentRunner, defaultVerifyRunner, describeAgent, invokeAgent, resolveAgent, resolveAuthorAgent, resolveDeciderAgent, resolveRecoveryAgent, resolveReviewerAgent, tail, } from "./agent-runner.js";
 import { resolveSummary, summaryContract } from "./agent-summary.js";
 import { authorProgram } from "./author.js";
 import { decisionContract, decisionFingerprint, extractDecisions, } from "./decision.js";
-import { appendLedgerEvents, readDecisionLedger, } from "./decision-ledger.js";
-import { escalatedRecords, renderRecord, } from "./decision-view.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 { loadManifest, saveManifest, } from "./manifest.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 { verifyAccessWarning } from "./verify-allowlist.js";
+import { buildPermitsContext } from "./permits.js";
 import { CouldNotStartError } from "./exit-codes.js";
 import { runReportPath } from "./report-path.js";
 import { AS_BUILT_PATH, runWholeProgramReview, renderWholeProgramReview, } from "./whole-program-review.js";
 const execFileAsync = promisify(execFile);
 /** Matches every wording git uses to report an empty commit attempt. */
 const NOTHING_TO_COMMIT = /nothing to commit|nothing added to commit|no changes added to commit/u;
+/**
+ * Attributes a transcript denial's source: `"deny-rule"` when the command
+ * matches an operator-authored `permits.deny` rule, `"classifier"`
+ * otherwise. The Claude stream does not reliably distinguish the two
+ * mechanisms, so this is derived rather than carried from WS-02.
+ *
+ * A bounded matcher, not a permission-rules engine: it recognizes only the
+ * `Bash(...)` shapes nightshift itself emits and the CLI documents —
+ * colon-wildcard (`Bash(<prefix>:*)`), space-wildcard (`Bash(<prefix> *)`),
+ * and exact (`Bash(<cmd>)`), each with a word-boundary prefix match so
+ * `Bash(git push:*)` does not match `git pushx`. Every rule it does not
+ * recognize (a non-`Bash(...)` rule, or an inner shape matching none of the
+ * three) is skipped, defaulting the denial to `"classifier"` — the safe
+ * direction, since an over-attribution to `classifier` at worst prints an
+ * allow-rule remediation, the safe remediation to print when the mechanism
+ * is unconfirmed.
+ */
+export function attributeDenialSource(command, denyRules) {
+    for (const rule of denyRules) {
+        const match = /^Bash\((.+)\)$/iu.exec(rule.trim());
+        if (!match)
+            continue;
+        const inner = match[1] ?? "";
+        let prefix;
+        if (inner.endsWith(":*"))
+            prefix = inner.slice(0, -2);
+        else if (inner.endsWith(" *"))
+            prefix = inner.slice(0, -2);
+        if (prefix !== undefined) {
+            if (command === prefix || command.startsWith(`${prefix} `))
+                return "deny-rule";
+            continue;
+        }
+        if (command === inner)
+            return "deny-rule";
+    }
+    return "classifier";
+}
+/**
+ * Correlates one spawn's observed transcript denials with the agent's own
+ * `needs-permission` self-reports into one `permission-denied` ledger event
+ * per command (SC-12). An agent report naming the same command as an
+ * observed denial attaches as `agentReason` on that observed record rather
+ * than creating a second one; an agent report with no matching observed
+ * denial (an unobserved provider, or a command the CLI denied without
+ * surfacing it) gets its own `agent-report` record. `needsPermission` is
+ * empty for a read-only reviewer/decider spawn, where an agent-report record
+ * never arises.
+ */
+function buildDenialEvents(workstreamId, attempt, denials, needsPermission, denyRules, at) {
+    const events = [];
+    const observedCommands = new Set(denials.map((denial) => denial.command));
+    for (const denial of denials) {
+        const agentMatch = needsPermission.find((need) => need.command === denial.command);
+        events.push({
+            kind: "permission-denied",
+            at,
+            id: denialFingerprint(workstreamId, attempt, denial.command),
+            workstream: workstreamId,
+            attempt,
+            command: denial.command,
+            source: attributeDenialSource(denial.command, denyRules),
+            reason: denial.reason,
+            ...(agentMatch?.reason === undefined ? {} : { agentReason: agentMatch.reason }),
+        });
+    }
+    for (const need of needsPermission) {
+        if (observedCommands.has(need.command))
+            continue;
+        events.push({
+            kind: "permission-denied",
+            at,
+            id: denialFingerprint(workstreamId, attempt, need.command),
+            workstream: workstreamId,
+            attempt,
+            command: need.command,
+            source: "agent-report",
+            ...(need.reason === undefined ? {} : { agentReason: need.reason }),
+        });
+    }
+    return events;
+}
 export const defaultGitOps = {
     async isRepository(cwd) {
         try {
@@ -198,7 +280,38 @@ function findingsRuledOnSection(records) {
         return [];
     return ["## Findings ruled on", "", ...lines, ""];
 }
-function implementerBrief(manifest, workstream, spec, ledger, priorFailure, priorDiagnosis) {
+/**
+ * The Shell policy section (SC-11): the operator's own policy prose,
+ * verbatim, when set, and — always — the rule that turns a denied command
+ * into a reported fact rather than an obstacle to route around. Placed in
+ * the working contract (before the decision/summary contracts) so it reaches
+ * every provider alike: the Claude `auto` classifier judges an action
+ * against the request it can see, and codex has no classifier but still
+ * reads the same prose.
+ */
+function shellPolicySection(shellPolicy) {
+    const policyLines = shellPolicy === undefined || shellPolicy.trim() === ""
+        ? []
+        : ["Your operator set this shell policy for this run:", "", shellPolicy, ""];
+    return [
+        "## Shell policy",
+        "",
+        ...policyLines,
+        "If a shell command you need is denied, do not work around it, retry it",
+        "a different way, or abandon the fix silently. Report it. In your",
+        "summary block, add one `needs-permission:` line naming the exact",
+        "command, and a following `because:` line naming why you needed it. One",
+        "pair per denied command:",
+        "",
+        "```summary",
+        "...",
+        "needs-permission: npm install left-pad",
+        "because: the fixture needs a dev dependency that isn't installed.",
+        "```",
+        "",
+    ];
+}
+function implementerBrief(manifest, workstream, spec, ledger, shellPolicy, priorFailure, priorDiagnosis) {
     const roster = manifest.workstreams
         .map((entry) => {
         const scope = entry.scope?.summary ?? entry.name;
@@ -261,6 +374,7 @@ function implementerBrief(manifest, workstream, spec, ledger, priorFailure, prio
         "  independently afterwards and your claim of success is never trusted",
         "  without it.",
         "",
+        ...shellPolicySection(shellPolicy),
         decisionContract(),
         "",
         summaryContract(),
@@ -332,6 +446,52 @@ export function downstreamCone(workstreams, rootIds) {
         cone.delete(id);
     return cone;
 }
+/**
+ * The `permissions:` startup lines (WS-01 SC-07): one per distinct derived
+ * invocation, naming the role(s) that share it, the containment in effect,
+ * and the settings file it reads when one applies. `recovery.agent` and
+ * `resolveAuthorAgent(config)`'s agent both carry a guaranteed fallback to
+ * the implementer, so a solo setup with only `agent` configured naturally
+ * dedupes into one line covering all three roles.
+ */
+async function permissionsStartupLines(config, permits, agent, recovery, decider, reviewer) {
+    const author = resolveAuthorAgent(config);
+    const roles = [
+        { role: "agent", agentConfig: agent },
+        { role: "recoveryAgent", agentConfig: recovery?.agent },
+        { role: "authorAgent", agentConfig: author?.agent },
+        { role: "deciderAgent", agentConfig: decider },
+        { role: "reviewerAgent", agentConfig: reviewer },
+    ];
+    const distinct = new Map();
+    for (const { role, agentConfig } of roles) {
+        if (!agentConfig)
+            continue;
+        const derived = await permits.derive(role, agentConfig);
+        const key = JSON.stringify([derived.agent.command, derived.agent.args, derived.agent.promptMode]);
+        const entry = distinct.get(key);
+        if (entry)
+            entry.roles.push(role);
+        else {
+            distinct.set(key, {
+                roles: [role],
+                label: derived.label,
+                ...(derived.settingsPath === undefined ? {} : { settingsPath: derived.settingsPath }),
+                ...(derived.note === undefined ? {} : { note: derived.note }),
+            });
+        }
+    }
+    const lines = [];
+    for (const entry of distinct.values()) {
+        const parts = [`permissions: ${entry.roles.join(", ")}: ${entry.label}`];
+        if (entry.settingsPath !== undefined)
+            parts.push(`settings: ${entry.settingsPath}`);
+        if (entry.note !== undefined)
+            parts.push(entry.note);
+        lines.push(parts.join(" — "));
+    }
+    return lines;
+}
 /**
  * The decide-and-continue runner.
  *
@@ -343,6 +503,23 @@ export function downstreamCone(workstreams, rootIds) {
  * verify commands itself, and writes the run report last, whatever happened.
  */
 export async function runProgram(options) {
+    // A caller-supplied context is the caller's to dispose. One this run builds
+    // for itself is removed on every exit path — a could-not-start refusal, a
+    // crash mid-run, or the normal return — which is why the build sits in a
+    // thin wrapper around the run rather than inside it: the run's body
+    // declares its stage functions after its return statement, and a try/finally
+    // inside it would take every shared variable out of their scope.
+    if (options.permits !== undefined)
+        return runProgramWith(options, options.permits);
+    const permits = await buildPermitsContext({ config: options.config });
+    try {
+        return await runProgramWith(options, permits);
+    }
+    finally {
+        await permits.dispose?.();
+    }
+}
+async function runProgramWith(options, permits) {
     const root = resolve(options.cwd);
     const config = options.config;
     const agentRunner = options.agentRunner ?? defaultAgentRunner;
@@ -357,6 +534,11 @@ export async function runProgram(options) {
     catch (error) {
         throw new CouldNotStartError(error.message, { cause: error });
     }
+    // Snapshotted once, right after the initial load, rather than cleared on
+    // any later reload (e.g. the post-authoring reload below) — so a merge
+    // during authoring is still visible in the report-time comparison, and a
+    // second run in the same test process starts from its own baseline.
+    const mergesAtStart = manifestMergeCount(root, options.programId);
     const resolvedAgent = resolveAgent(config);
     if (!resolvedAgent) {
         throw new CouldNotStartError("No implementer configured. Set the `agent` block in nightshift.config.json.");
@@ -366,15 +548,21 @@ export async function runProgram(options) {
     const decider = resolveDeciderAgent(config);
     const reviewer = resolveReviewerAgent(config);
     log(`implementer: ${describeAgent(agent)}`);
-    const sandboxWarning = verifyAccessWarning(agent, config.verify);
-    if (sandboxWarning !== undefined)
-        log(`warning: ${sandboxWarning}`);
     log(decider
         ? `decider: ${describeAgent(decider)}`
         : "decider: none configured — implementer defaults will stand unratified");
     log(reviewer
         ? `reviewer (test critique, whole-program review): ${describeAgent(reviewer)}`
         : "reviewer: none configured — test critique and the whole-program review are disabled");
+    // Built once, for this whole run (by the wrapper above): the containment
+    // nightshift derives for every agent spawn (WS-01). Threaded explicitly
+    // into every nested stage and every invokeAgent call this function owns,
+    // rather than rebuilt per stage — a per-stage rebuild would write several
+    // settings files and print a startup line describing a context later
+    // spawns do not actually use.
+    for (const line of await permissionsStartupLines(config, permits, agent, recovery, decider, reviewer)) {
+        log(line);
+    }
     const cycles = findCycles(manifest.workstreams);
     if (cycles.length > 0) {
         // A cyclic graph cannot be ordered; this is a planning defect, not a
@@ -522,7 +710,7 @@ export async function runProgram(options) {
     // mutates neither the manifest nor the ledger.
     if (preflight.events.length > 0) {
         await appendLedgerEvents(root, options.programId, preflight.events);
-        await saveManifest(root, options.programId, manifest);
+        await 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
@@ -545,6 +733,7 @@ export async function runProgram(options) {
         programId: options.programId,
         config,
         agentRunner,
+        permits,
         git,
         log,
         now,
@@ -620,7 +809,7 @@ export async function runProgram(options) {
         // 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);
+            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.`
@@ -680,13 +869,14 @@ export async function runProgram(options) {
         : intermission
             ? "awaiting_human"
             : "partial";
-    await saveManifest(root, options.programId, manifest);
+    await saveManifest(root, options.programId, manifest, { log });
     const wholeProgram = await runWholeProgramStage({
         root,
         programId: options.programId,
         manifest,
         config,
         agentRunner,
+        permits,
         git,
         isRepository,
         results,
@@ -715,7 +905,7 @@ export async function runProgram(options) {
         // 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), "utf8");
+        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"]);
         }
@@ -740,7 +930,18 @@ export async function runProgram(options) {
             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");
@@ -753,7 +954,7 @@ export async function runProgram(options) {
             return base;
         }
         workstream.status = "in_progress";
-        await saveManifest(root, options.programId, manifest);
+        await saveManifest(root, options.programId, manifest, { log });
         const baseCommit = isRepository
             ? await git.currentCommit(root)
             : undefined;
@@ -761,10 +962,10 @@ export async function runProgram(options) {
         let priorDiagnosis;
         let implementerFingerprint;
         const attempts = [
-            { agent, label: "implementer" },
+            { agent, label: "implementer", role: "agent" },
         ];
         if (recovery && !recovery.borrowedImplementer) {
-            attempts.push({ agent: recovery.agent, label: "recovery" });
+            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
@@ -772,14 +973,31 @@ export async function runProgram(options) {
             // the reviewer's diagnosis in hand, a composition neither prior
             // attempt had.
             if (reviewer)
-                attempts.push({ agent, label: "informed retry" });
+                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, priorFailure, priorDiagnosis);
-            const invocation = await invokeAgent(agentRunner, attempt.agent, brief, root);
+            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);
@@ -789,6 +1007,13 @@ export async function runProgram(options) {
             // 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.
@@ -836,6 +1061,7 @@ export async function runProgram(options) {
                         spec,
                         config,
                         agentRunner,
+                        permits,
                         verifyRunner,
                         git,
                         reviewer,
@@ -844,12 +1070,18 @@ export async function runProgram(options) {
                         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.
@@ -867,23 +1099,35 @@ export async function runProgram(options) {
                 workstream.status = "complete";
                 if (finalCommit !== undefined)
                     workstream.commit = finalCommit;
-                await saveManifest(root, options.programId, manifest);
-                await reviewWorkstreamDecisions(workstream.id, parsed.decisions, baseCommit);
+                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.
-                await reviewWorkstreamFindings(workstream.id, findingEvents, baseCommit);
+                {
+                    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);
-                    if (driven !== finalCommit) {
-                        finalCommit = driven;
+                    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);
+                        await saveManifest(root, options.programId, manifest, { log });
                     }
                 }
                 if (critique)
@@ -907,8 +1151,12 @@ export async function runProgram(options) {
                 !resumedIds.has(workstream.id) &&
                 failureFingerprint(failure) === baselineFingerprint) {
                 workstream.status = "failed";
-                await saveManifest(root, options.programId, manifest);
-                await reviewWorkstreamDecisions(workstream.id, parsed.decisions, baseCommit);
+                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",
@@ -930,10 +1178,14 @@ export async function runProgram(options) {
                 failureFingerprint(failure) === implementerFingerprint;
             if (index === attempts.length - 1 || stuck) {
                 workstream.status = "failed";
-                await saveManifest(root, options.programId, manifest);
+                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.
-                await reviewWorkstreamDecisions(workstream.id, parsed.decisions, baseCommit);
+                {
+                    const spawnErrors = await reviewWorkstreamDecisions(workstream.id, parsed.decisions, baseCommit);
+                    if (spawnErrors.length > 0)
+                        (base.stageErrors ??= []).push(...spawnErrors);
+                }
                 base.outcome = {
                     status: "failed",
                     reason: stuck
@@ -953,19 +1205,30 @@ export async function runProgram(options) {
             // 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.
-            priorDiagnosis = reviewer && !deterministicFailure
-                ? await diagnoseFailure({
+            if (reviewer && !deterministicFailure) {
+                const diagnosed = await diagnoseFailure({
                     root,
                     manifest,
                     workstream,
                     spec,
                     agentRunner,
+                    permits,
                     reviewer,
                     git,
                     baseCommit,
                     failure,
-                })
-                : undefined;
+                    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);
+            }
+            else {
+                priorDiagnosis = undefined;
+            }
             if (priorDiagnosis !== undefined) {
                 (base.failureDiagnoses ??= []).push({
                     attempt: attempt.label,
@@ -991,6 +1254,23 @@ export async function runProgram(options) {
             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")
+                continue;
+            log(`${workstreamId} ${attempt}: denied \`${event.command}\` (${event.source})`);
+        }
+    }
     function reviewWorkstreamDecisions(workstreamId, decisions, baseCommit) {
         return reviewDecisions({
             root,
@@ -1001,12 +1281,15 @@ export async function runProgram(options) {
             baseCommit,
             decider,
             agentRunner,
+            permits,
             git,
             isRepository,
             reviewed,
+            onTranscript: (transcript) => journalDenials(workstreamId, "decider", transcript),
             triaged,
             now,
             log,
+            observe: { root, programId: options.programId, label: `${workstreamId}-decider-decision`, log },
         });
     }
     function reviewWorkstreamFindings(workstreamId, findings, baseCommit) {
@@ -1019,9 +1302,12 @@ export async function runProgram(options) {
             baseCommit,
             decider,
             agentRunner,
+            permits,
             git,
             isRepository,
             reviewed,
+            observe: { root, programId: options.programId, label: `${workstreamId}-decider-finding`, log },
+            onTranscript: (transcript) => journalDenials(workstreamId, "decider", transcript),
             triaged,
             now,
             log,
@@ -1037,13 +1323,13 @@ export async function runProgram(options) {
      * 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) {
+    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 greenCommit;
+            return { commit: greenCommit };
         const toFix = [];
         const matchedIds = [];
         for (const candidate of openFindings) {
@@ -1056,7 +1342,7 @@ export async function runProgram(options) {
         // An id triaged fix-now but absent from the open set (should not
         // happen — it is where the id came from) is skipped, fail-open.
         if (toFix.length === 0)
-            return greenCommit;
+            return { commit: greenCommit };
         const fix = await attemptFix({
             root,
             programId: options.programId,
@@ -1064,6 +1350,7 @@ export async function runProgram(options) {
             spec,
             config,
             agentRunner,
+            permits,
             verifyRunner,
             git,
             agent,
@@ -1071,6 +1358,8 @@ export async function runProgram(options) {
             greenCommit,
             label: "fix-now fix",
             log,
+            now,
+            observe,
         });
         // "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
@@ -1094,7 +1383,12 @@ export async function runProgram(options) {
         log(kept
             ? `${workstream.id}: fix-now fix verified and committed`
             : `${workstream.id}: fix-now fix failed and was escalated — ${note}`);
-        return kept ? fix.greenCommit : greenCommit;
+        const resultCommit = kept ? fix.greenCommit : greenCommit;
+        return {
+            commit: resultCommit,
+            ...(fix.spawnError === undefined ? {} : { spawnError: fix.spawnError }),
+            ...(fix.transcript === undefined ? {} : { transcript: fix.transcript }),
+        };
     }
 }
 /**
@@ -1184,7 +1478,7 @@ function notBuiltRoster(results, authorResult) {
  * bug in this function's own body throws before the pass has even run.
  */
 export async function runWholeProgramStage(args) {
-    const { root, programId, manifest, config, agentRunner, git, isRepository, results, authorResult, runStartCommit, decider, reviewed, triaged, now, log, fs, } = args;
+    const { root, programId, manifest, config, agentRunner, permits, git, isRepository, results, authorResult, runStartCommit, decider, reviewed, triaged, now, log, fs, } = args;
     const errors = [];
     let commit;
     let commitSkipped = false;
@@ -1215,6 +1509,7 @@ export async function runWholeProgramStage(args) {
             manifest,
             config,
             agentRunner,
+            permits,
             diff,
             ...(base === undefined ? {} : { baseCommit: base }),
             ...(notBuilt.length === 0 ? {} : { notBuilt }),
@@ -1261,7 +1556,7 @@ export async function runWholeProgramStage(args) {
         }
         if (journaled && events.length > 0) {
             try {
-                await triageFindings({
+                const spawnErrors = await triageFindings({
                     root,
                     programId,
                     manifest,
@@ -1270,6 +1565,7 @@ export async function runWholeProgramStage(args) {
                     baseCommit: reviewCommit,
                     decider,
                     agentRunner,
+                    permits,
                     git,
                     isRepository,
                     reviewed,
@@ -1277,6 +1573,7 @@ export async function runWholeProgramStage(args) {
                     now,
                     log,
                 });
+                errors.push(...spawnErrors);
             }
             catch (error) {
                 errors.push(`the decider failed to triage the whole-program findings: ${error.message}`);
@@ -1387,14 +1684,30 @@ 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, reviewer, git, baseCommit, failure } = 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 invocation = await invokeAgent(agentRunner, reviewer, brief, root);
+    let invocation;
+    try {
+        invocation = await invokeAgent(agentRunner, reviewer, brief, root, permits, "reviewerAgent", observe);
+    }
+    catch (error) {
+        return {
+            spawnError: `the reviewer could not be spawned while diagnosing the ${workstream.id} ` +
+                `failure: ${error.message}; the next attempt proceeds undiagnosed`,
+        };
+    }
+    // The transcript is captured whether or not the reviewer's reply parsed —
+    // a denial it hit while reading is a fact regardless of what it concluded
+    // (SC-12: every workstream-attributed spawn's denials are journaled).
+    const transcript = invocation.transcript;
     if (invocation.exitCode !== 0)
-        return undefined;
+        return transcript === undefined ? {} : { transcript };
     const text = invocation.output.trim();
-    return text === "" ? undefined : tail(text, 2000);
+    return {
+        ...(transcript === undefined ? {} : { transcript }),
+        ...(text === "" ? {} : { diagnosis: tail(text, 2000) }),
+    };
 }
 function successCriteriaLines(manifest) {
     if (manifest.successCriteria.length === 0) {
@@ -1554,10 +1867,35 @@ function testCritiqueFixBrief(workstream, spec, findings) {
  * whether (and how many times) this is called.
  */
 async function attemptFix(options) {
-    const { root, programId, workstream, spec, config, agentRunner, verifyRunner, git, agent, findings, greenCommit, label, } = options;
+    const { root, programId, workstream, spec, config, agentRunner, permits, verifyRunner, git, agent, findings, greenCommit, label, log, now, observe, } = options;
     const brief = testCritiqueFixBrief(workstream, spec, findings);
-    const invocation = await invokeAgent(agentRunner, agent, brief, root);
-    const summary = resolveSummary(invocation.output).text;
+    let invocation;
+    try {
+        invocation = await invokeAgent(agentRunner, agent, brief, root, permits, "agent", observe);
+    }
+    catch (error) {
+        const spawnError = `the ${label} implementer could not be spawned: ${error.message}; ` +
+            "the fix was not attempted and the green state was preserved.";
+        return {
+            outcome: "failed",
+            greenCommit,
+            summary: "(fix not attempted — the implementer could not be spawned)",
+            failure: spawnError,
+            spawnError,
+        };
+    }
+    const transcript = invocation.transcript;
+    const resolvedSummary = resolveSummary(invocation.output);
+    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);
+        for (const event of denialEvents) {
+            if (event.kind !== "permission-denied")
+                continue;
+            log(`${workstream.id} ${label}: denied \`${event.command}\` (${event.source})`);
+        }
+    }
     const failure = await verifyAttempt(config, verifyRunner, root, invocation.exitCode);
     if (failure === undefined) {
         // The runner's own pending ledger and manifest writes under
@@ -1579,6 +1917,7 @@ async function attemptFix(options) {
             greenCommit: commit ?? greenCommit,
             ...(commit === undefined ? {} : { commit }),
             summary,
+            ...(transcript === undefined ? {} : { transcript }),
         };
     }
     // The same uncommitted bookkeeping the clean path guards against sweeping
@@ -1594,7 +1933,7 @@ async function attemptFix(options) {
     const snapshot = await snapshotProgramsDir(root);
     await git.resetHard(root, greenCommit);
     await restoreProgramsDir(root, snapshot);
-    return { outcome: "failed", greenCommit, summary, failure };
+    return { outcome: "failed", greenCommit, summary, failure, ...(transcript === undefined ? {} : { transcript }) };
 }
 /**
  * The test-critique driver: wires WS-01's bounded review loop to the two
@@ -1604,11 +1943,19 @@ 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, verifyRunner, git, reviewer, agent, baseCommit, log, } = options;
+    const { root, manifest, workstream, spec, config, agentRunner, permits, verifyRunner, git, reviewer, agent, baseCommit, now, log, transcriptSink, } = options;
     let greenCommit = options.greenCommit;
     let diffClipped = false;
+    const stageErrors = [];
+    const transcripts = [];
     if (!reviewer) {
-        return { outcome: reviewerAbsentOutcome(), finalCommit: greenCommit, diffClipped };
+        return {
+            outcome: reviewerAbsentOutcome(),
+            finalCommit: greenCommit,
+            diffClipped,
+            stageErrors,
+            transcripts,
+        };
     }
     const locate = (file) => locateInRepo(root, file);
     const review = async (_round, priorOpen) => {
@@ -1618,7 +1965,28 @@ async function runTestCritique(options) {
         if (diff.clipped || clippedSpec.clipped)
             diffClipped = true;
         const brief = testCritiqueReviewerBrief(manifest, workstream, clippedSpec.text, diff.text, priorOpen);
-        const invocation = await invokeAgent(agentRunner, reviewer, brief, root);
+        let invocation;
+        try {
+            invocation = await invokeAgent(agentRunner, reviewer, brief, root, permits, "reviewerAgent", transcriptSink("test-critique-reviewer"));
+        }
+        catch (error) {
+            // Fail open, matching the existing reviewer-error path: no findings
+            // this round, the workstream outcome is unaffected, and the reason is
+            // recorded durably rather than only logged (SC-12).
+            stageErrors.push(`the reviewer could not be spawned during test critique: ${error.message}`);
+            return { findings: [], errors: [], ran: false };
+        }
+        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);
+                for (const event of denialEvents) {
+                    if (event.kind !== "permission-denied")
+                        continue;
+                    log(`${workstream.id} reviewer: denied \`${event.command}\` (${event.source})`);
+                }
+            }
+        }
         const parsed = extractFindings(invocation.output);
         const findings = verifyEvidence(parsed.findings, locate);
         const ran = invocation.exitCode === 0 && hasFindingsBlock(invocation.output);
@@ -1632,6 +2000,7 @@ async function runTestCritique(options) {
             spec,
             config,
             agentRunner,
+            permits,
             verifyRunner,
             git,
             agent,
@@ -1639,8 +2008,14 @@ async function runTestCritique(options) {
             greenCommit,
             label: "test critique fix",
             log,
+            now,
+            observe: transcriptSink("test-critique-fix"),
         });
         greenCommit = fix.greenCommit;
+        if (fix.transcript)
+            transcripts.push(fix.transcript);
+        if (fix.spawnError !== undefined)
+            stageErrors.push(fix.spawnError);
         if (fix.outcome === "kept") {
             log(`${workstream.id}: test critique fix verified and committed`);
             return { note: `${fix.summary} (fix verified and committed)` };
@@ -1649,7 +2024,7 @@ async function runTestCritique(options) {
         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 };
+    return { outcome, finalCommit: greenCommit, diffClipped, stageErrors, transcripts };
 }
 function renderSpecsSection(authorResult) {
     if (authorResult.results.length === 0)
@@ -1883,7 +2258,84 @@ function renderAwaitingHumanSection(manifest, preflight, resumeCommand) {
     lines.push(`Resume with: \`${resumeCommand ?? `npx --yes @wildorder/nightshift run ${manifest.program.id}`}\``, "");
     return lines;
 }
-export function renderRunReport(manifest, results, ledger, triagedThisRun, authorResult, at, wholeProgram, preflight, resumeCommand) {
+/**
+ * A workstream's Commands subsection (WS-02 SC-10): executed commands
+ * deduplicated with counts, denied commands verbatim with the CLI's reason,
+ * or — when nothing this workstream's build-role spawns produced was
+ * observed (Codex, an unparsed stream, an operator-configured or
+ * operator-`--output-format` role) — one honest line naming the agent
+ * command so the reader knows why nothing is listed.
+ */
+function renderWorkstreamCommands(result) {
+    const observed = (result.transcripts ?? []).filter((transcript) => transcript.observed);
+    if (observed.length === 0) {
+        return [
+            `  - Commands: not observable for \`${result.buildAgentCommand ?? "the configured agent"}\``,
+        ];
+    }
+    const counts = new Map();
+    for (const transcript of observed) {
+        for (const entry of transcript.commands) {
+            counts.set(entry.command, (counts.get(entry.command) ?? 0) + 1);
+        }
+    }
+    const denials = observed.flatMap((transcript) => transcript.denials);
+    // A line mid-stream that failed to parse could have been a command or a
+    // denial — the transcript itself cannot say which — so this is surfaced
+    // here rather than letting an incomplete transcript stand as authoritative.
+    const corrupted = observed.some((transcript) => transcript.corrupted);
+    if (counts.size === 0 && denials.length === 0 && !corrupted) {
+        return ["  - Commands: none observed"];
+    }
+    const lines = ["  - Commands:"];
+    if (corrupted) {
+        lines.push("    - warning: a line in this transcript could not be parsed — it may be missing a command or denial");
+    }
+    for (const [command, count] of counts) {
+        lines.push(`    - \`${command}\`${count > 1 ? ` ×${count}` : ""}`);
+    }
+    for (const denial of denials) {
+        lines.push(`    - denied: \`${denial.command}\` — ${denial.reason}`);
+    }
+    return lines;
+}
+/**
+ * The program-level `## Commands denied` section (SC-12): every
+ * `permission-denied` ledger record, grouped by workstream in the run's own
+ * workstream order, each rendered by the single `renderDenial` a human,
+ * `decide`, and this report all share. Omits the heading entirely when the
+ * ledger carries no denials, so a clean run's report is unchanged. Each
+ * workstream group closes with the run's retry command, so the operator sees
+ * the remediation to apply and the command to re-run in one place.
+ */
+function renderCommandsDeniedSection(results, ledger, programId) {
+    if (ledger.denials.length === 0)
+        return [];
+    const byWorkstream = new Map();
+    for (const denial of ledger.denials) {
+        const list = byWorkstream.get(denial.workstream) ?? [];
+        list.push(denial);
+        byWorkstream.set(denial.workstream, list);
+    }
+    const orderedIds = [
+        ...results.map((result) => result.id),
+        ...[...byWorkstream.keys()].filter((workstreamId) => !results.some((result) => result.id === workstreamId)),
+    ];
+    const lines = ["## Commands denied", ""];
+    for (const workstreamId of orderedIds) {
+        const denials = byWorkstream.get(workstreamId);
+        if (denials === undefined || denials.length === 0)
+            continue;
+        const name = results.find((result) => result.id === workstreamId)?.name ?? workstreamId;
+        lines.push(`### ${workstreamId} ${name}`, "");
+        for (const denial of denials) {
+            lines.push(...renderDenial(denial));
+        }
+        lines.push("", `Retry with: \`npx --yes @wildorder/nightshift run ${programId}\``, "");
+    }
+    return lines;
+}
+export function renderRunReport(manifest, results, ledger, triagedThisRun, authorResult, at, wholeProgram, preflight, resumeCommand, manifestAmended) {
     const programId = manifest.program.id;
     const built = results.filter((result) => result.outcome.status === "complete" ||
         result.outcome.status === "skipped").length;
@@ -1899,8 +2351,11 @@ export function renderRunReport(manifest, results, ledger, triagedThisRun, autho
         "",
         outcomeLine,
         "",
-        ...renderSpecsSection(authorResult),
     ];
+    if (manifestAmended === true) {
+        lines.push("## Manifest amended mid-run", "", "The manifest on disk was edited while this run held it. The edit was", "merged: the human's amendment was kept and the run's own status", "changes were preserved on top of it.", "");
+    }
+    lines.push(...renderSpecsSection(authorResult));
     const escalated = escalatedRecords(ledger);
     if (escalated.length > 0) {
         lines.push("## Needs your attention", "", "The decider reviewed these choices and findings and believes you", "might decide differently. Each is self-contained below: why it is", "here, the alternatives, and a command to flip it if you disagree.", "");
@@ -1925,6 +2380,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, "");
             }
+            const workstreamDenials = ledger.denials.filter((denial) => denial.workstream === result.id);
+            if (workstreamDenials.length > 0) {
+                lines.push("Commands denied: " +
+                    workstreamDenials.map((denial) => `\`${denial.command}\``).join(", ") +
+                    " — see Commands denied below.", "");
+            }
             lines.push(`Retry after fixing: \`npx --yes @wildorder/nightshift run ${manifest.program.id}\``, "(completed workstreams are skipped automatically).", "");
         }
     }
@@ -1949,6 +2410,9 @@ export function renderRunReport(manifest, results, ledger, triagedThisRun, autho
                 lines.push("  The reviewer saw input clipped for length.");
             }
         }
+        if (result.outcome.status === "complete" || result.outcome.status === "failed") {
+            lines.push(...renderWorkstreamCommands(result));
+        }
     }
     lines.push("");
     if (wholeProgram !== undefined) {
@@ -1964,11 +2428,22 @@ export function renderRunReport(manifest, results, ledger, triagedThisRun, autho
             lines.push(...renderRecord(record, { density: "compact", programId }), "");
         }
     }
+    lines.push(...renderCommandsDeniedSection(results, ledger, programId));
     lines.push(...renderKnownLimitations(results, authorResult, ledger, escalated, triagedThisRun, programId, wholeProgram));
     const decisionErrors = results.flatMap((result) => result.decisionErrors);
     if (decisionErrors.length > 0) {
         lines.push("## Decision blocks the runner could not read", "", ...decisionErrors.map((error) => `- ${error}`), "");
     }
+    const stageErrors = [
+        ...results.flatMap((result) => result.stageErrors ?? []),
+        ...authorResult.results.flatMap((result) => result.stageErrors ?? []),
+    ];
+    if (stageErrors.length > 0) {
+        lines.push("## Agent stages that could not run", "", "A reviewer, decider, or fix implementer could not be spawned after " +
+            "the workstream it concerns had already verified green; the " +
+            "workstream's own outcome is unaffected, but the reason it fell " +
+            "open belongs here.", "", ...stageErrors.map((error) => `- ${error}`), "");
+    }
     return lines.join("\n");
 }
 //# sourceMappingURL=run-program.js.map