@kontourai/flow-agents 3.5.0 → 3.7.0

package/src/builder-lifecycle-authority.ts

@@ -0,0 +1,218 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash, createPublicKey, verify } from "node:crypto";
+import type { FlowLifecycleRequest } from "@kontourai/flow";
+import type { ActorStruct } from "./cli/assignment-provider.js";
+import { durableFlowAgentsRoot } from "./lib/local-artifact-root.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 function lifecycleAuthorityKeysPath(projectRoot: string): string {
+  return path.join(durableFlowAgentsRoot(projectRoot), "lifecycle-authority-keys.json");
+}
+
+export function loadBuilderLifecycleAuthorization(
+  fileInput: string,
+  expected: { projectRoot: string; operation: AuthorizedBuilderLifecycleOperation; runId: string; subject: string; actorKey: string; now?: string; allowExpired?: boolean },
+): BuilderLifecycleAuthorization {
+  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 as string,
+    request,
+    signature,
+  } satisfies BuilderLifecycleAuthorization;
+  verifyAuthorizationSignature(authorization, lifecycleAuthorityKeysPath(expected.projectRoot));
+  return authorization;
+}
+
+export function builderLifecycleAuthorizationPayload(value: Omit<BuilderLifecycleAuthorization, "signature">): string {
+  return JSON.stringify(value);
+}
+
+export function assertAuthorizationUnused(artifactRoot: string, authorization: BuilderLifecycleAuthorization): void {
+  if (!readAuthorizationConsumption(artifactRoot, authorization)) return;
+  throw new Error("lifecycle authorization nonce has already been consumed");
+}
+
+export function readAuthorizationConsumption(artifactRoot: string, authorization: BuilderLifecycleAuthorization): JsonRecord | null {
+  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: string, authorization: BuilderLifecycleAuthorization, at = new Date().toISOString()): void {
+  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: string, authorization: BuilderLifecycleAuthorization): string {
+  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: BuilderLifecycleAuthorization): string {
+  return createHash("sha256").update(JSON.stringify(authorization)).digest("hex");
+}
+
+function verifyAuthorizationSignature(authorization: BuilderLifecycleAuthorization, keysFile: string): void {
+  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: string, label: string, requireProtected = false): JsonRecord {
+  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")) as unknown;
+    if (!isRecord(value)) throw new Error(`${label} must be a JSON object`);
+    return value;
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function validateActor(value: unknown): ActorStruct {
+  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"] as const) 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 as string, session_id: value.session_id as string, host: value.host as string, human: value.human == null ? null : value.human as string };
+}
+
+function validateRequest(value: unknown): FlowLifecycleRequest {
+  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 as string } };
+}
+
+function validateSignature(value: unknown): BuilderLifecycleAuthorization["signature"] {
+  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: unknown, expected: string, field: string): void {
+  if (actual !== expected) throw new Error(`lifecycle authorization ${field} does not match the requested Builder operation`);
+}
+
+function assertExactKeys(value: JsonRecord, allowed: string[], field: string): void {
+  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: unknown, field: string): number {
+  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: unknown, field: string, limit: number): string {
+  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: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0 && !/[\x00-\x1f\x7f]/.test(value);
+}
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function pathExistsNoFollow(candidate: string): boolean {
+  try { fs.lstatSync(candidate); return true; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return false; throw error; }
+}
+
+function pathIsWithin(candidate: string, root: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}

package/src/cli/assignment-provider-lock.test.mjs

