@kontourai/flow-agents 3.8.0 → 3.10.0

package/src/cli/assignment-provider.ts

@@ -1,5 +1,4 @@
 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";
@@ -118,25 +117,19 @@ const CLAIM_COMMENT_MARKER_DEFAULT = "<!-- flow-agents:assignment-claim -->";
  */
 function loadActorIdentityHelper(): {
   resolveActor: (env: NodeJS.ProcessEnv) => { actor: string; source: string };
+  resolveActorIdentity: (env: NodeJS.ProcessEnv) => { actor: string; source: string; actorStruct: ActorStruct | null };
   serializeActor: (actor: Partial<ActorStruct> | undefined) => string;
   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);
   const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/actor-identity.js");
   return _req(helperPath) as {
     resolveActor: (env: NodeJS.ProcessEnv) => { actor: string; source: string };
+    resolveActorIdentity: (env: NodeJS.ProcessEnv) => { actor: string; source: string; actorStruct: ActorStruct | null };
     serializeActor: (actor: Partial<ActorStruct> | undefined) => string;
     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;
   };
 }
 
@@ -209,24 +202,10 @@ function loadActorStruct(args: ParsedArgs): { actor: ActorStruct; actorKey?: str
 
 export function resolveCurrentAssignmentActor(): { actor: ActorStruct; actorKey: string } {
   const helper = loadActorIdentityHelper();
-  const resolved = helper.resolveActor(process.env);
+  const resolved = helper.resolveActorIdentity(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");
-  // #398: reconstruct the SAME struct resolveActor serialized for a CI actor, mirroring
-  // resolveEnsureSessionActor (workflow-sidecar.ts) via the shared detectCiActor. Without this the
-  // else-branch would write `record.actor = {runtime:"unknown", session_id:<the whole triple>}` for a
-  // 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 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 };
+  if (!resolved.actorStruct) throw new Error("actor identity resolved without a canonical actor struct");
+  return { actor: { ...resolved.actorStruct, human: resolved.actorStruct.human ?? null }, actorKey: resolved.actor };
 }
 
 export function assignmentFilePath(artifactRoot: string, subjectId: string): string {

package/src/cli/builder-flow-runtime.test.mjs

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { createHash, generateKeyPairSync, sign } from "node:crypto";
+import { spawnSync } from "node:child_process";
 
 import { FLOW_RUN_EVIDENCE_MANIFEST_PATH, runDir } from "@kontourai/flow";
 import {
@@ -18,9 +19,11 @@ import {
   syncBuilderFlowSession,
 } from "../../build/src/builder-flow-runtime.js";
 import { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization, recordAuthorizationConsumed } from "../../build/src/builder-lifecycle-authority.js";
+import { driveBuilderFlowSession } from "../../build/src/continuation-driver.js";
 import { cancelBuilderBuildRun } from "../../build/src/builder-flow-run-adapter.js";
 import { performLocalClaim, performLocalRelease, readLocalAssignmentStatus, resolveCurrentAssignmentActor } from "../../build/src/cli/assignment-provider.js";
 import { main as builderRunMain } from "../../build/src/cli/builder-run.js";
+import { main as workflowMain } from "../../build/src/cli/workflow.js";
 import { buildTrustBundle, inferExecutedTestCount, main as workflowSidecarMain } from "../../build/src/cli/workflow-sidecar.js";
 
 const SUBJECT = "local:work-item/runtime-projection";
@@ -30,6 +33,20 @@ const ACTOR = { runtime: "codex", session_id: "runtime-projection", host: "test-
 const ACTOR_KEY = "codex:runtime-projection:test-host";
 const AUTHORITY_KEY_ID = "runtime-test";
 const AUTHORITY_KEYS = generateKeyPairSync("ed25519");
+const AMBIENT_IDENTITY_ENV_KEYS = [
+  "FLOW_AGENTS_ACTOR",
+  "CODEX_THREAD_ID",
+  "CODEX_SESSION_ID",
+  "CLAUDE_CODE_SESSION_ID",
+  "OPENCODE_SESSION_ID",
+  "PI_SESSION_ID",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "CIRCLECI",
+  "JENKINS_URL",
+  "TF_BUILD",
+  "BUILDKITE",
+];
 
 function makeSession(slug = "runtime-projection") {
   const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-builder-runtime-"));
@@ -88,7 +105,7 @@ function claimSessionAssignment(session) {
     ttlSeconds: 1800,
     actorKey: ACTOR_KEY,
     branch: `agent/${session.slug}`,
-    artifactDir: session.sessionDir,
+    artifactDir: session.slug,
     workItemRef: SUBJECT,
     reason: "test",
   });
@@ -100,7 +117,7 @@ function claimAmbientSessionAssignment(session) {
     ttlSeconds: 1800,
     actorKey: ambient.actorKey,
     branch: `agent/${session.slug}`,
-    artifactDir: session.sessionDir,
+    artifactDir: session.slug,
     workItemRef: SUBJECT,
     reason: "test",
   });
@@ -365,6 +382,202 @@ test("small-model client can start and advance from projected actions without ch
   assert.equal(duplicate.run.manifest.evidence.length, advanced.run.manifest.evidence.length);
 });
 
+test("Builder projection preserves Flow continuation semantics for exceptional statuses", async () => {
+  const session = makeSession("continuation-status-projection");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const stateFile = path.join(runDir(session.slug, session.projectRoot), "state.json");
+  const original = readJson(stateFile);
+  for (const [status, expected] of [
+    ["blocked", "continue"],
+    ["accepted_by_exception", "continue"],
+    ["needs_decision", "blocked"],
+    ["failed", "failed"],
+  ]) {
+    writeJson(stateFile, { ...original, status, next_action: `fixture ${status}` });
+    const recovered = await recoverBuilderFlowSession({ sessionDir: session.sessionDir });
+    assert.equal(recovered.projection.next_action.status, expected, status);
+  }
+});
+
+test("continuation driver advances two real FlowDefinition steps unattended", async () => {
+  const session = makeSession("continuation-driver-two-steps");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const visited = [];
+
+  const result = await driveBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    maxTurns: 2,
+    execute: async (request) => {
+      visited.push(request.current_step);
+      if (request.current_step === "pull-work") {
+        writeBundle(session.sessionDir, [bundleClaim({
+          expectation: "selected-work",
+          claimType: "builder.pull-work.selected",
+          subjectType: "work-item",
+        })]);
+      } else if (request.current_step === "design-probe") {
+        writeBundle(session.sessionDir, [
+          bundleClaim({
+            expectation: "pickup-probe-readiness",
+            claimType: "builder.design-probe.pickup-readiness",
+            subjectType: "work-item",
+          }),
+          bundleClaim({
+            expectation: "probe-decisions-or-accepted-gaps",
+            claimType: "builder.design-probe.decisions",
+            subjectType: "decision",
+          }),
+        ]);
+      } else {
+        assert.fail(`unexpected continuation step ${request.current_step}`);
+      }
+      return { status: "completed", summary: `completed ${request.current_step}` };
+    },
+  });
+
+  assert.equal(result.outcome, "budget_exhausted");
+  assert.equal(result.turns_started, 2);
+  assert.deepEqual(visited, ["pull-work", "design-probe"]);
+  assert.equal(result.snapshot.current_step, "plan");
+  assert.equal(result.snapshot.next_action.skills[0], "plan-work");
+  const driverState = readJson(path.join(session.sessionDir, "continuation-driver", "state.json"));
+  assert.equal(driverState.status, "budget_exhausted");
+  assert.equal(driverState.turns_started, 2);
+  const events = fs.readFileSync(path.join(session.sessionDir, "continuation-driver", "events.jsonl"), "utf8").trim().split("\n").map(JSON.parse);
+  assert.deepEqual(events.filter((event) => event.type === "turn_started").map((event) => event.current_step), ["pull-work", "design-probe"]);
+});
+
+test("public workflow evidence accepts only live signed turn authority after ordinary ancestry resolution mismatches", async () => {
+  const session = makeSession("continuation-driver-cli");
+  claimAmbientSessionAssignment(session);
+  fs.writeFileSync(path.join(session.projectRoot, "AGENTS.md"), "# Test Repo\n");
+  fs.writeFileSync(path.join(session.sessionDir, `${session.slug}--deliver.md`), "# Continuation\n\nstatus: executing\ntype: deliver\n");
+  fs.writeFileSync(path.join(session.sessionDir, `${session.slug}--pull-work.md`), "# Pull Work\n\nSelected continuation fixture.\n");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const unrelatedSlug = "unrelated-pointer-session";
+  const unrelatedDir = path.join(session.artifactRoot, unrelatedSlug);
+  fs.mkdirSync(unrelatedDir, { recursive: true });
+  fs.writeFileSync(path.join(unrelatedDir, `${unrelatedSlug}--deliver.md`), "# Unrelated\n\nstatus: executing\ntype: deliver\n");
+  writeJson(path.join(unrelatedDir, "state.json"), {
+    schema_version: "1.0", task_slug: unrelatedSlug, status: "executing", phase: "execution",
+    updated_at: new Date().toISOString(), next_action: { status: "continue", summary: "Unrelated work" },
+  });
+  writeJson(path.join(session.artifactRoot, "current.json"), { active_slug: unrelatedSlug, artifact_dir: unrelatedSlug });
+  const adapter = path.join(session.projectRoot, "adapter.mjs");
+  const commandFile = path.join(session.projectRoot, "adapter-command.json");
+  const authorityFile = path.join(session.sessionDir, "continuation-driver", "active-turn.json");
+  fs.writeFileSync(adapter, `
+    import fs from "node:fs";
+    import { spawnSync } from "node:child_process";
+    let input = "";
+    for await (const chunk of process.stdin) input += chunk;
+    const request = JSON.parse(input);
+    fs.writeFileSync("adapter-request.json", input);
+    const evidenceEnv = { ...process.env };
+    for (const key of ${JSON.stringify(AMBIENT_IDENTITY_ENV_KEYS)}) delete evidenceEnv[key];
+    const ordinaryChild = ${JSON.stringify(path.resolve(import.meta.dirname, "../../scripts/hooks/lib/actor-identity.js"))};
+    const childIdentity = (await import("node:module")).createRequire(import.meta.url)(ordinaryChild).resolveActorIdentity(evidenceEnv);
+    const record = (expectation) => {
+      const evidence = { kind: "artifact", file: ${JSON.stringify(`.kontourai/flow-agents/${session.slug}/${session.slug}--pull-work.md`)}, summary: "adapter child records " + expectation };
+      return spawnSync(process.execPath, [${JSON.stringify(path.resolve(import.meta.dirname, "../../build/src/cli.js"))}, "workflow", "evidence", "--session-dir", ${JSON.stringify(session.sessionDir)}, "--expectation", expectation, "--status", "pass", "--summary", "adapter child records " + expectation, "--evidence-ref-json", JSON.stringify(evidence), "--json"], { cwd: ${JSON.stringify(session.projectRoot)}, encoding: "utf8", env: evidenceEnv });
+    };
+    const evidenceRuns = request.current_step === "pull-work"
+      ? [record("selected-work")]
+      : [record("pickup-probe-readiness"), record("probe-decisions-or-accepted-gaps")];
+    if (evidenceRuns.some((result) => result.status !== 0)) {
+      fs.writeFileSync("adapter-evidence-error.json", JSON.stringify(evidenceRuns.map((result) => ({ status: result.status, stderr: result.stderr, stdout: result.stdout }))));
+      throw new Error("public workflow evidence rejected signed adapter authority: " + evidenceRuns.map((result) => result.stderr).join("\\n"));
+    }
+    const lifecycleRuns = [
+      ["pause", "--reason", "capability must not pause"],
+      ["resume"],
+      ["release", "--reason", "capability must not release"],
+      ["cancel"],
+      ["archive"],
+    ].map((args) => spawnSync(process.execPath, [${JSON.stringify(path.resolve(import.meta.dirname, "../../build/src/cli.js"))}, "workflow", ...args, "--session-dir", ${JSON.stringify(session.sessionDir)}], { cwd: ${JSON.stringify(session.projectRoot)}, encoding: "utf8", env: evidenceEnv }));
+    const currentPointer = (await import("node:module")).createRequire(import.meta.url)(${JSON.stringify(path.resolve(import.meta.dirname, "../../scripts/hooks/lib/current-pointer.js"))});
+    currentPointer.writePerActorCurrent(${JSON.stringify(session.artifactRoot)}, childIdentity.actor, { active_slug: ${JSON.stringify(unrelatedSlug)}, artifact_dir: ${JSON.stringify(unrelatedSlug)} });
+    fs.writeFileSync(${JSON.stringify(path.join(session.artifactRoot, "current.json"))}, JSON.stringify({ active_slug: ${JSON.stringify(unrelatedSlug)}, artifact_dir: ${JSON.stringify(unrelatedSlug)} }));
+    const unrelatedAssignment = ${JSON.stringify(path.join(session.artifactRoot, "assignment", `${unrelatedSlug}.json`))};
+    fs.mkdirSync((await import("node:path")).dirname(unrelatedAssignment), { recursive: true });
+    fs.writeFileSync(unrelatedAssignment, JSON.stringify({ schema_version: "1.0", role: "AssignmentClaimRecord", subject_id: ${JSON.stringify(unrelatedSlug)}, actor: childIdentity.actorStruct, actor_key: childIdentity.actor, artifact_dir: ${JSON.stringify(unrelatedSlug)}, status: "claimed" }));
+    const canonicalState = JSON.parse(fs.readFileSync(${JSON.stringify(path.join(runDir(session.slug, session.projectRoot), "state.json"))}, "utf8"));
+    const authorityValidation = (await import("node:module")).createRequire(import.meta.url)(${JSON.stringify(path.resolve(import.meta.dirname, "../../scripts/hooks/lib/continuation-turn-authority.js"))}).validateActiveTurnAuthority({ sessionDir: ${JSON.stringify(session.sessionDir)}, runId: process.env.FLOW_AGENTS_CONTINUATION_RUN_ID, turnSecret: process.env.FLOW_AGENTS_CONTINUATION_TURN_SECRET, canonicalState });
+    const hookEnv = { ...process.env, FLOW_AGENTS_GOAL_FIT_MODE: "block" };
+    const hook = spawnSync(process.execPath, [${JSON.stringify(path.resolve(import.meta.dirname, "../../scripts/hooks/stop-goal-fit.js"))}], { cwd: ${JSON.stringify(session.projectRoot)}, input: JSON.stringify({ hook_event_name: "Stop", cwd: ${JSON.stringify(session.projectRoot)} }), encoding: "utf8", env: hookEnv });
+    fs.writeFileSync("adapter-authority.json", JSON.stringify({ turnSecret: process.env.FLOW_AGENTS_CONTINUATION_TURN_SECRET || null, runId: process.env.FLOW_AGENTS_CONTINUATION_RUN_ID || null, childIdentity, evidenceRuns: evidenceRuns.map((result) => ({ status: result.status, stderr: result.stderr })), lifecycleRuns: lifecycleRuns.map((result) => ({ status: result.status, stderr: result.stderr })), unrelatedAssignment: JSON.parse(fs.readFileSync(unrelatedAssignment, "utf8")), unrelatedHandoffExists: fs.existsSync(${JSON.stringify(path.join(unrelatedDir, "handoff.json"))}), active: fs.existsSync(${JSON.stringify(authorityFile)}), authorityValidation, hookStatus: hook.status, hookStderr: hook.stderr }));
+    if (hook.status !== 0) throw new Error("Stop hook blocked canonical continuation: " + hook.stderr);
+    process.stdout.write(JSON.stringify({ status: "completed", summary: "adapter advanced " + request.current_step }));
+  `);
+  writeJson(commandFile, { argv: [process.execPath, adapter] });
+
+  const rc = await workflowMain([
+    "drive",
+    "--session-dir", session.sessionDir,
+    "--adapter-command-file", commandFile,
+    "--max-turns", "2",
+    "--turn-timeout-ms", "5000",
+    "--barrier-wait-ms", "0",
+    "--json",
+  ]);
+
+  assert.equal(rc, 0);
+  const request = readJson(path.join(session.projectRoot, "adapter-request.json"));
+  assert.equal(request.current_step, "design-probe", fs.existsSync(path.join(session.projectRoot, "adapter-evidence-error.json")) ? fs.readFileSync(path.join(session.projectRoot, "adapter-evidence-error.json"), "utf8") : "adapter did not advance canonical Flow");
+  assert.deepEqual(request.next_action.skills, ["pickup-probe"]);
+  assert.equal(Object.hasOwn(request, "system_prompt"), false);
+  const authority = readJson(path.join(session.projectRoot, "adapter-authority.json"));
+  assert.match(authority.turnSecret, /^[A-Za-z0-9_-]{43}$/);
+  assert.equal(authority.runId, session.slug);
+  assert.equal(authority.childIdentity.source, "process-ancestry");
+  assert.ok(authority.evidenceRuns.every((result) => result.status === 0), JSON.stringify(authority.evidenceRuns));
+  assert.ok(authority.lifecycleRuns.every((result) => result.status !== 0), JSON.stringify(authority.lifecycleRuns));
+  assert.equal(authority.unrelatedAssignment.status, "claimed", "Stop does not release the unrelated per-actor/global-pointer session");
+  assert.equal(authority.unrelatedHandoffExists, false, "Stop does not relax or hand off the unrelated session");
+  assert.equal(authority.active, true);
+  assert.equal(authority.authorityValidation.valid, true, authority.authorityValidation.reason);
+  assert.equal(authority.hookStatus, 0, `the blocking Stop hook returns control during the signed adapter turn: ${authority.hookStderr}`);
+  assert.match(authority.hookStderr, /continuation driver active turn is authorized/);
+  assert.equal(fs.existsSync(authorityFile), false, "adapter turn authority is removed after the child exits");
+  const driverState = readJson(path.join(session.sessionDir, "continuation-driver", "state.json"));
+  assert.equal(driverState.status, "budget_exhausted");
+  const canonical = await recoverBuilderFlowSession({ sessionDir: session.sessionDir });
+  assert.equal(canonical.run.state.status, "active");
+  assert.equal(canonical.run.state.current_step, "plan");
+  const events = fs.readFileSync(path.join(session.sessionDir, "continuation-driver", "events.jsonl"), "utf8").trim().split("\n").map(JSON.parse);
+  assert.deepEqual(events.filter((event) => event.type === "turn_started").map((event) => event.current_step), ["pull-work", "design-probe"]);
+  assert.equal(events.some((event) => event.type === "gate_not_advanced"), false);
+  const replayEnv = { ...process.env, FLOW_AGENTS_CONTINUATION_TURN_SECRET: authority.turnSecret, FLOW_AGENTS_CONTINUATION_RUN_ID: authority.runId };
+  for (const key of AMBIENT_IDENTITY_ENV_KEYS) delete replayEnv[key];
+  const replay = spawnSync(process.execPath, [path.resolve(import.meta.dirname, "../../build/src/cli.js"), "workflow", "evidence", "--session-dir", session.sessionDir, "--expectation", "implementation-plan", "--status", "pass", "--summary", "replayed turn capability", "--evidence-ref-json", JSON.stringify({ kind: "artifact", file: "adapter.mjs", summary: "replay fixture" })], { cwd: session.projectRoot, encoding: "utf8", env: replayEnv });
+  assert.notEqual(replay.status, 0, "copied capability values fail after active-turn cleanup");
+  replayEnv.FLOW_AGENTS_CONTINUATION_TURN_SECRET = "A".repeat(43);
+  const forged = spawnSync(process.execPath, [path.resolve(import.meta.dirname, "../../build/src/cli.js"), "workflow", "evidence", "--session-dir", session.sessionDir, "--expectation", "implementation-plan", "--status", "pass", "--summary", "forged turn capability", "--evidence-ref-json", JSON.stringify({ kind: "artifact", file: "adapter.mjs", summary: "forgery fixture" })], { cwd: session.projectRoot, encoding: "utf8", env: replayEnv });
+  assert.notEqual(forged.status, 0, "fake nonce and digest without a signed active turn fail ownership");
+});
+
+test("public workflow drive rejects a non-owner before adapter execution", async () => {
+  const session = makeSession("continuation-driver-owner");
+  claimSessionAssignment(session);
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const marker = path.join(session.projectRoot, "adapter-ran");
+  const adapter = path.join(session.projectRoot, "adapter.mjs");
+  const commandFile = path.join(session.projectRoot, "adapter-command.json");
+  fs.writeFileSync(adapter, `
+    import fs from "node:fs";
+    fs.writeFileSync(${JSON.stringify(marker)}, "ran");
+    process.stdout.write(JSON.stringify({ status: "completed" }));
+  `);
+  writeJson(commandFile, { argv: [process.execPath, adapter] });
+
+  await assert.rejects(
+    workflowMain(["drive", "--session-dir", session.sessionDir, "--adapter-command-file", commandFile]),
+    /active, matching assignment actor/,
+  );
+  assert.equal(fs.existsSync(marker), false);
+  assert.equal(fs.existsSync(path.join(session.sessionDir, "continuation-driver")), false);
+});
+
 test("sync attaches the staged trust.bundle bytes when the session bundle is replaced", async () => {
   const session = makeSession("snapshot-attachment");
   await startBuilderFlowSession({ sessionDir: session.sessionDir });

package/src/cli/continuation-adapter.ts

@@ -0,0 +1,265 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { ContinuationAdapterTimeoutError } from "../continuation-driver.js";
+import type { ContinuationBarrier, ContinuationTurnRequest, ContinuationTurnResult } from "../continuation-driver.js";
+
+export type ContinuationAdapterCommand = {
+  argv: string[];
+  identity: string;
+  integrity: Array<{ file: string; sha256: string }>;
+};
+
+export function loadContinuationAdapterCommand(commandFileInput: string): ContinuationAdapterCommand {
+  const commandFile = path.resolve(commandFileInput);
+  const command = validateAdapterCommand(JSON.parse(readRegularFileNoFollow(commandFile, "continuation adapter command file")) as unknown);
+  if (!path.isAbsolute(command.argv[0]!)) throw new Error("continuation adapter executable must be an absolute path");
+  const integrity = [...new Set(command.argv.filter((entry) => path.isAbsolute(entry) && regularFileExists(entry)))]
+    .map((file) => ({ file, sha256: sha256File(file, "continuation adapter integrity file") }));
+  if (!integrity.some((entry) => entry.file === command.argv[0])) throw new Error("continuation adapter executable must be a regular file");
+  const identity = createHash("sha256").update(JSON.stringify({ ...command, integrity })).digest("hex");
+  return { ...command, identity, integrity };
+}
+
+export async function executeContinuationAdapter(
+  commandFileInput: string,
+  request: ContinuationTurnRequest,
+  options: ContinuationAdapterOptions,
+): Promise<ContinuationTurnResult> {
+  const command = loadContinuationAdapterCommand(commandFileInput);
+  return executeLoadedContinuationAdapter(command, request, options);
+}
+
+export async function executeLoadedContinuationAdapter(
+  command: ContinuationAdapterCommand,
+  request: ContinuationTurnRequest,
+  options: ContinuationAdapterOptions,
+): Promise<ContinuationTurnResult> {
+  assertLoadedContinuationAdapterIntegrity(command);
+  assertPositiveInteger(options.timeoutMs, "continuation adapter timeoutMs", 1, 86_400_000);
+  return await spawnAdapter(command, request, options);
+}
+
+export function assertLoadedContinuationAdapterIntegrity(command: ContinuationAdapterCommand): void {
+  for (const entry of command.integrity) {
+    if (sha256File(entry.file, "continuation adapter integrity file") !== entry.sha256) {
+      throw new Error(`continuation adapter integrity changed after mission binding: ${entry.file}`);
+    }
+  }
+}
+
+export async function waitForContinuationBarrier(
+  barrier: ContinuationBarrier,
+  options: { maxWaitMs: number; pollMs: number; now?: () => number; sleep?: (ms: number) => Promise<void> },
+): Promise<"ready" | "pending"> {
+  assertPositiveInteger(options.maxWaitMs, "continuation barrier maxWaitMs", 0, 86_400_000);
+  assertPositiveInteger(options.pollMs, "continuation barrier pollMs", 1, 60_000);
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const stopAt = now() + options.maxWaitMs;
+
+  if (barrier.kind === "deadline") {
+    const deadline = Date.parse(barrier.at);
+    if (deadline <= now()) return "ready";
+    const waitMs = Math.min(deadline - now(), Math.max(0, stopAt - now()));
+    if (waitMs > 0) await sleep(waitMs);
+    return Date.parse(barrier.at) <= now() ? "ready" : "pending";
+  }
+
+  while (pidAlive(barrier.pid)) {
+    const remaining = stopAt - now();
+    if (remaining <= 0) return "pending";
+    await sleep(Math.min(options.pollMs, remaining));
+  }
+  return "ready";
+}
+
+function spawnAdapter(
+  command: ContinuationAdapterCommand,
+  request: ContinuationTurnRequest,
+  options: ContinuationAdapterOptions,
+): Promise<ContinuationTurnResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command.argv[0]!, command.argv.slice(1), {
+      cwd: options.cwd,
+      env: adapterEnvironment(options),
+      detached: process.platform !== "win32",
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let settled = false;
+    let forcedKill: NodeJS.Timeout | undefined;
+    let terminationError: Error | undefined;
+    const maxBytes = 4 * 1024 * 1024;
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      terminationError = new ContinuationAdapterTimeoutError(options.timeoutMs);
+      terminateProcessGroup(child.pid, "SIGTERM");
+      forcedKill = setTimeout(() => terminateProcessGroup(child.pid, "SIGKILL"), 250);
+    }, options.timeoutMs);
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > maxBytes) {
+        if (!terminationError) {
+          terminationError = new Error("continuation adapter stdout exceeded 4 MiB");
+          clearTimeout(timeout);
+          terminateProcessGroup(child.pid, "SIGTERM");
+          forcedKill = setTimeout(() => terminateProcessGroup(child.pid, "SIGKILL"), 250);
+        }
+        return;
+      }
+      stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderrBytes += chunk.length;
+      if (stderrBytes <= maxBytes) stderr.push(chunk);
+    });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      if (forcedKill) clearTimeout(forcedKill);
+      reject(error);
+    });
+    child.on("close", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      if (forcedKill) clearTimeout(forcedKill);
+      if (terminationError) {
+        reject(terminationError);
+        return;
+      }
+      const stderrText = Buffer.concat(stderr).toString("utf8").trim();
+      if (code !== 0) {
+        scheduleProcessGroupTermination(child.pid);
+        reject(new Error(`continuation adapter exited ${code ?? signal ?? "unknown"}${stderrText ? `: ${stderrText}` : ""}`));
+        return;
+      }
+      const output = Buffer.concat(stdout).toString("utf8").trim();
+      try {
+        const result = JSON.parse(output) as ContinuationTurnResult;
+        if (!isValidWaitResult(result)) scheduleProcessGroupTermination(child.pid);
+        resolve(result);
+      } catch {
+        scheduleProcessGroupTermination(child.pid);
+        reject(new Error("continuation adapter must emit exactly one JSON result on stdout"));
+      }
+    });
+    child.stdin.on("error", (error) => {
+      if ((error as NodeJS.ErrnoException).code !== "EPIPE" && !settled) {
+        settled = true;
+        clearTimeout(timeout);
+        if (forcedKill) clearTimeout(forcedKill);
+        scheduleProcessGroupTermination(child.pid);
+        reject(error);
+      }
+    });
+    child.stdin.end(`${JSON.stringify(request)}\n`);
+  });
+}
+
+type ContinuationAdapterOptions = {
+  cwd: string;
+  timeoutMs: number;
+  continuationTurnSecret?: string;
+  continuationRunId?: string;
+};
+
+function adapterEnvironment(options: ContinuationAdapterOptions): NodeJS.ProcessEnv {
+  const env = { ...process.env };
+  delete env.FLOW_AGENTS_CONTINUATION_TURN_SECRET;
+  delete env.FLOW_AGENTS_CONTINUATION_RUN_ID;
+  delete env.FLOW_AGENTS_CONTINUATION_TURN_NONCE;
+  delete env.FLOW_AGENTS_CONTINUATION_TURN_PUBLIC_KEY_DIGEST;
+  delete env.FLOW_AGENTS_CONTINUATION_ACTOR_B64;
+  const { continuationTurnSecret: turnSecret, continuationRunId: runId } = options;
+  if (!turnSecret || !runId) return env;
+  env.FLOW_AGENTS_CONTINUATION_TURN_SECRET = turnSecret;
+  env.FLOW_AGENTS_CONTINUATION_RUN_ID = runId;
+  return env;
+}
+
+function validateAdapterCommand(value: unknown): Pick<ContinuationAdapterCommand, "argv"> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("continuation adapter command file must contain an object");
+  const argv = (value as { argv?: unknown }).argv;
+  if (!Array.isArray(argv) || argv.length === 0 || argv.length > 128 || argv.some((entry) => typeof entry !== "string" || entry.length === 0 || entry.includes("\0"))) {
+    throw new Error("continuation adapter command argv must contain 1 through 128 non-empty strings");
+  }
+  return { argv: [...argv] as string[] };
+}
+
+function assertRegularFile(file: string, label: string): void {
+  const stat = fs.lstatSync(file);
+  if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`${label} must be a regular file`);
+}
+
+function readRegularFileNoFollow(file: string, label: string): string {
+  return readRegularFileBufferNoFollow(file, label).toString("utf8");
+}
+
+function readRegularFileBufferNoFollow(file: string, label: string): Buffer {
+  assertRegularFile(file, label);
+  const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+  try {
+    if (!fs.fstatSync(fd).isFile()) throw new Error(`${label} must be a regular file`);
+    return fs.readFileSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function assertPositiveInteger(value: number, label: string, min: number, max: number): void {
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`${label} must be an integer from ${min} through ${max}`);
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function terminateProcessGroup(pid: number | undefined, signal: NodeJS.Signals): void {
+  if (!pid) return;
+  try {
+    process.kill(process.platform === "win32" ? pid : -pid, signal);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+  }
+}
+
+function isValidWaitResult(result: ContinuationTurnResult): boolean {
+  if (result?.status !== "wait" || !result.barrier || typeof result.barrier !== "object") return false;
+  if (result.barrier.kind === "pid") return Number.isSafeInteger(result.barrier.pid) && result.barrier.pid > 0;
+  return result.barrier.kind === "deadline" && typeof result.barrier.at === "string" && Number.isFinite(Date.parse(result.barrier.at));
+}
+
+function scheduleProcessGroupTermination(pid: number | undefined): void {
+  terminateProcessGroup(pid, "SIGTERM");
+  const forcedKill = setTimeout(() => terminateProcessGroup(pid, "SIGKILL"), 250);
+  forcedKill.unref();
+}
+
+function regularFileExists(file: string): boolean {
+  try {
+    const stat = fs.lstatSync(file);
+    return !stat.isSymbolicLink() && stat.isFile();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function sha256File(file: string, label: string): string {
+  return createHash("sha256").update(readRegularFileBufferNoFollow(file, label)).digest("hex");
+}