@kontourai/flow-agents 2.2.0 → 2.4.0

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

@@ -10,7 +10,7 @@ import { resolveActiveFlowStep, resolveFlowFilePath, resolvePhaseMap, resolveRou
 import { defaultArtifactRootForRead, flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
 export const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
 export const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
-export const checkKinds = new Set(["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]);
+export const checkKinds = new Set(["build", "types", "lint", "test", "command", "security", "diff", "browser", "runtime", "policy", "external"]);
 export const checkStatuses = new Set(["pass", "fail", "not_verified", "skip"]);
 export const verdicts = new Set(["pass", "partial", "fail", "not_verified"]);
 function now() { return new Date().toISOString().replace(/\.\d{3}Z$/, "Z"); }
@@ -48,6 +48,162 @@ function workItemSlug(ref) {
     const [owner, repo] = parts;
     return slugify(`${owner}-${repo}-${id}`, "work-item");
 }
+/** Pure, lock-free, side-effect-free CLI wrapper around workItemSlug() — the single source of
+ * truth for the deterministic subjectId/session-directory-name slug. Named resolveSlugCmd (not
+ * resolveSlug) to avoid colliding with any future export named resolveSlug. */
+function resolveSlugCmd(p) {
+    const ref = p.positional[0] || die("resolve-slug requires an owner/repo#id ref");
+    console.log(workItemSlug(ref));
+    return 0;
+}
+/** First 6 hex chars of sha256(raw) — a short deterministic disambiguator (#289 F4). Two
+ * different raw inputs that both collapse to a segment's "unknown" fallback (e.g. two distinct
+ * all-garbage --task-slug values, or two distinct raw actor strings that both resolve
+ * "unresolved") would otherwise derive the identical fallback branch — this makes them diverge
+ * while staying fully deterministic for a given raw input (same raw -> same hash every call),
+ * which is required to preserve resolveSessionBranch's no-rederive/resume-continuity semantics
+ * (a resumed session's already-recorded branch is never recomputed regardless of this helper). */
+function unknownDisambiguator(raw) {
+    return createHash("sha256").update(raw).digest("hex").slice(0, 6);
+}
+/** Encode a value (actor string or --task-slug, neither guaranteed git-ref-safe) into a
+ * single git-check-ref-format(1)-safe branch path component (#289). Reuses
+ * actor-identity.js's sanitizeSegment (consume, don't fork) as the base, then closes the
+ * git-specific gaps sanitizeSegment's [A-Za-z0-9_.-] charset does not: the `:` delimiter
+ * serializeActor() uses (disallowed in a git ref), consecutive dots, a leading dot, a trailing
+ * dot (fix-plan iteration 1 F1 — git-check-ref-format forbids a component ending in `.`, and
+ * the prior pass only handled a run of 2+ trailing dots via the `..`-collapse step, missing the
+ * single-trailing-dot case e.g. a `--task-slug` of `my-fix.`), and a trailing `.lock`. The
+ * trailing-dot strip runs BEFORE the `.lock` rewrite so a `.lock` suffix hidden behind trailing
+ * dots (e.g. `foo.lock.`) is exposed and still rewritten rather than left dangling. Whenever the
+ * FINAL sanitized segment equals the fallback token `"unknown"` — whether because the charset
+ * filter collapsed the raw input to nothing, OR because the leading-/trailing-dot stripping
+ * above collapsed a near-miss input like `"unknown."` or `".unknown"` down to the literal
+ * `"unknown"`, OR because the raw input genuinely WAS the literal string `"unknown"` — a
+ * deterministic disambiguator (see unknownDisambiguator) is ALWAYS appended (fix-plan iteration 2
+ * F4': no literal-input carve-out). Distinct raw inputs can never collide on the bare literal
+ * `"unknown"` segment; the same raw input always re-derives the same disambiguated segment. See
+ * Design Decision 2 in the plan. */
+function sanitizeBranchSegment(value, helper) {
+    const raw = String(value ?? "");
+    const colonReplaced = raw.replace(/:/g, "-");
+    let seg = helper.sanitizeSegment(colonReplaced);
+    seg = seg.replace(/\.{2,}/g, "-").replace(/^\.+/, "").replace(/\.+$/, "").replace(/\.lock$/i, "-lock");
+    if (!seg || seg === "unknown")
+        return `unknown-${unknownDisambiguator(raw)}`;
+    return seg;
+}
+/** Validate an explicit `--branch` value strictly rather than trusting it verbatim (fix-plan
+ * iteration 1 F2, tightened by iteration 2 F2'). Explicit `--branch` bypasses
+ * `sanitizeBranchSegment` entirely by design (it is caller intent, may legitimately contain `/`
+ * to nest under `agent/...`, etc.), so unlike the derived path it must be rejected outright — not
+ * silently sanitized — when it cannot be a valid git ref. Whole-string checks (iteration 1):
+ * any control character/newline, a space, a leading or trailing `/`, a `//` sequence, a leading
+ * `.`, any `..` sequence, a trailing `.`, a trailing `.lock`, or any character outside
+ * `[A-Za-z0-9_./-]`. Per-component checks (iteration 2 F2'): the whole-string checks above only
+ * examine the START/END of the full value, so a charset-legal value can still smuggle an invalid
+ * `/`-delimited component past them — e.g. `"-lead"` (a leading `-` breaks the whole git ref,
+ * applied uniformly to every component here — stricter than git strictly requires, which is fine
+ * for a caller-facing override flag), `"a/.b"` (a non-first component starting with `.`),
+ * `"foo.lock/bar"` (a non-last component ending in `.lock`), or `"a/./b"` (a component that is
+ * exactly `.`). Belt-and-braces (F2'): once the lexical checks above all pass, `git
+ * check-ref-format --branch <value>` (the real git binary) is run as the final authority — it can
+ * only ever REJECT a value the lexical checks let through (never re-legalize one they rejected),
+ * so it closes any residual gap in this hand-rolled lexical pass. When git cannot be spawned at
+ * all (e.g. not installed — `ENOENT`) or does not complete (e.g. the 5s timeout fires), the git
+ * check is skipped silently and the lexical checks above remain the sole authority. Dies with
+ * remediation, or with git's own rejection message; never mutates any artifact before this check
+ * runs (resolveSessionBranch calls this before any file write). */
+function validateExplicitBranch(value) {
+    const remediation = `Pass a --branch value matching [A-Za-z0-9_./-], with no leading/trailing "/", no "//", no leading ".", no ".." sequence, and no trailing "." or ".lock" (got: ${JSON.stringify(value)}).`;
+    const fail = (reason) => die(`ensure-session --branch value is not a valid git ref: ${reason}. ${remediation}`);
+    if (/[\x00-\x1F\x7F]/.test(value))
+        fail("contains a control character or newline");
+    if (/ /.test(value))
+        fail("contains a space");
+    if (value.startsWith("/") || value.endsWith("/"))
+        fail('must not start or end with "/"');
+    if (value.includes("//"))
+        fail('must not contain "//"');
+    if (value.startsWith("."))
+        fail('must not start with "."');
+    if (value.includes(".."))
+        fail('must not contain a ".." sequence');
+    if (value.endsWith("."))
+        fail('must not end with "."');
+    if (/\.lock$/i.test(value))
+        fail('must not end with ".lock"');
+    if (/[^A-Za-z0-9_./-]/.test(value))
+        fail("contains a character outside [A-Za-z0-9_./-]");
+    // F2' per-component checks: split on "/" and validate each path component individually. The
+    // whole-string checks above cannot catch a hostile component that is not at the very start or
+    // end of the full value.
+    for (const component of value.split("/")) {
+        if (!component)
+            fail('must not contain an empty path component ("//" or a leading/trailing "/")');
+        if (component === ".")
+            fail('must not contain a path component that is exactly "."');
+        if (component.startsWith("."))
+            fail('must not contain a path component starting with "."');
+        if (component.startsWith("-"))
+            fail('must not contain a path component starting with "-"');
+        if (component.endsWith("."))
+            fail('must not contain a path component ending with "."');
+        if (/\.lock$/i.test(component))
+            fail('must not contain a path component ending with ".lock"');
+    }
+    // F2' belt-and-braces: the real `git check-ref-format --branch` binary is the final authority
+    // when git is available. This can only REJECT a value that already passed every lexical check
+    // above — it never re-legalizes a value the lexical checks rejected (those `fail()` calls
+    // above already threw). argv-array form (no shell) with a 5s timeout so a hung or missing git
+    // binary cannot hang or crash session creation.
+    let result;
+    try {
+        execFileSync("git", ["check-ref-format", "--branch", value], { stdio: ["ignore", "ignore", "pipe"], timeout: 5000 });
+        return; // exit 0 — git accepts the value; nothing further to check.
+    }
+    catch (err) {
+        const spawnError = err;
+        if (spawnError && spawnError.code === "ENOENT")
+            return; // git not installed — lexical checks stand alone.
+        if (spawnError && typeof spawnError.status === "number") {
+            result = { status: spawnError.status, stderr: spawnError.stderr ?? "" };
+        }
+        else
+            return; // Any other spawn failure (e.g. timeout) — skip silently; lexical checks already passed.
+    }
+    if (result && result.status !== 0) {
+        const gitMessage = String(result.stderr ?? "").trim();
+        fail(gitMessage ? `git check-ref-format rejected the value: ${gitMessage}` : "git check-ref-format rejected the value");
+    }
+}
+/** Resolve the branch to seed a brand-new session with. Only called from ensureSession's
+ * `if (!md)` fresh-creation branch — an existing session's already-recorded branch is never
+ * recomputed (ADR 0021 §5 takeover continuity; see Design Decision 3). Precedence: explicit
+ * --branch (strictly validated, then honored verbatim — see F2) > derived agent/<actor>/<slug>.
+ * Never hard-fails session creation on actor-resolution ambiguity (Design Decision 4) — only a
+ * garbage explicit --actor, or a garbage explicit --branch, dies. */
+function resolveSessionBranch(p, slug) {
+    // Deliberately NOT trimmed before validation (unlike the pre-F2 baseline): a leading/trailing
+    // space must be REJECTED, not silently trimmed away — silent trimming would let a
+    // caller-supplied value differ from what gets recorded without any diagnostic (F2).
+    const explicitBranch = opt(p, "branch");
+    if (explicitBranch) {
+        validateExplicitBranch(explicitBranch);
+        return explicitBranch;
+    }
+    const helper = loadActorIdentityHelper();
+    const explicitActorRaw = opt(p, "actor", "").trim();
+    if (explicitActorRaw && !/[A-Za-z0-9_.-]/.test(explicitActorRaw)) {
+        die("ensure-session --actor value strips to empty under the allowed actor charset ([A-Za-z0-9_.-]) — pass a value containing at least one letter, digit, underscore, period, or hyphen.");
+    }
+    const actor = explicitActorRaw ? helper.sanitizeSegment(explicitActorRaw) : helper.resolveActor(process.env).actor;
+    const unresolved = helper.isUnresolvedActor(actor);
+    const safeActor = unresolved ? `unknown-actor-${unknownDisambiguator(actor)}` : sanitizeBranchSegment(actor, helper);
+    if (unresolved)
+        process.stderr.write("[ensure-session] actor unresolved; branch uses \"unknown-actor\" segment (set --actor or FLOW_AGENTS_ACTOR for a stable branch name)\n");
+    return `agent/${safeActor}/${sanitizeBranchSegment(slug, helper)}`;
+}
 /**
  * Validate a Hachure trust.bundle using @kontourai/surface's canonical validator
  * (surface is the authoritative owner of trust-bundle schema validation per ADR 0010 / ADR 0015).
@@ -180,6 +336,47 @@ function criterionStatusToEventStatus(status) {
         return "assumed";
     return null; // pending / not_verified → no event → Surface returns "unknown"
 }
+/**
+ * WS8 (ADR 0020): Derive Surface evidence classification (evidenceType + method)
+ * from a workflow check's kind, replacing the previous hardcoded `test_output`.
+ * Only command-backed re-runnable checks are `test_output` (CI-reconcilable);
+ * everything else is inherently session-local (manual attestation, provider/
+ * document citation, crawl observation, policy rule, source excerpt). The
+ * `reconcilable` flag is informational — the CI reconciler classifies purely by
+ * the emitted `evidenceType`. Every value is a member of Surface's own
+ * evidence.schema.json `evidenceType`/`method` enums (consume-never-fork).
+ */
+function classifyEvidence(kind, hasCommand) {
+    const k = String(kind ?? "external");
+    switch (k) {
+        case "build":
+        case "types":
+        case "lint":
+        case "test":
+        case "command":
+            return { evidenceType: "test_output", method: "validation", reconcilable: true };
+        case "security":
+            return hasCommand
+                ? { evidenceType: "test_output", method: "validation", reconcilable: true }
+                : { evidenceType: "attestation", method: "corroboration", reconcilable: false };
+        case "diff":
+            return { evidenceType: "source_excerpt", method: "extraction", reconcilable: false };
+        case "browser":
+            return hasCommand
+                ? { evidenceType: "test_output", method: "validation", reconcilable: true }
+                : { evidenceType: "crawl_observation", method: "observation", reconcilable: false };
+        case "runtime":
+            return hasCommand
+                ? { evidenceType: "test_output", method: "validation", reconcilable: true }
+                : { evidenceType: "attestation", method: "attestation", reconcilable: false };
+        case "policy":
+            return { evidenceType: "policy_rule", method: "auditability", reconcilable: false };
+        case "external":
+            return { evidenceType: "attestation", method: "corroboration", reconcilable: false };
+        default:
+            return { evidenceType: "test_output", method: "validation", reconcilable: true };
+    }
+}
 /** Map a critique verdict to the Surface VerificationEvent status. */
 function critiqueToEventStatus(verdict, findings) {
     if (verdict === "fail")
@@ -221,14 +418,29 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
     const evidenceItems = [];
     const events = [];
     const ts = timestamp || new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
-    // One VerificationPolicy per distinct claimType, so status is policy-governed
-    // (not derived against an empty policy set). Maximal-fidelity per ADR 0010.
+    // One VerificationPolicy per distinct (claimType, requiredEvidence) pair, so status is
+    // policy-governed (not derived against an empty policy set). Maximal-fidelity per ADR 0010.
+    //
+    // WS8 (AC1, iteration 2): the cache is keyed by claimType + the normalized requiredEvidence
+    // set, NOT by claimType alone. Two checks of the same legacy claimType that differ in
+    // command-presence (e.g. a command-backed browser check → requiredEvidence [test_output]
+    // vs a no-command browser check → [crawl_observation]) previously COLLIDED: the first-seen
+    // requiredEvidence won and corrupted the second claim's derived status (verified → proposed)
+    // in a record-order-dependent way. Keying by (claimType, requiredEvidence) makes policy
+    // construction order-independent — each distinct evidence signature gets its own policy, and
+    // each claim references its own via verificationPolicyId (Surface's resolvePolicyForClaim
+    // honors verificationPolicyId first, so same-claimType policies never cross-resolve).
+    // Merging is NOT used because Surface's requiredEvidence is all-of (`.every`), so a union
+    // would over-constrain both claims.
     const policies = new Map();
     const ensurePolicy = (claimType, impactLevel, requiredEvidence) => {
-        let p = policies.get(claimType);
+        const reqSorted = [...new Set(requiredEvidence)].sort();
+        const key = `${claimType}::${reqSorted.join(",")}`;
+        let p = policies.get(key);
         if (!p) {
-            p = { id: `policy:${claimType}`, claimType, requiredEvidence, acceptanceCriteria: [`A verified verification event must support a ${claimType} claim.`], reviewAuthority: "system", validityRule: { kind: "manual" }, stalenessTriggers: [], conflictRules: [], impactLevel };
-            policies.set(claimType, p);
+            const id = reqSorted.length ? `policy:${claimType}:${reqSorted.join("+")}` : `policy:${claimType}`;
+            p = { id, claimType, requiredEvidence: reqSorted, acceptanceCriteria: [`A verified verification event must support a ${claimType} claim.`], reviewAuthority: "system", validityRule: { kind: "manual" }, stalenessTriggers: [], conflictRules: [], impactLevel };
+            policies.set(key, p);
         }
         return p;
     };
@@ -349,37 +561,60 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         const claimId = generateClaimId(subjectId, "flow-agents.workflow", fieldOrBehavior);
         const evId = `ev:${claimId}`;
         const legacyClaimType = `workflow.check.${check.kind ?? "external"}`;
-        const policy = ensurePolicy(legacyClaimType, "high", ["test_output"]);
         const cmd = typeof check.command === "string" ? check.command.replace(/\s+/g, " ").trim() : "";
         const captured = cmd ? captureByCommand.get(cmd) : undefined;
+        // WS8 (ADR 0020): classify evidence from check.kind instead of hardcoding test_output.
+        // A waived accepted-gap (check._waiver, set by record-evidence/record-gate-claim
+        // --accepted-gap-reason/--waived-by) is by definition session-local: it is an
+        // attested accepted gap, never a CI-re-runnable command, so it is classified
+        // attestation/attestation and its claim status is forced to `assumed` (reusing the
+        // existing accepted_gap -> assumed mapping — no new status value).
+        const waiver = (check._waiver && typeof check._waiver === "object") ? check._waiver : null;
+        const evClass = waiver
+            ? { evidenceType: "attestation", method: "attestation", reconcilable: false }
+            : classifyEvidence(check.kind, cmd.length > 0);
+        const policy = ensurePolicy(legacyClaimType, "high", [evClass.evidenceType]);
         const effectiveStatus = captured ? captured.observedResult : String(check.status ?? "");
-        const evStatus = checkStatusToEventStatus(effectiveStatus);
+        const evStatus = waiver ? "assumed" : checkStatusToEventStatus(effectiveStatus);
+        // Promotion claim marker (issue #312): a `promote` check carries a session-local
+        // _promotion object that must survive onto claim.metadata.promotion so the archive gate
+        // (workflow-artifact-cleanup-audit) and validators can detect the promotion claim without a
+        // new manifest entry. It rides alongside any waiver in a single merged metadata object.
+        const promotionMeta = (check._promotion && typeof check._promotion === "object") ? check._promotion : null;
+        const claimMetadata = (waiver || promotionMeta) ? { ...(waiver ? { waiver } : {}), ...(promotionMeta ? { promotion: promotionMeta } : {}) } : null;
         const claimEvents = [];
         if (evStatus) {
             const evt = { id: `evt:${claimId}`, claimId, status: evStatus, actor: "flow-agents/workflow-sidecar", method: "validation", evidenceIds: [evId], createdAt: ts, verifiedAt: ts };
             events.push(evt);
             claimEvents.push(evt);
         }
-        const evItem = { id: evId, claimId, evidenceType: "test_output", method: "validation", sourceRef: `${slug}/evidence.json`, excerptOrSummary: fieldOrBehavior, observedAt: ts, collectedBy: "flow-agents/workflow-sidecar", passing: effectiveStatus === "pass" };
+        const evItem = { id: evId, claimId, evidenceType: evClass.evidenceType, method: evClass.method, sourceRef: `${slug}/evidence.json`, excerptOrSummary: fieldOrBehavior, observedAt: ts, collectedBy: "flow-agents/workflow-sidecar", passing: effectiveStatus === "pass" };
         if (captured) {
             evItem.sourceRef = `${slug}/command-log.jsonl`;
             evItem.collectedBy = "flow-agents/evidence-capture";
             evItem.execution = { runner: "bash", label: cmd, isError: captured.observedResult === "fail", ...(captured.exitCode != null ? { exitCode: captured.exitCode } : {}) };
         }
+        else if (cmd && !waiver) {
+            // WS8 (ADR 0020): always stamp execution.label on command-backed checks so the CI
+            // reconciler has a stable key to match against the manifest, even when the local
+            // command-log capture did not happen to run this command. isError is derived from
+            // the check's own reported status (no captured exit code available in this path).
+            evItem.execution = { runner: "bash", label: cmd, isError: effectiveStatus !== "pass" };
+        }
         evidenceItems.push(evItem);
         // P-d: declared-only when active flow/step present (shadow retired); no-flow path unchanged.
         // When record-gate-claim sets _gate_claim_expectation_id, pass it for exact lookup (ADR 0016 P-d Increment 2).
         const declared = matchExpectsEntry("check", check.kind, typeof check._gate_claim_expectation_id === "string" ? check._gate_claim_expectation_id : undefined);
         if (declared) {
             // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
-            const declaredPolicy = ensurePolicy(declared.claimType, "high", ["test_output"]);
-            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, surface: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: effectiveStatus, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id };
+            const declaredPolicy = ensurePolicy(declared.claimType, "high", [evClass.evidenceType]);
+            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: effectiveStatus, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, ...(claimMetadata ? { metadata: claimMetadata } : {}) };
             const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [evItem], events: claimEvents, policies: [declaredPolicy] });
             claims.push({ ...declaredClaimObj, status: declaredStatus });
         }
         else {
             // No active flow step — only the workflow.* primary claim (legitimate no-flow fallback path).
-            const claimObj = { id: claimId, subjectType: "workflow-check", subjectId, surface: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: effectiveStatus, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: policy.id };
+            const claimObj = { id: claimId, subjectType: "workflow-check", subjectId, facet: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: effectiveStatus, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: policy.id, ...(claimMetadata ? { metadata: claimMetadata } : {}) };
             const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [evItem], events: claimEvents, policies: [policy] });
             claims.push({ ...claimObj, status: derivedStatus });
         }
