@kontourai/flow-agents 3.3.0 → 3.4.1

package/build/src/cli/workflow-sidecar.js

@@ -2,13 +2,14 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 // ADR 0016 Abstraction A: shared FlowDefinition resolver (P-a)
-import { resolveActiveFlowStep, resolveFlowFilePath, resolvePhaseMap, resolveRouteBackPolicy } from "../lib/flow-resolver.js";
+import { resolveActiveFlowStep, resolveAllFlowGateExpects, resolveFlowFilePath, resolvePhaseMap, resolveRouteBackPolicy } from "../lib/flow-resolver.js";
 import { defaultArtifactRootForRead, flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
+import { syncBuilderFlowSessionIfPresent } from "../builder-flow-runtime.js";
 // #291 Wave 1 Task 1.1 exports: ensure-session's ownership guard reuses the EXACT same
 // assignment ⋈ liveness join / claim / supersede logic #290 already ships for the
 // `assignment-provider` CLI, rather than reimplementing a second, parallel join (static ESM
@@ -54,6 +55,32 @@ function workItemSlug(ref) {
     const [owner, repo] = parts;
     return slugify(`${owner}-${repo}-${id}`, "work-item");
 }
+function sessionWorkItem(p, slug, dir) {
+    const providerRef = opt(p, "work-item");
+    if (providerRef) {
+        return { ref: providerRef };
+    }
+    const existingState = loadJson(path.join(dir, "state.json"));
+    if (Array.isArray(existingState.work_item_refs) && typeof existingState.work_item_refs[0] === "string") {
+        return { ref: existingState.work_item_refs[0] };
+    }
+    const title = opt(p, "title", slug).trim() || slug;
+    const body = opt(p, "summary").trim();
+    return {
+        ref: `local:${slug}`,
+        localRecord: {
+            id: slug,
+            title,
+            ...(body ? { body } : {}),
+            status: "ready",
+            source_provider: {
+                kind: "local",
+                path: "work-item.json",
+            },
+            artifact_refs: ["state.json", "handoff.json"],
+        },
+    };
+}
 /** Pure, lock-free, side-effect-free CLI wrapper around workItemSlug() — the single source of
  * truth for the deterministic subjectId/session-directory-name slug. Named resolveSlugCmd (not
  * resolveSlug) to avoid colliding with any future export named resolveSlug. */
@@ -471,6 +498,68 @@ function critiqueToEventStatus(verdict, findings) {
         return "assumed";
     return null; // not_verified or unknown → no event → Surface returns "unknown"
 }
+/**
+ * Fold a raw command-log (command-log.jsonl entries) into a per-command classification,
+ * keyed by normalized command text (whitespace-collapsed, trimmed). Pure and side-effect-free
+ * so it is directly unit-testable (#470 iteration 2, finding #2 — HIGH: the prior inline reducer
+ * collapsed every non-"fail" `observedResult` — including "ambiguous" — to "pass", feeding a
+ * verified event + `passing:true` and reintroducing the #470 false-pass through the trust-bundle
+ * reconciliation path).
+ *
+ * Three-way classification, keyed on `observedResult` (never re-derived from `exitCode` alone,
+ * which would miscoerce the #362 grep/diff absence carve-out `ambiguous,exitCode:1` entry to
+ * `fail`):
+ *   - "fail"      when `observedResult==="fail"`, or (legacy, no observedResult) a nonzero
+ *                 integer `exitCode`.
+ *   - "ambiguous" when `observedResult==="ambiguous"`, or (legacy) `exitCode` is `null` with no
+ *                 fail signal.
+ *   - "pass"      when `observedResult==="pass"`, or (legacy) `exitCode===0`.
+ *
+ * Precedence across repeated entries for the same command: fail > pass > ambiguous. A genuine
+ * exit-0 pass is positive evidence and confirms; ambiguous holds only when there is neither a
+ * fail nor a positive pass, since a "pass" always requires positive evidence.
+ *
+ * The caller (buildTrustBundle) maps "ambiguous" onto the existing canonical non-confirming
+ * status `not_verified` — consume-never-fork, mirroring record-check's identical mapping — so
+ * `checkStatusToEventStatus("not_verified")` returns null (no verification event emitted) and the
+ * evidence item is stamped `passing:false`. See Decision/finding #2 in the iteration-2 plan.
+ */
+export function reduceCaptureLogByCommand(commandLog) {
+    const captureByCommand = new Map();
+    for (const entry of Array.isArray(commandLog) ? commandLog : []) {
+        if (!entry || typeof entry.command !== "string")
+            continue;
+        const key = entry.command.replace(/\s+/g, " ").trim();
+        if (!key)
+            continue;
+        const exitCode = Number.isInteger(entry.exitCode) ? entry.exitCode : null;
+        let result;
+        if (entry.observedResult === "fail" || (entry.observedResult === undefined && exitCode !== null && exitCode !== 0)) {
+            result = "fail";
+        }
+        else if (entry.observedResult === "pass" || (entry.observedResult === undefined && exitCode === 0)) {
+            result = "pass";
+        }
+        else {
+            // Covers observedResult==="ambiguous" AND the legacy no-observedResult, exitCode:null case.
+            result = "ambiguous";
+        }
+        const prev = captureByCommand.get(key);
+        let merged = result;
+        if (prev) {
+            // fail > pass > ambiguous precedence.
+            if (prev.observedResult === "fail" || result === "fail")
+                merged = "fail";
+            else if (prev.observedResult === "pass" || result === "pass")
+                merged = "pass";
+            else
+                merged = "ambiguous";
+        }
+        const mergedExitCode = exitCode !== null ? exitCode : (prev ? prev.exitCode : null);
+        captureByCommand.set(key, { observedResult: merged, exitCode: mergedExitCode });
+    }
+    return captureByCommand;
+}
 /**
  * Build a Hachure trust.bundle from raw check/criterion/critique inputs.
  * trust.bundle is the PRIMARY artifact (ADR 0010 Phase 4a producer inversion).
@@ -498,6 +587,114 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
     // writeTrustBundle below) threads through to resolveActiveFlowStep's per-actor-first,
     // legacy-fallback current.json read; omitted, this is IDENTICAL to pre-#291 behavior.
     const activeStep = flowAgentsDir ? resolveActiveFlowStep(flowAgentsDir, actorKey) : null;
+    // #270 CRITICAL/HIGH fix: resolve the session's active_flow_id independent of whether the
+    // CURRENTLY-active step resolves — a stamped gate claim names the STEP IT WAS ORIGINALLY
+    // RECORDED AT (frozen in metadata.gate_claim.step_id), which is routinely a DIFFERENT step than
+    // whatever is active now. Validating the stamp against only the currently-active step's
+    // expects[] would reject every honest round-trip the moment the session advances past the step
+    // the gate claim was recorded at — the validation must be against the FULL flow definition
+    // (every step's gate expects[], via resolveAllFlowGateExpects), not just the active one.
+    const sessionFlowId = (() => {
+        if (!flowAgentsDir)
+            return null;
+        try {
+            const pointer = loadCurrentPointerHelper().readCurrentPointer(flowAgentsDir, actorKey);
+            const payload = pointer.payload;
+            const fid = payload && typeof payload["active_flow_id"] === "string" ? payload["active_flow_id"] : null;
+            return fid && fid.length > 0 ? fid : null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    const workflowSubjectRef = (() => {
+        if (!flowAgentsDir)
+            return null;
+        try {
+            const state = loadJson(path.join(flowAgentsDir, slug, "state.json"));
+            const refs = Array.isArray(state.work_item_refs) ? state.work_item_refs : [];
+            return refs.length === 1 && typeof refs[0] === "string" && refs[0].length > 0 ? refs[0] : null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    // repoRoot resolution mirrors resolveActiveFlowStep's own internal findRepoRoot(path.dirname(
+    // flowAgentsDir)) call exactly (flow-resolver.ts) — findRepoRootFromDir is this file's
+    // fallback-to-cwd equivalent of that unexported helper. NOTE (#270 MEDIUM fix, iteration 3):
+    // findRepoRootFromDir ALWAYS returns a truthy string (it falls back to process.cwd() — see
+    // findRepoRootFromDir's own doc comment above) whenever flowAgentsDir is set, so `flowRepoRoot`
+    // is only ever null when `!flowAgentsDir`. It can therefore never by itself signal a FlowDefinition
+    // load failure; that signal now comes from resolveAllFlowGateExpects's own null return (below).
+    const flowRepoRoot = flowAgentsDir ? findRepoRootFromDir(path.dirname(flowAgentsDir)) : null;
+    // Built lazily (only when at least one check actually carries a metadata.gate_claim stamp or
+    // gate-claim shape to validate) and cached across every check in this call's loop — the
+    // FlowDefinition file is read once per buildTrustBundle call, not once per claim.
+    //
+    // #270 MEDIUM fix (iteration 3): tri-state cache — `undefined` (not yet built), `null` (the
+    // FlowDefinition could not be loaded/parsed — see resolveAllFlowGateExpects's doc comment),
+    // or an array (loaded; possibly genuinely empty). This lets assertStampedGateClaimValid tell
+    // "cannot load the flow definition" apart from "loaded fine, tuple just doesn't match" — the
+    // previous code collapsed both into `[]`, which always failed the `.some()` match below and
+    // was misreported as "forged or corrupt" even when the real cause was an unloadable
+    // FlowDefinition (e.g. a bogus/renamed active_flow_id, or a `kits/` path that no longer
+    // resolves) — a `!flowRepoRoot` check can never catch this because flowRepoRoot is always
+    // truthy here (see the note above), so that check was dead code against this failure mode.
+    let _allGateExpectsCache = undefined;
+    const allGateExpectsForSession = () => {
+        if (_allGateExpectsCache !== undefined)
+            return _allGateExpectsCache;
+        _allGateExpectsCache = (sessionFlowId && flowRepoRoot) ? resolveAllFlowGateExpects(sessionFlowId, flowRepoRoot) : null;
+        return _allGateExpectsCache;
+    };
+    /**
+     * Validate a RESTORED metadata.gate_claim stamp's (expectation_id, claim_type, subject_type,
+     * step_id) tuple against the session's FULL flow definition (every step's gate expects[], not
+     * just the currently-active step). This is the honest round-trip check: a claim recorded by
+     * record-gate-claim/buildTrustBundle can only ever carry a tuple that matches some real
+     * expects[] entry, because that is the only place the stamp is ever written (see the
+     * declaredMetadata.gate_claim assembly below). A tuple that does NOT match a real expectation is
+     * either FORGED (a hand-edited/attacker-supplied metadata.gate_claim) or CORRUPT — never a
+     * legitimate state this code can produce — so it dies loudly naming the claim id and the
+     * invalid stamp. It must NEVER fall through to matchExpectsEntry: that silent fall-through
+     * IS the re-typing bug this fix closes (a forged/corrupt stamp would otherwise get a fresh,
+     * heuristic-derived typing instead of being rejected).
+     *
+     * Accepted residual (#270, documented not fixed — iteration 3): this check validates
+     * STRUCTURAL conformance of the stamp's tuple against the flow definition's declared
+     * expects[] shape — it does not (and cannot, at this layer) verify WHO produced the stamp. A
+     * stamp that reuses a REAL (expectation_id, claim_type, subject_type, step_id) tuple copied
+     * from a legitimately-earned claim will PASS this validation, because it is, structurally,
+     * indistinguishable from an honest one. This is an accepted floor equal to the pre-existing
+     * trust boundary: any local process with filesystem access to this session already has an
+     * equivalent capability by invoking record-gate-claim directly. This validator closes the
+     * STRICTLY WORSE case — a forged tuple that does NOT correspond to any real expects[] entry,
+     * or a stamp silently re-typed via matchExpectsEntry's heuristic fallback — not general
+     * authorship/provenance binding. Provenance binding (e.g. cryptographically tying a stamp to
+     * the actor/process that recorded it) is future work; see issue #270's review thread.
+     *
+     * #270 MEDIUM fix (iteration 3): a DIFFERENT failure class — the FlowDefinition genuinely
+     * cannot be loaded/parsed (missing kits/ file, unreadable, invalid JSON, or a since-renamed/
+     * bogus active_flow_id) — must NEVER be reported as "forged or corrupt"; that message asserts
+     * the stamp itself is untrustworthy, which is not what happened here. This case dies with its
+     * own dedicated, distinctly-worded message instead.
+     */
+    function assertStampedGateClaimValid(claimId, stamp) {
+        if (!sessionFlowId) {
+            die(`buildTrustBundle: claim '${claimId}' carries a metadata.gate_claim stamp (expectation_id='${stamp.expectationId}') but no flow definition is resolvable for this session (no active_flow_id) — a stamped gate claim cannot be validated without the flow definition it was recorded against. This is either a legacy non-flow session or a missing --flow-id; re-record the gate claim inside a session with a resolvable --flow-id.`);
+        }
+        const allExpects = allGateExpectsForSession();
+        if (allExpects === null) {
+            die(`buildTrustBundle: claim '${claimId}' carries a metadata.gate_claim stamp (expectation_id='${stamp.expectationId}') naming flow '${sessionFlowId}', but FlowDefinition '${sessionFlowId}' cannot be loaded — cannot validate the gate-claim stamp. This is a load/parse failure (missing FlowDefinition file, unreadable, invalid JSON, or a renamed/bogus active_flow_id) — never treat this as a forged stamp. Restore or correct the '${sessionFlowId}' FlowDefinition (or the session's active_flow_id) before this claim can be validated.`);
+        }
+        const match = allExpects.some((entry) => entry.gateExpects.some((exp) => exp.id === stamp.expectationId
+            && exp.bundle_claim.claimType === stamp.claimType
+            && exp.bundle_claim.subjectType === stamp.subjectType
+            && (stamp.stepId === null || stamp.stepId === entry.stepId)));
+        if (!match) {
+            die(`buildTrustBundle: claim '${claimId}' carries a metadata.gate_claim stamp that does not match any expects[] entry declared in the '${sessionFlowId}' flow definition (expectation_id='${stamp.expectationId}', claim_type='${stamp.claimType}', subject_type='${stamp.subjectType}', step_id='${stamp.stepId ?? "<none>"}'). This stamp is forged or corrupt — it can never legitimately fail validation, since it is only ever written by this same code against a real expects[] entry. Refusing to trust it; never silently re-typing via matchExpectsEntry.`);
+        }
+    }
     const claims = [];
     const evidenceItems = [];
     const events = [];
@@ -528,19 +725,15 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         }
         return p;
     };
-    // Index the deterministic capture log by normalized command (a single FAIL wins),
-    // so a claimed-pass check whose command actually FAILED becomes authoritative here.
-    const captureByCommand = new Map();
-    for (const entry of Array.isArray(commandLog) ? commandLog : []) {
-        if (!entry || typeof entry.command !== "string")
-            continue;
-        const key = entry.command.replace(/\s+/g, " ").trim();
-        if (!key)
-            continue;
-        const failed = entry.observedResult === "fail" || (Number.isInteger(entry.exitCode) && entry.exitCode !== 0);
-        const prev = captureByCommand.get(key);
-        captureByCommand.set(key, { observedResult: failed || (prev && prev.observedResult === "fail") ? "fail" : "pass", exitCode: Number.isInteger(entry.exitCode) ? entry.exitCode : (prev ? prev.exitCode : null) });
-    }
+    // Index the deterministic capture log by normalized command (fail > pass > ambiguous
+    // precedence wins across repeated entries for the same command), so a claimed-pass check
+    // whose command actually FAILED (or never produced usable signal) becomes authoritative here.
+    // Extracted to reduceCaptureLogByCommand (below) for direct unit testing (#470 iteration 2,
+    // finding #2): the three-way classification is keyed on `observedResult`, NEVER re-derived
+    // from `exitCode` alone, so an `ambiguous,exitCode:1` entry (the #362 grep/diff absence
+    // carve-out) is never miscoerced to `fail` here, and a no-signal `ambiguous` (exitCode:null)
+    // is never coerced to `pass`.
+    const captureByCommand = reduceCaptureLogByCommand(commandLog);
     // ─── P-b dual-emit helper ──────────────────────────────────────────────────
     // Semantic matching table (ADR 0016 Abstraction A P-b):
     //   check (non-policy kind) → expects[] entry where claimType does NOT contain
