@kontourai/flow-agents 3.6.0 → 3.7.0

package/build/src/builder-flow-runtime.js

@@ -1,31 +1,38 @@
 import * as fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
 import { flowAgentsPackageVersion } from "./lib/package-version.js";
 import { pinnedFlowAgentsCommand } from "./lib/pinned-cli-command.js";
-import { expectationsForGate, lifecycleRequestMatches, openGates, readJson, runDir, sha256File, } from "@kontourai/flow";
+import { expectationsForGate, lifecycleRequestMatches, openGates, } from "@kontourai/flow";
 import { assertAuthorizationUnused, loadBuilderLifecycleAuthorization, readAuthorizationConsumption, recordAuthorizationConsumed } from "./builder-lifecycle-authority.js";
 import { assignmentFilePath, performLocalReleaseUnderLock, readLocalAssignmentStatus, resolveCurrentAssignmentActor, withSubjectLock } from "./cli/assignment-provider.js";
-import { BUILDER_BUILD_FLOW_ID, BuilderBuildRunInputError, cancelBuilderBuildRun, evaluateBuilderBuildRun, loadBuilderBuildRun, pauseBuilderBuildRun, resumeBuilderBuildRun, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
+import { BUILDER_BUILD_FLOW_ID, BuilderBuildRunInputError, cancelBuilderFlowRun, evaluateBuilderFlowRun, loadBuilderFlowRun, pauseBuilderFlowRun, resumeBuilderFlowRun, startBuilderFlowRun, } from "./builder-flow-run-adapter.js";
 export async function startBuilderFlowSession(input) {
     const context = resolveSessionContext(input.sessionDir);
     const sidecarSnapshot = readSidecarSnapshot(context);
     const subject = workflowSubject(sidecarSnapshot.state);
+    const requestedFlowId = input.flowId ?? persistedFlowId(sidecarSnapshot.state) ?? BUILDER_BUILD_FLOW_ID;
     let run;
     try {
-        run = await loadBuilderBuildRun({
+        run = await loadBuilderFlowRun({
             cwd: context.projectRoot,
             runId: context.slug,
         });
+        if (run.definitionId !== requestedFlowId) {
+            throw new BuilderBuildRunInputError("flowId", `requested ${requestedFlowId} does not match the existing ${run.definitionId} run; start builder.build from a provider Work Item instead of retrying a local shape session`);
+        }
     }
     catch (error) {
         if (!isRunNotFound(error))
             throw error;
-        run = await startBuilderBuildRun({
+        run = await startBuilderFlowRun({
             cwd: context.projectRoot,
             runId: context.slug,
             subject,
+            flowId: requestedFlowId,
             params: {
                 subject,
             },
@@ -38,7 +45,7 @@ export async function syncBuilderFlowSession(input) {
     const context = resolveSessionContext(input.sessionDir);
     const sidecarSnapshot = readSidecarSnapshot(context);
     const subject = workflowSubject(sidecarSnapshot.state);
-    const run = await loadBuilderBuildRun({
+    const run = await loadBuilderFlowRun({
         cwd: context.projectRoot,
         runId: context.slug,
     });
@@ -49,7 +56,7 @@ export async function recoverBuilderFlowSession(input) {
     const context = resolveSessionContext(input.sessionDir);
     const sidecarSnapshot = readSidecarSnapshot(context);
     const subject = workflowSubject(sidecarSnapshot.state);
-    const run = await loadBuilderBuildRun({
+    const run = await loadBuilderFlowRun({
         cwd: context.projectRoot,
         runId: context.slug,
     });
@@ -64,6 +71,20 @@ export async function recoverBuilderFlowSession(input) {
         attached: false,
     };
 }
+export async function inspectBuilderFlowSession(input) {
+    const context = resolveSessionContext(input.sessionDir);
+    const sidecarSnapshot = readSidecarSnapshot(context);
+    const subject = workflowSubject(sidecarSnapshot.state);
+    const run = await loadBuilderFlowRun({ cwd: context.projectRoot, runId: context.slug });
+    assertRunSubjectBinding(run, subject);
+    return {
+        sessionDir: context.sessionDir,
+        projectRoot: context.projectRoot,
+        run,
+        projection: projectFlowRun(context, run, sidecarSnapshot.state),
+        attached: false,
+    };
+}
 export async function pauseBuilderFlowSession(input) {
     return changeBuilderFlowSessionLifecycle(input, "pause");
 }
@@ -75,7 +96,7 @@ export async function cancelBuilderFlowSession(input) {
     return await withSubjectLock(context.artifactRoot, context.slug, async () => {
         const prepared = await prepareAuthorizedLifecycleChange(input, "cancel", context);
         assertAuthorizationUnused(prepared.context.artifactRoot, prepared.authorization);
-        const changed = await cancelBuilderBuildRun({ cwd: prepared.context.projectRoot, runId: prepared.context.slug, request: prepared.authorization.request });
+        const changed = await cancelBuilderFlowRun({ cwd: prepared.context.projectRoot, runId: prepared.context.slug, request: prepared.authorization.request });
         const released = performLocalReleaseUnderLock(prepared.context.artifactRoot, prepared.context.slug, prepared.authorization.assignment_actor, {
             actorKey: prepared.authorization.assignment_actor_key,
             reason: `canonical Flow run canceled by ${prepared.authorization.request.authority.request_ref}`,
@@ -91,7 +112,7 @@ export async function releaseBuilderFlowAssignment(input) {
     const context = resolveSessionContext(input.sessionDir);
     return await withSubjectLock(context.artifactRoot, context.slug, async () => {
         const prepared = prepareAgentLifecycleChange(input, context);
-        const run = await loadBuilderBuildRun({ cwd: context.projectRoot, runId: context.slug });
+        const run = await loadBuilderFlowRun({ cwd: context.projectRoot, runId: context.slug });
         const released = performLocalReleaseUnderLock(context.artifactRoot, context.slug, prepared.actor, { actorKey: prepared.actorKey, reason: input.reason });
         return { sessionDir: context.sessionDir, projectRoot: context.projectRoot, run, projection: prepared.sidecarSnapshot.state, attached: false, assignmentReleased: released !== null };
     });
@@ -104,7 +125,7 @@ export async function archiveBuilderFlowSession(input) {
         const recoveringPreparedArchive = priorConsumption !== null && prepared.sidecarSnapshot.state.status === "archived";
         if (priorConsumption && !recoveringPreparedArchive)
             throw new Error("lifecycle authorization nonce has already been consumed");
-        const run = await loadBuilderBuildRun({ cwd: prepared.context.projectRoot, runId: prepared.context.slug });
+        const run = await loadBuilderFlowRun({ cwd: prepared.context.projectRoot, runId: prepared.context.slug });
         if (run.state.status !== "completed" && run.state.status !== "canceled") {
             throw new BuilderBuildRunInputError("flow_run.status", "must be completed or canceled before archival");
         }
@@ -145,7 +166,7 @@ async function changeBuilderFlowSessionLifecycle(input, operation) {
     const context = resolveSessionContext(input.sessionDir);
     return await withSubjectLock(context.artifactRoot, context.slug, async () => {
         const prepared = prepareAgentLifecycleChange(input, context);
-        const change = operation === "pause" ? pauseBuilderBuildRun : resumeBuilderBuildRun;
+        const change = operation === "pause" ? pauseBuilderFlowRun : resumeBuilderFlowRun;
         const at = new Date().toISOString();
         const run = await change({
             cwd: context.projectRoot,
@@ -171,7 +192,7 @@ async function prepareAuthorizedLifecycleChange(input, operation, context) {
     const persistedAssignment = pathExistsNoFollow(assignmentFile)
         ? (assertSafeFile(assignmentFile, context.artifactRoot, "assignment record"), JSON.parse(fs.readFileSync(assignmentFile, "utf8")))
         : null;
-    const canonicalRun = await loadBuilderBuildRun({ cwd: context.projectRoot, runId: context.slug });
+    const canonicalRun = await loadBuilderFlowRun({ cwd: context.projectRoot, runId: context.slug });
     const acceptsReleasedAssignment = (operation === "cancel" && canonicalRun.state.status === "canceled") || operation === "archive";
     const assignment = activeAssignment ?? (acceptsReleasedAssignment && persistedAssignment?.status === "released" ? persistedAssignment : null);
     if (!assignment || (assignment.status !== "claimed" && !acceptsReleasedAssignment) || !assignment.actor_key) {
@@ -245,20 +266,6 @@ function clearCurrentPointers(artifactRoot, slug) {
             fs.unlinkSync(file);
     }
 }
-export async function syncBuilderFlowSessionIfPresent(sessionDir) {
-    let context;
-    try {
-        context = resolveSessionContext(sessionDir);
-    }
-    catch (error) {
-        if (error instanceof BuilderBuildRunInputError && error.field === "sessionDir")
-            return null;
-        throw error;
-    }
-    if (!fs.existsSync(runDir(context.slug, context.projectRoot)))
-        return null;
-    return syncBuilderFlowSession({ sessionDir });
-}
 async function syncAndProject(context, initial, sidecarSnapshot) {
     let run = initial;
     let attached = false;
@@ -267,25 +274,35 @@ async function syncAndProject(context, initial, sidecarSnapshot) {
         throw new BuilderBuildRunInputError("flow_run.open_gates", `expected exactly one gate for active step ${run.state.current_step}, found ${gates.length}`);
     }
     if (gates.length === 1 && fs.existsSync(context.bundleFile)) {
-        const rawBundle = await readJson(context.bundleFile);
-        const gateEvidence = bundleGateEvidence(rawBundle, gates[0], run.state.subject);
-        if (gateEvidence) {
-            const digest = await sha256File(context.bundleFile);
-            const alreadyAttached = manifestEvidence(run.manifest).some((entry) => entry.gate_id === gates[0].id && entry.sha256 === digest);
-            if (!alreadyAttached) {
-                run = await evaluateBuilderBuildRun({
-                    cwd: context.projectRoot,
-                    runId: context.slug,
-                    evidence: {
-                        gate: gates[0].id,
-                        file: path.relative(context.projectRoot, context.bundleFile),
-                        ...(gateEvidence.failed ? { status: "failed" } : {}),
-                        ...(gateEvidence.routeReason ? { routeReason: gateEvidence.routeReason } : {}),
-                    },
-                });
-                attached = true;
+        const snapshot = stageTrustBundleSnapshot(context);
+        try {
+            const rawBundle = JSON.parse(snapshot.raw.toString("utf8"));
+            const gateEvidence = await bundleGateEvidence(rawBundle, gates[0], run.state.subject, context.projectRoot);
+            if (gateEvidence) {
+                const alreadyAttached = manifestEvidence(run.manifest).some((entry) => entry.gate_id === gates[0].id && entry.sha256 === snapshot.sha256);
+                if (!alreadyAttached) {
+                    const supersede = manifestEvidence(run.manifest)
+                        .filter((entry) => entry.gate_id === gates[0].id && typeof entry.superseded_by !== "string")
+                        .map((entry) => String(entry.id));
+                    run = await evaluateBuilderFlowRun({
+                        cwd: context.projectRoot,
+                        runId: context.slug,
+                        evidence: {
+                            gate: gates[0].id,
+                            file: path.relative(context.projectRoot, snapshot.file),
+                            expectedSha256: snapshot.sha256,
+                            ...(supersede.length > 0 ? { supersede } : {}),
+                            ...(gateEvidence.failed ? { status: "failed" } : {}),
+                            ...(gateEvidence.routeReason ? { routeReason: gateEvidence.routeReason } : {}),
+                        },
+                    });
+                    attached = true;
+                }
             }
         }
+        finally {
+            removeTrustBundleSnapshot(snapshot);
+        }
     }
     const projection = projectFlowRun(context, run, sidecarSnapshot.state);
     writeProjection(context, projection, sidecarSnapshot.raw, "projection");
@@ -352,10 +369,15 @@ function workflowSubject(state) {
     }
     return refs[0];
 }
+function persistedFlowId(state) {
+    const flowRun = isRecord(state.flow_run) ? state.flow_run : null;
+    const flowId = flowRun?.definition_id;
+    return flowId === "builder.build" || flowId === "builder.shape" ? flowId : null;
+}
 function openGatesForResult(run) {
     return openGates(JSON.parse(fs.readFileSync(path.join(run.dir, "definition.json"), "utf8")), run.state);
 }
-function bundleGateEvidence(bundle, gate, subject) {
+async function bundleGateEvidence(bundle, gate, subject, projectRoot) {
     if (!isRecord(bundle) || !Array.isArray(bundle.claims))
         return null;
     const selectors = expectationsForGate(gate).map((expectation) => expectation.bundle_claim);
@@ -387,8 +409,247 @@ function bundleGateEvidence(bundle, gate, subject) {
     if (routeReason && (!routeMap || typeof routeMap[routeReason] !== "string")) {
         throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", `is not declared by gate ${String(gate.id ?? "<unknown>")}`);
     }
+    if (String(gate.id) === "verify-gate" && relevant.some((claim) => claim.claimType === "builder.verify.tests" && claim.value === "pass")) {
+        await assertVerifiedTestsTrust(bundle.claims, projectRoot);
+    }
     return { failed, routeReason };
 }
+async function assertVerifiedTestsTrust(claims, projectRoot) {
+    const testClaims = claims.filter((claim) => isRecord(claim)
+        && claim.claimType === "builder.verify.tests"
+        && claim.value === "pass"
+        && isRecord(claim.metadata)
+        && isRecord(claim.metadata.gate_claim)
+        && claim.metadata.gate_claim.expectation_id === "tests-evidence");
+    if (testClaims.length === 0)
+        throw new BuilderBuildRunInputError("evidence.tests", "is missing a passing tests-evidence claim");
+    const liveCritiques = claims.filter((claim) => isRecord(claim)
+        && isRecord(claim.metadata)
+        && claim.metadata.origin === "critique"
+        && typeof claim.metadata.superseded_by !== "string");
+    if (liveCritiques.length === 0 || liveCritiques.some((claim) => !isSubstantivePassingCritique(claim))) {
+        throw new BuilderBuildRunInputError("evidence.critique", "a passing tests-evidence claim requires a current clean critique");
+    }
+    const implementationActors = new Set(testClaims.map((claim) => claim.metadata.recorded_by).filter((actor) => typeof actor === "string" && actor.length > 0));
+    if (implementationActors.size !== 1 || liveCritiques.some((claim) => typeof claim.metadata.reviewer !== "string" || implementationActors.has(claim.metadata.reviewer))) {
+        throw new BuilderBuildRunInputError("evidence.critique.reviewer", "must identify a reviewer distinct from the tests-evidence implementation actor");
+    }
+    await Promise.all(liveCritiques.flatMap(async (claim) => {
+        const artifacts = reviewedArtifacts(claim);
+        await Promise.all(artifacts.map((artifact) => assertReviewedArtifactDigest(artifact, projectRoot)));
+        assertReviewedWorkspaceSnapshot(claim, artifacts, projectRoot);
+    }));
+    const criteria = claims.filter((claim) => isRecord(claim) && isRecord(claim.metadata) && claim.metadata.origin === "acceptance");
+    if (criteria.length === 0 || criteria.some((claim) => {
+        const criterion = isRecord(claim.metadata.criterion) ? claim.metadata.criterion : null;
+        return claim.value !== "pass" || !criterion || !Array.isArray(criterion.evidence_refs) || criterion.evidence_refs.length === 0;
+    })) {
+        throw new BuilderBuildRunInputError("evidence.acceptance", "a passing tests-evidence claim requires complete verified acceptance criteria");
+    }
+    for (const testClaim of testClaims)
+        assertObservedTestsEvidence(testClaim, criteria);
+}
+function assertObservedTestsEvidence(testClaim, criteria) {
+    const observed = testClaim.metadata.observed_commands;
+    if (!Array.isArray(observed) || observed.length === 0) {
+        throw new BuilderBuildRunInputError("evidence.tests.observed_commands", "must contain successful command observations");
+    }
+    const commands = new Set();
+    for (const entry of observed) {
+        if (!isRecord(entry) || typeof entry.command !== "string" || entry.exit_code !== 0 || !Number.isSafeInteger(entry.test_count) || Number(entry.test_count) <= 0 || typeof entry.output_sha256 !== "string" || !/^[a-f0-9]{64}$/i.test(entry.output_sha256) || commands.has(entry.command)) {
+            throw new BuilderBuildRunInputError("evidence.tests.observed_commands", "must contain unique commands with exit_code 0, a positive executed-test count, and SHA-256 output digests");
+        }
+        commands.add(entry.command);
+    }
+    const topRefs = Array.isArray(testClaim.metadata.artifact_refs) ? testClaim.metadata.artifact_refs : [];
+    const topCommands = new Set(topRefs.flatMap((ref) => isRecord(ref) && ref.kind === "command" && typeof ref.excerpt === "string" ? [ref.excerpt.trim()] : []));
+    if ([...commands].some((command) => !topCommands.has(command))) {
+        throw new BuilderBuildRunInputError("evidence.tests.artifact_refs", "must reference every successful observed command exactly");
+    }
+    const criterionCommands = new Set();
+    for (const claim of criteria) {
+        const criterion = claim.metadata.criterion;
+        const refs = Array.isArray(criterion.evidence_refs) ? criterion.evidence_refs : [];
+        const matched = refs.flatMap((ref) => isRecord(ref) && ref.kind === "command" && typeof ref.excerpt === "string" && commands.has(ref.excerpt.trim()) ? [ref.excerpt.trim()] : []);
+        if (matched.length === 0)
+            throw new BuilderBuildRunInputError("evidence.acceptance.evidence_refs", `criterion ${String(criterion.id ?? claim.id)} must reference a successful observed command`);
+        matched.forEach((command) => criterionCommands.add(command));
+    }
+    if ([...commands].some((command) => !criterionCommands.has(command))) {
+        throw new BuilderBuildRunInputError("evidence.acceptance.evidence_refs", "must bind every successful observed command to at least one criterion");
+    }
+}
+function isSubstantivePassingCritique(claim) {
+    if (claim.value !== "pass" || (Array.isArray(claim.metadata.findings) && claim.metadata.findings.some((finding) => isRecord(finding) && finding.status === "open")))
+        return false;
+    const lanes = claim.metadata.lanes;
+    return Array.isArray(lanes)
+        && lanes.length > 0
+        && lanes.every((lane) => isRecord(lane) && (lane.status === "pass" || lane.verdict === "pass"))
+        && reviewedArtifacts(claim).length > 0;
+}
+function reviewedArtifacts(claim) {
+    const reviewTarget = isRecord(claim.metadata.review_target) ? claim.metadata.review_target : null;
+    const artifacts = reviewTarget?.artifacts;
+    if (!Array.isArray(artifacts) || artifacts.length === 0)
+        return [];
+    if (!artifacts.every((artifact) => isRecord(artifact) && typeof artifact.file === "string" && typeof artifact.sha256 === "string" && /^[a-f0-9]{64}$/i.test(artifact.sha256)))
+        return [];
+    return artifacts;
+}
+function assertReviewedWorkspaceSnapshot(claim, artifacts, projectRoot) {
+    const reviewTarget = isRecord(claim.metadata.review_target) ? claim.metadata.review_target : null;
+    const expected = reviewTarget?.workspace_snapshot;
+    if (!isRecord(expected)) {
+        throw new BuilderBuildRunInputError("evidence.critique.review_target.workspace_snapshot", "is required for a passing critique");
+    }
+    const current = captureReviewWorkspaceSnapshot(projectRoot, expected.kind === "reviewed-files"
+        ? reviewedWorkspaceFiles(expected)
+        : artifacts.map((artifact) => ({ file: artifact.file, sha256: artifact.sha256 })));
+    if (expected.version !== current.version || expected.kind !== current.kind || expected.algorithm !== current.algorithm) {
+        throw new BuilderBuildRunInputError("evidence.critique.review_target.workspace_snapshot", "does not match the current workspace snapshot strategy");
+    }
+    if (expected.digest !== current.digest) {
+        throw new BuilderBuildRunInputError("evidence.critique.review_target.workspace_snapshot.digest", "does not match the current implementation workspace");
+    }
+    if (current.kind === "git-worktree" && expected.head_sha !== current.head_sha) {
+        throw new BuilderBuildRunInputError("evidence.critique.review_target.workspace_snapshot.head_sha", "does not match the current Git HEAD");
+    }
+    if (current.kind === "reviewed-files" && !isDeepStrictEqual(expected.files, current.files)) {
+        throw new BuilderBuildRunInputError("evidence.critique.review_target.workspace_snapshot.files", "does not match the explicitly reviewed files");
+    }
+}
+function gitWorktreeSnapshot(projectRoot) {
+    const root = fs.realpathSync(projectRoot);
+    const hasGitMarker = fs.existsSync(path.join(root, ".git"));
+    try {
+        const gitRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        if (!gitRoot || fs.realpathSync(gitRoot) !== root) {
+            throw new BuilderBuildRunInputError("evidence.critique.review_target.workspace_snapshot", "requires the canonical project root to match the Git worktree root");
+        }
+        const headSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        const trackedDiff = execFileSync("git", ["diff", "--binary", "--no-ext-diff", "HEAD", "--"], { cwd: root, encoding: "buffer", stdio: ["ignore", "pipe", "ignore"] });
+        const untracked = execFileSync("git", ["ls-files", "--others", "--exclude-standard", "-z"], { cwd: root, encoding: "buffer", stdio: ["ignore", "pipe", "ignore"] })
+            .toString("utf8").split("\0").filter(Boolean).sort();
+        const hash = createHash("sha256");
+        hash.update("flow-agents:git-worktree:v1\0");
+        hash.update(headSha).update("\0");
+        hash.update(trackedDiff).update("\0");
+        for (const file of untracked) {
+            const absolute = path.resolve(root, file);
+            if (!pathIsWithin(absolute, root))
+                throw new Error("untracked file escapes repository root");
+            const stat = fs.lstatSync(absolute);
+            if (!stat.isFile() || stat.isSymbolicLink())
+                throw new Error("untracked entry is not a regular file");
+            hash.update(file).update("\0").update(fs.readFileSync(absolute)).update("\0");
+        }
+        return { version: 1, kind: "git-worktree", algorithm: "sha256", digest: hash.digest("hex"), head_sha: headSha };
+    }
+    catch (error) {
+        if (hasGitMarker || error instanceof BuilderBuildRunInputError) {
+            if (error instanceof BuilderBuildRunInputError)
+                throw error;
+            throw new BuilderBuildRunInputError("evidence.critique.review_target.workspace_snapshot", `could not inspect the Git worktree: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return null;
+    }
+}
+export function captureReviewWorkspaceSnapshot(projectRoot, reviewedFiles) {
+    return gitWorktreeSnapshot(projectRoot) ?? reviewedFilesSnapshot(projectRoot, reviewedFiles);
+}
+function reviewedWorkspaceFiles(snapshot) {
+    if (!Array.isArray(snapshot.files) || snapshot.files.length === 0
+        || !snapshot.files.every((file) => isRecord(file) && typeof file.file === "string" && /^[a-f0-9]{64}$/i.test(String(file.sha256)))) {
+        throw new BuilderBuildRunInputError("evidence.critique.review_target.workspace_snapshot.files", "must list explicitly reviewed files with SHA-256 digests");
+    }
+    const files = snapshot.files.map((file) => ({ file: file.file, sha256: file.sha256 })).sort((left, right) => left.file.localeCompare(right.file));
+    if (new Set(files.map((file) => file.file)).size !== files.length) {
+        throw new BuilderBuildRunInputError("evidence.critique.review_target.workspace_snapshot.files", "must not contain duplicate files");
+    }
+    return files;
+}
+function reviewedFilesSnapshot(projectRoot, reviewedFiles) {
+    const files = reviewedFiles.map((file) => ({ ...file }));
+    const hash = createHash("sha256");
+    hash.update("flow-agents:reviewed-files:v1\0");
+    for (const artifact of files) {
+        const absolute = safeReviewedArtifactPath(projectRoot, artifact.file);
+        hash.update(artifact.file).update("\0").update(fs.readFileSync(absolute)).update("\0");
+    }
+    return { version: 1, kind: "reviewed-files", algorithm: "sha256", digest: hash.digest("hex"), files };
+}
+async function assertReviewedArtifactDigest(artifact, projectRoot) {
+    const canonicalArtifact = safeReviewedArtifactPath(projectRoot, artifact.file);
+    if (createHash("sha256").update(fs.readFileSync(canonicalArtifact)).digest("hex") !== artifact.sha256) {
+        throw new BuilderBuildRunInputError("evidence.critique.review_target.artifacts.sha256", `does not match ${artifact.file}`);
+    }
+}
+function safeReviewedArtifactPath(projectRoot, file) {
+    const canonicalRoot = fs.realpathSync(projectRoot);
+    const candidate = path.resolve(canonicalRoot, file);
+    const relative = path.relative(canonicalRoot, candidate);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new BuilderBuildRunInputError("evidence.critique.review_target.artifacts.file", "must resolve within the canonical project root");
+    }
+    let canonicalArtifact;
+    try {
+        canonicalArtifact = fs.realpathSync(candidate);
+    }
+    catch {
+        throw new BuilderBuildRunInputError("evidence.critique.review_target.artifacts.file", `is missing: ${file}`);
+    }
+    const canonicalRelative = path.relative(canonicalRoot, canonicalArtifact);
+    if (canonicalRelative === ".." || canonicalRelative.startsWith(`..${path.sep}`) || path.isAbsolute(canonicalRelative) || !fs.statSync(canonicalArtifact).isFile()) {
+        throw new BuilderBuildRunInputError("evidence.critique.review_target.artifacts.file", "must be a regular file within the canonical project root");
+    }
+    return canonicalArtifact;
+}
+function stageTrustBundleSnapshot(context) {
+    assertSafeFile(context.bundleFile, context.sessionDir, "trust.bundle");
+    const source = fs.openSync(context.bundleFile, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    let raw;
+    try {
+        const stat = fs.fstatSync(source);
+        if (!stat.isFile())
+            throw new BuilderBuildRunInputError("trust.bundle", "must be a regular file");
+        raw = fs.readFileSync(source);
+    }
+    finally {
+        fs.closeSync(source);
+    }
+    const directory = path.join(context.sessionDir, ".trust-bundle-snapshots");
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    assertSafeDirectory(directory, context.sessionDir, "trust.bundle snapshot directory");
+    fs.chmodSync(directory, 0o700);
+    const file = path.join(directory, `${randomBytes(16).toString("hex")}.json`);
+    const descriptor = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+        fs.writeFileSync(descriptor, raw);
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    fs.chmodSync(file, 0o400);
+    return { file, raw, sha256: createHash("sha256").update(raw).digest("hex") };
+}
+function removeTrustBundleSnapshot(snapshot) {
+    try {
+        fs.unlinkSync(snapshot.file);
+    }
+    catch (error) {
+        if (!isRecord(error) || error.code !== "ENOENT")
+            throw error;
+    }
+    try {
+        fs.rmdirSync(path.dirname(snapshot.file));
+    }
+    catch (error) {
+        if (!isRecord(error) || (error.code !== "ENOENT" && error.code !== "ENOTEMPTY"))
+            throw error;
+    }
+}
 function workflowSubjectRef(claim) {
     const metadata = isRecord(claim.metadata) ? claim.metadata : null;
     return metadata && typeof metadata.workflow_subject_ref === "string"
@@ -404,7 +665,7 @@ function projectFlowRun(context, run, sidecar) {
     const complete = run.state.status === "completed";
     const paused = run.state.status === "paused";
     const canceled = run.state.status === "canceled";
-    const action = complete || paused || canceled ? { skills: [], operations: [] } : stepAction(run.state.current_step);
+    const action = complete || paused || canceled ? { skills: [], operations: [] } : stepAction(run.definitionId, run.state.current_step);
     if (!action) {
         throw new BuilderBuildRunInputError("kit.flow_step_actions", `does not declare Builder step ${run.state.current_step}`);
     }
@@ -505,7 +766,7 @@ function prepareProjectionWrites(context, projection, expectedStateRaw, operatio
             continue;
         const output = {
             ...pointer,
-            active_flow_id: BUILDER_BUILD_FLOW_ID,
+            active_flow_id: projection.flow_run.definition_id,
             active_step_id: projection.flow_run.current_step,
             updated_at: projection.updated_at,
         };
@@ -602,11 +863,11 @@ function writeExistingFileNoFollow(file, content) {
         fs.closeSync(descriptor);
     }
 }
-function stepAction(stepId) {
+function stepAction(flowId, stepId) {
     const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot(), "kits", "builder", "kit.json"), "utf8"));
     const actions = Array.isArray(manifest.flow_step_actions) ? manifest.flow_step_actions : [];
     const action = actions.find((candidate) => isRecord(candidate)
-        && candidate.flow_id === BUILDER_BUILD_FLOW_ID
+        && candidate.flow_id === flowId
         && candidate.step_id === stepId);
     if (!isRecord(action) || !Array.isArray(action.skills) || !action.skills.every((skill) => typeof skill === "string")) {
         return null;

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

@@ -66,13 +66,10 @@ export declare function writeLocalRecord(artifactRoot: string, subjectId: string
  * 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,

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