audit-tools 0.42.1 → 0.44.0

package/dist/remediate/steps/nextStep.js

@@ -1,6 +1,6 @@
 import { loadRemediateSessionConfig } from "./sessionConfigLoad.js";
 import { existsSync, statSync } from "node:fs";
-import { mkdir, readFile, rename } from "node:fs/promises";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { StateStore } from "../state/store.js";
 // IO / validation / rendering helpers
@@ -15,17 +15,18 @@ import { runTriagePhase } from "../phases/triage.js";
 import { runClosePhase } from "../phases/close.js";
 import { validateRemediationPlan } from "../validation/remediationState.js";
 import { readExtractedPlanIfPresent, } from "./dispatch.js";
-import { ingestRemediationHostResults, hostDependencyLevels, prepareRemediationHostHandoff, } from "./dispatch/hostHandoff.js";
+import { ingestRemediationHostResults, hostDependencyLevels, precomputeRecoveryTestVerdicts, prepareRemediationHostHandoff, } from "./dispatch/hostHandoff.js";
 import { FileLockTimeoutError, withFileLock, } from "../../shared/io/fileLock.js";
-import { AUDIT_FINDINGS_FILENAME, AUDIT_REPORT_FILENAME, auditArtifactsDir, auditFindingsPath, auditReportPath, auditToolsDir, promotedAuditFindingsPath, promotedAuditReportPath, remediationArtifactsDir, } from "../../shared/io/auditToolsPaths.js";
+import { AUDIT_FINDINGS_FILENAME, AUDIT_REPORT_FILENAME, auditArtifactsDir, auditFindingsPath, auditReportPath, promotedAuditFindingsPath, promotedAuditReportPath, remediationArtifactsDir, } from "../../shared/io/auditToolsPaths.js";
 import { resolveRepoRoot } from "../../shared/io/repoRoot.js";
 import { writeCurrentStep } from "./stepWriter.js";
 import { dependencyAwaitingClarification, dependencyVerifiedComplete, } from "./stepUtils.js";
 import { isTerminalStatus, isVerifiedCompleteStatus, } from "../state/itemStatus.js";
 import { deduplicateCrossLensFindings, fixupBlocksAfterDedup, } from "../dedup/crossLensDedup.js";
 import { checkAffectedFileIntegrity } from "../utils/fileIntegrity.js";
+import { applyIntentOrdering } from "../intent/intentOrdering.js";
 import { resolveIntakeStep } from "./intakeResolver.js";
-import { runToolOwnedFinalGate, applyCoarseReblock, readFinalGateSidecar, writeFinalGateSidecar, } from "./finalGate.js";
+import { runToolOwnedFinalGate, writeFinalGateRedRecord, writeFinalGateOutcomeRecord, } from "./finalGate.js";
 import { buildNextContractPipelineStep, shouldEnterContractPipeline, writePathASeedFromFindings, buildLeanExtractedPlan, } from "./contractPipeline.js";
 import { contractArtifactExists, contractPipelineDir, } from "../contractPipeline/artifactStore.js";
 import { buildReviewRequest, applyReviewResolution, isResolutionForRequest, screenResolutionIds, REVIEW_REQUEST_SCHEMA_VERSION, } from "../review/reviewGate.js";
@@ -69,7 +70,31 @@ function stateRunId(state) {
     // record path is deterministic across multiple next-step calls on the same run.
     return state?.plan?.plan_id ?? "run";
 }
