@kontourai/flow-agents 3.8.0 → 3.9.0

package/build/src/continuation-driver.js

@@ -0,0 +1,444 @@
+import * as fs from "node:fs";
+import { constants as fsConstants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import { inspectBuilderFlowSession, syncBuilderFlowSession } from "./builder-flow-runtime.js";
+import { atomicWriteJson, ensureSafeDirectory } from "./lib/fs.js";
+export async function runContinuationDriver(input) {
+    assertMaxTurns(input.maxTurns);
+    const now = input.now ?? (() => new Date());
+    const waitForBarrier = input.waitForBarrier ?? (async () => "pending");
+    const authorizeTurn = input.authorizeTurn ?? (async () => { });
+    const adapterCommandIdentity = input.adapterCommandIdentity ?? null;
+    let snapshot = validateSnapshot(await input.runtime.inspect());
+    let state = loadOrCreateState(input.store, snapshot, input.maxTurns, adapterCommandIdentity, now);
+    if (state.max_turns !== input.maxTurns)
+        throw new Error(`continuation maxTurns ${input.maxTurns} does not match the persisted mission budget ${state.max_turns}`);
+    if (state.adapter_command_identity !== adapterCommandIdentity)
+        throw new Error("continuation adapter command identity does not match the persisted mission adapter");
+    const inspectedOutcome = canonicalOutcome(snapshot);
+    if (inspectedOutcome === "done")
+        return finishDone(input.store, state, snapshot, now);
+    if (inspectedOutcome === "failed")
+        return finishFailed(input.store, state, snapshot, now);
+    if (state.pending_barrier) {
+        const barrier = state.pending_barrier;
+        const readiness = await waitForBarrier(barrier);
+        if (readiness === "pending") {
+            state = saveState(input.store, state, { status: "waiting" }, now);
+            return { outcome: "waiting", turns_started: state.turns_started, snapshot, barrier };
+        }
+        state = saveState(input.store, state, { status: "active", pending_barrier: null }, now);
+        appendEvent(input.store, state, snapshot, "resumed", now, { barrier });
+    }
+    snapshot = validateSnapshot(await input.runtime.synchronize());
+    assertMissionIdentity(state, snapshot);
+    const initialOutcome = canonicalOutcome(snapshot);
+    if (initialOutcome === "done")
+        return finishDone(input.store, state, snapshot, now);
+    if (initialOutcome === "failed")
+        return finishFailed(input.store, state, snapshot, now);
+    if (initialOutcome === "waiting") {
+        state = saveState(input.store, state, { status: "waiting" }, now);
+        return { outcome: "waiting", turns_started: state.turns_started, snapshot };
+    }
+    while (state.turns_started < input.maxTurns) {
+        await authorizeTurn();
+        const iteration = state.turns_started + 1;
+        state = saveState(input.store, state, { status: "active", turns_started: iteration }, now);
+        appendEvent(input.store, state, snapshot, "turn_started", now);
+        let result;
+        try {
+            result = validateTurnResult(await input.runtime.execute(Object.freeze({
+                schema_version: "1.0",
+                run_id: snapshot.run_id,
+                definition_id: snapshot.definition_id,
+                current_step: snapshot.current_step,
+                iteration,
+                max_turns: input.maxTurns,
+                next_action: snapshot.next_action ? structuredClone(snapshot.next_action) : null,
+            })));
+        }
+        catch (error) {
+            appendEvent(input.store, state, snapshot, "turn_failed", now, { summary: boundedErrorMessage(error) });
+            snapshot = validateSnapshot(await input.runtime.synchronize());
+            assertMissionIdentity(state, snapshot);
+            const outcome = canonicalOutcome(snapshot);
+            if (outcome === "done")
+                return finishDone(input.store, state, snapshot, now);
+            if (outcome === "failed")
+                return finishFailed(input.store, state, snapshot, now);
+            if (outcome === "waiting") {
+                state = saveState(input.store, state, { status: "waiting" }, now);
+                return { outcome: "waiting", turns_started: state.turns_started, snapshot };
+            }
+            continue;
+        }
+        appendEvent(input.store, state, snapshot, "turn_completed", now, { summary: result.summary });
+        if (result.status === "wait") {
+            state = saveState(input.store, state, { status: "waiting", pending_barrier: result.barrier }, now);
+            appendEvent(input.store, state, snapshot, "parked", now, { barrier: result.barrier, summary: result.summary });
+            const readiness = await waitForBarrier(result.barrier);
+            if (readiness === "pending") {
+                return { outcome: "waiting", turns_started: state.turns_started, snapshot, barrier: result.barrier };
+            }
+            state = saveState(input.store, state, { status: "active", pending_barrier: null }, now);
+            appendEvent(input.store, state, snapshot, "resumed", now, { barrier: result.barrier });
+        }
+        snapshot = validateSnapshot(await input.runtime.synchronize());
+        assertMissionIdentity(state, snapshot);
+        const outcome = canonicalOutcome(snapshot);
+        if (outcome === "done")
+            return finishDone(input.store, state, snapshot, now);
+        if (outcome === "failed")
+            return finishFailed(input.store, state, snapshot, now);
+        if (outcome === "waiting") {
+            state = saveState(input.store, state, { status: "waiting" }, now);
+            return { outcome: "waiting", turns_started: state.turns_started, snapshot };
+        }
+    }
+    state = saveState(input.store, state, { status: "budget_exhausted" }, now);
+    appendEvent(input.store, state, snapshot, "budget_exhausted", now);
+    return { outcome: "budget_exhausted", turns_started: state.turns_started, snapshot };
+}
+export async function driveBuilderFlowSession(input) {
+    const sessionDir = path.resolve(input.sessionDir);
+    const runtime = {
+        inspect: async () => builderSessionSnapshot(await inspectBuilderFlowSession({ sessionDir })),
+        synchronize: async () => builderSessionSnapshot(await syncBuilderFlowSession({ sessionDir })),
+        execute: input.execute,
+    };
+    return runContinuationDriver({
+        maxTurns: input.maxTurns,
+        ...(input.adapterCommandIdentity ? { adapterCommandIdentity: input.adapterCommandIdentity } : {}),
+        runtime,
+        store: createFileContinuationStore(sessionDir),
+        ...(input.waitForBarrier ? { waitForBarrier: input.waitForBarrier } : {}),
+        ...(input.authorizeTurn ? { authorizeTurn: input.authorizeTurn } : {}),
+        ...(input.now ? { now: input.now } : {}),
+    });
+}
+export async function withContinuationDriverLock(sessionDirInput, body) {
+    const sessionDir = path.resolve(sessionDirInput);
+    const driverDir = path.join(sessionDir, "continuation-driver");
+    const locksDir = path.join(driverDir, "locks");
+    ensureSafeDirectory(sessionDir, locksDir);
+    const token = randomUUID();
+    const lockFile = path.join(locksDir, `${process.pid}-${token}.lock`);
+    const owner = { schema_version: "1.0", pid: process.pid, token, created_at: new Date().toISOString() };
+    acquireDriverLock(locksDir, lockFile, owner);
+    try {
+        return await body();
+    }
+    finally {
+        releaseDriverLock(lockFile, token);
+    }
+}
+export function createFileContinuationStore(sessionDirInput) {
+    const sessionDir = path.resolve(sessionDirInput);
+    const driverDir = path.join(sessionDir, "continuation-driver");
+    const stateFile = path.join(driverDir, "state.json");
+    const eventsFile = path.join(driverDir, "events.jsonl");
+    ensureSafeDirectory(sessionDir, driverDir);
+    return {
+        load() {
+            if (!fs.existsSync(stateFile)) {
+                if (fs.existsSync(eventsFile) && fs.statSync(eventsFile).size > 0)
+                    throw new Error("continuation driver state is missing while mission events exist");
+                return null;
+            }
+            const state = JSON.parse(readRegularFileNoFollow(stateFile, "continuation driver state"));
+            reconcileStateWithEvents(state, eventsFile);
+            return state;
+        },
+        save(state) {
+            atomicWriteJson(sessionDir, stateFile, state);
+        },
+        append(event) {
+            appendJsonLineNoFollow(sessionDir, eventsFile, event);
+        },
+    };
+}
+function builderSessionSnapshot(result) {
+    const nextAction = result.projection.next_action;
+    return validateSnapshot({
+        run_id: result.run.runId,
+        definition_id: result.run.definitionId,
+        status: result.run.state.status,
+        disposition: builderContinuationDisposition(result.projection.next_action),
+        current_step: result.run.state.current_step,
+        next_action: nextAction && typeof nextAction === "object" && !Array.isArray(nextAction)
+            ? structuredClone(nextAction)
+            : null,
+    });
+}
+function appendJsonLineNoFollow(root, file, value) {
+    ensureSafeDirectory(root, path.dirname(file));
+    if (fs.existsSync(file))
+        assertRegularFile(file, "continuation driver event log");
+    const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    const fd = fs.openSync(file, fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT | noFollow, 0o600);
+    try {
+        fs.writeFileSync(fd, `${JSON.stringify(value)}\n`, "utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function assertRegularFile(file, label) {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile())
+        throw new Error(`${label} must be a regular file`);
+}
+function readRegularFileNoFollow(file, label) {
+    assertRegularFile(file, label);
+    const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    const fd = fs.openSync(file, fsConstants.O_RDONLY | noFollow);
+    try {
+        if (!fs.fstatSync(fd).isFile())
+            throw new Error(`${label} must be a regular file`);
+        return fs.readFileSync(fd, "utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function acquireDriverLock(locksDir, lockFile, owner) {
+    const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    const fd = fs.openSync(lockFile, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | noFollow, 0o600);
+    try {
+        fs.writeFileSync(fd, `${JSON.stringify(owner)}\n`, "utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        for (const name of fs.readdirSync(locksDir).sort()) {
+            const candidate = path.join(locksDir, name);
+            if (candidate === lockFile)
+                continue;
+            let existing;
+            try {
+                existing = JSON.parse(readRegularFileNoFollow(candidate, "continuation driver lock"));
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    continue;
+                throw error;
+            }
+            if (existing.schema_version !== "1.0" || typeof existing.pid !== "number" || !Number.isSafeInteger(existing.pid) || existing.pid <= 0 || typeof existing.token !== "string") {
+                throw new Error("continuation driver lock is invalid");
+            }
+            if (processAlive(existing.pid))
+                throw new Error(`continuation driver is already running under pid ${existing.pid}`);
+            try {
+                fs.unlinkSync(candidate);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(lockFile);
+        }
+        catch { }
+        throw error;
+    }
+}
+function releaseDriverLock(lockFile, token) {
+    try {
+        const owner = JSON.parse(readRegularFileNoFollow(lockFile, "continuation driver lock"));
+        if (owner.token === token)
+            fs.unlinkSync(lockFile);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function loadOrCreateState(store, snapshot, maxTurns, adapterCommandIdentity, now) {
+    const existing = store.load();
+    if (existing) {
+        validateState(existing);
+        assertMissionIdentity(existing, snapshot);
+        return existing;
+    }
+    const state = {
+        schema_version: "1.0",
+        run_id: snapshot.run_id,
+        definition_id: snapshot.definition_id,
+        max_turns: maxTurns,
+        adapter_command_identity: adapterCommandIdentity,
+        status: "active",
+        turns_started: 0,
+        pending_barrier: null,
+        updated_at: now().toISOString(),
+    };
+    store.save(state);
+    appendEvent(store, state, snapshot, "started", now);
+    return state;
+}
+function canonicalOutcome(snapshot) {
+    return snapshot.disposition;
+}
+function finishDone(store, state, snapshot, now) {
+    const done = saveState(store, state, { status: "done", pending_barrier: null }, now);
+    appendEvent(store, done, snapshot, "done", now);
+    return { outcome: "done", turns_started: done.turns_started, snapshot };
+}
+function finishFailed(store, state, snapshot, now) {
+    const failed = saveState(store, state, { status: "failed", pending_barrier: null }, now);
+    return { outcome: "failed", turns_started: failed.turns_started, snapshot };
+}
+function saveState(store, current, patch, now) {
+    const next = { ...current, ...patch, updated_at: now().toISOString() };
+    store.save(next);
+    return next;
+}
+function appendEvent(store, state, snapshot, type, now, extra = {}) {
+    store.append({
+        schema_version: "1.0",
+        type,
+        run_id: state.run_id,
+        definition_id: state.definition_id,
+        current_step: snapshot.current_step,
+        turns_started: state.turns_started,
+        at: now().toISOString(),
+        ...(extra.barrier ? { barrier: extra.barrier } : {}),
+        ...(extra.summary ? { summary: extra.summary } : {}),
+    });
+}
+function validateSnapshot(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("continuation runtime returned an invalid canonical snapshot");
+    for (const field of ["run_id", "definition_id", "status", "current_step"]) {
+        if (typeof value[field] !== "string" || value[field].length === 0)
+            throw new Error(`continuation snapshot ${field} must be a non-empty string`);
+    }
+    if (!new Set(["continue", "waiting", "done", "failed"]).has(value.disposition))
+        throw new Error("continuation snapshot disposition is invalid");
+    if (value.next_action !== null && (typeof value.next_action !== "object" || Array.isArray(value.next_action))) {
+        throw new Error("continuation snapshot next_action must be an object or null");
+    }
+    return structuredClone(value);
+}
+function validateTurnResult(value) {
+    if (!value || typeof value !== "object" || (value.status !== "completed" && value.status !== "wait")) {
+        throw new Error("continuation adapter must return status completed or wait");
+    }
+    if (value.status === "wait")
+        validateBarrier(value.barrier);
+    if (value.summary !== undefined && typeof value.summary !== "string")
+        throw new Error("continuation adapter summary must be a string");
+    const copy = structuredClone(value);
+    if (copy.summary && copy.summary.length > 2_000)
+        copy.summary = `${copy.summary.slice(0, 1_997)}...`;
+    return copy;
+}
+function validateBarrier(barrier) {
+    if (!barrier || typeof barrier !== "object")
+        throw new Error("continuation wait result requires a barrier");
+    if (barrier.kind === "pid") {
+        if (!Number.isSafeInteger(barrier.pid) || barrier.pid <= 0)
+            throw new Error("continuation pid barrier requires a positive integer pid");
+        return;
+    }
+    if (barrier.kind === "deadline") {
+        if (typeof barrier.at !== "string" || !Number.isFinite(Date.parse(barrier.at)))
+            throw new Error("continuation deadline barrier requires an ISO date-time");
+        return;
+    }
+    throw new Error("continuation barrier kind must be pid or deadline");
+}
+function validateState(state) {
+    if (state.schema_version !== "1.0")
+        throw new Error("continuation driver state schema_version must be 1.0");
+    assertMaxTurns(state.max_turns);
+    if (state.adapter_command_identity !== null && (typeof state.adapter_command_identity !== "string" || state.adapter_command_identity.length === 0)) {
+        throw new Error("continuation driver adapter_command_identity must be a non-empty string or null");
+    }
+    if (!Number.isSafeInteger(state.turns_started) || state.turns_started < 0)
+        throw new Error("continuation driver turns_started must be a non-negative integer");
+    if (state.turns_started > state.max_turns)
+        throw new Error("continuation driver turns_started cannot exceed max_turns");
+    if (!new Set(["active", "waiting", "done", "failed", "budget_exhausted"]).has(state.status))
+        throw new Error("continuation driver state status is invalid");
+    if (state.status === "budget_exhausted" && state.turns_started !== state.max_turns) {
+        throw new Error("continuation driver budget_exhausted state must consume max_turns");
+    }
+    if (state.pending_barrier)
+        validateBarrier(state.pending_barrier);
+}
+function assertMissionIdentity(state, snapshot) {
+    if (state.run_id !== snapshot.run_id || state.definition_id !== snapshot.definition_id) {
+        throw new Error("continuation driver mission identity does not match the canonical Flow run");
+    }
+}
+function assertMaxTurns(value) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 100)
+        throw new Error("continuation maxTurns must be an integer from 1 through 100");
+}
+function boundedErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.length <= 2_000 ? message : `${message.slice(0, 1_997)}...`;
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function reconcileStateWithEvents(state, eventsFile) {
+    if (!fs.existsSync(eventsFile)) {
+        if (state.turns_started > 0)
+            throw new Error("continuation driver event history is missing for a started mission");
+        return;
+    }
+    const lines = readRegularFileNoFollow(eventsFile, "continuation driver event log").split("\n").filter((line) => line.length > 0);
+    let highestStartedTurn = 0;
+    let eventBarrier = null;
+    for (const line of lines) {
+        const event = JSON.parse(line);
+        if (event.run_id !== state.run_id || event.definition_id !== state.definition_id)
+            throw new Error("continuation driver event history has a foreign mission identity");
+        if (event.type === "turn_started") {
+            if (!Number.isSafeInteger(event.turns_started) || event.turns_started < 1)
+                throw new Error("continuation driver event history has an invalid turn count");
+            highestStartedTurn = Math.max(highestStartedTurn, event.turns_started);
+        }
+        if (event.type === "parked") {
+            validateBarrier(event.barrier);
+            eventBarrier = structuredClone(event.barrier);
+        }
+        if (event.type === "resumed")
+            eventBarrier = null;
+    }
+    if (highestStartedTurn > state.turns_started)
+        throw new Error("continuation driver state rolled back behind its event history");
+    if (state.turns_started > highestStartedTurn + 1)
+        throw new Error("continuation driver state is ahead of its event history");
+    if (!state.pending_barrier && eventBarrier) {
+        state.pending_barrier = eventBarrier;
+        state.status = "waiting";
+    }
+}
+function builderContinuationDisposition(nextAction) {
+    if (!nextAction || typeof nextAction !== "object" || Array.isArray(nextAction))
+        throw new Error("Builder Flow projection is missing its canonical next action");
+    const status = nextAction.status;
+    if (status === "continue")
+        return "continue";
+    if (status === "blocked")
+        return "waiting";
+    if (status === "done")
+        return "done";
+    if (status === "failed")
+        return "failed";
+    throw new Error(`Builder Flow projection has unsupported next-action status: ${String(status)}`);
+}

package/build/src/index.d.ts

@@ -2,6 +2,8 @@ export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRu
 export type { BuilderBuildRunResult, BuilderBuildRunIdentityMismatch, BuilderBuildTrustBundleEvidenceInput, EvaluateBuilderBuildRunInput, LoadBuilderBuildRunInput, StartBuilderBuildRunInput, } from "./builder-flow-run-adapter.js";
 export { archiveBuilderFlowSession, cancelBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "./builder-flow-runtime.js";
 export type { BuilderFlowAgentLifecycleInput, BuilderFlowAuthorizedLifecycleInput, BuilderFlowSessionInput, BuilderFlowSessionResult } from "./builder-flow-runtime.js";
+export { createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
+export type { ContinuationBarrier, ContinuationDriverEvent, ContinuationDriverOutcome, ContinuationDriverState, ContinuationRuntimePort, ContinuationSnapshot, ContinuationStateStore, ContinuationTurnRequest, ContinuationTurnResult, DriveBuilderFlowSessionInput, RunContinuationDriverInput, } from "./continuation-driver.js";
 export { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 export type { BuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 export { defaultArtifactRootForRead, defaultCodexHome, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, durableFlowAgentsRoot, durableInstallRecordPath, DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR, FLOW_AGENTS_RUNTIME_SUBDIR, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.js";

package/build/src/index.js

@@ -15,6 +15,7 @@ import * as path from "node:path";
 import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-sidecar.js";
 export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRunInputError, BuilderBuildRunIdentityError, evaluateBuilderBuildRun, loadBuilderBuildRun, resolveBuilderBuildFlowDefinitionPath, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
 export { archiveBuilderFlowSession, cancelBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "./builder-flow-runtime.js";
+export { createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
 // Pure serialization contract used by external lifecycle authorities when
 // signing requests. This does not load, create, or mutate a Flow run.
 export { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";

package/docs/public-workflow-cli.md

@@ -113,6 +113,60 @@ flow_agents workflow archive --authorization-file archive.json
 state, and the canonical Flow run without rewriting either store. Its `next_action` is freshly
 derived from the canonical run, so a stale sidecar projection cannot misdirect recovery.
 
+## Bounded Continuation Driver
+
+`workflow drive` lets the active implementation assignment run multiple Flow steps without a
+human continuation prompt. Flow remains authoritative: the runtime adapter receives the current
+projected action, but its `completed` result means only that one model turn ended. The driver
+returns `done` only after the canonical Flow run is terminal.
+
+The adapter command is an explicit JSON argv file whose executable must be an absolute path. Flow
+Agents invokes it directly without a shell, writes one versioned continuation-turn request to stdin, and requires exactly one
+JSON result on stdout:
+
+```json
+{ "argv": ["/absolute/path/to/runtime-adapter", "--profile", "builder"] }
+```
+
+```json
+{ "status": "completed", "summary": "Turn ended; synchronize canonical evidence." }
+```
+
+An adapter may instead park on a process or deadline. A pending barrier is persisted and does not
+consume another turn when `workflow drive` is invoked again:
+
+```json
+{ "status": "wait", "barrier": { "kind": "pid", "pid": 12345 }, "summary": "Waiting for the verification process." }
+```
+
+```bash
+flow_agents workflow drive \
+  --session-dir .kontourai/flow-agents/example \
+  --adapter-command-file .kontourai/flow-agents/runtime-adapter.json \
+  --max-turns 6 \
+  --turn-timeout-ms 900000 \
+  --barrier-wait-ms 300000 \
+  --json
+```
+
+Driver state and its append-only event stream live under
+`.kontourai/flow-agents/<slug>/continuation-driver/`. The mission turn count survives reinvocation;
+subsequent invocations must use the same `--max-turns` value. The request contains the
+canonical run id, definition id, current step, projected `next_action`, iteration, and budget. It
+does not mutate or replace the runtime system prompt. Adapter errors are recorded as failed turns
+and fail open to canonical resynchronization and the next bounded turn; they cannot bypass the
+persisted mission budget. The Builder Flow projection supplies the canonical continue/wait/done/failed
+disposition, so the generic driver does not duplicate Flow lifecycle semantics. Human-decision and
+paused Flow states park, while remediable blocked and accepted-exception states continue; failed Flow
+runs stop as failed. Assignment ownership is revalidated before every adapter
+turn. A session-scoped process lock rejects concurrent drivers and safely removes unique lock files
+left by exited owners. The adapter argv plus the content digests of its executable and absolute
+regular-file arguments are bound to the mission on first invocation and rechecked before every turn.
+Adapter process groups are terminated after every non-wait result. In addition,
+state rollback or deletion is rejected when its append-only event history proves turns already
+started. These local coordination records detect accidental or in-process rollback; they are not a
+cryptographic boundary against a process that can rewrite the entire artifact directory.
+
 ## Compatibility Doctor
 
 Run doctor through the exact isolated package helper defined above:

package/docs/workflow-usage-guide.md

@@ -663,6 +663,13 @@ the read-only `workflow status` projection without attaching evidence or advanci
 [`docs/spec/builder-flow-runtime.md`](spec/builder-flow-runtime.md) for the ownership,
 trust-binding, route-back, and artifact-root contract.
 
+For unattended runtime re-entry, the active assignment actor may use `workflow drive` with an
+explicit runtime adapter argv file. The driver repeats the same public projection/evidence cycle,
+persists its mission turn budget, and parks on adapter-declared PID or deadline barriers instead of
+spending turns while external work is incomplete. Adapter completion never advances a gate by
+self-report; only trust evidence accepted by canonical Flow can change the current step. See
+[`docs/public-workflow-cli.md`](public-workflow-cli.md#bounded-continuation-driver) for the protocol.
+
 If the same Builder slice is interrupted, inspect its canonical status. Resume
 only when the public status reports a paused run:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",
@@ -144,9 +144,9 @@
     "kit": "npm run build --silent && node build/src/cli.js kit"
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
-    "promptfoo": "^0.121.17",
-    "typescript": "^6.0.3"
+    "@types/node": "^26.1.1",
+    "promptfoo": "^0.121.18",
+    "typescript": "^7.0.2"
   },
   "dependencies": {
     "@kontourai/flow": "^3.1.4"

package/src/builder-flow-runtime.ts

@@ -861,7 +861,9 @@ function projectFlowRun(context: SessionContext, run: BuilderFlowRunResult, side
   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.definitionId, run.state.current_step);
+  const needsDecision = run.state.status === "needs_decision";
+  const failed = run.state.status === "failed";
+  const action = complete || paused || canceled || needsDecision || failed ? { 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}`);
   }
@@ -886,6 +888,10 @@ function projectFlowRun(context: SessionContext, run: BuilderFlowRunResult, side
       ? { status: "done", summary: "Canonical Flow run was canceled by an authorized external request. Artifacts are retained until separately archived." }
       : paused
         ? { status: "blocked", summary: "Canonical Flow run is paused. The current assignment actor may resume it with a reason." }
+      : needsDecision
+        ? { status: "blocked", summary: "Canonical Flow requires an external decision before continuation." }
+      : failed
+        ? { status: "failed", summary: "Canonical Flow run failed; no continuation turn is allowed." }
     : {
         status: "continue",
         summary: `Flow step \`${run.state.current_step}\`: ${skillText}${operationText} ${gateText}${routeText} Then synchronize the recorded evidence.`,
@@ -896,8 +902,8 @@ function projectFlowRun(context: SessionContext, run: BuilderFlowRunResult, side
   const phase = phaseForStep(definition.phase_map, run.state.current_step) ?? sidecar.phase;
   return {
     ...sidecar,
-    status: complete ? "delivered" : canceled ? "canceled" : paused ? "blocked" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
-    phase: complete || canceled ? "done" : phase,
+    status: complete ? "delivered" : canceled ? "canceled" : failed ? "failed" : (paused || needsDecision) ? "blocked" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
+    phase: complete || canceled || failed ? "done" : phase,
     updated_at: run.state.updated_at,
     flow_run: {
       run_id: run.runId,