@kontourai/flow-agents 3.5.0 → 3.7.0

package/build/src/builder-lifecycle-authority.d.ts

@@ -0,0 +1,35 @@
+import type { FlowLifecycleRequest } from "@kontourai/flow";
+import type { ActorStruct } from "./cli/assignment-provider.js";
+type JsonRecord = Record<string, unknown>;
+export type AuthorizedBuilderLifecycleOperation = "cancel" | "archive";
+export interface BuilderLifecycleAuthorization {
+    schema_version: "1.0";
+    operation: AuthorizedBuilderLifecycleOperation;
+    run_id: string;
+    subject: string;
+    assignment_actor_key: string;
+    assignment_actor: ActorStruct;
+    nonce: string;
+    expires_at: string;
+    request: FlowLifecycleRequest;
+    signature: {
+        algorithm: "ed25519";
+        key_id: string;
+        value: string;
+    };
+}
+export declare function lifecycleAuthorityKeysPath(projectRoot: string): string;
+export declare function loadBuilderLifecycleAuthorization(fileInput: string, expected: {
+    projectRoot: string;
+    operation: AuthorizedBuilderLifecycleOperation;
+    runId: string;
+    subject: string;
+    actorKey: string;
+    now?: string;
+    allowExpired?: boolean;
+}): BuilderLifecycleAuthorization;
+export declare function builderLifecycleAuthorizationPayload(value: Omit<BuilderLifecycleAuthorization, "signature">): string;
+export declare function assertAuthorizationUnused(artifactRoot: string, authorization: BuilderLifecycleAuthorization): void;
+export declare function readAuthorizationConsumption(artifactRoot: string, authorization: BuilderLifecycleAuthorization): JsonRecord | null;
+export declare function recordAuthorizationConsumed(artifactRoot: string, authorization: BuilderLifecycleAuthorization, at?: string): void;
+export {};

package/build/src/builder-lifecycle-authority.js

