@kontourai/flow-agents 3.0.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 = [];
@@ -721,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.
@@ -739,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);
@@ -1110,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) || ".",
@@ -1134,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");
@@ -1142,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 ?? "");
@@ -1157,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) : [];
@@ -1214,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`)) : "";
@@ -1262,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");
@@ -1279,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())
@@ -1290,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) {
@@ -1732,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;
@@ -1781,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;
 }
 /**
@@ -1917,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);
@@ -3008,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.

package/build/src/lib/flow-resolver.d.ts

@@ -72,16 +72,22 @@ export declare function resolvePhaseMap(flowId: string, repoRoot: string): Recor
 /**
  * Resolve the active flow step from current.json.
  *
- * Reads active_flow_id and active_step_id from <flowAgentsDir>/current.json.
- * If both are present, delegates to resolveFlowStep. The repoRoot is derived by
- * walking upward from flowAgentsDir to find the nearest ancestor containing kits/,
- * with a fallback to process.cwd(). This handles temp dirs, CI workspaces, and
- * subproject layouts without hardcoding the repo structure.
+ * Reads active_flow_id and active_step_id via the shared per-actor current-pointer helper
+ * (#291 Wave 2 Task 2.2): when `actorKey` is a resolved actor with its own
+ * `current/<actor>.json` projection, that file is preferred; otherwise (no actorKey, an
+ * unresolved actor, or no per-actor file yet) this falls straight back to the legacy global
+ * `<flowAgentsDir>/current.json` — IDENTICAL to this function's pre-#291 behavior for every
+ * caller that does not pass `actorKey`. The repoRoot is derived by walking upward from
+ * flowAgentsDir to find the nearest ancestor containing kits/, with a fallback to
+ * process.cwd(). This handles temp dirs, CI workspaces, and subproject layouts without
+ * hardcoding the repo structure.
  *
  * @param flowAgentsDir Path to the runtime artifact root directory (contains current.json).
+ * @param actorKey Optional resolved actor identity (Wave 2 Task 2.1's `writeCurrent()` dual-write
+ *   key) — when omitted, behavior is unchanged (legacy-file-only, exactly as before #291).
  * @returns ActiveFlowStep or null when fields are absent or resolution fails.
  */
-export declare function resolveActiveFlowStep(flowAgentsDir: string): ActiveFlowStep | null;
+export declare function resolveActiveFlowStep(flowAgentsDir: string, actorKey?: string): ActiveFlowStep | null;
 /** The resolved route-back policy for a phase transition. */
 export type RouteBackPolicy = {
     /** Maximum allowed route-back attempts for this transition key. */