@kontourai/flow-agents 3.4.3 → 3.6.0

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

@@ -31,6 +31,7 @@ export type AssignmentClaimRecord = {
     subject_id: string;
     actor: ActorStruct;
     actor_key?: string;
+    work_item_ref?: string;
     claimed_at: string;
     ttl_seconds: number;
     branch: string;
@@ -53,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;
@@ -116,6 +121,7 @@ export declare function performLocalClaim(artifactRoot: string, subjectId: strin
     artifactDir: string;
     reason?: string;
     actorKey?: string;
+    workItemRef?: string;
 }): AssignmentClaimRecord;
 /**
  * Wave 1 (#292) extraction: the durable-write body previously inlined inside releaseLocalFile's
@@ -162,6 +168,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
@@ -177,6 +189,7 @@ export declare function performLocalSupersede(artifactRoot: string, subjectId: s
     artifactDir?: string;
     reason?: string;
     actorKey?: string;
+    workItemRef?: string;
 }): AssignmentClaimRecord;
 /**
  * Wave 1 (#291) extraction: the local-file branch of statusCommand's assignment-layer read,

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

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagString } from "../lib/args.js";
-import { readJson, writeJson, isoNow } from "../lib/fs.js";
+import { atomicWriteJson, readJson, isoNow } from "../lib/fs.js";
 const DEFAULT_LABEL_NAME = "agent:claimed";
 const CLAIM_COMMENT_MARKER_DEFAULT = "<!-- flow-agents:assignment-claim -->";
 /**
@@ -76,6 +76,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,28 +89,74 @@ 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) {
     const sanitized = loadActorIdentityHelper().sanitizeSegment(subjectId);
     return path.join(artifactRoot, "assignment", `${sanitized}.json`);
 }
+function localAssignmentDir(artifactRoot, create) {
+    const dir = path.join(artifactRoot, "assignment");
+    if (create)
+        fs.mkdirSync(dir, { recursive: true });
+    let stat;
+    try {
+        stat = fs.lstatSync(dir);
+    }
+    catch (error) {
+        if (!create && error.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, subjectId) {
-    const file = assignmentFilePath(artifactRoot, subjectId);
-    if (!fs.existsSync(file))
+    if (!localAssignmentDir(artifactRoot, false))
         return null;
+    const file = assignmentFilePath(artifactRoot, subjectId);
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch (error) {
+        if (error.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;
+    let descriptor = 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.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;
@@ -119,7 +168,7 @@ 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).
-    writeJson(assignmentFilePath(artifactRoot, subjectId), record);
+    atomicWriteJson(artifactRoot, assignmentFilePath(artifactRoot, subjectId), record);
 }
 /**
  * Synchronous busy-sleep via Atomics.wait on a throwaway SharedArrayBuffer — Node.js (unlike
@@ -133,8 +182,7 @@ function sleepSync(ms) {
     Atomics.wait(ia, 0, 0, ms);
 }
 function subjectLockDir(artifactRoot, subjectId) {
-    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`);
 }
@@ -190,12 +238,20 @@ export function withSubjectLock(artifactRoot, subjectId, body) {
             sleepSync(20);
         }
     }
+    const release = () => fs.rmSync(lockDir, { recursive: true, force: true });
+    let result;
     try {
-        return body();
+        result = body();
     }
-    finally {
-        fs.rmSync(lockDir, { recursive: true, force: true });
+    catch (error) {
+        release();
+        throw error;
+    }
+    if (result && typeof result.then === "function") {
+        return Promise.resolve(result).finally(release);
     }
+    release();
+    return result;
 }
 /**
  * The assignment ⋈ liveness join (contract doc's "assignment ⋈ liveness join" section, ADR 0021
@@ -403,6 +459,7 @@ export function performLocalClaim(artifactRoot, subjectId, actor, opts) {
             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,
@@ -474,61 +531,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);
@@ -574,6 +631,7 @@ export function performLocalSupersede(artifactRoot, subjectId, fromActor, toActo
             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,

package/build/src/cli/builder-run.js

@@ -1,35 +1,76 @@
 import { flagString, parseArgs } from "../lib/args.js";
-import { recoverBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
+import { cancelBuilderFlowSession, archiveBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "../builder-flow-runtime.js";
+const USAGE = "Usage: flow-agents builder-run <start|sync|recover|pause|resume|cancel|release-assignment|archive> --session-dir <path> [--reason <text> | --authorization-file <path>]";
 export async function main(argv) {
     const parsed = parseArgs(argv);
     const action = parsed.positionals[0];
     const sessionDir = flagString(parsed.flags, "session-dir");
+    const authorizationFile = flagString(parsed.flags, "authorization-file");
+    const reason = flagString(parsed.flags, "reason");
     const validRecoveryArguments = parsed.positionals.length === 1
         && Object.keys(parsed.flags).length === 1
         && typeof parsed.flags["session-dir"] === "string";
     if (action === "recover" && !validRecoveryArguments) {
-        console.error("Usage: flow-agents builder-run <start|sync|recover> --session-dir <path>");
+        console.error(USAGE);
         return 64;
     }
     if (!sessionDir) {
         console.error("builder-run requires --session-dir .kontourai/flow-agents/<slug>");
         return 64;
     }
-    if (action !== "start" && action !== "sync" && action !== "recover") {
-        console.error("Usage: flow-agents builder-run <start|sync|recover> --session-dir <path>");
+    if (!action || !["start", "sync", "recover", "pause", "resume", "cancel", "release-assignment", "archive"].includes(action)) {
+        console.error(USAGE);
+        return 64;
+    }
+    const agentLifecycle = action === "pause" || action === "resume" || action === "release-assignment";
+    const authorizedLifecycle = action === "cancel" || action === "archive";
+    const lifecycle = agentLifecycle || authorizedLifecycle;
+    const allowedLifecycleFlag = (name) => name === "session-dir" || (agentLifecycle ? name === "reason" : name === "authorization-file");
+    if (lifecycle && (parsed.positionals.length !== 1 || Object.keys(parsed.flags).some((name) => !allowedLifecycleFlag(name)))) {
+        console.error(USAGE);
+        return 64;
+    }
+    if (agentLifecycle && !reason) {
+        console.error(`builder-run ${action} requires --reason <text>`);
+        return 64;
+    }
+    if (authorizedLifecycle && !authorizationFile) {
+        console.error(`builder-run ${action} requires a signed --authorization-file <path>`);
+        return 64;
+    }
+    if (!lifecycle && (authorizationFile || reason)) {
+        console.error(USAGE);
         return 64;
     }
     const result = action === "start"
         ? await startBuilderFlowSession({ sessionDir })
         : action === "sync"
             ? await syncBuilderFlowSession({ sessionDir })
-            : await recoverBuilderFlowSession({ sessionDir });
+            : action === "recover"
+                ? await recoverBuilderFlowSession({ sessionDir })
+                : action === "pause"
+                    ? await pauseBuilderFlowSession({ sessionDir, reason: reason })
+                    : action === "resume"
+                        ? await resumeBuilderFlowSession({ sessionDir, reason: reason })
+                        : action === "cancel"
+                            ? await cancelBuilderFlowSession({ sessionDir, authorizationFile: authorizationFile })
+                            : action === "release-assignment"
+                                ? await releaseBuilderFlowAssignment({ sessionDir, reason: reason })
+                                : await archiveBuilderFlowSession({ sessionDir, authorizationFile: authorizationFile });
     console.log(JSON.stringify({
         run_id: result.run.runId,
         definition_id: result.run.definitionId,
         current_step: result.run.state.current_step,
         status: result.run.state.status,
         attached: result.attached,
+        ...(action === "cancel" ? {
+            assignment_released: "assignmentReleased" in result ? result.assignmentReleased : false,
+            idempotent: "idempotent" in result ? result.idempotent : false,
+        } : action === "release-assignment" ? {
+            assignment_released: "assignmentReleased" in result ? result.assignmentReleased : false,
+        } : action === "archive" ? {
+            archive_dir: "archiveDir" in result ? result.archiveDir : null,
+        } : {}),
         next_action: result.projection.next_action,
     }));
     return 0;

package/build/src/cli/workflow-artifact-cleanup-audit.js

@@ -255,6 +255,9 @@ function classifyWorkflow(slug, workflowPath) {
     if (status === "verified" && nextStatus === "done") {
         return { ...base, classification: "cleanup_candidate", reasons: ["verified workflow has next_action.status done"] };
     }
+    if (status === "canceled" && phase === "done") {
+        return { ...base, classification: "terminal_done", reasons: ["canceled workflow retains its artifacts without requiring delivery promotion"] };
+    }
     if (["delivered", "accepted", "archived"].includes(status) && phase === "done") {
         if (status !== "archived" && !hasPromotionClaim(workflowPath)) {
             return { ...base, classification: "cleanup_candidate", reasons: [`${status} workflow reached phase done without a promotion claim; ${PROMOTE_REMEDY}`] };

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

@@ -6,6 +6,7 @@ export declare const phases: string[];
 export declare const checkKinds: Set<string>;
 export declare const checkStatuses: Set<string>;
 export declare const verdicts: Set<string>;
+export declare const WORKFLOW_WRITER_CONTRACT_VERSION = "1.0";
 export declare function writeJson(file: string, payload: AnyObj): void;
 export declare function loadJson(file: string, fallback?: AnyObj): AnyObj;
 export declare function appendJsonl(file: string, payload: AnyObj): void;
@@ -195,6 +196,7 @@ export declare function writeTrustBundle(dir: string, slug: string, timestamp: s
     errors: string[];
 }>;
 export declare function sidecarBase(slug: string): AnyObj;
+export declare function currentWorkflowSessionDir(root: string): string | null;
 export declare function validateEvidenceRef(ref: AnyObj, label: string): AnyObj;
 export declare function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[];
 export declare function normalizeCheck(raw: AnyObj, allowGateClaimPrefix?: boolean, existingCheckStampById?: ReadonlyMap<string, boolean>): AnyObj;
@@ -622,3 +624,4 @@ export declare function buildGateInquiryRecords(bundle: BundleFile, blockSignal:
 export declare const LIVENESS_TERMINAL: Set<string>;
 export { buildClaimExplanation } from "./sidecar-claim-explain.js";
 export type { ClaimEvidenceItem, ClaimExplanation } from "./sidecar-claim-explain.js";
+export declare function main(argv?: string[]): Promise<number>;