@@ -658,18 +851,75 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
             ? { evidenceType: "attestation", method: "attestation", reconcilable: false }
             : classifyEvidence(check.kind, cmd.length > 0);
         const policy = ensurePolicy(legacyClaimType, "high", [evClass.evidenceType]);
-        const effectiveStatus = captured ? captured.observedResult : String(check.status ?? "");
+        // #470 iteration 2, finding #2: an "ambiguous" capture (no positive pass/fail signal —
+        // e.g. the codex no-signal default, or the #362 grep/diff absence carve-out) is
+        // non-confirming and must never be surfaced as a claim value of "pass". Map it onto the
+        // EXISTING canonical non-confirming status "not_verified" (consume-never-fork; the same
+        // mapping record-check already applies at its `ambiguous` branch above) so
+        // checkStatusToEventStatus("not_verified") returns null — no verification event, and the
+        // evidence item below is stamped passing:false. `isError` stays fail-only (ambiguous is
+        // not an error).
+        const effectiveStatus = captured ? (captured.observedResult === "ambiguous" ? "not_verified" : captured.observedResult) : String(check.status ?? "");
         const evStatus = waiver ? "assumed" : checkStatusToEventStatus(effectiveStatus);
         // Promotion claim marker (issue #312): a `promote` check carries a session-local
         // _promotion object that must survive onto claim.metadata.promotion so the archive gate
         // (workflow-artifact-cleanup-audit) and validators can detect the promotion claim without a
         // new manifest entry. It rides alongside any waiver in a single merged metadata object.
         const promotionMeta = (check._promotion && typeof check._promotion === "object") ? check._promotion : null;
+        // #298: artifact_refs/standard_refs are validated on input by normalizeCheck but were
+        // previously never persisted onto the claim — silently lost on the very first write, not
+        // just on round-trip. Stamp them onto claim.metadata (additive, mirrors waiver/promotion
+        // above) so checksFromBundle can restore them for every subsequent writer.
+        const artifactRefsMeta = Array.isArray(check.artifact_refs) && check.artifact_refs.length > 0 ? check.artifact_refs : null;
+        const standardRefsMeta = Array.isArray(check.standard_refs) && check.standard_refs.length > 0 ? check.standard_refs : null;
+        // #270/#380 MEDIUM fix: record-check's captured-output sha256 digest (see recordCheck's
+        // outputSha256 computation) — hash ONLY, never the raw output text, so this is secret-safe by
+        // construction even though trust.bundle is often committed/shared. Stamped onto
+        // claim.metadata (additive, mirrors artifact_refs/standard_refs above) so checksFromBundle can
+        // restore it for every subsequent writer, and so it survives any later rebuild.
+        // NOTE (#270 LOW fix, iteration 3): this digest is over the CLAMPED capture (recordCheck's
+        // clampOutput, first RECORD_CHECK_MAX_OUTPUT / 64 KiB of combined stdout+stderr), not the full
+        // raw command output — a command producing >64KiB of output has its digest computed only over
+        // the retained prefix, so two runs whose outputs diverge only past the 64KiB boundary hash
+        // identically.
+        const outputDigestMeta = typeof check._output_sha256 === "string" && check._output_sha256.length > 0
+            ? { algorithm: "sha256", hex: check._output_sha256 }
+            : null;
+        // #270(a)/(c): a gate claim's declared claimType/subjectType, once resolved (either freshly
+        // via matchExpectsEntry below, or restored from a prior write's metadata.gate_claim stamp by
+        // checksFromBundle), is stamped here so it is frozen at record time — a later bundle rebuild
+        // (record-evidence/record-critique/record-learning) must never re-derive it from whatever
+        // step happens to be active THEN. See the matchExpectsEntry call site immediately below.
+        const gateClaimExpectationId = typeof check._gate_claim_expectation_id === "string" ? check._gate_claim_expectation_id : null;
+        const gateClaimDeclaredType = typeof check._gate_claim_declared_type === "string" ? check._gate_claim_declared_type : null;
+        const gateClaimDeclaredSubject = typeof check._gate_claim_declared_subject === "string" ? check._gate_claim_declared_subject : null;
+        const gateClaimDeclaredStepId = typeof check._gate_claim_declared_step_id === "string" ? check._gate_claim_declared_step_id : null;
+        const gateClaimRouteReason = typeof check._gate_claim_route_reason === "string" ? check._gate_claim_route_reason : null;
+        // #270 CRITICAL/HIGH fix: checksFromBundle stamps this when it read a claim that is
+        // gate-claim-SHAPED (origin:"check", check_kind:"external", kit-typed claimType) but carries
+        // NO metadata.gate_claim stamp — a claim this code could not have produced without also
+        // writing the stamp, so it predates cluster #270/#344. Die loudly with the same remedy
+        // pattern requireStampedClaim already uses elsewhere in this file, instead of silently
+        // falling through to matchExpectsEntry (which would re-derive a FRESH, possibly-wrong typing
+        // for what is actually a previously-recorded, now-untraceable gate claim — the re-typing bug).
+        const gateClaimShapeUnstampedClaimId = typeof check._gate_claim_shape_unstamped_claim_id === "string" ? check._gate_claim_shape_unstamped_claim_id : null;
+        if (gateClaimShapeUnstampedClaimId) {
+            die(`pre-cluster-270 gate claim '${gateClaimShapeUnstampedClaimId}' has no metadata.gate_claim stamp and cannot be re-typed authoritatively — re-record it (record-gate-claim) to regenerate.`);
+        }
         // #268: stamp a stable origin discriminator so checksFromBundle / critiquesFromBundle can
         // distinguish check vs critique vs acceptance claims across round-trips even under --flow-id,
         // where all three collapse onto the same declared claimType (and a command-less critique claim
         // would otherwise be re-absorbed as a test_output check → permanent [not-run] divergence).
-        const claimMetadata = { origin: "check", check_kind: String(check.kind ?? "external"), ...(waiver ? { waiver } : {}), ...(promotionMeta ? { promotion: promotionMeta } : {}) };
+        const claimMetadata = {
+            origin: "check",
+            check_kind: String(check.kind ?? "external"),
+            ...(activeStep && workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}),
+            ...(waiver ? { waiver } : {}),
+            ...(promotionMeta ? { promotion: promotionMeta } : {}),
+            ...(artifactRefsMeta ? { artifact_refs: artifactRefsMeta } : {}),
+            ...(standardRefsMeta ? { standard_refs: standardRefsMeta } : {}),
+            ...(outputDigestMeta ? { output_digest: outputDigestMeta } : {}),
+        };
         const claimEvents = [];
         if (evStatus) {
             const evt = { id: `evt:${claimId}`, claimId, status: evStatus, actor: "flow-agents/workflow-sidecar", method: "validation", evidenceIds: [evId], createdAt: ts, verifiedAt: ts };
@@ -692,11 +942,47 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         evidenceItems.push(evItem);
         // P-d: declared-only when active flow/step present (shadow retired); no-flow path unchanged.
         // When record-gate-claim sets _gate_claim_expectation_id, pass it for exact lookup (ADR 0016 P-d Increment 2).
-        const declared = matchExpectsEntry("check", check.kind, typeof check._gate_claim_expectation_id === "string" ? check._gate_claim_expectation_id : undefined);
+        // #270(c): a REBUILD of a previously-recorded gate claim (both the expectation id AND its
+        // originally-declared claimType/subjectType round-tripped via checksFromBundle's
+        // metadata.gate_claim restoration) uses the STAMPED typing directly instead of re-resolving
+        // matchExpectsEntry against whatever step is active NOW — that re-resolution is the exact
+        // defect (a claim recorded at step N silently re-typed as step N+1's claim on rebuild).
+        // matchExpectsEntry is still the resolver for the FIRST write (no prior stamp to trust).
+        //
+        // #270 CRITICAL/HIGH fix: a RESTORED stamp (gateClaimDeclaredType/gateClaimDeclaredSubject
+        // both present — meaning this is a REBUILD reading back a prior write's metadata.gate_claim,
+        // not a fresh record-gate-claim call, which only ever sets gateClaimExpectationId) must be
+        // VALIDATED against the session's full flow definition before being trusted — see
+        // assertStampedGateClaimValid above. A stamp that fails validation dies loudly; it must NEVER
+        // silently fall through to matchExpectsEntry (that fall-through was the exact #270 defect:
+        // ANY invalid/forged/corrupt stamp got silently re-typed by the heuristic matcher instead of
+        // being rejected). A FRESH write (only gateClaimExpectationId set, no declared type/subject
+        // yet) has no stamp to validate — matchExpectsEntry is still the correct, and only, resolver
+        // for that case, exactly as before.
+        if (gateClaimExpectationId && gateClaimDeclaredType && gateClaimDeclaredSubject) {
+            assertStampedGateClaimValid(claimId, {
+                expectationId: gateClaimExpectationId,
+                claimType: gateClaimDeclaredType,
+                subjectType: gateClaimDeclaredSubject,
+                stepId: gateClaimDeclaredStepId,
+            });
+        }
+        const declared = (gateClaimExpectationId && gateClaimDeclaredType && gateClaimDeclaredSubject)
+            ? { claimType: gateClaimDeclaredType, subjectType: gateClaimDeclaredSubject }
+            : matchExpectsEntry("check", check.kind, gateClaimExpectationId ?? undefined);
         if (declared) {
             // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
             const declaredPolicy = ensurePolicy(declared.claimType, "high", [evClass.evidenceType]);
-            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: effectiveStatus, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, ...(claimMetadata ? { metadata: claimMetadata } : {}) };
+            // Freeze the resolved typing (fresh or restored) into metadata.gate_claim so it survives
+            // any subsequent rebuild regardless of the then-active step (#270a/c).
+            // step_id prefers the ORIGINALLY-recorded step (restored from a prior stamp) on a
+            // rebuild that has no active flow step of its own; only a genuinely first write (no
+            // restored stamp) takes the currently-active step's id.
+            const declaredStepId = gateClaimDeclaredStepId ?? (activeStep ? activeStep.stepId : null);
+            const declaredMetadata = gateClaimExpectationId
+                ? { ...claimMetadata, gate_claim: { expectation_id: gateClaimExpectationId, claim_type: declared.claimType, subject_type: declared.subjectType, step_id: declaredStepId, ...(gateClaimRouteReason ? { route_reason: gateClaimRouteReason } : {}) } }
+                : claimMetadata;
+            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: effectiveStatus, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, ...(declaredMetadata ? { metadata: declaredMetadata } : {}) };
             const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [evItem], events: claimEvents, policies: [declaredPolicy] });
             claims.push({ ...declaredClaimObj, status: declaredStatus });
         }
@@ -728,7 +1014,7 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         if (declared) {
             // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
             const declaredPolicy = ensurePolicy(declared.claimType, "high", []);
-            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, metadata: { origin: "acceptance" } };
+            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, metadata: { origin: "acceptance", ...(workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}) } };
             const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [], events: claimEvents, policies: [declaredPolicy] });
             claims.push({ ...declaredClaimObj, status: declaredStatus });
         }
@@ -752,7 +1038,7 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         const supersededBy = typeof c.superseded_by === "string" && c.superseded_by.length > 0 ? c.superseded_by : null;
         const critiqueReviewer = String(c.reviewer ?? "tool-code-reviewer");
         const critiqueReviewedAt = String(c.reviewed_at ?? ts);
-        const critMeta = { origin: "critique", reviewer: critiqueReviewer, reviewed_at: critiqueReviewedAt, ...(supersededBy ? { superseded_by: supersededBy } : {}) };
+        const critMeta = { origin: "critique", reviewer: critiqueReviewer, reviewed_at: critiqueReviewedAt, ...(activeStep && workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}), ...(supersededBy ? { superseded_by: supersededBy } : {}) };
         // A superseded historical write gets a distinct, stable claimId so it co-exists with the live
         // claim of the same critique id (never overwrites or duplicates it). The salt is reproducible
         // across rebuilds because superseded_by + reviewed_at are preserved in metadata.
@@ -848,6 +1134,7 @@ export async function writeTrustBundle(dir, slug, timestamp, checks, criteria, c
             return { written: false, errors: result.errors };
         }
         writeJson(path.join(dir, "trust.bundle"), bundle);
