audit-tools 0.51.7 → 0.51.9

package/dist/audit/cli/nextStepHelpers.js

@@ -1,3 +1,4 @@
+// sites-pinned: tests/audit/next-step-helpers.test.ts, tests/audit/charter-emit-order.test.ts, tests/audit/executor-registry-sync.test.ts, tests/audit/pipeline-integration.test.ts
 /**
  * Extracted helpers for the next-step command.
  *
@@ -8,14 +9,14 @@
 import { randomUUID } from "node:crypto";
 import { mkdir, readFile, unlink } from "node:fs/promises";
 import { join, relative } from "node:path";
-import { advance, describeStoppedFold, RunLogger, compareCodeUnits, hashContent, isFileMissingError, isJsonParseError, isRecord, readJsonFile, readTrailingSubmissionRefusals, persistAnalyzerConsent, persistAnalyzerSettings, writeJsonFile, } from "audit-tools/shared";
+import { advance, describeStoppedFold, RunLogger, compareCodeUnits, hashContent, isFileMissingError, isJsonParseError, isMissingObservation, isRecord, readJsonFile, readSubmissionIngestHistory, readTrailingSubmissionRefusals, persistAnalyzerConsent, persistAnalyzerSettings, writeJsonFile, } from "audit-tools/shared";
 import { loadArtifactBundle, promoteFinalAuditReport, } from "../io/artifacts.js";
 import { auditReportPath, groundDesignFindings, laneAssetsDir, promotedAuditReportPath, } from "audit-tools/shared";
 import { charterExtractionKindsForCeiling } from "./charterExtractionPrompt.js";
 import { archiveCharterPackets } from "../orchestrator/charterPacketArchive.js";
 import { LANE_SUBMISSION_SCHEMAS, charterLaneSchema, describeSubmissionShapeMismatch, unwrapSubmissionArray, } from "./laneValidators.js";
-import { ConceptualJudgeSubmissionSchema, buildConceptualReviewAdjudication, deriveConceptualVerificationStatus, loadConceptualPerspectiveFindings, MalformedConceptualPerspectivesError, readConceptualReviewRoundManifest, } from "../types/conceptualAdjudication.js";
-import { advanceAudit, engineMaxTransitions, findExecutorFailure, runSingleAdvanceStep, MAX_DRAIN_STEPS, } from "../orchestrator/advance.js";
+import { ConceptualJudgeSubmissionSchema, buildConceptualReviewAdjudication, deriveConceptualVerificationStatus, loadConceptualPerspectiveFindings, MalformedConceptualPerspectivesError, readConceptualReviewRoundManifest, suppliedToolVerdictIssue, } from "../types/conceptualAdjudication.js";
+import { advanceAudit, engineMaxTransitions, findExecutorFailure, runSingleAdvanceStep, startAdvanceHeartbeat, MAX_DRAIN_STEPS, } from "../orchestrator/advance.js";
 import { buildDesignReviewSnapshot, isDesignReviewStale, } from "../orchestrator/designReviewSnapshot.js";
 import { computeStaleArtifacts, emitStalenessRecord, isMetadataMigrationStaleness, resetStalenessDedup, } from "../orchestrator/staleness.js";
 import { commitFold, createFoldTransaction, markSubmissionApplied, describeQuarantineLocation, quarantineLocationPhrase, quarantineSubmissionFile, quarantineSurvivalNote, recoverStagedSubmissions, stageLaneSubmission, } from "./foldTransaction.js";
@@ -99,7 +100,8 @@ const NEXT_STEP_RETURN_KIND_TABLE = {
     design_review_contract: true,
     design_review_conceptual: true,
     charter_extraction: true,
-    charter_delta: true,
+    charter_comparison: true,
+    charter_fidelity: true,
     charter_clarification: true,
     systemic_challenge: true,
     confirm_intent: true,
@@ -408,7 +410,10 @@ export async function handleGraphEnrichmentBranch(params, bundle, state, analyze
  *   - `design_review_contract` → only contract pass still needed.
  *   - `design_review_conceptual` → only conceptual pass still needed.
  *
- * Also handles legacy `design-review-findings.json` for backward compatibility.
+ * Exactly these two passes exist. The pre-split combined submission
+ * (`design-review-findings.json`) is retired: it is neither polled here nor
+ * translated anywhere, and a pre-split directory is re-asked for both current
+ * passes (see `orchestrator/state.ts`).
  */
 /** Whether a completed design-review pass has gone stale vs. its snapshot. */
 function passIsStale(bundle, pass) {
@@ -573,6 +578,23 @@ async function consumeConceptualSubmission(artifactsDir, tx) {
     if (incoming.status === "quarantined") {
         return { ...incoming, lane };
     }
+    // BEFORE the schema parse, deliberately. The schema omits
+    // `verification_status` from every submitted finding, so a supplied value is
+    // stripped SILENTLY by the parse below — and the check that names the field
+    // lived only inside `buildConceptualReviewAdjudication`, which is reached with
+    // the ALREADY-PARSED submission. It therefore never fired here, and a judge
+    // could supply the field this whole vocabulary derives and be told nothing.
+    // Refusing it at the gate is what makes the naming reach the production path.
+    const suppliedStatus = suppliedToolVerdictIssue(incoming.value);
+    if (suppliedStatus !== null) {
+        const quarantinePath = await quarantineMisshapedSubmission(artifactsDir, incoming.path, lane, suppliedStatus);
+        return {
+            status: "quarantined",
+            quarantinePath,
+            lane,
+            reason: suppliedStatus,
+        };
+    }
     const parsed = ConceptualJudgeSubmissionSchema.safeParse(incoming.value);
     if (!parsed.success) {
         const quarantinePath = await quarantineMisshapedSubmission(artifactsDir, incoming.path, lane, parsed.error);
@@ -606,9 +628,19 @@ async function consumeConceptualSubmission(artifactsDir, tx) {
             generatedAt: new Date().toISOString(),
         });
         const refusals = await readTrailingSubmissionRefusals(artifactsDir, manifest.perspectives.map((p) => laneSubmissionId(p.lane_id)), { runId: AUDIT_GATE_SUBMISSION_SCOPE });
+        // ONE ledger read for this batch. `readTrailingSubmissionRefusals` above
+        // already paid for a scan; reusing ITS map as the accepted-history view
+        // would be wrong (it holds refusals, not acceptances) and re-reading per
+        // perspective would scan the ledger once per lane. So the shared view is
+        // taken here, and the refusal question above keeps its own reader — the two
+        // ask different questions and a single scan answering both would have to
+        // reimplement each.
+        const perspectiveHistory = await readSubmissionIngestHistory(artifactsDir, {
+            runId: AUDIT_GATE_SUBMISSION_SCOPE,
+        });
         for (const perspective of manifest.perspectives) {
             if (refusals.has(laneSubmissionId(perspective.lane_id))) {
-                await recordLaneOutcome(artifactsDir, perspective.lane_id, { kind: "accepted" });
+                await recordLaneOutcome(artifactsDir, perspective.lane_id, { kind: "accepted" }, perspectiveHistory);
             }
         }
         // THE observation boundary for this round's perspective lanes. The tool
@@ -825,7 +857,7 @@ export async function handleDesignReviewBranch(params, bundle, state, tx) {
         if (consumed) {
             // A review changes the assessment's content, not its structural baseline.
             // Only a newly produced adjudication may bind the new assessment revision;
-            // a contract/legacy update must leave an older adjudication stale.
+            // a contract-only update must leave an older adjudication stale.
             next.artifact_metadata = computeArtifactMetadata(next, bundle.artifact_metadata, conceptualAdjudication !== undefined && conceptualAdjudication !== bundle.conceptual_review_adjudication
                 ? ["conceptual_review_adjudication.json"]
                 : []);
@@ -867,32 +899,15 @@ export async function handleDesignReviewBranch(params, bundle, state, tx) {
                 reason,
             }) ?? assessment;
     };
-    // Legacy: consume the old combined findings submission. Tolerant-unwrap or
-    // quarantine (never a bare unconditional delete) — see the block comment above.
-    const legacyResult = await consumeArraySubmission(params.artifactsDir, GATE_LANES.design_review_legacy, tx);
-    if (legacyResult.status === "quarantined") {
-        assessment =
-            withRejectedDesignReviewSubmission(assessment, "legacy", legacyResult) ??
-                assessment;
-        return { action: "continue", bundle: carried() };
-    }
-    if (legacyResult.status === "ok") {
-        if (assessment) {
-            assessment = {
-                ...assessment,
-                review_findings: groundDesignFindings(legacyResult.value, bundle.repo_manifest),
-                reviewed: true,
-                rejected_submissions: (assessment.rejected_submissions ?? []).filter((r) => r.pass !== "legacy"),
-            };
-            consumed = true;
-            markSubmissionApplied(tx, legacyResult.path);
-            return { action: "continue", bundle: carried() };
-        }
-        await holdWithoutTarget("legacy", GATE_LANES.design_review_legacy, legacyResult.path);
-        return { action: "continue", bundle: carried() };
-    }
-    // absent: fall through to the contract/conceptual check.
-    // New: consume contract-findings and/or conceptual-findings independently.
+    // Only the two CURRENT passes are polled. The pre-split combined-findings lane
+    // (`design_review_legacy`) was retired: it was a third judgment type that no
+    // longer corresponds to anything the tool emits, and leaving it polled meant a
+    // directory written by the pre-split release kept satisfying a pass the modern
+    // tool never asked for. A resumed pre-split run now leaves BOTH modern
+    // obligations unmet and is re-asked for each pass in its current shape — never
+    // translated from the old lane. See the invalidation at load —
+    // `designReviewPassState` in `orchestrator/state.ts`, which reads only the two
+    // modern per-pass flags and never the retired combined one.
     const contractResult = await consumeArraySubmission(params.artifactsDir, GATE_LANES.design_review_contract, tx);
     const conceptualResult = await consumeConceptualSubmission(params.artifactsDir, tx);
     if (contractResult.status === "quarantined") {
@@ -1036,6 +1051,7 @@ export async function handleSynthesisNarrativeBranch(params, bundle, state, tx)
             artifactsDir: p.artifactsDir,
             preferredExecutor: "synthesis_narrative_executor",
             narrativeResultsPath: path,
+            scopeIndexMemo: p.scopeIndexMemo,
         }, foldBundle),
         // Narrative disabled: omit (run the deterministic omit executor below).
         // Single-sourced with the plan draw's classifier (obligationPolicy.ts).
@@ -1068,6 +1084,7 @@ export async function handleIntentEquivalenceBranch(params, bundle, state, tx) {
                 artifactsDir: params.artifactsDir,
                 preferredExecutor: "intent_equivalence_executor",
                 intentEquivalenceVerdictPath: incoming.path,
+                scopeIndexMemo: params.scopeIndexMemo,
             }, bundle);
             markSubmissionApplied(tx, incoming.path);
             return { action: "continue", bundle: applied.updated_bundle };