@@ -0,0 +1,83 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { syncBuiltinESMExports } from "node:module";
+
+import { withSubjectLock } from "../../build/src/cli/assignment-provider.js";
+
+test("a displaced lock owner cannot heartbeat or release a replacement lock", async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-lock-aba-"));
+  const subject = "lock-aba";
+  const lockDir = path.join(root, "assignment", ".lock-aba.lockdir");
+  let finish;
+  const held = withSubjectLock(root, subject, () => new Promise((resolve) => { finish = resolve; }));
+  const original = JSON.parse(fs.readFileSync(path.join(lockDir, "owner.json"), "utf8"));
+
+  const quarantine = `${lockDir}.stale-test`;
+  fs.renameSync(lockDir, quarantine);
+  fs.mkdirSync(lockDir);
+  const replacement = { token: "replacement-owner", stale_after_ms: 300000 };
+  fs.writeFileSync(path.join(lockDir, "owner.json"), `${JSON.stringify(replacement)}\n`);
+  fs.rmSync(quarantine, { recursive: true, force: true });
+
+  finish();
+  await held;
+  assert.equal(fs.existsSync(lockDir), true);
+  assert.deepEqual(JSON.parse(fs.readFileSync(path.join(lockDir, "owner.json"), "utf8")), replacement);
+  assert.notEqual(original.token, replacement.token);
+});
+
+test("stale locks fail closed instead of risking concurrent reclamation", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-lock-stale-"));
+  const lockDir = path.join(root, "assignment", ".lock-stale.lockdir");
+  fs.mkdirSync(lockDir, { recursive: true });
+  const ownerFile = path.join(lockDir, "owner.json");
+  fs.writeFileSync(ownerFile, `${JSON.stringify({ token: "old-owner", stale_after_ms: 1 })}\n`);
+  // The owner-provided one-millisecond threshold is ignored. Reclamation uses
+  // the contender's bounded policy, so this must be older than its default.
+  const old = new Date(Date.now() - 10 * 60 * 1000);
+  fs.utimesSync(ownerFile, old, old);
+
+  assert.throws(() => withSubjectLock(root, "lock-stale", () => "unreachable"), /requires explicit operator cleanup/);
+  assert.equal(fs.existsSync(lockDir), true);
+});
+
+test("old ownerless and malformed locks fail closed without a busy-spin", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-lock-malformed-"));
+  const assignmentDir = path.join(root, "assignment");
+  for (const [subject, owner] of [["ownerless", null], ["malformed", "not-json\n"]]) {
+    const lockDir = path.join(assignmentDir, `.${subject}.lockdir`);
+    fs.mkdirSync(lockDir, { recursive: true });
+    if (owner !== null) fs.writeFileSync(path.join(lockDir, "owner.json"), owner);
+    const old = new Date(Date.now() - 10 * 60 * 1000);
+    fs.utimesSync(lockDir, old, old);
+    if (owner !== null) fs.utimesSync(path.join(lockDir, "owner.json"), old, old);
+    const started = Date.now();
+    assert.throws(() => withSubjectLock(root, subject, () => "unreachable"), /requires explicit operator cleanup/);
+    assert.ok(Date.now() - started < 1_000, `${subject} stale lock should fail without spinning until deadline`);
+    assert.equal(fs.existsSync(lockDir), true);
+  }
+});
+
+test("failed owner metadata creation removes the ownerless lock directory", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-lock-owner-write-"));
+  const originalWriteFileSync = fs.writeFileSync;
+  fs.writeFileSync = function injectedOwnerWriteFailure(file, ...args) {
+    if (path.basename(String(file)) === "owner.json") {
+      const error = new Error("injected owner write failure");
+      error.code = "EACCES";
+      throw error;
+    }
+    return originalWriteFileSync.call(this, file, ...args);
+  };
+  syncBuiltinESMExports();
+  try {
+    assert.throws(() => withSubjectLock(root, "owner-write", () => "unreachable"), /failed to acquire assignment lock/);
+  } finally {
+    fs.writeFileSync = originalWriteFileSync;
+    syncBuiltinESMExports();
+  }
+  assert.equal(fs.existsSync(path.join(root, "assignment", ".owner-write.lockdir")), false);
+});

package/src/cli/assignment-provider.ts

@@ -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, type ParsedArgs } from "../lib/args.js";
@@ -121,6 +122,8 @@ function loadActorIdentityHelper(): {
   isUnresolvedActor: (actor: string) => boolean;
   sanitizeSegment: (value: unknown) => string;
   detectRuntime: (env: NodeJS.ProcessEnv) => string;
+  runtimeSessionId: (env: NodeJS.ProcessEnv) => string;
+  ancestorActorSeed: () => string;
   detectCiActor: (env: NodeJS.ProcessEnv) => { runtime: string; session_id: string } | null;
 } {
   const _req = createRequire(import.meta.url);
@@ -131,6 +134,8 @@ function loadActorIdentityHelper(): {
     isUnresolvedActor: (actor: string) => boolean;
     sanitizeSegment: (value: unknown) => string;
     detectRuntime: (env: NodeJS.ProcessEnv) => string;
+    runtimeSessionId: (env: NodeJS.ProcessEnv) => string;
+    ancestorActorSeed: () => string;
     detectCiActor: (env: NodeJS.ProcessEnv) => { runtime: string; session_id: string } | null;
   };
 }
