@kontourai/flow-agents 3.4.3 → 3.6.0

package/src/cli/assignment-provider.ts

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagString, type ParsedArgs } from "../lib/args.js";
-import { readJson, writeJson, isoNow } from "../lib/fs.js";
+import { atomicWriteJson, readJson, isoNow } from "../lib/fs.js";
 
 // ─── AssignmentProvider CLI (#290) ──────────────────────────────────────────
 // context/contracts/assignment-provider-contract.md is the governing vocabulary doc for this
@@ -60,6 +60,7 @@ export type AssignmentClaimRecord = {
   subject_id: string;
   actor: ActorStruct;
   actor_key?: string;
+  work_item_ref?: string;
   claimed_at: string;
   ttl_seconds: number;
   branch: string;
@@ -120,6 +121,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);
@@ -130,6 +133,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;
   };
 }
@@ -198,6 +203,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");
@@ -207,9 +216,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 };
 }
 
@@ -218,16 +233,50 @@ export function assignmentFilePath(artifactRoot: string, subjectId: string): str
   return path.join(artifactRoot, "assignment", `${sanitized}.json`);
 }
 
+function localAssignmentDir(artifactRoot: string, create: boolean): string | null {
+  const dir = path.join(artifactRoot, "assignment");
+  if (create) fs.mkdirSync(dir, { recursive: true });
+  let stat: fs.Stats;
+  try {
+    stat = fs.lstatSync(dir);
+  } catch (error) {
+    if (!create && (error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`assignment directory must be a real directory, not a symlink: ${dir}`);
+  }
+  const realRoot = fs.realpathSync(artifactRoot);
+  if (fs.realpathSync(dir) !== path.join(realRoot, "assignment")) {
+    throw new Error(`assignment directory escapes the artifact root: ${dir}`);
+  }
+  return dir;
+}
+
 export function readLocalRecord(artifactRoot: string, subjectId: string): AssignmentClaimRecord | null {
+  if (!localAssignmentDir(artifactRoot, false)) return null;
   const file = assignmentFilePath(artifactRoot, subjectId);
-  if (!fs.existsSync(file)) return null;
+  let stat: fs.Stats;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`assignment record must be a regular file, not a symlink: ${file}`);
+  }
   let data: unknown;
+  let descriptor: number | null = null;
   try {
-    data = readJson(file);
+    descriptor = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    data = JSON.parse(fs.readFileSync(descriptor, "utf8"));
   } catch (error) {
     // Fail loud: a corrupt claim record must never be silently treated as "no claim" — that
     // would be a fail-open path that could let a second claim silently overwrite a real one.
     throw new Error(`assignment record is corrupt, refusing to proceed: ${file}: ${(error as Error).message}`);
+  } finally {
+    if (descriptor !== null) fs.closeSync(descriptor);
   }
   if (typeof data !== "object" || data === null) throw new Error(`assignment record is not an object: ${file}`);
   const record = data as AssignmentClaimRecord;
@@ -239,7 +288,7 @@ export function writeLocalRecord(artifactRoot: string, subjectId: string, 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).
-  writeJson(assignmentFilePath(artifactRoot, subjectId), record);
+  atomicWriteJson(artifactRoot, assignmentFilePath(artifactRoot, subjectId), record);
 }
 
 /**
@@ -255,8 +304,7 @@ function sleepSync(ms: number): void {
 }
 
 function subjectLockDir(artifactRoot: string, subjectId: string): string {
-  const assignmentDir = path.join(artifactRoot, "assignment");
-  fs.mkdirSync(assignmentDir, { recursive: true });
+  const assignmentDir = localAssignmentDir(artifactRoot, true)!;
   const sanitized = loadActorIdentityHelper().sanitizeSegment(subjectId);
   return path.join(assignmentDir, `.${sanitized}.lockdir`);
 }
@@ -310,11 +358,19 @@ export function withSubjectLock<T>(artifactRoot: string, subjectId: string, body
       sleepSync(20);
     }
   }
+  const release = (): void => fs.rmSync(lockDir, { recursive: true, force: true });
+  let result: T;
   try {
-    return body();
-  } finally {
-    fs.rmSync(lockDir, { recursive: true, force: true });
+    result = body();
+  } catch (error) {
+    release();
+    throw error;
+  }
+  if (result && typeof (result as { then?: unknown }).then === "function") {
+    return Promise.resolve(result).finally(release) as T;
   }
+  release();
+  return result;
 }
 
 /**
@@ -512,7 +568,7 @@ export function performLocalClaim(
   artifactRoot: string,
   subjectId: string,
   actor: ActorStruct,
-  opts: { ttlSeconds: number; branch: string; artifactDir: string; reason?: string; actorKey?: string },
+  opts: { ttlSeconds: number; branch: string; artifactDir: string; reason?: string; actorKey?: string; workItemRef?: string },
 ): AssignmentClaimRecord {
   const helper = loadActorIdentityHelper();
   const reason = opts.reason ?? "claim";
@@ -538,6 +594,7 @@ export function performLocalClaim(
       subject_id: subjectId,
       actor,
       ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
+      ...((opts.workItemRef ?? existing?.work_item_ref) ? { work_item_ref: opts.workItemRef ?? existing?.work_item_ref } : {}),
       claimed_at: isoNow(),
       ttl_seconds: opts.ttlSeconds,
       branch: opts.branch,
@@ -615,15 +672,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}`);
@@ -675,8 +739,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 {
@@ -707,7 +770,7 @@ export function performLocalSupersede(
   subjectId: string,
   fromActor: ActorStruct,
   toActor: ActorStruct,
-  opts: { ttlSeconds?: number; branch?: string; artifactDir?: string; reason?: string; actorKey?: string } = {},
+  opts: { ttlSeconds?: number; branch?: string; artifactDir?: string; reason?: string; actorKey?: string; workItemRef?: string } = {},
 ): AssignmentClaimRecord {
   const helper = loadActorIdentityHelper();
   const reason = opts.reason ?? "supersede";
@@ -732,6 +795,7 @@ export function performLocalSupersede(
       subject_id: subjectId,
       actor: toActor,
       ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
+      ...((opts.workItemRef ?? existing.work_item_ref) ? { work_item_ref: opts.workItemRef ?? existing.work_item_ref } : {}),
       claimed_at: isoNow(),
       ttl_seconds: ttlSeconds,
       branch: opts.branch ?? existing.branch,