@@ -1103,6 +1120,7 @@ export async function handleCriticalFlowFallbackBranch(params, bundle, state, tx
             artifactsDir: p.artifactsDir,
             preferredExecutor: "critical_flow_fallback_executor",
             criticalFlowFallbackResultsPath: path,
+            scopeIndexMemo: p.scopeIndexMemo,
         }, foldBundle),
         // Never omit: the obligation is only reached when the deterministic bar
         // failed, and the host is always available to author the enrichment.
@@ -1127,16 +1145,15 @@ export async function handleCharterExtractionBranch(params, bundle, state, tx) {
     if (charterExtractionOmits(bundle)) {
         return { action: "run_omit" };
     }
-    // Per-kind blind lanes (design resolution 2): one submission file per kind,
-    // each validated at THIS chokepoint — schema shape + kind purity (a lane may
-    // only carry its own kind; anything else is a mis-routed submission) + scope
-    // grounding (design resolution 4: every teleology node's file scope must be
-    // repo paths — a lane citing files the repo does not contain is refused
-    // whole, naming them, never silently narrowed). An invalid lane is
-    // quarantined loudly and the step re-emits naming it; valid lanes stay on
-    // disk untouched (K-of-N resume), and only when EVERY lane is present and
-    // valid does the tool merge them into the single submission the executor
-    // ingests (`assembleCharters` joins teleologies by file-set overlap).
+    // Per-kind blind lanes (design resolution 2): one goal-DAG submission file per
+    // kind, each validated at THIS chokepoint — schema shape + kind purity (a lane
+    // may only carry its own kind; anything else is a mis-routed submission). An
+    // invalid lane is quarantined loudly and the step re-emits naming it; valid
+    // lanes stay on disk untouched (K-of-N resume), and only when EVERY lane is
+    // present and valid does the tool merge them into the single submission the
+    // executor ingests (`assembleLaneGraph` per lane: cycles refused, levels
+    // derived, scopes grounded against the repo universe with every unknown file
+    // named — never silently narrowed).
     const kinds = charterExtractionKindsForCeiling(ceiling);
     const universe = new Set((bundle.repo_manifest?.files ?? []).map((file) => file.path));
     const laneValues = new Map();
@@ -1172,7 +1189,7 @@ export async function handleCharterExtractionBranch(params, bundle, state, tx) {
         // would make a later staleness-triggered re-extraction read them as fresh
         // results and silently skip re-authoring.
         const merged = {
-            nodes: kinds.flatMap((kind) => laneValues.get(kind).value.nodes),
+            lanes: kinds.map((kind) => laneValues.get(kind).value),
         };
         // The merged submission is TOOL-written, so it lives with the other lane
         // assets rather than under `submissions/` (which holds only what a host
@@ -1184,6 +1201,7 @@ export async function handleCharterExtractionBranch(params, bundle, state, tx) {
             artifactsDir: params.artifactsDir,
             preferredExecutor: "charter_extraction_executor",
             charterSubmissionPath: mergedPath,
+            scopeIndexMemo: params.scopeIndexMemo,
         }, bundle);
         await unlink(mergedPath).catch(() => { });
         for (const lane of laneValues.values()) {
@@ -1216,30 +1234,47 @@ export async function handleCharterExtractionBranch(params, bundle, state, tx) {
     return { action: "return", result: { kind: "charter_extraction", state, bundle } };
 }
 /**
- * Handle the `charter_delta_executor` submission-polling block (Phase C.2 —
- * the INDEPENDENT delta-miner). Mirrors the charter-extraction branch:
- *   - a pending `charter_delta` lane submission → route+gate it via the preferred
- *     executor (ingest), then `continue`;
- *   - otherwise, when the register is NOT `deltas_pending` (extraction omitted, or
- *     found no subsystems to mine) → `run_omit` (the deterministic executor settles
- *     the register — no host turn);
- *   - a `deltas_pending` register with no submission yet → `return` the host step
- *     that renders the charter-delta prompt for the independent miner.
+ * Handle the `charter_comparison_executor` submission-polling block (steps 2–3
+ * — the comparison reader). Mirrors the charter-extraction branch:
+ *   - a pending `charter_comparison` lane submission → assemble + pre-check it
+ *     via the preferred executor (ingest), then `continue`;
+ *   - otherwise, when the register is NOT `comparison_pending` → `run_omit`;
+ *   - a `comparison_pending` register with no submission yet → `return` the host
+ *     step that renders the comparison prompt.
+ */
+export async function handleCharterComparisonBranch(params, bundle, state, tx) {
+    return runOmittableGate({
+        kind: "charter_comparison",
+        lane: GATE_LANES.charter_comparison,
+        schema: LANE_SUBMISSION_SCHEMAS[GATE_LANES.charter_comparison],
+        apply: (_value, path, p, foldBundle) => runAuditStepUnlocked({
+            root: p.root,
+            artifactsDir: p.artifactsDir,
+            preferredExecutor: "charter_comparison_executor",
+            charterComparisonSubmissionPath: path,
+            scopeIndexMemo: p.scopeIndexMemo,
+        }, foldBundle),
+        shouldOmit: (b) => !(b.charter_register?.comparison_pending === true),
+    }, params, bundle, state, tx);
+}
+/**
+ * Handle the `charter_fidelity_executor` submission-polling block (step 4 — the
+ * separate fidelity lane). Same three arms as the comparison branch, keyed on
+ * `fidelity_pending`.
  */
-export async function handleCharterDeltaBranch(params, bundle, state, tx) {
+export async function handleCharterFidelityBranch(params, bundle, state, tx) {
     return runOmittableGate({
-        kind: "charter_delta",
-        lane: GATE_LANES.charter_delta,
-        schema: LANE_SUBMISSION_SCHEMAS[GATE_LANES.charter_delta],
+        kind: "charter_fidelity",
+        lane: GATE_LANES.charter_fidelity,
+        schema: LANE_SUBMISSION_SCHEMAS[GATE_LANES.charter_fidelity],
         apply: (_value, path, p, foldBundle) => runAuditStepUnlocked({
             root: p.root,
             artifactsDir: p.artifactsDir,
-            preferredExecutor: "charter_delta_executor",
-            charterDeltaSubmissionPath: path,
+            preferredExecutor: "charter_fidelity_executor",
+            charterFidelitySubmissionPath: path,
+            scopeIndexMemo: p.scopeIndexMemo,
         }, foldBundle),
-        // Nothing to mine (extraction omitted or no subsystems): settle
-        // deterministically, no host turn.
-        shouldOmit: (b) => !(b.charter_register?.deltas_pending === true),
+        shouldOmit: (b) => !(b.charter_register?.fidelity_pending === true),
     }, params, bundle, state, tx);
 }
 /**
@@ -1266,6 +1301,7 @@ export async function handleCharterClarificationBranch(params, bundle, state, tx
             artifactsDir: p.artifactsDir,
             preferredExecutor: "charter_clarification_executor",
             clarificationAnswersPath: path,
+            scopeIndexMemo: p.scopeIndexMemo,
         }, foldBundle),
         // The omit predicate is single-sourced with the plan draw's classifier
         // (obligationPolicy.ts) — the two draws must agree on the boundary.
@@ -1302,6 +1338,7 @@ export async function handleSystemicChallengeBranch(params, bundle, state, tx) {
             systemicChallengeSubmissionHash: staged.contentHash === undefined
                 ? undefined
                 : hashContent(`${lane}\n${staged.contentHash}`),
+            scopeIndexMemo: p.scopeIndexMemo,
         }, foldBundle),
         // Single-sourced with the plan draw's classifier (obligationPolicy.ts).
         shouldOmit: systemicChallengeOmits,
@@ -1345,6 +1382,8 @@ export async function executeAndRecord(params, analyzers, decision, index, lastS
             since: params.since,
             lineIndex: indexes.lineIndex,
             sizeIndex: indexes.sizeIndex,
+            // ONE git-index probe per fold (see `ScopeIndexMemo`).
+            scopeIndexMemo: params.scopeIndexMemo,
         });
         await writeJsonFile(join(params.artifactsDir, "steps", "deterministic-progress.json"), {
             iteration: index + 1,
@@ -1514,10 +1553,68 @@ export async function checkFinalizationCycle(ctx) {
             "obligations are erroneously invalidating each other.",
     };
 }
-const EMPTY_FOLD_ADVISORIES = {
-    ingestIssues: [],
-    validationWarnings: [],
-};
+/**
+ * A FRESH empty carry — a factory, never a shared constant. The carry is
+ * MUTATED in place (`mergeFoldAdvisoriesInto` appends to both arrays), so two
+ * holders that received the same object would alias: the persistent carry is
+ * read as `emptyFoldAdvisories()`, merged into, and persisted, and a shared
+ * constant would mean the "empty" sentinel itself grew the advisories — after
+ * which every `writePendingAdvisories(emptyFoldAdvisories())` call is no longer
+ * empty, stops deleting the file, and re-states the advisory on EVERY later
+ * emission. That is not hypothetical: it is what a shallow spread of the
+ * constant did, and it turned the once-only property into once-per-emission.
+ */
+function emptyFoldAdvisories() {
+    return { ingestIssues: [], validationWarnings: [] };
+}
+/** `<artifactsDir>/steps/pending-advisories.json` — the drainable prompt carry. */
+function pendingAdvisoriesPath(artifactsDir) {
+    return join(artifactsDir, "steps", "pending-advisories.json");
+}
+/**
+ * Read the persisted carry. Lenient by design: an absent or unreadable file is
+ * an empty carry, because this is a PROMPT convenience over a ledger that
+ * remains authoritative — a bookkeeping file must never be able to fail the
+ * call it decorates. Shape-checked rather than schema-parsed for the same
+ * reason: unrecognized entries are dropped, never thrown on.
+ */
+async function readPendingAdvisories(artifactsDir) {
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(pendingAdvisoriesPath(artifactsDir), "utf8"));
+    }
+    catch {
+        return emptyFoldAdvisories();
+    }
+    if (!isRecord(raw))
+        return emptyFoldAdvisories();
+    const take = (value) => (Array.isArray(value) ? value : []);
+    return {
+        ingestIssues: take(raw.ingestIssues),
+        validationWarnings: take(raw.validationWarnings),
+    };
+}
+/**
+ * Persist the carry, or DELETE it when empty. Deleting rather than writing an
+ * empty object is what keeps presence a signal: a later fold reads "nothing
+ * pending" from absence, and no reader has to distinguish `[]` from "not yet
+ * written".
+ */
+async function writePendingAdvisories(artifactsDir, advisories) {
+    const path = pendingAdvisoriesPath(artifactsDir);
+    if (advisories.ingestIssues.length === 0 &&
+        advisories.validationWarnings.length === 0) {
+        try {
+            await unlink(path);
+        }
+        catch (error) {
+            if (!isFileMissingError(error))
+                throw error;
+        }
+        return;
+    }
+    await writeJsonFile(path, advisories);
+}
 /**
  * Append one fold iteration's advisories to the pending carry. Dedupe by
  * identity signature keeps an issue the SAME ingest re-classifies on a later
@@ -1540,16 +1637,20 @@ function mergeFoldAdvisoriesInto(carried, fresh) {
         carried.validationWarnings.push(warning);
     }
 }
-/** Drain the carry: what the NEXT emission must state, now consumed. */
-function takeFoldAdvisories(ref) {
+/**
+ * Drain the carry: what the NEXT emission must state, now consumed. Clears the
+ * in-memory ref AND the persisted copy TOGETHER, so the once-only property holds
+ * across a call boundary exactly as it does within one call — a ref cleared
+ * without the file would re-state on the next call, and a file left behind after
+ * a render would do the same.
+ */
+async function takeFoldAdvisories(artifactsDir, ref) {
     const taken = {
         ingestIssues: ref.value.ingestIssues,
         validationWarnings: ref.value.validationWarnings,
     };
-    ref.value = {
-        ingestIssues: [...EMPTY_FOLD_ADVISORIES.ingestIssues],
-        validationWarnings: [...EMPTY_FOLD_ADVISORIES.validationWarnings],
-    };
+    ref.value = emptyFoldAdvisories();
+    await writePendingAdvisories(artifactsDir, emptyFoldAdvisories());
     return taken;
 }
 /** Content identity of one advisory, across both channels. */
@@ -1738,12 +1839,24 @@ export function buildAuditObligations() {
             }
             return { kind: "transition", state: branch.bundle };
         },
-        // Charter delta-mining (Phase C.2): consume the delta lane submission,
-        // settle deterministically when the register is not deltas_pending, or
-        // emit the independent delta-miner's host step.
-        charter_delta_current: async (bundle, ctx) => {
+        // Charter comparison (steps 2–3): consume the comparison submission, settle
+        // deterministically when the register is not comparison_pending, or emit the
+        // comparison reader's host step.
+        charter_comparison_current: async (bundle, ctx) => {
             const state = deriveAuditState(bundle, { emitStaleness: false });
-            const branch = await handleCharterDeltaBranch(ctx.params, bundle, state, ctx.tx);
+            const branch = await handleCharterComparisonBranch(ctx.params, bundle, state, ctx.tx);
+            if (branch.action === "return") {
+                return { kind: "emit", step: branch.result, state: bundle };
+            }
+            if (branch.action === "run_omit") {
+                return runDeterministicExecutor(bundle, ctx);
+            }
+            return { kind: "transition", state: branch.bundle };
+        },
+        // Charter fidelity (step 4): the separate lane's verdicts, or the settle.
+        charter_fidelity_current: async (bundle, ctx) => {
+            const state = deriveAuditState(bundle, { emitStaleness: false });
+            const branch = await handleCharterFidelityBranch(ctx.params, bundle, state, ctx.tx);
             if (branch.action === "return") {
                 return { kind: "emit", step: branch.result, state: bundle };
             }
@@ -1878,7 +1991,16 @@ async function runHostDelegationObligation(bundle, ctx) {
         }
         catch (error) {
             // No handoff exists on the first visit, or prepare was interrupted before
-            // all binding artifacts landed. Re-preparing below restores it exactly.
+            // all binding artifacts landed. Re-preparing below restores it exactly:
+            // the prepare writes the workload, result map and binding set together,
+            // so a partial trio is overwritten whole.
+            //
+            // A STALE binding set is deliberately NOT in this class and must not be
+            // added to it: the ingest already classifies it and returns an issue
+            // WITHOUT throwing (see `StaleAuditHostTaskBindingsError`), precisely so
+            // the fold reaches the re-prepare below instead of aborting here. An
+            // error that arrives at this line was not classified by the ingest, and
+            // swallowing it would turn an unreadable handoff into a silent one.
             if (!isFileMissingError(error))
                 throw error;
         }
@@ -1913,15 +2035,20 @@ async function runHostDelegationObligation(bundle, ctx) {
                 issues: ingestIssues,
                 validationWarnings,
             });
+            // PERSIST with the merge, not at the emission: the transition below can
+            // end the call (the budget cap), and an emission-only write would lose
+            // exactly the advisory a call-ending transition produced — the case this
+            // carry exists to cover.
+            await writePendingAdvisories(ctx.params.artifactsDir, ctx.foldAdvisoriesRef.value);
             return { kind: "transition", state: ingested.updated_bundle };
         }
     }
     // The UNLOCKED variant: the fold already holds the artifact-tree lock, and
