@kontourai/flow-agents 3.6.0 → 3.8.0

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";
@@ -309,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,
@@ -331,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
@@ -358,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();
@@ -367,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
@@ -726,7 +775,19 @@ export function performLocalReleaseUnderLock(
       // 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) {
+      // Pre-3.7 lifecycle events could persist the derived ancestry actor before
+      // sanitizeSegment removed ':' separators. Modern explicit/env release paths
+      // always use the sanitized form. Accept only that one-way legacy migration;
+      // never normalize two modern keys or relax ownership to a prefix match.
+      const sameActorStruct = existing.actor.runtime === releasedBy.runtime
+        && existing.actor.session_id === releasedBy.session_id
+        && existing.actor.host === releasedBy.host
+        && (existing.actor.human ?? null) === (releasedBy.human ?? null);
+      const legacyActorKeyMatches = holderActorKey.includes(":")
+        && holderActorKey === helper.serializeActor(existing.actor)
+        && helper.sanitizeSegment(holderActorKey) === releasedByActorKey
+        && sameActorStruct;
+      if (holderActorKey !== releasedByActorKey && !legacyActorKeyMatches) {
         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`);
       }

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"] },
   ]);
 });