@kontourai/flow-agents 3.6.0 → 3.8.0

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";
@@ -186,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,
@@ -208,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) {
@@ -238,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();
@@ -248,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
@@ -572,7 +626,19 @@ export function performLocalReleaseUnderLock(artifactRoot, subjectId, releasedBy
         // 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/build/src/cli/builder-run.js

@@ -1,6 +1,6 @@
 import { flagString, parseArgs } from "../lib/args.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>]";
+import { cancelBuilderFlowSession, archiveBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, } from "../builder-flow-runtime.js";
+const USAGE = "Usage: flow-agents builder-run <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];
@@ -18,7 +18,7 @@ export async function main(argv) {
         console.error("builder-run requires --session-dir .kontourai/flow-agents/<slug>");
         return 64;
     }
-    if (!action || !["start", "sync", "recover", "pause", "resume", "cancel", "release-assignment", "archive"].includes(action)) {
+    if (!action || !["recover", "pause", "resume", "cancel", "release-assignment", "archive"].includes(action)) {
         console.error(USAGE);
         return 64;
     }
@@ -42,21 +42,17 @@ export async function main(argv) {
         console.error(USAGE);
         return 64;
     }
-    const result = action === "start"
-        ? await startBuilderFlowSession({ sessionDir })
-        : action === "sync"
-            ? await syncBuilderFlowSession({ 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 });
+    const result = 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,

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

@@ -174,10 +174,13 @@ export declare function reduceCaptureLogByCommand(commandLog: AnyObj[] | undefin
  * @param timestamp  ISO-8601 timestamp for createdAt / updatedAt / observedAt
  * @param checks     Normalized check objects (from record-evidence --check-json / --surface-trust-json)
  * @param criteria   Acceptance criteria objects (from acceptance.json .criteria array)
- * @param critiques  Critique objects (from critique.json .critiques array)
+ * @param critiques  Critique objects reconstructed from trust.bundle claims
  * @param commandLog Optional parsed command-log.jsonl entries (capture-authoritative fold)
  */
-export declare function buildTrustBundle(slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], commandLog?: AnyObj[], flowAgentsDir?: string, actorKey?: string): Promise<AnyObj | null>;
+export declare function buildTrustBundle(slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], commandLog?: AnyObj[], flowAgentsDir?: string, actorKey?: string, exactFlowContext?: {
+    flowId: string;
+    stepId: string;
+}): Promise<AnyObj | null>;
 /**
  * Fail-open wrapper: builds (via Surface), validates, and writes a trust.bundle.
  * Accepts raw check/criterion/critique inputs directly (ADR 0010 Phase 4a).
@@ -191,7 +194,10 @@ export declare function buildTrustBundle(slug: string, timestamp: string, checks
  * @param criteria   Acceptance criteria objects (same as buildTrustBundle)
  * @param critiques  Critique objects (same as buildTrustBundle)
  */
-export declare function writeTrustBundle(dir: string, slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], actorKey?: string): Promise<{
+export declare function writeTrustBundle(dir: string, slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], actorKey?: string, exactFlowContext?: {
+    flowId: string;
+    stepId: string;
+}): Promise<{
     written: boolean;
     errors: string[];
 }>;
@@ -199,6 +205,23 @@ 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[];
+/** Validate test-evidence command shape without executing it. */
+type TestExecutionProof = {
+    kind: "local-process-exit";
+    runner: string;
+    static_test_units: number;
+};
+/**
+ * Produce evidence from the locally executed command and statically reviewable
+ * test units. Runner stdout is deliberately excluded: any executable can print
+ * a Vitest/Jest-looking success summary, but it cannot turn a non-test script
+ * into a supported test workflow or supply this locally-created proof.
+ */
+export declare function testExecutionProof(command: string, projectRoot: string, seenScripts?: Set<string>, packageScriptBody?: boolean): TestExecutionProof | null;
+/** Validate test-evidence command shape without executing it. */
+export declare function isMeaningfulTestCommand(command: string, projectRoot: string, seenScripts?: Set<string>, packageScriptBody?: boolean): boolean;
+export declare function observedExecutedTestCount(output: string): number;
+export declare function inferExecutedTestCount(command: string, projectRoot: string, output: string, seenScripts?: Set<string>): number;
 export declare function normalizeCheck(raw: AnyObj, allowGateClaimPrefix?: boolean, existingCheckStampById?: ReadonlyMap<string, boolean>): AnyObj;
 /**
  * Derive kit identity from a parsed trust.bundle by structurally reading the
@@ -624,4 +647,5 @@ 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>;
+export declare function mainFromPublicWorkflow(argv: string[]): Promise<number>;
+export declare function main(argv?: string[], authority?: symbol): Promise<number>;