@kontourai/flow-agents 3.2.0 → 3.4.0

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. */
@@ -230,9 +257,17 @@ function resolveEnsureSessionActor(p) {
         // the ownership guard entirely when unresolved, rather than claiming under a synthetic identity.
         return { actorStruct: { runtime: "unresolved", session_id: branchActorKey, host: os.hostname() }, actorKey: resolved.actor, branchActorKey, unresolved: true };
     }
+    // #398: the CI-runtime tier must reconstruct the SAME struct resolveActor serialized, or
+    // `serializeActor(actorStruct)` would diverge from `resolved.actor` (the else-branch would rebuild
+    // an ANCESTRY struct — detectRuntime→unknown, runtimeSessionId→'' — so the claim's stored
+    // actor_key would not match the CI actor at publish → self not recognized → false-block, the exact
+    // bug this issue removes). Uses the SAME helper.detectCiActor as resolveActor, single-sourced.
+    const ciActor = resolved.source.startsWith("ci-runtime") ? helper.detectCiActor(process.env) : null;
     const actorStruct = resolved.source === "explicit-override"
         ? { runtime: "explicit-override", session_id: resolved.actor, host: os.hostname() }
-        : { runtime: helper.detectRuntime(process.env), session_id: helper.runtimeSessionId(process.env) || (() => { const seed = helper.ancestorActorSeed(); return seed ? `anc-${seed}` : ""; })(), host: os.hostname() };
+        : ciActor && ciActor.session_id
+            ? { runtime: ciActor.runtime, session_id: ciActor.session_id, host: os.hostname() }
+            : { runtime: helper.detectRuntime(process.env), session_id: helper.runtimeSessionId(process.env) || (() => { const seed = helper.ancestorActorSeed(); return seed ? `anc-${seed}` : ""; })(), host: os.hostname() };
     const actorKey = helper.serializeActor(actorStruct);
     return { actorStruct, actorKey, branchActorKey, unresolved: false };
 }
@@ -463,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).
@@ -490,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 = [];
@@ -520,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
@@ -650,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 };
@@ -684,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 });
         }
@@ -720,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 });
         }
@@ -744,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.
@@ -840,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) {
@@ -1079,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; }
@@ -1205,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
@@ -1214,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.
@@ -1233,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)) {
@@ -1316,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
@@ -1347,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 },
     });
@@ -1418,6 +1764,11 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution) {
     // assignment-provider.ts's sanitizeAuditEntryForDisplay) — this guard never echoes `--reason`
     // into a die() message, so it has no free-text field requiring the 240 tier today.
     const sanitize = (value) => stripControlCharsForDisplay(value).slice(0, 64);
+    // #294: the 240-char free-text tier (repo convention: 64 for id-like, 240 for free text — cf.
+    // assignment-provider.ts sanitizeDisplayField(record.branch/reason, 240)). Used for the takeover
+    // `resumed_branch` (a realistic agent/<actor>/<slug> branch exceeds 64 — truncation would produce a
+    // bad `git checkout` target) and the audit `reason` (else "resuming from trust bundle" is cut off).
+    const sanitizeWide = (value) => stripControlCharsForDisplay(value).slice(0, 240);
     const nowMs = opt(p, "now") ? Date.parse(opt(p, "now")) : Date.now();
     const assignmentProviderKind = opt(p, "assignment-provider", "local-file");
     let effective;
@@ -1496,15 +1847,32 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution) {
             const fromActor = assignment.record?.actor;
             if (!fromActor)
                 die(`ensure-session --supersede-stale: no existing local-file claim record found for subject ${sanitize(slug)} to supersede`);
+            // #294 (ADR 0021 §5): takeover is resumption — the successor CONTINUES the incumbent's branch,
+            // never a parallel one. Capture the incumbent's branch (from its pre-supersede record) and
+            // surface it as `resumed_branch` so the skill can `git checkout` it; default the audit reason to
+            // the ADR §5 wording (superseded actor X, last seen T, resuming from trust bundle).
+            const incumbentBranch = assignment.record?.branch;
+            const incumbentLastSeen = effective.holder?.last_at ?? assignment.record?.claimed_at;
+            const takeoverReason = opt(p, "reason") || `takeover: superseded ${holderActor}${incumbentLastSeen ? `, last seen ${sanitize(incumbentLastSeen)}` : ""}, resuming from trust bundle`;
             performLocalSupersede(root, slug, fromActor, resolution.actorStruct, {
-                branch: resolveBranchForClaim(),
+                // #294 (ADR 0021 §5): takeover is RESUMPTION — the successor continues the incumbent's branch,
+                // so the record must keep pointing at that branch, NOT be overwritten with the successor's
+                // current branch (`resolveBranchForClaim()`). At supersede time the successor has not yet
+                // `git checkout`ed the resume branch (the skill claims ownership first, then checks out), so
+                // resolveBranchForClaim() would otherwise clobber the record with a parallel branch and make a
+                // later reader (resume surface / verify-hold guidance) see the wrong branch. Preserve the
+                // incumbent's branch; fall back to the successor's only if the incumbent record had none.
+                branch: incumbentBranch || resolveBranchForClaim(),
                 artifactDir: path.relative(root, dir) || ".",
-                reason: opt(p, "reason", "ensure-session takeover: stale claim"),
+                reason: takeoverReason,
                 // F1 fix (fix-plan iteration 1, HIGH): persist the canonical actor_key on the record so
                 // computeEffectiveState's holderActorKey (assignment-provider.ts) matches this same
                 // branchActorKey string on the next status/guard check, cross-tool.
                 actorKey: resolution.branchActorKey,
             });
+            // Render-don't-execute: emit the incumbent's branch so the skill continues it (never a new
+            // branch). The successor re-enters the SAME artifact dir (deterministic slug) by construction.
+            printJson({ role: "SupersedeTakeover", subject: sanitize(slug), superseded_actor: holderActor, ...(incumbentBranch ? { resumed_branch: sanitizeWide(incumbentBranch) } : {}), reason: sanitizeWide(takeoverReason) });
             return;
         }
         case "free": {
@@ -1537,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
@@ -1549,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).
@@ -1556,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.
@@ -1569,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;
 }
