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

package/dist/services/engines.js

@@ -12,6 +12,7 @@ import { requireProtocol } from "./protocols.js";
 import { resolveCanonRootBeforeContext } from "./canon.js";
 import { appendAudit } from "./audit.js";
 import { findProjectByRoot } from "./projects.js";
+import { parseCommandArgs } from "./lifecycle-command.js";
 import { allRunEngineBindings, locateRunRoot, readRunEngineBinding, runEngineBindingSchemaId, writeRunEngineBinding } from "./run-engine-bindings.js";
 export const engineManifestSchemaId = "dd-flow/engine-manifest@1";
 const routerNativeFamilies = new Set(["engine", "version", "schema"]);
@@ -181,7 +182,8 @@ export function routeArgsThroughEngine(context, args, io, stdin, env, resolvedPr
     const entrypoint = resolveManifestEntrypoint(selection.selected);
     return spawnEngine(selection.selected, entrypoint, args, io, stdin, env, current.version);
 }
-export function bindRunEngine(context, input) {
+export function prepareRunEngineBind(context, input) {
+    const reason = requiredText(input.reason, "reason");
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const located = locateRunRoot(context.db, projectRoot, input.runId);
     if (!located)
@@ -191,19 +193,31 @@ export function bindRunEngine(context, input) {
         packageName: input.packageName ?? getCliBuildInfo().package_name,
         packageVersion: input.engineVersion,
         ...(input.integrityChecksum ? { integrityChecksum: input.integrityChecksum } : {})
-    });
+    }, { checkEntrypoint: false });
     const requested = engineIdentity(manifest);
     if (existing) {
         if (sameEngineIdentity(existing.engine, requested))
-            return { ok: true, action: "run_engine_bind", changed: false, binding: existing };
+            return { kind: "replay", binding: existing };
         throw new AppError("run_engine_binding_immutable", "RUN engine binding cannot be changed", 1, {
             run_id: located.run_id,
             current: existing.engine,
             requested
         });
     }
