@kontourai/flow-agents 2.2.0 → 2.4.0

package/src/cli/workflow-sidecar.ts

@@ -13,7 +13,7 @@ type AnyObj = Record<string, any>;
 
 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"]);
 
@@ -50,6 +50,144 @@ function workItemSlug(ref: string): string {
   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: ReturnType<typeof parseArgs>): number {
+  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: string): string {
+  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: string, helper: { sanitizeSegment: (v: unknown) => string }): string {
+  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: string): void {
+  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: string): never => 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: { status: number | null; stderr: Buffer | string } | undefined;
+  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 as NodeJS.ErrnoException & { status?: number | null; stderr?: Buffer | string };
+    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: ReturnType<typeof parseArgs>, slug: string): string {
+  // 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).
@@ -170,7 +308,7 @@ type SurfaceModule = {
     policies: Record<string, unknown>[];
     now?: Date;
   }) => { status: string; policyId: string | undefined };
-  generateClaimId: (subjectId: string, surface: string, fieldOrBehavior: string) => string;
+  generateClaimId: (subjectId: string, facet: string, fieldOrBehavior: string) => string;
   statusFunctionVersion: string;
   resolveInquiry: (
     bundle: Record<string, unknown>,
@@ -241,6 +379,48 @@ function criterionStatusToEventStatus(status: string): string | null {
   if (status === "accepted_gap") 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: string | undefined, hasCommand: boolean): { evidenceType: string; method: string; reconcilable: boolean } {
+  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: string, findings: AnyObj[]): string | null {
   if (verdict === "fail") return "disputed";
@@ -281,14 +461,29 @@ export async function buildTrustBundle(slug: string, timestamp: string, checks:
   const events: AnyObj[] = [];
   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<string, AnyObj>();
   const ensurePolicy = (claimType: string, impactLevel: string, requiredEvidence: string[]): AnyObj => {
-    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;
   };
@@ -402,12 +597,28 @@ export async function buildTrustBundle(slug: string, timestamp: string, checks:
     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 as AnyObj : 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 as AnyObj : null;
+    const claimMetadata: AnyObj | null = (waiver || promotionMeta) ? { ...(waiver ? { waiver } : {}), ...(promotionMeta ? { promotion: promotionMeta } : {}) } : null;
 
     const claimEvents: AnyObj[] = [];
     if (evStatus) {
@@ -415,11 +626,17 @@ export async function buildTrustBundle(slug: string, timestamp: string, checks:
       events.push(evt);
       claimEvents.push(evt);
     }
-    const evItem: AnyObj = { 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: AnyObj = { 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);
 
@@ -428,13 +645,13 @@ export async function buildTrustBundle(slug: string, timestamp: string, checks:
     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: AnyObj = { 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: AnyObj = { 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 as Record<string, unknown>, evidence: [evItem] as Record<string, unknown>[], events: claimEvents as Record<string, unknown>[], policies: [declaredPolicy] as Record<string, unknown>[] });
       claims.push({ ...declaredClaimObj, status: declaredStatus });
     } else {
       // No active flow step — only the workflow.* primary claim (legitimate no-flow fallback path).
-      const claimObj: AnyObj = { 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: AnyObj = { 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 as Record<string, unknown>, evidence: [evItem] as Record<string, unknown>[], events: claimEvents as Record<string, unknown>[], policies: [policy] as Record<string, unknown>[] });
       claims.push({ ...claimObj, status: derivedStatus });
     }
@@ -461,12 +678,12 @@ export async function buildTrustBundle(slug: string, timestamp: string, checks:
     if (declared) {
       // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
       const declaredPolicy = ensurePolicy(declared.claimType, "high", []);
-      const declaredClaimObj: AnyObj = { 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: AnyObj = { 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 as Record<string, unknown>, evidence: [], events: claimEvents as Record<string, unknown>[], policies: [declaredPolicy] as Record<string, unknown>[] });
       claims.push({ ...declaredClaimObj, status: declaredStatus });
     } else {
       // No active flow step — only the workflow.* primary claim (legitimate no-flow fallback path).
-      const claimObj: AnyObj = { 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: AnyObj = { 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 as Record<string, unknown>, evidence: [], events: claimEvents as Record<string, unknown>[], policies: [policy] as Record<string, unknown>[] });
       claims.push({ ...claimObj, status: derivedStatus });
     }
@@ -493,19 +710,19 @@ export async function buildTrustBundle(slug: string, timestamp: string, checks:
     if (declared) {
       // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
       const declaredPolicy = ensurePolicy(declared.claimType, "medium", []);
-      const declaredClaimObj: AnyObj = { 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: AnyObj = { 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 as Record<string, unknown>, evidence: [], events: claimEvents as Record<string, unknown>[], policies: [declaredPolicy] as Record<string, unknown>[] });
       claims.push({ ...declaredClaimObj, status: declaredStatus });
     } else {
       // No active flow step — only the workflow.* primary claim (legitimate no-flow fallback path).
-      const claimObj: AnyObj = { 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: AnyObj = { 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 as Record<string, unknown>, evidence: [], events: claimEvents as Record<string, unknown>[], policies: [policy] as Record<string, unknown>[] });
       claims.push({ ...claimObj, status: derivedStatus });
     }
   }
 
   return {
-    schemaVersion: 3,
+    schemaVersion: 5,
     source: `flow-agents/workflow-sidecar;statusFunctionVersion=${statusFunctionVersion}`,
     claims,
     evidence: evidenceItems,
@@ -536,7 +753,7 @@ export async function writeTrustBundle(dir: string, slug: string, timestamp: str
       const raw = fs.readFileSync(path.join(dir, "command-log.jsonl"), "utf8");
       commandLog = raw.split("\n").map((l) => l.trim()).filter(Boolean).map((l) => { try { return JSON.parse(l) as AnyObj; } catch { return null; } }).filter((x): x is AnyObj => 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);
@@ -743,6 +960,20 @@ function definitionAcceptanceLines(markdown: string): string[] {
   }
   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: string, name: string): string {
+  const re = new RegExp(`^${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:\\s*(.+)$`, "m");
+  return re.exec(markdown)?.[1]?.trim() ?? "";
+}
 function parseCriterion(line: string, index: number): AnyObj {
   let text = line.replace(/^-\s+\[[ xX]\]\s*/, "").trim();
   const m = /\s+-\s+Evidence:\s*(.+)$/i.exec(text);
@@ -777,14 +1008,20 @@ function validateAgentId(agent: string): string {
 
 /**
  * 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: string): string {
+function findRepoRootFromDirStrict(startDir: string): string | null {
   let dir = startDir;
   for (let i = 0; i < 16; i++) {
     if (fs.existsSync(path.join(dir, "kits"))) return dir;
@@ -792,7 +1029,24 @@ function findRepoRootFromDir(startDir: string): string {
     if (parent === dir) 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: string): string {
+  return findRepoRootFromDirStrict(startDir) ?? process.cwd();
 }
 
 /**
@@ -825,7 +1079,11 @@ function resolveFirstStep(flowId: string, repoRoot: string): string | null {
   }
 }
 
-function writeCurrent(root: string, dir: string, timestamp: string, owner: string, source: string, flowId?: string, stepId?: string): void {
+function writeCurrent(root: string, dir: string, timestamp: string, owner: string, source: string, flowId?: string, stepId?: string, adHocReason?: string): void {
+  // #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),
@@ -834,11 +1092,17 @@ function writeCurrent(root: string, dir: string, timestamp: string, owner: strin
     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: string): AnyObj | null {
@@ -850,7 +1114,13 @@ function currentDir(root: string): string | null {
   const c = loadCurrent(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: string, dir: string, agentId: string, status: string, timestamp: string): void {
   const cur = loadCurrent(root);
@@ -864,8 +1134,38 @@ function updateCurrentAgent(root: string, dir: string, agentId: string, status:
 
 function initSidecars(dir: string, slug: string, sourceRequest: string, summary: string, nextAction: string, timestamp: string, markdown?: string): void {
   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 },
   });
@@ -887,7 +1187,12 @@ function ensureSession(p: ReturnType<typeof parseArgs>): number {
   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"))) {
@@ -901,13 +1206,26 @@ function ensureSession(p: ReturnType<typeof parseArgs>): number {
   // 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: string | undefined;
   if (flowId && !stepId) {
     const repoRoot = findRepoRootFromDir(dir);
     const firstStep = resolveFirstStep(flowId, repoRoot);
     if (firstStep) stepId = firstStep;
+  } else if (flowId && explicitStep) {
+    // WS8 (AC12): --step-id is the sanctioned ad-hoc direct-entry mechanism. When it names
+    // a step other than the flow's resolved first step, record an explicit ad_hoc_entry
+    // marker (with a reason) instead of silently letting the mis-stamp look like the
+    // flow's normal first step. This is the root-cause fix for a planning-only session
+    // whose active_step_id would otherwise default to builder.build's first step.
+    const repoRoot = findRepoRootFromDir(dir);
+    const firstStep = resolveFirstStep(flowId, repoRoot);
+    if (firstStep && firstStep !== explicitStep) {
+      adHocReason = opt(p, "ad-hoc-reason") || `direct entry at step "${explicitStep}" via --step-id (flow first step is "${firstStep}")`;
+    }
   }
-  writeCurrent(root, dir, timestamp, "workflow-sidecar", "ensure-session", flowId || undefined, stepId || undefined);
+  writeCurrent(root, dir, timestamp, "workflow-sidecar", "ensure-session", flowId || undefined, stepId || undefined, adHocReason);
   console.log(dir);
   return 0;
 }
@@ -928,7 +1246,7 @@ function recordAgentEvent(p: ReturnType<typeof parseArgs>): number {
   const dir = explicit ? path.resolve(explicit) : currentDir(root);
   if (!dir || !fs.existsSync(dir)) die("artifact directory does not exist");
   if (explicit && fs.lstatSync(dir).isSymbolicLink()) die(`artifact directory must not be a symlink: ${dir}`);
-  if (hasExplicitRoot) requireArtifactDirUnderRoot(dir, root);
+  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") } : {}) };
@@ -986,7 +1304,7 @@ export function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[] {
 export function normalizeCheck(raw: AnyObj): AnyObj {
   const check = { ...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");
+    if (!checkKinds.has(check.kind)) die("kind must be one of: build, types, lint, test, command, security, diff, browser, runtime, policy, external");
   if (!checkStatuses.has(check.status)) die("status must be one of: pass, fail, not_verified, skip");
   if (Array.isArray(check.standard_refs)) for (const ref of check.standard_refs) if (!["junit", "sarif", "coverage", "veritas"].includes(ref.standard)) die("standard must be one of");
   if (check.artifact_refs) check.artifact_refs = normalizeEvidenceRefs(check.artifact_refs, "artifact_refs");
@@ -1129,7 +1447,7 @@ export function writeState(dir: string, slug: string, status: string, phase: str
 // "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.
@@ -1213,12 +1531,46 @@ function critiquesFromBundle(dir: string, declaredClaimTypes: Set<string> = new
   }));
 }
 // ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 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: ReturnType<typeof parseArgs>, ts: string): AnyObj | null {
+  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: ReturnType<typeof parseArgs>): Promise<number> {
   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 as AnyObj).command === "string" && String((c as AnyObj).command).trim().length > 0;
+      if (classifyEvidence((c as AnyObj).kind as string | undefined, hasCmd).evidenceType === "test_output") {
+        die(`--accepted-gap-reason/--waived-by cannot be applied to a command-backed check (kind='${String((c as AnyObj).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);
   // Phase 4c: bundle is the sole verification artifact — stop writing evidence.json and acceptance.json update.
@@ -1319,12 +1671,106 @@ async function recordGateClaim(p: ReturnType<typeof parseArgs>): Promise<number>
   }
 
   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: ReturnType<typeof parseArgs>): Promise<number> {
+  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: string[] = [];
+  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: AnyObj = {
+    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: AnyObj = { 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: AnyObj[] = 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: unknown) => {
+      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: ReturnType<typeof parseArgs>): Promise<number> {
   const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
   const status = opt(p, "status");
@@ -1375,7 +1821,14 @@ async function advanceState(p: ReturnType<typeof parseArgs>): Promise<number> {
   if (status === "delivered") {
     await sealTrustCheckpoint(dir, slug, timestamp, status, "release").catch(() => { /* best-effort; checkpoint seal must not break advance-state */ });
     // Publish delivery bundle: best-effort copy to delivery/ for CI trust-reconcile.
-    await publishDelivery(dir, findRepoRootFromDir(dir)).catch(() => { /* best-effort; must not break advance-state */ });
+    // 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: unknown) => {
+      process.stderr.write(`[advance-state] WARNING: publish-delivery failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    });
   }
   return 0;
 }
@@ -1442,7 +1895,14 @@ async function recordRelease(p: ReturnType<typeof parseArgs>): Promise<number> {
   // Trust checkpoint: seal at the "delivered" moment (the natural terminal mark for record-release).
   await sealTrustCheckpoint(dir, slug, payload.updated_at, "delivered", "release").catch(() => { /* best-effort; checkpoint seal must not break record-release */ });
   // Publish delivery bundle: best-effort copy to delivery/ for CI trust-reconcile.
-  await publishDelivery(dir, findRepoRootFromDir(dir)).catch(() => { /* best-effort; must not break record-release */ });
+  // 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: unknown) => {
+    process.stderr.write(`[record-release] WARNING: publish-delivery failed: ${err instanceof Error ? err.message : String(err)}\n`);
+  });
   return 0;
 }
 
@@ -1657,7 +2117,7 @@ async function sealCheckpoint(p: ReturnType<typeof parseArgs>): Promise<number>
 
 // ─── 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.
@@ -1672,13 +2132,25 @@ async function sealCheckpoint(p: ReturnType<typeof parseArgs>): Promise<number>
  * 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: string, repoRoot: string): Promise<void> {
+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`);
+    return;
+  }
+
   const deliveryDir = path.join(repoRoot, "delivery");
   fs.mkdirSync(deliveryDir, { recursive: true });
 
@@ -1713,7 +2185,10 @@ export async function publishDelivery(dir: string, repoRoot: string): Promise<vo
  */
 async function publishDeliveryCmd(p: ReturnType<typeof parseArgs>): Promise<number> {
   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;
 }
@@ -1890,7 +2365,7 @@ export interface TrustClaim {
   id: string;
   subjectType: string;
   subjectId: string;
-  surface: string;
+  facet?: string;
   claimType: string;
   fieldOrBehavior: string;
   value: string;
@@ -1909,7 +2384,7 @@ export interface BundleFile {
   policies: AnyObj[];
 }
 
-/** The gate block signal read from .flow-agents/.goal-fit-block-streak.json */
+/** The gate block signal read from .kontourai/flow-agents/.goal-fit-block-streak.json */
 export interface GateBlockSignal {
   /** True when the streak file exists AND count >= 1 */
   blocked: boolean;
@@ -1926,13 +2401,13 @@ export interface GateBlockSignal {
 export type GateCalibration = "correct" | "false_block" | "missed_block";
 
 /**
- * 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: string): GateBlockSignal {
   const streakFile = path.join(artifactRoot, ".goal-fit-block-streak.json");
@@ -2159,7 +2634,7 @@ export function buildGateInquiryRecords(
  *
  * 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).
@@ -2185,7 +2660,7 @@ async function gateReview(p: ReturnType<typeof parseArgs>): Promise<number> {
 
   const bundle: BundleFile = 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);
 
@@ -2342,7 +2817,7 @@ function trustMcp(p: ReturnType<typeof parseArgs>): number {
   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") die("trust-mcp --mode must be print|enable|disable");
@@ -2386,12 +2861,25 @@ const LIVENESS_POLICY = {
   impactLevel: "medium",
 };
 
-function livenessStreamFile(root: string): string { return path.join(root, "liveness", "events.jsonl"); }
-function appendLivenessEvent(root: string, evt: AnyObj): void {
-  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(): {
+  livenessStreamFile: (root: string) => string;
+  appendLivenessEvent: (root: string, evt: AnyObj) => void;
+} {
+  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) as {
+    livenessStreamFile: (root: string) => string;
+    appendLivenessEvent: (root: string, evt: AnyObj) => void;
+  };
 }
+function livenessStreamFile(root: string): string { return loadLivenessWriteHelper().livenessStreamFile(root); }
+function appendLivenessEvent(root: string, evt: AnyObj): void { loadLivenessWriteHelper().appendLivenessEvent(root, evt); }
 function readLivenessEvents(root: string): AnyObj[] {
   // 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.
@@ -2414,36 +2902,168 @@ function livenessLabel(status: string): string {
   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(): string { return (process.env.FLOW_AGENTS_ACTOR || "").trim() || "local"; }
-function livenessEnabled(): boolean { 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(): {
+  resolveActor: (env: NodeJS.ProcessEnv) => { actor: string; source: string };
+  sanitizeSegment: (value: unknown) => string;
+  isUnresolvedActor: (actor: string) => boolean;
+} {
+  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) as {
+    resolveActor: (env: NodeJS.ProcessEnv) => { actor: string; source: string };
+    sanitizeSegment: (value: unknown) => string;
+    isUnresolvedActor: (actor: string) => boolean;
+  };
+}
+function resolveLivenessActor(): string {
+  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(): {
+  isLivenessEnabled: (env: NodeJS.ProcessEnv) => boolean;
+  resolveTtlSeconds: (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;
+  };
+}
+function livenessEnabled(): boolean { 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: string, slug: string, kind: "claim" | "heartbeat" | "release", timestamp: string): void {
-  if (!livenessEnabled()) return;
   try {
-    const root = path.dirname(taskDir); // .flow-agents/<slug> → .flow-agents (the shared liveness stream lives here)
-    const evt: AnyObj = { type: kind, subjectId: slug, actor: resolveLivenessActor(), at: timestamp, source: "lifecycle" };
-    if (kind === "claim") evt.ttlSeconds = 1800;
+    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: AnyObj = { type: kind, subjectId: slug, actor, at: timestamp, source: "lifecycle" };
+    if (kind === "claim") 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: unknown): string {
+  return String(value ?? "").replace(/[\u0000-\u001F\u007F-\u009F]/g, "");
 }
 
 async function liveness(p: ReturnType<typeof parseArgs>): Promise<number> {
   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: AnyObj = { 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;
   }
 
@@ -2467,16 +3087,103 @@ async function liveness(p: ReturnType<typeof parseArgs>): Promise<number> {
     const rows: AnyObj[] = [];
     for (const g of groups.values()) {
       if (subjectFilter && g.subjectId !== subjectFilter) continue;
-      const claim: AnyObj = { 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: AnyObj = { 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) });
     }
     if (p.flags.has("json")) { console.log(JSON.stringify(rows, null, 2)); return 0; }
-    for (const r of rows) console.log(`${r.subjectId}\t${r.actor}\t${r.label}`);
+    for (const r of rows) 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) as { freshHolders: (events: AnyObj[], slug: string, selfActor: string, nowMs: number) => AnyObj[] };
+    // 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: string): string => {
+      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: AnyObj[] = 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: AnyObj | null = null;
+    let losers: AnyObj[] = [];
+    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: AnyObj | null): AnyObj | null =>
+        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 as AnyObj).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 as AnyObj).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;
 }
 // ─────────────────────────────────────────────────────────────────────────────
@@ -2652,9 +3359,24 @@ Available claim ids:
 async function main(): Promise<number> {
   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);
@@ -2663,6 +3385,7 @@ async function main(): Promise<number> {
       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);
@@ -2674,6 +3397,7 @@ async function main(): Promise<number> {
       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}`);