@kontourai/flow-agents 2.4.0 → 3.1.0

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
@@ -8,6 +9,11 @@ import { fileURLToPath } from "node:url";
 // ADR 0016 Abstraction A: shared FlowDefinition resolver (P-a)
 import { resolveActiveFlowStep, resolveFlowFilePath, resolvePhaseMap, resolveRouteBackPolicy } from "../lib/flow-resolver.js";
 import { defaultArtifactRootForRead, flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
+// #291 Wave 1 Task 1.1 exports: ensure-session's ownership guard reuses the EXACT same
+// assignment ⋈ liveness join / claim / supersede logic #290 already ships for the
+// `assignment-provider` CLI, rather than reimplementing a second, parallel join (static ESM
+// import — same idiom already used above for ../lib/flow-resolver.js).
+import { computeEffectiveState, performLocalClaim, performLocalSupersede, readLocalAssignmentStatus } from "./assignment-provider.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", "command", "security", "diff", "browser", "runtime", "policy", "external"]);
@@ -177,6 +183,74 @@ function validateExplicitBranch(value) {
         fail(gitMessage ? `git check-ref-format rejected the value: ${gitMessage}` : "git check-ref-format rejected the value");
     }
 }
+/**
+ * #291 Wave 2 Task 2.1: the single shared actor resolver for ensure-session — used by BOTH
+ * resolveSessionBranch() (below) and the new ownership guard inside ensureSession(), so the
+ * branch-naming actor and the assignment-claim actor are ALWAYS derived from the same one
+ * resolution pass (never re-derived twice with any risk of divergence). Same explicit-actor
+ * validation/die behavior as before this refactor (garbage --actor still dies; ambiguous/
+ * unresolved actor never hard-fails session creation — Design Decision 4).
+ *
+ * Returns TWO distinct identity strings, not one, because this repo already has two genuinely
+ * different actor-identity conventions in play and reconciling them into a single string would
+ * either break existing branch-naming byte-for-byte (see test_workflow_sidecar_writer.sh AC4) or
+ * break self-recognition against a durable assignment-claim record:
+ *   - `branchActorKey`: the flat, single-token-or-triple string this file has ALWAYS used for
+ *     branch naming, liveness `--actor`, and (Wave 2 Task 2.1 §6) per-actor current.json
+ *     partitioning — exactly `resolveActor(env).actor`, or the bare sanitized explicit --actor
+ *     override, unchanged from before this refactor.
+ *   - `actorStruct` / `claimActorKey` (`= serializeActor(actorStruct)`): a structured ActorStruct
+ *     for the assignment-provider claim record's `actor` field (Wave 1's `performLocalClaim`/
+ *     `performLocalSupersede` require one), and the identity string passed as `computeEffectiveState`'s
+ *     `selfActor` param. For the common/default case (no explicit --actor override — the ambient
+ *     runtime-session-id or process-ancestry derivation), this is reconstructed from the SAME
+ *     exported primitives `resolveActor()` uses internally, so `claimActorKey` reproduces
+ *     `branchActorKey` bit-for-bit. For an explicit --actor override, no ambient ActorStruct
+ *     exists (resolveActor()'s override branch is a flat bypass, never a serializeActor() triple),
+ *     so a synthetic-but-deterministic wrapper is used instead — self-recognition on reentry still
+ *     holds (same override value always re-derives the same claimActorKey), but this synthetic key
+ *     will not equal a DIFFERENT process's flat `liveness claim --actor <sameOverrideValue>` actor
+ *     string (that command's own `--actor` bypass strips the same override value's ':' or wraps it
+ *     no differently — a pre-existing seam between the liveness-actor and assignment-actor
+ *     identity domains, not introduced by this task; see Wave 2 Task 2.1 plan Conflict #3).
+ */
+function resolveEnsureSessionActor(p) {
+    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 explicitActor = explicitActorRaw ? helper.sanitizeSegment(explicitActorRaw) : "";
+    const resolved = explicitActor ? { actor: explicitActor, source: "explicit-override" } : helper.resolveActor(process.env);
+    const unresolved = helper.isUnresolvedActor(resolved.actor);
+    const branchActorKey = unresolved ? `unknown-actor-${unknownDisambiguator(resolved.actor)}` : resolved.actor;
+    if (unresolved) {
+        // Design Decision 4 (unchanged): never hard-fail session creation on actor ambiguity. No real
+        // ActorStruct exists for "unresolved" — the guard (ensureSession) is responsible for skipping
+        // the ownership guard entirely when unresolved, rather than claiming under a synthetic identity.
+        return { actorStruct: { runtime: "unresolved", session_id: branchActorKey, host: os.hostname() }, actorKey: resolved.actor, branchActorKey, unresolved: true };
+    }
+    const actorStruct = resolved.source === "explicit-override"
+        ? { runtime: "explicit-override", session_id: resolved.actor, host: os.hostname() }
+        : { runtime: helper.detectRuntime(process.env), session_id: helper.runtimeSessionId(process.env) || (() => { const seed = helper.ancestorActorSeed(); return seed ? `anc-${seed}` : ""; })(), host: os.hostname() };
+    const actorKey = helper.serializeActor(actorStruct);
+    return { actorStruct, actorKey, branchActorKey, unresolved: false };
+}
+/**
+ * Resolve an actor key for a READ-ONLY consumer (current(), currentDir(), recordAgentEvent(),
+ * writeTrustBundle()'s default) — deliberately lenient (never
+ * dies on a garbage --actor value; that enforcement belongs only to the write/claim path in
+ * resolveEnsureSessionActor above). Falls back to resolveActor(process.env) exactly like every
+ * write path already does. The returned value is passed straight into
+ * scripts/hooks/lib/current-pointer.js's readCurrentPointer(), which already tolerates an empty
+ * or unresolved actor by falling straight through to the legacy current.json branch — so an
+ * unresolved actor here reproduces exactly today's (pre-#291) legacy-only read behavior.
+ */
+function resolveReadActorKey(p) {
+    const helper = loadActorIdentityHelper();
+    const explicit = opt(p, "actor", "").trim();
+    return explicit ? helper.sanitizeSegment(explicit) : helper.resolveActor(process.env).actor;
+}
 /** 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
@@ -193,13 +267,12 @@ function resolveSessionBranch(p, slug) {
         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);
+    // #291 Wave 2 Task 2.1: actor resolution is now single-sourced via resolveEnsureSessionActor()
+    // (shared with the new ownership guard) — branchActorKey reproduces EXACTLY what this function's
+    // own inline `actor` variable used to compute, so branch naming is byte-identical to before this
+    // refactor (proven by test_workflow_sidecar_writer.sh's AC2/AC4/AC5 branch-naming assertions).
+    const { branchActorKey, unresolved } = resolveEnsureSessionActor(p);
+    const safeActor = unresolved ? branchActorKey : sanitizeBranchSegment(branchActorKey, 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)}`;
@@ -403,7 +476,7 @@ function critiqueToEventStatus(verdict, findings) {
  * @param critiques  Critique objects (from critique.json .critiques array)
  * @param commandLog Optional parsed command-log.jsonl entries (capture-authoritative fold)
  */