+    return { kind: "create", projectRoot, located, manifest, requested, reason, entrypoint: resolveManifestEntrypoint(manifest) };
+}
+export function bindRunEngine(context, input, prepared = prepareRunEngineBind(context, input)) {
+    if (prepared.kind === "replay")
+        return { ok: true, action: "run_engine_bind", changed: false, binding: prepared.binding };
+    const { projectRoot, located, manifest, requested, reason, entrypoint } = prepared;
+    const existing = readRunEngineBinding(located.binding_path, { allowMissing: true });
+    if (existing) {
+        if (sameEngineIdentity(existing.engine, requested))
+            return { ok: true, action: "run_engine_bind", changed: false, binding: existing };
+        throw new AppError("run_engine_binding_immutable", "RUN engine binding cannot be changed", 1, { run_id: located.run_id, current: existing.engine, requested });
+    }
     const probeArgs = ["run", "status", located.run_id, "--project-root", projectRoot, "--json"];
-    const probe = spawnSync(process.execPath, [resolveManifestEntrypoint(manifest), ...probeArgs], {
+    const probe = spawnSync(process.execPath, [entrypoint, ...probeArgs], {
         cwd: manifest.snapshot_root,
         env: { ...process.env, ...context.env, DD_FLOW_HOME: context.ddFlowHome, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: manifest.snapshot_root },
         encoding: "utf8",
@@ -224,7 +238,7 @@ export function bindRunEngine(context, input) {
         project_root: projectRoot,
         bound_at: context.now(),
         source: "legacy_recovery",
-        reason: requiredText(input.reason, "reason"),
+        reason,
         engine: requested,
         probe: { status: "passed", command: `dd-flow ${probeArgs.join(" ")}` }
     };
@@ -325,7 +339,7 @@ function runIdForArgs(args) {
         return option(parsed, "run");
     return null;
 }
-function requireBoundManifest(ddFlowHome, input) {
+function requireBoundManifest(ddFlowHome, input, options = {}) {
     const manifest = input.snapshotRoot
         ? requireManifest(path.join(input.snapshotRoot, "engine.json"))
         : findInstalledManifest(ddFlowHome, {
@@ -338,7 +352,7 @@ function requireBoundManifest(ddFlowHome, input) {
         || manifest.package_version !== input.packageVersion
         || input.integrityChecksum !== undefined && manifest.integrity.checksum !== input.integrityChecksum
         || input.snapshotRoot !== undefined && path.resolve(manifest.snapshot_root) !== path.resolve(input.snapshotRoot)
-        || !manifestHealthy(manifest)) {
+        || manifestDiagnostics(manifest, options).length !== 0) {
         throw new AppError("run_engine_binding_invalid", "RUN engine binding points to a missing or unhealthy engine snapshot", 1, {
             package_name: input.packageName,
             package_version: input.packageVersion,
@@ -379,7 +393,7 @@ function executionManifest(context) {
     return requireManifest(path.join(String(installed.path), "engine.json"));
 }
 function requiredText(value, label) {
-    const normalized = value.trim();
+    const normalized = typeof value === "string" ? value.trim() : "";
     if (!normalized)
         throw new AppError("usage", `Missing required value: ${label}`, 2);
     return normalized;
@@ -591,35 +605,11 @@ function canonCompatibilitySha(memorybankRoot) {
         return null;
     }
 }
-function parseLightArgs(args) {
-    const positional = [];
-    const options = new Map();
-    for (let index = 0; index < args.length; index += 1) {
-        const value = args[index];
-        if (value?.startsWith("--")) {
-            const equal = value.indexOf("=");
-            if (equal > 2) {
-                const key = value.slice(2, equal);
-                options.set(key, [...(options.get(key) ?? []), value.slice(equal + 1)]);
-                continue;
-            }
-            const key = value.slice(2);
-            const next = args[index + 1];
-            if (!next || next.startsWith("--"))
-                options.set(key, [...(options.get(key) ?? []), ""]);
-            else {
-                options.set(key, [...(options.get(key) ?? []), next]);
-                index += 1;
-            }
-        }
-        else if (value)
-            positional.push(value);
-    }
-    return { positional, options };
-}
+const parseLightArgs = parseCommandArgs;
 function option(parsed, key) {
     const values = parsed.options.get(key);
-    return values?.[values.length - 1] || null;
+    const value = values?.[values.length - 1];
+    return value && value !== "__dd_flow_flag__" ? value : null;
 }
 function positional(parsed, index) {
     return parsed.positional[index] ?? null;
@@ -651,23 +641,37 @@ function buildManifest(context, packageName, version, packageRoot, snapshotRoot,
     };
 }
 function copyPackageSnapshot(packageRoot, target) {
+    for (const [relative, source] of packageSnapshotFiles(packageRoot)) {
+        const destination = path.join(target, relative);
+        ensureDir(path.dirname(destination));
+        fs.copyFileSync(source, destination);
+    }
+}
+/** The same source inventory drives validation and copying; no staging writes. */
+function packageSnapshotFiles(packageRoot) {
+    const files = new Map();
+    const collect = (source, relative, skipNodeModules = false) => {
+        if (!fs.statSync(source).isDirectory()) {
+            files.set(relative, source);
+            return;
+        }
+        for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+            if (skipNodeModules && entry.name === "node_modules")
+                continue;
+            const child = path.join(source, entry.name), name = path.join(relative, entry.name);
+            if (entry.isDirectory())
+                collect(child, name, skipNodeModules);
+            else if (entry.isFile())
+                files.set(name, child);
+        }
+    };
     for (const item of ["dist", "package.json", "README.md", "CHANGELOG.md", "tools"]) {
         const from = path.join(packageRoot, item);
         if (!fs.existsSync(from))
             continue;
-        const to = path.join(target, item);
-        const stat = fs.statSync(from);
-        if (stat.isDirectory())
-            copyDir(from, to);
-        else {
-            ensureDir(path.dirname(to));
-            fs.copyFileSync(from, to);
-        }
+        collect(from, item);
     }
-    copyProductionDependencies(packageRoot, target);
-}
-function copyProductionDependencies(packageRoot, target) {
-    const queue = [{ sourceRoot: packageRoot, targetRoot: target, ancestors: new Set() }];
+    const queue = [{ sourceRoot: packageRoot, targetRoot: "", ancestors: new Set() }];
     const copied = new Set();
     while (queue.length > 0) {
         const current = queue.shift();
@@ -682,12 +686,35 @@ function copyProductionDependencies(packageRoot, target) {
             if (copied.has(copyKey))
                 continue;
             copied.add(copyKey);
-            copyDir(sourceRoot, targetRoot, true);
+            collect(sourceRoot, targetRoot, true);
             if (current.ancestors.has(sourceRoot))
                 continue;
             queue.push({ sourceRoot, targetRoot, ancestors: new Set([...current.ancestors, sourceRoot]) });
         }
     }
+    return files;
+}
+export function prepareForkEngine(engineVersion, integrityChecksum) {
+    const build = getCliBuildInfo();
+    if (engineVersion !== build.version)
+        throw new AppError("fork_engine_unavailable", "Fork installs the invoking CLI engine; invoke the requested version to upgrade the fork", 2, { requested: engineVersion, available: build.version });
+    const packageRoot = findPackageRoot(path.dirname(sourceFile));
+    if (!packageRoot || !fs.existsSync(path.join(packageRoot, "dist", "cli.js")))
+        throw new AppError("harness_runtime_unbuilt", "Build the CLI before preparing a fork", 1);
+    const files = packageSnapshotFiles(packageRoot);
+    if (integrityChecksum !== undefined) {
+        const checksum = crypto.createHash("sha256");
+        for (const [relative, source] of [...files].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+            if (path.basename(relative) === "engine.json")
+                continue;
+            checksum.update(relative);
+            checksum.update("\0");
+            checksum.update(fs.readFileSync(source));
+            checksum.update("\0");
+        }
+        if (checksum.digest("hex") !== integrityChecksum)
+            throw new AppError("fork_engine_unavailable", "Requested engine checksum differs from the invoking CLI artifact", 2, { requested: integrityChecksum });
+    }
 }
 function readProductionDependencies(packageRoot) {
     try {
@@ -744,19 +771,6 @@ function hasAncestorFile(start, name) {
         current = parent;
     }
 }
-function copyDir(from, to, skipNodeModules = false) {
-    ensureDir(to);
-    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
-        if (skipNodeModules && entry.name === "node_modules")
-            continue;
-        const source = path.join(from, entry.name);
-        const target = path.join(to, entry.name);
-        if (entry.isDirectory())
-            copyDir(source, target, skipNodeModules);
-        else if (entry.isFile())
-            fs.copyFileSync(source, target);
-    }
-}
 function acquireInstallLock(lockDir) {
     ensureDir(path.dirname(lockDir));
     try {

package/dist/services/eval-snapshots.js

@@ -14,8 +14,9 @@ import { readVnextFlowDefinition } from "./vnext-specify.js";
 import { captureRecoveryDatabase, readRecoveryResourceEvidence } from "./recovery-snapshot-database.js";
 import { resourceHome } from "./managed-processes.js";
 import { codexHomeSharedEntries } from "./hooks.js";
+import { prepareOutputFile } from "../cli/input-preparation.js";
 /** Capture the only flow boundary which exists before `stage start --bootstrap` creates a RUN. */
-export function createEvalBootstrapSnapshot(context, input) {
+export function prepareEvalBootstrapSnapshot(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const output = path.resolve(input.output);
     if (fs.existsSync(output))
@@ -24,6 +25,19 @@ export function createEvalBootstrapSnapshot(context, input) {
         throw new AppError("snapshot_output_inside_project", "Bootstrap snapshot output must be outside the project tree", 1, { output });
     if (isInside(physicalPath(context.ddFlowHome), physicalPath(output)))
         throw new AppError("snapshot_output_inside_runtime", "Bootstrap snapshot output must be outside DD_FLOW_HOME", 1, { output });
+    prepareOutputFile(output);
+    try {
+        prepareSnapshotProjectGit(projectRoot);
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "snapshot_project_git_invalid")
+            throw error;
+        throw new AppError(error.code, error.message, 2, { ...error.details, phase: "prepare", effect: "no_effect", recoverable: true });
+    }
+    return { projectRoot, output };
+}
+export function createEvalBootstrapSnapshot(context, input) {
+    const { projectRoot, output } = prepareEvalBootstrapSnapshot(context, input);
     fs.mkdirSync(output, { recursive: true });
     fs.cpSync(projectRoot, path.join(output, "project"), { recursive: true, verbatimSymlinks: true, filter: snapshotPayloadAllowed });
     const manifest = {
@@ -37,13 +51,18 @@ export function createEvalBootstrapSnapshot(context, input) {
     return { ok: true, snapshot: output, ...manifest };
 }
 /** Restore a pre-RUN project state; `stage start --bootstrap` creates runtime state afterwards. */
-export function restoreEvalBootstrapSnapshot(_context, input) {
+export function prepareEvalBootstrapRestore(input) {
     const snapshot = path.resolve(input.snapshot);
     const manifest = readBootstrapManifest(snapshot);
     const projectRoot = resolveProjectRoot(input.projectRoot);
+    assertRestoreTargetSeparation(snapshot, [projectRoot]);
     const sourceProject = path.join(snapshot, "project");
-    if (treeHash(sourceProject) !== manifest.project_sha256)
-        throw new AppError("snapshot_checksum_mismatch", "Bootstrap project checksum does not match manifest", 1, { snapshot });
+    verifyGitSnapshotPayload(snapshot, { name: "project", hash: manifest.project_sha256, git: manifest.project_git });
+    return { snapshot, manifest, projectRoot, sourceProject };
+}
+export function restoreEvalBootstrapSnapshot(_context, input, prepared = prepareEvalBootstrapRestore(input)) {
+    const { snapshot, manifest, projectRoot, sourceProject } = prepared;
+    assertRestoreTargetSeparation(snapshot, [projectRoot]);
     clearProjectTree(projectRoot, false);
     restoreProjectGit(snapshot, manifest.project_git, projectRoot);
     replaceProjectTree(projectRoot, sourceProject);
@@ -54,9 +73,7 @@ export function restoreEvalBootstrapSnapshot(_context, input) {
  * retain only the selected RUN's relational and filesystem evidence.
  */
 export function createEvalRunSnapshot(context, input) {
-    const output = path.resolve(input.output);
-    if (fs.existsSync(output))
-        throw new AppError("snapshot_exists", "Snapshot output already exists", 1, { output });
+    const { output } = prepareEvalRunSnapshotCreation(context, input);
     const temporary = `${output}.partial-${crypto.randomUUID()}`;
     try {
         input.boundary?.verify();
@@ -89,7 +106,9 @@ export function createEvalRunSnapshot(context, input) {
         throw error;
     }
 }
-function captureEvalRunSnapshot(context, input) {
+export function prepareEvalRunSnapshotCreation(context, input) {
+    if (Number(Boolean(input.candidate)) + Number(Boolean(input.incomplete)) + Number(input.stageEntry !== undefined) + Number(input.recoveryId !== undefined) !== 1)
+        throw new AppError("usage", "Use exactly one of candidate, incomplete, recoveryId or stageEntry", 2, { phase: "prepare", effect: "no_effect", recoverable: true });
     const projectRoot = resolveProjectRoot(input.projectRoot);
     // Snapshot is read-only at the control-plane boundary. An invalid workspace
     // root must fail without registering a second project in a dedicated home.
@@ -129,6 +148,13 @@ function captureEvalRunSnapshot(context, input) {
     const workspaceRoot = String(status.run.workspace_root ?? projectRoot);
     if (isInside(physicalPath(projectRoot), physicalPath(output)) || isInside(physicalPath(workspaceRoot), physicalPath(output)))
         throw new AppError("snapshot_output_inside_project", "Snapshot output must be outside the project and RUN workspace trees", 1, { output });
+    prepareOutputFile(output);
+    prepareSnapshotProjectGit(projectRoot);
+    prepareSnapshotWorkspace(workspaceRoot, projectRoot);
+    return { projectRoot, project, status, recovery, output, workspaceRoot, activeChildren };
+}
+function captureEvalRunSnapshot(context, input) {
+    const { projectRoot, project, status, recovery, output, workspaceRoot, activeChildren } = prepareEvalRunSnapshotCreation(context, input);
     fs.mkdirSync(output, { recursive: true, mode: 0o700 });
     const resourceDatabase = path.join(context.ddFlowHome, "runtime.sqlite");
     const databaseFiles = [context.db.path, resourceDatabase].flatMap(file => [file, `${file}-wal`, `${file}-shm`]);
@@ -217,9 +243,35 @@ function createdWorkSchemaForStage(stage) {
         return "dd-flow/merge-result";
     return null;
 }
-export function restoreEvalRunSnapshot(context, input) {
-    const snapshot = path.resolve(input.snapshot);
+/** Validate sealed source data before any target cleanup or copy. */
+export function prepareEvalRunSnapshot(snapshot) {
     const manifest = readManifest(snapshot);
+    if (manifest.purpose === "incomplete")
+        throw new AppError("snapshot_incomplete_not_restorable", "Incomplete snapshot is forensic evidence, not a stage-entry fixture", 1, { snapshot });
+    if (manifest.purpose === "candidate")
+        throw new AppError("snapshot_candidate_not_restorable", "A terminal candidate snapshot is evidence, not a stage-entry fixture", 1, { snapshot });
+    verifySnapshotPayload(snapshot, manifest);
+    if (manifest.purpose === "stage_entry") {
+        const db = new DatabaseSync(path.join(snapshot, "runtime", "db.sqlite"), { readOnly: true });
+        try {
+            assertSnapshotRuntimeDetachAllowed(sql => db.prepare(sql).get());
+            const row = db.prepare("SELECT index_json FROM runs WHERE id = ?").get(manifest.run_id);
+            if (!row)
+                throw new AppError("snapshot_invalid", "Snapshot RUN is not registered", 1);
+            const index = JSON.parse(row.index_json);
+            if (!Array.isArray(index?.stage_runs))
+                throw new AppError("snapshot_invalid", "Snapshot RUN index is invalid", 1);
+            assertStageEntry(index.stage_runs, manifest.stage_entry);
+        }
+        finally {
+            db.close();
+        }
+    }
+    return manifest;
+}
+export function prepareEvalRunRestore(context, input, preparedManifest) {
+    const snapshot = path.resolve(input.snapshot);
+    const manifest = preparedManifest ?? prepareEvalRunSnapshot(snapshot);
     if (manifest.purpose === "incomplete")
         throw new AppError("snapshot_incomplete_not_restorable", "Incomplete snapshot is forensic evidence, not a stage-entry fixture", 1, { snapshot });
     const recovery = manifest.purpose === "recovery";
@@ -234,24 +286,15 @@ export function restoreEvalRunSnapshot(context, input) {
     if (!recovery && !manifest.stage_entry)
         throw new AppError("snapshot_invalid", "Stage-entry snapshot has no target stage", 1, { snapshot });
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    if (recovery) {
-        if (fs.readdirSync(projectRoot).length || (context.db.get("SELECT COUNT(*) AS count FROM projects")?.count ?? 0) > 0)
-            throw new AppError("recovery_restore_target_not_empty", "Recovery restore requires fresh project and runtime targets", 1);
+    assertRunRestoreTargets(context, input, snapshot, projectRoot, manifest);
+    if (recovery)
         verifyRecoverySnapshot(snapshot, { runId: manifest.run_id, recoveryId: input.recoveryId, projectRoot, workspaceRoot: projectRoot }, false);
-    }
-    const existing = fs.readdirSync(context.ddFlowHome).filter((name) => !["db.sqlite", "db.sqlite-wal", "db.sqlite-shm", ...(input.executionRoutingFile !== undefined ? ["agent-profiles"] : [])].includes(name));
-    if (existing.length > 0)
-        throw new AppError("restore_home_not_empty", "Snapshot restore requires an empty DD_FLOW_HOME", 1, { dd_flow_home: context.ddFlowHome, existing });
-    if (context.db.get("SELECT 1 FROM projects LIMIT 1") || context.db.get("SELECT 1 FROM runs LIMIT 1"))
-        throw new AppError("restore_home_not_empty", "Snapshot restore cannot replace an initialized runtime", 1);
     const sourceRuntime = path.join(snapshot, "runtime");
     const sourceProject = path.join(snapshot, "project");
-    verifySnapshotPayload(snapshot, manifest);
     const routingInput = input.executionRoutingFile !== undefined ? loadExecutionRoutingInput(input.executionRoutingFile) : undefined;
     let selectedProfile;
     if (routingInput) {
-        // Resolve selected profiles from the fresh caller home before replacing it.
-        // Source DB is read-only; no context or migrations may touch the snapshot.
+        // Resolve selected profiles before replacing the caller's fresh runtime.
         const sourceDb = new DatabaseSync(path.join(sourceRuntime, "db.sqlite"), { readOnly: true });
         try {
             const row = sourceDb.prepare("SELECT index_json FROM runs WHERE id = ?").get(manifest.run_id);
@@ -266,11 +309,42 @@ export function restoreEvalRunSnapshot(context, input) {
                     resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy: routingInput.execution, profiles: selectedProfile.agent_profiles, stage: manifest.stage_entry, work: payload.execution_override });
             }
             selectedProfile.routing_input.artifact = `execution-routing.${routingInput.source_checksum}.input.json`;
+            const sourceRun = sourceDb.prepare("SELECT run_root FROM runs WHERE id = ?").get(manifest.run_id);
+            if (typeof sourceRun?.run_root !== "string" || !path.isAbsolute(sourceRun.run_root) || !isInside(manifest.dd_flow_home, sourceRun.run_root))
+                throw new AppError("snapshot_invalid", "Snapshot RUN root must be inside its runtime home", 1);
+            const existingRouting = path.join(sourceRuntime, path.relative(manifest.dd_flow_home, sourceRun.run_root), selectedProfile.routing_input.artifact);
+            if (fs.existsSync(existingRouting) && !fs.readFileSync(existingRouting).equals(routingInput.bytes))
+                throw new AppError("snapshot_checksum_mismatch", "Existing routing input does not match its checksum", 1);
         }
         finally {
             sourceDb.close();
         }
     }
+    return { snapshot, manifest, recovery, projectRoot, sourceRuntime, sourceProject, routingInput, selectedProfile };
+}
+function assertRunRestoreTargets(context, input, snapshot, projectRoot, manifest) {
+    assertRestoreTargetSeparation(snapshot, [projectRoot, context.ddFlowHome]);
+    if (manifest.workspace.kind === "git_worktree") {
+        const workspaceRoot = restoredWorkspaceRoot(manifest, projectRoot, context.ddFlowHome);
+        assertRestoreTargetSeparation(snapshot, [workspaceRoot]);
+        if (isInside(physicalPath(projectRoot), physicalPath(workspaceRoot)) || isInside(physicalPath(workspaceRoot), physicalPath(projectRoot)) || physicalPath(workspaceRoot) === physicalPath(context.ddFlowHome))
+            throw new AppError("snapshot_path_conflict", "Feature workspace overlaps a restore target", 2);
+        if (fs.existsSync(workspaceRoot))
+            throw new AppError("snapshot_workspace_target_exists", "Snapshot feature workspace target already exists", 1, { workspace_root: workspaceRoot });
+    }
+    if (manifest.purpose === "recovery") {
+        if (fs.readdirSync(projectRoot).length || (context.db.get("SELECT COUNT(*) AS count FROM projects")?.count ?? 0) > 0)
+            throw new AppError("recovery_restore_target_not_empty", "Recovery restore requires fresh project and runtime targets", 1);
+    }
+    const existing = (fs.existsSync(context.ddFlowHome) ? fs.readdirSync(context.ddFlowHome) : []).filter((name) => !["db.sqlite", "db.sqlite-wal", "db.sqlite-shm", ...(input.executionRoutingFile !== undefined ? ["agent-profiles"] : [])].includes(name));
+    if (existing.length > 0)
+        throw new AppError("restore_home_not_empty", "Snapshot restore requires an empty DD_FLOW_HOME", 1, { dd_flow_home: context.ddFlowHome, existing });
+    if (context.db.get("SELECT 1 FROM projects LIMIT 1") || context.db.get("SELECT 1 FROM runs LIMIT 1"))
+        throw new AppError("restore_home_not_empty", "Snapshot restore cannot replace an initialized runtime", 1);
+}
+export function restoreEvalRunSnapshot(context, input, prepared = prepareEvalRunRestore(context, input)) {
+    const { snapshot, manifest, recovery, projectRoot, sourceRuntime, sourceProject, routingInput, selectedProfile } = prepared;
+    assertRunRestoreTargets(context, input, snapshot, projectRoot, manifest);
     clearProjectTree(projectRoot, false);
     restoreProjectGit(snapshot, manifest.project_git, projectRoot);
     replaceProjectTree(projectRoot, sourceProject);
@@ -370,12 +444,15 @@ function assertTerminalCandidate(stages) {
 }
 /** A stage-entry import is a new experiment, not a lease takeover or recovery.
  * Keep source authority as evidence, never as executable target inventory. */
-function detachSnapshotRuntimeOwners(context, snapshot, manifest) {
-    const hasTable = (table) => Boolean(context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?", [table]));
-    if (hasTable("run_recovery_guards") && context.db.get("SELECT 1 FROM run_recovery_guards WHERE status IN ('draining','sealed','resuming') LIMIT 1"))
+function assertSnapshotRuntimeDetachAllowed(get) {
+    if (get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'run_recovery_guards'") && get("SELECT 1 FROM run_recovery_guards WHERE status IN ('draining','sealed','resuming') LIMIT 1"))
         throw new AppError("snapshot_control_requires_recovery", "A fenced RUN requires explicit recovery, not a stage-entry fork", 1);
-    if (context.db.get("SELECT 1 FROM merge_requests WHERE status IN ('dispatching','active','waiting_user','action_required','recovery_required') LIMIT 1"))
+    if (get("SELECT 1 FROM merge_requests WHERE status IN ('dispatching','active','waiting_user','action_required','recovery_required') LIMIT 1"))
         throw new AppError("snapshot_execution_active", "A stage-entry fork cannot discard an unresolved MERGE execution", 1);
+}
+function detachSnapshotRuntimeOwners(context, snapshot, manifest) {
+    const hasTable = (table) => Boolean(context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?", [table]));
+    assertSnapshotRuntimeDetachAllowed(sql => context.db.get(sql));
     const detachedTables = ["lifecycle_invocations", "run_control_admissions", "run_control_stage_admissions", "run_control_operations", "run_control_workers", "run_controls", "run_controller_events", "run_controller_operations", "run_controllers", "run_recovery_bindings", "work_recovery_segments", "run_recovery_guards", "work_launches", "merge_servers", "merge_sessions", "lane_locks", "lane_waiters"].filter(hasTable);
     const runTables = Object.fromEntries([...detachedTables, "runs", "merge_requests", "sessions", "work_sessions"].map(table => [table, context.db.all(`SELECT * FROM ${table}`)]));
     const resourceFile = path.join(context.ddFlowHome, "runtime.sqlite");
@@ -496,15 +573,22 @@ function rebaseStructuredValue(value, oldRoot, newRoot, oldWorkspace, newWorkspa
 function rebasePathString(value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) { for (const [oldPrefix, newPrefix] of [[oldHome, newHome], [oldWorkspace, newWorkspace], [oldRoot, newRoot]])
     if (value === oldPrefix || value.startsWith(`${oldPrefix}${path.sep}`))
         return `${newPrefix}${value.slice(oldPrefix.length)}`; return value; }
-function snapshotWorkspace(workspaceRoot, projectRoot, output) {
+function prepareSnapshotWorkspace(workspaceRoot, projectRoot) {
     if (samePath(workspaceRoot, projectRoot))
-        return { kind: "project" };
+        return null;
     const branch = git(workspaceRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
     if (!branch)
         throw new AppError("snapshot_workspace_invalid", "Feature workspace must be on a named Git branch", 1, { workspace_root: workspaceRoot });
     const baseRef = git(workspaceRoot, ["rev-parse", "HEAD"]);
     if (!baseRef)
         throw new AppError("snapshot_workspace_invalid", "Feature workspace has no readable HEAD", 1, { workspace_root: workspaceRoot });
+    return { branch, baseRef };
+}
+function snapshotWorkspace(workspaceRoot, projectRoot, output) {
+    const prepared = prepareSnapshotWorkspace(workspaceRoot, projectRoot);
+    if (!prepared)
+        return { kind: "project" };
+    const { branch, baseRef } = prepared;
     const workspace = path.join(output, "workspace");
     const bundle = path.join(output, "workspace.bundle");
     fs.cpSync(workspaceRoot, workspace, { recursive: true, verbatimSymlinks: true, filter: snapshotPayloadAllowed });
@@ -520,11 +604,7 @@ function restoreWorkspace(snapshot, manifest, projectRoot, ddFlowHome) {
         throw new AppError("snapshot_checksum_mismatch", "Snapshot workspace checksum does not match manifest", 1, { snapshot });
     if (!fs.existsSync(bundle) || fileHash(bundle) !== manifest.workspace.bundle_sha256)
         throw new AppError("snapshot_checksum_mismatch", "Snapshot workspace Git bundle does not match manifest", 1, { snapshot });
-    const managedRoot = physicalPath(manifest.dd_flow_home);
-    const sourceRoot = physicalPath(manifest.workspace.source_root);
-    const workspaceRoot = isInside(managedRoot, sourceRoot)
-        ? path.join(ddFlowHome, path.relative(managedRoot, sourceRoot))
-        : path.join(path.dirname(projectRoot), "workspace");
+    const workspaceRoot = restoredWorkspaceRoot(manifest, projectRoot, ddFlowHome);
     if (fs.existsSync(workspaceRoot))
         throw new AppError("snapshot_workspace_target_exists", "Snapshot feature workspace target already exists", 1, { workspace_root: workspaceRoot });
     runGit(projectRoot, ["fetch", bundle, `+refs/heads/${manifest.workspace.branch}:refs/heads/${manifest.workspace.branch}`]);
@@ -535,14 +615,32 @@ function restoreWorkspace(snapshot, manifest, projectRoot, ddFlowHome) {
     restoreIndex(snapshot, "workspace", manifest.workspace, workspaceRoot);
     return fs.realpathSync(workspaceRoot);
 }
+function restoredWorkspaceRoot(manifest, projectRoot, ddFlowHome) {
+    if (manifest.workspace.kind === "project")
+        return projectRoot;
+    const managedRoot = physicalPath(manifest.dd_flow_home), sourceRoot = physicalPath(manifest.workspace.source_root);
+    return isInside(managedRoot, sourceRoot) ? path.join(ddFlowHome, path.relative(managedRoot, sourceRoot)) : path.join(path.dirname(projectRoot), "workspace");
+}
+function assertRestoreTargetSeparation(snapshot, targets) {
+    const roots = [snapshot, ...targets].map(physicalPath);
+    for (let i = 0; i < roots.length; i++)
+        for (let j = i + 1; j < roots.length; j++) {
+            if (isInside(roots[i], roots[j]) || isInside(roots[j], roots[i]))
+                throw new AppError("snapshot_path_conflict", "Snapshot source and restore targets must not overlap", 2, { source: roots[i], target: roots[j] });
+        }
+}
 function sourceWorkspaceRoot(manifest) {
     return manifest.workspace.kind === "project" ? manifest.project_root : manifest.workspace.source_root;
 }
-function snapshotProjectGit(projectRoot, output) {
+function prepareSnapshotProjectGit(projectRoot) {
     const branch = git(projectRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
     const head = git(projectRoot, ["rev-parse", "HEAD"]);
     if (!branch || !head)
         throw new AppError("snapshot_project_git_invalid", "Snapshot requires a project on a named Git branch with a readable HEAD", 1, { project_root: projectRoot });
+    return { branch, head };
+}
+function snapshotProjectGit(projectRoot, output) {
+    const { branch, head } = prepareSnapshotProjectGit(projectRoot);
     const bundle = path.join(output, "project.bundle");
     runGit(projectRoot, ["bundle", "create", bundle, "--all"]);
     return { branch, head, bundle_sha256: fileHash(bundle), ...snapshotIndex(projectRoot, output, "project") };
@@ -673,10 +771,12 @@ function verifySnapshotPayload(snapshot, manifest) {
         throw new AppError("snapshot_checksum_mismatch", "Snapshot runtime checksum does not match", 1);
     verifySnapshotModes(snapshot, manifest);
     const payloads = [{ name: "project", hash: manifest.project_sha256, git: manifest.project_git }, ...(manifest.workspace.kind === "git_worktree" ? [{ name: "workspace", hash: manifest.workspace.sha256, git: manifest.workspace }] : [])];
-    for (const payload of payloads) {
-        if (treeHash(path.join(snapshot, payload.name)) !== payload.hash || fileHash(path.join(snapshot, `${payload.name}.bundle`)) !== payload.git.bundle_sha256 || payload.git.index_sha256 && fileHash(path.join(snapshot, `${payload.name}.index.patch`)) !== payload.git.index_sha256 || payload.git.index_format === "entries@1" && (!payload.git.index_objects_sha256 || fileHash(path.join(snapshot, `${payload.name}.index.pack`)) !== payload.git.index_objects_sha256))
-            throw new AppError("snapshot_checksum_mismatch", "Snapshot payload or Git index checksum does not match", 1, { payload: payload.name });
-    }
+    for (const payload of payloads)
+        verifyGitSnapshotPayload(snapshot, payload);
+}
+function verifyGitSnapshotPayload(snapshot, payload) {
+    if (treeHash(path.join(snapshot, payload.name)) !== payload.hash || fileHash(path.join(snapshot, `${payload.name}.bundle`)) !== payload.git.bundle_sha256 || payload.git.index_sha256 && fileHash(path.join(snapshot, `${payload.name}.index.patch`)) !== payload.git.index_sha256 || payload.git.index_format === "entries@1" && (!payload.git.index_objects_sha256 || fileHash(path.join(snapshot, `${payload.name}.index.pack`)) !== payload.git.index_objects_sha256))
+        throw new AppError("snapshot_checksum_mismatch", "Snapshot payload or Git index checksum does not match", 1, { payload: payload.name });
 }
 function git(root, args) {
     const result = spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });

package/dist/services/execution-policy.js

@@ -4,26 +4,19 @@ import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { harnessKey } from "./harness-config.js";
 import { vnextStages } from "../domain/stage-catalog.js";
+import { prepareFileBytes, prepareJsonText } from "../cli/input-preparation.js";
 /** Read once so the frozen policy and its provenance describe the same bytes. */
 export function loadExecutionRoutingInput(file) {
-    const source_path = path.resolve(file);
-    let bytes;
-    let value;
-    try {
-        bytes = fs.readFileSync(source_path);
-        value = JSON.parse(bytes.toString("utf8"));
-    }
-    catch {
-        throw new AppError("execution_profile_invalid", "Execution routing input must be a readable JSON file", 2, { source_path });
-    }
+    const { file: source_path, bytes } = prepareFileBytes(file, "execution routing");
+    const value = prepareJsonText(bytes.toString("utf8"), { file: source_path, label: "execution routing" }).value;
     if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new AppError("execution_profile_invalid", "Execution routing input must be an object", 2, { source_path });
+        throw new AppError("execution_profile_invalid", "Execution routing input must be an object", 2, { source_path, phase: "prepare", effect: "no_effect", recoverable: true });
     }
     const input = value;
     if (input.schema_id !== "dd-flow/execution-routing@1"
         || Object.keys(input).some(key => key !== "schema_id" && key !== "execution")
         || !isExecutionRouting(input.execution)) {
-        throw new AppError("execution_profile_invalid", "Execution routing input does not match dd-flow/execution-routing@1", 2, { source_path });
+        throw new AppError("execution_profile_invalid", "Execution routing input does not match dd-flow/execution-routing@1", 2, { source_path, phase: "prepare", effect: "no_effect", recoverable: true });
     }
     return { execution: input.execution, bytes, source_path, source_checksum: crypto.createHash("sha256").update(bytes).digest("hex") };
 }