@@ -405,13 +640,13 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         if (declared) {
             // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
             const declaredPolicy = ensurePolicy(declared.claimType, "high", []);
-            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, surface: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id };
+            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id };
             const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [], events: claimEvents, policies: [declaredPolicy] });
             claims.push({ ...declaredClaimObj, status: declaredStatus });
         }
         else {
             // No active flow step — only the workflow.* primary claim (legitimate no-flow fallback path).
-            const claimObj = { id: claimId, subjectType: "workflow-acceptance-criterion", subjectId, surface: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: policy.id };
+            const claimObj = { id: claimId, subjectType: "workflow-acceptance-criterion", subjectId, facet: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: policy.id };
             const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [], events: claimEvents, policies: [policy] });
             claims.push({ ...claimObj, status: derivedStatus });
         }
@@ -437,19 +672,19 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         if (declared) {
             // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
             const declaredPolicy = ensurePolicy(declared.claimType, "medium", []);
-            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, surface: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: c.verdict, createdAt: ts, updatedAt: ts, impactLevel: "medium", verificationPolicyId: declaredPolicy.id };
+            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: c.verdict, createdAt: ts, updatedAt: ts, impactLevel: "medium", verificationPolicyId: declaredPolicy.id };
             const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [], events: claimEvents, policies: [declaredPolicy] });
             claims.push({ ...declaredClaimObj, status: declaredStatus });
         }
         else {
             // No active flow step — only the workflow.* primary claim (legitimate no-flow fallback path).
-            const claimObj = { id: claimId, subjectType: "workflow-critique", subjectId, surface: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: c.verdict, createdAt: ts, updatedAt: ts, impactLevel: "medium", verificationPolicyId: policy.id };
+            const claimObj = { id: claimId, subjectType: "workflow-critique", subjectId, facet: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: c.verdict, createdAt: ts, updatedAt: ts, impactLevel: "medium", verificationPolicyId: policy.id };
             const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [], events: claimEvents, policies: [policy] });
             claims.push({ ...claimObj, status: derivedStatus });
         }
     }
     return {
-        schemaVersion: 3,
+        schemaVersion: 5,
         source: `flow-agents/workflow-sidecar;statusFunctionVersion=${statusFunctionVersion}`,
         claims,
         evidence: evidenceItems,
@@ -485,7 +720,7 @@ export async function writeTrustBundle(dir, slug, timestamp, checks, criteria, c
             } }).filter((x) => x !== null);
         }
         catch { /* no capture log — fine */ }
