@kontourai/flow-agents 3.11.0 → 3.12.1

package/dist/base/build/src/continuation-driver.js

@@ -1,9 +1,10 @@
-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";
+import { gateActionProgressSnapshot, withGateActionPriorProgress, } from "./builder-gate-action-envelope.js";
+import { createFileContinuationStore } from "./continuation-persistence.js";
+import { assertMaxTurns, assertMissionIdentity, validateSnapshot, validateState, validateTurnResult } from "./continuation-validation.js";
+export { MAX_CONTINUATION_TURNS, createFileContinuationStore, withContinuationDriverLock } from "./continuation-persistence.js";
+export { MAX_CONTINUATION_ADAPTER_EVIDENCE_BYTES, MAX_CONTINUATION_TURN_RESULT_BYTES } from "./continuation-validation.js";
 export class ContinuationAdapterTimeoutError extends Error {
     code = "CONTINUATION_ADAPTER_TIMEOUT";
     constructor(timeoutMs) {
@@ -14,155 +15,242 @@ export class ContinuationAdapterTimeoutError extends Error {
 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 issueTurnAuthority = input.issueTurnAuthority;
     const adapterCommandIdentity = input.adapterCommandIdentity ?? null;
-    let snapshot = validateSnapshot(await input.runtime.inspect());
-    let state = loadOrCreateState(input.store, snapshot, input.maxTurns, adapterCommandIdentity, now);
+    const inspected = validateSnapshot(await input.runtime.inspect());
+    let state = loadOrCreateState(input.store, inspected, 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);
+    let settled = await settleMissionStart(input, state, now);
+    if (settled.outcome)
+        return settled.outcome;
+    ({ state } = settled);
+    let snapshot = settled.snapshot;
+    while (state.turns_started < input.maxTurns) {
+        const turn = await executeContinuationTurn(input, state, snapshot, now);
+        if (turn.outcome)
+            return turn.outcome;
+        state = turn.state;
+        snapshot = turn.snapshot;
+    }
+    return finishBudgetExhausted(input.store, state, snapshot, now);
+}
+async function settleMissionStart(input, state, now) {
+    let position = await synchronizeAndRecover(input, state, now);
+    if (position.state.pending_barrier && new Set(["done", "failed"]).has(canonicalOutcome(position.snapshot))) {
+        const barrier = position.state.pending_barrier;
+        position.state = saveState(input.store, position.state, { status: "active", pending_barrier: null }, now);
+        appendEvent(input.store, position.state, position.snapshot, "resumed", now, { barrier, summary: "canonical Flow resolved the pending barrier" });
+    }
+    const terminal = resolveCanonicalDisposition(input.store, position.state, position.snapshot, now, false);
+    if (terminal)
+        return { ...position, outcome: terminal };
+    if (position.state.pending_barrier) {
+        const barrier = position.state.pending_barrier;
+        const readiness = await (input.waitForBarrier ?? (async () => "pending"))(barrier);
         if (readiness === "pending") {
-            state = saveState(input.store, state, { status: "waiting", active_turn_step: null, active_turn_public_key_digest: null }, now);
-            return { outcome: "waiting", turns_started: state.turns_started, snapshot, barrier };
+            const waiting = saveState(input.store, position.state, { status: "waiting" }, now);
+            return { state: waiting, snapshot: position.snapshot, outcome: { outcome: "waiting", turns_started: waiting.turns_started, snapshot: position.snapshot, barrier } };
         }
-        state = saveState(input.store, state, { status: "active", active_turn_step: null, active_turn_public_key_digest: null, pending_barrier: null }, now);
-        appendEvent(input.store, state, snapshot, "resumed", now, { barrier });
+        position.state = saveState(input.store, position.state, { status: "active", pending_barrier: null }, now);
+        appendEvent(input.store, position.state, position.snapshot, "resumed", now, { barrier });
+        position = await synchronizeAndRecover(input, position.state, now);
     }
-    snapshot = validateSnapshot(await input.runtime.synchronize());
+    const disposition = resolveCanonicalDisposition(input.store, position.state, position.snapshot, now, true);
+    return disposition ? { ...position, outcome: disposition } : position;
+}
+async function synchronizeAndRecover(input, state, now) {
+    const 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", active_turn_step: null, active_turn_public_key_digest: null }, now);
-        return { outcome: "waiting", turns_started: state.turns_started, snapshot };
+    const recovered = reconcileInterruptedTurn(input.store, state, snapshot, now);
+    return { state: reconcileProgress(input.store, recovered, snapshot, now), snapshot };
+}
+function resolveCanonicalDisposition(store, state, snapshot, now, includeWaiting) {
+    const disposition = canonicalOutcome(snapshot);
+    if (disposition === "done")
+        return finishDone(store, state, snapshot, now);
+    if (disposition === "failed")
+        return finishFailed(store, state, snapshot, now);
+    if (includeWaiting && disposition === "waiting") {
+        const waiting = saveState(store, state, { status: "waiting" }, now);
+        return { outcome: "waiting", turns_started: waiting.turns_started, snapshot };
+    }
+    return null;
+}
+async function executeContinuationTurn(input, current, snapshot, now) {
+    await (input.authorizeTurn ?? (async () => { }))();
+    const request = continuationTurnRequest(input, current, snapshot);
+    if (input.preflightTurn)
+        await input.preflightTurn(request);
+    let state = beginContinuationTurn(input.store, current, snapshot, request.iteration, now);
+    let authority;
+    try {
+        authority = input.issueTurnAuthority ? await input.issueTurnAuthority(request) : undefined;
+        if (authority)
+            state = saveState(input.store, state, { active_turn_public_key_digest: authority.publicKeyDigest }, now);
+        const result = validateTurnResult(await input.runtime.execute(request, authorityContext(authority)));
+        return await recordAcceptedTurn(input, state, snapshot, request, result, now);
     }
-    while (state.turns_started < input.maxTurns) {
-        await authorizeTurn();
-        const iteration = state.turns_started + 1;
-        state = saveState(input.store, state, {
-            status: "active",
-            turns_started: iteration,
-            active_turn_step: snapshot.current_step,
-            active_turn_public_key_digest: null,
-        }, now);
-        appendEvent(input.store, state, snapshot, "turn_started", now);
-        let result;
-        let request;
-        let authority;
-        let terminalized = false;
-        try {
-            request = 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,
-            });
-            authority = issueTurnAuthority ? await issueTurnAuthority(request) : undefined;
-            if (authority) {
-                state = saveState(input.store, state, { active_turn_public_key_digest: authority.publicKeyDigest }, now);
-            }
-            result = validateTurnResult(await input.runtime.execute(request, authority ? {
-                continuationTurnSecret: authority.turnSecret,
-                continuationRunId: authority.runId,
-            } : undefined));
-        }
-        catch (error) {
-            const summary = boundedErrorMessage(error);
-            appendEvent(input.store, state, snapshot, "turn_failed", now, { summary, failure_kind: error instanceof ContinuationAdapterTimeoutError ? "timeout" : "adapter_error" });
-            snapshot = validateSnapshot(await input.runtime.synchronize());
-            assertMissionIdentity(state, snapshot);
-            const outcome = canonicalOutcome(snapshot);
-            if (outcome === "done") {
-                terminalized = true;
-                return finishDone(input.store, state, snapshot, now);
-            }
-            if (outcome === "failed") {
-                terminalized = true;
-                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;
-        }
-        finally {
-            let cleanupFailure;
-            try {
-                if (authority && !authority.cleanup())
-                    cleanupFailure = "continuation turn authority cleanup returned false";
-            }
-            catch (error) {
-                cleanupFailure = boundedErrorMessage(error);
-            }
-            finally {
-                if (!terminalized)
-                    state = saveState(input.store, state, {
-                        active_turn_step: null,
-                        active_turn_public_key_digest: null,
-                    }, now);
-                if (cleanupFailure) {
-                    try {
-                        appendEvent(input.store, state, snapshot, "authority_cleanup_failed", now, { summary: cleanupFailure });
-                    }
-                    catch {
-                        // Audit is best effort. A cleanup extension must not replace the adapter outcome.
-                    }
-                }
-            }
-        }
-        if (input.onTurnAccepted)
-            await input.onTurnAccepted(request, result);
-        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);
-        if (snapshot.status === "active" && snapshot.current_step === request.current_step) {
-            appendEvent(input.store, state, snapshot, "gate_not_advanced", now, { summary: "adapter completed without canonical gate advancement" });
-        }
-        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 };
-        }
+    catch (error) {
+        const failed = await recordFailedTurn(input, input.store.load() ?? state, snapshot, error, now);
+        if (isTurnCaptureFailure(error))
+            throw error.cause;
+        return failed;
     }
