@deksden-com/dd-flow-cli 0.9.0-beta.75 → 0.9.0-beta.79

package/dist/services/run-controller.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 import { ensureRunControllerStorage, getDatabase } from "../storage/database.js";
 import { canonicalPath, resolveProjectRoot } from "../storage/paths.js";
 import { AppError } from "../shared/errors.js";
+import { prepareFileBytes, prepareJsonText } from "../cli/input-preparation.js";
 import { parseRuntimeBudget } from "./runtime-budget.js";
 import { requireProjectByRoot } from "./projects.js";
 import { assertRunMutationAllowed, recoveryGuard } from "./run-recovery.js";
@@ -23,15 +24,14 @@ import { launchExternalWork } from "./external-work-launch.js";
 import { controllerNativeChildren, controllerStageEntryPrompt, nextControllerFanout } from "./controller-fanout.js";
 import { claimQueuedMergeRequest } from "./merge-server.js";
 import { prepareVnextCodeWorkspace } from "./vnext-code.js";
-import { requireRun, requireController, controllerReceipt, appendEvent, saveState, digest, digestBytes, errorRecord } from "./run-controller-state.js";
+import { requireRun, requireController, controllerReceipt, appendEvent, saveState, retainControllerContinuation, digest, digestBytes, errorRecord } from "./run-controller-state.js";
 import { spawnController, recordControllerLauncher, claimControllerProcess, markControllerDispatchReady } from "./run-controller-process.js";
 import { controllerAdapter, controllerEnvironment, sessionArguments } from "./run-controller-adapter.js";
 import { resumeControllerSession, failControllerRecovery } from "./run-controller-recovery.js";
 import { captureControllerBoundary } from "./run-controller-capture.js";
 import { requestRunControl } from "./run-control-worker.js";
 export { resumeRunController } from "./run-controller-recovery.js";
-/** Persist intent before spawning. A repeated client observes the same owner. */
-export async function launchRunController(context, input) {
+export function prepareRunControllerLaunch(context, input) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(input.requestId) || !/^[a-f0-9]{64}$/.test(input.contextSha256))
         throw new AppError("usage", "Managed launch needs a request id and context SHA-256", 2);
     if (input.stopAfter !== undefined && !/^[a-z][a-z-]*$/.test(input.stopAfter))
@@ -46,12 +46,12 @@ export async function launchRunController(context, input) {
     const budget = parseRuntimeBudget(context.env.DD_FLOW_RUNTIME_BUDGET);
     const request = { project_root: project.root, run_id: run.id, context_sha256: input.contextSha256, stop_after: input.stopAfter ?? null, ...(captureRoot ? { capture_root: captureRoot } : {}), ...(budget ? { budget_sha256: digest(budget) } : {}) };
     const requestHash = digest(request);
-    ensureRunControllerStorage(context.db);
-    const existing = context.db.get("SELECT * FROM run_controllers WHERE project_id = ? AND run_id = ? AND request_id = ?", [project.id, run.id, input.requestId]);
+    const existing = context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controllers'")
+        ? context.db.get("SELECT * FROM run_controllers WHERE project_id = ? AND run_id = ? AND request_id = ?", [project.id, run.id, input.requestId]) : undefined;
     if (existing) {
         if (existing.request_hash !== requestHash)
             throw new AppError("runtime_request_conflict", "Managed launch request id has different inputs", 1);
-        return { ...await spawnController(context, existing), reused: true };
+        return { kind: "replay", existing };
     }
     const generation = assertRunMutationAllowed(context, project.id, run.id);
     if (run.status !== "running")
@@ -71,13 +71,21 @@ export async function launchRunController(context, input) {
         const harness = runtimeHarness(profile);
         adapters[harness] = { executable: resolveHarnessCommand(context.ddFlowHome, harness, "adapter"), runtime_args: harnessRuntimeArguments(context.ddFlowHome, harness) };
     }
+    const entry = fileURLToPath(new URL("../cli.js", import.meta.url));
+    if (!fs.existsSync(entry))
+        throw new AppError("harness_runtime_unbuilt", "Build the CLI before launching its detached controller", 1);
+    return { kind: "create", project, run, request, requestHash, generation, budget, execution, contexts, adapters };
+}
+export async function launchRunController(context, input, prepared = prepareRunControllerLaunch(context, input)) {
+    if (prepared.kind === "replay")
+        return { ...await spawnController(context, prepared.existing), reused: true };
+    const { project, run, request, requestHash, generation, budget, execution, contexts, adapters } = prepared;
+    assertRunMutationAllowed(context, project.id, run.id, generation);
+    ensureRunControllerStorage(context.db);
     const controllerId = `DRV-${crypto.randomUUID()}`;
     const root = path.join(run.run_root, "controllers", controllerId);
     fs.mkdirSync(root, { recursive: true, mode: 0o700 });
     const flowExecutable = prepareHarnessFlowExecutable(context, root);
-    const entry = fileURLToPath(new URL("../cli.js", import.meta.url));
-    if (!fs.existsSync(entry))
-        throw new AppError("harness_runtime_unbuilt", "Build the CLI before launching its detached controller", 1);
     const frozenContexts = {};
     for (const [stage, value] of Object.entries(contexts)) {
         const file = path.join(root, `${stage}.context.json`);
@@ -98,6 +106,8 @@ export async function launchRunController(context, input) {
             return { ...controllerReceipt(duplicate), reused: true };
         }
         assertRunMutationAllowed(context, project.id, run.id, generation);
+        if (requireRun(context, project.id, run.id).status !== "running")
+            throw new AppError("invalid_run_state", "Managed launch requires a running logical RUN", 1);
         const owner = context.db.get("SELECT * FROM run_controllers WHERE project_id = ? AND run_id = ? AND status NOT IN ('completed','cancelled','superseded')", [project.id, run.id]);
         if (owner)
             throw new AppError("controller_already_owned", "RUN already has an unresolved managed owner; observe or reconcile it", 1, { controller_id: owner.controller_id });
@@ -287,42 +297,66 @@ export async function serveRunController(context, input) {
         }
     }
 }