-function defaultInputCandidates(root) {
+/**
+ * Where an autonomous run's LEFTOVER deliverable pair lands.
+ *
+ * REMEDIATION-OWNED, deliberately. This module used to write the canonical
+ * `.audit-tools/audit-findings.json` + `audit-report.md` pair directly and
+ * unarchived, which destroys the audit source `defaultInputCandidates` resolves
+ * FIRST — the original contract becomes unrecoverable for any external consumer
+ * (INV-RNF-NO-CANONICAL-PAIR-WRITE). The canonical pair belongs to
+ * audit-artifact-promotion-lifecycle, whose exported write-with-archive is the
+ * only sanctioned way to replace it.
+ */
+export function autonomousLeftoverFindingsPath(root) {
+    return join(remediationArtifactsDir(root), "autonomous-leftovers-findings.json");
+}
+export function autonomousLeftoverReportPath(root) {
+    return join(remediationArtifactsDir(root), "autonomous-leftovers-report.md");
+}
+/**
+ * The intake sources a bare `next-step` discovers, IN PRIORITY ORDER — index 0
+ * wins. Exported so the ordering can be asserted by CALLING it: the property
+ * that matters ("a real audit always beats this run's own leftovers") is a fact
+ * about the returned array, and a test that reads it out of the source text is
+ * asserting the prose, not the order.
+ */
+export function defaultInputCandidates(root) {
     // Prefer the canonical machine contract (audit-findings.json) over its
     // human-facing render (audit-report.md). The JSON is the source of truth on
     // both sides of the audit -> remediate pipeline, and feeding it triggers the
@@ -83,6 +108,13 @@ function defaultInputCandidates(root) {
         promotedAuditReportPath(auditDir),
         auditReportPath(auditDir),
         join(root, AUDIT_REPORT_FILENAME),
+        // LAST, so a real audit always wins. The autonomous leftover pair moved off
+        // the canonical paths (it may no longer overwrite them), and without a
+        // candidate entry the next unattended run would stop round-tripping its own
+        // leftovers back through intake — the behaviour the old canonical write was
+        // there to provide, kept without the destructive overwrite.
+        autonomousLeftoverFindingsPath(root),
+        autonomousLeftoverReportPath(root),
     ];
 }
 function inputValues(input) {
@@ -269,16 +301,15 @@ export function phaseBoundaryToGate(state) {
         .every((b) => b.items.every((id) => items[id]?.status === "pending"));
     return pristine ? dispatchPhase : null;
 }
-// Tool-owned final completion gate (INV-RS-10) + coarse re-block (INV-RS-09)
+// Tool-owned final completion gate (INV-RS-10)
 // ---------------------------------------------------------------------------
 //
-// The gate runner, its bounded coarse-reblock backstop, and the sidecar counter
-// I/O were extracted behaviour-preservingly into the sibling leaf module
-// `finalGate.ts` (CP-NODE-1). They are imported below for local use in the
-// completion handler and re-exported to preserve this module's public surface +
+// The gate runner and its red record live in the sibling leaf module
+// `finalGate.ts`. They are imported below for local use in the boundary and
+// completion gates and re-exported to preserve this module's public surface +
 // existing test imports. See `finalGate.ts` for the INV-RS-10 / CE-001 / CE-002
 // documentation.
-export { isAuditToolsMonorepo, toolOwnedFinalGateCommands, runToolOwnedFinalGate, applyCoarseReblock, COARSE_REBLOCK_BOUND, } from "./finalGate.js";
+export { isAuditToolsMonorepo, toolOwnedFinalGateCommands, runToolOwnedFinalGate, finalGateOutcomePath, writeFinalGateOutcomeRecord, } from "./finalGate.js";
 function resolvedOrTerminalItems(state) {
     return Object.values(state.items ?? {}).filter((item) => isTerminalStatus(item.status));
 }
@@ -286,6 +317,26 @@ function allItemsTerminal(state) {
     const items = Object.values(state.items ?? {});
     return items.length > 0 && resolvedOrTerminalItems(state).length === items.length;
 }
+/**
+ * Reorder a finalized plan by the checkpoint's interpreted intent.
+ *
+ * The checkpoint persists the operator's `free_form_intent` verbatim; the
+ * structured `InterpretedIntent` is derived from it by the single shared
+ * interpreter. INV-S04: the raw directive is never read past this line — only
+ * the derived lens-weight / priority / scope signals reach the ordering, so the
+ * verbatim string cannot leak into a worker prompt through this path.
+ *
+ * Absent checkpoint, absent intent, or an intent that interprets to nothing all
+ * return the plan untouched.
+ */
+async function applyCheckpointIntentOrdering(artifactsDir, plan) {
+    const checkpoint = await readOptionalJsonFile(join(artifactsDir, "intent_checkpoint.json")).catch(() => undefined);
+    const freeForm = checkpoint?.free_form_intent;
+    if (typeof freeForm !== "string" || freeForm.trim().length === 0)
+        return plan;
+    const ordered = applyIntentOrdering(plan.findings, plan.blocks, interpretFreeFormIntent(freeForm));
+    return { ...plan, findings: ordered.findings, blocks: ordered.blocks };
+}
 function normalizeExtractedPlan(value) {
     if (!isRecord(value)) {
         throw new Error("extracted-plan.json must be an object.");
@@ -394,7 +445,20 @@ function stripPlanTimeBookkeeping(value) {
     }
     return stripped;
 }
-function findingCarryForwardKey(finding) {
+/**
+ * The re-plan carry-forward identity of a finding: canonical JSON with the
+ * plan-time bookkeeping keys stripped, so a re-plan whose only delta is a
+ * recomputed file hash or a re-evaluated grounding flag carries the prior item
+ * (and its `item_spec`) forward, while a real change to the finding does not.
+ *
+ * EXPORTED so the invariant suite can call THIS function. It was module-internal,
+ * and the suite claiming to cover the invariant declared its own copy of the key
+ * set, the strip and the key builder — so dropping `evidence_grounded` from the
+ * production set, or widening it with a real field like `severity`, left the
+ * block green while carry-forward regressed. A test asserting against its own
+ * re-implementation pins nothing about shipped behaviour.
+ */
+export function findingCarryForwardKey(finding) {
     return JSON.stringify(stripPlanTimeBookkeeping(finding));
 }
 // Single-block membership is enforced by `fixupBlocksAfterDedup` (each finding
@@ -453,7 +517,7 @@ function carryForwardMatchingItems(previous, replanned) {
         status: hasPending ? "planning" : replanned.status,
     };
 }
-async function forceReplanFromExistingIntake(root, artifactsDir, previous, store) {
+async function forceReplanFromExistingIntake(root, artifactsDir, previous, store, runLogger) {
     const pendingState = {
         status: "pending",
         started_at: previous.started_at,
@@ -476,7 +540,7 @@ async function forceReplanFromExistingIntake(root, artifactsDir, previous, store
         await store.saveState(pendingState);
         return null;
     }
-    const replanned = await handlePendingExtractedPlan(root, artifactsDir, pendingState, extractedPlan);
+    const replanned = await handlePendingExtractedPlan(root, artifactsDir, pendingState, extractedPlan, runLogger);
     if (!replanned) {
         return null;
     }
@@ -525,8 +589,120 @@ function currentHostBoundaryState(state) {
         ...state,
     };
 }
+/**
+ * The `recover-ingest` verb's whole body: ingest the host's landed results in
+ * RECOVERY mode and persist through the same file-locked, atomically-writing
+ * store, with the same `contract_version` strip.
+ *
+ * It is a separate verb rather than a flag on `next-step` because the
+ * relaxation it enables must be an operator's explicit act — see
+ * `ingestRemediationHostResults`, which states what is waived and the residual
+ * risk. Nothing else here differs from the normal ingestion: the same workload,
+ * the same contract gates, the same eligibility frontier.
+ *
+ * ## Why this runs in two phases
+ *
+ * A required-test rerun is `spawnSync`, which blocks the event loop for its
+ * whole duration. Run inside the state lock, it would starve the lock's own
+ * heartbeat timer (`setInterval` in the shared fileLock) — the held lock's mtime
+ * would stop being refreshed, a second acquirer would classify it as stale at
+ * ~30s and steal it, and mutual exclusion would be gone precisely during the
+ * longest critical section in the codebase. Holding a lock across a blocking
+ * spawn is therefore not merely slow; it is unsound.
+ *
+ * So:
+ *
+ * - **Phase 1, UNLOCKED.** Snapshot the state, capture HEAD, and run every
+ *   distinct required-test command exactly once
+ *   (`precomputeRecoveryTestVerdicts`). HEAD is captured BEFORE the spawns, not
+ *   after, because a host-authored command that MOVES HEAD would otherwise
+ *   produce verdicts of mixed provenance and go undetected. (The guard compares
+ *   commit shas: it sees HEAD movement, not worktree dirt — a command that only
+ *   dirties files is invisible to it, which is acceptable because phase 2's
+ *   corroboration is commit-based.)
+ * - **Phase 2, LOCKED.** Re-read HEAD and abort the whole recovery if it moved
+ *   (`tree_moved_between_phases`) — the phase-1 verdicts would describe a tree
+ *   that no longer exists, and nothing is accepted or appended. Otherwise ingest
+ *   with the pre-computed verdicts, which the ingest only READS: in recovery
+ *   mode it never spawns, and a command missing from the table fails closed.
+ *
+ * What remains inside the lock is git plumbing (ancestry, ref scan, diff-tree),
+ * the ledger append, and the state write — sub-second work, comfortably inside
+ * heartbeat coverage. The HEAD-unchanged guard closes the gap the phase split
+ * opens; the operational protocol is still one writer at a time, now enforced by
+ * a lock that cannot be stolen mid-hold instead of by convention.
+ *
+ * One accepted cost: `StateStore.mutate` always writes, so a recovery run that
+ * changes nothing rewrites `state.json` with identical content. Expressing a
+ * true no-op means plumbing the locked store's `SKIP_WRITE` sentinel through
+ * `StateStore.mutate`, which is a change to the store's API rather than to this
+ * verb. The `state_changed` flag on the returned summary stays authoritative
+ * for callers either way.
+ */
+export async function recoverIngestHostResults(options) {
+    const root = resolveRoot(options.root);
+    const artifactsDir = resolveArtifactsDir(root, options.artifactsDir);
+    const store = new StateStore(artifactsDir);
+    // ── Phase 1: unlocked ────────────────────────────────────────────────────
+    const snapshot = await store.loadState();
+    if (!snapshot) {
+        throw new Error(`No remediation state at ${artifactsDir} — there is nothing to ingest.`);
+    }
+    const headBeforeTests = headCommit(root);
+    const requiredTestVerdicts = await precomputeRecoveryTestVerdicts({
+        root,
+        artifactsDir,
+        runId: options.runId,
+        state: currentHostBoundaryState(snapshot),
+    });
+    if (requiredTestVerdicts === "unsupported_retired_state") {
+        throw new Error("Remediation state uses a retired dispatch shape and cannot cross the host handoff boundary.");
+    }
+    // ── Phase 2: locked, spawn-free ──────────────────────────────────────────
+    let ingested;
+    await store.mutate(async (state) => {
+        if (!state) {
+            throw new Error(`No remediation state at ${artifactsDir} — there is nothing to ingest.`);
+        }
+        const headNow = headCommit(root);
+        if (headNow !== headBeforeTests) {
+            ingested = {
+                accepted_count: 0,
+                completed_work_item_ids: [],
+                pending_work_item_ids: state.host_handoff?.work_item_ids ?? [],
+                issues: [
+                    {
+                        code: "tree_moved_between_phases",
+                        message: `HEAD moved from ${headBeforeTests ?? "(none)"} to ${headNow ?? "(none)"} ` +
+                            "while the required tests were running, so their verdicts no longer describe " +
+                            "this tree. Nothing was accepted; re-run recover-ingest on a settled tree.",
+                    },
+                ],
+                state_changed: false,
+                state: currentHostBoundaryState(state),
+            };
+            return state;
+        }
+        const outcome = await ingestRemediationHostResults({
+            root,
+            artifactsDir,
+            runId: options.runId,
+            state: currentHostBoundaryState(state),
+            recovery: { requiredTestVerdicts },
+        });
+        if (outcome === "unsupported_retired_state") {
+            throw new Error("Remediation state uses a retired dispatch shape and cannot cross the host handoff boundary.");
+        }
+        ingested = outcome;
+        if (!outcome.state_changed)
+            return state;
+        const { contract_version: _contractVersion, ...persistableState } = outcome.state;
+        return persistableState;
+    });
+    return ingested;
+}
 async function buildImplementDispatchStep(ctx) {
-    const { root, artifactsDir, state, store } = ctx;
+    const { root, artifactsDir, state, store, runLogger } = ctx;
     const runId = stateRunId(state);
     const boundaryState = currentHostBoundaryState(state);
     const ingested = await ingestRemediationHostResults({
@@ -564,6 +740,21 @@ async function buildImplementDispatchStep(ctx) {
             host_handoff: handoff.handoff_record,
         });
     }
+    // Ingest issues reached the PROMPT and nothing else — a channel that survives
+    // exactly as long as the host reads that one step. They are also the durable
+    // record of which submitted results were rejected and why, so they are logged
+    // as well as rendered.
+    for (const issue of ingested.issues) {
+        runLogger.event({
+            phase: "next-step",
+            kind: "outcome",
+            obligation: "host_ingest",
+            note: `host_ingest_issue code=${issue.code}` +
+                (issue.work_item_id ? ` work_item=${issue.work_item_id}` : "") +
+                (issue.result_path ? ` result=${issue.result_path}` : "") +
+                ` message=${issue.message}`,
+        });
+    }
     const resultDiagnostics = ingested.issues.length === 0
         ? ""
         : `
@@ -668,7 +859,39 @@ async function handleComplete(root, artifactsDir, state) {
 export async function decideRemediateFrictionCloseout(artifactsDir, state) {
     return decideFrictionTriage(artifactsDir, stateRunId(state), "remediate-code");
 }
-async function handlePendingExtractedPlan(root, artifactsDir, existing, extractedPlan) {
+/**
+ * Copy an unusable extracted plan somewhere recoverable and PROVE the copy
+ * landed, returning the archive path. Read back and compared byte-for-byte:
+ * "the write did not throw" is not evidence a file exists, and this is the last
+ * moment the plan is recoverable at all.
+ *
+ * THROWS rather than returning when the copy cannot be made or verified, so the
+ * caller's unlink is unreachable on that path — an irreversible delete never
+ * runs before its archive is written and verified.
+ */
+async function archiveExtractedPlan(extractedPlanPath) {
+    // BYTES, compared with Buffer.compare — the bar CP-NODE-3 set for the
+    // verified-archive promotion path. A utf8-string compare is a weaker claim
+    // than the one an archive has to make: it silently equates byte sequences that
+    // decode alike (a BOM, a lone surrogate, an invalid sequence replaced by
+    // U+FFFD on BOTH sides), so a corrupt copy can read as verified.
+    const original = await readFile(extractedPlanPath);
+    const archivePath = join(dirname(extractedPlanPath), "archive", `extracted-plan-${Date.now()}.json`);
+    await mkdir(dirname(archivePath), { recursive: true });
+    await writeFile(archivePath, original);
+    const readBack = await readFile(archivePath);
+    if (Buffer.compare(original, readBack) !== 0) {
+        throw new Error(`Extracted-plan archive at ${archivePath} does not match the original bytes.`);
+    }
+    return archivePath;
+}
+async function handlePendingExtractedPlan(root, artifactsDir, existing, extractedPlan, 
+// The plan path's high-consequence events — findings dropped by grounding, and
+// the plan being destroyed — are DURABLE, so the logger is a parameter rather
+// than a module-level singleton reached for at the point of use. stderr is not
+// captured into the artifact dir; before this, the durable tree held no trace
+// that a plan had been destroyed or that findings had been dropped.
+runLogger) {
     // The discard-and-re-extract recovery below covers EXACTLY the region whose
     // failures mean the extracted PLAN is unusable: normalization and grounding.
     // It deliberately stops there. Everything after it — sizing, the dirty
@@ -688,6 +911,14 @@ async function handlePendingExtractedPlan(root, artifactsDir, existing, extracte
     let grounding;
     try {
         ({ plan, sourceFindings, mergeMap } = normalizeExtractedPlan(extractedPlan));
+        // INTENT ORDERING, applied where the plan's findings and blocks are
+        // FINALIZED. `applyIntentOrdering` existed with no production caller at all:
+        // the checkpoint's interpreted intent was written and never read back, so
+        // "the work the user emphasised is dispatched first" was a property the code
+        // could state but not deliver. Ordering ONLY — it never drops or mutates a
+        // finding; every input is present in the output with a different order, so a
+        // plan whose checkpoint carries no intent is returned unchanged.
+        plan = await applyCheckpointIntentOrdering(artifactsDir, plan);
         // Deterministic grounding for the LLM-extracted plan (this path never sees
         // structured audit findings): strip phantom affected_files paths, drop
         // findings whose every cited path was phantom, and classify evidence. No
@@ -701,6 +932,21 @@ async function handlePendingExtractedPlan(root, artifactsDir, existing, extracte
             evidenceGrounding: plan.source !== "contract_pipeline",
         });
         if (grounding.dropped.length > 0) {
+            // DROPPED-ID BOOKKEEPING, durable. A caller reading a finding count across
+            // the plan boundary must never receive the submitted count when findings
+            // were dropped, so the ids, the dropped count and the surviving grounded
+            // count all land in the run log — not only on stderr, which no artifact
+            // captures.
+            const droppedIds = grounding.dropped.map((d) => d.finding.id);
+            runLogger.event({
+                phase: "next-step",
+                kind: "outcome",
+                obligation: "plan_grounding",
+                note: `grounding_dropped_findings dropped=${String(droppedIds.length)} ` +
+                    `grounded=${String(grounding.findings.length)} ` +
+                    `submitted=${String(plan.findings.length)} ` +
+                    `ids=${droppedIds.join(",")}`,
+            });
             process.stderr.write(`[remediate-code] Grounding dropped ${grounding.dropped.length} extracted finding(s) whose cited paths do not exist: ${grounding.dropped.map((d) => `${d.finding.id} (${d.phantomPaths.join(", ")})`).join("; ")}\n`);
         }
         plan.findings = grounding.findings;
@@ -714,12 +960,43 @@ async function handlePendingExtractedPlan(root, artifactsDir, existing, extracte
     }
     catch (error) {
         const paths = intakePaths(artifactsDir);
-        try {
+        const reason = error instanceof Error ? error.message : String(error);
+        // ARCHIVE, VERIFY, THEN destroy — in that order, with the delete unreachable
+        // if the archive did not land. This recovery used to unlink the plan
+        // outright, unarchived and unverified, leaving a line on stderr as the only
+        // record; the plan the run was built from was simply gone.
+        let archivePath;
+        if (existsSync(paths.extractedPlan)) {
+            try {
+                archivePath = await archiveExtractedPlan(paths.extractedPlan);
+            }
+            catch (archiveError) {
+                const detail = archiveError instanceof Error
+                    ? archiveError.message
+                    : String(archiveError);
+                runLogger.event({
+                    phase: "next-step",
+                    kind: "error",
+                    obligation: "extracted_plan_recovery",
+                    note: `extracted_plan_archive_failed reason=${reason} archive_error=${detail}`,
+                });
+                // NOT a re-emitted extraction step. Returning null here would report a
+                // routine "re-extract, please" while the plan was destroyed and nothing
+                // held a copy of it.
+                throw new Error(`Extracted plan at ${paths.extractedPlan} is unusable (${reason}) but could ` +
+                    `not be archived (${detail}); it was left in place rather than destroyed.`);
+            }
             const { unlink } = await import("node:fs/promises");
             await unlink(paths.extractedPlan);
         }
-        catch { /* already gone */ }
-        process.stderr.write(`[remediate-code] Unusable extracted-plan.json removed (${error instanceof Error ? error.message : String(error)}). Re-emitting extraction step.\n`);
+        runLogger.event({
+            phase: "next-step",
+            kind: "outcome",
+            obligation: "extracted_plan_recovery",
+            note: `extracted_plan_removed reason=${reason} ` +
+                `archive=${archivePath ?? "(nothing on disk to archive)"}`,
+        });
+        process.stderr.write(`[remediate-code] Unusable extracted-plan.json removed (${reason}); archived at ${archivePath ?? "(nothing on disk to archive)"}. Re-emitting extraction step.\n`);
         return null;
     }
     // Past the recovery boundary: a failure below is a real failure and propagates.
@@ -1102,15 +1379,33 @@ async function emitAutonomousLeftoverDeliverable(root, artifactsDir, leftovers)
             "fail-closed non-destructiveness allowlist (or not tier-safe), so not auto-fixed. " +
             "They carry NO declined disposition — re-run remediation to re-evaluate them.",
     });
-    // Prefer the canonical `.audit-tools/` location (defaultInputCandidates[0]);
-    // fall back to the artifacts dir's parent when artifactsDir is non-standard.
-    const canonicalOutDir = auditToolsDir(root);
-    const outDir = existsSync(canonicalOutDir) ? canonicalOutDir : dirname(artifactsDir);
-    await mkdir(outDir, { recursive: true });
+    // REMEDIATION-OWNED PATH. This used to write the canonical
+    // `.audit-tools/audit-findings.json` + `audit-report.md` pair directly, with
+    // no archive: the audit source that `defaultInputCandidates` resolves first
+    // was silently replaced by a remediation-authored render, and the original
+    // contract was unrecoverable. The canonical pair is
+    // audit-artifact-promotion-lifecycle's; anything that must replace it goes
+    // through its exported write-with-archive
+    // (artifact:canonical-audit-deliverable-write-path), never a raw write here.
+    const findingsPath = autonomousLeftoverFindingsPath(root);
+    const reportPath = autonomousLeftoverReportPath(root);
+    await mkdir(dirname(findingsPath), { recursive: true });
     await Promise.all([
-        writeJsonFile(join(outDir, AUDIT_FINDINGS_FILENAME), pair.findings_report),
-        writeTextFile(join(outDir, AUDIT_REPORT_FILENAME), pair.report_markdown),
+        writeJsonFile(findingsPath, pair.findings_report),
+        writeTextFile(reportPath, pair.report_markdown),
     ]);
+    // NAMED IN THE DURABLE LOG. A leftover emit that left no event was invisible
+    // after the fact: an operator could not tell an emit from a silent no-op.
+    // The run log is opened here rather than threaded down: the two frames above
+    // this one carry no logger, and widening both signatures to pass one through
+    // would touch call paths this change has no other business in.
+    new RunLogger(join(artifactsDir, "run.log.jsonl"), { enabled: true }).event({
+        phase: "next-step",
+        kind: "outcome",
+        obligation: "autonomous_leftovers",
+        note: `autonomous_leftover_deliverable findings=${String(leftovers.length)} ` +
+            `path=${findingsPath}`,
+    });
 }
 // ── Path-A filter dispositions (persisted for the coverage ledger) ──────────────
 // The single filter pass runs at intake over the ORIGINAL findings; its
@@ -1133,14 +1428,14 @@ async function persistReviewFilterDispositions(artifactsDir, originals, filter)
     };
     await writeJsonFile(reviewFilterDispositionsPath(artifactsDir), payload);
 }
-async function handleReadyIntakeContractPipeline(root, artifactsDir, options) {
+async function handleReadyIntakeContractPipeline(root, artifactsDir, options, runLogger) {
     // Fast path: if an extracted-plan.json already exists (pipeline complete or
     // promoted from a previous contract pipeline run), consume it directly without
     // requiring intake artifacts. This handles both "plan promoted, ready to
     // ground+plan" and the grounding tests that write extracted-plan.json directly.
     const earlyExtractedPlan = await readExtractedPlanIfPresent(artifactsDir);
     if (earlyExtractedPlan) {
-        return handlePendingExtractedPlan(root, artifactsDir, { status: "pending" }, earlyExtractedPlan);
+        return handlePendingExtractedPlan(root, artifactsDir, { status: "pending" }, earlyExtractedPlan, runLogger);
     }
     const intake = await readIntakeArtifacts(artifactsDir);
     if (!intake.summary || !isIntakeReady(intake.summary)) {
@@ -1267,14 +1562,28 @@ async function handleReadyIntakeContractPipeline(root, artifactsDir, options) {
                         tier: "medium",
                         reason: `lean light review surfaced a concern: ${review.concerns.join("; ")}`,
                     }));
+                    runLogger.event({
+                        phase: "next-step",
+                        kind: "outcome",
+                        obligation: "lean_fast_path",
+                        note: `lean_fast_path_escalated concerns=${String(review.concerns.length)} ` +
+                            `detail=${review.concerns.join("; ")}`,
+                    });
                     process.stderr.write(`[remediate-code] Lean light review escalated (${review.concerns.join("; ")}); routing to the full contract pipeline.\n`);
                 }
                 else {
                     // Clear verdict → proceed with the lean plan.
                     const leanPlan = buildLeanExtractedPlan(gate.approved, randomRunId("LEAN"));
                     await writeJsonFile(intakePaths(artifactsDir).extractedPlan, leanPlan);
+                    runLogger.event({
+                        phase: "next-step",
+                        kind: "outcome",
+                        obligation: "lean_fast_path",
+                        note: `lean_fast_path_routed findings=${String(gate.approved.length)} ` +
+                            `rationale=${riskSignal.rationale.join("; ")}`,
+                    });
                     process.stderr.write(`[remediate-code] Lean fast path (risk tier low): ${riskSignal.rationale.join("; ")}; light review clear. Routing to plan→implement.\n`);
-                    const planned = await handlePendingExtractedPlan(root, artifactsDir, { status: "pending" }, leanPlan);
+                    const planned = await handlePendingExtractedPlan(root, artifactsDir, { status: "pending" }, leanPlan, runLogger);
                     if (planned) {
                         return planned;
                     }
@@ -1282,6 +1591,12 @@ async function handleReadyIntakeContractPipeline(root, artifactsDir, options) {
                     // normalize. If it somehow didn't, handlePendingExtractedPlan removed
                     // the file; fall through to the full pipeline (the safety net) rather
                     // than stalling the run.
+                    runLogger.event({
+                        phase: "next-step",
+                        kind: "outcome",
+                        obligation: "lean_fast_path",
+                        note: "lean_fast_path_fallback plan failed to materialize; routing to the contract pipeline",
+                    });
                     process.stderr.write("[remediate-code] Lean fast-path plan failed to materialize; falling back to the contract pipeline.\n");
                 }
             }
@@ -1329,16 +1644,16 @@ async function handleReadyIntakeContractPipeline(root, artifactsDir, options) {
     if (!extractedPlan) {
         return null;
     }
-    return handlePendingExtractedPlan(root, artifactsDir, { status: "pending" }, extractedPlan);
+    return handlePendingExtractedPlan(root, artifactsDir, { status: "pending" }, extractedPlan, runLogger);
 }
-async function handlePendingIntake(root, artifactsDir, options) {
+async function handlePendingIntake(root, artifactsDir, options, runLogger) {
     // Short-circuit: if an extracted-plan.json already exists (promoted from the
     // contract pipeline), consume it directly without requiring intake artifacts.
     // This allows decideNextStep to resume a plan-grounding pass even when the
     // full intake artifact set is no longer present.
     const earlyExtractedPlan = await readExtractedPlanIfPresent(artifactsDir);
     if (earlyExtractedPlan) {
-        return handleReadyIntakeContractPipeline(root, artifactsDir, options);
+        return handleReadyIntakeContractPipeline(root, artifactsDir, options, runLogger);
     }
     const inputResolution = resolveInputPaths(root, options.input);
     const intakeResult = await resolveIntakeStep({
@@ -1356,7 +1671,7 @@ async function handlePendingIntake(root, artifactsDir, options) {
         return intakeResult.step;
     }
     // Intake is complete — route both paths through the contract pipeline.
-    return handleReadyIntakeContractPipeline(root, artifactsDir, options);
+    return handleReadyIntakeContractPipeline(root, artifactsDir, options, runLogger);
 }
 async function handleNoState(root, artifactsDir) {
     const paths = intakePaths(artifactsDir);
@@ -1894,14 +2209,151 @@ function hasResolvedItems(state) {
     return Object.values(state.items ?? {}).some((it) => isVerifiedCompleteStatus(it.status));
 }
 /**
- * The tool-owned final gate (INV-RS-10) is disabled for this run — explicitly via
- * `skipFinalGate` (test hermeticity) or `REMEDIATE_SKIP_FINAL_GATE`. Single-sourced
- * so the all-terminal gate and the per-phase boundary gate agree.
+ * WHICH suppression disabled the tool-owned final gate (INV-RS-10) for this run —
+ * `skipFinalGate` (test hermeticity) or `REMEDIATE_SKIP_FINAL_GATE` — or null when
+ * it is live. Single-sourced so the all-terminal gate and the per-phase boundary
+ * gate agree, and so both RECORD the same reason.
+ *
+ * The reason is carried into the outcome record rather than collapsed to a
+ * boolean: the environment skip is the quietest not-run in the system (it needs
+ * no option, no argument and no code change to fire), so a record that says only
+ * "disabled" would leave an operator unable to tell a deliberate test-hermeticity
+ * run from a stray exported variable.
  */
-function finalGateDisabled(options) {
-    return (options.skipFinalGate === true ||
-        process.env.REMEDIATE_SKIP_FINAL_GATE === "1" ||
-        process.env.REMEDIATE_SKIP_FINAL_GATE === "true");
+function finalGateDisabledReason(options) {
+    if (options.skipFinalGate === true)
+        return "skipFinalGate option";
+    if (process.env.REMEDIATE_SKIP_FINAL_GATE === "1" ||
+        process.env.REMEDIATE_SKIP_FINAL_GATE === "true") {
+        return "REMEDIATE_SKIP_FINAL_GATE environment variable";
+    }
+    return null;
+}
+/**
+ * The ONE way a gate evaluation is recorded, shared by BOTH gate families (the
+ * phase-boundary gate and the all-terminal funnel), so neither can grow a second
+ * executed/scoped-out/disabled vocabulary of its own.
+ *
+ * Writes the durable {@link writeFinalGateOutcomeRecord} artifact AND the run-log
+ * event from the same values, so the two can never disagree about which of the
+ * three happened.
+ *
+ * This is the affirmation the gate lacked. The floor's control flow was already
+ * right — a scoped-out gate is deliberately NON-BLOCKING, a declared scope rather
+ * than a vacuous pass — but the only thing either consumer wrote was
+ * `passed=<bool>`, which is `true` for an executed green floor, for a scoped-out
+ * target that ran nothing, and for a suppressed gate that was never reached. All
+ * three produced byte-identical records, so "the suite passed" and "no suite ran"
+ * were indistinguishable after the fact.
+ */
+async function recordFinalGateOutcome(ctx) {
+    const ran = ctx.outcome === "executed";
+    await writeFinalGateOutcomeRecord(ctx.artifactsDir, {
+        scope: ctx.scope,
+        outcome: ctx.outcome,
+        passed: ctx.passed,
+        commands_run: ctx.commandsRun,
+        ...(ctx.reason === undefined ? {} : { reason: ctx.reason }),
+    });
+    ctx.runLogger.event({
+        phase: "next-step",
+        kind: "executor_end",
+        obligation: ctx.state.status,
+        note: `${ctx.gateKey} outcome=${ctx.outcome} ` +
+            // "n/a", never "true": a gate that ran nothing has no verdict, and the
+            // durable record it is written beside carries `passed: null` for the
+            // same reason.
+            `passed=${ran ? String(ctx.passed) : "n/a"} ` +
+            `commands=${ran ? String(ctx.commandsRun) : "0"}` +
+            (ctx.reason === undefined ? "" : ` reason=${ctx.reason}`),
+        ...(ctx.durationMs === undefined ? {} : { duration_ms: ctx.durationMs }),
+    });
+}
+/**
+ * The ONE response to a red tool-owned gate, shared by both gates that run it.
+ *
+ * Records the failing command beneath the artifacts dir and emits a resumable
+ * `final_gate_red` step. It MUTATES NOTHING — no item status, no `state.status`,
+ * no persisted state write at all — because a whole-repo red is unattributable:
+ * nothing in the gate computes which item or path caused it, so every response
+ * that touches items is guessing. The predecessor guessed by re-opening all of
+ * them, and on 2026-08-20 that erased 21 accepted resolutions over a red from an
+ * unrelated landed commit.
+ *
+ * Resumable BY CONSTRUCTION rather than by stored progress: the next next-step
+ * re-runs the gate, and a green one proceeds exactly as if the red never
+ * happened. There is nothing to reset and no counter that can strand the run.
+ *
+ * The prompt carries the failing command line and the PATH to the record — never
+ * the captured output, which stays in the artifact where a multi-KB suite log
+ * costs nothing.
+ *
+ * COST OF THE PAUSE, stated in the prompt rather than discovered: there is no
+ * cached verdict, so EVERY next-step taken while the suite is red re-runs the
+ * whole gate — a full build plus the whole suite, minutes, holding the phase
+ * lock throughout. That is the deliberate price of having no counter to strand
+ * the run on, and it makes polling expensive: the host should re-run once it has
+ * actually fixed something, not on a timer.
+ */
+async function emitFinalGateRedStep(ctx) {
+    const { root, artifactsDir, state, scope, gate, runLogger } = ctx;
+    const failed = gate.results.find((r) => !r.passed);
+    const recordPath = await writeFinalGateRedRecord(artifactsDir, scope, failed);
+    const failingCommand = failed
+        ? `${failed.argv.join(" ")} (exit ${String(failed.exit_code)})`
+        : "(the gate reported no failing command)";
+    runLogger.event({
+        phase: "next-step",
+        kind: "outcome",
+        obligation: state.status,
+        note: `final_gate_red scope=${scope} command=${failed ? failed.argv.join(" ") : "unknown"}`,
+    });
+    const nextCommand = loaderCommand("next-step");
+    return {
+        kind: "emit",
+        step: await writeCurrentStep({
+            stepKind: "final_gate_red",
+            status: "blocked",
+            runId: stateRunId(state),
+            repoRoot: root,
+            artifactsDir,
+            prompt: `
+# Remediation paused — the repository suite is red
+
+The tool-owned gate (${scope}) ran the repository's own build/typecheck/test
+floor and it FAILED. Nothing about this run has been changed: every item keeps
+the status it had, the run stays in the same phase, and no work was discarded.
+
+Failing command:
+
+\`${failingCommand}\`
+
+The captured output tail is recorded at:
+
+\`${recordPath}\`
+
+A red here is whole-repo and says nothing about which remediation item caused
+it — it may not be this run's doing at all (a commit landed alongside the run is
+enough). So this is a PAUSE, not a verdict on the work.
+
+Fix the failing command — or confirm it was already broken independently of this
+run — then run:
+
+\`${nextCommand}\`
+
+The gate re-runs from scratch. The moment it is green the run continues exactly
+where it left off.
+
+Re-run it DELIBERATELY, not on a timer: there is no cached verdict, so every
+next-step taken while the suite is red re-runs the entire gate — a full build
+plus the whole suite, minutes, holding the run's phase lock the whole time.
+Fix something first, then re-run.
+`,
+            allowedCommands: [nextCommand],
+            stopCondition: "Stop. Make the repository suite green, then re-run next-step to resume the run.",
+            artifactPaths: { final_gate_record: recordPath },
+        }),
+    };
 }
 /**
  * Whole-repo test-suite gate at a foundations→consumers PHASE BOUNDARY (T3). Runs
@@ -1909,24 +2361,42 @@ function finalGateDisabled(options) {
  * so an integration break introduced by a just-completed foundations phase is
  * caught — and attributed to that phase — before consumers are built on top of it
  * (strictly earlier + more attributable than the all-terminal gate, whose red is
- * unattributable across every phase). Reuses the all-terminal gate's coarse
- * re-block + bounded auto-terminate machinery (INV-RS-09 / CE-003) and its shared
- * sidecar so a no-human host converges deterministically.
+ * unattributable across every phase).
+ *
+ * A red RECORDS and PAUSES — see {@link emitFinalGateRedStep}. It mutates no item,
+ * moves no phase, and writes no state. (It used to re-open every item and, at a
+ * bound, abandon the run; that backstop is gone, along with the counter sidecar
+ * that drove it.)
  *
- * Returns a re-block / terminate transition when the gate is RED, or null when no
- * gate is due this pass OR the gate is GREEN — in which case the caller proceeds
- * to dispatch the phase.
+ * Returns the pause step when the gate is RED, or null when no gate is due this
+ * pass OR the gate is GREEN — in which case the caller proceeds to dispatch the
+ * phase.
  */
 async function runPhaseBoundaryGate(ctx) {
-    const { root, artifactsDir, state, options, store, runLogger } = ctx;
-    if (finalGateDisabled(options))
-        return null;
+    const { root, artifactsDir, state, options, runLogger } = ctx;
+    // Whether a gate is DUE is decided BEFORE whether it is suppressed. The old
+    // order asked the suppression first and returned, so a disabled run could not
+    // tell "no gate was due this pass" from "a gate was due and skipped" — and the
+    // second is the one worth recording.
     const phase = phaseBoundaryToGate(state);
     if (phase == null)
         return null;
-    const sidecar = await readFinalGateSidecar(artifactsDir);
-    if (sidecar.terminated)
-        return null; // bounded backstop already converged
+    const scope = `phase ${phase} boundary`;
+    const disabledReason = finalGateDisabledReason(options);
+    if (disabledReason !== null) {
+        await recordFinalGateOutcome({
+            artifactsDir,
+            state,
+            scope,
+            gateKey: `phase_boundary_gate phase=${phase}`,
+            runLogger,
+            outcome: "disabled",
+            passed: false,
+            commandsRun: 0,
+            reason: disabledReason,
+        });
+        return null;
+    }
     const gateStart = Date.now();
     runLogger.event({
         phase: "next-step",
@@ -1935,46 +2405,47 @@ async function runPhaseBoundaryGate(ctx) {
         note: `phase_boundary_gate phase=${phase}`,
     });
     const gate = await runToolOwnedFinalGate(root, { runner: options.finalGateRunner });
-    runLogger.event({
-        phase: "next-step",
-        kind: "executor_end",
-        obligation: state.status,
-        note: `phase_boundary_gate phase=${phase} passed=${gate.passed}`,
-        duration_ms: Date.now() - gateStart,
+    await recordFinalGateOutcome({
+        artifactsDir,
+        state,
+        scope,
+        gateKey: `phase_boundary_gate phase=${phase}`,
+        runLogger,
+        outcome: gate.outcome,
+        passed: gate.passed,
+        commandsRun: gate.results.length,
+        ...(gate.outcome === "scoped_out"
+            ? { reason: "target is not the audit-tools monorepo" }
+            : {}),
+        durationMs: Date.now() - gateStart,
     });
     if (gate.passed)
-        return null; // green → dispatch this phase
-    // RED at the boundary: the just-completed lower phases broke the whole-repo
-    // suite. Coarse re-block (INV-RS-09) + bounded auto-terminate (CE-003), exactly
-    // as the all-terminal gate — never the human triage prompt.
-    const failedCmd = gate.results.find((r) => !r.passed);
-    const summary = failedCmd
-        ? `Phase ${phase} boundary gate — failing command: ${failedCmd.argv.join(" ")} (exit ${failedCmd.exit_code}).`
-        : `Phase ${phase} boundary gate failed.`;
-    const decision = applyCoarseReblock(state, sidecar.count, summary);
-    await writeFinalGateSidecar(artifactsDir, decision.next_count, decision.action === "terminal_blocked");
-    runLogger.event({
-        phase: "next-step",
-        kind: "outcome",
-        obligation: state.status,
-        note: `phase_boundary_coarse_reblock phase=${phase} action=${decision.action} count=${decision.next_count}`,
+        return null; // green (or declared-out-of-scope) → dispatch
+    // RED at the boundary. The next phase does NOT dispatch — but nothing is
+    // re-opened or closed either; the run pauses exactly where it stands.
+    return emitFinalGateRedStep({
+        root,
+        artifactsDir,
+        state,
+        scope,
+        gate,
+        runLogger,
     });
-    decision.state.status =
-        decision.action === "reattempt_all" ? "implementing" : "closing";
-    await store.saveState(decision.state);
-    return { kind: "transition", state: decision.state };
 }
 async function handleAllTerminalTransition(root, artifactsDir, state, store, options, runLogger) {
-    const gateDisabled = finalGateDisabled(options);
-    const sidecar = await readFinalGateSidecar(artifactsDir);
+    const disabledReason = finalGateDisabledReason(options);
+    const gateDisabled = disabledReason !== null;
+    const scope = "all-terminal final gate";
     // The tool-owned final gate (INV-RS-10) runs at the single all-terminal →
-    // closing funnel, exactly once per arrival here. It is skipped when:
+    // closing funnel, on EVERY arrival here. It is skipped only when:
     //  - there is nothing resolved to validate (everything blocked/skipped), or
-    //  - the bounded backstop already terminated (CE-003 — never re-run after), or
     //  - it is explicitly disabled for test hermeticity.
-    // The gate is INDEPENDENT of plan.test_command and runs through the
-    // env-scrubbing runTracked path.
-    if (!gateDisabled && !sidecar.terminated && hasResolvedItems(state)) {
+    // There is deliberately no third "already gave up" skip: the flag that used to
+    // provide one made a run that hit the old backstop's bound skip the suite check
+    // permanently, so the gate it exists to enforce stopped running exactly when it
+    // mattered most. The gate is INDEPENDENT of plan.test_command and runs through
+    // the env-scrubbing runTracked path.
+    if (!gateDisabled && hasResolvedItems(state)) {
         const gateStart = Date.now();
         runLogger.event({
             phase: "next-step",
@@ -1983,37 +2454,53 @@ async function handleAllTerminalTransition(root, artifactsDir, state, store, opt
             note: "tool_owned_final_gate",
         });
         const gate = await runToolOwnedFinalGate(root, { runner: options.finalGateRunner });
-        runLogger.event({
-            phase: "next-step",
-            kind: "executor_end",
-            obligation: state.status,
-            note: `tool_owned_final_gate passed=${gate.passed}`,
-            duration_ms: Date.now() - gateStart,
+        await recordFinalGateOutcome({
+            artifactsDir,
+            state,
+            scope,
+            gateKey: "tool_owned_final_gate",
+            runLogger,
+            outcome: gate.outcome,
+            passed: gate.passed,
+            commandsRun: gate.results.length,
+            ...(gate.outcome === "scoped_out"
+                ? { reason: "target is not the audit-tools monorepo" }
+                : {}),
+            durationMs: Date.now() - gateStart,
         });
         if (!gate.passed) {
-            // INV-RS-09: a whole-repo gate red is unattributable → coarse re-block.
-            // CE-003: bounded, monotonic auto-terminate to terminal `blocked`.
-            const failedCmd = gate.results.find((r) => !r.passed);
-            const summary = failedCmd
-                ? `Failing command: ${failedCmd.argv.join(" ")} (exit ${failedCmd.exit_code}).`
-                : "Tool-owned final gate failed.";
-            const decision = applyCoarseReblock(state, sidecar.count, summary);
-            await writeFinalGateSidecar(artifactsDir, decision.next_count, decision.action === "terminal_blocked");
-            runLogger.event({
-                phase: "next-step",
-                kind: "outcome",
-                obligation: state.status,
-                note: `coarse_reblock action=${decision.action} count=${decision.next_count}`,
+            // A whole-repo red at the closing funnel is exactly as unattributable as
+            // one at a phase boundary, so it gets the same answer: record and pause.
+            // The run does NOT advance to `closing` — closing on a red would write a
+            // report claiming an outcome the suite never corroborated.
+            return emitFinalGateRedStep({
+                root,
+                artifactsDir,
+                state,
+                scope,
+                gate,
+                runLogger,
             });
-            // reattempt_all → re-open items to pending and re-emit the host workload
-            // (NEVER the human triage prompt — CE-003 no-human-host path); terminal_blocked
-            // → everything non-skip is now blocked, so close writes the partial report.
-            decision.state.status =
-                decision.action === "reattempt_all" ? "implementing" : "closing";
-            await store.saveState(decision.state);
-            return { kind: "transition", state: decision.state };
         }
     }
+    else {
+        // The gate was DUE at the closing funnel and did not run. Recorded, with
+        // WHICH suppression did it — the run is about to transition to `closing`
+        // and write a completion report, and without this the report would be
+        // byte-identical to one produced after a green floor.
+        await recordFinalGateOutcome({
+            artifactsDir,
+            state,
+            scope,
+            gateKey: "tool_owned_final_gate",
+            runLogger,
+            outcome: "disabled",
+            passed: false,
+            commandsRun: 0,
+            reason: disabledReason ??
+                "no verified-complete items to validate (nothing resolved)",
+        });
+    }
     state.status = "closing";
     await store.saveState(state);
     return { kind: "transition", state };
@@ -2368,7 +2855,11 @@ export const INTENT_INTERPRETATION_SCHEMA_VERSION = "remediate-code-intent-inter
  * throws into the decide loop. The raw `free_form_intent` string is NOT returned
  * or threaded anywhere — only the structured `InterpretedIntent` is (INV-S04).
  */
-export async function interpretConfirmedCheckpointIntent(artifactsDir, checkpoint) {
+export async function interpretConfirmedCheckpointIntent(artifactsDir, checkpoint, 
+// Optional so the exported helper stays callable standalone; the decide loop
+// always supplies it, because an unencodable clause is an operator-visible
+// loss of intent and belongs in the durable log, not only on stderr.
+runLogger) {
     if (!checkpoint || checkpoint.confirmed_by !== "host")
         return null;
     const raw = checkpoint.free_form_intent;
@@ -2388,6 +2879,13 @@ export async function interpretConfirmedCheckpointIntent(artifactsDir, checkpoin
         // Best-effort sidecar: a write failure must never block the decide loop.
     }
     if (interpreted.unencodableClauses.length > 0) {
+        runLogger?.event({
+            phase: "next-step",
+            kind: "outcome",
+            obligation: "interpret_intent",
+            note: `intent_unencodable_clauses count=${String(interpreted.unencodableClauses.length)} ` +
+                `clauses=${interpreted.unencodableClauses.join("; ")}`,
+        });
         process.stderr.write(`[remediate-code] free_form_intent: ${interpreted.unencodableClauses.length} ` +
             `clause(s) could not be encoded as lens/priority/scope signals and are ` +
             `surfaced for promotion to constraints: ` +
@@ -2532,8 +3030,8 @@ function buildPreIntakeObligations(ctx, snapshot) {
                 !existsSync(interpretationPath)
                 ? "missing"
                 : "satisfied",
-            execute: async (state) => {
-                await interpretConfirmedCheckpointIntent(artifactsDir, existingCheckpoint);
+            execute: async (state, c) => {
+                await interpretConfirmedCheckpointIntent(artifactsDir, existingCheckpoint, c.runLogger);
                 return { kind: "transition", state };
             },
         },
@@ -2587,7 +3085,7 @@ function buildPreIntakeObligations(ctx, snapshot) {
             id: "pending_intake",
             derive: (state) => (state == null ? "missing" : "satisfied"),
             execute: async (_state, c) => {
-                const outcome = await handlePendingIntake(c.root, c.artifactsDir, c.options);
+                const outcome = await handlePendingIntake(c.root, c.artifactsDir, c.options, c.runLogger);
                 if (outcome && "step_kind" in outcome) {
                     return { kind: "emit", step: outcome };
                 }
@@ -2714,14 +3212,14 @@ function buildMainObligations(ctx) {
                 const pendingBlocks = implementableBlocks(s);
                 if (pendingBlocks.length > 0) {
                     // Per-phase boundary gate (T3): before opening a phase P > 0, run the
-                    // whole-repo suite once over the just-landed foundations. A red re-blocks
-                    // here (transition); green / no-boundary falls through to dispatch.
+                    // whole-repo suite once over the just-landed foundations. A red PAUSES
+                    // here (an emitted step, no state written); green / no-boundary falls
+                    // through to dispatch.
                     const gated = await runPhaseBoundaryGate({
                         root,
                         artifactsDir,
                         state: s,
                         options,
-                        store,
                         runLogger,
                     });
                     if (gated)
@@ -2732,6 +3230,7 @@ function buildMainObligations(ctx) {
                         state: s,
                         options,
                         store,
+                        runLogger,
                     });
                 }
                 // Dead-end pending nodes whose dependency never reached verified-complete
@@ -2810,17 +3309,56 @@ function buildMainObligations(ctx) {
         },
     ];
 }
+/**
+ * ONE mutex for the WHOLE advance.
+ *
+ * The pre-intake segment used to run OUTSIDE the lock, with only the main
+ * advance inside it — and the pre-intake segment is where the review-approval
+ * gate and the autonomous leftover emit live, so two concurrent next-step calls
+ * could both take the autonomous branch. Serializing only the second half made
+ * the mutex a statement about which code was easy to wrap, not about which work
+ * is serial: the entire state-machine advance is serial, so the entire advance
+ * is guarded.
+ *
+ * The state is loaded once here (outside) purely to name the run in the
+ * `phase_busy` step; the advance re-loads under the lock, so a peer that
+ * persisted between the two is never clobbered.
+ */
 async function decideNextStepLoop(options, runLogger) {
     const root = resolveRoot(options.root);
     const artifactsDir = resolveArtifactsDir(root, options.artifactsDir);
     await mkdir(artifactsDir, { recursive: true });
     const store = new StateStore(artifactsDir);
-    let state = await store.loadState();
+    const entryState = await store.loadState();
     runLogger.event({
         phase: "next-step",
         kind: "state",
-        obligation: state?.status ?? "pending",
+        obligation: entryState?.status ?? "pending",
     });
+    try {
+        return await withFileLock(join(artifactsDir, "phase.lock"), () => advanceUnderPhaseLock({ root, artifactsDir, store, options, runLogger }), PHASE_LOCK_TIMEOUT_MS);
+    }
+    catch (error) {
+        if (error instanceof FileLockTimeoutError) {
+            return buildPhaseBusyStep({
+                root,
+                artifactsDir,
+                runId: stateRunId(entryState),
+            });
+        }
+        throw error;
+    }
+}
+/**
+ * The serial state-machine advance itself — pre-intake gates, then the main
+ * obligation fold. Runs with `<artifactsDir>/phase.lock` HELD for its whole
+ * duration; never call it without that lock.
+ */
+async function advanceUnderPhaseLock(deps) {
+    const { root, artifactsDir, store, options, runLogger } = deps;
+    // Loaded FRESH under the mutex: a peer may have advanced and persisted state
+    // between the entry read and this process winning the lock.
+    let state = await store.loadState();
     // step_count is incremented once per host invocation. The `counted` flag guards
     // the shared `countStep` closure so the forceReplan preamble, the pre-intake
     // obligation executors, and the post-intake count point can never double-count
@@ -2844,7 +3382,7 @@ async function decideNextStepLoop(options, runLogger) {
     // transitions, never a recursive decideNextStepLoop), so this fires at most once.
     if (options.forceReplan && state != null) {
         await countStep(state);
-        state = await forceReplanFromExistingIntake(root, artifactsDir, state, store);
+        state = await forceReplanFromExistingIntake(root, artifactsDir, state, store, runLogger);
     }
     // Pre-read the once-async signals the pre-intake derive()s consume
     // synchronously (no transition inside this advance call rewrites either file).
@@ -2890,32 +3428,15 @@ async function decideNextStepLoop(options, runLogger) {
         return handleNoState(root, artifactsDir);
     }
     await countStep(state);
-    // One generic filesystem mutex serializes the in-process MAIN advance so two
-    // joining peers cannot run the same serial phase and clobber state.json. It is
-    // coordination only: host execution, grouping, and concurrency stay outside
-    // audit-tools.
-    const phaseRunId = stateRunId(state);
-    try {
-        const main = await withFileLock(join(artifactsDir, "phase.lock"), async () => {
-            // Re-load fresh under the mutex: a peer may have advanced and persisted
-            // state between our initial load and winning the lock.
-            const advanceState = (await store.loadState()) ?? state;
-            return {
-                advanceState,
-                outcome: await advance({ priority: MAIN_PRIORITY, obligations: buildMainObligations(ctx) }, advanceState, ctx),
-            };
-        }, PHASE_LOCK_TIMEOUT_MS);
-        if (main.outcome.step)
-            return main.outcome.step;
-        // The unhandled catch-all always emits on a non-null state, so a null step
-        // here is unreachable; keep an explicit fallback rather than a non-null assert.
-        return handleUnhandledState(root, artifactsDir, main.advanceState);
-    }
-    catch (error) {
-        if (error instanceof FileLockTimeoutError) {
-            return buildPhaseBusyStep({ root, artifactsDir, runId: phaseRunId });
-        }
-        throw error;
-    }
+    // Re-read between the two folds: a pre-intake executor may persist through the
+    // store without returning the persisted value, so the main fold reads from disk
+    // exactly as it did when it owned its own lock acquisition.
+    const advanceState = (await store.loadState()) ?? state;
+    const main = await advance({ priority: MAIN_PRIORITY, obligations: buildMainObligations(ctx) }, advanceState, ctx);
+    if (main.step)
+        return main.step;
+    // The unhandled catch-all always emits on a non-null state, so a null step
+    // here is unreachable; keep an explicit fallback rather than a non-null assert.
+    return handleUnhandledState(root, artifactsDir, advanceState);
 }
 //# sourceMappingURL=nextStep.js.map