-    state = saveState(input.store, state, {
-        status: "budget_exhausted",
+    finally {
+        auditAuthorityCleanup(input.store, state, snapshot, authority, now);
+    }
+}
+function continuationTurnRequest(input, state, snapshot) {
+    const envelope = snapshot.gate_action_envelope
+        ? withGateActionPriorProgress(snapshot.gate_action_envelope, state.prior_progress ?? initialProgress())
+        : undefined;
+    return Object.freeze({
+        schema_version: "1.0",
+        run_id: snapshot.run_id,
+        definition_id: snapshot.definition_id,
+        current_step: snapshot.current_step,
+        iteration: state.turns_started + 1,
+        max_turns: input.maxTurns,
+        next_action: snapshot.next_action ? structuredClone(snapshot.next_action) : null,
+        ...(envelope ? { gate_action_envelope: envelope } : {}),
+    });
+}
+function beginContinuationTurn(store, state, snapshot, iteration, now) {
+    let started = saveState(store, state, {
+        status: "active", turns_started: iteration, active_turn_step: snapshot.current_step,
+        active_turn_public_key_digest: null, active_turn_phase: "prepared", active_turn_progress: progressSnapshot(snapshot), active_turn_capture: null,
+    }, now);
+    appendEvent(store, started, snapshot, "turn_started", now);
+    started = saveState(store, started, { active_turn_phase: "started" }, now);
+    return started;
+}
+function authorityContext(authority) {
+    return authority ? { continuationTurnSecret: authority.turnSecret, continuationRunId: authority.runId } : undefined;
+}
+async function captureAcceptedTurn(callback, request, result) {
+    try {
+        await callback(request, result);
+    }
+    catch (cause) {
+        const error = new Error(boundedErrorMessage(cause));
+        error.cause = cause;
+        error.capture_failure = true;
+        throw error;
+    }
+}
+function isTurnCaptureFailure(error) {
+    return error instanceof Error && error.capture_failure === true;
+}
+async function recordFailedTurn(input, state, previous, error, now) {
+    const measured = state.active_turn_phase === "measured" && state.active_turn_capture
+        ? { state, snapshot: validateSnapshot(await input.runtime.synchronize()), progress: state.active_turn_capture.progress ?? undefined }
+        : await synchronizeTurnMeasurement(input, state, previous, null, null, now);
+    appendEvent(input.store, measured.state, measured.snapshot, "turn_failed", now, {
+        summary: boundedErrorMessage(error),
+        failure_kind: error instanceof ContinuationAdapterTimeoutError ? "timeout" : "adapter_error",
+        ...(measured.progress ? { progress: measured.progress } : {}),
+        ...(measured.state.active_turn_capture ? { turn_id: measured.state.active_turn_capture.turn_id } : {}),
+    });
+    const cleared = clearActiveTurn(input.store, measured.state, now);
+    const outcome = resolveCanonicalDisposition(input.store, cleared, measured.snapshot, now, true);
+    return outcome ? { state: cleared, snapshot: measured.snapshot, outcome } : { ...measured, state: cleared };
+}
+async function recordAcceptedTurn(input, state, previous, request, result, now) {
+    let measured = await synchronizeTurnMeasurement(input, state, previous, request, result, now);
+    const capture = measured.state.active_turn_capture;
+    acceptedTurnJournal(input.store)?.captureAcceptedTurn(capture);
+    if (input.onTurnAccepted)
+        await captureAcceptedTurn(input.onTurnAccepted, request, result);
+    if (result.status === "wait")
+        return parkAcceptedTurn(input, measured, result, now);
+    appendEvent(input.store, measured.state, measured.snapshot, "turn_completed", now, {
+        summary: result.summary,
+        ...(measured.progress ? { progress: measured.progress } : {}),
+        turn_id: capture.turn_id,
+    });
+    measured = { ...measured, state: clearActiveTurn(input.store, measured.state, now) };
+    if (measured.snapshot.status === "active" && measured.snapshot.current_step === request.current_step) {
+        appendEvent(input.store, measured.state, measured.snapshot, "gate_not_advanced", now, { summary: "adapter completed without canonical gate advancement" });
+    }
+    const outcome = resolveCanonicalDisposition(input.store, measured.state, measured.snapshot, now, true);
+    return outcome ? { state: measured.state, snapshot: measured.snapshot, outcome } : measured;
+}
+async function parkAcceptedTurn(input, measured, result, now) {
+    let state = saveState(input.store, measured.state, { status: "waiting", pending_barrier: result.barrier }, now);
+    const turnId = state.active_turn_capture.turn_id;
+    appendEvent(input.store, state, measured.snapshot, "parked", now, {
+        barrier: result.barrier, summary: result.summary, ...(measured.progress ? { progress: measured.progress } : {}), turn_id: turnId,
+    });
+    state = clearActiveTurn(input.store, state, now);
+    const readiness = await (input.waitForBarrier ?? (async () => "pending"))(result.barrier);
+    if (readiness === "pending") {
+        return { state, snapshot: measured.snapshot, outcome: { outcome: "waiting", turns_started: state.turns_started, snapshot: measured.snapshot, barrier: result.barrier } };
+    }
+    state = saveState(input.store, state, { status: "active", pending_barrier: null }, now);
+    appendEvent(input.store, state, measured.snapshot, "resumed", now, { barrier: result.barrier });
+    const resumed = await synchronizeAndRecover(input, state, now);
+    const outcome = resolveCanonicalDisposition(input.store, resumed.state, resumed.snapshot, now, true);
+    return outcome ? { ...resumed, outcome } : resumed;
+}
+async function synchronizeTurnMeasurement(input, state, previous, request, result, now) {
+    const snapshot = validateSnapshot(await input.runtime.synchronize());
+    assertMissionIdentity(state, snapshot);
+    const before = state.active_turn_progress ?? state.last_progress ?? progressSnapshot(previous);
+    const progress = measureProgress(state, before, progressSnapshot(snapshot));
+    const capture = request && result ? acceptedTurnCapture(request, result, progress?.delta ?? null, now) : null;
+    const measured = saveState(input.store, state, {
+        ...(progress ? { last_progress: progress.snapshot, prior_progress: progress.delta } : {}),
+        ...(capture ? { active_turn_phase: "measured", active_turn_capture: capture } : {}),
+    }, now);
+    return { state: measured, snapshot, ...(progress ? { progress: progress.delta } : {}) };
+}
+function acceptedTurnCapture(request, result, progress, now) {
+    return {
+        schema_version: "1.0",
+        turn_id: `${request.run_id}:${request.iteration}`,
+        iteration: request.iteration,
+        request: structuredClone(request),
+        result: structuredClone(result),
+        progress: progress ? structuredClone(progress) : null,
+        captured_at: now().toISOString(),
+    };
+}
+function clearActiveTurn(store, state, now) {
+    return saveState(store, state, {
         active_turn_step: null,
         active_turn_public_key_digest: null,
+        active_turn_phase: null,
+        active_turn_progress: null,
+        active_turn_capture: null,
+    }, now);
+}
+function auditAuthorityCleanup(store, state, snapshot, authority, now) {
+    let summary;
+    try {
+        if (authority && !authority.cleanup())
+            summary = "continuation turn authority cleanup returned false";
+    }
+    catch (error) {
+        summary = boundedErrorMessage(error);
+    }
+    if (!summary)
+        return;
+    try {
+        appendEvent(store, state, snapshot, "authority_cleanup_failed", now, { summary });
+    }
+    catch {
+        // Audit is best effort. A cleanup extension must not replace the adapter outcome.
+    }
+}
+function finishBudgetExhausted(store, state, snapshot, now) {
+    const exhausted = saveState(store, state, {
+        status: "budget_exhausted", active_turn_step: null, active_turn_public_key_digest: null,
+        active_turn_phase: null, active_turn_progress: null, active_turn_capture: null,
     }, now);
-    appendEvent(input.store, state, snapshot, "budget_exhausted", now);
-    return { outcome: "budget_exhausted", turns_started: state.turns_started, snapshot };
+    appendEvent(store, exhausted, snapshot, "budget_exhausted", now);
+    return { outcome: "budget_exhausted", turns_started: exhausted.turns_started, snapshot };
 }
 export async function driveBuilderFlowSession(input) {
     const sessionDir = path.resolve(input.sessionDir);
@@ -175,56 +263,15 @@ export async function driveBuilderFlowSession(input) {
         maxTurns: input.maxTurns,
         ...(input.adapterCommandIdentity ? { adapterCommandIdentity: input.adapterCommandIdentity } : {}),
         runtime,
-        store: createFileContinuationStore(sessionDir),
+        store: input.store ?? createFileContinuationStore(sessionDir),
         ...(input.waitForBarrier ? { waitForBarrier: input.waitForBarrier } : {}),
         ...(input.authorizeTurn ? { authorizeTurn: input.authorizeTurn } : {}),
         ...(input.issueTurnAuthority ? { issueTurnAuthority: input.issueTurnAuthority } : {}),
+        ...(input.preflightTurn ? { preflightTurn: input.preflightTurn } : {}),
         ...(input.onTurnAccepted ? { onTurnAccepted: input.onTurnAccepted } : {}),
         ...(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 lease = { pid: process.pid, token, created_at: new Date().toISOString() };
-    const owner = { schema_version: "1.0", ...lease };
-    acquireDriverLock(locksDir, lockFile, owner);
-    try {
-        return await body(lease);
-    }
-    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({
@@ -236,95 +283,10 @@ function builderSessionSnapshot(result) {
         next_action: nextAction && typeof nextAction === "object" && !Array.isArray(nextAction)
             ? structuredClone(nextAction)
             : null,
+        progress_snapshot: structuredClone(result.progressSnapshot),
+        ...(result.gateActionEnvelope ? { gate_action_envelope: structuredClone(result.gateActionEnvelope) } : {}),
     });
 }
-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) {
@@ -342,6 +304,9 @@ function loadOrCreateState(store, snapshot, maxTurns, adapterCommandIdentity, no
         turns_started: 0,
         active_turn_step: null,
         active_turn_public_key_digest: null,
+        active_turn_phase: null,
+        active_turn_progress: null,
+        active_turn_capture: null,
         pending_barrier: null,
         updated_at: now().toISOString(),
     };
@@ -352,11 +317,133 @@ function loadOrCreateState(store, snapshot, maxTurns, adapterCommandIdentity, no
 function canonicalOutcome(snapshot) {
     return snapshot.disposition;
 }
+function reconcileProgress(store, state, snapshot, now) {
+    const current = progressSnapshot(snapshot);
+    if (!current)
+        return state;
+    if (!state.last_progress)
+        return saveState(store, state, { last_progress: current, prior_progress: initialProgress() }, now);
+    if (sameProgressSnapshot(state.last_progress, current))
+        return state;
+    const progress = measureProgress(state, state.last_progress, current);
+    return progress ? saveState(store, state, { last_progress: progress.snapshot, prior_progress: progress.delta }, now) : state;
+}
+function reconcileInterruptedTurn(store, state, snapshot, now) {
+    if (!state.active_turn_phase)
+        return state;
+    if (state.active_turn_phase === "prepared") {
+        return clearActiveTurn(store, state, now);
+    }
+    if (state.active_turn_phase === "measured") {
+        if (!state.active_turn_capture)
+            throw new Error("continuation measured turn is missing its durable capture");
+        const capture = state.active_turn_capture;
+        acceptedTurnJournal(store)?.captureAcceptedTurn(capture);
+        let recovered = capture.result.status === "wait"
+            ? saveState(store, state, { status: "waiting", pending_barrier: capture.result.barrier }, now)
+            : state;
+        appendEvent(store, recovered, snapshot, capture.result.status === "wait" ? "parked" : "turn_completed", now, {
+            ...(capture.result.status === "wait" ? { barrier: capture.result.barrier } : {}),
+            ...(capture.result.summary ? { summary: capture.result.summary } : {}),
+            ...(capture.progress ? { progress: capture.progress } : {}),
+            turn_id: capture.turn_id,
+        });
+        recovered = clearActiveTurn(store, recovered, now);
+        appendEvent(store, recovered, snapshot, "turn_recovered", now, {
+            summary: "completed durable accepted-turn capture after interruption",
+            ...(capture.progress ? { progress: capture.progress } : {}),
+            turn_id: capture.turn_id,
+        });
+        return recovered;
+    }
+    const progress = measureProgress(state, state.active_turn_progress ?? state.last_progress ?? null, progressSnapshot(snapshot));
+    const recovered = saveState(store, state, {
+        ...(progress ? { last_progress: progress.snapshot, prior_progress: progress.delta } : {}),
+        active_turn_step: null,
+        active_turn_public_key_digest: null,
+        active_turn_phase: null,
+        active_turn_progress: null,
+        active_turn_capture: null,
+    }, now);
+    appendEvent(store, recovered, snapshot, "turn_recovered", now, {
+        summary: "recovered interrupted adapter turn from canonical Flow progress",
+        ...(progress ? { progress: progress.delta } : {}),
+    });
+    return recovered;
+}
+function sameProgressSnapshot(left, right) {
+    return left.current_step === right.current_step
+        && sameCanonicalStatus(left.canonical_status, right.canonical_status)
+        && left.canonical_evidence.length === right.canonical_evidence.length
+        && left.canonical_evidence.every((entry, index) => entry === right.canonical_evidence[index])
+        && left.observed_artifacts.length === right.observed_artifacts.length
+        && left.observed_artifacts.every((entry, index) => entry === right.observed_artifacts[index]);
+}
+function isTerminalCanonicalStatus(status) {
+    return status === "completed" || status === "failed";
+}
+function sameCanonicalStatus(left, right) {
+    if (left === right)
+        return true;
+    // Pre-status snapshots remain compatible while active. A newly observed
+    // terminal status is still a real canonical transition from legacy state.
+    if (left === undefined)
+        return !isTerminalCanonicalStatus(right);
+    if (right === undefined)
+        return !isTerminalCanonicalStatus(left);
+    return false;
+}
+function progressSnapshot(snapshot) {
+    if (snapshot.progress_snapshot)
+        return structuredClone(snapshot.progress_snapshot);
+    return snapshot.gate_action_envelope ? gateActionProgressSnapshot(snapshot.gate_action_envelope) : null;
+}
+function acceptedTurnJournal(store) {
+    const candidate = store;
+    return typeof candidate.captureAcceptedTurn === "function" && typeof candidate.acceptedTurns === "function"
+        ? candidate
+        : null;
+}
+function initialProgress() {
+    return {
+        step_advanced: false,
+        evidence_added: [],
+        artifact_changes: [],
+        no_progress: false,
+        consecutive_no_progress: 0,
+        stagnation: "none",
+    };
+}
+function measureProgress(state, before, after) {
+    if (!before || !after)
+        return null;
+    const terminalStatusAdvanced = isTerminalCanonicalStatus(after.canonical_status)
+        && before.canonical_status !== after.canonical_status;
+    const stepAdvanced = before.current_step !== after.current_step || terminalStatusAdvanced;
+    const evidenceAdded = after.canonical_evidence.filter((entry) => !before.canonical_evidence.includes(entry));
+    const artifactChanges = after.observed_artifacts.filter((entry) => !before.observed_artifacts.includes(entry));
+    const noProgress = !stepAdvanced && evidenceAdded.length === 0 && artifactChanges.length === 0;
+    const consecutiveNoProgress = noProgress ? (state.prior_progress?.consecutive_no_progress ?? 0) + 1 : 0;
+    return {
+        snapshot: after,
+        delta: {
+            step_advanced: stepAdvanced,
+            evidence_added: evidenceAdded,
+            artifact_changes: artifactChanges,
+            no_progress: noProgress,
+            consecutive_no_progress: consecutiveNoProgress,
+            stagnation: consecutiveNoProgress >= 2 ? "stagnant" : consecutiveNoProgress === 1 ? "possible" : "none",
+        },
+    };
+}
 function finishDone(store, state, snapshot, now) {
     const done = saveState(store, state, {
         status: "done",
         active_turn_step: null,
         active_turn_public_key_digest: null,
+        active_turn_phase: null,
+        active_turn_progress: null,
+        active_turn_capture: null,
         pending_barrier: null,
     }, now);
     appendEvent(store, done, snapshot, "done", now);
@@ -367,6 +454,9 @@ function finishFailed(store, state, snapshot, now) {
         status: "failed",
         active_turn_step: null,
         active_turn_public_key_digest: null,
+        active_turn_phase: null,
+        active_turn_progress: null,
+        active_turn_capture: null,
         pending_barrier: null,
     }, now);
     return { outcome: "failed", turns_started: failed.turns_started, snapshot };
@@ -388,155 +478,14 @@ function appendEvent(store, state, snapshot, type, now, extra = {}) {
         ...(extra.barrier ? { barrier: extra.barrier } : {}),
         ...(extra.summary ? { summary: extra.summary } : {}),
         ...(extra.failure_kind ? { failure_kind: extra.failure_kind } : {}),
+        ...(extra.progress ? { progress: structuredClone(extra.progress) } : {}),
+        ...(extra.turn_id ? { turn_id: extra.turn_id } : {}),
     });
 }
-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");
-    if (value.status === "completed" && value.evidence !== undefined)
-        validateAdapterEvidence(value.evidence);
-    if (value.status === "wait" && Object.hasOwn(value, "evidence"))
-        throw new Error("continuation wait results must not include evidence");
-    const copy = structuredClone(value);
-    if (copy.summary && copy.summary.length > 2_000)
-        copy.summary = `${copy.summary.slice(0, 1_997)}...`;
-    return copy;
-}
-function validateAdapterEvidence(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new Error("continuation adapter evidence must be a JSON object");
-    }
-    let encoded;
-    try {
-        encoded = JSON.stringify(value);
-    }
-    catch {
-        throw new Error("continuation adapter evidence must be JSON-serializable");
-    }
-    if (encoded === undefined || Buffer.byteLength(encoded, "utf8") > 65_536) {
-        throw new Error("continuation adapter evidence must not exceed 65536 bytes");
-    }
-    const parsed = JSON.parse(encoded);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("continuation adapter evidence must be a JSON object");
-    }
-}
-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 (state.active_turn_step !== undefined && state.active_turn_step !== null && (typeof state.active_turn_step !== "string" || state.active_turn_step.length === 0)) {
-        throw new Error("continuation driver active_turn_step must be a non-empty string or null");
-    }
-    if (state.active_turn_public_key_digest !== undefined && state.active_turn_public_key_digest !== null
-        && (typeof state.active_turn_public_key_digest !== "string" || !/^[a-f0-9]{64}$/.test(state.active_turn_public_key_digest))) {
-        throw new Error("continuation driver active_turn_public_key_digest must be a SHA-256 hex digest or null");
-    }
-    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");