@@ -199,6 +204,10 @@ function loadActorStructFromFile(file: string): ActorStruct {
 function loadActorStruct(args: ParsedArgs): { actor: ActorStruct; actorKey?: string } {
   const actorJsonPath = flagString(args.flags, "actor-json");
   if (actorJsonPath) return { actor: loadActorStructFromFile(actorJsonPath) };
+  return resolveCurrentAssignmentActor();
+}
+
+export function resolveCurrentAssignmentActor(): { actor: ActorStruct; actorKey: string } {
   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");
@@ -208,9 +217,15 @@ function loadActorStruct(args: ParsedArgs): { actor: ActorStruct; actorKey?: str
   // 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: ActorStruct = 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: ActorStruct = 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 };
 }
 
@@ -295,18 +310,28 @@ function subjectLockDir(artifactRoot: string, subjectId: string): string {
   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(): number {
+  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,
@@ -317,22 +342,31 @@ function subjectLockDir(artifactRoot: string, subjectId: string): string {
  */
 export function withSubjectLock<T>(artifactRoot: string, subjectId: string, body: () => T): T {
   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 as NodeJS.ErrnoException;
+      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) {
         if ((statError as NodeJS.ErrnoException).code === "ENOENT") continue; // lock released between mkdir/EEXIST and stat; retry immediately
@@ -344,7 +378,12 @@ export function withSubjectLock<T>(artifactRoot: string, subjectId: string, body
       sleepSync(20);
     }
   }
-  const release = (): void => fs.rmSync(lockDir, { recursive: true, force: true });
+  let heartbeat: NodeJS.Timeout | undefined;
+  const ownsLock = (): boolean => readSubjectLockOwner(ownerFile)?.token === token;
+  const release = (): void => {
+    if (heartbeat) clearInterval(heartbeat);
+    if (ownsLock()) fs.rmSync(lockDir, { recursive: true, force: true });
+  };
   let result: T;
   try {
     result = body();
@@ -353,12 +392,36 @@ export function withSubjectLock<T>(artifactRoot: string, subjectId: string, body
     throw error;
   }
   if (result && typeof (result as { then?: unknown }).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) as T;
   }
   release();
   return result;
 }
 
+function readSubjectLockOwner(file: string): { token?: string } | null {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8")) as unknown;
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? value as { token?: string }
+      : null;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).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
@@ -658,15 +721,22 @@ export function performLocalRelease(
   subjectId: string,
   releasedBy: ActorStruct | null,
   opts: { reason?: string; actorKey?: string; tolerateNoActiveClaim?: boolean } = {},
+): AssignmentClaimRecord | null {
+  return withSubjectLock(artifactRoot, subjectId, () => performLocalReleaseUnderLock(artifactRoot, subjectId, releasedBy, opts));
+}
+
+/** Caller must already hold this subject's assignment lock through withSubjectLock(). */
+export function performLocalReleaseUnderLock(
+  artifactRoot: string,
+  subjectId: string,
+  releasedBy: ActorStruct | null,
+  opts: { reason?: string; actorKey?: string; tolerateNoActiveClaim?: boolean } = {},
 ): AssignmentClaimRecord | null {
   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, (): AssignmentClaimRecord | null => {
-    const existing = readLocalRecord(artifactRoot, subjectId);
+  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}`);
@@ -718,8 +788,7 @@ export function performLocalRelease(
       audit_trail: [...(existing.audit_trail ?? []), { at: isoNow(), transition: "release", from_actor: existing.actor, to_actor: releasedBy, reason }],
     };
     writeLocalRecord(artifactRoot, subjectId, record);
-    return record;
-  });
+  return record;
 }
 
 function releaseLocalFile(argv: string[]): number {

package/src/cli/builder-flow-run-adapter.test.mjs

@@ -17,7 +17,7 @@ import {
   BUILDER_BUILD_FLOW_ID,
   evaluateBuilderBuildRun,
   startBuilderBuildRun,
-} from "../../build/src/index.js";
+} from "../../build/src/builder-flow-run-adapter.js";
 
 const REPO_ROOT = path.resolve(import.meta.dirname, "../..");
 const BUILDER_BUILD_DEFINITION = path.join(REPO_ROOT, "kits/builder/flows/build.flow.json");
@@ -245,6 +245,8 @@ test("all verified parent selectors advance only their persisted gates through p
       subjectType: "flow-step",
       name: "verify-all-selectors",
       bundle: trustBundle({ claims: [
+        claim("workflow.critique.review", "workflow-critique"),
+        claim("workflow.acceptance.criterion", "flow-step"),
         claim("builder.verify.tests", "flow-step"),
         claim("builder.verify.policy-compliance", "artifact"),
       ] }),
@@ -271,7 +273,7 @@ test("all verified parent selectors advance only their persisted gates through p
     { gate_id: "design-probe-gate", status: "pass", matched_expectations: ["pickup-probe-readiness", "probe-decisions-or-accepted-gaps"] },
     { gate_id: "plan-gate", status: "pass", matched_expectations: ["implementation-plan"] },
     { gate_id: "execute-gate", status: "pass", matched_expectations: ["implementation-scope"] },
-    { gate_id: "verify-gate", status: "pass", matched_expectations: ["tests-evidence", "policy-compliance"] },
+    { gate_id: "verify-gate", status: "pass", matched_expectations: ["clean-critique", "acceptance-criteria", "tests-evidence", "policy-compliance"] },
     { gate_id: "merge-ready-gate", status: "pass", matched_expectations: ["merge-readiness"] },
   ]);
 });