@@ -1720,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))
@@ -1859,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") {
@@ -1930,6 +2415,106 @@ function checksFromBundle(dir) {
     const seen = new Set();
     const checks = [];
     const kindOf = (claim) => String(claim.metadata.check_kind);
+    // Read side of the buildTrustBundle waiver round-trip (write side: buildTrustBundle reads
+    // check._waiver at line ~689 and stamps it onto claimMetadata.waiver at line ~705). Without
+    // this, any caller that rebuilds checks via checksFromBundle() (recordCritique/recordLearning)
+    // silently drops a previously-recorded waiver on the next bundle write.
+    const waiverOf = (claim) => {
+        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;
@@ -1948,6 +2533,15 @@ function checksFromBundle(dir) {
             check.command = ev.execution.label;
         if (ev.evidenceType)
             check.evidenceType = ev.evidenceType;
+        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).
@@ -1960,10 +2554,71 @@ function checksFromBundle(dir) {
             continue;
         seen.add(claim.id);
         const kind = kindOf(claim);
-        checks.push({ id: String(claim.subjectId || "").split("/").pop() || claim.id, kind, status: claim.value ?? "not_verified", summary: claim.fieldOrBehavior || "" });
+        const check = { id: String(claim.subjectId || "").split("/").pop() || claim.id, kind, status: claim.value ?? "not_verified", summary: claim.fieldOrBehavior || "" };
+        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))
@@ -2015,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
@@ -2034,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);
@@ -2063,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
@@ -2090,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
@@ -2100,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`);
@@ -2131,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;
 }
 /**
@@ -2224,7 +3076,17 @@ async function promote(p) {
     // Optionally republish so delivery/trust.bundle carries the promotion claim for CI.
     if (p.flags.has("publish")) {
         const publishRepoRoot = opt(p, "publish-repo-root") ? path.resolve(opt(p, "publish-repo-root")) : findRepoRootFromDirStrict(dir);
+        // #356 AC6: an InvalidBundleShapeError refusal must be LOUD (rethrown, so `promote`
+        // itself fails/exits non-zero) — it is NOT one of the best-effort failure modes (missing
+        // kits/ ancestor, I/O) this catch otherwise tolerates. A `.catch(() => {})`-style swallow
+        // here would silently defeat the whole preflight for the --publish path.
         await publishDelivery(dir, publishRepoRoot).catch((err) => {
+            if (err instanceof InvalidBundleShapeError)
+                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`);
         });
     }
@@ -2284,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);
@@ -2296,8 +3158,18 @@ async function advanceState(p) {
         // publishDelivery below. An explicit --repo-root (e.g. for a scratch/test artifact dir
         // with no kits/ ancestor of its own) always wins, matching publishDeliveryCmd. Failures
         // are visible (stderr warning), not silently swallowed.
+        // #356 AC6: an InvalidBundleShapeError refusal is NOT one of those best-effort failure
+        // modes — it must be LOUD and cause advance-state itself to fail (rethrown here so the
+        // outer command surfaces a non-zero exit), never silently swallowed alongside a genuine
+        // repo-root-resolution/I-O failure.
         const publishRepoRoot = opt(p, "repo-root") ? path.resolve(opt(p, "repo-root")) : findRepoRootFromDirStrict(dir);
         await publishDelivery(dir, publishRepoRoot).catch((err) => {
+            if (err instanceof InvalidBundleShapeError)
+                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`);
         });
     }
@@ -2338,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) {
@@ -2393,8 +3268,18 @@ async function recordRelease(p) {
     // publishDelivery below. An explicit --repo-root (e.g. for a scratch/test artifact dir with
     // no kits/ ancestor of its own) always wins, matching publishDeliveryCmd. Failures are
     // visible (stderr warning), not silently swallowed.
+    // #356 AC6: an InvalidBundleShapeError refusal is NOT best-effort — rethrow so record-release
+    // itself fails loudly (non-zero exit) rather than silently publishing nothing while reporting
+    // success. This is the crux of AC6: record-release is one of the auto-publish paths that must
+    // never let a shape-invalid bundle slip past unnoticed.
     const publishRepoRoot = opt(p, "repo-root") ? path.resolve(opt(p, "repo-root")) : findRepoRootFromDirStrict(dir);
     await publishDelivery(dir, publishRepoRoot).catch((err) => {
+        if (err instanceof InvalidBundleShapeError)
+            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;
@@ -2596,6 +3481,799 @@ async function sealCheckpoint(p) {
     }
     return 0;
 }
+// ─── Reconcile Preflight (#356) ───────────────────────────────────────────────
+// Local, pre-push shape-only preflight for a session's trust.bundle, reusing
+// scripts/lib/reconcile-shape.js (WS8/#356 extraction) and scripts/ci/trust-reconcile.js's
+// own exported manifest resolver — never a forked reimplementation, so this can never
+// silently drift from what the CI trust-reconcile job actually enforces. Deliberately
+// shape-only: it never spawns a fresh manifest/CI command (AC5) — only the already-cheap
+// `run-baseline.sh --manifest-json` static registry emit, which prints the manifest, not
+// test results.
+/**
+ * Delegate to the shared pure-CJS bundle-shape module (scripts/lib/reconcile-shape.js),
+ * mirroring the createRequire pattern used by loadActorIdentityHelper()/
+ * loadLivenessWriteHelper() above — the one repo/runtime boundary #356's plan flagged as
+ * worth double-checking (workflow-sidecar.ts is TS→ESM-compiled-to-CJS-compatible-output;
+ * scripts/lib/reconcile-shape.js is plain CommonJS). Verified clean via `npm run build`
+ * + a require() smoke against build/src/cli/workflow-sidecar.js before this was wired in.
+ */
+function loadReconcileShapeHelper() {
+    const _req = createRequire(import.meta.url);
+    const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/lib/reconcile-shape.js");
+    return _req(helperPath);
+}
+/**
+ * Delegate to scripts/ci/trust-reconcile.js's own EXPORTED pure helpers (manifest
+ * resolution + the git-ancestor primitive) — same createRequire idiom as
+ * loadReconcileShapeHelper() above. trust-reconcile.js is CommonJS; these exports were
+ * added alongside `runTrustReconcile` specifically so a local caller (this preflight)
+ * never needs a second implementation of "how the manifest is resolved" (Q1/AC5).
+ */
+function loadTrustReconcileHelper() {
+    const _req = createRequire(import.meta.url);
+    const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/ci/trust-reconcile.js");
+    return _req(helperPath);
+}
+/**
+ * Shell to scripts/ci/derive-claim-status.mjs exactly as trust-reconcile.js's own
+ * deriveClaimStatuses() does (Q1's recommendation: full status-misassertion/unwaived-assumed
+ * parity with CI, at the cost of one cheap local-only spawn — no CI command execution, just
+ * Surface's pure deriveClaimStatus over the bundle's own evidence/events/policies). Returns
+ * null when re-derivation is unavailable (Surface could not load / helper failed) — callers
+ * degrade to reconcile-shape.js's documented reduced-coverage mode, they do not fail the
+ * whole preflight over this.
+ */
+function derivePreflightClaimStatuses(bundlePath, repoRoot) {
+    const helper = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/ci/derive-claim-status.mjs");
+    if (!fs.existsSync(helper))
+        return null;
+    let stdout;
+    try {
+        stdout = execFileSync(process.execPath, [helper, bundlePath], { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 60000 });
+    }
+    catch {
+        return null;
+    }
+    if (!stdout)
+        return null;
+    try {
+        const obj = JSON.parse(stdout);
+        const m = new Map();
+        for (const [k, v] of Object.entries(obj))
+            m.set(k, v);
+        return m;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Distinct, identifiable error for a shape-invalid trust.bundle — NOT a generic Error, so
+ * every publishDelivery() call site (advanceState/recordRelease/promote/publishDeliveryCmd)
+ * can positively distinguish "refuses to publish an invalid bundle" (must be LOUD, fail
+ * closed, AC6) from the other failure modes those call sites already tolerate as best-effort
+ * (missing kits/ ancestor for a scratch dir, I/O errors, etc — see each catch's own comment).
+ * A bare `instanceof Error` check would not suffice since every thrown failure in this file is
+ * already an Error; `code` is the recognizable, grep-stable discriminator.
+ */
+export class InvalidBundleShapeError extends Error {
+    code = "RECONCILE_PREFLIGHT_INVALID_SHAPE";
+    issues;
+    constructor(issues) {
+        super(`trust.bundle failed the reconcile-preflight shape check (${issues.length} issue(s)) — see .issues for the full report`);
+        this.name = "InvalidBundleShapeError";
+        this.issues = issues;
+    }
+}
+/**
+ * Distinct, identifiable error for a publish attempt by an actor who is NOT the fresh,
+ * non-superseded holder of the subject (issue #293, ADR 0021 §3) — NOT a generic Error and NOT
+ * `InvalidBundleShapeError` (#356), so every publishDelivery() call site can positively
+ * distinguish "refuses to publish because the bundle shape is invalid" from "refuses to publish
+ * because this actor no longer holds the subject" — two genuinely distinct fail-closed tiers
+ * that must never be conflated in a catch handler (a worker fixing a shape issue must not be
+ * told to "re-record evidence" when the real problem is a stale/superseded claim, and vice
+ * versa). Mirrors `InvalidBundleShapeError`'s shape exactly: same `extends Error` base, same
+ * `readonly code` discriminator convention, same doc-comment structure — only the payload
+ * differs (the effective-state/holder/reason/guidance `runVerifyHold()` computed, rather than a
+ * shape-issue list).
+ */
+export class NotFreshHolderError extends Error {
+    code = "VERIFY_HOLD_NOT_FRESH_HOLDER";
+    effective_state;
+    holder;
+    reason;
+    guidance;
+    constructor(result) {
+        super(`verify-hold refused publish — not the fresh holder of this subject (${result.reason}) — see .guidance for reconcile steps`);
+        this.name = "NotFreshHolderError";
+        this.effective_state = result.effective_state;
+        this.holder = result.holder;
+        this.reason = result.reason;
+        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
+ * NOT a distinct predicate, it is #2 enriched, per the plan's Q2 resolution).
+ */
+function preflightFixHint(type) {
+    switch (type) {
+        case "unwaived-assumed":
+            return "FIX: make it pass for real, or re-record with --accepted-gap-reason/--waived-by on a SEPARATE record-evidence call — a command-backed check in the SAME call voids/rejects the waiver (see the command-backed-waiver guard in workflow-sidecar.ts's recordEvidence).";
+        case "waiver-on-command-check":
+            return "FIX: a command-backed (test_output) check cannot be waived — either drop the waiver metadata and let it reconcile against the manifest for real, or record it as a session-local (non-command) claim if it genuinely cannot be re-run.";
+        case "not-run":
+            return "FIX: fold this into a non-command summary (session-local claim, no execution.label), or name the EXACT verbatim manifest command in evidence.execution.label so it reconciles.";
+        case "laundering":
+            return "FIX: remove the exit-code-laundering operator (||, ; true, ; exit 0, etc.) from the command — a laundered command cannot be trusted to reconcile.";
+        case "session-local-failed":
+            return "FIX: a disputed/failing claim always blocks reconcile. Document a disjoint pre-existing failure as prose in a WAIVED non-command summary, not as a standalone claim.";
+        case "status-misassertion":
+            return "FIX: the claim's asserted status does not match what Surface re-derives from the bundle's own evidence/events/policies — re-record evidence so the bundle's own data supports the asserted status; do not hand-edit status.";
+        case "status-underivable":
+            return "FIX: CI-side status re-derivation failed for this claim — ensure @kontourai/surface is installed/resolvable and the claim's evidence/events are well-formed, then re-record.";
+        case "unwaived-session-local":
+            return "FIX: this claim asserts pass but has neither a waiver nor a CI-re-derived 'verified' status — add a waiver (--accepted-gap-reason/--waived-by) or resolve it so Surface derives 'verified'.";
+        default:
+            return "FIX: see the divergence message above for the specific shape defect.";
+    }
+}
+/**
+ * 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)
+ */
+/**
+ * #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))
+            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 — 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;
+}
+export function runReconcilePreflight(dir, repoRoot, manifestOverride) {
+    const bundlePath = path.join(dir, "trust.bundle");
+    if (!fs.existsSync(bundlePath)) {
+        // A preflight with nothing to check is a usage error, not a soft pass — an agent must
+        // never read "no bundle" as "bundle is valid" (see reconcilePreflightCmd for the CLI-side
+        // die()). The library entrypoint throws too, since publishDelivery() itself already has
+        // its OWN, separate, pre-existing fail-soft branch for bundle-absence (guarded before this
+        // function is ever called there) — this function is never invoked without a bundle.
+        throw new Error(`reconcile-preflight: no trust.bundle found at ${bundlePath} — nothing to check. This is a usage error, not a soft pass.`);
+    }
+    const bundle = loadJson(bundlePath);
+    const shape = loadReconcileShapeHelper();
+    const tr = loadTrustReconcileHelper();
+    // Resolve the SAME canonical (fresh-verify) commands CI would fall back to feeding into
+    // resolveManifest's legacy tier (tier 5), for genuine parity on that fallback path too —
+    // CLI --commands is not a preflight concept, so only the TRUST_RECONCILE_COMMANDS env /
+    // package.json trust-reconcile-verify tiers apply locally; a repo with neither and no
+    // manifest source resolves to the same empty legacy fallback CI itself would in that case.
+    const canonicalCommands = tr.resolveCanonicalCommands({ commands: [] }, repoRoot) ?? [];
+    const manifestResolution = tr.resolveManifest({ manifest: manifestOverride ?? null }, repoRoot, canonicalCommands);
+    const manifestByCmd = new Map();
+    for (const e of manifestResolution.entries)
+        manifestByCmd.set(tr.normalizeCmd(e.command), e);
+    const derivedStatus = derivePreflightClaimStatuses(bundlePath, repoRoot);
+    const { reconcilable, sessionLocal, noEvidenceCommand, waiverOnCommand } = shape.classifyBundleClaims(bundle);
+    const issues = [];
+    issues.push(...shape.waiverOnCommandIssues(waiverOnCommand));
+    issues.push(...shape.noEvidenceCommandIssues(noEvidenceCommand));
+    const { issues: manifestIssues } = shape.reconcilableManifestIssues(reconcilable, manifestByCmd);
+    issues.push(...manifestIssues);
+    // iteration-1 F1: the local preflight explicitly opts into reduced-coverage degradation
+    // when re-derivation is unavailable (Surface not installed, spawn failure, etc.) — CI's
+    // trust-reconcile.js does NOT opt in and stays fail-closed on the same condition (see
+    // reconcile-shape.js's sessionLocalShapeIssues docstring for the full mode contract).
+    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);
+    return { ok: report.length === 0, issues: report, warnings };
+}
+/**
+ * reconcile-preflight <artifact-dir> [--manifest <json>] [--repo-root <path>]
+ *
+ * Local, pre-push shape-only check of the session's trust.bundle — reuses
+ * scripts/lib/reconcile-shape.js and scripts/ci/trust-reconcile.js's own exported
+ * classification/manifest-resolution so this can never silently drift from what CI's
+ * Trust Reconcile job enforces. Prints every divergence with the claim id, divergence
+ * type, and a human fix instruction; exits 0 with zero issues, 1 otherwise. Never spawns a
+ * fresh manifest/CI command re-run (AC5) — resolves the manifest and re-derives status
+ * (both local-only, no CI command execution) but never re-runs a manifest command itself.
+ *
+ * Usage: workflow-sidecar reconcile-preflight <artifactDir> [--manifest <json>] [--repo-root <path>]
+ */
+async function reconcilePreflightCmd(p) {
+    if (p.flags.has("help") || (!p.positional[0] && !p.opts["help"])) {
+        if (p.flags.has("help")) {
+            console.log("Usage: workflow-sidecar reconcile-preflight <artifactDir> [--manifest <json>] [--repo-root <path>]");
+            console.log("Local, pre-push shape-only check of <artifactDir>/trust.bundle. Exits 0 with no issues, 1 otherwise.");
+            return 0;
+        }
+    }
+    const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
+    const repoRoot = opt(p, "repo-root") ? path.resolve(opt(p, "repo-root")) : findRepoRootFromDirStrict(dir);
+    if (!repoRoot)
+        die(`reconcile-preflight: no kits/ ancestor found from ${dir}; pass --repo-root explicitly.`);
+    const manifestOverride = p.opts["manifest"]?.at(-1) ?? null;
+    const bundlePath = path.join(dir, "trust.bundle");
+    if (!fs.existsSync(bundlePath)) {
+        die(`reconcile-preflight: no trust.bundle at ${bundlePath} — a preflight with nothing to check is a usage error, not a soft pass. Record evidence first (record-evidence) before running reconcile-preflight.`);
+    }
+    const result = runReconcilePreflight(dir, repoRoot, manifestOverride);
+    for (const w of result.warnings) {
+        process.stderr.write(`[reconcile-preflight] ${w}\n`);
+    }
+    if (result.ok) {
+        console.log(`[reconcile-preflight] OK — no shape issues found in ${bundlePath}`);
+        return 0;
+    }
+    process.stderr.write(`[reconcile-preflight] FAILED — ${result.issues.length} shape issue(s) found in ${bundlePath}:\n`);
+    for (const issue of result.issues) {
+        process.stderr.write(`[reconcile-preflight]   - ${issue}\n`);
+    }
+    return 1;
+}
+/**
+ * The ONE hard-stop gate (issue #293, ADR 0021 §3): "is my actor the fresh, non-superseded
+ * holder of this subject (or is the subject free/self-held)?" Reuses the SAME assignment ⋈
+ * liveness join #290/#291 already built (`computeEffectiveState` + `readLocalAssignmentStatus`
+ * + `readLivenessEvents`/`freshHolders`) — no second computation is invented here. This is the
+ * mirror-image check, at the OTHER end of the session lifecycle, of
+ * `enforceEnsureSessionOwnership`'s pre-entry guard above: that guard decides whether entry
+ * should claim/supersede/refuse; this gate decides whether PUBLISH should proceed, with a
+ * different (new) per-effective-state mapping — the ownership guard's "claim"/"supersede"
+ * actions are wrong at publish time, so this is new interpretation of the existing join output,
+ * not a new join and not a new `EffectiveState` value (there is no literal `"superseded"` state
+ * — a superseded-away actor's own re-check naturally resolves to `held`(holder=successor) or
+ * `reclaimable`, never `self_is_holder`; see assignment-provider.ts's `computeEffectiveState`).
+ *
+ * Effective-state -> publish-decision mapping (the operative spec, from the plan's table).
+ * IMPORTANT (bug fix, #397): this gate fences the durable ASSIGNMENT hold, not ambient
+ * liveness — liveness is advisory everywhere else in the system, and this is the ONE hard
+ * gate, so it must never false-block on liveness alone. A subject with fresh liveness by
+ * another actor but NO durable assignment record (`held`, reason
+ * `liveness_claim_present_assignment_lagging`) therefore PASSES, not BLOCKs — there is no
+ * durable ownership conflict to protect, only ambient presence. This does NOT weaken zombie
+ * protection: a superseded zombie always has an assignment record (either its own stale
+ * assignment — `reclaimable` — or the successor's assignment-backed `held`/
+ * `fresh_liveness_heartbeat`), both of which still BLOCK below.
+ *   - `free` (no assignment ever recorded)              -> PASS (never false-block an untracked subject)
+ *   - `held`, reason `self_is_holder`                    -> PASS (the caller IS the current holder)
+ *   - `held`, reason `liveness_claim_present_assignment_lagging`
+ *     (fresh liveness by another actor, NO durable assignment record) -> PASS (liveness alone
+ *     is never a durable ownership conflict — see #397 fix note above)
+ *   - `held`, reason `fresh_liveness_heartbeat`
+ *     (durable assignment held by another actor + fresh liveness)     -> BLOCK (a different
+ *     actor durably holds this subject and is demonstrably still live)
+ *   - `reclaimable` (assignment present, stale/absent liveness)       -> BLOCK (not proof of
+ *     self — safe default blocks; a durable assignment record exists)
+ *   - `human-held`                                        -> BLOCK (never publish over a human assignee)
+ *   - no resolvable join at all (non-local-file provider
+ *     with no --effective-state-json)                    -> `not_evaluated`, PASS (documented scope
+ *                                                             boundary, loud stderr note, never a silent block)
+ *
+ * Actor resolution mirrors `enforceEnsureSessionOwnership` EXACTLY: the bare
+ * `resolveActor(env).actor` / branchActorKey string, NEVER `serializeActor(actorStruct)`'s
+ * triple — the #291 flat-vs-triple seam. `opts.actorKey` (the CLI's --actor / FLOW_AGENTS_ACTOR
+ * override, already sanitized by the caller) takes precedence when provided.
+ *
+ * Slug/artifactRoot derivation matches `publishDelivery()`'s own `slug =
+ * path.basename(path.resolve(dir))` byte-for-byte (both must resolve the SAME assignment
+ * record) and the `artifactRoot = path.dirname(dir)` pattern already used elsewhere in this
+ * file for a `dir`-only consumer.
+ *
+ * github provider: read-only precomputed `--effective-state-json` escape hatch, matching
+ * `enforceEnsureSessionOwnership`'s existing github branch precedent exactly (render-don't-
+ * execute — assignment-provider.ts never calls `gh` directly from this CLI).
+ *
+ * Every interpolated actor/holder/reason string is sanitized via
+ * `stripControlCharsForDisplay(...).slice(0, 64)` — reusing the exact top-level helper, never a
+ * second sanitizer (AC7).
+ *
+ * SECOND CI-blocking false-block fix (this iteration): the hard gate above enforces ONLY for a
+ * STABLY-identified actor. A caller's identity is STABLE when it comes from an explicit
+ * `opts.actorKey` (a caller that hands in an actor key is asserting a stable identity — e.g. the
+ * CLI's --actor / FLOW_AGENTS_ACTOR override, or the github skill's precomputed path), from
+ * `FLOW_AGENTS_ACTOR` (`resolveActor` source `"explicit-override"`), or from a runtime-native
+ * session id (`resolveActor` source `` `runtime-session-id:${runtime}` ``, e.g. Claude Code's
+ * `CLAUDE_CODE_SESSION_ID`). It is UNSTABLE when `resolveActor` falls all the way through to the
+ * process-ancestry fallback (source `"process-ancestry"`) or fails to resolve at all (source
+ * `"unresolved"` / `isUnresolvedActor(actor)`). This mirrors `enforceEnsureSessionOwnership`'s
+ * Design Decision 4 (never hard-fail on actor ambiguity): a session that cannot stably
+ * self-identify cannot be meaningfully fenced against a durable assignment record, so hard-
+ * blocking it produces exactly the false-block CI hit (no `FLOW_AGENTS_ACTOR`/runtime session id
+ * in CI -> ancestry fallback -> a DIFFERENT ancestry-derived actor string than the one that
+ * created the claim -> `reclaimable`/not-self -> hard BLOCK of a legitimate self-publish). A
+ * real coordination participant always has a stable identity (explicit override or runtime
+ * session id), so zombie protection under a stable actor is completely unaffected — this only
+ * changes behavior for a caller that was never fenceable in the first place. When the resolved
+ * actor identity is UNSTABLE, this function short-circuits to `{ ok: true, effective_state:
+ * "not_evaluated", reason: "actor-identity-unstable-advisory-only" }` (holder included, sanitized,
+ * when one exists) BEFORE running the assignment ⋈ liveness join at all, with one loud stderr
+ * note — the gate degrades to advisory-only rather than ever false-blocking an unstable identity.
+ * When the actor identity IS stable, the effective-state -> publish-decision mapping above
+ * applies exactly as documented, unchanged.
+ */
+export function runVerifyHold(dir, repoRoot, opts) {
+    // repoRoot is accepted (not derived) for signature symmetry with runReconcilePreflight(dir,
+    // repoRoot, ...) / publishDelivery(dir, repoRoot) — the local-file join below only needs
+    // artifactRoot/slug, but a future non-local-file provider branch that resolves a live
+    // repo-relative fixture would need it, so the parameter stays part of the public contract.
+    void repoRoot;
+    const sanitize = (value) => stripControlCharsForDisplay(value).slice(0, 64);
+    const slug = path.basename(path.resolve(dir));
+    const artifactRoot = path.dirname(path.resolve(dir));
+    const nowMs = opts?.now ?? Date.now();
+    const assignmentProviderKind = opts?.assignmentProviderKind || "local-file";
+    const helper = loadActorIdentityHelper();
+    // Stability check (SECOND CI-blocking false-block fix, this iteration): an explicitly-provided
+    // opts.actorKey is treated as stable outright (the caller is asserting a stable identity — see
+    // doc comment above). Otherwise resolve BOTH the actor and its source so we can tell an
+    // explicit-override / runtime-session-id actor (stable, enforce as today) apart from a
+    // process-ancestry / unresolved one (unstable, advisory-only — never hard-block).
+    const resolved = opts?.actorKey ? { actor: opts.actorKey, source: "explicit-override" } : helper.resolveActor(process.env);
+    const actorKey = resolved.actor;
+    const isStableActor = !!opts?.actorKey
+        || resolved.source === "explicit-override"
+        || resolved.source.startsWith("runtime-session-id")
+        // #398: a CI-runtime actor is STABLE across every subprocess in a CI job (derived from the
+        // provider's published run/job identifiers), so the verify-hold gate ENFORCES for CI sessions
+        // instead of degrading to advisory — the root fix for the #293 CI false-block workaround.
+        || resolved.source.startsWith("ci-runtime");
+    const guidanceLines = (holderActor) => [
+        "Re-run pull-work/pickup-probe to discover the current holder of this subject and hand off cleanly (learning-review/handoff) rather than publishing over it.",
+        holderActor
+            ? `The current holder appears to be ${sanitize(holderActor)} — confirm with them before proceeding.`
+            : "Confirm with the assigned human before proceeding.",
+        "If a human confirms this session should resume ownership, run `ensure-session --supersede-stale` to explicitly re-claim the subject before retrying publish.",
+    ];
+    let effective = null;
+    if (opts?.effectiveStateJson !== undefined) {
+        const parsed = opts.effectiveStateJson;
+        const candidate = parsed && typeof parsed === "object" ? parsed.effective : undefined;
+        const validStates = new Set(["held", "reclaimable", "human-held", "free"]);
+        if (candidate && typeof candidate.effective_state === "string" && validStates.has(candidate.effective_state)) {
+            effective = candidate;
+        }
+    }
+    else if (assignmentProviderKind === "local-file") {
+        // Same call shape as enforceEnsureSessionOwnership's local-file branch — no second
+        // freshness/ownership computation is invented (see that function's F1 fix comment for why
+        // branchActorKey, not the serialized ActorStruct triple, is the correct selfActor here).
+        const assignment = readLocalAssignmentStatus(artifactRoot, slug);
+        const events = readLivenessEvents(artifactRoot);
+        const freshList = loadLivenessReadHelper().freshHolders(events, slug, actorKey, nowMs);
+        effective = computeEffectiveState(assignment, freshList, actorKey, nowMs);
+    }
+    if (!effective) {
+        // Documented scope boundary (Design Constraint): a non-local-file provider with no
+        // precomputed --effective-state-json cannot be evaluated in-CLI (render-don't-execute — no
+        // live `gh` call from workflow-sidecar.ts). PASS-through, never a silent block, with a loud
+        // stderr note — mirroring enforceEnsureSessionOwnership's existing github branch precedent.
+        process.stderr.write(`[verify-hold] not evaluated: provider "${sanitize(assignmentProviderKind)}" requires --effective-state-json (or use --assignment-provider local-file)\n`);
+        return { ok: true, effective_state: "not_evaluated", reason: "provider_not_evaluated", guidance: [] };
+    }
+    // F1 fix (fix-plan iteration 1, HIGH): sanitize EVERY untrusted string field of
+    // effective.holder before it reaches the returned JSON / NotFreshHolderError.holder — never
+    // spread the raw holder and override only the discriminated field. `last_at` (sourced from
+    // record.claimed_at or a liveness event's `at`, both attacker-writable in the shared
+    // multi-writer liveness/assignment stream) and `actor`/`assignee` are all display strings and
+    // go through the SAME `sanitize` helper (stripControlCharsForDisplay(...).slice(0, 64)) as
+    // enforceEnsureSessionOwnership's equivalent call sites (AC7 injection-discipline parity).
+    // `idle_days` is a `number | null` computed by computeEffectiveState from Date.parse/Math.floor
+    // arithmetic (assignment-provider.ts) — never an attacker-controlled string — so it is passed
+    // through as-is, but defensively re-coerced with `typeof === "number"` so a future shape change
+    // upstream can never smuggle a string through this field.
+    const sanitizeHolder = (holder) => {
+        if (!holder)
+            return undefined;
+        return {
+            actor: holder.actor ? sanitize(holder.actor) : undefined,
+            assignee: holder.assignee ? sanitize(holder.assignee) : holder.assignee,
+            idle_days: typeof holder.idle_days === "number" ? holder.idle_days : undefined,
+            last_at: holder.last_at ? sanitize(holder.last_at) : undefined,
+        };
+    };
+    // SECOND CI-blocking false-block fix (this iteration): an actor identity that cannot stably
+    // self-identify (process-ancestry fallback or unresolved) cannot be meaningfully fenced against
+    // a durable assignment record — hard-blocking it is exactly the CI false-block this fix targets
+    // (see doc comment above). Degrade to advisory-only: never hard-block, regardless of what the
+    // join above computed. This check runs AFTER the join so an existing holder (if any) can still
+    // be surfaced for visibility, but strictly BEFORE the effective-state switch below so no
+    // unstable-actor request can ever reach a `case` that returns `ok: false`.
+    if (!isStableActor) {
+        process.stderr.write("[verify-hold] actor identity is ancestry-derived/unresolved — gate is advisory only for unstable identities; not hard-blocking publish\n");
+        return {
+            ok: true,
+            effective_state: "not_evaluated",
+            reason: "actor-identity-unstable-advisory-only",
+            guidance: [],
+            ...(effective.holder ? { holder: sanitizeHolder(effective.holder) } : {}),
+        };
+    }
+    switch (effective.effective_state) {
+        case "free":
+            return { ok: true, effective_state: "free", reason: effective.reason, guidance: [] };
+        case "held": {
+            const isSelf = effective.reason === "self_is_holder" || (!!effective.holder?.actor && effective.holder.actor === actorKey);
+            if (isSelf)
+                return { ok: true, effective_state: "held", holder: sanitizeHolder(effective.holder), reason: effective.reason, guidance: [] };
+            // Bug fix (#397): `liveness_claim_present_assignment_lagging` means computeEffectiveState
+            // found NO durable assignment record at all — only ambient liveness by another actor
+            // (assignment-provider.ts's `if (!isAssigned) { if (freshHoldersList.length > 0) return
+            // held/liveness_claim_present_assignment_lagging }`). Liveness alone is advisory
+            // everywhere else in this system; this ONE hard gate must fence the durable ASSIGNMENT
+            // hold, not ambient presence, so this case PASSES rather than false-blocking. Every other
+            // `held` reason (`fresh_liveness_heartbeat`) is reached only when an assignment record
+            // DOES exist (assignment-provider.ts's `isAssigned` branch) and the recorded holder is
+            // still fresh-live — a genuine durable-ownership conflict, which still BLOCKs below.
+            if (effective.reason === "liveness_claim_present_assignment_lagging") {
+                return { ok: true, effective_state: "held", holder: sanitizeHolder(effective.holder), reason: effective.reason, guidance: [] };
+            }
+            const holderActor = effective.holder?.actor;
+            return {
+                ok: false,
+                effective_state: "held",
+                holder: sanitizeHolder(effective.holder),
+                reason: `subject ${sanitize(slug)} is currently held by a different, still-live actor (${sanitize(holderActor ?? "unknown")})`,
+                guidance: guidanceLines(holderActor),
+            };
+        }
+        case "reclaimable": {
+            // Stop-short risk (plan): reclaimable is NEVER treated as PASS. A lapsed self-claim looks
+            // reclaimable, not self_is_holder, to a woken zombie's own re-check — the safe default
+            // blocks and asks for reconcile guidance rather than auto-passing a stale self-claim.
+            const holderActor = effective.holder?.actor;
+            return {
+                ok: false,
+                effective_state: "reclaimable",
+                holder: sanitizeHolder(effective.holder),
+                reason: `subject ${sanitize(slug)}'s existing claim (held by ${sanitize(holderActor ?? "unknown")}) is stale/unverified as self — not a confirmed fresh hold`,
+                guidance: guidanceLines(holderActor),
+            };
+        }
+        case "human-held": {
+            const assignee = effective.holder?.assignee;
+            return {
+                ok: false,
+                effective_state: "human-held",
+                holder: sanitizeHolder(effective.holder),
+                reason: `subject ${sanitize(slug)} is assigned to ${assignee ? sanitize(assignee) : "an assigned human"} — never publish over a human assignment without confirmation`,
+                guidance: guidanceLines(undefined),
+            };
+        }
+        default:
+            return { ok: true, effective_state: "not_evaluated", reason: "unrecognized_effective_state", guidance: [] };
+    }
+}
+/**
+ * verify-hold <artifact-dir> [--actor <key>] [--now <iso>] [--assignment-provider <kind>]
+ *   [--effective-state-json <path|->]
+ *
+ * CLI surface for runVerifyHold() (issue #293). Prints `{ role: "VerifyHoldResult", ... }` JSON
+ * and exits 0 when `ok` (including `not_evaluated` — a documented scope boundary is never a
+ * failure exit), 1 otherwise. NEVER throws at the CLI boundary — matches
+ * `reconcilePreflightCmd`'s existing convention of printing then exiting rather than throwing;
+ * the thrown `NotFreshHolderError` variant is reserved for the LIBRARY call inside
+ * `publishDelivery()`.
+ *
+ * Usage: workflow-sidecar verify-hold <artifactDir> [--actor <key>] [--now <iso>]
+ *   [--assignment-provider <kind>] [--effective-state-json <path|->]
+ */
+async function verifyHoldCmd(p) {
+    if (p.flags.has("help") || (!p.positional[0] && !p.opts["help"])) {
+        if (p.flags.has("help")) {
+            console.log("Usage: workflow-sidecar verify-hold <artifactDir> [--actor <key>] [--now <iso>] [--assignment-provider <kind>] [--effective-state-json <path|->]");
+            console.log("Checks whether the calling actor is the fresh, non-superseded holder of <artifactDir>'s subject. Exits 0 if ok (including not_evaluated), 1 otherwise.");
+            return 0;
+        }
+    }
+    const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
+    const repoRoot = opt(p, "repo-root") ? path.resolve(opt(p, "repo-root")) : findRepoRootFromDirStrict(dir);
+    // SECOND CI-blocking false-block fix (this iteration): only pass an explicit actorKey through
+    // to runVerifyHold when the CALLER explicitly passed --actor — that is the one case where an
+    // actorKey should be treated as an asserted-stable identity (see runVerifyHold's doc comment).
+    // When --actor is omitted, actorKey is left undefined so runVerifyHold performs its OWN
+    // resolveActor(process.env) call internally and can see the real `source` (explicit-override /
+    // runtime-session-id / process-ancestry / unresolved) to decide stability — calling
+    // resolveReadActorKey(p) here first would discard that source and wrongly force every ambient
+    // resolution (including an ancestry fallback) to be treated as an explicit/stable actorKey.
+    const actorKey = opt(p, "actor") ? loadActorIdentityHelper().sanitizeSegment(opt(p, "actor")) : undefined;
+    const nowMs = opt(p, "now") ? Date.parse(opt(p, "now")) : undefined;
+    const assignmentProviderKind = opt(p, "assignment-provider", "local-file");
+    const effectiveStateJsonFlag = opt(p, "effective-state-json");
+    const effectiveStateJson = effectiveStateJsonFlag ? loadJsonInputFile(effectiveStateJsonFlag) : undefined;
+    const result = runVerifyHold(dir, repoRoot, { actorKey, now: nowMs, assignmentProviderKind, effectiveStateJson });
+    printJson({ role: "VerifyHoldResult", ...result });
+    return result.ok ? 0 : 1;
+}
+// ─── Takeover Preflight (#294, ADR 0021 §5) ───────────────────────────────────
+/**
+ * Render (never execute) the takeover protocol for a candidate the skill has selected. Takeover is
+ * RESUMPTION, not restart: when a subject is `reclaimable` (a durable assignment whose incumbent is
+ * no longer heartbeating), a successor must (1) grace-beat — wait one heartbeat interval and re-check,
+ * backing off if the incumbent revives — (2) supersede via `ensure-session --supersede-stale`, and
+ * (3) CONTINUE THE INCUMBENT'S BRANCH (from the incumbent's claim record), never a parallel one, and
+ * re-enter the SAME artifact dir (deterministic slug). This function computes the effective state
+ * (the same assignment ⋈ liveness join verify-hold/ensure-session use) and emits the appropriate
+ * action + the incumbent's `resume_branch`; the skill executes the beat/supersede/git steps.
+ *
+ * Race-safety is CLI-enforced at supersede time, not here: `ensure-session --supersede-stale`
+ * re-computes the state and refuses (dies on `held`) if the incumbent revived during the beat, so a
+ * successor that skipped or lost the grace race still cannot supersede a live incumbent (AC2a).
+ *
+ * ADVISORY, not a gate: the assignment ⋈ liveness JOIN is identical to verify-hold's, but this render
+ * only advises the skill which action to take — the ACTUAL enforcement is `ensure-session
+ * --supersede-stale` (re-check under a subject lock). So it deliberately does NOT replicate
+ * verify-hold's #398 `isStableActor` tiering (which exists there only because verify-hold is a hard
+ * publish BLOCK that must not false-block an unstable/ancestry identity): a wrong self-identification
+ * here yields only a wrong advisory string, never a wrong mutation.
+ *
+ * Ordering note: ADR 0021 §5's literal wording is supersede→grace→maybe-undo; this implements
+ * grace→recheck→supersede (never write until the beat confirms the incumbent stayed stale) — a
+ * deliberate, safer variant that preserves the ADR's intent ("laptop just woke resolves in the
+ * incumbent's favor") without a premature write to walk back.
+ *
+ * All untrusted fields (incumbent actor / branch / last_at, sourced from the shared multi-writer
+ * assignment+liveness stream) pass through `sanitize`/`sanitizeWide` (stripControlCharsForDisplay +
+ * the repo's 64/240 cap tiers — branch uses the 240 free-text tier so a valid long branch is never
+ * truncated into a bad checkout target) — the #287/#320/#293 injection class.
+ */
+export function runTakeoverPreflight(dir, opts) {
+    const sanitize = (value) => stripControlCharsForDisplay(value).slice(0, 64);
+    // Branch names use the repo's 240-char free-text tier (matching assignment-provider.ts's
+    // sanitizeDisplayField(record.branch, 240)), NOT the 64-char id tier: a realistic
+    // `agent/<actor>/<slug>` branch can exceed 64 chars, and truncating `resume_branch` would hand the
+    // skill a `git checkout <truncated>` target that does not exist — defeating the resume-the-branch
+    // guarantee. Control chars are still stripped (injection), only the cap widens.
+    const sanitizeWide = (value) => stripControlCharsForDisplay(value).slice(0, 240);
+    const slug = path.basename(path.resolve(dir));
+    const artifactRoot = path.dirname(path.resolve(dir));
+    const nowMs = opts?.now ?? Date.now();
+    const helper = loadActorIdentityHelper();
+    const actorKey = opts?.actorKey ? helper.sanitizeSegment(opts.actorKey) : helper.resolveActor(process.env).actor;
+    const graceSeconds = opts?.graceSeconds ?? loadLivenessPolicyHelper().resolveHeartbeatThrottleSeconds(process.env);
+    const assignment = readLocalAssignmentStatus(artifactRoot, slug);
+    const events = readLivenessEvents(artifactRoot);
+    const freshList = loadLivenessReadHelper().freshHolders(events, slug, actorKey, nowMs);
+    const effective = computeEffectiveState(assignment, freshList, actorKey, nowMs);
+    const reason = sanitize(effective.reason);
+    const holderActor = effective.holder?.actor ? sanitize(effective.holder.actor) : undefined;
+    const holderLastAt = effective.holder?.last_at ? sanitize(effective.holder.last_at) : undefined;
+    switch (effective.effective_state) {
+        case "reclaimable": {
+            // The incumbent's branch is the resume target — read it from the pre-supersede record, never
+            // derive a new one (AC1: takeover continues the incumbent's branch, no parallel branch).
+            const resumeBranch = assignment.record?.branch ? sanitizeWide(assignment.record.branch) : undefined;
+            return {
+                ok: true,
+                action: "grace-then-supersede",
+                effective_state: "reclaimable",
+                reason,
+                holder: { actor: holderActor, last_at: holderLastAt },
+                ...(resumeBranch ? { resume_branch: resumeBranch } : {}),
+                grace_seconds: graceSeconds,
+                next_steps: [
+                    `Grace beat: wait ${graceSeconds}s (one heartbeat interval) for the incumbent to revive.`,
+                    `Re-run \`workflow-sidecar takeover-preflight ${slug}\`; if it now reports action "back-off" the incumbent revived — STOP and reselect.`,
+                    `If still "grace-then-supersede", run \`ensure-session --supersede-stale\` to take over (it re-checks and refuses if the incumbent revived), recording the audit trail.`,
+                    resumeBranch
+                        ? `Continue the incumbent's branch: \`git fetch origin ${resumeBranch} && git checkout ${resumeBranch}\` — NEVER create a new branch. Re-enter the existing artifact dir (deterministic slug); do not restart the plan.`
+                        : `Re-enter the existing artifact dir (deterministic slug) and continue the incumbent's branch from state.json.branch — never a new branch; do not restart the plan.`,
+                ],
+            };
+        }
+        case "held": {
+            const selfIsHolder = effective.reason === "self_is_holder";
+            return {
+                ok: selfIsHolder,
+                action: selfIsHolder ? "proceed" : "back-off",
+                effective_state: "held",
+                reason,
+                holder: { actor: holderActor, last_at: holderLastAt },
+                next_steps: selfIsHolder
+                    ? ["This subject is already held by you — proceed with your existing session; no takeover needed."]
+                    : [`The incumbent is live/revived (held by ${holderActor ?? "another actor"}). Back off — do NOT supersede a live holder — and reselect a different item.`],
+            };
+        }
+        case "human-held": {
+            return {
+                ok: false,
+                action: "ask-first",
+                effective_state: "human-held",
+                reason,
+                holder: { actor: holderActor, last_at: holderLastAt },
+                next_steps: [`A human is assigned (${holderActor ?? "assignee"}). Ask first — never auto-supersede a human assignment (ADR 0021 §6).`],
+            };
+        }
+        case "free":
+        default: {
+            return {
+                ok: true,
+                action: "claim",
+                effective_state: "free",
+                reason,
+                next_steps: ["No durable claim to supersede — this is a normal claim, not a takeover. Run `ensure-session` to claim it."],
+            };
+        }
+    }
+}
+async function takeoverPreflightCmd(p) {
+    if (p.flags.has("help")) {
+        console.log("Usage: workflow-sidecar takeover-preflight <artifactDir> [--actor <key>] [--now <iso>] [--grace-seconds <n>]");
+        console.log("Renders the ADR 0021 §5 takeover protocol (grace-then-supersede | back-off | claim | ask-first | proceed) for a reclaimable candidate. Read-only; never mutates.");
+        return 0;
+    }
+    const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
+    const actorKey = opt(p, "actor") ? loadActorIdentityHelper().sanitizeSegment(opt(p, "actor")) : undefined;
+    const nowMs = opt(p, "now") ? Date.parse(opt(p, "now")) : undefined;
+    const graceSeconds = opt(p, "grace-seconds") ? Number(opt(p, "grace-seconds")) : undefined;
+    const result = runTakeoverPreflight(dir, { actorKey, now: nowMs, graceSeconds });
+    printJson({ role: "TakeoverPreflight", ...result });
+    return result.ok ? 0 : 1;
+}
 // ─── Publish Delivery Bundle ──────────────────────────────────────────────────
 // Copies the session's trust.bundle (+ checkpoint companions) from the gitignored
 // session artifact dir (.kontourai/flow-agents/<slug>/) to the committed delivery/ transport
@@ -2606,52 +4284,47 @@ async function sealCheckpoint(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.
- *
- * 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.
- *
- * 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.
+ * #413 Facet B: prune ONLY keepSlug's OWN prior seal — NEVER another session's
+ * `delivery/<other-slug>/` directory.
+ *
+ * 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 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`);
     }
 }
 /**
@@ -2679,6 +4352,55 @@ function pruneSupersededSeals(deliveryDir, keepSlug) {
  * evals/integration/test_checkpoint_signing.sh TEST 2 and the WS5 session findings at
  * .kontourai/flow-agents/ws5-governance-kit-slice1 for the root cause this fixes).
  * Idempotent: overwrites on re-delivery to the same slug.
+ *
+ * #356 Wave 3 (AC6): Fail-CLOSED on bundle SHAPE. After the fail-soft absence guard below,
+ * runs the SAME reconcile-preflight shape check (runReconcilePreflight) the
+ * `reconcile-preflight` CLI subcommand exposes, BEFORE copying anything into delivery/. A
+ * shape-invalid bundle throws InvalidBundleShapeError (a distinct, identifiable error — see
+ * its own doc comment) rather than silently publishing a bundle CI's Trust Reconcile job
+ * would reject anyway. This is intentionally a NEW, additive fail-closed branch — it must
+ * never be conflated with the pre-existing fail-soft absence/repo-root branches above/below,
+ * which stay exactly as before (see each publishDelivery call site's catch handler for how
+ * the distinction is preserved end-to-end).
+ *
+ * #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).
+ *
+ * #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");
@@ -2688,6 +4410,39 @@ 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 — 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`);
+        for (const issue of preflight.issues) {
+            process.stderr.write(`[publish-delivery]   - ${issue}\n`);
+        }
+        throw new InvalidBundleShapeError(preflight.issues);
+    }
+    // #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`);
+        for (const line of holdCheck.guidance)
+            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
@@ -2695,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)
@@ -2801,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) {
@@ -2888,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.
@@ -3904,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
@@ -3933,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);
@@ -3948,6 +5733,9 @@ async function main() {
             case "resolve-slug": return resolveSlugCmd(p);
             case "seal-checkpoint": return sealCheckpoint(p);
             case "publish-delivery": return publishDeliveryCmd(p);
+            case "reconcile-preflight": return reconcilePreflightCmd(p);
+            case "verify-hold": return verifyHoldCmd(p);
+            case "takeover-preflight": return takeoverPreflightCmd(p);
             default: die(`unknown command: ${p.command}`);
         }
     });