-/** Public HITL input: persist raw bytes, never deliver a turn from this client. */
-export function answerRunController(context, input) {
+export function prepareRunControllerAnswer(context, input) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(input.requestId) || !input.pauseId.trim())
         throw new AppError("usage", "Answer requires request-id and pause-id", 2);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const prior = context.db.get(`SELECT o.operation_id, o.status, o.input_json
+    FROM run_controller_operations o JOIN run_controllers c ON c.controller_id = o.controller_id
+    WHERE c.project_id = ? AND c.run_id = ? AND o.operation_id = c.controller_id || ':answer:' || ?`, [project.id, input.runId, input.requestId]);
+    if (prior) {
+        const retained = JSON.parse(prior.input_json);
+        if (retained.pause_id !== input.pauseId)
+            throw new AppError("runtime_request_conflict", "HITL answer request id belongs to another pause", 1, { operation_id: prior.operation_id });
+        return { kind: "replay", operationId: prior.operation_id, status: prior.status };
+    }
+    const { bytes } = prepareFileBytes(input.answerFile, "HITL answer");
+    if (!bytes.toString("utf8").trim())
+        throw new AppError("validation", "HITL answer must not be empty", 2);
     const row = context.db.get("SELECT * FROM run_controllers WHERE project_id = ? AND run_id = ? AND status NOT IN ('completed','cancelled','superseded')", [project.id, input.runId]);
     if (!row)
         throw new AppError("not_found", "RUN has no managed controller for this answer", 1);
-    const bytes = fs.readFileSync(path.resolve(input.answerFile));
-    if (!bytes.toString("utf8").trim())
-        throw new AppError("validation", "HITL answer must not be empty", 2);
     const operationId = `${row.controller_id}:answer:${input.requestId}`;
     const answerHash = digestBytes(bytes);
     const hash = digest({ pause_id: input.pauseId, answer_sha256: answerHash });
