@kontourai/flow-agents 3.0.0 → 3.1.0

package/.github/workflows/ci.yml

@@ -161,6 +161,14 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check pull-work-assignment-join-integration
 
+      - name: Ensure-session ownership guard integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check ensure-session-ownership-guard-integration
+
+      - name: Current.json per-actor integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check current-json-per-actor-integration
+
       - name: Finalize CI evidence
         if: always()
         run: bash evals/ci/run-baseline.sh --finalize

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [3.1.0](https://github.com/kontourai/flow-agents/compare/v3.0.0...v3.1.0) (2026-07-04)
+
+
+### Features
+
+* **docs:** probe docs-write contract — vocabulary + decision deltas ([#311](https://github.com/kontourai/flow-agents/issues/311)) ([#371](https://github.com/kontourai/flow-agents/issues/371)) ([867c3b5](https://github.com/kontourai/flow-agents/commit/867c3b5b645c896e5df6886177171b05e73e8fa9))
+* **knowledge:** neo4j knowledge-store provider — Cypher-backed [#317](https://github.com/kontourai/flow-agents/issues/317) interface (opt-in default) ([#373](https://github.com/kontourai/flow-agents/issues/373)) ([2ef2523](https://github.com/kontourai/flow-agents/commit/2ef2523cc65a5e56dec8dcbf84edc3718cfe190c))
+* **knowledge:** promote sub-flow — ingest→distill→link→health (flow within a flow) ([#313](https://github.com/kontourai/flow-agents/issues/313)) ([#372](https://github.com/kontourai/flow-agents/issues/372)) ([b345d89](https://github.com/kontourai/flow-agents/commit/b345d89873c99f65f00d0fe8ede6a8702b1a2b43))
+* **knowledge:** stable record identity — short-id prefix + slug aliases ([#339](https://github.com/kontourai/flow-agents/issues/339)) ([ff54bc7](https://github.com/kontourai/flow-agents/commit/ff54bc74f893321f13276cd147d500f91e1fc133))
+
+
+### Documentation
+
+* **adr:** ADR freeze cutover + liveness coordination experiment ([#332](https://github.com/kontourai/flow-agents/issues/332)) ([#368](https://github.com/kontourai/flow-agents/issues/368)) ([2c845b8](https://github.com/kontourai/flow-agents/commit/2c845b81675db02622fee8fa1efa6aa197ce96c0))
+
 ## [3.0.0](https://github.com/kontourai/flow-agents/compare/v2.4.0...v3.0.0) (2026-07-04)
 
 

package/CONTEXT.md

@@ -66,6 +66,16 @@ _Avoid_: Graph database as the generic term (the model is provider-independent;
 A configured implementation of the knowledge-store capability behind the Knowledge Graph model. Providers expose a read interface (nodes, edges, query-by-type) and a proposals-only write interface (proposeWrite returns a proposal, never mutating a human-curated store). The reference providers are markdown-vault (the Obsidian-shaped vault), git-repo (decision registry, CONTEXT.md vocabulary, learnings), and work-item (GitHub issues as a source/sink adapter). See context/contracts/knowledge-store-contract.md.
 _Avoid_: Knowledge adapter when contrasting the provider interface with a single store adapter
 
+### Graph Knowledge Provider
+
+The owner's opt-in Neo4j-backed Knowledge Store Provider (the `neo4j` provider). A queryable materialized view of the Knowledge Graph, synced from the file/work-item providers with idempotent MERGE semantics — the file stores stay the source of truth and the write side stays proposals-only. Selected via `KNOWLEDGE_PROVIDER=neo4j`; degrades to the file providers when no Neo4j is reachable. The file providers remain the portfolio default; the graph is a personal default only. See docs/decisions/graph-knowledge-provider.md.
+_Avoid_: Graph database as the default store (it is opt-in and a view, not the source of truth)
+
+### Knowledge Promote Sub-Flow
+
+The Knowledge Kit's codebase-facing pipeline (the "flow within a flow") that a delivered session's promotion runs through: ingest the session artifacts, distill schema-valid draft decision/vocabulary/learning deltas, link their provenance (PR, merge SHA, session archive, touched topics), and health-check the registry for contradictions with a merge-repair proposal. It is proposals-only — every output is a draft under the session's proposals directory that the promote step applies; the sub-flow never writes docs directly. Invokable standalone and composable from the Builder promote step. See docs/decisions/knowledge-promote-sub-flow.md.
+_Avoid_: Promotion gate as a synonym (the gate is the recorded promote claim; this is the assisted pipeline)
+
 ### Kontour Resource Contract
 
 A versioned Kontour record shape for durable machine-readable configuration, scope, run state, evidence, provider output, and cross-product interchange. Kontour Resource Contracts are the default for new pre-public durable contracts unless a product records why a native shape is clearer.
@@ -225,7 +235,7 @@ A reason code for a Gate that cannot be evaluated or cannot pass because a requi
 
 ### Probe
 
-A Builder Kit Alignment Gate that explores context, challenges assumptions, and records aligned decisions before the process continues. A Probe asks one question at a time, recommends an answer, and uses repository context before asking when the answer can be discovered.
+A Builder Kit Alignment Gate that explores context, challenges assumptions, and records aligned decisions before the process continues. A Probe asks one question at a time, recommends an answer, and uses repository context before asking when the answer can be discovered. As understanding crystallizes, a Probe writes it into durable docs in the same motion: a vocabulary delta into this glossary and a decision delta into the Decision Registry, per [context/contracts/probe-docs-write-contract.md](context/contracts/probe-docs-write-contract.md).
 _Avoid_: Grill, interrogation
 
 ### Flow
@@ -328,6 +338,62 @@ The Console overview for global setup, registered projects, cross-project usage,
 
 The shared tool layer used by the Console, CLI, AI agents, and automation. The Control API owns operations such as reading effective settings, explaining provider resolution, testing provider health, previewing config changes, writing config, inspecting workflow state, and reporting usage or eval outcomes.
 
+### Workflow trust state
+
+The trust bundle a workflow gate reads to decide whether to advance — claims, evidence, verification events, and derived status expressed as a Hachure Trust Bundle — so gates consume inspectable trust state rather than raw tool output. Provenance lives in frozen ADRs; the subject is open in the Decision Registry as [docs/decisions/workflow-trust-state.md](docs/decisions/workflow-trust-state.md).
+
+### TypeScript-first source policy
+
+The policy that Kontour product and runtime source defaults to TypeScript, with narrow JavaScript/MJS exceptions (config/tooling, generated assets, thin launchers, fixtures, historical artifacts) and staged per-repo migration for existing non-TypeScript source. Ratified in the Decision Registry as [docs/decisions/typescript-source-policy.md](docs/decisions/typescript-source-policy.md).
+
+### Flow / Skill / Kit / Tool boundary
+
+The layering that separates a Flow (workflow semantics) from a Skill (agent-facing procedure), a Flow Kit (installable bundle), and a Tool (an executable operation), so each concern has one home and does not leak into the others. Subject open in the Decision Registry as [docs/decisions/flow-skill-kit-tool-boundary.md](docs/decisions/flow-skill-kit-tool-boundary.md).
+
+### Kit operation boundary
+
+The rule for what a kit-owned operation may do versus what belongs to the core, keeping kit operations scoped to their capability and free of core enforcement responsibilities. Subject open in the Decision Registry as [docs/decisions/kit-operation-boundary.md](docs/decisions/kit-operation-boundary.md).
+
+### Hook core/kit boundary
+
+The division between canonical hook behavior owned by the core and hook contributions owned by kits, so enforcement hooks have a single authoritative implementation. Subject open in the Decision Registry as [docs/decisions/hook-core-kit-boundary.md](docs/decisions/hook-core-kit-boundary.md).
+
+### MCP posture
+
+Flow Agents' stance on the Model Context Protocol: enforcement stays in hooks, Surface owns any MCP projection, and no MCP configuration is auto-injected into a runtime. Subject open in the Decision Registry as [docs/decisions/mcp-posture.md](docs/decisions/mcp-posture.md).
+
+### Agent coordination
+
+How concurrent agents avoid stepping on each other's work, modeled as Hachure liveness claims plus assignment leases with stale-claim takeover, so a work item's holder is advisory-visible and reclaimable when stale. Subject open in the Decision Registry as [docs/decisions/agent-coordination.md](docs/decisions/agent-coordination.md).
+
+### Context lifecycle
+
+The lifecycle of an agent's working context — workflow-boundary compaction, freshness-gated reuse, and the split between durable learnings and ephemeral context — so context is refreshed rather than silently stale. Subject open in the Decision Registry as [docs/decisions/context-lifecycle.md](docs/decisions/context-lifecycle.md).
+
+### Core vs domain kit boundary
+
+The generic/kit boundary that keeps the Flow Agents core domain-agnostic while domain behavior lives in kits, so the core carries no kit-specific knowledge. Subject open in the Decision Registry as [docs/decisions/core-domain-kit-boundary.md](docs/decisions/core-domain-kit-boundary.md).
+
+### Flow / Flow Agents boundary
+
+The reconciled division of responsibility between Flow (the workflow engine consumed for enforcement) and Flow Agents (the product that consumes it), so each owns a distinct layer without duplicating the other. Subject open in the Decision Registry as [docs/decisions/flow-flow-agents-boundary.md](docs/decisions/flow-flow-agents-boundary.md).
+
+### Three-hard-boundary model
+
+The FlowDefinition-driven, kit-agnostic model that names the three hard boundaries the core enforces, unifying the individual boundary decisions into one architecture. Subject open in the Decision Registry as [docs/decisions/three-hard-boundary-model.md](docs/decisions/three-hard-boundary-model.md).
+
+### Anti-gaming trust security
+
+The layered-defense trust security model that assumes the local agent can be gamed and anchors enforcement in an external CI check, freezing the local shell-parsing heuristics and routing new enforcement to the CI anchor. Subject open in the Decision Registry as [docs/decisions/anti-gaming-trust-security.md](docs/decisions/anti-gaming-trust-security.md).
+
+### Kit dependency ownership
+
+The rule for which layer owns a kit's runtime dependencies, keeping dependency declaration and installation with the kit that needs them rather than the core. Subject open in the Decision Registry as [docs/decisions/kit-dependency-ownership.md](docs/decisions/kit-dependency-ownership.md).
+
+### Trust-reconcile and delivery reconciliation
+
+The CI-anchored reconciliation of a session's trust claims against a manifest — classifying command, session-local, and attested claims, honoring governed waivers — and the fail-closed delivery reconciliation that blocks publication on unreconciled residue unless an exemption is recorded. Subject open in the Decision Registry as [docs/decisions/trust-reconcile.md](docs/decisions/trust-reconcile.md).
+
 ### Model Routing
 
 The policy that maps a delegate role name (such as `delegate-mechanical`, `delegate-implementation`, `delegate-design`, `orchestrator`, `extraction-default`) to a specific `model@provider` ref. Model Routing is data, not code: it lives in `.datum/config.json` (read by the `@kontourai/datum` registry, schema `datum.schema.json`) and never in generated files or per-agent frontmatter. The orchestrator resolves the role at delegation time (`datum resolve <role> --json`) and passes the resolved model explicitly when spawning each delegate. See [context/contracts/execution-contract.md](context/contracts/execution-contract.md) § Delegation: Model Routing and [docs/decisions/model-routing.md](docs/decisions/model-routing.md).

package/README.md

@@ -217,6 +217,10 @@ See [Repository Structure](docs/repository-structure.md) for the canonical map.
 - `kits/`, `schemas/`, `packaging/`, `evals/`, `docs/`, and `integrations/` hold Flow Kit assets, contracts, package metadata, evals, durable docs, and optional integrations.
 - `dist/`, `build/`, and `_site/` are generated output. Local `.kontourai/`, `.flow-agents/`, `.codex/`, `.claude/`, telemetry, promptfoo, Veritas, and cache directories stay ignored; durable outcomes belong in docs, source, schemas, or provider records.
 
+## Graph provider (opt-in)
+
+The Knowledge Kit ships an optional `neo4j` graph provider — the owner's opt-in personal default, while the file providers remain the portfolio default. It is a queryable **materialized view** synced from the file/work-item stores (which stay the source of truth), with Cypher-backed health/query verbs when selected and graceful degradation to the file providers when no Neo4j is reachable (never a hard dependency). Opt in with `KNOWLEDGE_PROVIDER=neo4j` and see [Graph provider (opt-in)](kits/knowledge/docs/README.md#graph-provider-opt-in) for the `docker run` one-liner, env vars, sync command, and an example Cypher session.
+
 ## Documentation
 
 The [GitHub Pages site](https://kontourai.github.io/flow-agents/) is the product overview and quickstart. The repository docs are the developer reference for contracts, workflow behavior, evals, and integration boundaries. For the gate semantics underneath — definitions, runs, evidence, route-back — read the [Kontour Flow documentation](https://kontourai.github.io/flow/).

package/build/src/cli/assignment-provider.d.ts

@@ -1 +1,144 @@
+export type ActorStruct = {
+    runtime: string;
+    session_id: string;
+    host: string;
+    human?: string | null;
+};
+type AssignmentClaimRecordStatus = "claimed" | "released" | "superseded";
+type AssignmentAuditEntry = {
+    at: string;
+    transition: "claim" | "release" | "supersede";
+    from_actor?: ActorStruct | null;
+    to_actor?: ActorStruct | null;
+    reason?: string;
+};
+/**
+ * The versioned claim-record shape from the contract doc's "Versioned claim-record format"
+ * section (Design Decision 2). `schema_version` is bumped only on an incompatible change, per
+ * artifact-contract.md's existing sidecar rule.
+ *
+ * `actor_key` (F1 fix, fix-plan iteration 1, HIGH — additive field, schema_version unchanged):
+ * the canonical `resolveActor(env).actor` string for the claiming actor — the SAME flat/bare
+ * token every other tool (`liveness whoami`, `liveness claim --actor`, per-actor current.json,
+ * pull-work's `--self-actor`) already uses. Optional so every pre-fix record and every #290 eval
+ * fixture with no `actor_key` still parses; `computeEffectiveState` falls back to
+ * `serializeActor(record.actor)` (today's behavior) whenever it's absent. Present, it is the ONLY
+ * correct self-recognition/liveness-join key — see computeEffectiveState's holderActorKey.
+ */
+export type AssignmentClaimRecord = {
+    schema_version: "1.0";
+    role: "AssignmentClaimRecord";
+    subject_id: string;
+    actor: ActorStruct;
+    actor_key?: string;
+    claimed_at: string;
+    ttl_seconds: number;
+    branch: string;
+    artifact_dir: string;
+    status: AssignmentClaimRecordStatus;
+    audit_trail?: AssignmentAuditEntry[];
+};
+export type FreshHolder = {
+    actor: string;
+    lastAt: string;
+    ttlSeconds: number;
+    fresh: boolean;
+};
+export type EffectiveState = "held" | "reclaimable" | "human-held" | "free";
+/** Provider-neutral assignment-layer read, before any liveness join (contract doc's status()). */
+export type AssignmentStatus = {
+    subject_id: string;
+    provider: "local-file" | "github";
+    assignee: string | null;
+    record: AssignmentClaimRecord | null;
+    has_claim_label?: boolean;
+};
+export declare function assignmentFilePath(artifactRoot: string, subjectId: string): string;
+export declare function readLocalRecord(artifactRoot: string, subjectId: string): AssignmentClaimRecord | null;
+export declare function writeLocalRecord(artifactRoot: string, subjectId: string, record: AssignmentClaimRecord): void;
+/**
+ * F1 fix (fix-plan iteration 1, CRITICAL): claimLocalFile/releaseLocalFile/supersedeLocalFile were
+ * a plain read -> compare-actor -> write with no lock, so two concurrently-launched OS processes
+ * could both read "no conflicting claim" before either wrote, and the second write would silently
+ * clobber the first with zero error and zero audit-trail entry for the loser (reproduced 29/40
+ * races against the built CLI). This mirrors the EXACT mechanism `withLock` already uses in
+ * workflow-sidecar.ts:908 for the same class of shared-state mutation — atomic `fs.mkdirSync`
+ * lockdir create as the mutual-exclusion primitive, EEXIST-spin with a staleness-reclaim check
+ * (a lock directory older than the stale threshold is presumed abandoned by a crashed process and
+ * is reclaimed rather than waited on forever) and a bounded deadline, `finally` rmSync release —
+ * as a small LOCAL helper (not a cross-import of that private function, which would pull the
+ * entire workflow-sidecar module in for one primitive). Deliberately synchronous (sleepSync's
+ * Atomics.wait spin, not setTimeout/await) so claim/release/supersede can stay sync `number`
+ * -returning functions and the CLI dispatcher (src/cli.ts, `number | Promise<number>`) does not
+ * need any ripple to async. On lock-acquire failure (any error other than a live contested lock,
+ * or a timeout waiting one out) this THROWS — never a silent no-op — "fail loud, never fail-open"
+ * (artifact-contract.md). Wrap the ENTIRE read-modify-write body (the existing-claim check AND
+ * the write) of all three local-file mutators in this, since all three mutate the same record
+ * file for a given subject.
+ */
+export declare function withSubjectLock<T>(artifactRoot: string, subjectId: string, body: () => T): T;
+/**
+ * The assignment ⋈ liveness join (contract doc's "assignment ⋈ liveness join" section, ADR 0021
+ * §1). Pure function: `{ assignment, freshHoldersList, selfActor, nowMs }` -> one of five
+ * effective states (held/reclaimable/human-held/free — "held" covers both the plain and
+ * assignment-lagging rows, matching the contract table's own repeated "held" label).
+ *
+ * The human-assignee gate (AC11, Design Decision 3) reads `record.actor.human` being *present*,
+ * never a username heuristic — an idle human assignment is always `human-held`, regardless of
+ * idle duration, and is never auto-reclaimable by this function.
+ *
+ * `nowMs` (F3 fix, fix-plan iteration 1) is the SAME resolved "now" the caller already threads
+ * into `freshHolders()` (the `--now` override, when passed, else `Date.now()`) — passing it
+ * through here too means `--now` deterministically governs idle_days as well as liveness
+ * freshness, rather than idle_days silently reading the real wall clock regardless of `--now`.
+ */
+export declare function computeEffectiveState(assignment: AssignmentStatus, freshHoldersList: FreshHolder[], selfActor: string | undefined, nowMs: number): {
+    effective_state: EffectiveState;
+    reason: string;
+    holder?: {
+        actor?: string;
+        assignee?: string | null;
+        idle_days?: number | null;
+        last_at?: string;
+    };
+};
+/**
+ * Wave 1 (#291) extraction: the durable-write body previously inlined inside claimLocalFile's
+ * withSubjectLock() closure, now a parameter-driven pure function so ensure-session's ownership
+ * guard (workflow-sidecar.ts, Wave 2) can reuse the EXACT same claim logic — same-actor idempotent
+ * refresh, different-actor throw, atomic write under withSubjectLock — rather than reimplementing
+ * a second, parallel claim path. claimLocalFile (CLI wrapper, below) is now a thin
+ * parse-args/print-envelope shell around this.
+ */
+export declare function performLocalClaim(artifactRoot: string, subjectId: string, actor: ActorStruct, opts: {
+    ttlSeconds: number;
+    branch: string;
+    artifactDir: string;
+    reason?: string;
+    actorKey?: string;
+}): AssignmentClaimRecord;
+/**
+ * Wave 1 (#291) extraction: the durable-write body previously inlined inside supersedeLocalFile's
+ * withSubjectLock() closure, now a parameter-driven pure function so ensure-session's
+ * `--supersede-stale` takeover path (workflow-sidecar.ts, Wave 2) can reuse the EXACT same
+ * supersede logic — from-actor holder verification, ttl/branch/artifact_dir carry-forward,
+ * audit-trail append, atomic write under withSubjectLock — rather than reimplementing a second,
+ * parallel supersede path. supersedeLocalFile (CLI wrapper, below) is now a thin
+ * parse-args/print-envelope shell around this.
+ */
+export declare function performLocalSupersede(artifactRoot: string, subjectId: string, fromActor: ActorStruct, toActor: ActorStruct, opts?: {
+    ttlSeconds?: number;
+    branch?: string;
+    artifactDir?: string;
+    reason?: string;
+    actorKey?: string;
+}): AssignmentClaimRecord;
+/**
+ * Wave 1 (#291) extraction: the local-file branch of statusCommand's assignment-layer read,
+ * mirrored exactly so ensure-session's ownership guard (workflow-sidecar.ts, Wave 2) derives an
+ * AssignmentStatus identically to the `assignment-provider status` CLI command — a single
+ * implementation, not a second parallel local-file read.
+ */
+export declare function readLocalAssignmentStatus(artifactRoot: string, subjectId: string): AssignmentStatus;
 export declare function main(argv?: string[]): number;
+export {};

package/build/src/cli/assignment-provider.js

@@ -64,22 +64,29 @@ function loadActorStructFromFile(file) {
  * fixture-friendly path (used by evals and any caller that already knows its own struct);
  * when omitted, auto-derive from the live environment via the shared resolver, mirroring
  * (never forking) the exact struct fields serializeActor() already defines.
+ *
+ * F1 fix (fix-plan iteration 1, HIGH): also returns `actorKey` — set to the canonical
+ * `resolveActor(env).actor` string ONLY on the auto-derive path (pull-work's real path, and any
+ * other caller with no --actor-json), so a claim made via `assignment-provider claim` and one
+ * made via ensure-session share the same canonical key. `--actor-json` explicit fixtures leave
+ * `actorKey` unset — `performLocalClaim`/`performLocalSupersede` then fall back to
+ * `serializeActor(actor)` for the record's `actor_key`, preserving existing fixture behavior.
  */
 function loadActorStruct(args) {
     const actorJsonPath = flagString(args.flags, "actor-json");
     if (actorJsonPath)
-        return loadActorStructFromFile(actorJsonPath);
+        return { actor: loadActorStructFromFile(actorJsonPath) };
     const helper = loadActorIdentityHelper();
     const resolved = helper.resolveActor(process.env);
     if (helper.isUnresolvedActor(resolved.actor))
         throw new Error("could not resolve an actor identity (no --actor-json and no resolvable environment actor); pass --actor-json explicitly");
-    return { runtime: helper.detectRuntime(process.env), session_id: resolved.actor, host: os.hostname(), human: null };
+    return { actor: { runtime: helper.detectRuntime(process.env), session_id: resolved.actor, host: os.hostname(), human: null }, actorKey: resolved.actor };
 }
-function assignmentFilePath(artifactRoot, subjectId) {
+export function assignmentFilePath(artifactRoot, subjectId) {
     const sanitized = loadActorIdentityHelper().sanitizeSegment(subjectId);
     return path.join(artifactRoot, "assignment", `${sanitized}.json`);
 }
-function readLocalRecord(artifactRoot, subjectId) {
+export function readLocalRecord(artifactRoot, subjectId) {
     const file = assignmentFilePath(artifactRoot, subjectId);
     if (!fs.existsSync(file))
         return null;
@@ -99,7 +106,7 @@ function readLocalRecord(artifactRoot, subjectId) {
         throw new Error(`${file}: unsupported schema_version ${String(record.schema_version)}`);
     return record;
 }
-function writeLocalRecord(artifactRoot, subjectId, record) {
+export function writeLocalRecord(artifactRoot, subjectId, record) {
     // writeJson throws on any mkdir/writeFileSync failure; that error is intentionally allowed to
     // propagate to main()'s top-level try/catch and exit non-zero. Durable writes must fail loud,
     // never fail open (artifact-contract.md).
@@ -142,7 +149,7 @@ function subjectLockDir(artifactRoot, subjectId) {
  * the write) of all three local-file mutators in this, since all three mutate the same record
  * file for a given subject.
  */
-function withSubjectLock(artifactRoot, subjectId, body) {
+export function withSubjectLock(artifactRoot, subjectId, body) {
     const lockDir = subjectLockDir(artifactRoot, subjectId);
     const staleMs = Number(process.env.FLOW_AGENTS_ASSIGNMENT_STALE_LOCK_MS ?? 5 * 60 * 1000);
     const deadline = Date.now() + 30000;
@@ -196,7 +203,7 @@ function withSubjectLock(artifactRoot, subjectId, body) {
  * through here too means `--now` deterministically governs idle_days as well as liveness
  * freshness, rather than idle_days silently reading the real wall clock regardless of `--now`.
  */
-function computeEffectiveState(assignment, freshHoldersList, selfActor, nowMs) {
+export function computeEffectiveState(assignment, freshHoldersList, selfActor, nowMs) {
     const record = assignment.record && assignment.record.status === "claimed" ? assignment.record : null;
     const isAssigned = Boolean(assignment.assignee) || Boolean(record);
     if (!isAssigned) {
@@ -222,7 +229,14 @@ function computeEffectiveState(assignment, freshHoldersList, selfActor, nowMs) {
         // human's work (Design Decision 3 / ADR 0021 §6's "never auto-reclaim" non-goal).
         return { effective_state: "human-held", reason: "assignee_without_claim_record", holder: { assignee: assignment.assignee } };
     }
-    const holderActorKey = loadActorIdentityHelper().serializeActor(record.actor);
+    // F1 fix (fix-plan iteration 1, HIGH): prefer the canonical actor_key over re-serializing
+    // record.actor. record.actor_key IS resolveActor(env).actor for records written by the fixed
+    // performLocalClaim/performLocalSupersede paths (below) — the same flat/bare string liveness
+    // whoami, `liveness claim --actor`, per-actor current.json, and pull-work's --self-actor all
+    // use — so for an explicit-override actor the self-check and the liveness join now agree with
+    // every other tool. BACK-COMPAT: records with no actor_key (every pre-fix record, every #290
+    // eval fixture) fall back to serializeActor(record.actor) exactly as before this fix.
+    const holderActorKey = record.actor_key || loadActorIdentityHelper().serializeActor(record.actor);
     if (selfActor && holderActorKey === selfActor)
         return { effective_state: "held", reason: "self_is_holder", holder: { actor: holderActorKey } };
     const fresh = freshHoldersList.find((holder) => holder.actor === holderActorKey);
@@ -349,22 +363,17 @@ function loadLivenessInputs(args) {
 }
 // ─── local-file: claim | release | supersede (the durable-write path; real I/O by design — no
 // external mutation to defer to a skill for this provider kind, per Design Decision 1) ─────────
-function claimLocalFile(argv) {
-    const args = parseArgs(argv);
-    const provider = flagString(args.flags, "provider", "local-file");
-    if (provider !== "local-file")
-        throw new Error(`claim: --provider must be local-file (use render-claim for github); got ${provider}`);
-    const artifactRoot = requireFlag(args, "artifact-root");
-    const subjectId = requireFlag(args, "subject-id");
-    const actor = loadActorStruct(args);
+/**
+ * Wave 1 (#291) extraction: the durable-write body previously inlined inside claimLocalFile's
+ * withSubjectLock() closure, now a parameter-driven pure function so ensure-session's ownership
+ * guard (workflow-sidecar.ts, Wave 2) can reuse the EXACT same claim logic — same-actor idempotent
+ * refresh, different-actor throw, atomic write under withSubjectLock — rather than reimplementing
+ * a second, parallel claim path. claimLocalFile (CLI wrapper, below) is now a thin
+ * parse-args/print-envelope shell around this.
+ */
+export function performLocalClaim(artifactRoot, subjectId, actor, opts) {
     const helper = loadActorIdentityHelper();
-    const ttlSecondsRaw = flagString(args.flags, "ttl-seconds", "1800") ?? "1800";
-    const ttlSeconds = Number(ttlSecondsRaw);
-    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0)
-        throw new Error(`--ttl-seconds must be a positive number; got ${ttlSecondsRaw}`);
-    const branch = requireFlag(args, "branch");
-    const artifactDir = requireFlag(args, "artifact-dir");
-    const reason = flagString(args.flags, "reason") ?? "claim";
+    const reason = opts.reason ?? "claim";
     // F1 fix (fix-plan iteration 1, CRITICAL): the existing-claim check AND the write must happen
     // atomically with respect to any other `assignment-provider` invocation on the same subject —
     // see withSubjectLock()'s doc comment for the full rationale.
@@ -384,18 +393,37 @@ function claimLocalFile(argv) {
             role: "AssignmentClaimRecord",
             subject_id: subjectId,
             actor,
+            ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
             claimed_at: isoNow(),
-            ttl_seconds: ttlSeconds,
-            branch,
-            artifact_dir: artifactDir,
+            ttl_seconds: opts.ttlSeconds,
+            branch: opts.branch,
+            artifact_dir: opts.artifactDir,
             status: "claimed",
             audit_trail: [...(existing?.audit_trail ?? []), { at: isoNow(), transition: "claim", from_actor: null, to_actor: actor, reason }],
         };
         writeLocalRecord(artifactRoot, subjectId, record);
-        console.log(JSON.stringify({ role: "AssignmentClaimResult", subject_id: subjectId, record }, null, 2));
-        return 0;
+        return record;
     });
 }
+function claimLocalFile(argv) {
+    const args = parseArgs(argv);
+    const provider = flagString(args.flags, "provider", "local-file");
+    if (provider !== "local-file")
+        throw new Error(`claim: --provider must be local-file (use render-claim for github); got ${provider}`);
+    const artifactRoot = requireFlag(args, "artifact-root");
+    const subjectId = requireFlag(args, "subject-id");
+    const { actor, actorKey } = loadActorStruct(args);
+    const ttlSecondsRaw = flagString(args.flags, "ttl-seconds", "1800") ?? "1800";
+    const ttlSeconds = Number(ttlSecondsRaw);
+    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0)
+        throw new Error(`--ttl-seconds must be a positive number; got ${ttlSecondsRaw}`);
+    const branch = requireFlag(args, "branch");
+    const artifactDir = requireFlag(args, "artifact-dir");
+    const reason = flagString(args.flags, "reason") ?? "claim";
+    const record = performLocalClaim(artifactRoot, subjectId, actor, { ttlSeconds, branch, artifactDir, reason, actorKey });
+    console.log(JSON.stringify({ role: "AssignmentClaimResult", subject_id: subjectId, record }, null, 2));
+    return 0;
+}
 function releaseLocalFile(argv) {
     const args = parseArgs(argv);
     const provider = flagString(args.flags, "provider", "local-file");
@@ -421,20 +449,18 @@ function releaseLocalFile(argv) {
         return 0;
     });
 }
-function supersedeLocalFile(argv) {
-    const args = parseArgs(argv);
-    const provider = flagString(args.flags, "provider", "local-file");
-    if (provider !== "local-file")
-        throw new Error(`supersede: --provider must be local-file (use render-supersede for github); got ${provider}`);
-    const artifactRoot = requireFlag(args, "artifact-root");
-    const subjectId = requireFlag(args, "subject-id");
+/**
+ * Wave 1 (#291) extraction: the durable-write body previously inlined inside supersedeLocalFile's
+ * withSubjectLock() closure, now a parameter-driven pure function so ensure-session's
+ * `--supersede-stale` takeover path (workflow-sidecar.ts, Wave 2) can reuse the EXACT same
+ * supersede logic — from-actor holder verification, ttl/branch/artifact_dir carry-forward,
+ * audit-trail append, atomic write under withSubjectLock — rather than reimplementing a second,
+ * parallel supersede path. supersedeLocalFile (CLI wrapper, below) is now a thin
+ * parse-args/print-envelope shell around this.
+ */
+export function performLocalSupersede(artifactRoot, subjectId, fromActor, toActor, opts = {}) {
     const helper = loadActorIdentityHelper();
-    const fromActor = loadActorStructFromFile(requireFlag(args, "from-actor-json"));
-    const toActor = loadActorStructFromFile(requireFlag(args, "to-actor-json"));
-    const reason = flagString(args.flags, "reason") ?? "supersede";
-    const ttlSecondsOverride = flagString(args.flags, "ttl-seconds");
-    const branchOverride = flagString(args.flags, "branch");
-    const artifactDirOverride = flagString(args.flags, "artifact-dir");
+    const reason = opts.reason ?? "supersede";
     // F1 fix (fix-plan iteration 1, CRITICAL): supersede mutates the same record file claim/release
     // do, under the same per-subject lock (see withSubjectLock()'s doc comment).
     return withSubjectLock(artifactRoot, subjectId, () => {
@@ -444,7 +470,7 @@ function supersedeLocalFile(argv) {
         if (helper.serializeActor(existing.actor) !== helper.serializeActor(fromActor)) {
             throw new Error(`--from-actor-json does not match the current holder (${helper.serializeActor(existing.actor)}); refusing to supersede a claim held by someone else`);
         }
-        const ttlSecondsRaw = ttlSecondsOverride ?? String(existing.ttl_seconds);
+        const ttlSecondsRaw = opts.ttlSeconds != null ? String(opts.ttlSeconds) : String(existing.ttl_seconds);
         const ttlSeconds = Number(ttlSecondsRaw);
         if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0)
             throw new Error(`--ttl-seconds must be a positive number; got ${ttlSecondsRaw}`);
@@ -453,18 +479,40 @@ function supersedeLocalFile(argv) {
             role: "AssignmentClaimRecord",
             subject_id: subjectId,
             actor: toActor,
+            ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
             claimed_at: isoNow(),
             ttl_seconds: ttlSeconds,
-            branch: branchOverride ?? existing.branch,
-            artifact_dir: artifactDirOverride ?? existing.artifact_dir,
+            branch: opts.branch ?? existing.branch,
+            artifact_dir: opts.artifactDir ?? existing.artifact_dir,
             status: "claimed",
             audit_trail: [...(existing.audit_trail ?? []), { at: isoNow(), transition: "supersede", from_actor: fromActor, to_actor: toActor, reason }],
         };
         writeLocalRecord(artifactRoot, subjectId, record);
-        console.log(JSON.stringify({ role: "AssignmentSupersedeResult", subject_id: subjectId, record }, null, 2));
-        return 0;
+        return record;
     });
 }
+function supersedeLocalFile(argv) {
+    const args = parseArgs(argv);
+    const provider = flagString(args.flags, "provider", "local-file");
+    if (provider !== "local-file")
+        throw new Error(`supersede: --provider must be local-file (use render-supersede for github); got ${provider}`);
+    const artifactRoot = requireFlag(args, "artifact-root");
+    const subjectId = requireFlag(args, "subject-id");
+    const fromActor = loadActorStructFromFile(requireFlag(args, "from-actor-json"));
+    const toActor = loadActorStructFromFile(requireFlag(args, "to-actor-json"));
+    const reason = flagString(args.flags, "reason") ?? "supersede";
+    const ttlSecondsOverride = flagString(args.flags, "ttl-seconds");
+    const branchOverride = flagString(args.flags, "branch");
+    const artifactDirOverride = flagString(args.flags, "artifact-dir");
+    const record = performLocalSupersede(artifactRoot, subjectId, fromActor, toActor, {
+        ttlSeconds: ttlSecondsOverride != null ? Number(ttlSecondsOverride) : undefined,
+        branch: branchOverride ?? undefined,
+        artifactDir: artifactDirOverride ?? undefined,
+        reason,
+    });
+    console.log(JSON.stringify({ role: "AssignmentSupersedeResult", subject_id: subjectId, record }, null, 2));
+    return 0;
+}
 // ─── GitHub: render-claim | render-release | render-supersede (render, don't execute — Design
 // Decision 1). Pure functions: no I/O beyond reading --input-json/--actor-json. Never invoke
 // `gh` (or any process) here — the calling skill runs the emitted argv verbatim. ────────────────
@@ -624,6 +672,17 @@ function renderSupersede(argv) {
     return 0;
 }
 // ─── status | list (both provider kinds) ────────────────────────────────────────────────────
+/**
+ * Wave 1 (#291) extraction: the local-file branch of statusCommand's assignment-layer read,
+ * mirrored exactly so ensure-session's ownership guard (workflow-sidecar.ts, Wave 2) derives an
+ * AssignmentStatus identically to the `assignment-provider status` CLI command — a single
+ * implementation, not a second parallel local-file read.
+ */
+export function readLocalAssignmentStatus(artifactRoot, subjectId) {
+    const record = readLocalRecord(artifactRoot, subjectId);
+    const active = record && record.status === "claimed" ? record : null;
+    return { subject_id: subjectId, provider: "local-file", assignee: active ? loadActorIdentityHelper().serializeActor(active.actor) : null, record: active };
+}
 function statusCommand(argv) {
     const args = parseArgs(argv);
     const provider = requireFlag(args, "provider");
@@ -633,9 +692,7 @@ function statusCommand(argv) {
         const artifactRoot = requireFlag(args, "artifact-root");
         if (!requestedSubjectId)
             throw new Error("--subject-id is required for status --provider local-file");
-        const record = readLocalRecord(artifactRoot, requestedSubjectId);
-        const active = record && record.status === "claimed" ? record : null;
-        assignment = { subject_id: requestedSubjectId, provider: "local-file", assignee: active ? loadActorIdentityHelper().serializeActor(active.actor) : null, record: active };
+        assignment = readLocalAssignmentStatus(artifactRoot, requestedSubjectId);
     }
     else if (provider === "github") {
         const issueJsonPath = requireFlag(args, "issue-json");

package/build/src/cli/workflow-sidecar.d.ts

@@ -145,7 +145,7 @@ type SurfaceModule = {
  * @param critiques  Critique objects (from critique.json .critiques array)
  * @param commandLog Optional parsed command-log.jsonl entries (capture-authoritative fold)
  */
-export declare function buildTrustBundle(slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], commandLog?: AnyObj[], flowAgentsDir?: string): Promise<AnyObj | null>;
+export declare function buildTrustBundle(slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], commandLog?: AnyObj[], flowAgentsDir?: string, actorKey?: string): Promise<AnyObj | null>;
 /**
  * Fail-open wrapper: builds (via Surface), validates, and writes a trust.bundle.
  * Accepts raw check/criterion/critique inputs directly (ADR 0010 Phase 4a).
@@ -159,7 +159,7 @@ export declare function buildTrustBundle(slug: string, timestamp: string, checks
  * @param criteria   Acceptance criteria objects (same as buildTrustBundle)
  * @param critiques  Critique objects (same as buildTrustBundle)
  */
-export declare function writeTrustBundle(dir: string, slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[]): Promise<{
+export declare function writeTrustBundle(dir: string, slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], actorKey?: string): Promise<{
     written: boolean;
     errors: string[];
 }>;