-export async function buildTrustBundle(slug, timestamp, checks, criteria, critiques, commandLog, flowAgentsDir) {
+export async function buildTrustBundle(slug, timestamp, checks, criteria, critiques, commandLog, flowAgentsDir, actorKey) {
     const surface = await tryLoadSurface();
     if (!surface)
         return null;
@@ -413,7 +486,10 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
     // each produced claim gets a DECLARED primary claim (kit-typed) plus a legacy shadow
     // (workflow.* type, claimId suffix "-legacy") for backward compatibility. When null,
     // only the existing workflow.* claims are produced (zero behavior change).
-    const activeStep = flowAgentsDir ? resolveActiveFlowStep(flowAgentsDir) : null;
+    // #291 Wave 2 Task 2.1 (§7)/Task 2.2: actorKey (when the caller already resolved one — see
+    // writeTrustBundle below) threads through to resolveActiveFlowStep's per-actor-first,
+    // legacy-fallback current.json read; omitted, this is IDENTICAL to pre-#291 behavior.
+    const activeStep = flowAgentsDir ? resolveActiveFlowStep(flowAgentsDir, actorKey) : null;
     const claims = [];
     const evidenceItems = [];
     const events = [];
@@ -581,7 +657,11 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         // (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;
+        // #268: stamp a stable origin discriminator so checksFromBundle / critiquesFromBundle can
+        // distinguish check vs critique vs acceptance claims across round-trips even under --flow-id,
+        // where all three collapse onto the same declared claimType (and a command-less critique claim
+        // would otherwise be re-absorbed as a test_output check → permanent [not-run] divergence).
+        const claimMetadata = { origin: "check", check_kind: String(check.kind ?? "external"), ...(waiver ? { waiver } : {}), ...(promotionMeta ? { promotion: promotionMeta } : {}) };
         const claimEvents = [];
         if (evStatus) {
             const evt = { id: `evt:${claimId}`, claimId, status: evStatus, actor: "flow-agents/workflow-sidecar", method: "validation", evidenceIds: [evId], createdAt: ts, verifiedAt: ts };
@@ -640,13 +720,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, facet: "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, metadata: { origin: "acceptance" } };
             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, facet: "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, metadata: { origin: "acceptance" } };
             const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [], events: claimEvents, policies: [policy] });
             claims.push({ ...claimObj, status: derivedStatus });
         }
@@ -657,10 +737,23 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
             continue;
         const subjectId = `${slug}/${c.id}`;
         const fieldOrBehavior = String(c.summary ?? c.verdict ?? c.id);
-        const claimId = generateClaimId(subjectId, "flow-agents.workflow", fieldOrBehavior);
+        // #267/#282: a critique carrying `superseded_by` is retained as HISTORY — a prior write for
+        // this critique id that a later, same-reviewer critique resolved. It is preserved structurally
+        // (status "superseded" + first-class metadata.superseded_by), but is excluded from reconcile
+        // evaluation and from the "critique pass cannot include fail members" validator rule.
+        const supersededBy = typeof c.superseded_by === "string" && c.superseded_by.length > 0 ? c.superseded_by : null;
+        const critiqueReviewer = String(c.reviewer ?? "tool-code-reviewer");
+        const critiqueReviewedAt = String(c.reviewed_at ?? ts);
+        const critMeta = { origin: "critique", reviewer: critiqueReviewer, reviewed_at: critiqueReviewedAt, ...(supersededBy ? { superseded_by: supersededBy } : {}) };
+        // A superseded historical write gets a distinct, stable claimId so it co-exists with the live
+        // claim of the same critique id (never overwrites or duplicates it). The salt is reproducible
+        // across rebuilds because superseded_by + reviewed_at are preserved in metadata.
+        const claimIdSalt = supersededBy ? `${fieldOrBehavior}::superseded::${supersededBy}::${critiqueReviewedAt}` : fieldOrBehavior;
+        const claimId = generateClaimId(subjectId, "flow-agents.workflow", claimIdSalt);
         const legacyClaimType = "workflow.critique.review";
         const policy = ensurePolicy(legacyClaimType, "medium", []);
-        const evStatus = critiqueToEventStatus(String(c.verdict ?? ""), c.findings ?? []);
+        // A superseded write emits NO verification event (its status is "superseded" directly).
+        const evStatus = supersededBy ? null : critiqueToEventStatus(String(c.verdict ?? ""), c.findings ?? []);
         const claimEvents = [];
         if (evStatus) {
             const evt = { id: `evt:${claimId}`, claimId, status: evStatus, actor: "flow-agents/workflow-sidecar", method: "validation", evidenceIds: [], createdAt: ts, verifiedAt: ts };
@@ -669,17 +762,16 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         }
         // P-d: declared-only when active flow/step present (shadow retired); no-flow path unchanged.
         const declared = matchExpectsEntry("critique");
-        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, 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 });
+        const claimType = declared ? declared.claimType : legacyClaimType;
+        const subjectType = declared ? declared.subjectType : "workflow-critique";
+        const claimPolicy = declared ? ensurePolicy(declared.claimType, "medium", []) : policy;
+        const claimObj = { id: claimId, subjectType, subjectId, facet: "flow-agents.workflow", claimType, fieldOrBehavior, value: c.verdict, createdAt: ts, updatedAt: ts, impactLevel: "medium", verificationPolicyId: claimPolicy.id, metadata: critMeta };
+        if (supersededBy) {
+            // History: status is "superseded" directly (no verification event); excluded from evaluation.
+            claims.push({ ...claimObj, status: "superseded" });
         }
         else {
-            // No active flow step — only the workflow.* primary claim (legitimate no-flow fallback path).
-            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] });
+            const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [], events: claimEvents, policies: [claimPolicy] });
             claims.push({ ...claimObj, status: derivedStatus });
         }
     }
@@ -705,7 +797,7 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
  * @param criteria   Acceptance criteria objects (same as buildTrustBundle)
  * @param critiques  Critique objects (same as buildTrustBundle)
  */