@@ -0,0 +1,219 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash, createPublicKey, verify } from "node:crypto";
+import { durableFlowAgentsRoot } from "./lib/local-artifact-root.js";
+export function lifecycleAuthorityKeysPath(projectRoot) {
+    return path.join(durableFlowAgentsRoot(projectRoot), "lifecycle-authority-keys.json");
+}
+export function loadBuilderLifecycleAuthorization(fileInput, expected) {
+    const value = readRegularJson(fileInput, "lifecycle authorization");
+    assertExactKeys(value, ["schema_version", "operation", "run_id", "subject", "assignment_actor_key", "assignment_actor", "nonce", "expires_at", "request", "signature"], "authorization");
+    if (value.schema_version !== "1.0")
+        throw new Error("lifecycle authorization schema_version must be 1.0");
+    assertEqual(value.operation, expected.operation, "operation");
+    assertEqual(value.run_id, expected.runId, "run_id");
+    assertEqual(value.subject, expected.subject, "subject");
+    assertEqual(value.assignment_actor_key, expected.actorKey, "assignment_actor_key");
+    const assignmentActor = validateActor(value.assignment_actor);
+    const request = validateRequest(value.request);
+    const nonce = boundedText(value.nonce, "nonce", 256);
+    const expiresAt = dateTime(value.expires_at, "expires_at");
+    const requestedAt = Date.parse(request.authority.requested_at);
+    const now = Date.parse(expected.now ?? new Date().toISOString());
+    if (expiresAt < requestedAt)
+        throw new Error("lifecycle authorization expires_at must not precede request.authority.requested_at");
+    if (now > expiresAt && !expected.allowExpired)
+        throw new Error("lifecycle authorization is expired");
+    if (requestedAt > now + 5 * 60_000)
+        throw new Error("lifecycle authorization request time is in the future");
+    const signature = validateSignature(value.signature);
+    const authorization = {
+        schema_version: "1.0",
+        operation: expected.operation,
+        run_id: expected.runId,
+        subject: expected.subject,
+        assignment_actor_key: expected.actorKey,
+        assignment_actor: assignmentActor,
+        nonce,
+        expires_at: value.expires_at,
+        request,
+        signature,
+    };
+    verifyAuthorizationSignature(authorization, lifecycleAuthorityKeysPath(expected.projectRoot));
+    return authorization;
+}
+export function builderLifecycleAuthorizationPayload(value) {
+    return JSON.stringify(value);
+}
+export function assertAuthorizationUnused(artifactRoot, authorization) {
+    if (!readAuthorizationConsumption(artifactRoot, authorization))
+        return;
+    throw new Error("lifecycle authorization nonce has already been consumed");
+}
+export function readAuthorizationConsumption(artifactRoot, authorization) {
+    const file = consumedAuthorizationPath(artifactRoot, authorization);
+    if (!pathExistsNoFollow(file))
+        return null;
+    const record = readRegularJson(file, "consumed lifecycle authorization record");
+    if (record.run_id !== authorization.run_id
+        || record.operation !== authorization.operation
+        || record.nonce !== authorization.nonce
+        || record.key_id !== authorization.signature.key_id
+        || record.authorization_sha256 !== authorizationDigest(authorization)) {
+        throw new Error("consumed lifecycle authorization record does not match its integrity key");
+    }
+    return record;
+}
+export function recordAuthorizationConsumed(artifactRoot, authorization, at = new Date().toISOString()) {
+    const file = consumedAuthorizationPath(artifactRoot, authorization);
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true });
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || !pathIsWithin(fs.realpathSync(directory), fs.realpathSync(artifactRoot)))
+        throw new Error("lifecycle authorization registry directory is unsafe");
+    const temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+    const descriptor = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+        fs.writeFileSync(descriptor, `${JSON.stringify({ run_id: authorization.run_id, operation: authorization.operation, nonce: authorization.nonce, key_id: authorization.signature.key_id, authorization_sha256: authorizationDigest(authorization), at })}\n`);
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    try {
+        fs.linkSync(temporary, file);
+        const directoryDescriptor = fs.openSync(directory, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            fs.fsyncSync(directoryDescriptor);
+        }
+        finally {
+            fs.closeSync(directoryDescriptor);
+        }
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+}
+function consumedAuthorizationPath(artifactRoot, authorization) {
+    const integrityKey = createHash("sha256").update(authorization.run_id).update("\0").update(authorization.nonce).digest("hex");
+    return path.join(artifactRoot, "lifecycle-authority", "consumed", `${integrityKey}.json`);
+}
+function authorizationDigest(authorization) {
+    return createHash("sha256").update(JSON.stringify(authorization)).digest("hex");
+}
+function verifyAuthorizationSignature(authorization, keysFile) {
+    const registry = readRegularJson(keysFile, "lifecycle authority key registry", true);
+    assertExactKeys(registry, ["schema_version", "keys"], "key registry");
+    if (registry.schema_version !== "1.0" || !Array.isArray(registry.keys))
+        throw new Error("lifecycle authority key registry must contain schema_version 1.0 and keys[]");
+    const key = registry.keys.find((candidate) => isRecord(candidate) && candidate.id === authorization.signature.key_id);
+    if (!isRecord(key) || key.algorithm !== "ed25519" || typeof key.public_key_pem !== "string" || key.public_key_pem.trim().length === 0) {
+        throw new Error(`lifecycle authorization key ${authorization.signature.key_id} is not trusted`);
+    }
+    const { signature: _signature, ...unsigned } = authorization;
+    let verified = false;
+    try {
+        verified = verify(null, Buffer.from(builderLifecycleAuthorizationPayload(unsigned)), createPublicKey(key.public_key_pem), Buffer.from(authorization.signature.value, "base64"));
+    }
+    catch {
+        verified = false;
+    }
+    if (!verified)
+        throw new Error("lifecycle authorization signature is invalid");
+}
+function readRegularJson(fileInput, label, requireProtected = false) {
+    const file = path.resolve(fileInput);
+    const descriptor = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+        const stat = fs.fstatSync(descriptor);
+        if (!stat.isFile())
+            throw new Error(`${label} must be a regular file`);
+        if (stat.size > 64 * 1024)
+            throw new Error(`${label} exceeds 64 KiB`);
+        if (requireProtected && (stat.mode & 0o022) !== 0)
+            throw new Error(`${label} must not be group- or world-writable`);
+        const value = JSON.parse(fs.readFileSync(descriptor, "utf8"));
+        if (!isRecord(value))
+            throw new Error(`${label} must be a JSON object`);
+        return value;
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function validateActor(value) {
+    if (!isRecord(value))
+        throw new Error("lifecycle authorization assignment_actor must be an object");
+    assertExactKeys(value, ["runtime", "session_id", "host", "human"], "assignment_actor");
+    if (!Object.prototype.hasOwnProperty.call(value, "human"))
+        throw new Error("lifecycle authorization assignment_actor.human is required");
+    for (const field of ["runtime", "session_id", "host"])
+        boundedText(value[field], `assignment_actor.${field}`, 256);
+    if (value.human !== undefined && value.human !== null)
+        boundedText(value.human, "assignment_actor.human", 256);
+    return { runtime: value.runtime, session_id: value.session_id, host: value.host, human: value.human == null ? null : value.human };
+}
+function validateRequest(value) {
+    if (!isRecord(value))
+        throw new Error("lifecycle authorization request must be an object");
+    assertExactKeys(value, ["reason", "authority"], "request");
+    const reason = boundedText(value.reason, "request.reason", 4096);
+    if (!isRecord(value.authority))
+        throw new Error("lifecycle authorization request.authority must be an object");
+    assertExactKeys(value.authority, ["kind", "actor", "request_ref", "requested_at"], "request.authority");
+    if (value.authority.kind !== "user_request" && value.authority.kind !== "operator_request")
+        throw new Error("lifecycle authorization request.authority.kind must be user_request or operator_request");
+    const actor = boundedText(value.authority.actor, "request.authority.actor", 256);
+    const requestRef = boundedText(value.authority.request_ref, "request.authority.request_ref", 2048);
+    dateTime(value.authority.requested_at, "request.authority.requested_at");
+    return { reason, authority: { kind: value.authority.kind, actor, request_ref: requestRef, requested_at: value.authority.requested_at } };
+}
+function validateSignature(value) {
+    if (!isRecord(value))
+        throw new Error("lifecycle authorization signature must be an object");
+    assertExactKeys(value, ["algorithm", "key_id", "value"], "signature");
+    if (value.algorithm !== "ed25519")
+        throw new Error("lifecycle authorization signature.algorithm must be ed25519");
+    return { algorithm: "ed25519", key_id: boundedText(value.key_id, "signature.key_id", 256), value: boundedText(value.value, "signature.value", 1024) };
+}
+function assertEqual(actual, expected, field) {
+    if (actual !== expected)
+        throw new Error(`lifecycle authorization ${field} does not match the requested Builder operation`);
+}
+function assertExactKeys(value, allowed, field) {
+    const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
+    if (unexpected.length)
+        throw new Error(`lifecycle authorization ${field} contains unsupported field ${unexpected[0]}`);
+}
+function dateTime(value, field) {
+    const text = boundedText(value, field, 128);
+    if (!Number.isFinite(Date.parse(text)))
+        throw new Error(`lifecycle authorization ${field} must be a date-time`);
+    return Date.parse(text);
+}
+function boundedText(value, field, limit) {
+    if (!nonEmpty(value) || [...value].length > limit)
+        throw new Error(`lifecycle authorization ${field} must be a non-empty string of at most ${limit} characters`);
+    return value;
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0 && !/[\x00-\x1f\x7f]/.test(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function pathExistsNoFollow(candidate) {
+    try {
+        fs.lstatSync(candidate);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function pathIsWithin(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}

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

@@ -54,6 +54,10 @@ export type AssignmentStatus = {
     record: AssignmentClaimRecord | null;
     has_claim_label?: boolean;
 };
+export declare function resolveCurrentAssignmentActor(): {
+    actor: ActorStruct;
+    actorKey: string;
+};
 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;
@@ -62,13 +66,10 @@ export declare function writeLocalRecord(artifactRoot: string, subjectId: string
  * 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
+ * races against the built CLI). Atomic directory creation establishes ownership before metadata
+ * is written; contenders treat even an ownerless directory as held. Live contention waits with a
+ * bounded deadline; stale or malformed residue fails closed for explicit operator cleanup because portable Node
+ * filesystem APIs cannot compare-and-swap a directory identity safely. 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,
@@ -164,6 +165,12 @@ export declare function performLocalRelease(artifactRoot: string, subjectId: str
     actorKey?: string;
     tolerateNoActiveClaim?: boolean;
 }): AssignmentClaimRecord | null;
+/** Caller must already hold this subject's assignment lock through withSubjectLock(). */
+export declare function performLocalReleaseUnderLock(artifactRoot: string, subjectId: string, releasedBy: ActorStruct | null, opts?: {
+    reason?: string;
+    actorKey?: string;
+    tolerateNoActiveClaim?: boolean;
+}): AssignmentClaimRecord | null;
 /**
  * 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

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

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { randomBytes } from "node:crypto";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagString } from "../lib/args.js";
@@ -76,6 +77,9 @@ function loadActorStruct(args) {
     const actorJsonPath = flagString(args.flags, "actor-json");
     if (actorJsonPath)
         return { actor: loadActorStructFromFile(actorJsonPath) };
+    return resolveCurrentAssignmentActor();
+}
+export function resolveCurrentAssignmentActor() {
     const helper = loadActorIdentityHelper();
     const resolved = helper.resolveActor(process.env);
     if (helper.isUnresolvedActor(resolved.actor))
@@ -86,9 +90,15 @@ function loadActorStruct(args) {
     // CI session — actor_key stays correct (so no false-block), but record.actor is malformed and the
     // audit-trail / `assignment-provider status` output for CI sessions would be corrupt.
     const ci = resolved.source.startsWith("ci-runtime") ? helper.detectCiActor(process.env) : null;
-    const actor = ci && ci.session_id
-        ? { runtime: ci.runtime, session_id: ci.session_id, host: os.hostname(), human: null }
-        : { runtime: helper.detectRuntime(process.env), session_id: resolved.actor, host: os.hostname(), human: null };
+    const runtimeSessionId = resolved.source.startsWith("runtime-session-id") ? helper.runtimeSessionId(process.env) : "";
+    const ancestrySeed = resolved.source === "process-ancestry" ? helper.ancestorActorSeed() : "";
+    const actor = resolved.source === "explicit-override"
+        ? { runtime: "explicit-override", session_id: resolved.actor, host: os.hostname(), human: null }
+        : ci && ci.session_id
+            ? { runtime: ci.runtime, session_id: ci.session_id, host: os.hostname(), human: null }
+            : runtimeSessionId
+                ? { runtime: helper.detectRuntime(process.env), session_id: runtimeSessionId, host: os.hostname(), human: null }
+                : { runtime: helper.detectRuntime(process.env), session_id: ancestrySeed ? `anc-${ancestrySeed}` : resolved.actor, host: os.hostname(), human: null };
     return { actor, actorKey: resolved.actor };
 }
 export function assignmentFilePath(artifactRoot, subjectId) {
@@ -177,18 +187,27 @@ function subjectLockDir(artifactRoot, subjectId) {
     const sanitized = loadActorIdentityHelper().sanitizeSegment(subjectId);
     return path.join(assignmentDir, `.${sanitized}.lockdir`);
 }
+// Lock age is adjudicated by the current contender, never by metadata written
+// by the lock owner. The environment is only an operator tuning input; clamp it
+// so a caller cannot turn a transient owner-file write into immediate takeover.
+const SUBJECT_LOCK_STALE_MIN_MS = 1_000;
+const SUBJECT_LOCK_STALE_MAX_MS = 30 * 60 * 1_000;
+const SUBJECT_LOCK_STALE_DEFAULT_MS = 5 * 60 * 1_000;
+function trustedSubjectLockStaleMs() {
+    const configured = Number(process.env.FLOW_AGENTS_ASSIGNMENT_STALE_LOCK_MS);
+    if (!Number.isFinite(configured))
+        return SUBJECT_LOCK_STALE_DEFAULT_MS;
+    return Math.min(SUBJECT_LOCK_STALE_MAX_MS, Math.max(SUBJECT_LOCK_STALE_MIN_MS, Math.floor(configured)));
+}
 /**
  * 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
+ * races against the built CLI). Atomic directory creation establishes ownership before metadata
+ * is written; contenders treat even an ownerless directory as held. Live contention waits with a
+ * bounded deadline; stale or malformed residue fails closed for explicit operator cleanup because portable Node
+ * filesystem APIs cannot compare-and-swap a directory identity safely. 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,
@@ -199,23 +218,33 @@ function subjectLockDir(artifactRoot, subjectId) {
  */
 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 staleMs = trustedSubjectLockStaleMs();
+    const token = randomBytes(16).toString("hex");
+    const ownerFile = path.join(lockDir, "owner.json");
     const deadline = Date.now() + 30000;
     while (true) {
+        let createdLockDir = false;
         try {
             fs.mkdirSync(lockDir);
+            createdLockDir = true;
+            fs.writeFileSync(ownerFile, `${JSON.stringify({ token, pid: process.pid, acquired_at: isoNow() })}\n`, { flag: "wx", mode: 0o600 });
             break;
         }
         catch (error) {
             const lockError = error;
+            if (createdLockDir)
+                fs.rmSync(lockDir, { recursive: true, force: true });
             if (lockError.code !== "EEXIST") {
                 throw new Error(`failed to acquire assignment lock for subject ${subjectId}: ${lockDir}: ${lockError.message || lockError.code || String(lockError)}`);
             }
             try {
-                const stat = fs.statSync(lockDir);
-                if (staleMs > 0 && Date.now() - stat.mtimeMs > staleMs) {
-                    fs.rmSync(lockDir, { recursive: true, force: true });
-                    continue;
+                const owner = readSubjectLockOwner(ownerFile);
+                const stat = fs.lstatSync(owner?.token ? ownerFile : lockDir);
+                if (stat.isSymbolicLink() || !(owner?.token ? stat.isFile() : stat.isDirectory())) {
+                    throw new Error(`assignment lock has an unsafe ${owner?.token ? "owner file" : "directory"}: ${lockDir}`);
+                }
+                if (Date.now() - stat.mtimeMs > staleMs) {
+                    throw new Error(`assignment lock is stale or malformed and requires explicit operator cleanup after confirming no owner is active: ${lockDir}`);
                 }
             }
             catch (statError) {
@@ -229,7 +258,14 @@ export function withSubjectLock(artifactRoot, subjectId, body) {
             sleepSync(20);
         }
     }
-    const release = () => fs.rmSync(lockDir, { recursive: true, force: true });
+    let heartbeat;
+    const ownsLock = () => readSubjectLockOwner(ownerFile)?.token === token;
+    const release = () => {
+        if (heartbeat)
+            clearInterval(heartbeat);
+        if (ownsLock())
+            fs.rmSync(lockDir, { recursive: true, force: true });
+    };
     let result;
     try {
         result = body();
@@ -239,11 +275,38 @@ export function withSubjectLock(artifactRoot, subjectId, body) {
         throw error;
     }
     if (result && typeof result.then === "function") {
+        // An async owner can legitimately hold the lock longer than the stale-lock
+        // threshold while an authority-bound command is running. Keep its mtime fresh
+        // so lifecycle operations and takeovers continue to observe the live lock.
+        const heartbeatMs = Math.max(10, Math.min(1_000, Math.floor(staleMs > 0 ? staleMs / 3 : 1_000)));
+        heartbeat = setInterval(() => {
+            try {
+                if (!ownsLock())
+                    return;
+                const timestamp = new Date();
+                fs.utimesSync(ownerFile, timestamp, timestamp);
+                fs.utimesSync(lockDir, timestamp, timestamp);
+            }
+            catch { /* release, reclamation, or process teardown owns cleanup */ }
+        }, heartbeatMs);
         return Promise.resolve(result).finally(release);
     }
     release();
     return result;
 }
+function readSubjectLockOwner(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        return value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : null;
+    }
+    catch (error) {
+        if (error.code === "ENOENT" || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
 /**
  * The assignment ⋈ liveness join (contract doc's "assignment ⋈ liveness join" section, ADR 0021
  * §1). Pure function: `{ assignment, freshHoldersList, selfActor, nowMs }` -> one of five
@@ -522,61 +585,61 @@ function claimLocalFile(argv) {
  * than allowed to silently no-op or wrongly refuse.
  */
 export function performLocalRelease(artifactRoot, subjectId, releasedBy, opts = {}) {
+    return withSubjectLock(artifactRoot, subjectId, () => performLocalReleaseUnderLock(artifactRoot, subjectId, releasedBy, opts));
+}
+/** Caller must already hold this subject's assignment lock through withSubjectLock(). */
+export function performLocalReleaseUnderLock(artifactRoot, subjectId, releasedBy, opts = {}) {
     const helper = loadActorIdentityHelper();
     const reason = opts.reason ?? "released";
     const tolerateNoActiveClaim = opts.tolerateNoActiveClaim ?? false;
-    // F1 fix (fix-plan iteration 1, CRITICAL): release mutates the same record file claim/supersede
-    // do, under the same per-subject lock (see withSubjectLock()'s doc comment).
-    return withSubjectLock(artifactRoot, subjectId, () => {
-        const existing = readLocalRecord(artifactRoot, subjectId);
-        if (!existing || existing.status !== "claimed") {
-            if (tolerateNoActiveClaim)
+    const existing = readLocalRecord(artifactRoot, subjectId);
+    if (!existing || existing.status !== "claimed") {
+        if (tolerateNoActiveClaim)
+            return null;
+        throw new Error(`no active claim to release for subject: ${subjectId}`);
+    }
+    if (releasedBy) {
+        // Contract guard (hardening fix, #292 review): a caller that supplies `releasedBy` but NOT
+        // `opts.actorKey` against a record that already carries `actor_key` cannot reliably prove
+        // ownership — see this function's doc comment. This is the ONLY combination that fires: it
+        // does NOT fire when `existing.actor_key` is absent (the CLI/fixture path, where both sides
+        // fall back to serializeActor() and legitimately compare equal). Fail loudly rather than
+        // silently no-op (tolerant callers) or wrongly refuse (throwing callers) — never silent.
+        if (!opts.actorKey && existing.actor_key) {
+            if (tolerateNoActiveClaim) {
+                console.error(`[performLocalRelease] cannot verify ownership of an actor_key-stamped record without opts.actorKey; skipping release for ${subjectId}`);
                 return null;
-            throw new Error(`no active claim to release for subject: ${subjectId}`);
-        }
-        if (releasedBy) {
-            // Contract guard (hardening fix, #292 review): a caller that supplies `releasedBy` but NOT
-            // `opts.actorKey` against a record that already carries `actor_key` cannot reliably prove
-            // ownership — see this function's doc comment. This is the ONLY combination that fires: it
-            // does NOT fire when `existing.actor_key` is absent (the CLI/fixture path, where both sides
-            // fall back to serializeActor() and legitimately compare equal). Fail loudly rather than
-            // silently no-op (tolerant callers) or wrongly refuse (throwing callers) — never silent.
-            if (!opts.actorKey && existing.actor_key) {
-                if (tolerateNoActiveClaim) {
-                    console.error(`[performLocalRelease] cannot verify ownership of an actor_key-stamped record without opts.actorKey; skipping release for ${subjectId}`);
-                    return null;
-                }
-                throw new Error("performLocalRelease: pass opts.actorKey (the canonical resolveActor().actor string) when releasedBy is set and the record carries actor_key — serializeActor(releasedBy) is not a valid ownership key for actor_key-stamped records");
-            }
-            // AC6: never force-release a claim held by a different actor. Mirrors
-            // computeEffectiveState()'s canonical self-recognition comparison EXACTLY —
-            // `holderActorKey` prefers the stored `actor_key` (the canonical resolveActor(env).actor
-            // string, present on records written by the fixed performLocalClaim/performLocalSupersede
-            // paths) and only falls back to `serializeActor(existing.actor)` when `actor_key` is
-            // absent (every pre-fix record, every #290 eval fixture). The releaser's side must use the
-            // SAME canonical form: `opts.actorKey` (the caller's resolveActor(env).actor string, e.g.
-            // scripts/hooks/stop-goal-fit.js's Stop hook) when provided, else re-derived via
-            // serializeActor(releasedBy) — never serializeActor() unconditionally on both sides, which
-            // would compare the bare actor_key form against a re-derived triple form for an
-            // explicit-override actor and spuriously reject a legitimate same-actor release (the #291
-            // seam, relocated to this write path).
-            const holderActorKey = existing.actor_key || helper.serializeActor(existing.actor);
-            const releasedByActorKey = opts.actorKey || helper.serializeActor(releasedBy);
-            if (holderActorKey !== releasedByActorKey) {
-                if (tolerateNoActiveClaim)
-                    return null;
-                throw new Error(`--actor-json does not match the current holder (${holderActorKey}); refusing to release a claim held by someone else`);
             }
+            throw new Error("performLocalRelease: pass opts.actorKey (the canonical resolveActor().actor string) when releasedBy is set and the record carries actor_key — serializeActor(releasedBy) is not a valid ownership key for actor_key-stamped records");
         }
-        const record = {
-            ...existing,
-            ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
-            status: "released",
-            audit_trail: [...(existing.audit_trail ?? []), { at: isoNow(), transition: "release", from_actor: existing.actor, to_actor: releasedBy, reason }],
-        };
-        writeLocalRecord(artifactRoot, subjectId, record);
-        return record;
-    });
+        // AC6: never force-release a claim held by a different actor. Mirrors
+        // computeEffectiveState()'s canonical self-recognition comparison EXACTLY —
+        // `holderActorKey` prefers the stored `actor_key` (the canonical resolveActor(env).actor
+        // string, present on records written by the fixed performLocalClaim/performLocalSupersede
+        // paths) and only falls back to `serializeActor(existing.actor)` when `actor_key` is
+        // absent (every pre-fix record, every #290 eval fixture). The releaser's side must use the
+        // SAME canonical form: `opts.actorKey` (the caller's resolveActor(env).actor string, e.g.
+        // scripts/hooks/stop-goal-fit.js's Stop hook) when provided, else re-derived via
+        // serializeActor(releasedBy) — never serializeActor() unconditionally on both sides, which
+        // would compare the bare actor_key form against a re-derived triple form for an
+        // explicit-override actor and spuriously reject a legitimate same-actor release (the #291
+        // seam, relocated to this write path).
+        const holderActorKey = existing.actor_key || helper.serializeActor(existing.actor);
+        const releasedByActorKey = opts.actorKey || helper.serializeActor(releasedBy);
+        if (holderActorKey !== releasedByActorKey) {
+            if (tolerateNoActiveClaim)
+                return null;
+            throw new Error(`--actor-json does not match the current holder (${holderActorKey}); refusing to release a claim held by someone else`);
+        }
+    }
+    const record = {
+        ...existing,
+        ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
+        status: "released",
+        audit_trail: [...(existing.audit_trail ?? []), { at: isoNow(), transition: "release", from_actor: existing.actor, to_actor: releasedBy, reason }],
+    };
+    writeLocalRecord(artifactRoot, subjectId, record);
+    return record;
 }
 function releaseLocalFile(argv) {
     const args = parseArgs(argv);