+    prepareControllerAnswerAcceptance(context, input, project.id, row, operationId, hash);
+    return { kind: "create", project, row, bytes, operationId, answerHash, hash };
+}
+function prepareControllerAnswerAcceptance(context, input, projectId, row, operationId, hash) {
+    const prior = context.db.get("SELECT input_hash, status FROM run_controller_operations WHERE operation_id = ?", [operationId]);
+    if (prior) {
+        if (prior.input_hash !== hash)
+            throw new AppError("runtime_request_conflict", "HITL answer request id has different raw input", 1);
+        return { prior };
+    }
+    const currentOwner = requireController(context, row.controller_id);
+    if (["completed", "cancelled", "superseded"].includes(currentOwner.status))
+        throw new AppError("invalid_run_state", "The answer's controller is no longer current", 1);
+    const competing = context.db.get("SELECT operation_id FROM run_controller_operations WHERE controller_id = ? AND json_extract(input_json, '$.action') = 'user_answer' AND json_extract(input_json, '$.pause_id') = ? LIMIT 1", [row.controller_id, input.pauseId]);
+    if (competing)
+        throw new AppError("runtime_request_conflict", "This HITL pause already has an accepted answer", 1, { operation_id: competing.operation_id });
+    const run = requireRun(context, projectId, input.runId);
+    if (["done", "failed", "cancelled"].includes(run.status))
+        throw new AppError("invalid_run_state", "A terminal RUN cannot accept a new answer", 1);
+    const index = JSON.parse(run.index_json);
+    const stage = index.stage_runs.find(stage => stage.pause?.id === input.pauseId && ["paused", "waiting_for_user"].includes(stage.status));
+    if (!stage?.pause?.work_id)
+        throw new AppError("hitl_pause_mismatch", "Answer does not match the RUN's current HITL pause", 1);
+    return { run, stage, workId: stage.pause.work_id };
+}
+export function answerRunController(context, input, prepared = prepareRunControllerAnswer(context, input)) {
+    if (prepared.kind === "replay")
+        return { ok: true, operation_id: prepared.operationId, status: prepared.status, reused: true };
+    const { project, row, bytes, operationId, answerHash, hash } = prepared;
     context.db.beginWriteTransaction();
     try {
-        const prior = context.db.get("SELECT input_hash, status FROM run_controller_operations WHERE operation_id = ?", [operationId]);
-        if (prior) {
-            if (prior.input_hash !== hash)
-                throw new AppError("runtime_request_conflict", "HITL answer request id has different raw input", 1);
+        // Recheck only mutable acceptance state under the write transaction; bytes are already prepared.
+        const acceptance = prepareControllerAnswerAcceptance(context, input, project.id, row, operationId, hash);
+        if (acceptance.prior) {
             context.db.exec("COMMIT");
-            return { ok: true, operation_id: operationId, status: prior.status, reused: true };
+            return { ok: true, operation_id: operationId, status: acceptance.prior.status, reused: true };
         }
-        const currentOwner = requireController(context, row.controller_id);
-        if (["completed", "cancelled", "superseded"].includes(currentOwner.status))
-            throw new AppError("invalid_run_state", "The answer's controller is no longer current", 1);
-        const competing = context.db.get("SELECT operation_id FROM run_controller_operations WHERE controller_id = ? AND json_extract(input_json, '$.action') = 'user_answer' AND json_extract(input_json, '$.pause_id') = ? LIMIT 1", [row.controller_id, input.pauseId]);
-        if (competing)
-            throw new AppError("runtime_request_conflict", "This HITL pause already has an accepted answer", 1, { operation_id: competing.operation_id });
-        const run = requireRun(context, project.id, input.runId);
-        if (["done", "failed", "cancelled"].includes(run.status))
-            throw new AppError("invalid_run_state", "A terminal RUN cannot accept a new answer", 1);
-        const index = JSON.parse(run.index_json);
-        const stage = index.stage_runs.find(stage => stage.pause?.id === input.pauseId && ["paused", "waiting_for_user"].includes(stage.status));
-        if (!stage?.pause?.work_id)
-            throw new AppError("hitl_pause_mismatch", "Answer does not match the RUN's current HITL pause", 1);
+        const { run, stage, workId } = acceptance;
         const file = path.join(row.state_dir, `answer-${digest(operationId)}.md`);
         try {
             fs.writeFileSync(file, bytes, { flag: "wx", mode: 0o600 });
@@ -336,7 +370,7 @@ export function answerRunController(context, input) {
         }
         const now = context.now();
         const generation = recoveryGuard(context, project.id, run.id)?.generation ?? row.generation;
-        context.db.run("INSERT INTO run_controller_operations (operation_id, controller_id, generation, input_hash, input_json, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'accepted', ?, ?)", [operationId, row.controller_id, generation, hash, JSON.stringify({ action: "user_answer", pause_id: input.pauseId, stage: stage.stage, work_id: stage.pause.work_id, file, sha256: answerHash }), now, now]);
+        context.db.run("INSERT INTO run_controller_operations (operation_id, controller_id, generation, input_hash, input_json, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'accepted', ?, ?)", [operationId, row.controller_id, generation, hash, JSON.stringify({ action: "user_answer", pause_id: input.pauseId, stage: stage.stage, work_id: workId, file, sha256: answerHash }), now, now]);
         appendEvent(context, row.controller_id, "answer_accepted", { operation_id: operationId, pause_id: input.pauseId, answer_sha256: answerHash });
         context.db.exec("COMMIT");
         return { ok: true, operation_id: operationId, status: "accepted" };
@@ -346,13 +380,29 @@ export function answerRunController(context, input) {
         throw error;
     }
 }
-/** Publish a missing stage slice without giving the submitting client dispatch rights. */
-export function supplyRunControllerContext(context, input) {
+export function prepareRunControllerContext(context, input) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(input.requestId) || !/^[a-z][a-z-]*$/.test(input.stage) || !/^[a-f0-9]{64}$/.test(input.contextSha256))
         throw new AppError("usage", "Context submission requires request id, stage and SHA-256", 2);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const operationId = `${input.controllerId}:context:${input.requestId}`;
     const hash = digest({ stage: input.stage, sha256: input.contextSha256 });
+    const row = requireController(context, input.controllerId);
+    if (row.project_id !== project.id || row.run_id !== input.runId)
+        throw new AppError("controller_owner_mismatch", "Context submission belongs to another RUN", 1);
+    const prior = context.db.get("SELECT input_hash, status FROM run_controller_operations WHERE operation_id = ?", [operationId]);
+    if (prior) {
+        if (prior.input_hash !== hash)
+            throw new AppError("runtime_request_conflict", "Context request id has different inputs", 1);
+        return { kind: "replay", operationId, status: prior.status };
+    }
+    availableControllerContext(context, input, row);
+    const { bytes } = loadExternalStageContext({ file: input.contextFile, expectedSha256: input.contextSha256, stage: input.stage });
+    return { kind: "create", project, operationId, hash, bytes };
+}
+export function supplyRunControllerContext(context, input, prepared = prepareRunControllerContext(context, input)) {
+    if (prepared.kind === "replay")
+        return { ok: true, operation_id: prepared.operationId, status: prepared.status, reused: true };
+    const { project, operationId, hash, bytes } = prepared;
     context.db.beginWriteTransaction();
     try {
         const row = requireController(context, input.controllerId);
@@ -365,16 +415,7 @@ export function supplyRunControllerContext(context, input) {
             context.db.exec("COMMIT");
             return { ok: true, operation_id: operationId, status: prior.status, reused: true };
         }
-        assertRunMutationAllowed(context, project.id, input.runId, row.generation);
-        if (!["starting", "running", "waiting_for_context", "waiting_for_user", "waiting_for_children", "waiting_for_capacity", "waiting_for_merge"].includes(row.status))
-            throw new AppError("invalid_run_state", "Controller cannot accept a new context in its current state", 1);
-        const manifest = JSON.parse(row.manifest_json);
-        if (manifest.contexts[input.stage])
-            throw new AppError("stage_context_replacement", "Controller already has an immutable context for this stage", 1);
-        loadExternalStageContext({ file: input.contextFile, expectedSha256: input.contextSha256, stage: input.stage });
-        const bytes = fs.readFileSync(input.contextFile);
-        if (digestBytes(bytes) !== input.contextSha256)
-            throw new AppError("context_checksum_mismatch", "Context changed before publication", 2);
+        const manifest = availableControllerContext(context, input, row);
         const file = path.join(row.state_dir, `${input.stage}.context.json`);
         try {
             fs.writeFileSync(file, bytes, { flag: "wx", mode: 0o600 });
@@ -398,6 +439,15 @@ export function supplyRunControllerContext(context, input) {
         throw error;
     }
 }
+function availableControllerContext(context, input, row) {
+    assertRunMutationAllowed(context, row.project_id, input.runId, row.generation);
+    if (!["starting", "running", "waiting_for_context", "waiting_for_user", "waiting_for_children", "waiting_for_capacity", "waiting_for_merge"].includes(row.status))
+        throw new AppError("invalid_run_state", "Controller cannot accept a new context in its current state", 1);
+    const manifest = JSON.parse(row.manifest_json);
+    if (manifest.contexts[input.stage])
+        throw new AppError("stage_context_replacement", "Controller already has an immutable context for this stage", 1);
+    return manifest;
+}
 async function executeController(context, row, manifest, state, assertOwnership, assertPhysicalOwner) {
     assertOwnership();
     const observer = { ...context, db: getDatabase(context.ddFlowHome, "read_existing") };
@@ -580,6 +630,8 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     continue;
                 }
                 loadExternalStageContext({ file: stageContext.file, expectedSha256: stageContext.sha256, stage: next.stage });
+                const continuation = JSON.stringify(["start_stage", next.stage, next.attempt ?? null]);
+                retainControllerContinuation(state, continuation, { code: "stage_entry_nonprogressing", message: "The coordinator returned without starting the assigned Stage", details: { stage: next.stage, attempt: next.attempt ?? null, last_receipt: state.last_receipt ?? null } });
                 const transition = resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy, profiles, ...(state.stage ? { fromStage: state.stage } : {}), stage: next.stage, stageSessionMode: manifest.execution_profile.settings.stage_session_mode, mergeMode: manifest.execution_profile.settings.merge_mode });
                 if (next.stage === "merge" && manifest.execution_profile.settings.merge_mode === "server" && !state.merge_claim) {
                     const request = context.db.get("SELECT merge_request_id, status FROM merge_requests WHERE project_id = ? AND run_id = ? ORDER BY created_at DESC, merge_request_id DESC LIMIT 1", [row.project_id, row.run_id]);
@@ -629,7 +681,6 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 }
                 state.native_baseline = controllerNativeChildren(state.last_receipt ?? {}, session.id).map(child => child.session_id);
                 state.stage = next.stage;
-                state.last_continuation = null;
                 saveState(context, row, state);
                 setStatus("running");
                 if (next.stage === "code" || next.stage === "code-review") {
@@ -692,9 +743,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 saveState(context, row, state);
                 continue;
             }
-            if (state.last_continuation === fanout.fingerprint)
-                throw new AppError("fanout_stage_nonprogressing", "The coordinator repeated an unchanged Work-graph continuation", 1, { stage: next.stage });
-            state.last_continuation = fanout.fingerprint;
+            retainControllerContinuation(state, fanout.fingerprint, { code: "fanout_stage_nonprogressing", message: "The coordinator repeated an unchanged Work-graph continuation", details: { stage: next.stage } });
             saveState(context, row, state);
             await prompt(session, fanout.prompt);
         }
@@ -713,20 +762,17 @@ async function executeController(context, row, manifest, state, assertOwnership,
     }
 }
 function readContexts(file, expected) {
-    const bytes = fs.readFileSync(path.resolve(file));
+    const { bytes } = prepareFileBytes(file, "Managed context package");
     if (digestBytes(bytes) !== expected)
         throw new AppError("context_checksum_mismatch", "Managed context package SHA-256 differs", 2);
-    const value = JSON.parse(bytes.toString("utf8"));
-    if (value.schema_id !== "dd-flow/managed-context@1" || !value.stages || typeof value.stages !== "object" || Array.isArray(value.stages) || Object.keys(value).some(key => !["schema_id", "stages"].includes(key)))
+    const value = prepareJsonText(bytes.toString("utf8"), { file, label: "Managed context package" }).value;
+    if (!value || value.schema_id !== "dd-flow/managed-context@1" || !value.stages || typeof value.stages !== "object" || Array.isArray(value.stages) || Object.keys(value).some(key => !["schema_id", "stages"].includes(key)))
         throw new AppError("validation", "Expected dd-flow/managed-context@1 with stage file/hash references", 2);
     const result = {};
     for (const [stage, source] of Object.entries(value.stages)) {
         if (!/^[a-z][a-z-]*$/.test(stage) || !source || typeof source !== "object" || Object.keys(source).some(key => !["file", "sha256"].includes(key)) || typeof source.file !== "string" || !path.isAbsolute(source.file) || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256))
             throw new AppError("validation", "Invalid managed stage context reference", 2);
-        loadExternalStageContext({ file: source.file, expectedSha256: source.sha256, stage });
-        const content = fs.readFileSync(source.file);
-        if (digestBytes(content) !== source.sha256)
-            throw new AppError("context_checksum_mismatch", "Stage context changed while freezing the launch", 2);
+        const { bytes: content } = loadExternalStageContext({ file: source.file, expectedSha256: source.sha256, stage });
         result[stage] = { bytes: content, sha256: source.sha256 };
     }
     return result;