-        // ADR 0016 Abstraction A (P-d): pass the .flow-agents dir ONLY when current.json
+        // ADR 0016 Abstraction A (P-d): pass the runtime artifact root ONLY when current.json
         // points to this session (scoped active-flow guard). If current.json.artifact_dir
         // resolves to a different session, pass null — no active-flow claim mapping for this bundle.
         const _flowAgentsDir = path.dirname(dir);
@@ -726,6 +961,19 @@ function definitionAcceptanceLines(markdown) {
     }
     return out;
 }
+/** Extract a top-level `name: value` markdown field's value (e.g. `branch: agent/x/y`), mirroring
+ * this file's own local-regex-parsing convention for section()/definitionAcceptanceLines() (a
+ * near-duplicate of validate-workflow-artifacts.ts's field()/section() helpers — this file
+ * already keeps its own local copy of that pattern rather than sharing a module). `name` is
+ * regex-escaped before interpolation (fix-plan iteration 1 F3), mirroring
+ * validate-workflow-artifacts.ts's own field() escaping verbatim — every current call site
+ * passes a fixed literal (e.g. "branch"), but escaping keeps a future non-literal name from
+ * silently changing match semantics via unescaped regex metacharacters. Returns "" when the
+ * field is absent. */
+function markdownField(markdown, name) {
+    const re = new RegExp(`^${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:\\s*(.+)$`, "m");
+    return re.exec(markdown)?.[1]?.trim() ?? "";
+}
 function parseCriterion(line, index) {
     let text = line.replace(/^-\s+\[[ xX]\]\s*/, "").trim();
     const m = /\s+-\s+Evidence:\s*(.+)$/i.exec(text);
@@ -770,14 +1018,20 @@ function validateAgentId(agent) {
 }
 /**
  * Find the repository root by walking upward from a starting directory to locate
- * the nearest ancestor containing a kits/ subdirectory. Mirrors flow-resolver.ts
- * findRepoRoot, but callable from workflow-sidecar.ts without re-importing the
- * internal helper.
+ * the nearest ancestor containing a kits/ subdirectory, without falling back to
+ * process.cwd(). Returns null when no kits/ ancestor is found within the walk
+ * bound (e.g. a scratch/temp session directory with no repo ancestor at all).
  *
- * ADR 0016 Abstraction A (P-d): used by advance-state and ensure-session to
- * derive repoRoot for resolvePhaseMap calls.
+ * WS5 iteration-2 part 2: extracted so publishDelivery's repo-root resolution can
+ * be fail-closed (see findRepoRootFromDir below and publishDelivery). A scratch
+ * test session dir (mktemp -d, no kits/ ancestor) must never resolve to whatever
+ * repo happens to be the current process's cwd — that previously let a throwaway
+ * eval-local trust.bundle silently clobber this real repo's delivery/trust.bundle
+ * when the eval was run from a checkout of this repo (see
+ * evals/integration/test_checkpoint_signing.sh TEST 2 and the WS5 session findings
+ * at .kontourai/flow-agents/ws5-governance-kit-slice1).
  */
-function findRepoRootFromDir(startDir) {
+function findRepoRootFromDirStrict(startDir) {
     let dir = startDir;
     for (let i = 0; i < 16; i++) {
         if (fs.existsSync(path.join(dir, "kits")))
@@ -787,7 +1041,23 @@ function findRepoRootFromDir(startDir) {
             break;
         dir = parent;
     }
-    return process.cwd();
+    return null;
+}
+/**
+ * Find the repository root by walking upward from a starting directory to locate
+ * the nearest ancestor containing a kits/ subdirectory. Mirrors flow-resolver.ts
+ * findRepoRoot, but callable from workflow-sidecar.ts without re-importing the
+ * internal helper. Falls back to process.cwd() when no kits/ ancestor is found —
+ * appropriate for phase-map/first-step resolution (ADR 0016 Abstraction A, P-d),
+ * where the caller is always invoked from within a real repo checkout.
+ *
+ * Do NOT use this cwd-falling-back variant for publishDelivery's repo-root
+ * resolution — use findRepoRootFromDirStrict there instead, so a scratch/test
+ * session dir with no repo ancestor fails closed (skips publish) rather than
+ * silently trusting process.cwd(), which could be an unrelated real repo.
+ */
+function findRepoRootFromDir(startDir) {
+    return findRepoRootFromDirStrict(startDir) ?? process.cwd();
 }
 /**
  * Resolve the first step id from a FlowDefinition's steps[] list.
@@ -824,7 +1094,11 @@ function resolveFirstStep(flowId, repoRoot) {
         return null;
     }
 }
-function writeCurrent(root, dir, timestamp, owner, source, flowId, stepId) {
+function writeCurrent(root, dir, timestamp, owner, source, flowId, stepId, adHocReason) {
+    // #289: mirror the active session's already-recorded branch (state.json.branch) into
+    // current.json so consumers of current.json (which has no schema of its own — not one of the
+    // 9 schemas under schemas/) see the routing branch without re-reading state.json separately.
+    const branch = loadJson(path.join(dir, "state.json")).branch;
     writeJson(path.join(root, "current.json"), {
         schema_version: "1.0",
         active_slug: path.basename(dir),
@@ -833,11 +1107,17 @@ function writeCurrent(root, dir, timestamp, owner, source, flowId, stepId) {
         owner,
         source,
         active_agents: [],
+        ...(branch ? { branch } : {}),
         // ADR 0016 Abstraction A (P-a): optional FlowDefinition routing keys for the producer
         // and enforcer. Both fields are optional and backward-compatible — sessions without a
         // FlowDefinition omit them and fall through to the workflow.* claim type path.
         ...(flowId ? { active_flow_id: flowId } : {}),
         ...(stepId ? { active_step_id: stepId } : {}),
+        // WS8 (AC12): sanctioned ad-hoc direct entry marker. Set when --step-id explicitly
+        // targets a step other than the flow's resolved first step, so stop-goal-fit /
+        // gate-review can distinguish an intentional direct entry (e.g. a planning-only
+        // session that skips pull-work) from a stale/mis-stamped active_step_id.
+        ...(adHocReason ? { ad_hoc_entry: true, ad_hoc_reason: adHocReason } : {}),
     });
 }
 function loadCurrent(root) {
@@ -851,7 +1131,15 @@ function currentDir(root) {
     if (!c)
         return null;
     const dir = path.resolve(root, c.artifact_dir ?? c.active_slug ?? "");
-    return fs.existsSync(dir) ? dir : null;
+    if (!fs.existsSync(dir))
+        return null;
+    try {
+        requireArtifactDirUnderRoot(dir, root);
+    }
+    catch {
+        return null;
+    }
+    return dir;
 }
 function updateCurrentAgent(root, dir, agentId, status, timestamp) {
     const cur = loadCurrent(root);
@@ -866,8 +1154,38 @@ function updateCurrentAgent(root, dir, agentId, status, timestamp) {
 }
 function initSidecars(dir, slug, sourceRequest, summary, nextAction, timestamp, markdown) {
     const criteria = markdown ? definitionAcceptanceLines(markdown).map(parseCriterion) : [];
+    // #289/#309: `markdown` here is NOT always the session `<slug>--deliver.md` that
+    // ensureSession seeds the `branch:` line into — initPlan is called against the tool-planner's
+    // PLAN artifact (`<slug>--plan-work.md` etc.), a different file that typically carries no
+    // `branch:` line at all. Since this function fully rewrites state.json (no merge with the
+    // prior contents), naively re-deriving branch from `markdown` alone would clobber whatever
+    // ensure-session already recorded there moments earlier (#309 regression). Resolve branch with
+    // a three-tier fallback, preferring the most durable source first:
+    //   1. EXISTING state.json.branch — once recorded, it is never re-derived or clobbered.
+    //   2. The session's OWN canonical `<dir>/<slug>--deliver.md` on disk — the file ensureSession
+    //      always seeds the `branch:` line into, independent of whatever `markdown` was passed in.
+    //      Reading it directly (rather than trusting `markdown`) is what makes a repaired/backfilled
+    //      init-plan call (re-run against the same branch-less plan artifact, after a #309-era
+    //      session lost its state.json branch) recover the branch without a direct file edit.
+    //   3. The `markdown` param itself (covers ensureSession's fresh-creation call, before
+    //      `<slug>--deliver.md` differs from `markdown`, and any direct/legacy caller that passes
+    //      the deliver markdown itself as the init-plan artifact).
+    // This makes the branch survive every subsequent initSidecars call (init-plan, or a resumed
+    // ensure-session) at this single choke point, without patching every other writer.
+    const existingState = loadJson(path.join(dir, "state.json"));
+    const existingBranch = existingState.branch;
+    const deliverMdPath = path.join(dir, `${slug}--deliver.md`);
+    const deliverBranch = fs.existsSync(deliverMdPath) ? markdownField(read(deliverMdPath), "branch") : "";
+    const branch = existingBranch || deliverBranch || (markdown ? markdownField(markdown, "branch") : "");
+    // #309 (scope addition): created_at is write-once, same class as the branch-drop bug above —
+    // initSidecars fully rewrites state.json on every call (including a repair/backfill re-run of
+    // init-plan against an already-existing session), so naively re-stamping created_at from the
+    // current call's timestamp silently rewrites a session's original creation time. Preserve the
+    // existing state.json's created_at when present; stamp only on true first-creation.
+    // updated_at still reflects "now" on every call — that field is intentionally mutable.
     writeJson(path.join(dir, "state.json"), {
-        ...sidecarBase(slug), status: "planned", phase: "planning", created_at: timestamp, updated_at: timestamp,
+        ...sidecarBase(slug), status: "planned", phase: "planning", created_at: existingState.created_at || timestamp, updated_at: timestamp,
+        ...(branch ? { branch } : {}),
         artifact_paths: relArtifacts(dir),
         next_action: { status: "continue", summary: nextAction || summary },
     });
@@ -888,7 +1206,12 @@ function ensureSession(p) {
     const timestamp = opt(p, "timestamp", now());
     let md = fs.existsSync(path.join(dir, `${slug}--deliver.md`)) ? read(path.join(dir, `${slug}--deliver.md`)) : "";
     if (!md) {
-        md = `# ${opt(p, "title", slug)}\n\nbranch: main\nworktree: main\ncreated: ${timestamp}\nstatus: planning\ntype: deliver\niteration: 1\n\n## Plan\n\n${opt(p, "summary", "")}\n\n## Definition Of Done\n\n- **User outcome:** ${opt(p, "summary", "Workflow session is durable.")}\n- **Scope:** Workflow session artifacts and sidecars.\n- **Acceptance criteria:**\n${opts(p, "criterion").map((c) => `  - [ ] ${c} - Evidence: pending.`).join("\n")}\n- **Usefulness checks:**\n  - [ ] User-facing workflow is documented or discoverable\n- **Stop-short risks:** Workflow artifacts could drift.\n- **Durable docs target:** not needed\n- **Sandbox mode:** local-edit\n\n## Execution Progress\n\n- [ ] Session initialized.\n\n## Verification Report\n\nBuild: [NOT_VERIFIED] Verification has not run yet.\n\n### Acceptance Criteria\n- [NOT_VERIFIED] Verification has not run yet - Evidence: pending workflow execution and checks.\n\n### Verdict: NOT_VERIFIED\n\n## Goal Fit Gate\n\n- [ ] Original user goal restated\n\n## Final Acceptance\n\n- [ ] CI/relevant checks passed or local equivalent recorded\n`;
+        // #289: derive the routing branch ONLY on fresh session creation (this `if (!md)` guard).
+        // An existing session's already-recorded `branch:` line is never touched — that whole branch
+        // of code is skipped on a resumed/taken-over session, which is what makes ADR 0021 §5
+        // takeover continuity true by construction (see Design Decision 3 in the plan).
+        const branch = resolveSessionBranch(p, slug);
+        md = `# ${opt(p, "title", slug)}\n\nbranch: ${branch}\nworktree: main\ncreated: ${timestamp}\nstatus: planning\ntype: deliver\niteration: 1\n\n## Plan\n\n${opt(p, "summary", "")}\n\n## Definition Of Done\n\n- **User outcome:** ${opt(p, "summary", "Workflow session is durable.")}\n- **Scope:** Workflow session artifacts and sidecars.\n- **Acceptance criteria:**\n${opts(p, "criterion").map((c) => `  - [ ] ${c} - Evidence: pending.`).join("\n")}\n- **Usefulness checks:**\n  - [ ] User-facing workflow is documented or discoverable\n- **Stop-short risks:** Workflow artifacts could drift.\n- **Durable docs target:** not needed\n- **Sandbox mode:** local-edit\n\n## Execution Progress\n\n- [ ] Session initialized.\n\n## Verification Report\n\nBuild: [NOT_VERIFIED] Verification has not run yet.\n\n### Acceptance Criteria\n- [NOT_VERIFIED] Verification has not run yet - Evidence: pending workflow execution and checks.\n\n### Verdict: NOT_VERIFIED\n\n## Goal Fit Gate\n\n- [ ] Original user goal restated\n\n## Final Acceptance\n\n- [ ] CI/relevant checks passed or local equivalent recorded\n`;
         fs.writeFileSync(path.join(dir, `${slug}--deliver.md`), md);
     }
     if (!fs.existsSync(path.join(dir, "state.json")) || !fs.existsSync(path.join(dir, "acceptance.json")) || !fs.existsSync(path.join(dir, "handoff.json"))) {
@@ -902,14 +1225,28 @@ function ensureSession(p) {
     // ensure-session --flow-id builder.build produces a FlowDefinition-driven session even
     // before the first advance-state call.
     const flowId = opt(p, "flow-id");
-    let stepId = opt(p, "step-id");
+    const explicitStep = opt(p, "step-id");
+    let stepId = explicitStep;
+    let adHocReason;
     if (flowId && !stepId) {
         const repoRoot = findRepoRootFromDir(dir);
         const firstStep = resolveFirstStep(flowId, repoRoot);
         if (firstStep)
             stepId = firstStep;
     }
-    writeCurrent(root, dir, timestamp, "workflow-sidecar", "ensure-session", flowId || undefined, stepId || undefined);
+    else if (flowId && explicitStep) {
+        // WS8 (AC12): --step-id is the sanctioned ad-hoc direct-entry mechanism. When it names
+        // a step other than the flow's resolved first step, record an explicit ad_hoc_entry
+        // marker (with a reason) instead of silently letting the mis-stamp look like the
+        // flow's normal first step. This is the root-cause fix for a planning-only session
+        // whose active_step_id would otherwise default to builder.build's first step.
+        const repoRoot = findRepoRootFromDir(dir);
+        const firstStep = resolveFirstStep(flowId, repoRoot);
+        if (firstStep && firstStep !== explicitStep) {
+            adHocReason = opt(p, "ad-hoc-reason") || `direct entry at step "${explicitStep}" via --step-id (flow first step is "${firstStep}")`;
+        }
+    }
+    writeCurrent(root, dir, timestamp, "workflow-sidecar", "ensure-session", flowId || undefined, stepId || undefined, adHocReason);
     console.log(dir);
     return 0;
 }
@@ -931,7 +1268,7 @@ function recordAgentEvent(p) {
         die("artifact directory does not exist");
     if (explicit && fs.lstatSync(dir).isSymbolicLink())
         die(`artifact directory must not be a symlink: ${dir}`);
-    if (hasExplicitRoot)
+    if (hasExplicitRoot || !explicit)
         requireArtifactDirUnderRoot(dir, root);
     const timestamp = opt(p, "timestamp", now());
     const agent = validateAgentId(opt(p, "agent-id"));
@@ -1014,7 +1351,7 @@ export function normalizeCheck(raw) {
     if (!check.id || !check.kind || !check.status || !check.summary)
         die("check requires id, kind, status, and summary");
     if (!checkKinds.has(check.kind))
-        die("kind must be one of: build, types, lint, test, security, diff, browser, runtime, policy, external");
+        die("kind must be one of: build, types, lint, test, command, security, diff, browser, runtime, policy, external");
     if (!checkStatuses.has(check.status))
         die("status must be one of: pass, fail, not_verified, skip");
     if (Array.isArray(check.standard_refs))
@@ -1175,7 +1512,7 @@ export function writeState(dir, slug, status, phase, timestamp, summary, next =
 // "builder.verify.policy-compliance") so round-trip helpers broaden their filters
 // to include declared claims alongside the legacy workflow.* ones.
 //
-// Safety guard: current.json in the .flow-agents dir records the CURRENTLY ACTIVE
+// Safety guard: current.json in the runtime artifact root records the CURRENTLY ACTIVE
 // session via artifact_dir. If current.json points to a different session than `dir`
 // (e.g. another session was the last to call advance-state --flow-definition), we
 // return an empty set so declared-type predicates are NOT applied to the wrong session.
@@ -1273,13 +1610,49 @@ function critiquesFromBundle(dir, declaredClaimTypes = new Set()) {
     }));
 }
 // ─────────────────────────────────────────────────────────────────────────────
+/**
+ * WS8 (ADR 0020): parse the accepted-gap waiver flags. Both --accepted-gap-reason and
+ * --waived-by are required together (an accepted gap with no justification or no
+ * approver is refused — no silent/default waiver). Returns the waiver record to stamp
+ * onto claim.metadata.waiver, or null when neither flag is present. Reuses the existing
+ * accepted_gap -> assumed status mapping; adds no new canonical status value.
+ */
+function parseWaiver(p, ts) {
+    const reason = opt(p, "accepted-gap-reason");
+    const waivedBy = opt(p, "waived-by");
+    if (!reason && !waivedBy)
+        return null;
+    if (!reason)
+        die("--accepted-gap-reason is required when --waived-by is set (an accepted gap must carry its justification)");
+    if (!waivedBy)
+        die("--waived-by is required when --accepted-gap-reason is set (an accepted gap must name its approver)");
+    return { reason, approved_by: waivedBy, approved_at: ts };
+}
 async function recordEvidence(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
     const verdict = opt(p, "verdict") || die("--verdict is required");
     if (!verdicts.has(verdict))
         die("verdict must be one of: pass, partial, fail, not_verified");
     const slug = taskSlugFor(dir, opt(p, "task-slug"));
-    const checks = [...opts(p, "check-json").map((v) => normalizeCheck(parseJson(v, "--check-json"))), ...opts(p, "surface-trust-json").map(surfaceCheckFromArtifact)];
+    const _ts0 = opt(p, "timestamp", now());
+    const _waiver = parseWaiver(p, _ts0);
+    const _checksRaw = [...opts(p, "check-json").map((v) => normalizeCheck(parseJson(v, "--check-json"))), ...opts(p, "surface-trust-json").map(surfaceCheckFromArtifact)];
+    // WS8 (AC4, iteration 2): a command-backed check reconciles against CI or fails — it can
+    // NEVER be waived. Reject --accepted-gap-reason/--waived-by on any check whose evidence
+    // classifies as test_output (build/types/lint/test/command, and security/browser/runtime
+    // WHEN a command is present). Only session-local checks (attestation/observation/citation/
+    // diff/policy) are waivable. The CI reconciler enforces the same rule server-side (a waiver
+    // on test_output evidence is a divergence), so this producer-side guard is defense-in-depth,
+    // not the sole gate. (ADR 0020)
+    if (_waiver) {
+        for (const c of _checksRaw) {
+            const hasCmd = typeof c.command === "string" && String(c.command).trim().length > 0;
+            if (classifyEvidence(c.kind, hasCmd).evidenceType === "test_output") {
+                die(`--accepted-gap-reason/--waived-by cannot be applied to a command-backed check (kind='${String(c.kind)}'${hasCmd ? " with a command" : ""}): a command-backed check reconciles against CI or fails and cannot be waived. Waive only session-local checks (attestation/observation/citation). (ADR 0020)`);
+            }
+        }
+    }
+    const checks = _checksRaw.map((c) => _waiver ? { ...c, _waiver } : c);
     if (!checks.length && opts(p, "surface-trust-json").length === 0)
         die("record-evidence requires at least one --check-json or --surface-trust-json");
     validateAcceptanceEvidenceRefs(dir);
@@ -1377,11 +1750,101 @@ async function recordGateClaim(p) {
         check.artifact_refs = evidenceRefs;
     }
     const checkNormalized = normalizeCheck(check);
+    // WS8 (ADR 0020): honor the accepted-gap waiver flags for a gate claim too.
+    const gateWaiver = parseWaiver(p, ts);
+    if (gateWaiver)
+        checkNormalized._waiver = gateWaiver;
     // Log the targeted gate expectation for transparency (goes to stderr only)
-    process.stderr.write(`[record-gate-claim] targeting ${activeStep.stepId}/${activeStep.gateId}/${targetExpectation.id} → claimType=${claimType} subjectType=${subjectType}\n`);
+    process.stderr.write(`[record-gate-claim] targeting ${activeStep.stepId}/${activeStep.gateId}/${targetExpectation.id} → claimType=${claimType} subjectType=${subjectType}${gateWaiver ? " (WAIVED accepted_gap)" : ""}\n`);
     assertBundleWritten(await writeTrustBundle(dir, slug, ts, [checkNormalized], [], []));
     return 0;
 }
+/**
+ * promote — the promote-then-archive gate (issue #312). Durable-residue extraction is
+ * the archival act: this records WHAT durable residue was promoted WHERE and writes a
+ * PROMOTION CLAIM into the session trust.bundle.
+ *
+ * Claim shape (reconcile-safe by construction): the promotion check is kind="policy",
+ * so classifyEvidence maps it to evidenceType "policy_rule" (session-local, method
+ * "auditability"). It carries NO command / execution.label, so it can NEVER require a
+ * reconcile-manifest entry and can NEVER become a [not-run] / unbacked-command
+ * divergence at CI trust-reconcile. Its status derives to `verified` from that
+ * session-local policy_rule evidence item, so the reconciler classifies it session-local
+ * and accepts it as an ATTESTED claim (exit 0) — never as a test_output claim that must
+ * match the manifest. The _promotion marker rides onto claim.metadata.promotion (see
+ * buildTrustBundle) so the archive gate and validators can detect it without new manifest
+ * entries (R1).
+ *
+ * Modes:
+ *   promote <dir> --evidence-path <p> [--evidence-path <p> ...]
+ *       Records the durable doc paths written (docs/decisions/<slug>.md, CONTEXT.md,
+ *       docs/learnings/*, …). Each path MUST exist on disk at record time — a missing
+ *       path fails loud (no silent empty promotion).
+ *   promote <dir> --none --reason "<why nothing durable>"
+ *       An explicit, auditable no-residue promotion (R3).
+ */
+async function promote(p) {
+    const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
+    const slug = taskSlugFor(dir, opt(p, "task-slug"));
+    const ts = opt(p, "timestamp", now());
+    const none = p.flags.has("none");
+    const reason = opt(p, "reason");
+    const repoRoot = opt(p, "repo-root") ? path.resolve(opt(p, "repo-root")) : findRepoRootFromDir(dir);
+    const rawPaths = opts(p, "evidence-path");
+    if (none) {
+        if (rawPaths.length)
+            die("promote --none records a no-residue claim; do not also pass --evidence-path");
+        if (!reason.trim())
+            die("promote --none requires --reason \"<why nothing durable was promoted>\"");
+    }
+    else {
+        if (!rawPaths.length)
+            die("promote requires at least one --evidence-path <durable-doc-path> (or --none --reason \"<why>\" for an explicit no-residue promotion)");
+    }
+    // Every evidence ref MUST exist on disk at record time (fail loud otherwise). Store
+    // repo-relative paths when the ref lives under the repo, so the claim is portable.
+    const targets = [];
+    for (const raw of rawPaths) {
+        const abs = path.isAbsolute(raw) ? raw : path.resolve(repoRoot, raw);
+        if (!fs.existsSync(abs))
+            die(`promote --evidence-path does not exist on disk: ${raw} (resolved: ${abs}). Promotion evidence refs must point at durable docs that were actually written.`);
+        const rel = path.relative(repoRoot, abs);
+        targets.push(rel && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel : raw);
+    }
+    const promotionMarker = {
+        schema_version: "1.0",
+        none,
+        ...(none ? { reason } : {}),
+        targets,
+        promoted_at: ts,
+    };
+    const summary = opt(p, "summary") || (none
+        ? `Promotion (no durable residue): ${reason}`
+        : `Promoted durable residue: ${targets.join(", ")}`);
+    // Session-local promotion check: kind="policy" -> policy_rule evidence, no command.
+    const promotionCheck = { id: "promotion", kind: "policy", status: "pass", summary, _promotion: promotionMarker };
+    // Add the promotion claim WITHOUT dropping the session's existing verification
+    // evidence/criteria/critiques (mirror record-critique's merge pattern). Drop any prior
+    // "promotion" check so re-running promote is idempotent rather than duplicating.
+    const _dct = declaredClaimTypesFor(dir);
+    const existingChecks = checksFromBundle(dir, _dct).filter((c) => c.id !== "promotion");
+    const _acc = loadJson(path.join(dir, "acceptance.json"));
+    const criteria = Array.isArray(_acc.criteria) ? _acc.criteria : [];
+    const critiques = critiquesFromBundle(dir, _dct);
+    assertBundleWritten(await writeTrustBundle(dir, slug, ts, [...existingChecks, promotionCheck], criteria, critiques));
+    // Auditable record of what was promoted where (companion to the trust.bundle claim).
+    writeJson(path.join(dir, "promotion.json"), { ...sidecarBase(slug), ...promotionMarker, summary });
+    // 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);
+        await publishDelivery(dir, publishRepoRoot).catch((err) => {
+            process.stderr.write(`[promote] WARNING: publish-delivery failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        });
+    }
+    process.stderr.write(`[promote] recorded ${none ? "no-residue" : targets.length + " durable ref(s)"} promotion claim for ${slug}\n`);
+    printJson({ ok: true, slug, none, targets, promotion_claim: "trust.bundle" });
+    return 0;
+}
 async function advanceState(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
     const status = opt(p, "status");
@@ -1438,7 +1901,14 @@ async function advanceState(p) {
     if (status === "delivered") {
         await sealTrustCheckpoint(dir, slug, timestamp, status, "release").catch(() => { });
         // Publish delivery bundle: best-effort copy to delivery/ for CI trust-reconcile.
-        await publishDelivery(dir, findRepoRootFromDir(dir)).catch(() => { });
+        // Fail-closed repo-root resolution (findRepoRootFromDirStrict, no cwd fallback) — see
+        // 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.
+        const publishRepoRoot = opt(p, "repo-root") ? path.resolve(opt(p, "repo-root")) : findRepoRootFromDirStrict(dir);
+        await publishDelivery(dir, publishRepoRoot).catch((err) => {
+            process.stderr.write(`[advance-state] WARNING: publish-delivery failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        });
     }
     return 0;
 }
@@ -1511,7 +1981,14 @@ async function recordRelease(p) {
     // Trust checkpoint: seal at the "delivered" moment (the natural terminal mark for record-release).
     await sealTrustCheckpoint(dir, slug, payload.updated_at, "delivered", "release").catch(() => { });
     // Publish delivery bundle: best-effort copy to delivery/ for CI trust-reconcile.
-    await publishDelivery(dir, findRepoRootFromDir(dir)).catch(() => { });
+    // Fail-closed repo-root resolution (findRepoRootFromDirStrict, no cwd fallback) — see
+    // 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.
+    const publishRepoRoot = opt(p, "repo-root") ? path.resolve(opt(p, "repo-root")) : findRepoRootFromDirStrict(dir);
+    await publishDelivery(dir, publishRepoRoot).catch((err) => {
+        process.stderr.write(`[record-release] WARNING: publish-delivery failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    });
     return 0;
 }
 // ─── Trust Checkpoint (Increment A) ──────────────────────────────────────────
@@ -1713,7 +2190,7 @@ async function sealCheckpoint(p) {
 }
 // ─── Publish Delivery Bundle ──────────────────────────────────────────────────
 // Copies the session's trust.bundle (+ checkpoint companions) from the gitignored
-// session artifact dir (.flow-agents/<slug>/) to the committed delivery/ transport
+// session artifact dir (.kontourai/flow-agents/<slug>/) to the committed delivery/ transport
 // path so the CI trust-reconcile job can reconcile it against fresh CI results.
 //
 // Fail-soft: if trust.bundle is absent (no evidence recorded yet), does nothing.
@@ -1727,13 +2204,24 @@ async function sealCheckpoint(p) {
  * trust.checkpoint.intoto.json / trust.checkpoint.sig.json from the
  * session artifact dir to <repoRoot>/delivery/.
  *
- * Fail-soft: if trust.bundle is absent, returns without throwing.
+ * 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
+ * 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.
  */
 export async function publishDelivery(dir, repoRoot) {
     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`);
+        return;
+    }
     const deliveryDir = path.join(repoRoot, "delivery");
     fs.mkdirSync(deliveryDir, { recursive: true });
     // Required: trust.bundle (the CI anchor)
@@ -1764,7 +2252,10 @@ export async function publishDelivery(dir, repoRoot) {
  */
 async function publishDeliveryCmd(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
-    const repoRoot = opt(p, "repo-root") || findRepoRootFromDir(dir);
+    // Fail-closed: an explicit --repo-root always wins; otherwise resolve strictly (no
+    // process.cwd() fallback) so a scratch/test artifact dir cannot accidentally publish
+    // into whichever repo happens to be the current working directory.
+    const repoRoot = opt(p, "repo-root") || findRepoRootFromDirStrict(dir);
     await publishDelivery(dir, repoRoot);
     return 0;
 }
@@ -1971,13 +2462,13 @@ async function dogfoodPass(p) {
     return 0;
 }
 /**
- * Read the gate block signal from .flow-agents/.goal-fit-block-streak.json
+ * Read the gate block signal from .kontourai/flow-agents/.goal-fit-block-streak.json
  * (written by scripts/hooks/stop-goal-fit.js when block mode fires).
  * The file sits at <artifact-root>/.goal-fit-block-streak.json — one level
  * above the session artifact dir. Fail-open: returns { blocked: false } when
  * the file is absent or unreadable.
  *
- * @param artifactRoot  The .flow-agents root dir (parent of session slug dir).
+ * @param artifactRoot  The runtime artifact root dir (parent of session slug dir).
  */
 export function readGateBlockSignal(artifactRoot) {
     const streakFile = path.join(artifactRoot, ".goal-fit-block-streak.json");
@@ -2183,7 +2674,7 @@ export function buildGateInquiryRecords(bundle, blockSignal, slug, expectedCrite
  *
  * The block signal is read from <artifact-root>/.goal-fit-block-streak.json,
  * written by scripts/hooks/stop-goal-fit.js when block mode fires. The file
- * lives one level above the session slug dir (the .flow-agents root).
+ * lives one level above the session slug dir (the runtime artifact root).
  *
  * If @kontourai/surface is unavailable, logs a warning and returns 0
  * (fail-open — no bespoke fork fallback).
@@ -2206,7 +2697,7 @@ async function gateReview(p) {
         return 0;
     }
     const bundle = JSON.parse(fs.readFileSync(bundlePath, "utf8"));
-    // Read gate block signal from .flow-agents root (one level above session dir)
+    // Read gate block signal from the runtime artifact root (one level above session dir)
     const artifactRoot = path.dirname(dir);
     const blockSignal = readGateBlockSignal(artifactRoot);
     // Enumerate expected criterion IDs: primary = bundle claims (workflow.acceptance.criterion),
@@ -2370,7 +2861,7 @@ function trustMcp(p) {
     if (mode === "print") {
         console.log(JSON.stringify({ mcpServers: { [TRUST_MCP_SERVER]: trustMcpRegistration() } }, null, 2));
         process.stderr.write(`\n# Paste the above into your runtime MCP config (e.g. .mcp.json). Flow Agents does NOT write it for you unless you run: trust-mcp --mode enable\n`);
-        process.stderr.write(`# To view a task's trust inline, call surface_summary with path=<.flow-agents/<slug>/trust.bundle>.\n`);
+        process.stderr.write(`# To view a task's trust inline, call surface_summary with path=<.kontourai/flow-agents/<slug>/trust.bundle>.\n`);
         return 0;
     }
     if (mode !== "enable" && mode !== "disable")
@@ -2422,12 +2913,19 @@ const LIVENESS_POLICY = {
     conflictRules: [],
     impactLevel: "medium",
 };
-function livenessStreamFile(root) { return path.join(root, "liveness", "events.jsonl"); }
-function appendLivenessEvent(root, evt) {
-    const file = livenessStreamFile(root);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.appendFileSync(file, `${JSON.stringify(evt)}\n`);
+/**
+ * Delegate to the shared pure-CJS writer (scripts/hooks/lib/liveness-write.js), mirroring the
+ * createRequire pattern used by loadActorIdentityHelper() below. Deliberately NO inline duplicate
+ * fallback — the whole point of #288 Wave 2 Task 2.1 is one writer shared by the CLI and the
+ * hook wrappers' tool-activity heartbeat, not two copies of the append shape that can drift.
+ */
+function loadLivenessWriteHelper() {
+    const _req = createRequire(import.meta.url);
+    const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/liveness-write.js");
+    return _req(helperPath);
 }
+function livenessStreamFile(root) { return loadLivenessWriteHelper().livenessStreamFile(root); }
+function appendLivenessEvent(root, evt) { loadLivenessWriteHelper().appendLivenessEvent(root, evt); }
 function readLivenessEvents(root) {
     // Delegate to the shared pure-CJS helper (scripts/hooks/lib/liveness-read.js).
     // Using createRequire so the ESM sidecar can load a CJS module without bundling it.
@@ -2463,39 +2961,158 @@ function livenessLabel(status) {
         return "superseded";
     return status;
 }
-// ─── ADR 0012 lifecycle-driven liveness (opt-in via FLOW_AGENTS_LIVENESS) ──────
+// ─── ADR 0012 lifecycle-driven liveness (default-on; opt-out via FLOW_AGENTS_LIVENESS) ──
 // 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"]);
-function resolveLivenessActor() { return (process.env.FLOW_AGENTS_ACTOR || "").trim() || "local"; }
-function livenessEnabled() { const v = String(process.env.FLOW_AGENTS_LIVENESS || "").trim().toLowerCase(); return v === "on" || v === "1" || v === "true"; }
+/**
+ * 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
+ * fallback: if the module fails to load, that failure itself must surface as an unresolved actor
+ * ("") — never silently degrade back to the retired "local" default (issue #287).
+ */
+function loadActorIdentityHelper() {
+    const _req = createRequire(import.meta.url);
+    const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/actor-identity.js");
+    return _req(helperPath);
+}
+function resolveLivenessActor() {
+    return loadActorIdentityHelper().resolveActor(process.env).actor;
+}
+// isUnresolvedActor is no longer defined locally — it is single-sourced in
+// scripts/hooks/lib/actor-identity.js (loadActorIdentityHelper().isUnresolvedActor) so the
+// lifecycle auto-emit path, the direct CLI liveness path, and the tool-activity heartbeat path
+// all consume the same predicate rather than forking their own copy (#287 re-review MEDIUM; #288
+// Wave 1 Task 1.1 single-sources it there).
+/**
+ * Delegate to the shared pure-CJS policy predicates (scripts/hooks/lib/liveness-policy.js) — the
+ * one definition of "enabled" (default-on/opt-out) and the claim TTL default, consumed by both the
+ * lifecycle auto-emit path and the manual `liveness claim --ttl` default so they can never disagree
+ * (#288).
+ */
+function loadLivenessPolicyHelper() {
+    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);
+}
+function livenessEnabled() { return loadLivenessPolicyHelper().isLivenessEnabled(process.env); }
+/**
+ * F1 (#288 fix iteration 1, cr-HIGH fail-open violation): the `livenessEnabled()`
+ * guard (and therefore its `loadLivenessPolicyHelper()` module load) must sit
+ * INSIDE this function's own fail-open try/catch — previously it sat outside,
+ * so a missing/broken scripts/hooks/lib/liveness-policy.js module made
+ * `init-plan`/`advance-state` exit 1 instead of degrading gracefully
+ * (repro-verified). Now: any failure here — including a failed helper load —
+ * is caught, produces one stderr diagnostic, and the lifecycle auto-emit is
+ * skipped; the workflow command's own exit code is never affected. This
+ * mirrors the #287 fail-open convention already used elsewhere in this file.
+ * The direct CLI write path (`async function liveness`, actions
+ * claim|heartbeat|release) is deliberately NOT wrapped this way — it stays
+ * fail-loud on a missing helper module, per the plan's explicit instruction
+ * that only the convenience lifecycle wiring is flag-gated/fail-open.
+ */
 function livenessLifecycle(taskDir, slug, kind, timestamp) {
-    if (!livenessEnabled())
-        return;
     try {
-        const root = path.dirname(taskDir); // .flow-agents/<slug> → .flow-agents (the shared liveness stream lives here)
-        const evt = { type: kind, subjectId: slug, actor: resolveLivenessActor(), at: timestamp, source: "lifecycle" };
+        if (!livenessEnabled())
+            return;
+        const actor = resolveLivenessActor();
+        if (loadActorIdentityHelper().isUnresolvedActor(actor)) {
+            process.stderr.write("[liveness] skipped auto-emit: actor unresolved (set FLOW_AGENTS_ACTOR or run inside a supported runtime)\n");
+            return;
+        }
+        const root = path.dirname(taskDir); // .kontourai/flow-agents/<slug> → .kontourai/flow-agents (the shared liveness stream lives here)
+        const evt = { type: kind, subjectId: slug, actor, at: timestamp, source: "lifecycle" };
         if (kind === "claim")
-            evt.ttlSeconds = 1800;
+            evt.ttlSeconds = loadLivenessPolicyHelper().resolveTtlSeconds(process.env);
         appendLivenessEvent(root, evt);
     }
-    catch { /* best-effort; liveness is advisory and must never break the workflow */ }
+    catch (err) {
+        // best-effort; liveness is advisory and must never break the workflow — but the failure
+        // itself must be visible (F1), not silently absorbed.
+        try {
+            const detail = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[liveness] skipped auto-emit: ${detail}\n`);
+        }
+        catch { /* best-effort diagnostic only */ }
+    }
+}
+/**
+ * F5 (#288 fix iteration 1, sec-LOW): strip control/escape characters before echoing a
+ * subjectId/actor to the terminal. subjectId is a raw CLI positional argument on the write path
+ * (never sanitized before this point — it is stored as-is in the event for data fidelity) and,
+ * on the `status` read path, both subjectId and actor may originate from a hand-edited or
+ * otherwise hostile liveness/events.jsonl file rather than this process's own writes. Strips the
+ * C0 control range (0x00-0x1F), DEL (0x7F), and the C1 range (0x80-0x9F, which includes
+ * ANSI-CSI-adjacent bytes) — display-only; the persisted event itself is never mutated.
+ */
+function stripControlCharsForDisplay(value) {
+    return String(value ?? "").replace(/[\u0000-\u001F\u007F-\u009F]/g, "");
 }
 async function liveness(p) {
     const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : flowAgentsArtifactRoot();
     const action = p.positional[0] || "";
     const subjectId = p.positional[1] || "";
-    const actor = opt(p, "actor", process.env.FLOW_AGENTS_ACTOR || "unknown");
     const nowIso = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    if (action === "whoami") {
+        // Read-only, lock-free, write-free advisory surface: reuses the identical resolution chain
+        // as the write paths (loadActorIdentityHelper().resolveActor) but deliberately never dies on
+        // an unresolved actor — the enforcement point stays at `liveness claim`, which already dies
+        // loudly (see below). This lets a skill learn "who am I" during a read-only preflight without
+        // emitting a bogus claim first.
+        const helper = loadActorIdentityHelper();
+        const explicitActorRaw = opt(p, "actor", "");
+        const explicitActor = explicitActorRaw ? helper.sanitizeSegment(explicitActorRaw) : "";
+        const resolved = explicitActor
+            ? { actor: explicitActor, source: "explicit-override" }
+            : helper.resolveActor(process.env);
+        if (p.flags.has("json")) {
+            console.log(JSON.stringify(resolved));
+            return 0;
+        }
+        console.log(`${stripControlCharsForDisplay(resolved.actor || "unresolved")}\t${stripControlCharsForDisplay(resolved.source)}`);
+        return 0;
+    }
     if (action === "claim" || action === "heartbeat" || action === "release") {
+        // Actor resolution happens only for write actions (F5, #287 fix iteration 1) — "status" is a
+        // read path and must not shell out via resolveLivenessActor()/resolveActor().
+        const helper = loadActorIdentityHelper();
+        const explicitActorRaw = opt(p, "actor", "");
+        // F7 (#287 fix iteration 2): an explicit --actor value that strips to empty under the allowed
+        // [A-Za-z0-9_.-] charset (e.g. "--actor ':::'") is a hard error on this write path, not a
+        // silent fallback to sanitizeSegment's shared "unknown" sentinel — garbage on an explicit flag
+        // is an authoring mistake the caller must fix, unlike the env-override seam (which falls
+        // through to derivation instead, since there is no flag to correct).
+        if (explicitActorRaw && !/[A-Za-z0-9_.-]/.test(explicitActorRaw)) {
+            die(`liveness ${action} --actor value strips to empty under the allowed actor charset ([A-Za-z0-9_.-]) — pass a --actor value containing at least one letter, digit, underscore, period, or hyphen.`);
+        }
+        const explicitActor = explicitActorRaw ? helper.sanitizeSegment(explicitActorRaw) : "";
+        const actor = explicitActor || helper.resolveActor(process.env).actor;
+        if (helper.isUnresolvedActor(actor)) {
+            die(`liveness ${action} requires a resolvable actor — no explicit --actor flag, no FLOW_AGENTS_ACTOR override, and runtime/ancestry resolution failed. Fix: pass --actor <id>, or set FLOW_AGENTS_ACTOR=<id>, or run inside a supported runtime.`);
+        }
         if (!subjectId)
             die(`liveness ${action} requires a subjectId`);
+        // F8(i) (#288 fix iteration 2, orphan-heartbeat invariant): heartbeat/release on the direct CLI
+        // write path must never be the FIRST liveness event ever written for a (subjectId, actor) pair —
+        // that is exactly how the reviewer-reproduced orphan-heartbeat bug arises (a bare heartbeat with
+        // no claim behind it, later mistaken for claim evidence). A full stream read here is fine: this
+        // is a rare, human/CLI-driven call, not the hot tool-activity path. `claim` itself is exempt (it
+        // is the event that ESTABLISHES the pair in the first place).
+        if (action === "heartbeat" || action === "release") {
+            const priorEvents = readLivenessEvents(root);
+            const hasPriorClaim = priorEvents.some((e) => e && e.type === "claim" && e.subjectId === subjectId && e.actor === actor);
+            if (!hasPriorClaim) {
+                die(`liveness ${action} requires a prior claim event for subjectId ${JSON.stringify(subjectId)} and actor ${JSON.stringify(actor)} — none was found in the liveness stream. Fix: run \`liveness claim ${subjectId} --actor ${actor}\` first, then retry ${action}.`);
+            }
+        }
         const evt = { type: action, subjectId, actor, at: opt(p, "at") || nowIso };
-        if (action === "claim")
-            evt.ttlSeconds = Number.parseInt(opt(p, "ttl", "1800"), 10) || 1800;
+        if (action === "claim") {
+            const defaultTtl = loadLivenessPolicyHelper().resolveTtlSeconds(process.env);
+            evt.ttlSeconds = Number.parseInt(opt(p, "ttl", String(defaultTtl)), 10) || defaultTtl;
+        }
         appendLivenessEvent(root, evt);
-        console.log(`liveness ${action}: ${subjectId} by ${actor}`);
+        console.log(`liveness ${action}: ${stripControlCharsForDisplay(subjectId)} by ${stripControlCharsForDisplay(actor)}`);
         return 0;
     }
     if (action === "status") {
@@ -2531,7 +3148,7 @@ async function liveness(p) {
         for (const g of groups.values()) {
             if (subjectFilter && g.subjectId !== subjectFilter)
                 continue;
-            const claim = { id: `${g.subjectId}::${g.actor}`, subjectType: "work-item", subjectId: g.subjectId, surface: "flow.liveness", claimType: "liveness.hold", fieldOrBehavior: "held-by", value: g.actor, createdAt: g.created, updatedAt: g.updated, ttlSeconds: g.ttlSeconds, verificationPolicyId: LIVENESS_POLICY.id };
+            const claim = { id: `${g.subjectId}::${g.actor}`, subjectType: "work-item", subjectId: g.subjectId, facet: "flow.liveness", claimType: "liveness.hold", fieldOrBehavior: "held-by", value: g.actor, createdAt: g.created, updatedAt: g.updated, ttlSeconds: g.ttlSeconds, verificationPolicyId: LIVENESS_POLICY.id };
             const status = surface.deriveTrustStatus({ claim, evidence: [], policy: LIVENESS_POLICY, events: g.events, now });
             rows.push({ subjectId: g.subjectId, actor: g.actor, status, label: livenessLabel(status) });
         }
@@ -2540,10 +3157,99 @@ async function liveness(p) {
             return 0;
         }
         for (const r of rows)
-            console.log(`${r.subjectId}\t${r.actor}\t${r.label}`);
+            console.log(`${stripControlCharsForDisplay(r.subjectId)}\t${stripControlCharsForDisplay(r.actor)}\t${r.label}`);
+        return 0;
+    }
+    if (action === "verdict") {
+        // Read-only, lock-free CLI helper (#320 AC1) — mirrors `whoami`'s lock-bypass (see
+        // isLivenessVerdict in main() below): computes {subjectId, winner, losers, reason, holders}
+        // as a PURE function of the shared liveness stream. Among the subject's currently-fresh
+        // claim holders (via the shared `freshHolders` helper — the exact canonical
+        // freshness/grouping/release-handling logic `workflow-steering.js`'s ambient digest already
+        // uses, not a re-derived rule), the holder whose most recent `claim` event has the earliest
+        // `at` wins; an exact-timestamp tie breaks by ascending plain string comparison of actor id
+        // (never locale-aware collation, for cross-machine determinism). Same stream state ⇒ same
+        // verdict, regardless of which actor invokes it — no actor-specific input is read here.
+        if (!subjectId)
+            die("liveness verdict requires a subjectId");
+        const events = readLivenessEvents(root);
+        const nowMs = opt(p, "now") ? Date.parse(opt(p, "now")) : Date.now();
+        const _req = createRequire(import.meta.url);
+        const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/liveness-read.js");
+        const { freshHolders } = _req(helperPath);
+        // Impossible-sentinel selfActor: real actors are sanitized to [A-Za-z0-9_.-]+ and can never be
+        // empty (enforced on every write path above), so passing "" excludes nothing.
+        const fresh = freshHolders(events, subjectId, "", nowMs);
+        // freshHolders' `lastAt` tracks the group's latest event of ANY type (heartbeat-updated); the
+        // tiebreak instead operates on each holder's most recent `claim`-type event `at` — the
+        // "current claim timestamp", distinct from lastAt.
+        const latestClaimAt = (actor) => {
+            let best = "";
+            for (const e of events) {
+                if (e && e.subjectId === subjectId && e.actor === actor && e.type === "claim" && typeof e.at === "string") {
+                    if (!best || e.at > best)
+                        best = e.at;
+                }
+            }
+            return best;
+        };
+        const holders = fresh
+            .map((h) => ({ actor: String(h.actor), claimAt: latestClaimAt(String(h.actor)) || String(h.lastAt), lastAt: String(h.lastAt), ttlSeconds: Number(h.ttlSeconds) }))
+            .sort((a, b) => (a.claimAt < b.claimAt ? -1 : a.claimAt > b.claimAt ? 1 : a.actor < b.actor ? -1 : a.actor > b.actor ? 1 : 0));
+        let winner = null;
+        let losers = [];
+        let reason = "no-conflict";
+        if (holders.length >= 2) {
+            winner = holders[0];
+            const tie = holders.filter((h) => h.claimAt === winner.claimAt).length > 1;
+            reason = tie ? "tie-actor-lexicographic" : "earlier-claim";
+            losers = holders.filter((h) => h.actor !== winner.actor);
+        }
+        if (p.flags.has("json")) {
+            // #320 fix iteration 1 (sec-HIGH F3): `winner`/`losers`/`holders` carry raw actor/claimAt/
+            // lastAt strings sourced straight from the multi-writer append-only liveness/events.jsonl
+            // stream (see stripControlCharsForDisplay's header above — any process can append a
+            // hostile line, bypassing the CLI write-side sanitizeSegment entirely). The pull-work
+            // SKILL.md's Post-Claim Conflict Re-check instructs an LLM to read `winner.actor` /
+            // `losers[].actor` straight out of THIS `--json` output into its own context — a second,
+            // LLM-facing injection path alongside the mid-turn conflict hook (liveness-heartbeat.js's
+            // computeConflict). Build a sanitized COPY for JSON emission only: control-char strip
+            // (matching the text branch's existing stripControlCharsForDisplay treatment below) plus a
+            // 64-char cap (matching sanitizeSegment's cap on the write side) on actor/claimAt/lastAt.
+            // `reason`/`subjectId`/`ttlSeconds` are left as-is (enum/number, never free text). Never
+            // mutates `result`/`holders`/`winner`/`losers` themselves — the text branch below still
+            // needs the untouched originals for its own per-line rendering, and winner/loser identity
+            // (already sanitizeSegment-clean for legitimate actors) is unaffected, so the loser-release
+            // contract still works.
+            const sanitizeVerdictHolderForJson = (h) => h
+                ? {
+                    ...h,
+                    actor: stripControlCharsForDisplay(h.actor).slice(0, 64),
+                    claimAt: stripControlCharsForDisplay(h.claimAt).slice(0, 64),
+                    lastAt: stripControlCharsForDisplay(h.lastAt).slice(0, 64),
+                }
+                : h;
+            const jsonResult = {
+                subjectId,
+                winner: sanitizeVerdictHolderForJson(winner),
+                losers: losers.map((l) => sanitizeVerdictHolderForJson(l)),
+                reason,
+                holders: holders.map((h) => sanitizeVerdictHolderForJson(h)),
+            };
+            console.log(JSON.stringify(jsonResult));
+            return 0;
+        }
+        for (const h of holders) {
+            const tag = winner && h.actor === winner.actor ? "WINNER" : (holders.length >= 2 ? "LOSER" : "HOLDER");
+            console.log(`${stripControlCharsForDisplay(h.actor)}\tclaimAt=${stripControlCharsForDisplay(h.claimAt)}\t${tag}`);
+        }
+        if (winner)
+            console.log(`WINNER: ${stripControlCharsForDisplay(winner.actor)}`);
+        for (const l of losers)
+            console.log(`LOSER: ${stripControlCharsForDisplay(l.actor)}`);
         return 0;
     }
-    die("liveness action must be one of: claim | heartbeat | release | status");
+    die("liveness action must be one of: claim | heartbeat | release | status | whoami | verdict");
     return 1;
 }
 // ─────────────────────────────────────────────────────────────────────────────
@@ -2707,9 +3413,24 @@ async function main() {
     const p = parseArgs(process.argv.slice(2));
     if (!p.command)
         die("workflow-sidecar command is required");
-    const lockRoot = ["ensure-session", "current", "dogfood-pass", "liveness"].includes(p.command)
+    // F1 (#166 fix iteration 1): `liveness whoami` is a read-only, lock-free, write-free advisory
+    // surface (see the `action === "whoami"` branch inside `liveness()` above) — it must never
+    // acquire the workflow-sidecar lock, regardless of whether the artifact root already exists on
+    // disk. Without this action-level bypass, `liveness` was blanket-included in the lock-routing
+    // branch below, so `whoami` against an EXISTING artifact root would still resolve a real
+    // lockRoot and go through `withLock`'s mkdir/lockdir path — the opposite of "genuinely
+    // lock-free". This bypass mirrors `resolve-slug`'s existing empty-lockRoot special case
+    // immediately below and is scoped to the `whoami` action only: `liveness status` (a read path)
+    // keeps its pre-existing lock behavior unchanged (out of scope for this fix — see fix-plan
+    // iteration 1, F1), and `liveness claim` / `heartbeat` / `release` (write paths) are untouched.
+    const isLivenessWhoami = p.command === "liveness" && p.positional[0] === "whoami";
+    // #320 AC1: `liveness verdict` is read-only and lock-free, exactly like `whoami` above — it
+    // must never acquire the workflow-sidecar lock. Same bypass shape, scoped to the `verdict`
+    // action only; `liveness status` (also a read path) keeps its pre-existing lock behavior.
+    const isLivenessVerdict = p.command === "liveness" && p.positional[0] === "verdict";
+    const lockRoot = (["ensure-session", "current", "dogfood-pass", "liveness"].includes(p.command) && !isLivenessWhoami && !isLivenessVerdict)
         ? (opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : (p.command === "ensure-session" ? flowAgentsArtifactRoot() : defaultArtifactRootForRead()))
-        : p.command === "record-agent-event" ? explicitArtifactRoot(p) : p.command === "claim" ? (p.positional[1] ? path.resolve(p.positional[1]) : "") : p.positional[0] ? artifactDirFrom(p.positional[0]) : "";
+        : p.command === "record-agent-event" ? explicitArtifactRoot(p) : p.command === "claim" ? (p.positional[1] ? path.resolve(p.positional[1]) : "") : p.command === "resolve-slug" ? "" : (isLivenessWhoami || isLivenessVerdict) ? "" : p.positional[0] ? artifactDirFrom(p.positional[0]) : "";
     return withLock(lockRoot, ["ensure-session", "record-agent-event", "dogfood-pass"].includes(p.command), p.command, () => {
         switch (p.command) {
             case "ensure-session": return ensureSession(p);
@@ -2718,6 +3439,7 @@ async function main() {
             case "init-plan": return initPlan(p);
             case "record-evidence": return recordEvidence(p);
             case "record-gate-claim": return recordGateClaim(p);
+            case "promote": return promote(p);
             case "advance-state": return advanceState(p);
             case "record-critique": return recordCritique(p);
             case "import-critique": return importCritique(p);
@@ -2729,6 +3451,7 @@ async function main() {
             case "trust-mcp": return trustMcp(p);
             case "liveness": return liveness(p);
             case "claim": return claimLookup(p);
+            case "resolve-slug": return resolveSlugCmd(p);
             case "seal-checkpoint": return sealCheckpoint(p);
             case "publish-delivery": return publishDeliveryCmd(p);
             default: die(`unknown command: ${p.command}`);