-    // `withFileLock` is non-reentrant — the locking `ensureSemanticReviewRun`
-    // here would be a deterministic FileLockTimeoutError on the audit loop's
-    // most common exit path. Its blocked core state rides the emit's `state`
-    // below, so the fold's single commit persists it (the pause's own persist
-    // was the split's other half).
+    // `withFileLock` is non-reentrant — taking the artifact-tree hold here would
+    // be a deterministic FileLockTimeoutError on the audit loop's most common
+    // exit path. Its blocked core state rides the emit's `state` below, so the
+    // fold's single commit persists it (the pause's own persist was the split's
+    // other half).
     const review = await ensureSemanticReviewRunUnlocked({
         root: ctx.params.root,
         artifactsDir: ctx.params.artifactsDir,
@@ -1931,37 +2058,89 @@ async function runHostDelegationObligation(bundle, ctx) {
         selfCliPath: ctx.params.selfCliPath,
         timeoutMs: ctx.params.timeoutMs,
     });
-    // Consume whatever earlier fold iterations of THIS call carried: each
-    // advisory is stated on exactly one emitted step (never duplicated on later
-    // folds), and an emit with nothing carried renders only what THIS ingest saw.
-    const carried = takeFoldAdvisories(ctx.foldAdvisoriesRef);
-    const emitted = {
-        kind: "semantic_review",
-        selectedExecutor: decision.selected_executor,
-        ...review,
-        ...(ingestIssues.length > 0 ? { ingestIssues } : {}),
-        ...(validationWarnings.length > 0 ? { validationWarnings } : {}),
-    };
+    // What THIS ingest saw. Deliberately NOT drained here: the carried advisories
+    // are taken at the fold's single emission boundary (`runDeterministicForNextStep`),
+    // which every emitted step kind passes through — draining at this obligation
+    // would state them only for a semantic-review emission and silently drop them
+    // the moment the run's next step happened to be a different kind
+    // (design_review_conceptual, charter_*, synthesis_narrative…).
     return {
         kind: "emit",
-        step: carried.ingestIssues.length > 0 || carried.validationWarnings.length > 0
-            ? {
-                ...emitted,
-                ingestIssues: [
-                    ...ingestIssues,
-                    ...carried.ingestIssues,
-                ],
-                validationWarnings: [
-                    ...validationWarnings,
-                    ...carried.validationWarnings,
-                ],
-            }
-            : emitted,
+        step: {
+            kind: "semantic_review",
+            selectedExecutor: decision.selected_executor,
+            ...review,
+            ...(ingestIssues.length > 0 ? { ingestIssues } : {}),
+            ...(validationWarnings.length > 0 ? { validationWarnings } : {}),
+        },
         // The pause's blocked core state — the fold's single commit persists it
         // (the locking variant's own write was the other half of the split).
         state: review.bundle,
     };
 }