package/dist/services/run-fork.js

@@ -4,19 +4,28 @@ import path from "node:path";
 import { createContext } from "../runtime/context.js";
 import { AppError } from "../shared/errors.js";
 import { canonicalPath } from "../storage/paths.js";
-import { installCurrentEngine, upgradeForkedRunEngine } from "./engines.js";
-import { restoreEvalRunSnapshot } from "./eval-snapshots.js";
-/** Restore a sealed stage boundary into its own home and replace only its
- * copied engine binding.  The original snapshot and RUN are read-only. */
-export function forkRunFromSnapshot(context, input) {
+import { installCurrentEngine, upgradeForkedRunEngine, prepareForkEngine } from "./engines.js";
+import { restoreEvalRunSnapshot, prepareEvalRunSnapshot, prepareEvalRunRestore } from "./eval-snapshots.js";
+export function prepareRunFork(input) {
     const requestId = requireId(input.requestId, "request-id");
-    const snapshot = canonicalPath(input.snapshot);
-    const output = path.resolve(input.output);
+    const snapshot = canonicalPath(input.snapshot, false);
+    const output = canonicalPath(input.output, false);
     if (snapshot === output || snapshot.startsWith(`${output}${path.sep}`) || output.startsWith(`${snapshot}${path.sep}`)) {
         throw new AppError("fork_path_conflict", "Fork output must not contain or be contained by its source snapshot", 2, { snapshot, output });
     }
     const manifestFile = path.join(snapshot, "snapshot.json");
-    const manifest = readJson(manifestFile);
+    const intentFile = path.join(output, ".fork-intent.json");
+    const receiptFile = path.join(output, "fork.json");
+    const engineVersion = requireText(input.engineVersion, "engine-version");
+    if (fs.existsSync(receiptFile)) {
+        const receipt = readJson(receiptFile);
+        const prior = receipt?.intent;
+        if (!prior || prior.request_id !== requestId || prior.snapshot !== snapshot || prior.engine_version !== engineVersion || prior.integrity_checksum !== (input.integrityChecksum ?? null))
+            throw new AppError("fork_request_conflict", "Fork output already belongs to another request", 1, { output });
+        return { receipt, output };
+    }
+    prepareForkEngine(engineVersion, input.integrityChecksum);
+    const manifest = prepareEvalRunSnapshot(snapshot);
     if (manifest.schema_id !== "dd-flow/eval-run-snapshot@5" || manifest.purpose !== "stage_entry" || typeof manifest.stage_entry !== "string" || typeof manifest.run_id !== "string") {
         throw new AppError("fork_checkpoint_invalid", "Fork requires a sealed stage-entry snapshot", 2, { snapshot });
     }
@@ -25,34 +34,39 @@ export function forkRunFromSnapshot(context, input) {
         request_id: requestId,
         snapshot,
         snapshot_sha256: fileHash(manifestFile),
-        engine_version: requireText(input.engineVersion, "engine-version"),
+        engine_version: engineVersion,
         integrity_checksum: input.integrityChecksum ?? null,
         target_stage: manifest.stage_entry
     };
-    const intentFile = path.join(output, ".fork-intent.json");
-    const receiptFile = path.join(output, "fork.json");
-    if (fs.existsSync(receiptFile)) {
-        const receipt = readJson(receiptFile);
-        if (hash(receipt.intent) !== hash(intent))
-            throw new AppError("fork_request_conflict", "Fork output already belongs to another request", 1, { output });
-        return receipt;
-    }
+    assertForkOutput(output, intentFile, intent);
+    return { manifest, snapshot, output, intent, intentFile, receiptFile, requestId };
+}
+function assertForkOutput(output, intentFile, intent) {
+    if (fs.existsSync(output) && !fs.statSync(output).isDirectory())
+        throw new AppError("fork_output_not_empty", "Fork output must be a directory", 2, { output });
     if (fs.existsSync(output) && fs.readdirSync(output).length > 0) {
         if (!fs.existsSync(intentFile) || hash(readJson(intentFile).intent) !== hash(intent))
             throw new AppError("fork_output_not_empty", "Fork output must be empty", 2, { output });
         const unknown = fs.readdirSync(output).filter(name => ![".fork-intent.json", "project", "dd-flow-home"].includes(name));
         if (unknown.length)
             throw new AppError("fork_retry_inspect_required", "Fork output contains data not owned by the interrupted fork", 1, { output, unknown });
-        for (const name of ["project", "dd-flow-home"])
-            fs.rmSync(path.join(output, name), { recursive: true, force: true });
     }
+}
+export function forkRunFromSnapshot(context, input, prepared = prepareRunFork(input)) {
+    if ("receipt" in prepared)
+        return prepared.receipt;
+    const { manifest, snapshot, output, intent, intentFile, receiptFile, requestId } = prepared;
+    assertForkOutput(output, intentFile, intent);
+    for (const name of ["project", "dd-flow-home"])
+        fs.rmSync(path.join(output, name), { recursive: true, force: true });
     fs.mkdirSync(output, { recursive: true, mode: 0o700 });
     writeJsonAtomic(intentFile, { schema_id: "dd-flow/run-fork-intent@1", intent });
     const projectRoot = path.join(output, "project");
     const home = path.join(output, "dd-flow-home");
     fs.mkdirSync(projectRoot, { recursive: true, mode: 0o700 });
     const targetContext = createContext({ ...context.env, DD_FLOW_HOME: home, DD_FLOW_ENGINE_MODE: "1" });
-    const restored = restoreEvalRunSnapshot(targetContext, { snapshot, projectRoot });
+    const restoreInput = { snapshot, projectRoot };
+    const restored = restoreEvalRunSnapshot(targetContext, restoreInput, prepareEvalRunRestore(targetContext, restoreInput, manifest));
     const restoredContext = createContext({ ...context.env, DD_FLOW_HOME: home, DD_FLOW_ENGINE_MODE: "1" });
     try {
         const runHome = String(restored.run_home);
@@ -69,8 +83,8 @@ export function forkRunFromSnapshot(context, input) {
         };
         writeJsonAtomic(path.join(runHome, "fork-lineage.json"), lineage);
         // Install the immutable artifact belonging to the currently executing
-        // CLI into the new home. A different exact version must already be
-        // supplied as an installed engine artifact for this fork home.
+        // CLI into the new home. Its exact version/checksum were checked before
+        // any interrupted-copy cleanup; snapshots exclude installed engines.
         installCurrentEngine(restoredContext, { forRouting: true });
         const binding = upgradeForkedRunEngine(restoredContext, {
             projectRoot,

package/dist/services/run-recovery.js

@@ -51,12 +51,21 @@ export function requireRecoveryRun(context, projectId, runId) {
         throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1, { run_id: runId });
     return run;
 }
-function parseObject(value, label) { try {
-    const parsed = JSON.parse(value);
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
-        return parsed;
+export function prepareRecoveryPayload(value, label) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new AppError("invalid_json", `${label} must be valid JSON`, 2);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new AppError("validation", `${label} must be a JSON object`, 2);
+    const payload = parsed;
+    if (label === "settlement" && payload.settled !== true)
+        throw new AppError("recovery_not_settled", "Recovery capture requires an explicit settled tree receipt", 1);
+    return payload;
 }
-catch { /* validated below */ } throw new AppError("validation", `${label} must be a JSON object`, 2); }
 export function recoveryGuard(context, projectId, runId) { return context.db.get("SELECT recovery_id, project_id, run_id, generation, status, interruption_json, settlement_json, capture_path, created_at, updated_at, sealed_at, resumed_at FROM run_recovery_guards WHERE project_id = ? AND run_id = ? ORDER BY generation DESC LIMIT 1", [projectId, runId]) ?? null; }
 export function assertRunMutationAllowed(context, projectId, runId, expectedGeneration) {
     const guard = recoveryGuard(context, projectId, runId);
@@ -103,10 +112,9 @@ export function assertRecoveryHookCurrent(context, projectId, runId, identity) {
     if (!identity.daemonId || retired)
         throw new AppError("recovery_daemon_stale", "Lifecycle receipt belongs to an unidentified or retired recovery daemon", 1, { run_id: runId, generation, daemon_id: identity.daemonId });
 }
-export function beginRunRecovery(context, input) {
+export function beginRunRecovery(context, input, interruption = prepareRecoveryPayload(input.interruption, "interruption")) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = requireRecoveryRun(context, project.id, input.runId);
-    const interruption = parseObject(input.interruption, "interruption");
     const recoveryId = `RCV-${crypto.randomUUID()}`, now = context.now();
     let generation;
     context.db.beginWriteTransaction();
@@ -133,15 +141,12 @@ export function beginRunRecovery(context, input) {
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "run_recovery_draining", recovery_id: recoveryId, generation, interruption });
     return { ok: true, recovery: { recovery_id: recoveryId, run_id: run.id, generation, status: "draining", interruption } };
 }
-export function sealRunRecovery(context, input) {
+export function sealRunRecovery(context, input, settlement = prepareRecoveryPayload(input.settlement, "settlement")) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = requireRecoveryRun(context, project.id, input.runId);
     const guard = recoveryGuard(context, project.id, run.id);
     if (!guard || guard.recovery_id !== input.recoveryId)
         throw new AppError("recovery_not_found", "Recovery operation is not registered for this RUN", 1, { recovery_id: input.recoveryId, run_id: run.id });
-    const settlement = parseObject(input.settlement, "settlement");
-    if (settlement.settled !== true)
-        throw new AppError("recovery_not_settled", "Recovery capture requires an explicit settled tree receipt", 1, { recovery_id: guard.recovery_id });
     if (guard.status === "sealed")
         return { ok: true, recovery: { ...guard, settlement: JSON.parse(guard.settlement_json ?? "{}") }, reused: true };
     if (guard.status !== "draining")
@@ -163,7 +168,7 @@ export function sealRunRecovery(context, input) {
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "run_recovery_sealed", recovery_id: guard.recovery_id, generation: guard.generation, settlement });
     return { ok: true, recovery: { recovery_id: guard.recovery_id, run_id: run.id, generation: guard.generation, status: "sealed", settlement } };
 }
-export function recordRecoveryCapture(context, input) {
+export function prepareRecoveryCapture(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = requireRecoveryRun(context, project.id, input.runId);
     const guard = recoveryGuard(context, project.id, run.id);
@@ -175,28 +180,33 @@ export function recordRecoveryCapture(context, input) {
     if (!fs.existsSync(capture))
         throw new AppError("recovery_capture_missing", "Recovery capture path is unavailable", 1, { capture });
     verifyRecoverySnapshot(capture, { runId: run.id, recoveryId: guard.recovery_id, projectRoot: run.project_root, workspaceRoot: run.workspace_root });
+    return { project, run, guard, capture };
+}
+export function recordRecoveryCapture(context, input, prepared = prepareRecoveryCapture(context, input)) {
+    const { project, run, guard, capture } = prepared;
     const updated = context.db.run("UPDATE run_recovery_guards SET capture_path = ?, updated_at = ? WHERE recovery_id = ? AND status = 'sealed' AND (capture_path IS NULL OR capture_path = ?) AND generation = (SELECT MAX(generation) FROM run_recovery_guards WHERE project_id = ? AND run_id = ?)", [capture, context.now(), guard.recovery_id, capture, project.id, run.id]);
     if (updated.changes !== 1)
         throw new AppError("recovery_state_changed", "Recovery state changed before capture could be bound", 1, { recovery_id: guard.recovery_id });
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "run_recovery_capture_ready", recovery_id: guard.recovery_id, capture_path: capture });
     return { ok: true, recovery_id: guard.recovery_id, capture_path: capture };
 }
-export function resumeRunRecovery(context, input) {
+export function prepareRunRecoveryResume(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = requireRecoveryRun(context, project.id, input.runId);
     const guard = recoveryGuard(context, project.id, run.id);
     if (!guard || guard.recovery_id !== input.recoveryId)
         throw new AppError("recovery_not_found", "Recovery operation is not registered for this RUN", 1, { recovery_id: input.recoveryId, run_id: run.id });
-    const acceptCommand = acceptanceCommand(context, run.id, guard.recovery_id, run.project_root);
     if (["resuming", "recovered"].includes(guard.status)) {
         const binding = context.db.get("SELECT * FROM run_recovery_bindings WHERE recovery_id = ?", [guard.recovery_id]);
         if (!binding || binding.daemon_id !== input.daemonId || binding.harness !== input.harness || binding.provider_session_id !== input.nativeSessionId)
             throw new AppError("recovery_binding_mismatch", "Recovery is already pinned to another physical Session", 1);
         recoveryPacketReceipt(binding);
-        return { ok: true, recovery_id: guard.recovery_id, generation: guard.generation, resumed: guard.status === "recovered", awaiting_acceptance: guard.status === "resuming", accept_command: acceptCommand, reused: true };
+        return { project, run, guard, binding, reused: true };
     }
     if (guard.status !== "sealed" || !guard.capture_path)
         throw new AppError("recovery_capture_required", "Recovery must be sealed and captured before it can resume", 1, { recovery_id: guard.recovery_id, status: guard.status });
+    if (!input.daemonId?.trim() || !input.harness?.trim() || !input.nativeSessionId?.trim())
+        throw new AppError("recovery_identity_required", "Recovery requires the replacement daemon and retained native Session identity", 1);
     // The coordinator keeps its same native Session and receives a recovery
     // prompt from the eval runner. At a stage boundary its last WorkSession is
     // completed; that retained identity still authorizes acknowledgement, but
@@ -204,6 +214,13 @@ export function resumeRunRecovery(context, input) {
     // Only delegated Work is returned to the ready graph and therefore gets a
     // fresh, addressable recovery packet.
     verifyRecoverySnapshot(guard.capture_path, { runId: run.id, recoveryId: guard.recovery_id, projectRoot: run.project_root, workspaceRoot: run.workspace_root });
+    return { project, run, guard, reused: false };
+}
+export function resumeRunRecovery(context, input, prepared = prepareRunRecoveryResume(context, input)) {
+    const { project, run, guard } = prepared;
+    const acceptCommand = acceptanceCommand(context, run.id, guard.recovery_id, run.project_root);
+    if (prepared.reused)
+        return { ok: true, recovery_id: guard.recovery_id, generation: guard.generation, resumed: guard.status === "recovered", awaiting_acceptance: guard.status === "resuming", accept_command: acceptCommand, reused: true };
     const now = context.now();
     let running = [];
     context.db.beginWriteTransaction();
@@ -211,8 +228,6 @@ export function resumeRunRecovery(context, input) {
         const current = recoveryGuard(context, project.id, run.id);
         if (!current || current.recovery_id !== guard.recovery_id || current.generation !== guard.generation || current.status !== "sealed" || current.capture_path !== guard.capture_path)
             throw new AppError("recovery_state_changed", "Recovery state changed before its resume transaction", 1, { recovery_id: guard.recovery_id });
-        if (!input.daemonId?.trim() || !input.harness?.trim() || !input.nativeSessionId?.trim())
-            throw new AppError("recovery_identity_required", "Recovery requires the replacement daemon and retained native Session identity", 1);
         const owner = context.db.get(`
       SELECT w.work_id, ws.id, ws.session_id, s.harness, s.provider_session_id,
         w.status AS work_status, ws.status AS session_status