@kontourai/flow-agents 3.1.0 → 3.3.0

package/src/cli/workflow-sidecar.ts

@@ -219,9 +219,17 @@ function resolveEnsureSessionActor(p: ReturnType<typeof parseArgs>): { actorStru
     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: 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 };
 }
@@ -1416,6 +1424,11 @@ function enforceEnsureSessionOwnership(
   // 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: unknown): string => 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: unknown): string => 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");
 
@@ -1495,15 +1508,32 @@ function enforceEnsureSessionOwnership(
       const assignment = readLocalAssignmentStatus(root, slug);
       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": {
@@ -1619,7 +1649,30 @@ function recordAgentEvent(p: ReturnType<typeof parseArgs>): number {
   if (hasExplicitRoot || !explicit) requireArtifactDirUnderRoot(dir, root);
   const timestamp = opt(p, "timestamp", now());
   const agent = validateAgentId(opt(p, "agent-id"));
-  const event = { timestamp, agent_id: agent, kind: opt(p, "kind", "note"), status: opt(p, "status", "info"), summary: opt(p, "summary"), ...(opt(p, "ref") ? { ref: opt(p, "ref") } : {}) };
+  // #376 model routing: optionally stamp the delegate role/model resolved from
+  // .datum/config.json onto the event so a downstream economics record (#349)
+  // can price role assignments per delegation, and so an escalate-on-gate-failure
+  // re-dispatch records which tier it climbed FROM. Fully additive/optional: when
+  // no routing flag is passed the event shape is byte-identical to before.
+  // These live as TOP-LEVEL event fields (not nested) on purpose: appendJsonl's
+  // serializer (spacedLine) uses the top-level key list as a JSON.stringify array
+  // replacer, which is an allowlist applied at every nesting level — a nested
+  // routing object would have its inner keys stripped. Flat keeps the shape a
+  // simple per-event routing record a JSONL economics feed can read directly.
+  const role = opt(p, "role");
+  const model = opt(p, "model");
+  const escalatedFrom = opt(p, "escalated-from");
+  const event = {
+    timestamp,
+    agent_id: agent,
+    kind: opt(p, "kind", "note"),
+    status: opt(p, "status", "info"),
+    summary: opt(p, "summary"),
+    ...(opt(p, "ref") ? { ref: opt(p, "ref") } : {}),
+    ...(role ? { role } : {}),
+    ...(model ? { model } : {}),
+    ...(escalatedFrom ? { escalated_from: escalatedFrom } : {}),
+  };
   appendJsonl(path.join(dir, "agents", agent, "events.jsonl"), event);
   updateCurrentAgent(root, dir, agent, event.status, timestamp, actorKey);
   return 0;
@@ -1856,6 +1909,14 @@ function checksFromBundle(dir: string): AnyObj[] {
   const seen = new Set<string>();
   const checks: AnyObj[] = [];
   const kindOf = (claim: AnyObj): string => String((claim.metadata as AnyObj).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: AnyObj): AnyObj | undefined => {
+    const md = claim.metadata as AnyObj;
+    return md && typeof md === "object" && md.waiver && typeof md.waiver === "object" ? md.waiver as AnyObj : undefined;
+  };
   for (const ev of bundle.evidence) {
     if (!ev || !ev.claimId) continue;
     const claim = claimById.get(ev.claimId);
@@ -1868,6 +1929,8 @@ function checksFromBundle(dir: string): AnyObj[] {
     const check: AnyObj = { id: String(claim.subjectId || "").split("/").pop() || ev.claimId, kind, status, summary: claim.fieldOrBehavior || "" };
     if (ev.execution && typeof ev.execution.label === "string") 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).
@@ -1877,7 +1940,10 @@ function checksFromBundle(dir: string): AnyObj[] {
     if (seen.has(claim.id)) 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: AnyObj = { 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;
 }
@@ -2142,7 +2208,13 @@ async function promote(p: ReturnType<typeof parseArgs>): Promise<number> {
   // 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: unknown) => {
+      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`);
     });
   }
@@ -2210,8 +2282,14 @@ async function advanceState(p: ReturnType<typeof parseArgs>): Promise<number> {
     // 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: unknown) => {
+      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`);
     });
   }
@@ -2300,8 +2378,14 @@ async function recordRelease(p: ReturnType<typeof parseArgs>): Promise<number> {
   // 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: unknown) => {
+    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;
@@ -2516,6 +2600,754 @@ async function sealCheckpoint(p: ReturnType<typeof parseArgs>): Promise<number>
   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(): {
+  classifyBundleClaims: (bundle: AnyObj) => {
+    reconcilable: AnyObj[];
+    sessionLocal: AnyObj[];
+    noEvidenceCommand: AnyObj[];
+    waiverOnCommand: AnyObj[];
+  };
+  normalizeCmd: (cmd: string) => string;
+  waiverOnCommandIssues: (waiverOnCommand: AnyObj[]) => AnyObj[];
+  noEvidenceCommandIssues: (noEvidenceCommand: AnyObj[]) => AnyObj[];
+  reconcilableManifestIssues: (reconcilable: AnyObj[], manifestByCmd: Map<string, AnyObj>) => { issues: AnyObj[]; unresolved: AnyObj[] };
+  sessionLocalShapeIssues: (
+    sessionLocal: AnyObj[],
+    derivedStatus: Map<string, string | null> | null,
+    opts?: { onUnderivable?: "fail" | "reduce" }
+  ) => { issues: AnyObj[]; attestedCount: number; logEvents: AnyObj[] };
+} {
+  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(): {
+  resolveManifest: (args: { manifest?: string | null }, repoRoot: string, canonicalCommands: string[]) => { entries: Array<{ id: string; command: string }>; source: string };
+  runBaselineManifest: (repoRoot: string) => Array<{ id: string; command: string }> | null;
+  normalizeManifestEntries: (raw: unknown) => Array<{ id: string; command: string }> | null;
+  slugifyLabel: (s: string) => string;
+  normalizeCmd: (cmd: string) => string;
+  isAncestorCommit: (repoRoot: string, ancestorSha: string, descendantSha: string) => boolean;
+  resolveCanonicalCommands: (args: { commands: string[] }, repoRoot: string) => string[] | null;
+} {
+  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: string, repoRoot: string): Map<string, string | null> | null {
+  const helper = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/ci/derive-claim-status.mjs");
+  if (!fs.existsSync(helper)) return null;
+  let stdout: string;
+  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<string, string | null>();
+    for (const [k, v] of Object.entries(obj)) m.set(k, v as string | null);
+    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 {
+  readonly code = "RECONCILE_PREFLIGHT_INVALID_SHAPE" as const;
+  readonly issues: string[];
+  constructor(issues: string[]) {
+    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 {
+  readonly code = "VERIFY_HOLD_NOT_FRESH_HOLDER" as const;
+  readonly effective_state: EffectiveState | "not_evaluated";
+  readonly holder?: { actor?: string; assignee?: string | null; idle_days?: number | null; last_at?: string };
+  readonly reason: string;
+  readonly guidance: string[];
+  constructor(result: { effective_state: EffectiveState | "not_evaluated"; holder?: { actor?: string; assignee?: string | null; idle_days?: number | null; last_at?: string }; reason: string; guidance: string[] }) {
+    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: string): string {
+  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)
+ */
+type TrustReconcileHelper = ReturnType<typeof loadTrustReconcileHelper>;
+
+/**
+ * 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: string, repoRoot: string, tr: TrustReconcileHelper): string[] {
+  const warnings: string[] = [];
+  try {
+    const checkpointPath = path.join(dir, "trust.checkpoint.json");
+    if (fs.existsSync(checkpointPath)) {
+      const checkpoint = loadJson(checkpointPath);
+      const commitSha = checkpoint && typeof checkpoint === "object" ? (checkpoint as AnyObj).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: string,
+  repoRoot: string,
+  manifestOverride?: string | null
+): { ok: boolean; issues: string[]; warnings: string[] } {
+  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<string, AnyObj>();
+  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: AnyObj[] = [];
+  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: ReturnType<typeof parseArgs>): Promise<number> {
+  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: string,
+  repoRoot: string | null,
+  opts?: { actorKey?: string; now?: number; assignmentProviderKind?: string; effectiveStateJson?: unknown },
+): {
+  ok: boolean;
+  effective_state: EffectiveState | "not_evaluated";
+  holder?: { actor?: string; assignee?: string | null; idle_days?: number | null; last_at?: string };
+  reason: string;
+  guidance: string[];
+} {
+  // 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: unknown): string => 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?: string): string[] => [
+    "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.",
+  ];
+
+  type EffectiveResult = { effective_state: EffectiveState; reason: string; holder?: { actor?: string; assignee?: string | null; idle_days?: number | null; last_at?: string } };
+  let effective: EffectiveResult | null = null;
+
+  if (opts?.effectiveStateJson !== undefined) {
+    const parsed = opts.effectiveStateJson as AnyObj;
+    const candidate = parsed && typeof parsed === "object" ? (parsed.effective as AnyObj | undefined) : undefined;
+    const validStates = new Set(["held", "reclaimable", "human-held", "free"]);
+    if (candidate && typeof candidate.effective_state === "string" && validStates.has(candidate.effective_state)) {
+      effective = candidate as EffectiveResult;
+    }
+  } 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: { actor?: string; assignee?: string | null; idle_days?: number | null; last_at?: string } | undefined,
+  ): { actor?: string; assignee?: string | null; idle_days?: number | null; last_at?: string } | undefined => {
+    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: ReturnType<typeof parseArgs>): Promise<number> {
+  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: string,
+  opts?: { actorKey?: string; now?: number; graceSeconds?: number },
+): {
+  ok: boolean;
+  action: "grace-then-supersede" | "back-off" | "claim" | "ask-first" | "proceed";
+  effective_state: EffectiveState;
+  reason: string;
+  holder?: { actor?: string; last_at?: string };
+  resume_branch?: string;
+  grace_seconds?: number;
+  next_steps: string[];
+} {
+  const sanitize = (value: unknown): string => 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: unknown): string => 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: ReturnType<typeof parseArgs>): Promise<number> {
+  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
@@ -2526,52 +3358,164 @@ async function sealCheckpoint(p: ReturnType<typeof parseArgs>): Promise<number>
 // 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.
+ *
+ * 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.
+ */
+function pruneSupersededSeals(deliveryDir: string, keepSlug: string): void {
+  let entries: fs.Dirent[] = [];
+  try {
+    entries = fs.readdirSync(deliveryDir, { withFileTypes: 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`);
+    }
+  }
+}
+
 /**
  * Publish the session's trust artifacts to the committed delivery/ path.
  *
+ * #379: writes to a PER-SESSION path `<repoRoot>/delivery/<slug>/` (slug = the session
+ * artifact dir's basename) rather than the shared flat `delivery/`. A shared path guarantees
+ * a git conflict between ANY two concurrent deliveries, and a conflicting (DIRTY) PR gets NO
+ * pull_request workflows — the required Trust Reconcile check silently never runs (field
+ * incidents #330/#358/#378). Per-session paths make concurrent deliveries write DISTINCT
+ * files that never contend. trust-reconcile.js reads both the flat (back-compat) and
+ * per-session layouts via resolveDeliveryCandidates() and selects the owning candidate by
+ * commit ancestry.
+ *
  * Copies trust.bundle, trust.checkpoint.json, and (if present)
- * trust.checkpoint.intoto.json / trust.checkpoint.sig.json from the
- * session artifact dir to <repoRoot>/delivery/.
+ * trust.checkpoint.intoto.json / trust.checkpoint.sig.json / trust.checkpoint.attestation.json
+ * from the session artifact dir to <repoRoot>/delivery/<slug>/.
  *
  * Fail-soft on a missing bundle: if trust.bundle is absent, returns without throwing.
  * Fail-CLOSED on repo-root resolution: repoRoot must be a real, resolved kits/ ancestor
  * (see findRepoRootFromDirStrict) — null (no ancestor found) skips the publish with a
  * visible warning instead of writing to whatever process.cwd() happens to be. This
  * prevents a scratch/test session dir (no kits/ ancestor) from silently clobbering an
- * unrelated real repo's delivery/trust.bundle when invoked with that repo as cwd (see
+ * unrelated real repo's delivery/ seal when invoked with that repo as cwd (see
  * 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.
+ * 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: string, repoRoot: string | null): Promise<void> {
   const bundleSrc = path.join(dir, "trust.bundle");
   if (!fs.existsSync(bundleSrc)) return; // no bundle — skip gracefully
 
   if (!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/trust.bundle. Pass --repo-root explicitly if this session dir is intentionally outside a repo checkout.\n`);
+    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
+  // a collision-avoidance handle; ownership is decided by commit ancestry, not by name.
+  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).
+  pruneSupersededSeals(deliveryDir, slug);
+  fs.mkdirSync(sessionDeliveryDir, { recursive: true });
 
   // Required: trust.bundle (the CI anchor)
-  fs.copyFileSync(bundleSrc, path.join(deliveryDir, "trust.bundle"));
+  fs.copyFileSync(bundleSrc, path.join(sessionDeliveryDir, "trust.bundle"));
 
   // Optional companions: checkpoint + signing artifacts
   const companions = [
     "trust.checkpoint.json",
     "trust.checkpoint.intoto.json",
     "trust.checkpoint.sig.json",
+    "trust.checkpoint.attestation.json",
   ];
   for (const filename of companions) {
     const src = path.join(dir, filename);
     if (fs.existsSync(src)) {
-      fs.copyFileSync(src, path.join(deliveryDir, filename));
+      fs.copyFileSync(src, path.join(sessionDeliveryDir, filename));
     }
   }
 
-  process.stderr.write(`[publish-delivery] published trust.bundle and companions to ${deliveryDir}\n`);
+  process.stderr.write(`[publish-delivery] published trust.bundle and companions to ${sessionDeliveryDir} (per-session path, #379)\n`);
 }
 
 /**
@@ -3330,7 +4274,7 @@ function loadLivenessReadHelper(): {
 // init-plan claims the work-item; advance-state heartbeats (or releases on terminal),
 // so the workflow lifecycle itself maintains the liveness claim — no manual liveness calls.
 // Additive + fail-open: a liveness-emit failure never affects the workflow command.
-const LIVENESS_TERMINAL = new Set(["delivered", "accepted", "archived"]);
+export const LIVENESS_TERMINAL = new Set(["delivered", "accepted", "archived"]);
 /**
  * Delegate to the shared pure-CJS resolver (scripts/hooks/lib/actor-identity.js), mirroring the
  * createRequire pattern used by readLivenessEvents() above. Deliberately NO inline duplicate
@@ -3350,6 +4294,7 @@ function loadActorIdentityHelper(): {
   serializeActor: (actor: Partial<ActorStruct> | undefined) => string;
   detectRuntime: (env: NodeJS.ProcessEnv) => string;
   runtimeSessionId: (env: NodeJS.ProcessEnv) => string;
+  detectCiActor: (env: NodeJS.ProcessEnv) => { runtime: string; session_id: string } | null;
   ancestorActorSeed: () => string;
 } {
   const _req = createRequire(import.meta.url);
@@ -3361,6 +4306,7 @@ function loadActorIdentityHelper(): {
     serializeActor: (actor: Partial<ActorStruct> | undefined) => string;
     detectRuntime: (env: NodeJS.ProcessEnv) => string;
     runtimeSessionId: (env: NodeJS.ProcessEnv) => string;
+    detectCiActor: (env: NodeJS.ProcessEnv) => { runtime: string; session_id: string } | null;
     ancestorActorSeed: () => string;
   };
 }
@@ -3381,12 +4327,14 @@ function resolveLivenessActor(): string {
 function loadLivenessPolicyHelper(): {
   isLivenessEnabled: (env: NodeJS.ProcessEnv) => boolean;
   resolveTtlSeconds: (env: NodeJS.ProcessEnv) => number;
+  resolveHeartbeatThrottleSeconds: (env: NodeJS.ProcessEnv) => number;
 } {
   const _req = createRequire(import.meta.url);
   const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/liveness-policy.js");
   return _req(helperPath) as {
     isLivenessEnabled: (env: NodeJS.ProcessEnv) => boolean;
     resolveTtlSeconds: (env: NodeJS.ProcessEnv) => number;
+    resolveHeartbeatThrottleSeconds: (env: NodeJS.ProcessEnv) => number;
   };
 }
 function livenessEnabled(): boolean { return loadLivenessPolicyHelper().isLivenessEnabled(process.env); }
@@ -3838,6 +4786,9 @@ async function main(): Promise<number> {
       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}`);
     }
   });