+        await syncBuilderFlowSessionIfPresent(dir);
         return { written: true, errors: [] };
     }
     catch (err) {
@@ -1087,8 +1374,23 @@ function parseCriterion(line, index) {
     if (m)
         text = text.slice(0, m.index).trim().replace(/\.$/, "");
     const item = { id: slugify(text, `criterion-${index + 1}`), description: text, status: "pending" };
-    if (evidence)
-        item.evidence_refs = [evidenceRef("command", { excerpt: evidence })];
+    // #412 (AC8 interaction, planning-contract.md line ~46/84): the "- Evidence: <...>" Markdown
+    // field is contractually a "test, command, screenshot, dashboard, doc, CI, or manual check" —
+    // NOT always a runnable command. Unconditionally synthesizing kind:"command" with the raw text
+    // in `excerpt` for EVERY Evidence line (the pre-existing behavior here) was already
+    // contract-incorrect for prose evidence; it is now also a hard failure at record time
+    // (validateAcceptanceEvidenceRefs's new runnability rejection targets kind:"command"'s
+    // excerpt/url), so fixing the classification here is required, not optional polish. Use the
+    // SAME isRunnableCommandText heuristic the record-time rejection itself uses (single-sourced):
+    // literally-runnable text goes in `excerpt` (reconcilable, execution.label-eligible); anything
+    // else (prose, or ensure-session's own "pending" scaffold placeholder) goes in `summary`
+    // instead (never validated for runnability, never executed) — still kind:"command" (a
+    // structured ref is still produced either way; only WHICH field carries the text changes),
+    // per the contract's own "prose belongs in ref.summary" rule.
+    if (evidence) {
+        const { isRunnableCommandText } = loadRunnableCommandHelper();
+        item.evidence_refs = [evidenceRef("command", isRunnableCommandText(evidence) ? { excerpt: evidence } : { summary: evidence })];
+    }
     return item;
 }
 function artifactDirFrom(value) { return path.extname(value) ? path.dirname(value) : value; }
@@ -1213,6 +1515,45 @@ function loadCurrentPointerHelper() {
     const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/current-pointer.js");
     return _req(helperPath);
 }
+/**
+ * #412: delegate to the shared pure-CJS runnable-command-text heuristic
+ * (scripts/hooks/lib/runnable-command.js), mirroring the createRequire idiom used by
+ * loadCurrentPointerHelper()/loadActorIdentityHelper() above. Single-sources the heuristic
+ * between stop-goal-fit.js's Stop-time backstop and this file's record-time rejection
+ * (validateAcceptanceEvidenceRefs, recordGateClaim --command, recordCheck --command) — see
+ * AC9.
+ *
+ * #362 (Wave 3, AC6/AC7): extended (not a new sibling loader — same module, same
+ * createRequire call, single require() of runnable-command.js) to also return
+ * `isAmbiguousAbsenceCommand`, landed in that module by Wave 1's Task 1.2. This keeps
+ * `recordCheck`'s record-time ambiguous-status stamp and `validateAcceptanceEvidenceRefs`'s
+ * record-time advisory single-sourced against the SAME heuristic `runBackstop`/
+ * `readCommandLog`/`evidence-capture.js`'s `observeResult` already consume (Waves 1-2) —
+ * never a second, divergent implementation of "what counts as ambiguous."
+ */
+function loadRunnableCommandHelper() {
+    const _req = createRequire(import.meta.url);
+    const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/runnable-command.js");
+    return _req(helperPath);
+}
+/**
+ * #362 (iteration-2 fix item 4/LOW): single-sourced human-facing remediation fragment shared by
+ * this file's two ambiguous-absence-command emission sites (`validateAcceptanceEvidenceRefs`'s
+ * record-time advisory and `recordCheck`'s ambiguous-status stderr note) — mirrors how
+ * `isAmbiguousAbsenceCommand` itself is single-sourced above. Cross-ref: scripts/hooks/
+ * stop-goal-fit.js keeps its OWN copy of the equivalent shared string (`AMBIGUOUS_REMEDIATION`)
+ * for its three Stop-hook emission sites — the two files do not share a module for this string,
+ * so each file single-sources independently.
+ */
+const AMBIGUOUS_REMEDIATION_ADVICE = "self-asserting command ('! grep ...' or 'grep -c ... | grep -qx 0')";
+function validateRunnableCheckCommand(check, context) {
+    if (check.kind !== "command" || !hasNonEmptyString(check.command))
+        return;
+    const { isRunnableCommandText } = loadRunnableCommandHelper();
+    if (!isRunnableCommandText(check.command)) {
+        die(`${context}: kind:"command" check command is not a runnable shell command: "${check.command}" — remediate by either (1) moving the prose to summary and omitting command/execution.label, or (2) reclassifying this check as kind:"external" (session-local attestation) instead of kind:"command".`);
+    }
+}
 /**
  * #291 Wave 2 Task 2.1 (§5): writes the UNCHANGED legacy global `<root>/current.json` (the
  * compat-shim's write-side half — every existing consumer without an actorKey keeps reading
@@ -1222,7 +1563,7 @@ function loadCurrentPointerHelper() {
  * byte-identical to this function's pre-#291 behavior — with a stderr note mirroring the existing
  * unresolved-actor branch-naming diagnostic.
  */
-function writeCurrent(root, dir, timestamp, owner, source, flowId, stepId, adHocReason, actorKey) {
+function writeCurrent(root, dir, timestamp, owner, source, flowId, stepId, actorKey) {
     // #289: mirror the active session's already-recorded branch (state.json.branch) into
     // current.json so consumers of current.json (which has no schema of its own — not one of the
     // 9 schemas under schemas/) see the routing branch without re-reading state.json separately.
@@ -1241,11 +1582,6 @@ function writeCurrent(root, dir, timestamp, owner, source, flowId, stepId, adHoc
         // FlowDefinition omit them and fall through to the workflow.* claim type path.
         ...(flowId ? { active_flow_id: flowId } : {}),
         ...(stepId ? { active_step_id: stepId } : {}),
-        // WS8 (AC12): sanctioned ad-hoc direct entry marker. Set when --step-id explicitly
-        // targets a step other than the flow's resolved first step, so stop-goal-fit /
-        // gate-review can distinguish an intentional direct entry (e.g. a planning-only
-        // session that skips pull-work) from a stale/mis-stamped active_step_id.
-        ...(adHocReason ? { ad_hoc_entry: true, ad_hoc_reason: adHocReason } : {}),
     };
     writeJson(path.join(root, "current.json"), payload);
     if (actorKey && !loadActorIdentityHelper().isUnresolvedActor(actorKey)) {
@@ -1324,7 +1660,7 @@ function updateCurrentAgent(root, dir, agentId, status, timestamp, actorKey) {
         }
     }
 }
-function initSidecars(dir, slug, sourceRequest, summary, nextAction, timestamp, markdown) {
+function initSidecars(dir, slug, sourceRequest, summary, nextAction, timestamp, markdown, workItemRefs = [], initialLifecycle) {
     const criteria = markdown ? definitionAcceptanceLines(markdown).map(parseCriterion) : [];
     // #289/#309: `markdown` here is NOT always the session `<slug>--deliver.md` that
     // ensureSession seeds the `branch:` line into — initPlan is called against the tool-planner's
@@ -1355,9 +1691,11 @@ function initSidecars(dir, slug, sourceRequest, summary, nextAction, timestamp,
     // current call's timestamp silently rewrites a session's original creation time. Preserve the
     // existing state.json's created_at when present; stamp only on true first-creation.
     // updated_at still reflects "now" on every call — that field is intentionally mutable.
+    const retainedWorkItemRefs = workItemRefs.length > 0 ? workItemRefs : (Array.isArray(existingState.work_item_refs) ? existingState.work_item_refs : []);
     writeJson(path.join(dir, "state.json"), {
-        ...sidecarBase(slug), status: "planned", phase: "planning", created_at: existingState.created_at || timestamp, updated_at: timestamp,
+        ...sidecarBase(slug), status: initialLifecycle?.status ?? "planned", phase: initialLifecycle?.phase ?? "planning", created_at: existingState.created_at || timestamp, updated_at: timestamp,
         ...(branch ? { branch } : {}),
+        ...(retainedWorkItemRefs.length > 0 ? { work_item_refs: retainedWorkItemRefs } : {}),
         artifact_paths: relArtifacts(dir),
         next_action: { status: "continue", summary: nextAction || summary },
     });
@@ -1567,10 +1905,40 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution) {
  *   --claim-ttl-seconds <n>        Overrides the liveness-policy TTL default for a new claim.
  *   --reason <text>                Audit-trail reason recorded on the claim/supersede record.
  */
+function resolveEnsureSessionEntry(p, dir) {
+    const flowId = opt(p, "flow-id");
+    const explicitStep = opt(p, "step-id");
+    if (!flowId) {
+        if (explicitStep)
+            die("ensure-session --step-id requires --flow-id");
+        if (opt(p, "ad-hoc-reason"))
+            die("ensure-session --ad-hoc-reason is no longer supported");
+        return { flowId: "", stepId: "", firstStep: "" };
+    }
+    const firstStep = resolveFirstStep(flowId, findRepoRootFromDir(dir));
+    if (!firstStep)
+        die(`ensure-session could not resolve the first step for Flow Definition ${JSON.stringify(flowId)}`);
+    if (opt(p, "ad-hoc-reason")) {
+        die("ensure-session --ad-hoc-reason cannot authorize workflow entry; start at the Flow Definition's first step or resume persisted run state");
+    }
+    if (explicitStep && explicitStep !== firstStep) {
+        die(`ensure-session refused workflow entry at ${JSON.stringify(explicitStep)}: new runs must start at first step ${JSON.stringify(firstStep)}; resume an existing run without --step-id`);
+    }
+    return { flowId, stepId: explicitStep || firstStep, firstStep };
+}
+function preflightEnsureSession(p) {
+    const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : flowAgentsArtifactRoot();
+    const slug = opt(p, "task-slug") || (opt(p, "work-item") ? workItemSlug(opt(p, "work-item")) : die("--task-slug is required (or pass --work-item to derive it)"));
+    const dir = sessionDirFor(root, slug);
+    resolveEnsureSessionEntry(p, dir);
+    sessionWorkItem(p, slug, dir);
+}
 function ensureSession(p) {
     const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : flowAgentsArtifactRoot();
     const slug = opt(p, "task-slug") || (opt(p, "work-item") ? workItemSlug(opt(p, "work-item")) : die("--task-slug is required (or pass --work-item to derive it)"));
     const dir = sessionDirFor(root, slug);
+    const entry = resolveEnsureSessionEntry(p, dir);
+    const workItem = sessionWorkItem(p, slug, dir);
     // #291 Wave 2 Task 2.1 (§3, §4): resolve the actor ONCE, then run the ownership guard BEFORE
     // any directory/file is created — a refusal must never leave a stray empty session dir. Reused
     // below (writeCurrent's per-actor dual-write) so the branch-naming actor and the
@@ -1579,6 +1947,9 @@ function ensureSession(p) {
     enforceEnsureSessionOwnership(p, root, slug, dir, actorResolution);
     fs.mkdirSync(dir, { recursive: true });
     const timestamp = opt(p, "timestamp", now());
+    if (workItem.localRecord && !fs.existsSync(path.join(dir, "work-item.json"))) {
+        writeJson(path.join(dir, "work-item.json"), workItem.localRecord);
+    }
     let md = fs.existsSync(path.join(dir, `${slug}--deliver.md`)) ? read(path.join(dir, `${slug}--deliver.md`)) : "";
     if (!md) {
         // #289: derive the routing branch ONLY on fresh session creation (this `if (!md)` guard).
@@ -1586,11 +1957,19 @@ function ensureSession(p) {
         // of code is skipped on a resumed/taken-over session, which is what makes ADR 0021 §5
         // takeover continuity true by construction (see Design Decision 3 in the plan).
         const branch = resolveSessionBranch(p, slug);
-        md = `# ${opt(p, "title", slug)}\n\nbranch: ${branch}\nworktree: main\ncreated: ${timestamp}\nstatus: planning\ntype: deliver\niteration: 1\n\n## Plan\n\n${opt(p, "summary", "")}\n\n## Definition Of Done\n\n- **User outcome:** ${opt(p, "summary", "Workflow session is durable.")}\n- **Scope:** Workflow session artifacts and sidecars.\n- **Acceptance criteria:**\n${opts(p, "criterion").map((c) => `  - [ ] ${c} - Evidence: pending.`).join("\n")}\n- **Usefulness checks:**\n  - [ ] User-facing workflow is documented or discoverable\n- **Stop-short risks:** Workflow artifacts could drift.\n- **Durable docs target:** not needed\n- **Sandbox mode:** local-edit\n\n## Execution Progress\n\n- [ ] Session initialized.\n\n## Verification Report\n\nBuild: [NOT_VERIFIED] Verification has not run yet.\n\n### Acceptance Criteria\n- [NOT_VERIFIED] Verification has not run yet - Evidence: pending workflow execution and checks.\n\n### Verdict: NOT_VERIFIED\n\n## Goal Fit Gate\n\n- [ ] Original user goal restated\n\n## Final Acceptance\n\n- [ ] CI/relevant checks passed or local equivalent recorded\n`;
+        const initialMarkdownStatus = entry.flowId ? "new" : "planning";
+        md = `# ${opt(p, "title", slug)}\n\nbranch: ${branch}\nworktree: main\ncreated: ${timestamp}\nstatus: ${initialMarkdownStatus}\ntype: deliver\niteration: 1\n\n## Plan\n\n${opt(p, "summary", "")}\n\n## Definition Of Done\n\n- **User outcome:** ${opt(p, "summary", "Workflow session is durable.")}\n- **Scope:** Workflow session artifacts and sidecars.\n- **Acceptance criteria:**\n${opts(p, "criterion").map((c) => `  - [ ] ${c} - Evidence: pending.`).join("\n")}\n- **Usefulness checks:**\n  - [ ] User-facing workflow is documented or discoverable\n- **Stop-short risks:** Workflow artifacts could drift.\n- **Durable docs target:** not needed\n- **Sandbox mode:** local-edit\n\n## Execution Progress\n\n- [ ] Session initialized.\n\n## Verification Report\n\nBuild: [NOT_VERIFIED] Verification has not run yet.\n\n### Acceptance Criteria\n- [NOT_VERIFIED] Verification has not run yet - Evidence: pending workflow execution and checks.\n\n### Verdict: NOT_VERIFIED\n\n## Goal Fit Gate\n\n- [ ] Original user goal restated\n\n## Final Acceptance\n\n- [ ] CI/relevant checks passed or local equivalent recorded\n`;
         fs.writeFileSync(path.join(dir, `${slug}--deliver.md`), md);
     }
     if (!fs.existsSync(path.join(dir, "state.json")) || !fs.existsSync(path.join(dir, "acceptance.json")) || !fs.existsSync(path.join(dir, "handoff.json"))) {
-        initSidecars(dir, slug, opt(p, "source-request"), opt(p, "summary"), opt(p, "next-action", "Continue."), timestamp, md);
+        const phaseMap = entry.flowId ? resolvePhaseMap(entry.flowId, findRepoRootFromDir(dir)) : null;
+        const initialPhase = Object.entries(phaseMap ?? {}).find(([, step]) => step === entry.firstStep)?.[0];
+        const nextAction = entry.flowId
+            ? entry.flowId === "builder.build"
+                ? `Start the canonical Flow run with \`flow-agents builder-run start --session-dir .kontourai/flow-agents/${slug}\`; activate \`pull-work\` for work item ${JSON.stringify(workItem.ref)}, and satisfy the declared gate before advancing.`
+                : `Continue at Flow step ${JSON.stringify(entry.stepId)} for work item ${JSON.stringify(workItem.ref)}; satisfy its declared gate before advancing.`
+            : opt(p, "next-action", "Continue.");
+        initSidecars(dir, slug, opt(p, "source-request"), opt(p, "summary"), nextAction, timestamp, md, [workItem.ref], initialPhase ? { status: "new", phase: initialPhase } : undefined);
     }
     // ADR 0016 Abstraction A (P-a): optional --flow-id / --step-id flags persist FlowDefinition
     // routing keys into current.json for the producer (P-b) and enforcer (P-c) to consume.
@@ -1599,29 +1978,14 @@ function ensureSession(p) {
     // active_step_id to the FIRST step in the FlowDefinition's steps[] list. This ensures
     // ensure-session --flow-id builder.build produces a FlowDefinition-driven session even
     // before the first advance-state call.
-    const flowId = opt(p, "flow-id");
-    const explicitStep = opt(p, "step-id");
-    let stepId = explicitStep;
-    let adHocReason;
-    if (flowId && !stepId) {
-        const repoRoot = findRepoRootFromDir(dir);
-        const firstStep = resolveFirstStep(flowId, repoRoot);
-        if (firstStep)
-            stepId = firstStep;
-    }
-    else if (flowId && explicitStep) {
-        // WS8 (AC12): --step-id is the sanctioned ad-hoc direct-entry mechanism. When it names
-        // a step other than the flow's resolved first step, record an explicit ad_hoc_entry
-        // marker (with a reason) instead of silently letting the mis-stamp look like the
-        // flow's normal first step. This is the root-cause fix for a planning-only session
-        // whose active_step_id would otherwise default to builder.build's first step.
-        const repoRoot = findRepoRootFromDir(dir);
-        const firstStep = resolveFirstStep(flowId, repoRoot);
-        if (firstStep && firstStep !== explicitStep) {
-            adHocReason = opt(p, "ad-hoc-reason") || `direct entry at step "${explicitStep}" via --step-id (flow first step is "${firstStep}")`;
-        }
-    }
-    writeCurrent(root, dir, timestamp, "workflow-sidecar", "ensure-session", flowId || undefined, stepId || undefined, adHocReason, actorResolution.unresolved ? undefined : actorResolution.branchActorKey);
+    const persistedCurrent = loadCurrent(root);
+    const resumedStep = !opt(p, "step-id")
+        && persistedCurrent?.active_slug === slug
+        && persistedCurrent?.active_flow_id === entry.flowId
+        && typeof persistedCurrent?.active_step_id === "string"
+        ? persistedCurrent.active_step_id
+        : entry.stepId;
+    writeCurrent(root, dir, timestamp, "workflow-sidecar", "ensure-session", entry.flowId || undefined, resumedStep || undefined, actorResolution.unresolved ? undefined : actorResolution.branchActorKey);
     console.log(dir);
     return 0;
 }
@@ -1750,14 +2114,62 @@ export function normalizeEvidenceRefs(raw, label) {
         return validateEvidenceRef({ ...ref }, label);
     });
 }
-export function normalizeCheck(raw) {
+// #270 HIGH fix (iteration 3): the `gate-claim-` check-id prefix is RESERVED for
+// record-gate-claim's own internally-constructed ids (`id: \`gate-claim-${checkId}\`` — see
+// recordGateClaim below). Every OTHER writer of check ids (record-evidence --check-json,
+// record-check, dogfood-pass --check-json) flows through this same normalizeCheck, and until
+// this fix any of them could ALSO hand-supply an id starting with "gate-claim-". That collision
+// silently satisfies the id-shape half of gateClaimShapeUnstampedId's four-signal detector (see
+// its comment above) without ever having gone through record-gate-claim, so a later rebuild
+// misclassifies the caller's check as an unstamped pre-cluster-270 gate claim and dies, losing
+// the write. Rejecting the prefix HERE, at record time, for every caller-supplied id makes the
+// id-shape signal sound again: only record-gate-claim's own path can ever produce that shape.
+// record-gate-claim opts in via allowGateClaimPrefix=true since it is the sole legitimate
+// producer of that id shape; every other caller uses the default (reject).
+//
+// #270 follow-up fix (publish-preflight, iteration 5): the rejection above must apply ONLY to
+// NEW mints, not to a correction of an id that already exists as a check claim id in the
+// session's CURRENT trust.bundle. A mis-recorded claim that already carries a `gate-claim-`
+// prefixed id (e.g. one that slipped through before this guard shipped, or was recorded via a
+// binary predating it) can otherwise NEVER be corrected: every attempt to re-record that exact
+// id — the only way to supersede/fix it — is itself rejected by this same guard, permanently
+// wedging that id.
+//
+// #270 CRITICAL fix (iteration 6, narrowing the above): "the id's identity already exists in
+// the bundle" is NOT by itself a safe supersession signal — an id that already exists MIGHT be
+// a REAL, properly-stamped claim produced by record-gate-claim itself (its own generated
+// `gate-claim-${checkId}` ids always already "exist" once minted). Exempting every existing id
+// unconditionally let record-evidence/record-check/dogfood-pass silently overwrite a live,
+// correctly-stamped gate claim — destroying its metadata.gate_claim stamp — and the caller
+// fully controls check_kind, so the replacement claim can trivially be shaped to evade
+// gateClaimShapeUnstampedId's detector (that detector requires check_kind==="external", which
+// only fires the alarm when the caller happens to pick that kind). The narrowed rule: an
+// existing id is supersedable via this path ONLY when the EXISTING claim for that id carries NO
+// metadata.gate_claim stamp — i.e. only the mis-recorded/wedged shape (the legitimate
+// correction target this exemption exists for). An existing id whose claim IS stamped is a live
+// gate claim; only record-gate-claim (allowGateClaimPrefix=true, its own unconditional opt-in)
+// may ever supersede it. Callers therefore pass `existingCheckStampById` (a Map from the
+// bundle's CURRENT check ids to whether that check's claim already carries a metadata.gate_claim
+// stamp, read via readBundleState/checksFromBundle's `_gate_claim_expectation_id` restoration
+// BEFORE normalizeCheck runs — see applyGateClaimStamp). This does not weaken new-mint
+// enforcement: a NOVEL gate-claim-* id (not already present at all) is still rejected exactly as
+// before, and superseding a STAMPED existing id is now rejected too.
+export function normalizeCheck(raw, allowGateClaimPrefix = false, existingCheckStampById) {
     const check = { ...raw };
     if (!check.id || !check.kind || !check.status || !check.summary)
         die("check requires id, kind, status, and summary");
+    if (!allowGateClaimPrefix && typeof check.id === "string" && check.id.startsWith("gate-claim-")) {
+        const existingHasStamp = existingCheckStampById?.get(check.id);
+        if (existingHasStamp === true)
+            die(`check id "${check.id}" belongs to a live, properly-stamped gate claim — only record-gate-claim may supersede it. Superseding a stamped gate claim via record-evidence/record-check/dogfood-pass would silently destroy its metadata.gate_claim stamp. Re-record via record-gate-claim, or choose a different --id.`);
+        if (existingHasStamp === undefined)
+            die(`check id "${check.id}" starts with the reserved "gate-claim-" prefix — that namespace is reserved for record-gate-claim's own generated ids. Choose a different --id (or omit --id to let the check derive one from its command/summary). Supersession of an EXISTING, UNSTAMPED check claim with this same id (a correction) is permitted — this rejection applies to newly-minted ids not already present in the session's trust.bundle, and to ids that already belong to a stamped (live) gate claim.`);
+    }
     if (!checkKinds.has(check.kind))
         die("kind must be one of: build, types, lint, test, command, security, diff, browser, runtime, policy, external");
     if (!checkStatuses.has(check.status))
         die("status must be one of: pass, fail, not_verified, skip");
+    validateRunnableCheckCommand(check, `check ${String(check.id)}`);
     if (Array.isArray(check.standard_refs))
         for (const ref of check.standard_refs)
             if (!["junit", "sarif", "coverage", "veritas"].includes(ref.standard))
@@ -1889,16 +2301,59 @@ function surfaceCheckFromArtifact(file, index) {
     }
     return { id: `surface-trust-${index + 1}`, kind: "policy", status: ref.status, summary: ref.summary, surface_trust_refs: [ref] };
 }
-function validateAcceptanceEvidenceRefs(dir) {
+/**
+ * #270 MEDIUM security fix: a `kind:"command"` evidence_refs entry whose command source is
+ * genuinely non-runnable-by-design (e.g. a screenshot/dashboard reference the record-time
+ * heuristic misclassifies) previously had NO escape hatch — this validator's die() was an
+ * unconditional lockout. Mirrors --skip-ownership-guard's existing pattern in this file exactly:
+ * a named, logged (never silent) bypass flag, not a silent fallback. `--skip-evidence-ref-
+ * runnability-guard` is intentionally verbose/unambiguous so it is never reached for
+ * accidentally — the die() message itself names the concrete remediations FIRST (move the prose
+ * to ref.summary, or reclassify as kind:"external"/"artifact"), so the bypass is a last resort,
+ * not the first thing an agent reaches for.
+ */
+function validateAcceptanceEvidenceRefs(dir, p) {
+    if (p?.flags.has("skip-evidence-ref-runnability-guard")) {
+        process.stderr.write("[record-evidence] evidence-ref runnability guard skipped via --skip-evidence-ref-runnability-guard\n");
+        return;
+    }
     const file = path.join(dir, "acceptance.json");
     if (!fs.existsSync(file))
         return;
     const data = loadJson(file);
     if (!Array.isArray(data.criteria))
         return;
+    const { isRunnableCommandText, isAmbiguousAbsenceCommand } = loadRunnableCommandHelper();
     data.criteria.forEach((criterion, index) => {
-        if (criterion.evidence_refs !== undefined)
-            normalizeEvidenceRefs(criterion.evidence_refs, `acceptance.criteria[${index}].evidence_refs`);
+        if (criterion.evidence_refs === undefined)
+            return;
+        const refs = normalizeEvidenceRefs(criterion.evidence_refs, `acceptance.criteria[${index}].evidence_refs`);
+        // #412 (AC8): a kind:"command" ref's command source (excerpt, falling back to url when that
+        // is where the command string lives) must be a literally runnable shell command, not prose
+        // describing a manual verification step — reject at RECORD time instead of letting it reach
+        // the Stop-hook backstop (stop-goal-fit.js's bundleClaimedPassCommandChecks section B), which
+        // would otherwise spawn `bash -lc "<a sentence>"` and misreport the resulting shell error as
+        // a caught false-completion. Prose belongs in `summary` (never executed).
+        refs.forEach((ref, refIndex) => {
+            if (ref.kind !== "command")
+                return;
+            const commandSource = hasNonEmptyString(ref.excerpt) ? ref.excerpt : (hasNonEmptyString(ref.url) ? ref.url : "");
+            if (!commandSource)
+                return; // command refs may carry only `summary` — nothing to validate
+            if (!isRunnableCommandText(commandSource)) {
+                die(`acceptance.criteria[${index}].evidence_refs[${refIndex}]: kind:"command" ref's command text is not a runnable shell command: "${commandSource}" — remediate by either (1) moving the prose to ref.summary (never executed) and dropping/emptying ref.excerpt/ref.url, or (2) reclassifying this ref as kind:"external" (session-local attestation) or kind:"artifact" (a file/screenshot/dashboard reference) instead of kind:"command". As a last resort, --skip-evidence-ref-runnability-guard bypasses this check (logged, not silent).`);
+            }
+            // #362 (Wave 3, AC7): ADVISORY ONLY — never die(), never rejects/alters the ref. This is
+            // deliberately the opposite posture from the runnability guard immediately above (which
+            // stays fatal, unchanged). Guidance, not enforcement, per the plan's item 2: nudge a
+            // newly-recorded bare (non-negated, non-count-asserted, non-chained) grep/diff evidence
+            // ref toward a self-asserting form, without breaking back-compat with any already-recorded
+            // evidence ref (#412) — an already-recorded ref reaching this validator on every subsequent
+            // record-evidence call must keep passing, just with a repeated nudge, never a new failure.
+            if (isAmbiguousAbsenceCommand(commandSource)) {
+                process.stderr.write(`[record-evidence] advisory: acceptance.criteria[${index}].evidence_refs[${refIndex}] kind:"command" ref "${commandSource}" is a bare grep/diff invocation — its exit code is AMBIGUOUS (zero matches/no diff could mean PASS for an absence check or FAIL for a presence check). Consider re-recording it as a ${AMBIGUOUS_REMEDIATION_ADVICE} to remove the ambiguity. This is advisory only; the ref is NOT rejected.\n`);
+            }
+        });
     });
 }
 export function writeState(dir, slug, status, phase, timestamp, summary, next = "continue") {
@@ -1968,6 +2423,98 @@ function checksFromBundle(dir) {
         const md = claim.metadata;
         return md && typeof md === "object" && md.waiver && typeof md.waiver === "object" ? md.waiver : undefined;
     };
+    // #298: read side of the artifact_refs/standard_refs stamp (write side: buildTrustBundle's
+    // claimMetadata.artifact_refs/.standard_refs, above). Previously these were validated on input
+    // but never persisted at all — restoring them here is what makes them round-trip through a
+    // second writer's rebuild instead of vanishing on the very first write.
+    const refsOf = (claim) => {
+        const md = claim.metadata;
+        if (!md || typeof md !== "object")
+            return {};
+        const out = {};
+        if (Array.isArray(md.artifact_refs) && md.artifact_refs.length > 0)
+            out.artifact_refs = md.artifact_refs;
+        if (Array.isArray(md.standard_refs) && md.standard_refs.length > 0)
+            out.standard_refs = md.standard_refs;
+        return out;
+    };
+    // #270/#380: read side of the record-check output-digest stamp (write side: buildTrustBundle's
+    // claimMetadata.output_digest, above). Restoring it here is what makes the digest survive a
+    // subsequent writer's rebuild instead of vanishing on the very next record-evidence/
+    // record-critique/record-learning call.
+    const outputSha256Of = (claim) => {
+        const md = claim.metadata;
+        const od = md && typeof md === "object" ? md.output_digest : undefined;
+        return od && typeof od === "object" && od.algorithm === "sha256" && typeof od.hex === "string" && od.hex.length > 0 ? od.hex : undefined;
+    };
+    // #270(a)/(c): read side of the gate_claim stamp (write side: buildTrustBundle's
+    // claimMetadata.gate_claim, above). Restoring expectation_id/claim_type/subject_type/step_id
+    // is what lets a REBUILD (record-evidence/record-critique/record-learning, after the recorded
+    // gate claim) recognize this as a previously-typed gate claim and reuse its frozen typing
+    // instead of re-deriving via matchExpectsEntry against whatever step is active at rebuild time.
+    const gateClaimOf = (claim) => {
+        const md = claim.metadata;
+        return md && typeof md === "object" && md.gate_claim && typeof md.gate_claim === "object" ? md.gate_claim : undefined;
+    };
+    const applyGateClaimStamp = (check, claim) => {
+        const gc = gateClaimOf(claim);
+        if (!gc)
+            return;
+        if (typeof gc.expectation_id === "string")
+            check._gate_claim_expectation_id = gc.expectation_id;
+        if (typeof gc.claim_type === "string")
+            check._gate_claim_declared_type = gc.claim_type;
+        if (typeof gc.subject_type === "string")
+            check._gate_claim_declared_subject = gc.subject_type;
+        if (typeof gc.step_id === "string")
+            check._gate_claim_declared_step_id = gc.step_id;
+        if (typeof gc.route_reason === "string")
+            check._gate_claim_route_reason = gc.route_reason;
+    };
+    // #270 CRITICAL/HIGH fix: a claim that is gate-claim-SHAPED but carries NO metadata.gate_claim
+    // stamp predates this cluster (#270/#344): buildTrustBundle could not have produced this shape
+    // without ALSO writing the stamp, once the stamping code shipped, EXCEPT for one legitimate,
+    // longstanding case that must NOT be flagged: a plain record-evidence check (kind:"external" or
+    // otherwise) that simply happens to auto-match a declared kit-typed claim via matchExpectsEntry's
+    // existing P-d fallback (ADR 0016) while a flow step is active — that path has ALWAYS existed,
+    // never goes through record-gate-claim, and correctly has no gate_claim stamp (there is no
+    // expectation id to freeze; matchExpectsEntry's heuristic result is expected to re-derive on
+    // every rebuild for a plain check). The ONLY structurally reliable signal that a claim was
+    // ACTUALLY produced by record-gate-claim (as opposed to a plain check that merely resembles one)
+    // is record-gate-claim's own check-id-generation convention: `id: \`gate-claim-${checkId}\``
+    // (see recordGateClaim) — no other producer in this file ever creates that id shape. Requiring
+    // ALL FOUR signals (origin:"check", check_kind:"external", a kit-typed claimType — i.e. does NOT
+    // start with "workflow." — AND a subjectId whose last path segment starts with "gate-claim-")
+    // narrows detection to exactly the pre-cluster-270 defect class, without misclassifying an
+    // ordinary declared check. Detected here (not in buildTrustBundle) because the claim's OWN
+    // claimType/origin/check_kind/subjectId — the fields the detection needs — live on the bundle
+    // claim, not on the reconstructed `check` object; buildTrustBundle only ever sees the `check`,
+    // so the detection result is threaded through as a stamp on the check object itself, exactly
+    // like every other gate_claim field above. buildTrustBundle's job is then only to die() loudly
+    // on this stamp — never to re-derive or silently re-type it (that silent re-typing IS the
+    // #268/#270 defect class).
+    const gateClaimShapeUnstampedId = (claim) => {
+        if (claimOrigin(claim) !== "check")
+            return null;
+        const md = (claim.metadata && typeof claim.metadata === "object") ? claim.metadata : {};
+        if (md.check_kind !== "external")
+            return null;
+        const claimType = typeof claim.claimType === "string" ? claim.claimType : "";
+        if (!claimType || claimType.startsWith("workflow."))
+            return null;
+        const subjectId = typeof claim.subjectId === "string" ? claim.subjectId : "";
+        const lastSegment = subjectId.split("/").pop() ?? "";
+        if (!lastSegment.startsWith("gate-claim-"))
+            return null; // not record-gate-claim-shaped at all
+        if (gateClaimOf(claim))
+            return null; // properly stamped — not this defect class
+        return typeof claim.id === "string" ? claim.id : "<unknown>";
+    };
+    const applyGateClaimShapeUnstamped = (check, claim) => {
+        const unstampedId = gateClaimShapeUnstampedId(claim);
+        if (unstampedId)
+            check._gate_claim_shape_unstamped_claim_id = unstampedId;
+    };
     for (const ev of bundle.evidence) {
         if (!ev || !ev.claimId)
             continue;
@@ -1989,6 +2536,12 @@ function checksFromBundle(dir) {
         const waiver = waiverOf(claim);
         if (waiver)
             check._waiver = waiver;
+        Object.assign(check, refsOf(claim));
+        const outputSha256 = outputSha256Of(claim);
+        if (outputSha256)
+            check._output_sha256 = outputSha256;
+        applyGateClaimStamp(check, claim);
+        applyGateClaimShapeUnstamped(check, claim);
         checks.push(check);
     }
     // Also include check claims that have no evidence item (surface_trust_refs style).
@@ -2005,10 +2558,67 @@ function checksFromBundle(dir) {
         const waiver = waiverOf(claim);
         if (waiver)
             check._waiver = waiver;
+        Object.assign(check, refsOf(claim));
+        const outputSha256 = outputSha256Of(claim);
+        if (outputSha256)
+            check._output_sha256 = outputSha256;
+        applyGateClaimStamp(check, claim);
+        applyGateClaimShapeUnstamped(check, claim);
         checks.push(check);
     }
     return checks;
 }
+/**
+ * #270 CRITICAL fix (iteration 6): build the id -> hasStamp map normalizeCheck's narrowed
+ * reserved-prefix exemption needs. A check's reconstructed `_gate_claim_expectation_id` (set by
+ * applyGateClaimStamp above, from the claim's metadata.gate_claim) is present if and only if the
+ * bundle claim backing this check id currently carries a live stamp. Every caller of
+ * normalizeCheck (record-evidence, record-check, dogfood-pass) must derive this from the SAME
+ * readBundleState/checksFromBundle snapshot used for the compose-safe merge, taken BEFORE
+ * normalizeCheck runs, so the exemption sees the bundle state as it stands right now — not a
+ * stale or partial view.
+ */
+function existingCheckStampMap(checks) {
+    const byId = new Map();
+    for (const c of checks)
+        if (c && typeof c.id === "string")
+            byId.set(c.id, typeof c._gate_claim_expectation_id === "string");
+    return byId;
+}
+/**
+ * #298/#270: the shared compose-safe read path every trust-bundle writer should use instead of
+ * hand-assembling its own partial slice. Reconstructs ALL THREE families losslessly from the
+ * existing bundle (checks via checksFromBundle, extended per above; criteria from
+ * acceptance.json; critiques via critiquesFromBundle) so a writer that only intends to touch ONE
+ * family never has to pass `[]` for the other two — that `[]`-for-untouched-slices pattern is
+ * exactly what caused #270's 21-claims-to-1 wipe. Generalizes the pattern recordLearning already
+ * used inline; behavior-neutral for recordLearning itself.
+ */
+function readBundleState(dir) {
+    const acceptance = loadJson(path.join(dir, "acceptance.json"));
+    return {
+        checks: checksFromBundle(dir),
+        criteria: Array.isArray(acceptance.criteria) ? acceptance.criteria : [],
+        critiques: critiquesFromBundle(dir),
+    };
+}
+/**
+ * #298: compose-safe merge-by-id for the `checks` slice of readBundleState — a later check
+ * with the same `id` supersedes/replaces the earlier one (same-id resupply is a legitimate
+ * update, e.g. re-recording the same gate claim or the same named check after a fix); a check
+ * with a new `id` is additive. Order is preserved (existing order, then newly-introduced ids
+ * appended) so unrelated diagnostics (e.g. CI reconcile output) do not reorder churn.
+ */
+function mergeChecksById(existing, incoming) {
+    const byId = new Map();
+    for (const c of existing)
+        if (c && c.id)
+            byId.set(c.id, c);
+    for (const c of incoming)
+        if (c && c.id)
+            byId.set(c.id, c);
+    return [...byId.values()];
+}
 function critiquesFromBundle(dir) {
     const bundle = loadJson(path.join(dir, "trust.bundle"));
     if (!Array.isArray(bundle.claims))
@@ -2060,7 +2670,14 @@ async function recordEvidence(p) {
     const slug = taskSlugFor(dir, opt(p, "task-slug"));
     const _ts0 = opt(p, "timestamp", now());
     const _waiver = parseWaiver(p, _ts0);
-    const _checksRaw = [...opts(p, "check-json").map((v) => normalizeCheck(parseJson(v, "--check-json"))), ...opts(p, "surface-trust-json").map(surfaceCheckFromArtifact)];
+    // #270 follow-up fix (iteration 5, narrowed iteration 6): read the bundle's CURRENT check ids
+    // (and stamp status) before normalizeCheck runs so a correction of an UNSTAMPED wedged id is
+    // exempted from the reserved gate-claim- prefix rejection below, while a brand-new mint of
+    // that shape, OR supersession of a STAMPED (live) gate claim, is still rejected. Reused below
+    // (not re-read) as _existingState for the compose-safe merge — one readBundleState call.
+    const _existingState = readBundleState(dir);
+    const _existingCheckStampById = existingCheckStampMap(_existingState.checks);
+    const _checksRaw = [...opts(p, "check-json").map((v) => normalizeCheck(parseJson(v, "--check-json"), false, _existingCheckStampById)), ...opts(p, "surface-trust-json").map(surfaceCheckFromArtifact)];
     // WS8 (AC4, iteration 2): a command-backed check reconciles against CI or fails — it can
     // NEVER be waived. Reject --accepted-gap-reason/--waived-by on any check whose evidence
     // classifies as test_output (build/types/lint/test/command, and security/browser/runtime
@@ -2079,22 +2696,182 @@ async function recordEvidence(p) {
     const checks = _checksRaw.map((c) => _waiver ? { ...c, _waiver } : c);
     if (!checks.length && opts(p, "surface-trust-json").length === 0)
         die("record-evidence requires at least one --check-json or --surface-trust-json");
-    validateAcceptanceEvidenceRefs(dir);
+    validateAcceptanceEvidenceRefs(dir, p);
     // Phase 4c: bundle is the sole verification artifact — stop writing evidence.json and acceptance.json update.
     const ts = opt(p, "timestamp", now());
-    const _existingAcceptance = loadJson(path.join(dir, "acceptance.json"));
-    const _existingCriteria = Array.isArray(_existingAcceptance.criteria) ? _existingAcceptance.criteria : [];
+    // #298: readBundleState + merge-by-id instead of unconditionally replacing every prior check —
+    // record-evidence previously never called checksFromBundle(dir), so it dropped every check
+    // recorded by an earlier record-evidence/record-check/record-gate-claim call. A later check
+    // with the same id supersedes the earlier one (same-id resupply); a new id is additive.
+    // (_existingState was already read above, before normalizeCheck ran, so the reserved-prefix
+    // exists-check sees the SAME bundle snapshot the merge below uses — no second read needed.)
     const _criteriaStatus = verdict === "pass" ? "pass" : verdict === "fail" ? "fail" : "not_verified";
-    const _criteriaForBundle = _existingCriteria.map((c) => ({ ...c, status: _criteriaStatus }));
+    const _criteriaForBundle = _existingState.criteria.map((c) => ({ ...c, status: _criteriaStatus }));
+    const _mergedChecks = mergeChecksById(_existingState.checks, checks);
     // #268: preserve any existing critique claims (including superseded history) instead of dropping
     // them — record-evidence previously hardcoded critiques:[] here, silently erasing finding history
     // whenever it ran after a critique existed.
-    const _existingCritiques = critiquesFromBundle(dir);
-    assertBundleWritten(await writeTrustBundle(dir, slug, ts, checks, _criteriaForBundle, _existingCritiques));
+    assertBundleWritten(await writeTrustBundle(dir, slug, ts, _mergedChecks, _criteriaForBundle, _existingState.critiques));
     const stateStatus = verdict === "pass" ? "verified" : verdict === "fail" ? "failed" : "not_verified";
     writeState(dir, slug, stateStatus, "verification", ts, "Evidence recorded.");
     return 0;
 }
+// #380: bounded stdout+stderr digest for a record-check execution, mirroring
+// scripts/hooks/evidence-capture.js's MAX_OUTPUT_SCAN bound (64 KiB) so the two capture code
+// paths (host-observed vs. self-executed) stay size-disciplined the same way, even though this
+// one runs the command itself rather than observing a host tool_response.
+const RECORD_CHECK_MAX_OUTPUT = 64 * 1024;
+function clampOutput(text) {
+    return text.length > RECORD_CHECK_MAX_OUTPUT ? text.slice(0, RECORD_CHECK_MAX_OUTPUT) : text;
+}
+/**
+ * record-check — run a command and record a capture-backed check in one step (#380).
+ *
+ * Trust posture (#270 MEDIUM fix — was previously misdescribed): record-check EXECUTES a command
+ * ON THE AGENT'S BEHALF, in-process, right here — it is not an observer. This is a materially
+ * DIFFERENT trust posture than scripts/hooks/evidence-capture.js, which never executes anything
+ * itself; it only OBSERVES a host tool_response that some other, already-executed tool call
+ * produced (a PostToolUse hook). record-check's exitCode/observedResult classification mirrors
+ * evidence-capture.js's observeResult() heuristic (a clean integer exit code is authoritative),
+ * but the EXECUTION itself is this function's own doing, under this process's privileges — an
+ * agent invoking record-check is asking this CLI to run a command for it, not merely to attest to
+ * something that already ran. Callers and reviewers should weigh that accordingly: record-check
+ * is a convenience that collapses "run a command" + "record its result" into one step, not a
+ * passive-observation capture path.
+ *
+ * Syntax: `workflow-sidecar record-check <artifact-dir> -- <command...>` (argv after the FIRST
+ * literal `--` token is the command to execute verbatim, split by main() before parseArgs — see
+ * main()'s pre-split below) or `--command "<shell string>"` for parity with record-gate-claim
+ * when the caller already has a single shell string rather than an argv array.
+ *
+ * Captures { exitCode, observedResult } the same way evidence-capture.js's observeResult() does:
+ * a clean integer exit code drives observedResult (0 => pass, nonzero => fail). Records a
+ * kind:"command" check with a real execution.label (the executed command), composed losslessly
+ * through the same readBundleState + mergeChecksById + writeTrustBundle path every other writer
+ * in this file uses — record-check is the compose-safe pattern PLUS an execution step in front
+ * of it, not a parallel bundle-writing implementation.
+ *
+ * The captured stdout+stderr is hashed (sha256) and the digest — never the raw output — is
+ * persisted onto the resulting claim's metadata.output_digest (see buildTrustBundle's
+ * outputDigestMeta) so a later reviewer can confirm two independent runs produced byte-identical
+ * output without the trust.bundle itself ever carrying raw command output (secret-safe by
+ * construction).
+ *
+ * A non-zero exit records status "fail" (never silently swallowed) AND this command itself exits
+ * non-zero — a check that failed to run correctly must be loud, not silently recorded as if
+ * nothing happened.
+ */
+async function recordCheck(p, commandArgv) {
+    const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
+    const slug = taskSlugFor(dir, opt(p, "task-slug"));
+    const ts = opt(p, "timestamp", now());
+    const commandString = opt(p, "command");
+    if (!commandArgv?.length && !commandString)
+        die('record-check requires a command: either `record-check <dir> -- <command...>` or `--command "<shell string>"`');
+    if (commandArgv?.length && commandString)
+        die("record-check: pass the command via EITHER `-- <command...>` OR --command, not both");
+    const repoRoot = findRepoRootFromDir(dir);
+    let displayCommand;
+    let exitCode;
+    let stdout = "";
+    let stderr = "";
+    try {
+        if (commandArgv?.length) {
+            displayCommand = commandArgv.join(" ");
+            const out = execFileSync(commandArgv[0], commandArgv.slice(1), { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 600000 });
+            stdout = out;
+            exitCode = 0;
+        }
+        else {
+            // #412: a --command shell string is validated the same way record-gate-claim's --command
+            // is (single-sourced isRunnableCommandText) — prose does not belong here either.
+            const { isRunnableCommandText } = loadRunnableCommandHelper();
+            if (!isRunnableCommandText(commandString))
+                die(`record-check --command "${commandString}" is not a runnable shell command.`);
+            displayCommand = commandString;
+            const out = execFileSync("bash", ["-lc", commandString], { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 600000 });
+            stdout = out;
+            exitCode = 0;
+        }
+    }
+    catch (err) {
+        const e = err;
+        exitCode = typeof e.status === "number" ? e.status : null;
+        stdout = typeof e.stdout === "string" ? e.stdout : "";
+        stderr = typeof e.stderr === "string" ? e.stderr : (e.message ?? "");
+        displayCommand = commandArgv?.length ? commandArgv.join(" ") : commandString;
+    }
+    // Mirror evidence-capture.js's observeResult(): a clean integer exit code is authoritative
+    // (0 => pass, nonzero => fail); this path always HAS a clean integer exit code because it ran
+    // the command itself (unlike the host-observation path, which sometimes only has failure
+    // indicators). See scripts/hooks/evidence-capture.js's observeResult()/cleanExitCode().
+    //
+    // #362 (Wave 3, AC6): the SAME narrow, two-binary carve-out `runBackstop`/`readCommandLog`
+    // (stop-goal-fit.js) and `observeResult` (evidence-capture.js) already apply — a bare
+    // (non-negated, non-count-asserted, non-chained) `grep`/`diff` invocation that exits EXACTLY
+    // 1 is exit-code-ambiguous (zero matches/no diff could be the author's intended PASS for an
+    // absence check, or an unintended miss for a presence check) — is applied HERE at record time
+    // too, since record-check is the most direct match to the issue's own AC12 field evidence: it
+    // executes the command itself and stamps the resulting status. Exit codes >= 2 are untouched
+    // (still "fail", a real tool error) — the carve-out is exit-code-1-only, never widened.
+    //
+    // There is no "ambiguous" value in the check-status enum (`checkStatuses`,
+    // schemas/workflow-acceptance.schema.json's criteria[].status enum) and none is added here —
+    // per the plan (and ADR 0008/0010 consume-never-fork), the ambiguous case maps onto the
+    // EXISTING "not_verified" status rather than inventing a new enum value that every consumer of
+    // that enum would need auditing for. The distinction from a hard "fail" is carried in the
+    // stderr note and the check summary text, not a new status value.
+    const { isAmbiguousAbsenceCommand } = loadRunnableCommandHelper();
+    const ambiguous = exitCode === 1 && isAmbiguousAbsenceCommand(displayCommand ?? "");
+    const status = exitCode === 0 ? "pass" : (ambiguous ? "not_verified" : "fail");
+    // #270 MEDIUM fix: hash the captured (clamped) output — the digest itself is what gets
+    // persisted onto claim.metadata (below, via buildTrustBundle), NEVER the raw output. This is
+    // secret-safe by construction: even if the executed command's stdout/stderr contained a
+    // credential or token, only its sha256 hex digest ever reaches the trust.bundle (which is
+    // frequently committed/shared), not the text itself. The previous `_output_digest` field held
+    // the raw clamped text under a misleading "digest" name and was never actually persisted
+    // anywhere (dead code) — this replaces it with a REAL digest that IS persisted.
+    const capturedOutput = clampOutput(`${stdout}${stderr ? `
+${stderr}` : ""}`.trim());
+    const outputSha256 = capturedOutput ? createHash("sha256").update(capturedOutput, "utf8").digest("hex") : null;
+    const checkIdRaw = opt(p, "id") || displayCommand;
+    const checkId = checkIdRaw.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "record-check";
+    const summary = opt(p, "summary", `record-check: ${displayCommand}${exitCode !== null ? ` (exit ${exitCode})` : ""}${ambiguous ? " — AMBIGUOUS (bare grep/diff exit 1): NOT_VERIFIED, not silently pass/fail" : ""}`);
+    // #270 follow-up fix (iteration 5, narrowed iteration 6): read the bundle's CURRENT check ids
+    // (and stamp status) BEFORE normalizeCheck runs so a correction of an UNSTAMPED wedged id is
+    // exempted from the reserved gate-claim- prefix rejection, while a brand-new mint of that
+    // shape, OR supersession of a STAMPED (live) gate claim, is still rejected. Reused below (not
+    // re-read) for the compose-safe merge — one readBundleState call.
+    const _existingState = readBundleState(dir);
+    const _existingCheckStampById = existingCheckStampMap(_existingState.checks);
+    // kind:"command" + a real `command` string already derives evidenceType "test_output" via
+    // classifyEvidence in buildTrustBundle — no separate evidenceType input is consumed there.
+    const check = normalizeCheck({
+        id: checkId,
+        kind: "command",
+        status,
+        summary,
+        command: displayCommand,
+    }, false, _existingCheckStampById);
+    if (outputSha256)
+        check._output_sha256 = outputSha256;
+    const _mergedChecks = mergeChecksById(_existingState.checks, [check]);
+    assertBundleWritten(await writeTrustBundle(dir, slug, ts, _mergedChecks, _existingState.criteria, _existingState.critiques));
+    if (ambiguous) {
+        // #362 (AC6): never silent-pass, never hard-fail — a bare grep/diff exit 1 is recorded
+        // "not_verified" (above) and this is surfaced loudly on stderr, but record-check itself
+        // still exits 0: the command DID run (this is not a tool/execution error), and the operator
+        // needs an actionable nudge, not a blocked pipeline. Exit codes >= 2 for grep/diff remain a
+        // hard "fail" via the branch below, unchanged.
+        process.stderr.write(`[record-check] command "${displayCommand}" exited 1 — for bare grep/diff this may mean zero matches/no differences (PASS for an absence check) or an unintended miss (FAIL for a presence check); recorded status: not_verified (ambiguous), not silently pass or fail. Re-record this check as a ${AMBIGUOUS_REMEDIATION_ADVICE} to remove the ambiguity.\n`);
+        return 0;
+    }
+    if (status === "fail") {
+        process.stderr.write(`[record-check] command failed (exit ${exitCode ?? "unknown"}): ${displayCommand}\n${stderr ? `${stderr}\n` : ""}`);
+        return 1;
+    }
+    return 0;
+}
 function diagnostic(dir, code, summary) {
     const payload = { timestamp: now(), code, summary };
     appendJsonl(path.join(dir, "transition-diagnostics.jsonl"), payload);
@@ -2108,6 +2885,7 @@ function diagnostic(dir, code, summary) {
  *   --status <pass|fail|not_verified>  (required)
  *   --summary <text>                   (required)
  *   --expectation <id>                 (optional; auto-resolved when the gate has one entry)
+ *   --route-reason <classifier>        (optional; fail only, interpreted by Flow)
  *   --evidence-json <json>             (optional; structured evidence refs)
  *
  * The producer emits a check of kind="external" targeting the gate expectation's declared
@@ -2135,6 +2913,11 @@ async function recordGateClaim(p) {
         die("--status must be one of: pass, fail, not_verified");
     const summary = opt(p, "summary") || die("--summary is required");
     const expectationId = opt(p, "expectation");
+    const routeReason = opt(p, "route-reason");
+    if (routeReason && statusVal !== "fail")
+        die("--route-reason is only valid with --status fail");
+    if (routeReason && !/^[a-z][a-z0-9_-]*$/.test(routeReason))
+        die("--route-reason must be a lowercase classifier identifier");
     // Resolve the active flow step from current.json. #291 Wave 2 Task 2.1 (§7)/Task 2.2: resolve
     // the CALLING actor's own current-pointer (per-actor-first, legacy-fallback) rather than an
     // unconditional legacy-only read — this is the fix for record-gate-claim's pre-existing (#291
@@ -2145,6 +2928,9 @@ async function recordGateClaim(p) {
     const activeStep = resolveActiveFlowStep(flowAgentsDir, gateClaimActorKey);
     if (!activeStep)
         die("record-gate-claim requires an active flow step in current.json (set via ensure-session --flow-id or advance-state --flow-definition)");
+    if (routeReason && !activeStep.routeBackReasons.includes(routeReason)) {
+        die(`--route-reason "${routeReason}" is not declared by gate "${activeStep.gateId}". Available: ${activeStep.routeBackReasons.join(", ") || "none"}`);
+    }
     const expects = activeStep.gateExpects;
     if (expects.length === 0)
         die(`record-gate-claim: active step "${activeStep.stepId}" gate "${activeStep.gateId}" has no expects[] entries`);
@@ -2176,20 +2962,41 @@ async function recordGateClaim(p) {
         status: statusVal,
         summary,
         _gate_claim_expectation_id: targetExpectation.id,
+        ...(routeReason ? { _gate_claim_route_reason: routeReason } : {}),
     };
     // Include structured evidence refs if provided
     const evidenceRefs = opts(p, "evidence-ref-json").map((v) => validateEvidenceRef(parseJson(v, "--evidence-ref-json"), "--evidence-ref-json"));
     if (evidenceRefs.length > 0) {
         check.artifact_refs = evidenceRefs;
     }
-    const checkNormalized = normalizeCheck(check);
+    // #270(b)/#412: --command gives a gate claim a real, runnable execution.label distinct from
+    // the human --summary prose, so stop-goal-fit.js's bundleClaimedPassCommandChecks section (B)
+    // finds a real command to re-run instead of falling back to fieldOrBehavior (the --summary
+    // prose itself), which it would otherwise execute as a shell command under
+    // FLOW_AGENTS_GOAL_FIT_RECHECK. Validated at record time with the same isRunnableCommandText
+    // heuristic the Stop-hook backstop uses (single-sourced — see loadRunnableCommandHelper).
+    const gateCommand = opt(p, "command");
+    if (gateCommand) {
+        const { isRunnableCommandText } = loadRunnableCommandHelper();
+        if (!isRunnableCommandText(gateCommand))
+            die(`record-gate-claim --command "${gateCommand}" is not a runnable shell command — prose belongs in --summary, which is never executed.`);
+        check.command = gateCommand;
+    }
+    const checkNormalized = normalizeCheck(check, /* allowGateClaimPrefix */ true);
     // WS8 (ADR 0020): honor the accepted-gap waiver flags for a gate claim too.
     const gateWaiver = parseWaiver(p, ts);
     if (gateWaiver)
         checkNormalized._waiver = gateWaiver;
     // Log the targeted gate expectation for transparency (goes to stderr only)
     process.stderr.write(`[record-gate-claim] targeting ${activeStep.stepId}/${activeStep.gateId}/${targetExpectation.id} → claimType=${claimType} subjectType=${subjectType}${gateWaiver ? " (WAIVED accepted_gap)" : ""}\n`);
-    assertBundleWritten(await writeTrustBundle(dir, slug, ts, [checkNormalized], [], [], gateClaimActorKey));
+    // #270: accumulate into the FULL existing bundle state (checks/criteria/critiques) instead of
+    // the prior [checkNormalized], [], [] call, which clobbered every other check/criterion/critique
+    // in the bundle on every gate-claim write (the 21-claims-to-1 wipe). A gate claim against the
+    // SAME expectation id supersedes the earlier check for that expectation (mergeChecksById); a
+    // gate claim against a different expectation is additive.
+    const _existingState = readBundleState(dir);
+    const _mergedChecks = mergeChecksById(_existingState.checks, [checkNormalized]);
+    assertBundleWritten(await writeTrustBundle(dir, slug, ts, _mergedChecks, _existingState.criteria, _existingState.critiques, gateClaimActorKey));
     return 0;
 }
 /**
@@ -2278,6 +3085,8 @@ async function promote(p) {
                 throw err;
             if (err instanceof NotFreshHolderError)
                 throw err;
+            if (err instanceof RepoHeadMismatchError)
+                throw err;
             process.stderr.write(`[promote] WARNING: publish-delivery failed: ${err instanceof Error ? err.message : String(err)}\n`);
         });
     }
@@ -2337,7 +3146,7 @@ async function advanceState(p) {
             // call site ALSO dual-writes the per-actor projection, not only ensure-session's call site —
             // otherwise a session that only ever calls advance-state (never re-running ensure-session)
             // would never get a per-actor current.json mirror for its own FlowDefinition routing keys.
-            writeCurrent(root, dir, timestamp, "workflow-sidecar", "advance-state", flow, stepId, undefined, resolveReadActorKey(p));
+            writeCurrent(root, dir, timestamp, "workflow-sidecar", "advance-state", flow, stepId, resolveReadActorKey(p));
         }
     }
     livenessLifecycle(dir, slug, LIVENESS_TERMINAL.has(status) ? "release" : "heartbeat", timestamp);
@@ -2359,6 +3168,8 @@ async function advanceState(p) {
                 throw err;
             if (err instanceof NotFreshHolderError)
                 throw err;
+            if (err instanceof RepoHeadMismatchError)
+                throw err;
             process.stderr.write(`[advance-state] WARNING: publish-delivery failed: ${err instanceof Error ? err.message : String(err)}\n`);
         });
     }
@@ -2399,10 +3210,13 @@ async function recordCritique(p) {
         return e;
     });
     const critiques = [..._mergedCritiques, critique];
-    // Phase 4c: build bundle from raw inputs; read checks from trust.bundle (evidence.json no longer written).
-    const _critiqueEvChecks = checksFromBundle(dir);
-    const _critiqueAccCriteria = Array.isArray(loadJson(path.join(dir, "acceptance.json")).criteria) ? loadJson(path.join(dir, "acceptance.json")).criteria : [];
-    assertBundleWritten(await writeTrustBundle(dir, slug, critique.reviewed_at, _critiqueEvChecks, _critiqueAccCriteria, critiques));
+    // Phase 4c: build bundle from raw inputs; read checks/criteria via the shared compose-safe
+    // readBundleState path (#270 LOW consolidation) instead of hand-rolling the identical
+    // checksFromBundle + acceptance.json read inline — this is the exact pattern readBundleState
+    // already exists to share; recordLearning uses it directly (see below) and recordCritique
+    // previously duplicated it by hand for no reason.
+    const _critiqueState = readBundleState(dir);
+    assertBundleWritten(await writeTrustBundle(dir, slug, critique.reviewed_at, _critiqueState.checks, _critiqueState.criteria, critiques));
     return 0;
 }
 function frontmatter(text, key) {
@@ -2464,6 +3278,8 @@ async function recordRelease(p) {
             throw err;
         if (err instanceof NotFreshHolderError)
             throw err;
+        if (err instanceof RepoHeadMismatchError)
+            throw err;
         process.stderr.write(`[record-release] WARNING: publish-delivery failed: ${err instanceof Error ? err.message : String(err)}\n`);
     });
     return 0;
@@ -2777,6 +3593,40 @@ export class NotFreshHolderError extends Error {
         this.guidance = result.guidance;
     }
 }
+/**
+ * Distinct, identifiable error for a publish attempt whose resolved `repoRoot` does not
+ * positively confirm the session's sealed `trust.checkpoint.json` `commit_sha` — a FOURTH,
+ * distinct fail-closed tier (#413 Facet A), never conflated with `InvalidBundleShapeError`
+ * (bundle shape) or `NotFreshHolderError` (actor hold). This is the "refuse loudly when the cwd
+ * repo does not match the sealed checkpoint commit_sha" fallback the issue itself proposed:
+ * `publishDelivery`'s `repoRoot` is resolved by walking up from the ARTIFACT directory
+ * (findRepoRootFromDirStrict), which always physically lives under the primary checkout even
+ * when invoked from an unrelated worktree/repo — so a positively-confirmed mismatch here is the
+ * signal that this resolved repoRoot is NOT the repo the sealed checkpoint was produced against,
+ * and publishing into it would silently write to the wrong tree.
+ *
+ * #413 iteration-2 Fix 4: thrown for the ONE positively-determinable `mismatchKind` (see
+ * checkpointHeadAncestry's doc comment) — `"positive"` (repoRoot's HEAD is confirmed NOT an
+ * ancestor-or-equal of commit_sha; `headSha` is a real sha). It is intentionally NEVER thrown for
+ * `"undeterminable-shallow"` (e.g. a shallow clone missing the commit object) — that case only
+ * warns and allows the publish (see publishDelivery's own gate). A non-git `repoRoot` classifies
+ * as `mismatchKind === "none"` (no opinion — allow; see checkpointHeadAncestry's doc comment for
+ * why the iteration-2 Fix 5 refusal here was reverted in iteration-3) and never throws this error
+ * either.
+ */
+export class RepoHeadMismatchError extends Error {
+    code = "PUBLISH_DELIVERY_REPO_HEAD_MISMATCH";
+    repoRoot;
+    commitSha;
+    headSha;
+    constructor(repoRoot, commitSha, headSha) {
+        super(`publish-delivery refused — resolved repoRoot '${repoRoot}' HEAD '${headSha}' is not an ancestor-or-equal of the sealed trust.checkpoint.json commit_sha '${commitSha}'. This usually means repoRoot was resolved to the wrong checkout (e.g. invoked from a worktree whose artifact dir physically lives under a different primary checkout), or repoRoot is not a valid git working tree at all. Pass --repo-root explicitly naming the checkout whose HEAD matches '${commitSha}', or re-seal the checkpoint (seal-checkpoint) against this repoRoot's current HEAD if this really is the intended target.`);
+        this.name = "RepoHeadMismatchError";
+        this.repoRoot = repoRoot;
+        this.commitSha = commitSha;
+        this.headSha = headSha;
+    }
+}
 /**
  * Human-actionable fix text per divergence type (Q2: unwaived-assumed's message always
  * carries the "waiver voided by a mixed record-evidence call" root-cause hint — shape #5 is
@@ -2805,34 +3655,139 @@ function preflightFixHint(type) {
     }
 }
 /**
- * F4 (iteration-1): extracted from runReconcilePreflight so the main function stays under
- * the 50-line guideline. Q3 (optional, non-blocking): warn if the checkpoint's commit_sha is
- * not yet an ancestor of local HEAD — never affects ok/exit code, best-effort only. Already a
- * self-contained try/catch with no effect on the caller's `ok`/`issues`.
+ * Callable core shared by BOTH the `reconcile-preflight` CLI handler and
+ * publishDelivery()'s fail-closed gate (#356 Wave 3) — one implementation, not two entry
+ * points that could drift. SHAPE-only: never spawns a fresh manifest/CI command (AC5) — the
+ * only subprocess calls here are the already-cheap run-baseline.sh --manifest-json static
+ * registry emit (inside resolveManifest, reused unchanged from trust-reconcile.js) and the
+ * local-only derive-claim-status.mjs re-derivation (no CI command execution either).
+ *
+ * @param dir artifact/session directory containing trust.bundle
+ * @param repoRoot repo root used for manifest resolution + the optional ancestor warning
+ * @param manifestOverride optional --manifest JSON string (CLI passthrough)
  */
-function checkpointStalenessWarning(dir, repoRoot, tr) {
-    const warnings = [];
+/**
+ * #413 Facet A: best-effort single-direction ancestor check scoped to the specific needs of
+ * checkpointHeadAncestry's hard-refuse gate — is `ancestorSha` positively determinable as an
+ * ancestor of (or equal to) `descendantSha` in `repoRoot`, OR positively determinable as NOT an
+ * ancestor, OR is the question simply UNDETERMINABLE here (shallow clone missing the object,
+ * unknown/garbage sha, git itself unusable, etc.)? This is intentionally a SEPARATE, local
+ * classification from `trust-reconcile.js`'s shared `isAncestorCommit()` (which the rest of the
+ * repo, including checkpointStalenessWarning's own non-blocking warning below, correctly keeps
+ * as a simple best-effort boolean that "fails toward false/stale" for every non-CI caller) —
+ * that collapsed boolean is exactly right for a WARNING, but wrong for a HARD REFUSE gate: a
+ * shallow clone's git-object-missing failure and a genuine cross-repo mismatch both surface as
+ * `false` there, yet only the second is real harm (#413 iteration-2 Fix 4). `git merge-base
+ * --is-ancestor` itself already distinguishes these at the exit-code level (0 = ancestor, 1 =
+ * positively NOT an ancestor, anything else / a spawn failure = underivable), so this reuses
+ * that primitive directly rather than duplicating trust-reconcile.js's collapsed wrapper.
+ */
+function classifyAncestry(repoRoot, ancestorSha, descendantSha) {
+    if (!ancestorSha || !descendantSha)
+        return "undeterminable";
+    try {
+        const res = spawnSync("git", ["merge-base", "--is-ancestor", ancestorSha, descendantSha], {
+            cwd: repoRoot,
+            stdio: "ignore",
+        });
+        if (!res || res.error)
+            return "undeterminable";
+        if (res.status === 0)
+            return "ancestor";
+        if (res.status === 1)
+            return "not-ancestor";
+        return "undeterminable"; // e.g. 128 (unknown commit, shallow clone missing the object, etc.)
+    }
+    catch {
+        return "undeterminable";
+    }
+}
+/**
+ * #413 Facet A: read `trust.checkpoint.json`'s `commit_sha` (if the checkpoint exists and
+ * carries one) and resolve `git rev-parse HEAD` with an EXPLICIT `{ cwd: repoRoot }` (never the
+ * bare no-cwd pattern `resolveCommitSha()` uses — see that function's own doc comment for why
+ * that variant is intentionally cwd-inheriting for the seal-checkpoint path, and must not be
+ * reused here). Returns `{ commitSha: null }` when there is no checkpoint or no commit_sha yet
+ * (a session with nothing sealed has nothing to compare against — callers must treat this as
+ * "no opinion", never as a mismatch). Returns `{ commitSha, headSha, isAncestor }` when both
+ * shas are resolvable. This is the ONE shared comparison both `checkpointStalenessWarning`
+ * (non-blocking) and `publishDelivery`'s hard refuse gate (fail-closed) call — never a second,
+ * independently-drifting git shell-out.
+ *
+ * #413 iteration-2 Fix 4 (scoped to the hard-refuse tier ONLY — checkpointStalenessWarning's
+ * non-blocking warning is intentionally unaffected, see its own doc comment): the returned
+ * `isAncestor` stays a simple boolean (`true` unless POSITIVELY determined false) for backward
+ * compatibility with that warning caller, but the `mismatchKind` field lets publishDelivery's
+ * hard gate distinguish these cases precisely:
+ *   - "none": no checkpoint, no commit_sha, `repoRoot` is not a git working tree at all (or is a
+ *     freshly-initialized repo with no resolvable HEAD), or the commit_sha IS an
+ *     ancestor-or-equal of HEAD — never refuse. A non-git `repoRoot` is a SUPPORTED flow (e.g.
+ *     checkpoint-signing against a bare scratch dir — see evals/integration/test_checkpoint_signing.sh
+ *     TEST 2), not a mismatch signal: there is no HEAD to compare against, so this is "no
+ *     opinion", exactly like the no-checkpoint case above.
+ *   - "positive": repoRoot is a real git working tree, HEAD resolves, AND commit_sha is
+ *     POSITIVELY determined to NOT be an ancestor of HEAD (`git merge-base --is-ancestor` exits
+ *     1, a real answer, not a failure) — the genuine wrong-tree harm case; hard refuse.
+ *   - "undeterminable-shallow": repoRoot is a real git working tree, HEAD resolves, but whether
+ *     commit_sha is an ancestor of HEAD could not be determined (e.g. a shallow clone missing
+ *     the commit_sha object) — must NOT hard-refuse a legitimate publish from a shallow clone;
+ *     warn loudly and allow (the shape + verify-hold gates still stand).
+ *
+ * #413 iteration-2 Fix 5 (reverted, iteration-3): a prior pass hard-refused here when `repoRoot`
+ * was not a git working tree at all but a sealed commit_sha existed ("a sealed delivery implies
+ * the target should be a real git repo"). That premise is false — publishing against a non-git
+ * `repoRoot` is a supported scratch/checkpoint-signing flow, and the refusal regressed
+ * `evals/integration/test_checkpoint_signing.sh` TEST 2. The accepted residual: a non-git
+ * `repoRoot` with a sealed checkpoint is ALLOWED here; wrong-tree protection for a REAL git
+ * repoRoot relies on this function's ancestry (HEAD-vs-commit_sha) check plus the shape-check and
+ * verify-hold gates in publishDelivery, all of which correctly no-op (allow) when there is no git
+ * HEAD to compare against.
+ */
+function checkpointHeadAncestry(dir, repoRoot) {
     try {
         const checkpointPath = path.join(dir, "trust.checkpoint.json");
-        if (fs.existsSync(checkpointPath)) {
-            const checkpoint = loadJson(checkpointPath);
-            const commitSha = checkpoint && typeof checkpoint === "object" ? checkpoint.commit_sha : undefined;
-            if (typeof commitSha === "string" && commitSha) {
-                let headSha = "";
-                try {
-                    headSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-                }
-                catch {
-                    headSha = "";
-                }
-                if (headSha && !tr.isAncestorCommit(repoRoot, commitSha, headSha)) {
-                    warnings.push(`NON-BLOCKING: trust.checkpoint.json commit_sha '${commitSha}' is not an ancestor of local HEAD '${headSha}' — the checkpoint may be stale (e.g. after an amend/rebase). Consider re-sealing (seal-checkpoint) before publishing. This is a warning only — see #335 for the full checkpoint-staleness ownership check.`);
-                }
-            }
+        if (!fs.existsSync(checkpointPath))
+            return { commitSha: null, headSha: null, isAncestor: true, mismatchKind: "none" };
+        const checkpoint = loadJson(checkpointPath);
+        const commitSha = checkpoint && typeof checkpoint === "object" ? checkpoint.commit_sha : undefined;
+        if (typeof commitSha !== "string" || !commitSha)
+            return { commitSha: null, headSha: null, isAncestor: true, mismatchKind: "none" };
+        let headSha = "";
+        try {
+            headSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        }
+        catch {
+            headSha = "";
         }
+        // repoRoot is not a git working tree at all (non-git scratch dir) or is a freshly-initialized
+        // repo with no resolvable HEAD yet — "no opinion", never a mismatch (see doc comment above).
+        if (!headSha)
+            return { commitSha, headSha: null, isAncestor: true, mismatchKind: "none" };
+        const classification = classifyAncestry(repoRoot, commitSha, headSha);
+        const isAncestor = classification !== "not-ancestor";
+        const mismatchKind = classification === "ancestor" ? "none" : classification === "not-ancestor" ? "positive" : "undeterminable-shallow";
+        return { commitSha, headSha, isAncestor, mismatchKind };
     }
     catch {
-        // best-effort only — never affects ok/exit code.
+        // best-effort only — a resolution failure must never be misread as a mismatch.
+        return { commitSha: null, headSha: null, isAncestor: true, mismatchKind: "none" };
+    }
+}
+/**
+ * F4 (iteration-1): extracted from runReconcilePreflight so the main function stays under
+ * the 50-line guideline. Q3 (optional, non-blocking): warn if the checkpoint's commit_sha is
+ * not yet an ancestor of local HEAD — never affects ok/exit code, best-effort only. Delegates
+ * to checkpointHeadAncestry (the shared comparison helper #413 Facet A's hard gate also uses)
+ * so the warning path and the hard-refuse path can never independently drift. #413 iteration-2:
+ * intentionally keeps using the plain `isAncestor` boolean (never `mismatchKind`) — a shallow
+ * clone's undeterminable case still deserves this SAME staleness-flavored warning text, it just
+ * must never become a hard refuse (see publishDelivery's own gate for that distinction).
+ */
+function checkpointStalenessWarning(dir, repoRoot) {
+    const warnings = [];
+    const { commitSha, headSha, isAncestor } = checkpointHeadAncestry(dir, repoRoot);
+    if (commitSha && headSha && !isAncestor) {
+        warnings.push(`NON-BLOCKING: trust.checkpoint.json commit_sha '${commitSha}' is not an ancestor of local HEAD '${headSha}' — the checkpoint may be stale (e.g. after an amend/rebase). Consider re-sealing (seal-checkpoint) before publishing. This is a warning only — see #335 for the full checkpoint-staleness ownership check.`);
     }
     return warnings;
 }
@@ -2873,7 +3828,7 @@ export function runReconcilePreflight(dir, repoRoot, manifestOverride) {
     const { issues: sessionLocalIssues } = shape.sessionLocalShapeIssues(sessionLocal, derivedStatus, { onUnderivable: "reduce" });
     issues.push(...sessionLocalIssues);
     const report = issues.map((i) => `${i.message} — ${preflightFixHint(i.type)}`);
-    const warnings = checkpointStalenessWarning(dir, repoRoot, tr);
+    const warnings = checkpointStalenessWarning(dir, repoRoot);
     return { ok: report.length === 0, issues: report, warnings };
 }
 /**
@@ -3329,52 +4284,47 @@ async function takeoverPreflightCmd(p) {
 // Called automatically from recordRelease and advanceState→delivered (best-effort).
 // Also exposed as the `publish-delivery <artifact-dir>` subcommand for explicit use.
 /**
- * #379 supersede-on-publish cleanup: keep delivery/ bounded by pruning inherited PER-SESSION
- * seal dirs (the growth vector), scoped to avoid any cross-PR conflict.
+ * #413 Facet B: prune ONLY keepSlug's OWN prior seal — NEVER another session's
+ * `delivery/<other-slug>/` directory.
  *
- * An inherited per-session seal dir (`delivery/<other-slug>/`) is UNIQUELY named, so pruning
- * it can never conflict with a concurrent PR: two branches deleting the same inherited dir is
- * a delete/delete (auto-merges), and each new delivery adds its OWN distinct
- * `delivery/<slug>/`. And it is HARMLESS to leave: trust-reconcile.js's prefer-newest
- * ownership selection always picks THIS session's fresher bundle over an older inherited one.
- * Pruning is therefore purely to stop unbounded accumulation of permanently-superseded dirs.
+ * This function previously (#379) deleted ANY non-keepSlug directory under delivery/ that
+ * "looked like a seal" (contained a trust.bundle or trust.checkpoint.json), on the theory that
+ * an inherited per-session seal dir is harmless to leave and therefore harmless to delete too.
+ * That theory was correct about harmlessness-if-left but did not follow that deletion was
+ * therefore SAFE: issue #413's own corrected evidence reports this exact cross-slug loop
+ * deleted a DIFFERENT, still-in-flight actor's active seal on a different branch
+ * (`delivery/kontourai-flow-agents-349/`) — a real, observed destructive side effect with no
+ * compensating correctness benefit. trust-reconcile.js's own PREFER-NEWEST doc comment
+ * (resolveDeliveryCandidates, ~line 480-491) already establishes that leaving an
+ * inherited/older seal in place is harmless — the reconciler always selects the newest owning
+ * bundle regardless of what else is present — so there is no correctness reason to prune
+ * ANOTHER session's seal at all, ever. The safest fix (and the one issue #413's own corrected
+ * comment endorses — "never prune another session's active seal", no same-branch carve-out) is
+ * to stop cross-slug pruning entirely, not merely narrow its blast radius.
  *
- * The SHARED FLAT path (`delivery/trust.bundle` + checkpoints) is deliberately NOT pruned
- * here. During the migration window other concurrent PRs may still seal to the flat path;
- * deleting it would produce a modify/delete conflict → a DIRTY PR → the no-CI failure this
- * whole change fixes. The flat path is a single fixed location (not a growth vector) and the
- * reconciler treats a stale flat bundle as non-owning / older-owning, so leaving it is safe.
- * Removing the flat legacy seals is a one-time cleanup for a dedicated PR once no open PR
- * still seals to it — intentionally NOT bundled into every delivery.
+ * The only pruning responsibility that legitimately remains here is keepSlug's OWN prior seal:
+ * publishDelivery() is about to freshly (re)write `delivery/<keepSlug>/trust.bundle` and its
+ * companions, but `fs.copyFileSync` only overwrites files that exist in the CURRENT session dir
+ * — a companion that existed in a PRIOR publish of this exact slug (e.g.
+ * trust.checkpoint.sig.json) but is absent from this publish would otherwise linger stale
+ * alongside the freshly-written files. Removing keepSlug's own existing directory before it is
+ * recreated (by the caller, immediately after this call) avoids that same-slug staleness
+ * without touching any OTHER slug's directory.
  *
  * Best-effort: a prune failure is logged, never fatal to the delivery. Never touches
- * README.md, DECLARED, the flat seal files, or any subdir that is not itself a seal dir.
+ * README.md, DECLARED, the flat seal files (delivery/trust.bundle at the shared flat path,
+ * deliberately untouched — see the historical #379 rationale on the flat-path migration
+ * window), or any directory other than keepSlug's own.
  */
 function pruneSupersededSeals(deliveryDir, keepSlug) {
-    let entries = [];
+    const ownDir = path.join(deliveryDir, keepSlug);
+    if (!fs.existsSync(ownDir))
+        return; // nothing to prune yet — first publish for this slug.
     try {
-        entries = fs.readdirSync(deliveryDir, { withFileTypes: true });
+        fs.rmSync(ownDir, { recursive: true, force: true });
     }
-    catch {
-        entries = [];
-    }
-    for (const entry of entries) {
-        if (!entry.isDirectory() || entry.name === keepSlug)
-            continue;
-        const subdir = path.join(deliveryDir, entry.name);
-        // Only prune dirs that actually look like a seal dir (contain a trust.bundle or
-        // trust.checkpoint.json) — never an unrelated directory a human placed under delivery/.
-        const looksLikeSeal = fs.existsSync(path.join(subdir, "trust.bundle")) ||
-            fs.existsSync(path.join(subdir, "trust.checkpoint.json"));
-        if (!looksLikeSeal)
-            continue;
-        try {
-            fs.rmSync(subdir, { recursive: true, force: true });
-            process.stderr.write(`[publish-delivery] #379: pruned superseded per-session seal delivery/${entry.name}/ (older-owning/stale; the reconciler selects the newest bundle regardless)\n`);
-        }
-        catch (err) {
-            process.stderr.write(`[publish-delivery] #379: could not prune per-session seal delivery/${entry.name}/ (non-fatal): ${err instanceof Error ? err.message : String(err)}\n`);
-        }
+    catch (err) {
+        process.stderr.write(`[publish-delivery] #413: could not prune this session's own prior seal delivery/${keepSlug}/ before rewriting it (non-fatal, publish continues): ${err instanceof Error ? err.message : String(err)}\n`);
     }
 }
 /**
@@ -3413,17 +4363,44 @@ function pruneSupersededSeals(deliveryDir, keepSlug) {
  * which stay exactly as before (see each publishDelivery call site's catch handler for how
  * the distinction is preserved end-to-end).
  *
- * #293 (SECOND, DISTINCT fail-closed gate): immediately after the shape check above and BEFORE
+ * #293 (THIRD, DISTINCT fail-closed gate): immediately after the shape check above and BEFORE
  * writing anything into delivery/, runs `runVerifyHold()` — the assignment ⋈ liveness join
  * asking "is the calling actor the fresh, non-superseded holder of this subject (or is it
  * free/self-held)?" A not-fresh-holder result throws `NotFreshHolderError` (distinct from
  * `InvalidBundleShapeError` — a different `code`, a different failure mode: actor hold vs
- * bundle shape). There are now THREE tiers here, and they must never be conflated in prose or
- * in a call site's catch handler: (1) fail-SOFT bundle absence / repo-root resolution (silent
- * no-op / visible warning, unchanged from before #356), (2) fail-CLOSED bundle shape (#356,
- * `InvalidBundleShapeError`), (3) fail-CLOSED verify-hold (#293, `NotFreshHolderError`). The
- * shape check runs first (per the plan's ordering) — a bundle that is BOTH shape-invalid and
- * not-held throws `InvalidBundleShapeError` specifically, never `NotFreshHolderError`.
+ * bundle shape).
+ *
+ * #413 Facet A (FOURTH, DISTINCT fail-closed gate): immediately after the verify-hold gate and
+ * BEFORE writing anything into delivery/, compares the resolved `repoRoot`'s `git rev-parse
+ * HEAD` against the session's sealed `trust.checkpoint.json` `commit_sha` (via the shared
+ * checkpointHeadAncestry() helper — the SAME ancestor-check checkpointStalenessWarning already
+ * used as a non-blocking warning). Throws `RepoHeadMismatchError` (distinct from both other
+ * error tiers) instead of silently publishing into what is very likely the WRONG repo (e.g.
+ * `repoRoot` resolved to the primary checkout via findRepoRootFromDirStrict's artifact-dir
+ * walk, even though this session's checkpoint was sealed against a DIFFERENT worktree's HEAD).
+ * A session with no checkpoint yet, or a checkpoint with no commit_sha, has nothing to compare
+ * against and is unaffected (scoped strictly to the mismatch case, never a spurious refusal).
+ *
+ * #413 iteration-2 Fix 4 (see checkpointHeadAncestry's own doc comment for the full
+ * `mismatchKind` classification this gate reads): only `mismatchKind === "positive"` (a
+ * POSITIVELY-DETERMINABLE ancestry mismatch — the real wrong-tree harm case) hard refuses here.
+ * `"undeterminable-shallow"` (e.g. a local shallow clone missing the commit_sha object) must
+ * NEVER hard-refuse a legitimate publish — this branch only WARNS loudly and lets the shape +
+ * verify-hold gates above continue to stand guard. A non-git `repoRoot` classifies as
+ * `mismatchKind === "none"` (allow) — iteration-2's Fix 5 hard-refused this case too, but that
+ * regressed the SUPPORTED non-git-repoRoot scratch/checkpoint-signing flow (see
+ * evals/integration/test_checkpoint_signing.sh TEST 2) and was reverted in iteration-3. Wrong-tree
+ * protection for that case relies on the shape-check and verify-hold gates above, which correctly
+ * no-op (allow) when there is no git repo to inspect, same as this gate.
+ *
+ * There are now FOUR fail-closed/fail-soft TIERS in this function, and they must never be
+ * conflated in prose or in a call site's catch handler: (1) fail-SOFT bundle absence /
+ * repo-root resolution (silent no-op / visible warning, unchanged from before #356), (2)
+ * fail-CLOSED bundle shape (#356, `InvalidBundleShapeError`), (3) fail-CLOSED verify-hold (#293,
+ * `NotFreshHolderError`), (4) fail-CLOSED repo-HEAD-vs-checkpoint mismatch (#413 Facet A,
+ * `RepoHeadMismatchError`) — see this tier's own gate below for the undeterminable-shallow
+ * carve-out. Tiers run in this fixed order (shape, then verify-hold, then HEAD-mismatch); a
+ * bundle that fails an earlier tier throws that tier's error specifically, never a later one's.
  */
 export async function publishDelivery(dir, repoRoot) {
     const bundleSrc = path.join(dir, "trust.bundle");
@@ -3433,10 +4410,8 @@ export async function publishDelivery(dir, repoRoot) {
         process.stderr.write(`[publish-delivery] WARNING: no kits/ ancestor found from ${dir}; skipping publish. Refusing to fall back to process.cwd() to avoid clobbering an unrelated repo's delivery/ seal. Pass --repo-root explicitly if this session dir is intentionally outside a repo checkout.\n`);
         return;
     }
-    // #356 AC6: fail-CLOSED on shape-invalidity — runs AFTER the fail-soft absence/repo-root
-    // guards above (both preserved unchanged) and BEFORE any copy into delivery/. Throws
-    // InvalidBundleShapeError (never a generic Error) so every call site can positively
-    // distinguish this from the failure modes they already tolerate as best-effort.
+    // #356 AC6: fail-CLOSED on shape-invalidity — TIER 2 (see this function's doc comment above
+    // for the full tier ordering). Throws InvalidBundleShapeError (never a generic Error).
     const preflight = runReconcilePreflight(dir, repoRoot);
     if (!preflight.ok) {
         process.stderr.write(`[publish-delivery] REFUSING to publish — trust.bundle failed the reconcile-preflight shape check (${preflight.issues.length} issue(s)):\n`);
@@ -3445,10 +4420,8 @@ export async function publishDelivery(dir, repoRoot) {
         }
         throw new InvalidBundleShapeError(preflight.issues);
     }
-    // #293: SECOND, DISTINCT fail-closed gate — runs after the shape check above and before any
-    // copy into delivery/. Throws NotFreshHolderError (never conflated with InvalidBundleShapeError)
-    // so every call site can positively distinguish "not the fresh holder" from "bundle shape
-    // invalid".
+    // #293: fail-CLOSED verify-hold — TIER 3 (see this function's doc comment above). Throws
+    // NotFreshHolderError (never conflated with InvalidBundleShapeError).
     const holdCheck = runVerifyHold(dir, repoRoot);
     if (!holdCheck.ok) {
         process.stderr.write(`[publish-delivery] REFUSING to publish — verify-hold gate: ${holdCheck.reason}\n`);
@@ -3456,6 +4429,20 @@ export async function publishDelivery(dir, repoRoot) {
             process.stderr.write(`[publish-delivery]   - ${line}\n`);
         throw new NotFreshHolderError(holdCheck);
     }
+    // #413 Facet A: FOURTH, DISTINCT fail-closed gate (see this function's doc comment above for
+    // the full four-tier ordering, and checkpointHeadAncestry's doc comment for the
+    // Fix 4 mismatchKind classification this reads).
+    const ancestry = checkpointHeadAncestry(dir, repoRoot);
+    if (ancestry.mismatchKind === "positive" && ancestry.commitSha && ancestry.headSha) {
+        process.stderr.write(`[publish-delivery] REFUSING to publish — resolved repoRoot '${repoRoot}' HEAD '${ancestry.headSha}' is not an ancestor-or-equal of the sealed trust.checkpoint.json commit_sha '${ancestry.commitSha}'. This resolved repoRoot is very likely the WRONG checkout for this session (e.g. invoked from a worktree whose artifact dir physically lives under a different primary checkout). Pass --repo-root explicitly, or re-seal the checkpoint against this repoRoot if it really is the intended target.\n`);
+        throw new RepoHeadMismatchError(repoRoot, ancestry.commitSha, ancestry.headSha);
+    }
+    if (ancestry.mismatchKind === "undeterminable-shallow" && ancestry.commitSha && ancestry.headSha) {
+        // #413 iteration-2 Fix 4: NEVER hard-refuse here — a shallow clone (or any other case where
+        // git cannot positively determine ancestry) must not spuriously block a legitimate publish.
+        // The shape + verify-hold gates above already ran and passed; this is warn-and-allow only.
+        process.stderr.write(`[publish-delivery] WARNING: could not determine whether trust.checkpoint.json commit_sha '${ancestry.commitSha}' is an ancestor of repoRoot '${repoRoot}' HEAD '${ancestry.headSha}' (e.g. a shallow clone missing the commit object) — allowing the publish since this is UNDETERMINABLE, not a positively-confirmed mismatch. The shape and verify-hold gates already passed.\n`);
+    }
     const deliveryDir = path.join(repoRoot, "delivery");
     // #379: slug is the session artifact dir's basename — the same human-meaningful id used
     // throughout the session (.kontourai/flow-agents/<slug>/). The per-session dir NAME is only
@@ -3463,7 +4450,8 @@ export async function publishDelivery(dir, repoRoot) {
     const slug = path.basename(path.resolve(dir));
     const sessionDeliveryDir = path.join(deliveryDir, slug);
     fs.mkdirSync(deliveryDir, { recursive: true });
-    // Supersede inherited/flat seals BEFORE writing this session's dir (keepSlug = our own).
+    // #413 Facet B: prune only THIS session's own prior seal (never another slug's) before
+    // freshly rewriting delivery/<slug>/ below.
     pruneSupersededSeals(deliveryDir, slug);
     fs.mkdirSync(sessionDeliveryDir, { recursive: true });
     // Required: trust.bundle (the CI anchor)
@@ -3569,12 +4557,13 @@ async function recordLearning(p) {
         die("learning status learned requires every record to include correction.needed");
     writeJson(path.join(dir, "learning.json"), { ...sidecarBase(slug), status, updated_at: timestamp, records });
     writeState(dir, slug, "accepted", "learning", timestamp, opt(p, "summary"));
-    // Phase 4c: build bundle from raw inputs; read checks/critiques from trust.bundle (bespoke sidecars no longer written).
+    // Phase 4c: build bundle from raw inputs; read checks/criteria/critiques via the shared
+    // compose-safe readBundleState path (#270 LOW consolidation — this was the literal inline
+    // pattern readBundleState was extracted FROM; using the shared helper directly keeps the two
+    // from silently drifting apart in the future).
     // #268/#344: declared builder.* claims survive the round-trip via their authoritative origin stamp.
-    const _learningChecks = checksFromBundle(dir);
-    const _learningCriteria = Array.isArray(loadJson(path.join(dir, "acceptance.json")).criteria) ? loadJson(path.join(dir, "acceptance.json")).criteria : [];
-    const _learningCritiques = critiquesFromBundle(dir);
-    assertBundleWritten(await writeTrustBundle(dir, slug, timestamp, _learningChecks, _learningCriteria, _learningCritiques));
+    const _learningState = readBundleState(dir);
+    assertBundleWritten(await writeTrustBundle(dir, slug, timestamp, _learningState.checks, _learningState.criteria, _learningState.critiques));
     return 0;
 }
 function evidenceClean(dir) {
@@ -3656,7 +4645,16 @@ async function dogfoodPass(p) {
     assertExistingLearningValid(dir);
     const verdict = opt(p, "verdict");
     if (verdict === "pass") {
-        const checks = opts(p, "check-json").map((v) => normalizeCheck(parseJson(v, "--check-json")));
+        // #270 follow-up fix (iteration 5, narrowed iteration 6): dogfood-pass's own pre-validation
+        // normalizeCheck call (before delegating the actual write to recordEvidence below) must apply
+        // the same narrowed existing-unstamped-id exemption recordEvidence/recordCheck do, or a
+        // legitimate correction of a mis-recorded, UNSTAMPED gate-claim-* id would die HERE, before
+        // ever reaching recordEvidence's own (already-fixed) guard — while supersession of a STAMPED
+        // (live) gate claim id must still die here too. readBundleState is safe to call even when
+        // trust.bundle does not yet exist (loadJson falls back to {}), exactly as
+        // recordEvidence/recordCheck rely on.
+        const _dogfoodExistingCheckStampById = existingCheckStampMap(readBundleState(dir).checks);
+        const checks = opts(p, "check-json").map((v) => normalizeCheck(parseJson(v, "--check-json"), false, _dogfoodExistingCheckStampById));
         if (checks.some((c) => c.status !== "pass" && c.status !== "skip"))
             die("clean evidence requires all non-skipped checks to pass");
         // Phase 4c: evidence check reads from trust.bundle (sole verification artifact); legacy evidence.json fallback in evidenceClean.
@@ -4672,9 +5670,27 @@ Available claim ids:
 }
 // ─────────────────────────────────────────────────────────────────────────────
 async function main() {
-    const p = parseArgs(process.argv.slice(2));
+    const _rawArgv = process.argv.slice(2);
+    // #380: `record-check <dir> -- <command...>` — argv after the FIRST literal `--` token is the
+    // command to execute verbatim (never option-parsed: a command like `npm test -- --watch`
+    // legitimately contains its OWN `--`, so only the record-check dispatcher's own separator, the
+    // first one, is consumed here). parseArgs() cannot represent this (it treats every `--foo`-
+    // shaped token as an option key, including a bare `--`), so the split happens here, before
+    // parseArgs ever sees the command's own argv.
+    let _commandArgv = null;
+    let _argvForParse = _rawArgv;
+    if (_rawArgv[0] === "record-check") {
+        const sepIdx = _rawArgv.indexOf("--");
+        if (sepIdx >= 0) {
+            _argvForParse = _rawArgv.slice(0, sepIdx);
+            _commandArgv = _rawArgv.slice(sepIdx + 1);
+        }
+    }
+    const p = parseArgs(_argvForParse);
     if (!p.command)
         die("workflow-sidecar command is required");
+    if (p.command === "ensure-session")
+        preflightEnsureSession(p);
     // F1 (#166 fix iteration 1): `liveness whoami` is a read-only, lock-free, write-free advisory
     // surface (see the `action === "whoami"` branch inside `liveness()` above) — it must never
     // acquire the workflow-sidecar lock, regardless of whether the artifact root already exists on
@@ -4701,6 +5717,7 @@ async function main() {
             case "init-plan": return initPlan(p);
             case "record-evidence": return recordEvidence(p);
             case "record-gate-claim": return recordGateClaim(p);
+            case "record-check": return recordCheck(p, _commandArgv);
             case "promote": return promote(p);
             case "advance-state": return advanceState(p);
             case "record-critique": return recordCritique(p);