+/**
+ * State the fold's carried advisories on the step about to be emitted, and
+ * DRAIN them.
+ *
+ * THE single emission-boundary drain. It lives here, not at any one obligation,
+ * because the property is "stated on exactly one emitted step, whichever call
+ * and whichever step kind emits it": a carry produced by a call-ending
+ * transition must survive to a later fold, and that fold's step may be ANY
+ * kind. Hanging the drain off the semantic-review obligation made it correct
+ * only for as long as the next step happened to be a semantic review.
+ *
+ * Advisories are only ever RENDERED by the semantic-review step today (the
+ * other kinds carry no advisory channel), so a carry drained onto one of them
+ * still reaches the operator — as a stated line in this step's prompt — rather
+ * than being lost. A step with nothing carried is returned untouched.
+ */
+async function withFoldAdvisories(step, ctx) {
+    const carried = await takeFoldAdvisories(ctx.params.artifactsDir, ctx.foldAdvisoriesRef);
+    if (carried.ingestIssues.length === 0 &&
+        carried.validationWarnings.length === 0) {
+        return step;
+    }
+    if (step.kind !== "semantic_review") {
+        return {
+            ...step,
+            advisoryNotice: renderCarriedAdvisoryLines(carried),
+        };
+    }
+    return {
+        ...step,
+        ingestIssues: [...(step.ingestIssues ?? []), ...carried.ingestIssues],
+        validationWarnings: [
+            ...(step.validationWarnings ?? []),
+            ...carried.validationWarnings,
+        ],
+    };
+}
+/**
+ * The advisory lines a step that carries no advisory CHANNEL still states. A
+ * carried advisory is never dropped on the floor because the run happened to
+ * move on to a different step kind — it is rendered as text, in the same
+ * wording the semantic-review step's own sections use.
+ */
+function renderCarriedAdvisoryLines(carried) {
+    const lines = [];
+    // The SAME missing/rejected split the semantic-review step renders, because a
+    // carried advisory and the step's own issues are the same fact reaching the
+    // operator through two different channels; they must not disagree on shape.
+    const describe = (issue) => `${issue.work_item_id ? `\`${issue.work_item_id}\` (${issue.code}): ` : `${issue.code}: `}` +
+        `${issue.message}${issue.result_path ? ` (\`${issue.result_path}\`)` : ""}`;
+    const missing = carried.ingestIssues.filter(isMissingObservation);
+    const refused = carried.ingestIssues.filter((issue) => !isMissingObservation(issue));
+    if (missing.length > 0) {
+        lines.push("## Results not yet written", "", ...missing.map((issue) => `- ${describe(issue)}`), "");
+    }
+    if (refused.length > 0) {
+        lines.push("## Result status requiring attention", "", ...refused.map((issue) => `- ${describe(issue)}`), "");
+    }
+    if (carried.validationWarnings.length > 0) {
+        lines.push("## Advisory notes on accepted results", "", ...carried.validationWarnings.map((warning) => `- \`${warning.work_item_id}\` was ACCEPTED; advisory: ${warning.message}`), "");
+    }
+    return lines;
+}
 /** Emit the no-executor blocked step (the hand loop's `!selected_executor` arm). */
 async function emitNoExecutorBlocked(bundle, ctx, decision) {
     const state = decision.state;
@@ -1987,17 +2166,46 @@ function trackFoldBundle(obligations) {
     return obligations.map((obligation) => ({
         ...obligation,
         execute: async (bundle, ctx) => {
-            const outcome = await obligation.execute(bundle, ctx);
-            if (outcome.kind === "transition") {
-                ctx.currentBundleRef.value = outcome.state;
+            // Liveness for the LONG deterministic drain (the >2min stale-artifact
+            // re-extraction next-step that blew a caller timeout with no output). The
+            // per-execution label is set HERE because this is the one place every fold
+            // execution passes through, whatever it dispatches; `runSingleAdvanceStep`
+            // then refines it to the selected obligation once the engine has picked
+            // one, so a beat is never unattributed. `advanceAudit`'s heartbeat already
+            // covers the un-forced `advanceAudit` path; the fold drives the shared
+            // engine directly and so owns its own.
+            ctx.heartbeat?.setLabel(obligation.id);
+            const startedAt = Date.now();
+            try {
+                const outcome = await obligation.execute(bundle, ctx);
+                if (outcome.kind === "transition") {
+                    ctx.currentBundleRef.value = outcome.state;
+                }
+                else if (outcome.state !== undefined) {
+                    ctx.currentBundleRef.value = outcome.state;
+                }
+                return outcome;
             }
-            else if (outcome.state !== undefined) {
-                ctx.currentBundleRef.value = outcome.state;
+            finally {
+                foldHeartbeatRecord(obligation.id, Date.now() - startedAt);
             }
-            return outcome;
         },
     }));
 }
+/**
+ * One JSONL line naming an obligation the fold finished executing and how long
+ * it took. Written to stderr beside the interval beat (same channel and shape as
+ * `progress_heartbeat`, so one reader consumes both) and to the fold's run log
+ * via its own logger when one is attached.
+ */
+function foldHeartbeatRecord(obligation, durationMs) {
+    process.stderr.write(JSON.stringify({
+        kind: "progress_heartbeat",
+        phase: obligation,
+        duration_ms: durationMs,
+        ts: new Date().toISOString(),
+    }) + "\n");
+}
 // ── Coordinator ───────────────────────────────────────────────────────────────
 /**
  * Drive the deterministic fold for one `next-step` call.
@@ -2019,6 +2227,24 @@ function trackFoldBundle(obligations) {
  * terminal step (present_report when a report is rendered, else blocked).
  */
 export async function runDeterministicForNextStep(params) {
+    // The heartbeat wraps the WHOLE call, throw path included: a drain that dies
+    // halfway is exactly when a caller most needs to know how far it got, and the
+    // interval beat has no other owner on this path (the fold drives the shared
+    // engine directly rather than through `advanceAudit`).
+    const heartbeat = startAdvanceHeartbeat();
+    try {
+        return await runDeterministicFold(params, heartbeat);
+    }
+    finally {
+        heartbeat.stop();
+    }
+}
+async function runDeterministicFold(params, heartbeat) {
+    // THE fold's one git-index probe cache (`ScopeIndexMemo`). It is created here
+    // and held on `params` — the object every dispatch path already shares, the
+    // gate handlers included — so one `next-step` call spawns `git` once rather
+    // than once per obligation execution.
+    params.scopeIndexMemo = {};
     const analyzersRef = {
         value: params.analyzers,
     };
@@ -2058,12 +2284,8 @@ export async function runDeterministicForNextStep(params) {
         params,
         analyzersRef,
         lastSummaryRef: { value: "" },
-        foldAdvisoriesRef: {
-            value: {
-                ingestIssues: [...EMPTY_FOLD_ADVISORIES.ingestIssues],
-                validationWarnings: [...EMPTY_FOLD_ADVISORIES.validationWarnings],
-            },
-        },
+        heartbeat,
+        foldAdvisoriesRef: { value: emptyFoldAdvisories() },
         dispatchOrdinalRef: { value: 0 },
         dispatchedSignatures: new Set(),
         seenStateSignatures: new Set(),
@@ -2091,6 +2313,14 @@ export async function runDeterministicForNextStep(params) {
         const holdStartMs = Date.now();
         let chargedExecutions;
         await recoverStagedSubmissions(params.artifactsDir);
+        // The PERSISTED carry, read back under the hold. A transition that ENDED
+        // an earlier call left its advisories on disk for the next emission to
+        // state, and that emission may be this call's — the ctx ref starts empty
+        // per call, so without this read the durable half would be write-only and
+        // the advisories would still die at the call boundary. Seeding the ref
+        // (rather than merging at the emit site) keeps ONE drain point, so the
+        // once-only property is the same one the in-call path already relies on.
+        ctx.foldAdvisoriesRef.value = await readPendingAdvisories(params.artifactsDir);
         const startBundle = await loadArtifactBundle(params.artifactsDir);
         ctx.currentBundleRef.value = startBundle;
         try {
@@ -2141,14 +2371,21 @@ export async function runDeterministicForNextStep(params) {
     const finalStale = computeStaleArtifacts(outcome.state, { emit: false });
     emitStalenessRecord(finalStale, isMetadataMigrationStaleness(outcome.state)
         ? "metadata_schema_version_migration"
-        : undefined);
+        : undefined, outcome.state);
+    // THE emission boundary — the one place every emitted step kind passes
+    // through. Draining the carry here, rather than at the semantic-review
+    // obligation that produces most of it, is what makes "stated on exactly one
+    // emitted step, WHICHEVER step that is" true for every kind. A terminal
+    // intent is deliberately excluded: it is not a step, and the terminal
+    // conversion below promotes and deletes the artifacts dir — the carry has
+    // nowhere left to be stated, and the run is over.
+    if (outcome.step && outcome.step.kind !== "terminal_intent") {
+        return await withFoldAdvisories(outcome.step, ctx);
+    }
     if (outcome.step) {
-        if (outcome.step.kind === "terminal_intent") {
-            // Guard terminals convert POST-commit, POST-hold: buildTerminalStep can
-            // promote, and promotion deletes artifactsDir.
-            return await buildTerminalStep(params, outcome.step.bundle, outcome.step.state, outcome.step.reason);
-        }
-        return outcome.step;
+        // Guard terminals convert POST-commit, POST-hold: buildTerminalStep can
+        // promote, and promotion deletes artifactsDir.
+        return await buildTerminalStep(params, outcome.step.bundle, outcome.step.state, outcome.step.reason);
     }
     if (outcome.stopped === "budget") {
         // The pacing cap (MAX_DRAIN_STEPS charged executions), spent gracefully: