@kontourai/flow-agents 3.2.0 → 3.3.0

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

@@ -230,9 +230,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 };
 }
@@ -1418,6 +1426,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 +1509,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": {
@@ -1930,6 +1960,14 @@ 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;
+    };
     for (const ev of bundle.evidence) {
         if (!ev || !ev.claimId)
             continue;
@@ -1948,6 +1986,9 @@ function checksFromBundle(dir) {
             check.command = ev.execution.label;
         if (ev.evidenceType)
             check.evidenceType = ev.evidenceType;
+        const waiver = waiverOf(claim);
+        if (waiver)
+            check._waiver = waiver;
         checks.push(check);
     }
     // Also include check claims that have no evidence item (surface_trust_refs style).
@@ -1960,7 +2001,11 @@ 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;
+        checks.push(check);
     }
     return checks;
 }
@@ -2224,7 +2269,15 @@ 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;
             process.stderr.write(`[promote] WARNING: publish-delivery failed: ${err instanceof Error ? err.message : String(err)}\n`);
         });
     }
@@ -2296,8 +2349,16 @@ 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;
             process.stderr.write(`[advance-state] WARNING: publish-delivery failed: ${err instanceof Error ? err.message : String(err)}\n`);
         });
     }
@@ -2393,8 +2454,16 @@ 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;
         process.stderr.write(`[record-release] WARNING: publish-delivery failed: ${err instanceof Error ? err.message : String(err)}\n`);
     });
     return 0;
@@ -2596,6 +2665,660 @@ 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;
+    }
+}
+/**
+ * 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.";
+    }
+}
+/**
+ * F4 (iteration-1): extracted from runReconcilePreflight so the main function stays under
+ * the 50-line guideline. Q3 (optional, non-blocking): warn if the checkpoint's commit_sha is
+ * not yet an ancestor of local HEAD — never affects ok/exit code, best-effort only. Already a
+ * self-contained try/catch with no effect on the caller's `ok`/`issues`.
+ */
+function checkpointStalenessWarning(dir, repoRoot, tr) {
+    const warnings = [];
+    try {
+        const checkpointPath = path.join(dir, "trust.checkpoint.json");
+        if (fs.existsSync(checkpointPath)) {
+            const checkpoint = loadJson(checkpointPath);
+            const commitSha = checkpoint && typeof checkpoint === "object" ? checkpoint.commit_sha : undefined;
+            if (typeof commitSha === "string" && commitSha) {
+                let headSha = "";
+                try {
+                    headSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+                }
+                catch {
+                    headSha = "";
+                }
+                if (headSha && !tr.isAncestorCommit(repoRoot, commitSha, headSha)) {
+                    warnings.push(`NON-BLOCKING: trust.checkpoint.json commit_sha '${commitSha}' is not an ancestor of local HEAD '${headSha}' — the checkpoint may be stale (e.g. after an amend/rebase). Consider re-sealing (seal-checkpoint) before publishing. This is a warning only — see #335 for the full checkpoint-staleness ownership check.`);
+                }
+            }
+        }
+    }
+    catch {
+        // best-effort only — never affects ok/exit code.
+    }
+    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, tr);
+    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
@@ -2679,6 +3402,28 @@ 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 (SECOND, DISTINCT fail-closed gate): immediately after the shape check above and BEFORE
+ * writing anything into delivery/, runs `runVerifyHold()` — the assignment ⋈ liveness join
+ * asking "is the calling actor the fresh, non-superseded holder of this subject (or is it
+ * free/self-held)?" A not-fresh-holder result throws `NotFreshHolderError` (distinct from
+ * `InvalidBundleShapeError` — a different `code`, a different failure mode: actor hold vs
+ * bundle shape). There are now THREE tiers here, and they must never be conflated in prose or
+ * in a call site's catch handler: (1) fail-SOFT bundle absence / repo-root resolution (silent
+ * no-op / visible warning, unchanged from before #356), (2) fail-CLOSED bundle shape (#356,
+ * `InvalidBundleShapeError`), (3) fail-CLOSED verify-hold (#293, `NotFreshHolderError`). The
+ * shape check runs first (per the plan's ordering) — a bundle that is BOTH shape-invalid and
+ * not-held throws `InvalidBundleShapeError` specifically, never `NotFreshHolderError`.
  */
 export async function publishDelivery(dir, repoRoot) {
     const bundleSrc = path.join(dir, "trust.bundle");
@@ -2688,6 +3433,29 @@ export async function publishDelivery(dir, repoRoot) {
         process.stderr.write(`[publish-delivery] WARNING: no kits/ ancestor found from ${dir}; skipping publish. Refusing to fall back to process.cwd() to avoid clobbering an unrelated repo's delivery/ seal. Pass --repo-root explicitly if this session dir is intentionally outside a repo checkout.\n`);
         return;
     }
+    // #356 AC6: fail-CLOSED on shape-invalidity — runs AFTER the fail-soft absence/repo-root
+    // guards above (both preserved unchanged) and BEFORE any copy into delivery/. Throws
+    // InvalidBundleShapeError (never a generic Error) so every call site can positively
+    // distinguish this from the failure modes they already tolerate as best-effort.
+    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: SECOND, DISTINCT fail-closed gate — runs after the shape check above and before any
+    // copy into delivery/. Throws NotFreshHolderError (never conflated with InvalidBundleShapeError)
+    // so every call site can positively distinguish "not the fresh holder" from "bundle shape
+    // invalid".
+    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);
+    }
     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
@@ -3948,6 +4716,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}`);
         }
     });