-export async function writeTrustBundle(dir, slug, timestamp, checks, criteria, critiques) {
+export async function writeTrustBundle(dir, slug, timestamp, checks, criteria, critiques, actorKey) {
     try {
         // Fold the deterministic capture log (PostToolUse evidence-capture) into the
         // bundle so capture is authoritative over claimed status. Best-effort read.
@@ -723,17 +815,23 @@ export async function writeTrustBundle(dir, slug, timestamp, checks, criteria, c
         // 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.
+        // #291 Wave 2 Task 2.1 (§7): the SOURCE of "what does current.json say" now prefers the
+        // resolved actor's own per-actor projection (falling back to the legacy global file) via the
+        // shared readCurrentPointer() helper — the "does artifact_dir match dir?" comparison itself is
+        // UNCHANGED. actorKey defaults to resolveActor(process.env) when the caller (below) does not
+        // already have one resolved, exactly like every other read-path consumer in this file.
         const _flowAgentsDir = path.dirname(dir);
+        const _effectiveActorKey = actorKey ?? loadActorIdentityHelper().resolveActor(process.env).actor;
         let _scopedFlowAgentsDir = undefined;
         try {
-            const _currentRaw = JSON.parse(fs.readFileSync(path.join(_flowAgentsDir, "current.json"), "utf8"));
-            const _artDir = typeof _currentRaw["artifact_dir"] === "string" ? _currentRaw["artifact_dir"] : null;
+            const _currentRaw = loadCurrentPointerHelper().readCurrentPointer(_flowAgentsDir, _effectiveActorKey).payload;
+            const _artDir = _currentRaw && typeof _currentRaw["artifact_dir"] === "string" ? _currentRaw["artifact_dir"] : null;
             if (_artDir && path.resolve(_flowAgentsDir, _artDir) === path.resolve(dir)) {
                 _scopedFlowAgentsDir = _flowAgentsDir;
             }
         }
         catch { /* current.json absent or unreadable — no scoping */ }
-        const bundle = await buildTrustBundle(slug, timestamp, checks, criteria, critiques, commandLog, _scopedFlowAgentsDir);
+        const bundle = await buildTrustBundle(slug, timestamp, checks, criteria, critiques, commandLog, _scopedFlowAgentsDir, _effectiveActorKey);
         if (!bundle)
             return { written: false, errors: [] }; // Surface unavailable — fail-open, skip write
         const result = await validateTrustBundle(bundle);
@@ -1094,12 +1192,34 @@ function resolveFirstStep(flowId, repoRoot) {
         return null;
     }
 }
-function writeCurrent(root, dir, timestamp, owner, source, flowId, stepId, adHocReason) {
+/**
+ * Delegate to the shared pure-CJS per-actor current-pointer helper
+ * (scripts/hooks/lib/current-pointer.js), mirroring the createRequire pattern already used above
+ * by loadActorIdentityHelper()/loadLivenessWriteHelper() for cross-boundary CJS helper reuse
+ * (#291 Wave 2 Task 2.1). This is the ONE place every current.json reader/writer in this file
+ * goes through from here on — the per-actor-first/legacy-fallback compat-shim rule (and its
+ * write-side counterpart) can never drift between call sites.
+ */
+function loadCurrentPointerHelper() {
+    const _req = createRequire(import.meta.url);
+    const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/current-pointer.js");
+    return _req(helperPath);
+}
+/**
+ * #291 Wave 2 Task 2.1 (§5): writes the UNCHANGED legacy global `<root>/current.json` (the
+ * compat-shim's write-side half — every existing consumer without an actorKey keeps reading
+ * exactly this file, exactly as before this change), then ADDITIONALLY projects the SAME payload
+ * into the caller's own `current/<actor>.json` when `actorKey` resolves to a real (not
+ * unresolved) actor. When `actorKey` is omitted or unresolved, only the legacy file is written —
+ * byte-identical to this function's pre-#291 behavior — with a stderr note mirroring the existing
+ * unresolved-actor branch-naming diagnostic.
+ */
+function writeCurrent(root, dir, timestamp, owner, source, flowId, stepId, adHocReason, actorKey) {
     // #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"), {
+    const payload = {
         schema_version: "1.0",
         active_slug: path.basename(dir),
         artifact_dir: path.relative(root, dir) || ".",
@@ -1118,7 +1238,21 @@ function writeCurrent(root, dir, timestamp, owner, source, flowId, stepId, adHoc
         // gate-review can distinguish an intentional direct entry (e.g. a planning-only
         // session that skips pull-work) from a stale/mis-stamped active_step_id.
         ...(adHocReason ? { ad_hoc_entry: true, ad_hoc_reason: adHocReason } : {}),
-    });
+    };
+    writeJson(path.join(root, "current.json"), payload);
+    if (actorKey && !loadActorIdentityHelper().isUnresolvedActor(actorKey)) {
+        try {
+            loadCurrentPointerHelper().writePerActorCurrent(root, actorKey, payload);
+        }
+        catch (err) {
+            // Best-effort projection only — the legacy file above is already durable and authoritative;
+            // a failure here must never affect ensure-session's own exit code (fail-open, visible).
+            process.stderr.write(`[ensure-session] failed to write per-actor current pointer: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    else {
+        process.stderr.write("[ensure-session] actor unresolved or not provided; per-actor current.json projection skipped (legacy current.json remains authoritative)\n");
+    }
 }
 function loadCurrent(root) {
     const file = path.join(root, "current.json");
@@ -1126,8 +1260,16 @@ function loadCurrent(root) {
         return null;
     return JSON.parse(read(file));
 }
-function currentDir(root) {
-    const c = loadCurrent(root);
+/**
+ * #291 Wave 2 Task 2.1 (§6): resolves the active session directory via the shared
+ * per-actor-first/legacy-fallback compat shim (readCurrentPointer) instead of the unconditional
+ * legacy-only loadCurrent() this function used before #291. When `actorKey` is omitted, empty, or
+ * unresolved, `readCurrentPointer` falls straight through to the legacy file — IDENTICAL to this
+ * function's pre-#291 behavior.
+ */
+function currentDir(root, actorKey) {
+    const pointer = loadCurrentPointerHelper().readCurrentPointer(root, actorKey);
+    const c = pointer.payload;
     if (!c)
         return null;
     const dir = path.resolve(root, c.artifact_dir ?? c.active_slug ?? "");
@@ -1141,16 +1283,38 @@ function currentDir(root) {
     }
     return dir;
 }
-function updateCurrentAgent(root, dir, agentId, status, timestamp) {
+/**
+ * #291 Wave 2 Task 2.1 (§6): updates BOTH the legacy current.json (when IT points at `dir` — the
+ * exact, unchanged existing check/write) AND the resolved actor's own per-actor current.json
+ * (independently, when IT points at `dir`) — never silently drops the legacy-file update path.
+ * The two checks are independent: either, both, or neither may fire depending on which
+ * pointer(s) currently reference `dir`.
+ */
+function updateCurrentAgent(root, dir, agentId, status, timestamp, actorKey) {
+    const applyAgentUpdate = (payload) => {
+        const active = Array.isArray(payload.active_agents) ? payload.active_agents.filter((a) => a.agent_id !== agentId) : [];
+        if (status === "active" || status === "blocked")
+            active.push({ agent_id: agentId, status, updated_at: timestamp });
+        return { ...payload, active_agents: active, updated_at: timestamp };
+    };
     const cur = loadCurrent(root);
-    if (!cur || path.resolve(root, cur.artifact_dir ?? "") !== path.resolve(dir))
-        return;
-    const active = Array.isArray(cur.active_agents) ? cur.active_agents.filter((a) => a.agent_id !== agentId) : [];
-    if (status === "active" || status === "blocked")
-        active.push({ agent_id: agentId, status, updated_at: timestamp });
-    cur.active_agents = active;
-    cur.updated_at = timestamp;
-    writeJson(path.join(root, "current.json"), cur);
+    if (cur && path.resolve(root, cur.artifact_dir ?? "") === path.resolve(dir)) {
+        writeJson(path.join(root, "current.json"), applyAgentUpdate(cur));
+    }
+    if (actorKey && !loadActorIdentityHelper().isUnresolvedActor(actorKey)) {
+        const helper = loadCurrentPointerHelper();
+        const perActorFile = helper.perActorCurrentFile(root, actorKey);
+        let perActor = null;
+        try {
+            perActor = fs.existsSync(perActorFile) ? JSON.parse(fs.readFileSync(perActorFile, "utf8")) : null;
+        }
+        catch {
+            perActor = null;
+        }
+        if (perActor && path.resolve(root, perActor.artifact_dir ?? "") === path.resolve(dir)) {
+            helper.writePerActorCurrent(root, actorKey, applyAgentUpdate(perActor));
+        }
+    }
 }
 function initSidecars(dir, slug, sourceRequest, summary, nextAction, timestamp, markdown) {
     const criteria = markdown ? definitionAcceptanceLines(markdown).map(parseCriterion) : [];
@@ -1198,10 +1362,191 @@ function initSidecars(dir, slug, sourceRequest, summary, nextAction, timestamp,
         ...sidecarBase(slug), summary, current_state_ref: "state.json", next_steps: nextAction ? [nextAction] : [], blockers: [], warnings: [],
     });
 }
+/** Read a `--*-json` flag's value as a file path (or `-` for stdin), mirroring
+ * assignment-provider.ts's own `loadJsonInput` convention — this file's OTHER `--*-json` flags
+ * (e.g. `--check-json`) instead take a literal inline JSON string via parseJson(), a DIFFERENT
+ * convention; `--effective-state-json` deliberately follows assignment-provider's file/stdin
+ * convention instead, since its value is the literal JSON `assignment-provider status
+ * --provider github ...` already prints to a file (or pipe), not something a caller would want to
+ * inline as a shell argument. */
+function loadJsonInputFile(file) {
+    return file === "-" ? JSON.parse(fs.readFileSync(0, "utf8")) : JSON.parse(read(file));
+}
+/**
+ * #291 Wave 2 Task 2.1 (§4): ensure-session's pre-entry ownership guard. MUST be called before
+ * any directory or file is created (a refusal must never leave a stray empty session dir) —
+ * ensureSession() calls this immediately, before `fs.mkdirSync(dir, ...)`. Reuses #290's
+ * assignment ⋈ liveness join (`computeEffectiveState`, Wave 1 export) so a fresh OTHER-actor claim
+ * refuses entry, a human assignment always asks first (never auto-reclaims), a stale
+ * (`reclaimable`) claim requires the explicit `--supersede-stale` takeover flag, and a `free`
+ * subject establishes a durable claim for the entering actor — ensure-session becomes a SECOND
+ * claim point, alongside pull-work (closing the loophole where a session entered without going
+ * through pull-work never gets a durable claim at all).
+ *
+ * Runs INSIDE ensureSession's existing root-level `withLock` (main(), unchanged) — no second/
+ * competing lock is introduced here. `performLocalClaim`/`performLocalSupersede`'s OWN internal
+ * `withSubjectLock` (a DIFFERENT lockdir, under `<root>/assignment/.<subject>.lockdir`) is what
+ * protects against a concurrent bare `assignment-provider claim` CLI invocation (e.g. from
+ * pull-work) racing this guard — two independent, non-conflicting lock resources.
+ *
+ * Every interpolated actor/holder/assignee/reason field in this function's die() messages is run
+ * through stripControlCharsForDisplay + a 64-char cap (AC9 — the #287/#320/#290 prompt-injection
+ * mitigation class: a hostile liveness event or a hand-crafted --effective-state-json fixture must
+ * never be able to smuggle raw control/ANSI bytes into this process's stderr/thrown message).
+ */
+function enforceEnsureSessionOwnership(p, root, slug, dir, resolution) {
+    if (p.flags.has("skip-ownership-guard")) {
+        process.stderr.write("[ensure-session] ownership guard skipped via --skip-ownership-guard\n");
+        return;
+    }
+    // Design Decision 4 (unchanged from resolveSessionBranch): actor-resolution ambiguity never
+    // hard-fails session creation. Without a resolvable actor there is no safe identity to claim
+    // under, so the guard is skipped entirely (documented scope boundary, not a silent hole) rather
+    // than claiming under a synthetic/unstable identity.
+    if (resolution.unresolved) {
+        process.stderr.write("[ensure-session] ownership guard not evaluated: actor is unresolved (set --actor or FLOW_AGENTS_ACTOR, or run inside a supported runtime) — proceeding without a durable claim, exactly as ensure-session behaved before #291\n");
+        return;
+    }
+    // F5 fix (fix-plan iteration 1, LOW): match assignment-provider.ts's sanitizeDisplayField
+    // two-tier convention (64 for id-like fields, 240 for free text) rather than asserting one
+    // uniform cap applies to every field class regardless of content. `sanitize` below is 64 chars —
+    // deliberately, not by uniform-cap default — because every value this function actually
+    // interpolates into a die()/stderr message is id-like (holder/actor key, subject slug, assignee,
+    // a claimed_at/last_at timestamp, the provider-kind enum); none of them is free text, so the
+    // id-like tier is the correct (not merely convenient) cap here. sanitizeDisplayField's 240
+    // free-text tier is for fields like a claim record's audit-trail `reason` (see
+    // assignment-provider.ts's sanitizeAuditEntryForDisplay) — this guard never echoes `--reason`
+    // into a die() message, so it has no free-text field requiring the 240 tier today.
+    const sanitize = (value) => stripControlCharsForDisplay(value).slice(0, 64);
+    const nowMs = opt(p, "now") ? Date.parse(opt(p, "now")) : Date.now();
+    const assignmentProviderKind = opt(p, "assignment-provider", "local-file");
+    let effective;
+    const effectiveStateJsonFlag = opt(p, "effective-state-json");
+    if (effectiveStateJsonFlag) {
+        const parsed = loadJsonInputFile(effectiveStateJsonFlag);
+        const candidate = parsed && typeof parsed === "object" ? parsed.effective : undefined;
+        const validStates = new Set(["held", "reclaimable", "human-held", "free"]);
+        if (!candidate || typeof candidate.effective_state !== "string" || !validStates.has(candidate.effective_state)) {
+            die(`ensure-session --effective-state-json must contain an .effective object with a recognized effective_state (held|reclaimable|human-held|free); got ${JSON.stringify(candidate ? candidate.effective_state : candidate)}`);
+        }
+        effective = candidate;
+    }
+    else if (assignmentProviderKind === "local-file") {
+        // Conflict #3 (plan): subjectId for BOTH the assignment lookup and the liveness freshHolders
+        // slug filter is `slug` — the ALREADY-COMPUTED session slug (workItemSlug()'s output), the
+        // exact same identifier pull-work itself uses for both halves of this same join. Never a
+        // second, independently-derived identifier.
+        // F1 fix (fix-plan iteration 1, HIGH): the guard's own self-check and the liveness join must
+        // key on `resolution.branchActorKey` — the canonical `resolveActor(env).actor` string — NOT
+        // `resolution.actorKey` (`serializeActor(actorStruct)`). For an explicit-override actor
+        // (FLOW_AGENTS_ACTOR) those two diverge: `actorKey` serializes to a triple
+        // (`explicit-override:<value>:<host>`) while `branchActorKey` is the bare value every other
+        // tool (`liveness whoami`, `liveness claim --actor`, per-actor current.json, pull-work's
+        // --self-actor) already uses. freshHolders' `selfActor` param and computeEffectiveState's
+        // `selfActor` param must both be the same canonical string the claim record's `actor_key` is
+        // written as (see the performLocalClaim/performLocalSupersede calls below) — otherwise a
+        // fresh heartbeat for this exact actor would never match the join, and
+        // `assignment-provider status --self-actor <branchActorKey>` run by a DIFFERENT tool
+        // afterward would never recognize this guard's own claim as self.
+        const assignment = readLocalAssignmentStatus(root, slug);
+        const events = readLivenessEvents(root);
+        const freshList = loadLivenessReadHelper().freshHolders(events, slug, resolution.branchActorKey, nowMs);
+        effective = computeEffectiveState(assignment, freshList, resolution.branchActorKey, nowMs);
+    }
+    else {
+        // Conflict #5 (plan): GitHub-provider (and any other non-local-file) subjects get no LIVE
+        // guard check here — assignment-provider.ts is deliberately render-don't-execute (no `gh`
+        // calls from any CLI file). A precomputed --effective-state-json is the escape hatch; when
+        // neither applies, this is a documented scope boundary (today's pre-#291 baseline behavior),
+        // never a silent hole.
+        process.stderr.write(`[ensure-session] ownership guard not evaluated: provider "${sanitize(assignmentProviderKind)}" requires --effective-state-json\n`);
+        return;
+    }
+    const resolveBranchForClaim = () => {
+        const existingBranch = fs.existsSync(path.join(dir, "state.json")) ? loadJson(path.join(dir, "state.json")).branch : undefined;
+        return existingBranch || resolveSessionBranch(p, slug);
+    };
+    switch (effective.effective_state) {
+        case "held": {
+            // F1 fix (fix-plan iteration 1, HIGH): compare against branchActorKey — the same canonical
+            // string just passed as computeEffectiveState's selfActor above — not actorKey (the wrapped
+            // ActorStruct triple), so this redundant belt-and-suspenders check agrees with the
+            // effective_state computation instead of silently using a different identity.
+            const isSelf = effective.reason === "self_is_holder" || (!!effective.holder?.actor && effective.holder.actor === resolution.branchActorKey);
+            if (isSelf)
+                return; // resume own session — no refusal
+            const holderActor = sanitize(effective.holder?.actor ?? "unknown");
+            const lastAtSuffix = effective.holder?.last_at ? ` (last_at ${sanitize(effective.holder.last_at)})` : "";
+            die(`ensure-session refused: subject ${sanitize(slug)} is currently held by a different, still-live actor (${holderActor}${lastAtSuffix}). Pick a different work item, or confirm the holder session is truly gone before considering a takeover.`);
+            return;
+        }
+        case "human-held": {
+            const assignee = effective.holder?.assignee ? sanitize(effective.holder.assignee) : "an assigned human";
+            const idleSuffix = effective.holder?.idle_days != null ? ` (idle ${Number(effective.holder.idle_days)} day(s))` : "";
+            die(`ensure-session refused: subject ${sanitize(slug)} is assigned to ${assignee}${idleSuffix}. This guard never auto-reclaims a human assignment — confirm with the user before proceeding.`);
+            return;
+        }
+        case "reclaimable": {
+            const holderActor = sanitize(effective.holder?.actor ?? "unknown");
+            const claimedAtSuffix = effective.holder?.last_at ? ` (claimed_at ${sanitize(effective.holder.last_at)})` : "";
+            if (!p.flags.has("supersede-stale")) {
+                die(`ensure-session refused: subject ${sanitize(slug)}'s existing claim (held by ${holderActor}${claimedAtSuffix}) is stale. Pass --supersede-stale to take it over explicitly.`);
+            }
+            const assignment = readLocalAssignmentStatus(root, slug);
+            const fromActor = assignment.record?.actor;
+            if (!fromActor)
+                die(`ensure-session --supersede-stale: no existing local-file claim record found for subject ${sanitize(slug)} to supersede`);
+            performLocalSupersede(root, slug, fromActor, resolution.actorStruct, {
+                branch: resolveBranchForClaim(),
+                artifactDir: path.relative(root, dir) || ".",
+                reason: opt(p, "reason", "ensure-session takeover: stale claim"),
+                // F1 fix (fix-plan iteration 1, HIGH): persist the canonical actor_key on the record so
+                // computeEffectiveState's holderActorKey (assignment-provider.ts) matches this same
+                // branchActorKey string on the next status/guard check, cross-tool.
+                actorKey: resolution.branchActorKey,
+            });
+            return;
+        }
+        case "free": {
+            performLocalClaim(root, slug, resolution.actorStruct, {
+                ttlSeconds: opt(p, "claim-ttl-seconds") ? Number(opt(p, "claim-ttl-seconds")) : loadLivenessPolicyHelper().resolveTtlSeconds(process.env),
+                branch: resolveBranchForClaim(),
+                artifactDir: path.relative(root, dir) || ".",
+                reason: opt(p, "reason", "ensure-session entry"),
+                // F1 fix (fix-plan iteration 1, HIGH): see the performLocalSupersede call above.
+                actorKey: resolution.branchActorKey,
+            });
+            return;
+        }
+        default:
+            die(`ensure-session ownership guard: unrecognized effective_state ${JSON.stringify(effective.effective_state)}`);
+    }
+}
+/**
+ * ensure-session flags added by #291 Wave 2 Task 2.1 (no printed --help/usage text exists in this
+ * file to update — this doc comment is the discoverable reference instead):
+ *   --skip-ownership-guard         Skip the pre-entry ownership guard entirely (logged, not silent).
+ *   --effective-state-json <path|-> Precomputed `{ effective: {...} }` JSON (the exact shape
+ *                                  `assignment-provider status` prints) — required to evaluate the
+ *                                  guard for any --assignment-provider other than local-file.
+ *   --assignment-provider <kind>   Defaults to "local-file"; see Conflict #5 in the plan for the
+ *                                  GitHub-provider scope boundary.
+ *   --now <iso>                    Deterministic "now" for freshness/idle-day computation (else
+ *                                  Date.now()).
+ *   --supersede-stale              Required to take over a `reclaimable` (stale) claim.
+ *   --claim-ttl-seconds <n>        Overrides the liveness-policy TTL default for a new claim.
+ *   --reason <text>                Audit-trail reason recorded on the claim/supersede record.
+ */
 function ensureSession(p) {
     const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : flowAgentsArtifactRoot();
     const slug = opt(p, "task-slug") || (opt(p, "work-item") ? workItemSlug(opt(p, "work-item")) : die("--task-slug is required (or pass --work-item to derive it)"));
     const dir = sessionDirFor(root, slug);
+    // #291 Wave 2 Task 2.1 (§3, §4): resolve the actor ONCE, then run the ownership guard BEFORE
+    // any directory/file is created — a refusal must never leave a stray empty session dir. Reused
+    // below (writeCurrent's per-actor dual-write) so the branch-naming actor and the
+    // assignment-claim actor are always the same identity.
+    const actorResolution = resolveEnsureSessionActor(p);
+    enforceEnsureSessionOwnership(p, root, slug, dir, actorResolution);
     fs.mkdirSync(dir, { recursive: true });
     const timestamp = opt(p, "timestamp", now());
     let md = fs.existsSync(path.join(dir, `${slug}--deliver.md`)) ? read(path.join(dir, `${slug}--deliver.md`)) : "";
@@ -1246,13 +1591,18 @@ function ensureSession(p) {
             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);
+    writeCurrent(root, dir, timestamp, "workflow-sidecar", "ensure-session", flowId || undefined, stepId || undefined, adHocReason, actorResolution.unresolved ? undefined : actorResolution.branchActorKey);
     console.log(dir);
     return 0;
 }
 function current(p) {
     const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : defaultArtifactRootForRead();
-    const dir = currentDir(root);
+    // #291 Wave 2 Task 2.1 (§6): new optional --actor override (same convention as
+    // resolveSessionBranch's existing --actor), falling back to resolveActor(process.env). Only the
+    // SOURCE of "what does current.json say" changes (per-actor-first, legacy-fallback) — this
+    // command's existing --format slug|path output is unchanged.
+    const actorKey = resolveReadActorKey(p);
+    const dir = currentDir(root, actorKey);
     if (!dir)
         die("no current workflow session is recorded");
     const format = opt(p, "format", "path");
@@ -1263,7 +1613,8 @@ function recordAgentEvent(p) {
     const hasExplicitRoot = !!opt(p, "artifact-root");
     const root = explicitArtifactRoot(p);
     const explicit = opt(p, "artifact-dir");
-    const dir = explicit ? path.resolve(explicit) : currentDir(root);
+    const actorKey = resolveReadActorKey(p);
+    const dir = explicit ? path.resolve(explicit) : currentDir(root, actorKey);
     if (!dir || !fs.existsSync(dir))
         die("artifact directory does not exist");
     if (explicit && fs.lstatSync(dir).isSymbolicLink())
@@ -1274,7 +1625,7 @@ function recordAgentEvent(p) {
     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") } : {}) };
     appendJsonl(path.join(dir, "agents", agent, "events.jsonl"), event);
-    updateCurrentAgent(root, dir, agent, event.status, timestamp);
+    updateCurrentAgent(root, dir, agent, event.status, timestamp, actorKey);
     return 0;
 }
 function initPlan(p) {
@@ -1504,67 +1855,70 @@ export function writeState(dir, slug, status, phase, timestamp, summary, next =
 // After 4c, evidence.json and critique.json are no longer written.
 // Extract checks and critiques from the existing trust.bundle for callers that
 // need to rebuild the bundle (e.g. record-critique, record-learning).
-// ADR 0016 Abstraction A (Step 0 Q3 carry-forward): build the set of declared
-// claimTypes from the active flow step for the session at `dir`. When no active
-// flow is present (workflow.* sessions), returns an empty set so every existing
-// predicate is unchanged. When a FlowDefinition-driven session (builder.build)
-// is active, the set contains the kit-typed claimTypes (e.g. "builder.verify.tests",
-// "builder.verify.policy-compliance") so round-trip helpers broaden their filters
-// to include declared claims alongside the legacy workflow.* ones.
+// #268/#344: buildTrustBundle stamps a stable origin discriminator ("check" | "acceptance" |
+// "critique") plus check_kind (for origin "check") on EVERY claim it writes. These stamps are
+// AUTHORITATIVE and the ONLY way checksFromBundle/critiquesFromBundle (and evidenceClean/
+// critiqueClean below) classify a claim.
 //
-// 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.
-// This prevents a cross-session active_flow_id from broadening claim filters for
-// unrelated sessions (which would cause spurious evidence/critique check behavior).
-function declaredClaimTypesFor(dir) {
-    const flowAgentsDir = path.dirname(dir);
-    // Verify that current.json points to `dir` before reading active flow step.
-    // If it points to a different session, return empty set (zero behavior change).
-    const currentFile = path.join(flowAgentsDir, "current.json");
-    try {
-        const current = JSON.parse(fs.readFileSync(currentFile, "utf8"));
-        const artDir = typeof current["artifact_dir"] === "string" ? current["artifact_dir"] : null;
-        if (!artDir)
-            return new Set();
-        const resolvedCurrent = path.resolve(flowAgentsDir, artDir);
-        if (path.resolve(dir) !== resolvedCurrent)
-            return new Set();
-    }
-    catch {
-        return new Set();
-    }
-    const activeStep = resolveActiveFlowStep(flowAgentsDir);
-    if (!activeStep || activeStep.gateExpects.length === 0)
-        return new Set();
-    return new Set(activeStep.gateExpects.map((e) => e.bundle_claim.claimType));
-}
-function checksFromBundle(dir, declaredClaimTypes = new Set()) {
+// Hard cutover (owner directive, no legacy fallbacks): there is deliberately no claimType-
+// derivation fallback for unstamped claims. A prior version of this file fell back to
+// classifying an unstamped claim by claimType heuristic — that fallback WAS the #268 defect
+// kept reachable (a no-evidence declared claim silently re-absorbed as a command-less
+// test_output check, and a critique claim silently re-absorbed as a check, corrupting the
+// round-trip catastrophically under --flow-id). An unstamped claim means the bundle predates
+// #344 and must be regenerated, not silently reclassified — see requireStampedClaim below.
+function claimOrigin(claim) {
+    const md = claim && claim.metadata;
+    return md && typeof md === "object" && typeof md.origin === "string" && md.origin.length > 0 ? String(md.origin) : null;
+}
+// Fails loud — never silent, never a heuristic reclassification — when a claim in `dir`'s
+// trust.bundle lacks its metadata.origin stamp, or (for an origin==="check" claim) its
+// metadata.check_kind stamp. Names the session dir and the remedy so the caller can regenerate
+// a fresh, fully-stamped bundle instead of reading a pre-supersession one.
+function requireStampedClaim(claim, dir) {
+    if (!claim || typeof claim !== "object")
+        die(`trust.bundle in ${dir} contains a malformed claim entry — cannot read.`);
+    const remedy = `re-record evidence to regenerate: npm run workflow:sidecar -- record-evidence ${dir} --verdict <verdict> --check-json <...>`;
+    const origin = claimOrigin(claim);
+    if (!origin) {
+        die(`pre-supersession trust.bundle in ${dir}: claim '${claim.id ?? "<unknown>"}' has no metadata.origin stamp (this bundle predates #344's origin/check_kind stamping and cannot be read authoritatively) — ${remedy}`);
+    }
+    if (origin === "check") {
+        const md = (claim.metadata && typeof claim.metadata === "object") ? claim.metadata : {};
+        if (typeof md.check_kind !== "string" || md.check_kind.length === 0) {
+            die(`pre-supersession trust.bundle in ${dir}: check claim '${claim.id ?? "<unknown>"}' has metadata.origin but no metadata.check_kind stamp (this bundle predates #344's stamping and cannot be read authoritatively) — ${remedy}`);
+        }
+    }
+    return origin;
+}
+function checksFromBundle(dir) {
     const bundle = loadJson(path.join(dir, "trust.bundle"));
+    const allClaims = Array.isArray(bundle.claims) ? bundle.claims : [];
+    // Validate stamps on every claim up front — any unstamped claim anywhere in the bundle marks
+    // it pre-supersession, regardless of whether it is check/acceptance/critique-typed.
+    for (const claim of allClaims)
+        requireStampedClaim(claim, dir);
     if (!Array.isArray(bundle.evidence))
         return [];
-    const allClaims = Array.isArray(bundle.claims) ? bundle.claims : [];
     const claimById = new Map();
     for (const c of allClaims)
         if (c && c.id)
             claimById.set(c.id, c);
     const seen = new Set();
     const checks = [];
+    const kindOf = (claim) => String(claim.metadata.check_kind);
     for (const ev of bundle.evidence) {
         if (!ev || !ev.claimId)
             continue;
         const claim = claimById.get(ev.claimId);
         if (!claim)
             continue;
-        const ct = String(claim.claimType || "");
-        // ADR 0016 Step 0: broaden to include declared kit-typed claims alongside workflow.check.*
-        if (!ct.startsWith("workflow.check.") && !declaredClaimTypes.has(ct))
+        if (claimOrigin(claim) !== "check")
             continue;
         if (seen.has(ev.claimId))
             continue;
         seen.add(ev.claimId);
-        const kind = ct.startsWith("workflow.check.") ? (ct.replace("workflow.check.", "") || "external") : (ct.split(".").pop() || "external");
+        const kind = kindOf(claim);
         const status = claim.value ?? "not_verified";
         const check = { id: String(claim.subjectId || "").split("/").pop() || ev.claimId, kind, status, summary: claim.fieldOrBehavior || "" };
         if (ev.execution && typeof ev.execution.label === "string")
@@ -1573,41 +1927,43 @@ function checksFromBundle(dir, declaredClaimTypes = new Set()) {
             check.evidenceType = ev.evidenceType;
         checks.push(check);
     }
-    // Also include check claims that have no evidence item (surface_trust_refs style)
+    // Also include check claims that have no evidence item (surface_trust_refs style).
     for (const claim of allClaims) {
         if (!claim)
             continue;
-        const ct = String(claim.claimType || "");
-        // ADR 0016 Step 0: broaden to include declared kit-typed claims alongside workflow.check.*
-        if (!ct.startsWith("workflow.check.") && !declaredClaimTypes.has(ct))
+        if (claimOrigin(claim) !== "check")
             continue;
         if (seen.has(claim.id))
             continue;
         seen.add(claim.id);
-        const kind = ct.startsWith("workflow.check.") ? (ct.replace("workflow.check.", "") || "external") : (ct.split(".").pop() || "external");
+        const kind = kindOf(claim);
         checks.push({ id: String(claim.subjectId || "").split("/").pop() || claim.id, kind, status: claim.value ?? "not_verified", summary: claim.fieldOrBehavior || "" });
     }
     return checks;
 }
-function critiquesFromBundle(dir, declaredClaimTypes = new Set()) {
+function critiquesFromBundle(dir) {
     const bundle = loadJson(path.join(dir, "trust.bundle"));
     if (!Array.isArray(bundle.claims))
         return [];
-    // ADR 0016 Step 0: broaden to include declared kit-typed critique claims alongside workflow.critique.review.
-    // P-d: exclude claims that have evidence items (evidence = check claims, not critique claims).
-    // This prevents check-type declared claims (e.g. builder.verify.tests) from being read back
-    // as critiques when declaredClaimTypes includes all gate expects[] types.
-    const evidenceClaimIds = new Set(Array.isArray(bundle.evidence) ? bundle.evidence.map((e) => e?.claimId).filter((id) => typeof id === "string") : []);
-    const critiqueClaims = bundle.claims.filter((c) => c && (c.claimType === "workflow.critique.review" || declaredClaimTypes.has(c.claimType)) && !evidenceClaimIds.has(c.id));
-    return critiqueClaims.map((c) => ({
-        id: String(c.subjectId || "").split("/").pop() || c.id,
-        verdict: c.value ?? "not_verified",
-        summary: c.fieldOrBehavior || "",
-        findings: [],
-        reviewer: "tool-code-reviewer",
-        reviewed_at: c.updatedAt || c.createdAt || now(),
-        artifact_refs: [],
-    }));
+    for (const c of bundle.claims)
+        requireStampedClaim(c, dir);
+    // A claim is a CRITIQUE when its origin is "critique" (authoritative — see requireStampedClaim
+    // above). reviewer / reviewed_at / superseded_by are read back from metadata so supersession
+    // (#267/#282) round-trips losslessly.
+    const critiqueClaims = bundle.claims.filter((c) => c && claimOrigin(c) === "critique");
+    return critiqueClaims.map((c) => {
+        const md = (c.metadata && typeof c.metadata === "object") ? c.metadata : {};
+        return {
+            id: String(c.subjectId || "").split("/").pop() || c.id,
+            verdict: c.value ?? "not_verified",
+            summary: c.fieldOrBehavior || "",
+            findings: [],
+            reviewer: typeof md.reviewer === "string" ? md.reviewer : "tool-code-reviewer",
+            reviewed_at: typeof md.reviewed_at === "string" ? md.reviewed_at : (c.updatedAt || c.createdAt || now()),
+            artifact_refs: [],
+            ...(typeof md.superseded_by === "string" && md.superseded_by.length > 0 ? { superseded_by: md.superseded_by } : {}),
+        };
+    });
 }
 // ─────────────────────────────────────────────────────────────────────────────
 /**
@@ -1662,7 +2018,11 @@ async function recordEvidence(p) {
     const _existingCriteria = Array.isArray(_existingAcceptance.criteria) ? _existingAcceptance.criteria : [];
     const _criteriaStatus = verdict === "pass" ? "pass" : verdict === "fail" ? "fail" : "not_verified";
     const _criteriaForBundle = _existingCriteria.map((c) => ({ ...c, status: _criteriaStatus }));
-    assertBundleWritten(await writeTrustBundle(dir, slug, ts, checks, _criteriaForBundle, []));
+    // #268: preserve any existing critique claims (including superseded history) instead of dropping
+    // them — record-evidence previously hardcoded critiques:[] here, silently erasing finding history
+    // whenever it ran after a critique existed.
+    const _existingCritiques = critiquesFromBundle(dir);
+    assertBundleWritten(await writeTrustBundle(dir, slug, ts, checks, _criteriaForBundle, _existingCritiques));
     const stateStatus = verdict === "pass" ? "verified" : verdict === "fail" ? "failed" : "not_verified";
     writeState(dir, slug, stateStatus, "verification", ts, "Evidence recorded.");
     return 0;
@@ -1707,9 +2067,14 @@ async function recordGateClaim(p) {
         die("--status must be one of: pass, fail, not_verified");
     const summary = opt(p, "summary") || die("--summary is required");
     const expectationId = opt(p, "expectation");
-    // Resolve the active flow step from current.json
+    // Resolve the active flow step from current.json. #291 Wave 2 Task 2.1 (§7)/Task 2.2: resolve
+    // the CALLING actor's own current-pointer (per-actor-first, legacy-fallback) rather than an
+    // unconditional legacy-only read — this is the fix for record-gate-claim's pre-existing (#291
+    // Stop-short risk) lack of a dir-scoping guard: it now resolves ITS OWN actor's current.json
+    // view, not a different actor's more-recently-written legacy pointer.
     const flowAgentsDir = path.dirname(dir);
-    const activeStep = resolveActiveFlowStep(flowAgentsDir);
+    const gateClaimActorKey = resolveReadActorKey(p);
+    const activeStep = resolveActiveFlowStep(flowAgentsDir, gateClaimActorKey);
     if (!activeStep)
         die("record-gate-claim requires an active flow step in current.json (set via ensure-session --flow-id or advance-state --flow-definition)");
     const expects = activeStep.gateExpects;
@@ -1756,7 +2121,7 @@ async function recordGateClaim(p) {
         checkNormalized._waiver = gateWaiver;
     // Log the targeted gate expectation for transparency (goes to stderr only)
     process.stderr.write(`[record-gate-claim] targeting ${activeStep.stepId}/${activeStep.gateId}/${targetExpectation.id} → claimType=${claimType} subjectType=${subjectType}${gateWaiver ? " (WAIVED accepted_gap)" : ""}\n`);
-    assertBundleWritten(await writeTrustBundle(dir, slug, ts, [checkNormalized], [], []));
+    assertBundleWritten(await writeTrustBundle(dir, slug, ts, [checkNormalized], [], [], gateClaimActorKey));
     return 0;
 }
 /**
@@ -1826,11 +2191,10 @@ async function promote(p) {
     // 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 existingChecks = checksFromBundle(dir).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);
+    const critiques = critiquesFromBundle(dir);
     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 });
@@ -1893,7 +2257,11 @@ async function advanceState(p) {
         const phaseMap = resolvePhaseMap(flow, repoRoot);
         const stepId = phaseMap?.[phase] ?? undefined;
         if (stepId) {
-            writeCurrent(root, dir, timestamp, "workflow-sidecar", "advance-state", flow, stepId);
+            // #291 Wave 2 Task 2.1 (§5): thread the calling actor through so this second writeCurrent()
+            // call site ALSO dual-writes the per-actor projection, not only ensure-session's call site —
+            // otherwise a session that only ever calls advance-state (never re-running ensure-session)
+            // would never get a per-actor current.json mirror for its own FlowDefinition routing keys.
+            writeCurrent(root, dir, timestamp, "workflow-sidecar", "advance-state", flow, stepId, undefined, resolveReadActorKey(p));
         }
     }
     livenessLifecycle(dir, slug, LIVENESS_TERMINAL.has(status) ? "release" : "heartbeat", timestamp);
@@ -1924,14 +2292,31 @@ async function recordCritique(p) {
     // Fall back to critique.json for legacy sessions that still have it on disk.
     const existingCritiqueJson = loadJson(path.join(dir, "critique.json"), { critiques: [] });
     const legacyCritiques = Array.isArray(existingCritiqueJson.critiques) ? existingCritiqueJson.critiques : [];
-    const _dctCritique = declaredClaimTypesFor(dir);
-    const bundleCritiques = legacyCritiques.length === 0 ? critiquesFromBundle(dir, _dctCritique) : legacyCritiques;
+    const bundleCritiques = legacyCritiques.length === 0 ? critiquesFromBundle(dir) : legacyCritiques;
     const critique = { id: opt(p, "id") || "review", reviewer: opt(p, "reviewer", "tool-code-reviewer"), reviewed_at: opt(p, "timestamp", now()), verdict: opt(p, "verdict", "pass"), summary: opt(p, "summary"), artifact_refs: opts(p, "artifact-ref"), findings: opts(p, "finding-json").map((v) => normalizeFinding(parseJson(v, "--finding-json"))) };
-    const critiques = [...bundleCritiques, critique];
     if (critique.verdict === "pass" && critique.findings.some((f) => f.status === "open"))
         die("required critique must pass");
+    // #267/#282: supersede-by-critique-id. The latest write for a critique id wins for
+    // reconcile / status / validator purposes; each prior LIVE write for the same id is RETAINED as
+    // history (status "superseded", first-class metadata.superseded_by) but excluded from evaluation.
+    // Supersession is REVIEWER-SCOPED (anti-gaming): a write may only supersede a prior live critique
+    // of the same id written by the SAME reviewer — a different reviewer's disputed finding is never
+    // buried, so it stays live and continues to block. DOCUMENTED GAP: reviewer identity is the
+    // free-form --reviewer string (with a default); there is no cryptographic worker-vs-reviewer
+    // distinction yet — that lands with the runtime actor-identity slice (#287/#290). Same-reviewer-
+    // string scoping is the strongest honest enforcement available today and matches the granularity
+    // the critique record already has.
+    const _supersedeMarker = `${critique.id}@${critique.reviewed_at}`;
+    const _mergedCritiques = bundleCritiques.map((e) => {
+        const eSuperseded = typeof e.superseded_by === "string" && e.superseded_by.length > 0;
+        const eReviewer = String(e.reviewer ?? "tool-code-reviewer");
+        if (e.id === critique.id && !eSuperseded && eReviewer === critique.reviewer)
+            return { ...e, superseded_by: _supersedeMarker };
+        return e;
+    });
+    const critiques = [..._mergedCritiques, critique];
     // Phase 4c: build bundle from raw inputs; read checks from trust.bundle (evidence.json no longer written).
-    const _critiqueEvChecks = checksFromBundle(dir, _dctCritique);
+    const _critiqueEvChecks = checksFromBundle(dir);
     const _critiqueAccCriteria = Array.isArray(loadJson(path.join(dir, "acceptance.json")).criteria) ? loadJson(path.join(dir, "acceptance.json")).criteria : [];
     assertBundleWritten(await writeTrustBundle(dir, slug, critique.reviewed_at, _critiqueEvChecks, _critiqueAccCriteria, critiques));
     return 0;
@@ -2327,26 +2712,23 @@ async function recordLearning(p) {
     writeJson(path.join(dir, "learning.json"), { ...sidecarBase(slug), status, updated_at: timestamp, records });
     writeState(dir, slug, "accepted", "learning", timestamp, opt(p, "summary"));
     // Phase 4c: build bundle from raw inputs; read checks/critiques from trust.bundle (bespoke sidecars no longer written).
-    // ADR 0016 Step 0: pass declaredClaimTypes so declared builder.* claims survive the round-trip.
-    const _dctLearning = declaredClaimTypesFor(dir);
-    const _learningChecks = checksFromBundle(dir, _dctLearning);
+    // #268/#344: declared builder.* claims survive the round-trip via their authoritative origin stamp.
+    const _learningChecks = checksFromBundle(dir);
     const _learningCriteria = Array.isArray(loadJson(path.join(dir, "acceptance.json")).criteria) ? loadJson(path.join(dir, "acceptance.json")).criteria : [];
-    const _learningCritiques = critiquesFromBundle(dir, _dctLearning);
+    const _learningCritiques = critiquesFromBundle(dir);
     assertBundleWritten(await writeTrustBundle(dir, slug, timestamp, _learningChecks, _learningCriteria, _learningCritiques));
     return 0;
 }
-function evidenceClean(dir, declaredClaimTypes = new Set()) {
-    // Phase 4c: read from trust.bundle (sole verification artifact); fall back to evidence.json for legacy sessions.
-    // ADR 0016 Step 0: declaredClaimTypes broadens the filter to include kit-typed check claims
-    // (e.g. builder.verify.tests) in addition to workflow.check.* for FlowDefinition-driven sessions.
+function evidenceClean(dir) {
+    // Phase 4c: read from trust.bundle (sole verification artifact); fall back to evidence.json for
+    // legacy (pre-bundle-era) sessions that never wrote a trust.bundle at all — unrelated to origin
+    // stamping. When a trust.bundle IS present, every claim must be stamped (requireStampedClaim);
+    // there is no claimType-derivation fallback for an unstamped claim (#268/#344).
     const bundle = loadJson(path.join(dir, "trust.bundle"));
     if (Array.isArray(bundle.claims)) {
-        const checkClaims = bundle.claims.filter((c) => {
-            if (!c)
-                return false;
-            const ct = String(c.claimType || "");
-            return ct.startsWith("workflow.check.") || declaredClaimTypes.has(ct);
-        });
+        for (const c of bundle.claims)
+            requireStampedClaim(c, dir);
+        const checkClaims = bundle.claims.filter((c) => c && claimOrigin(c) === "check");
         if (checkClaims.length === 0)
             return false;
         return checkClaims.every((c) => {
@@ -2354,7 +2736,7 @@ function evidenceClean(dir, declaredClaimTypes = new Set()) {
             return v === "pass" || v === "skip";
         });
     }
-    // Legacy fallback: evidence.json
+    // Legacy fallback: evidence.json (pre-bundle-era sessions with no trust.bundle at all)
     const e = loadJson(path.join(dir, "evidence.json"), {});
     return e.verdict === "pass" && Array.isArray(e.checks) && e.checks.length > 0 && e.checks.every((c) => {
         if (!(c.status === "pass" || c.status === "skip"))
@@ -2362,13 +2744,23 @@ function evidenceClean(dir, declaredClaimTypes = new Set()) {
         return !Array.isArray(c.standard_refs) || c.standard_refs.every((r) => ["junit", "sarif", "coverage", "veritas"].includes(r.standard));
     });
 }
-function critiqueClean(dir, declaredClaimTypes = new Set()) {
-    // Phase 4c: read from trust.bundle (sole verification artifact); fall back to critique.json for legacy sessions.
-    // ADR 0016 Step 0: declaredClaimTypes broadens the filter to include kit-typed critique claims
-    // (e.g. builder.verify.policy-compliance) in addition to workflow.critique.review.
+function critiqueClean(dir) {
+    // Phase 4c: read from trust.bundle (sole verification artifact); fall back to critique.json for
+    // legacy (pre-bundle-era) sessions — unrelated to origin stamping. When a trust.bundle IS
+    // present, every claim must be stamped (requireStampedClaim); no claimType-derivation fallback
+    // for an unstamped claim (#268/#344).
     const bundle = loadJson(path.join(dir, "trust.bundle"));
     if (Array.isArray(bundle.claims)) {
-        const critiqueClaims = bundle.claims.filter((c) => c && (c.claimType === "workflow.critique.review" || declaredClaimTypes.has(c.claimType)));
+        for (const c of bundle.claims)
+            requireStampedClaim(c, dir);
+        const critiqueClaims = bundle.claims.filter((c) => {
+            if (!c)
+                return false;
+            // #267/#282: superseded history is not evaluated for cleanliness.
+            if (c.metadata && typeof c.metadata === "object" && c.metadata.superseded_by)
+                return false;
+            return claimOrigin(c) === "critique";
+        });
         if (critiqueClaims.length === 0)
             return false; // no critique written yet
         return critiqueClaims.every((c) => {
@@ -2410,10 +2802,9 @@ async function dogfoodPass(p) {
         if (checks.some((c) => c.status !== "pass" && c.status !== "skip"))
             die("clean evidence requires all non-skipped checks to pass");
         // Phase 4c: evidence check reads from trust.bundle (sole verification artifact); legacy evidence.json fallback in evidenceClean.
-        // ADR 0016 Step 0: pass declaredClaimTypes so builder.* check/critique claims count as clean evidence.
-        const _dctDogfood = declaredClaimTypesFor(dir);
-        const _hasBundleEvidence = fs.existsSync(path.join(dir, "trust.bundle")) && evidenceClean(dir, _dctDogfood);
-        const _hasLegacyEvidence = fs.existsSync(path.join(dir, "evidence.json")) && evidenceClean(dir, _dctDogfood);
+        // #268/#344: builder.* check/critique claims count as clean evidence via their authoritative origin stamp.
+        const _hasBundleEvidence = fs.existsSync(path.join(dir, "trust.bundle")) && evidenceClean(dir);
+        const _hasLegacyEvidence = fs.existsSync(path.join(dir, "evidence.json")) && evidenceClean(dir);
         if (!_hasBundleEvidence && !_hasLegacyEvidence && fs.existsSync(path.join(dir, "trust.bundle")))
             die("cannot mark clean without passing evidence");
         if (!_hasBundleEvidence && !_hasLegacyEvidence && !fs.existsSync(path.join(dir, "trust.bundle")) && fs.existsSync(path.join(dir, "evidence.json")))
@@ -2426,10 +2817,10 @@ async function dogfoodPass(p) {
                 normalizeFinding(parseJson(value, "--finding-json"));
             if (newCritiqueVerdict !== "pass")
                 die(opt(p, "release-decision") ? "requires clean critique" : "requires clean critique before recording pass evidence");
-            if (!opt(p, "critique-id") && !critiqueClean(dir, _dctDogfood))
+            if (!opt(p, "critique-id") && !critiqueClean(dir))
                 die("requires passing critique");
             // Phase 4c: if existing state has a dirty critique (in bundle or legacy critique.json), block even when adding a new critique-id.
-            if (!critiqueClean(dir, _dctDogfood) && (fs.existsSync(path.join(dir, "trust.bundle")) || fs.existsSync(path.join(dir, "critique.json"))))
+            if (!critiqueClean(dir) && (fs.existsSync(path.join(dir, "trust.bundle")) || fs.existsSync(path.join(dir, "critique.json"))))
                 die(opt(p, "release-decision") ? "requires clean critique" : "requires clean critique before recording pass evidence");
         }
     }
@@ -2961,6 +3352,19 @@ function livenessLabel(status) {
         return "superseded";
     return status;
 }
+/**
+ * Delegate to the shared pure-CJS liveness reader's freshHolders() (scripts/hooks/lib/liveness-read.js),
+ * mirroring the exact loader shape assignment-provider.ts already uses for the same helper (#291
+ * Wave 2 Task 2.1) — so ensure-session's ownership guard computes freshness identically to
+ * `assignment-provider status`'s own join, a single implementation. `readLivenessEvents` above
+ * already loads this same module inline for its own narrower need (just the events reader); this
+ * loader additionally exposes `freshHolders` for the guard's `computeEffectiveState` call.
+ */
+function loadLivenessReadHelper() {
+    const _req = createRequire(import.meta.url);
+    const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/liveness-read.js");
+    return _req(helperPath);
+}
 // ─── 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.