@deksden-com/dd-flow-cli 0.9.0-beta.37 → 0.9.0-beta.39

package/dist/services/eval-snapshots.js

@@ -2,13 +2,18 @@ import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { registerStoreWriter } from "../storage/writer-contract.js";
 import { createContext } from "../runtime/context.js";
 import { AppError } from "../shared/errors.js";
-import { resolveProjectRoot } from "../storage/paths.js";
+import { resolveProjectRoot, runtimeProtocolDir, runtimeRunDir } from "../storage/paths.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
-import { getFlowRunStatus, startFlowRun } from "./runs.js";
+import { freezeRunExecutionRouting, getFlowRunStatus, importFlowRunExecutionProfile, startFlowRun } from "./runs.js";
+import { loadExecutionRoutingInput, resolveExecutionPolicy } from "./execution-policy.js";
 import { readVnextFlowDefinition } from "./vnext-specify.js";
 import { assertRunWorkResultArtifacts, runWorkResultArtifactIssues } from "./work-registry.js";
+import { captureRecoveryDatabase, readRecoveryResourceEvidence } from "./recovery-snapshot-database.js";
+import { resourceHome } from "./managed-processes.js";
 /** Capture the only flow boundary which exists before `stage start --bootstrap` creates a RUN. */
 export function createEvalBootstrapSnapshot(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
@@ -45,9 +50,8 @@ export function restoreEvalBootstrapSnapshot(_context, input) {
     return { ok: true, schema_id: "dd-eval/bootstrap-restore@1", snapshot, project_root: projectRoot, target_stage: "specify" };
 }
 /**
- * Snapshot a deliberately dedicated DD_FLOW_HOME. Eval checkpoints are not a
- * general runtime export format: a shared home fails closed instead of trying
- * to infer a safe subset of SQLite rows.
+ * Eval fixtures require a dedicated home. Sealed recovery exports instead
+ * retain only the selected RUN's relational and filesystem evidence.
  */
 export function createEvalRunSnapshot(context, input) {
     const output = path.resolve(input.output);
@@ -55,7 +59,13 @@ export function createEvalRunSnapshot(context, input) {
         throw new AppError("snapshot_exists", "Snapshot output already exists", 1, { output });
     const temporary = `${output}.partial-${crypto.randomUUID()}`;
     try {
+        input.boundary?.verify();
+        const sourceVersion = input.boundary ? snapshotSourceVersion(context, input) : null;
         const result = captureEvalRunSnapshot(context, { ...input, output: temporary });
+        if (input.boundary && sourceVersion) {
+            Object.assign(result, { consistency: "controller_boundary_writer_barrier@1", boundary_capture: { controller_id: input.boundary.controllerId, operation_id: input.boundary.operationId, boundary_key: input.boundary.boundaryKey, source_sha256: sourceVersion, observation: input.boundary.observation } });
+            writeJson(path.join(temporary, "snapshot.json"), Object.fromEntries(Object.entries(result).filter(([key]) => key !== "ok" && key !== "snapshot")));
+        }
         if (input.recoveryId) {
             const projectRoot = resolveProjectRoot(input.projectRoot);
             const project = requireProjectByRoot(context, projectRoot);
@@ -65,6 +75,11 @@ export function createEvalRunSnapshot(context, input) {
         if (fs.existsSync(output))
             throw new AppError("snapshot_exists", "Snapshot output already exists", 1, { output });
         syncSnapshotTree(temporary);
+        if (input.boundary) {
+            if (sourceVersion !== snapshotSourceVersion(context, input))
+                throw new AppError("snapshot_source_changed", "Snapshot source files or Git state changed during boundary capture", 1);
+            input.boundary.verify();
+        }
         fs.renameSync(temporary, output);
         syncPath(path.dirname(output));
         return { ...result, snapshot: output };
@@ -80,10 +95,16 @@ function captureEvalRunSnapshot(context, input) {
     // root must fail without registering a second project in a dedicated home.
     const project = requireProjectByRoot(context, projectRoot);
     const status = getFlowRunStatus(context, { projectRoot, runId: input.runId });
-    assertDedicatedHome(context, project.id, input.runId);
+    const recovery = typeof input.recoveryId === "string";
+    if (!recovery && !input.incomplete && context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controllers'")) {
+        const controller = context.db.get("SELECT controller_id,status,owner_pid,owner_token FROM run_controllers WHERE project_id = ? AND run_id = ? AND status NOT IN ('completed','cancelled','superseded','stop_target_reached')", [project.id, input.runId]);
+        if (controller && (controller.status !== "capturing" || controller.controller_id !== input.boundary?.controllerId || controller.owner_pid !== process.pid || controller.owner_token !== context.env.DD_FLOW_CONTROLLER_TOKEN))
+            throw new AppError("snapshot_controller_capture_required", "A live managed RUN must be captured by its fenced controller, not an external observer", 1, { controller_id: controller.controller_id });
+    }
+    if (!recovery)
+        assertDedicatedHome(context, project.id, input.runId);
     if (!input.incomplete)
         assertRunWorkResultArtifacts(context, project.id, input.runId);
-    const recovery = typeof input.recoveryId === "string";
     if (recovery) {
         const guard = context.db.get("SELECT status, recovery_id FROM run_recovery_guards WHERE project_id = ? AND run_id = ? AND recovery_id = ?", [project.id, input.runId, input.recoveryId]);
         if (!guard || guard.status !== "sealed")
@@ -110,20 +131,47 @@ 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 });
-    fs.mkdirSync(output, { recursive: true });
-    fs.cpSync(context.ddFlowHome, path.join(output, "runtime"), {
-        recursive: true,
-        verbatimSymlinks: true,
-        // Managed checkouts are restored from their Git bundle and workspace
-        // payload. Copying their .git indirection into runtime makes the snapshot
-        // dependent on the source machine's worktree metadata.
-        filter: (source) => snapshotPayloadAllowed(source) && !["engines", "checkouts"].includes(path.basename(source)) && ![context.db.path, `${context.db.path}-wal`, `${context.db.path}-shm`].includes(source)
-    });
+    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`]);
+    if (recovery) {
+        if (typeof status.run.run_root !== "string" || !isInside(physicalPath(context.ddFlowHome), physicalPath(status.run.run_root)) || samePath(physicalPath(context.ddFlowHome), physicalPath(status.run.run_root)))
+            throw new AppError("snapshot_run_scope_invalid", "Recovery requires a RUN artifact root within its runtime", 1);
+        for (const source of new Set([status.run.run_root, runtimeRunDir(context.ddFlowHome, project.id, input.runId)])) {
+            if (fs.existsSync(source))
+                copyRuntimeTree(source, path.join(output, "runtime", path.relative(context.ddFlowHome, source)));
+        }
+    }
+    else
+        copyRuntimeTree(context.ddFlowHome, path.join(output, "runtime"), false, databaseFiles);
     // VACUUM INTO is a consistent SQLite read snapshot, including committed WAL
     // pages. Copying the live database and its WAL separately is not atomic.
     const databaseCopy = path.join(output, "runtime", path.relative(context.ddFlowHome, context.db.path));
     fs.mkdirSync(path.dirname(databaseCopy), { recursive: true });
-    context.db.exec(`VACUUM INTO '${databaseCopy.replace(/'/g, "''")}'`);
+    if (recovery) {
+        const report = typeof status.run.run_root === "string" ? path.join(output, "runtime", path.relative(context.ddFlowHome, status.run.run_root), "02-protocolize", "stage-report.json") : null;
+        if (report && !isInside(physicalPath(path.join(output, "runtime")), physicalPath(report)))
+            throw new AppError("snapshot_protocol_scope_invalid", "Recovery protocol evidence is outside the captured runtime", 1);
+        const protocols = report && fs.existsSync(report) ? JSON.parse(fs.readFileSync(report, "utf8")).semantic?.acceptance : [];
+        if (!Array.isArray(protocols) || !protocols.every(id => typeof id === "string" && id.startsWith("PRT-")))
+            throw new AppError("snapshot_protocol_scope_invalid", "Recovery export requires the accepted PROTOCOLIZE protocol IDs", 1);
+        captureRecoveryDatabase(context.db, databaseCopy, project.id, input.runId, protocols);
+    }
+    else
+        context.db.exec(`VACUUM INTO '${databaseCopy.replace(/'/g, "''")}'`);
+    // Resource heartbeats can continue after productive RUN writers are sealed.
+    // Keep their committed evidence consistent too; never copy a live WAL pair.
+    if (!recovery && fs.existsSync(resourceDatabase)) {
+        const resources = new DatabaseSync(resourceDatabase, { readOnly: true });
+        try {
+            const resourceCopy = path.join(output, "runtime", "runtime.sqlite");
+            resources.exec("PRAGMA busy_timeout = 4000");
+            resources.exec(`VACUUM INTO '${resourceCopy.replace(/'/g, "''")}'`);
+        }
+        finally {
+            resources.close();
+        }
+    }
     fs.cpSync(projectRoot, path.join(output, "project"), {
         recursive: true,
         verbatimSymlinks: true,
@@ -136,6 +184,8 @@ function captureEvalRunSnapshot(context, input) {
     const copiedContext = createContext({ ...context.env, DD_FLOW_HOME: path.join(output, "runtime") }, "read_existing");
     let receiptIssues;
     try {
+        if (recovery)
+            captureRecoveryAuxiliary(context, copiedContext, { projectId: project.id, runId: input.runId, output });
         receiptIssues = runWorkResultArtifactIssues(copiedContext, project.id, input.runId, file => {
             const roots = [[context.ddFlowHome, "runtime"], [workspaceRoot, workspace.kind === "git_worktree" ? "workspace" : "project"], [projectRoot, "project"]];
             for (const [source, payload] of roots) {
@@ -186,6 +236,8 @@ export function restoreEvalRunSnapshot(context, input) {
     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";
+    if (recovery && input.executionRoutingFile !== undefined)
+        throw new AppError("snapshot_recovery_policy_frozen", "Recovery must retain its frozen execution policy", 2);
     if (recovery && input.recoveryId !== manifest.recovery_id)
         throw new AppError("snapshot_recovery_requires_explicit_restore", "Recovery snapshots require their explicit --recovery-id", 1, { snapshot });
     if (!recovery && input.recoveryId)
@@ -200,16 +252,38 @@ export function restoreEvalRunSnapshot(context, input) {
             throw new AppError("recovery_restore_target_not_empty", "Recovery restore requires fresh project and runtime targets", 1);
         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"].includes(name));
+    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");
-    if (treeHash(sourceRuntime) !== manifest.runtime_sha256)
-        throw new AppError("snapshot_checksum_mismatch", "Snapshot runtime checksum does not match manifest", 1, { snapshot });
-    if (treeHash(sourceProject) !== manifest.project_sha256)
-        throw new AppError("snapshot_checksum_mismatch", "Snapshot project checksum does not match manifest", 1, { snapshot });
-    verifySnapshotModes(snapshot, manifest);
+    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.
+        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);
+            const index = row ? JSON.parse(row.index_json) : null;
+            if (!index?.execution_profile || !["vnext_specify", "vnext_protocolize"].includes(index.flow_kind))
+                throw new AppError("execution_profile_not_frozen", "Stage-entry routing requires a vNext execution snapshot", 1);
+            assertStageEntry(index.stage_runs, manifest.stage_entry);
+            selectedProfile = freezeRunExecutionRouting(context.ddFlowHome, index.execution_profile, routingInput);
+            for (const row of sourceDb.prepare("SELECT payload_json FROM works WHERE run_id = ? AND status = 'created'").all(manifest.run_id)) {
+                const payload = row.payload_json ? JSON.parse(row.payload_json) : null;
+                if (payload?.execution_override !== undefined)
+                    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`;
+        }
+        finally {
+            sourceDb.close();
+        }
+    }
     clearProjectTree(projectRoot, false);
     restoreProjectGit(snapshot, manifest.project_git, projectRoot);
     replaceProjectTree(projectRoot, sourceProject);
@@ -221,9 +295,21 @@ export function restoreEvalRunSnapshot(context, input) {
     // A fresh process owns all subsequent normal commands.
     const restored = createContext({ ...context.env, DD_FLOW_HOME: context.ddFlowHome });
     try {
+        const runtimeLineage = recovery ? null : detachSnapshotRuntimeOwners(restored, snapshot, manifest);
         rebaseRuntime(restored, manifest.project_root, projectRoot, sourceWorkspaceRoot(manifest), workspaceRoot, manifest.dd_flow_home, context.ddFlowHome, recovery);
         registerProject(restored, { root: projectRoot });
         requireProjectByRoot(restored, projectRoot);
+        if (selectedProfile && routingInput && runtimeLineage) {
+            const run = restored.db.get("SELECT run_root FROM runs WHERE id = ?", [manifest.run_id]);
+            const artifact = path.join(run.run_root, selectedProfile.routing_input.artifact);
+            if (fs.existsSync(artifact)) {
+                if (!fs.readFileSync(artifact).equals(routingInput.bytes))
+                    throw new AppError("snapshot_checksum_mismatch", "Existing routing input does not match its checksum", 1);
+            }
+            else
+                fs.writeFileSync(artifact, routingInput.bytes, { flag: "wx", mode: 0o600 });
+            importFlowRunExecutionProfile(restored, { projectRoot, runId: manifest.run_id, stage: manifest.stage_entry, lineageFile: runtimeLineage, profile: selectedProfile });
+        }
         const status = getFlowRunStatus(restored, { projectRoot, runId: manifest.run_id });
         if (!recovery)
             assertStageEntry(status.index.stage_runs ?? [], manifest.stage_entry);
@@ -251,6 +337,7 @@ export function restoreEvalRunSnapshot(context, input) {
             dd_flow_home: context.ddFlowHome,
             run_home: runHome,
             target_stage: manifest.stage_entry,
+            ...(runtimeLineage ? { runtime_lineage_file: runtimeLineage } : {}),
             ...(recovery ? { recovery_id: input.recoveryId, native_session_portability: "requires_adapter_verification", relocation_file: relocationFile, relocation } : {}),
             next_command: recovery ? `dd-flow run recovery inspect ${status.run.id} --project-root ${JSON.stringify(projectRoot)} --json` : `dd-flow stage start ${status.run.id} --stage ${manifest.stage_entry} --project-root ${JSON.stringify(projectRoot)} --json`
         };
@@ -270,6 +357,7 @@ export function prepareVnextSpecifyRun(context, input) {
         subjectType: "discussion",
         subjectId: "SPECIFY",
         slug: input.slug,
+        executionRoutingFile: input.executionRoutingFile,
         nextAction: "start_specify"
     });
     return { ok: true, run_id: started.run.id, run_root: started.run.run_root, target_stage: "specify" };
@@ -284,15 +372,69 @@ function assertDedicatedHome(context, projectId, runId) {
 function assertStageEntry(stages, target) {
     if (stages.some((entry) => entry.stage === target))
         throw new AppError("snapshot_target_started", "Stage-entry snapshot requires its target stage to be unstarted", 1, { target });
-    const unfinished = stages.filter((entry) => entry.status !== "done");
+    const unfinished = stages.filter((entry) => !["done", "skipped"].includes(entry.status ?? ""));
     if (unfinished.length > 0)
         throw new AppError("snapshot_predecessor_incomplete", "Stage-entry snapshot requires completed predecessor stages", 1, { target, unfinished });
 }
 function assertTerminalCandidate(stages) {
-    const unfinished = stages.filter((entry) => entry.status !== "done");
+    const unfinished = stages.filter((entry) => !["done", "skipped"].includes(entry.status ?? ""));
     if (unfinished.length > 0)
         throw new AppError("snapshot_candidate_incomplete", "Candidate snapshot requires every started stage to be done", 1, { unfinished });
 }
+/** 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"))
+        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"))
+        throw new AppError("snapshot_execution_active", "A stage-entry fork cannot discard an unresolved MERGE execution", 1);
+    const detachedTables = ["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");
+    const resources = fs.existsSync(resourceFile) ? new DatabaseSync(resourceFile) : null;
+    try {
+        if (resources)
+            registerStoreWriter(resources);
+        const resourceTables = Object.fromEntries(["managed_resources", "managed_processes"].filter(table => resources?.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?").get(table)).map(table => [table, resources.prepare(`SELECT * FROM ${table}`).all()]));
+        const directory = path.join(context.ddFlowHome, "snapshot-imports");
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const file = path.join(directory, `${crypto.randomUUID()}.json`);
+        fs.writeFileSync(file, `${JSON.stringify({ schema_id: "dd-flow/snapshot-runtime-lineage@1", source_snapshot: snapshot, source_manifest_sha256: fileHash(path.join(snapshot, "snapshot.json")), source_runtime: manifest.dd_flow_home, restored_runtime: context.ddFlowHome, run_id: manifest.run_id, run_tables: runTables, resource_tables: resourceTables }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+        syncPath(file);
+        syncPath(directory);
+        context.db.exec("BEGIN IMMEDIATE");
+        try {
+            context.db.run("UPDATE sessions SET metadata_json = json_set(metadata_json, '$.snapshot_import', json(?))", [JSON.stringify({ lineage_file: file, lineage_sha256: fileHash(file) })]);
+            for (const table of detachedTables)
+                context.db.exec(`DELETE FROM ${table}`);
+            context.db.run("UPDATE merge_requests SET dispatch_owner = NULL, dispatch_lease_token = NULL, dispatch_lease_expires_at = NULL, lock_acquired_at = NULL, adapter_receipt_json = NULL");
+            // Only the copied dedicated registry is touched. Source/external homes
+            // are historical references in the archive and are never opened here.
+            if (resources) {
+                resources.exec("BEGIN IMMEDIATE");
+                try {
+                    for (const table of Object.keys(resourceTables))
+                        resources.exec(`DELETE FROM ${table}`);
+                    resources.exec("COMMIT");
+                }
+                catch (error) {
+                    resources.exec("ROLLBACK");
+                    throw error;
+                }
+            }
+            context.db.exec("COMMIT");
+        }
+        catch (error) {
+            context.db.exec("ROLLBACK");
+            throw error;
+        }
+        return file;
+    }
+    finally {
+        resources?.close();
+    }
+}
 function rebaseRuntime(context, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome, recovery = false) {
     context.db.exec("PRAGMA foreign_keys = OFF");
     context.db.exec("BEGIN IMMEDIATE");
@@ -304,7 +446,12 @@ function rebaseRuntime(context, oldRoot, newRoot, oldWorkspace, newWorkspace, ol
         context.db.run("UPDATE protocols SET project_root = ?", [newRoot]);
         for (const column of ["state_path", "plan_path"])
             rewriteDatabaseColumn(context, "protocols", column, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
-        context.db.run("UPDATE sessions SET project_root = ?, status = CASE WHEN status = 'active' THEN 'stopped' ELSE status END, stop_reason = CASE WHEN status = 'active' THEN 'snapshot_restored' ELSE stop_reason END", [newRoot]);
+        for (const column of ["source_workspace", "target_workspace"])
+            rewriteDatabaseColumn(context, "merge_requests", column, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+        if (recovery)
+            context.db.run("UPDATE sessions SET project_root = ?, status = CASE WHEN status = 'active' THEN 'stopped' ELSE status END, stop_reason = CASE WHEN status = 'active' THEN 'snapshot_restored' ELSE stop_reason END", [newRoot]);
+        else
+            context.db.run("UPDATE sessions SET project_root = ?, status = 'stopped', stop_reason = 'snapshot_restored', stopped_at = ?", [newRoot, context.now()]);
         for (const column of ["workspace_path", "cwd", "transcript_path"])
             rewriteDatabaseColumn(context, "sessions", column, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
         for (const column of ["prompt_path", "result_path"])
@@ -337,10 +484,13 @@ function rewriteStructuredFiles(root, oldRoot, newRoot, oldWorkspace, newWorkspa
     const visit = (dir) => {
         for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
             const file = path.join(dir, entry.name);
+            // This is hashed input evidence, not a mutable runtime projection.
+            if (/^execution-routing(?:\.[a-f0-9]{64})?\.input\.json$/.test(entry.name))
+                continue;
             // DD_FLOW_HOME also contains the restored checkout and installed tools.
             // They are project/tool bytes, not flow records; parsing every *.json
             // there breaks on valid JSON-with-comments such as tsconfig files.
-            if (entry.isDirectory() && ![".git", "checkouts", "engines", "node_modules", "tools"].includes(entry.name))
+            if (entry.isDirectory() && ![".git", "checkouts", "engines", "node_modules", "tools", "snapshot-imports"].includes(entry.name))
                 visit(file);
             else if (entry.isFile() && entry.name.endsWith(".json")) {
                 const value = JSON.parse(fs.readFileSync(file, "utf8"));
@@ -517,21 +667,37 @@ export function verifyRecoverySnapshot(snapshot, input, checkWorkingState = true
         { name: "project", root: input.projectRoot, hash: manifest.project_sha256, git: manifest.project_git, head: manifest.project_git.head },
         ...(manifest.workspace.kind === "git_worktree" ? [{ name: "workspace", root: input.workspaceRoot, hash: manifest.workspace.sha256, git: manifest.workspace, head: manifest.workspace.base_ref }] : [])
     ];
-    if (treeHash(path.join(snapshot, "runtime")) !== manifest.runtime_sha256)
-        throw new AppError("snapshot_checksum_mismatch", "Recovery runtime checksum does not match", 1);
-    verifySnapshotModes(snapshot, manifest);
+    verifySnapshotPayload(snapshot, manifest);
     for (const entry of entries) {
         const expectedModes = manifest.payload_modes?.[entry.name];
         if (checkWorkingState && expectedModes && treeModesHash(entry.root, true) !== expectedModes)
             throw new AppError("recovery_workspace_drift", "Executable file modes changed after recovery capture", 1, { payload: entry.name });
-        if (treeHash(path.join(snapshot, entry.name)) !== entry.hash || fileHash(path.join(snapshot, `${entry.name}.bundle`)) !== entry.git.bundle_sha256 || (entry.git.index_sha256 && fileHash(path.join(snapshot, `${entry.name}.index.patch`)) !== entry.git.index_sha256))
-            throw new AppError("snapshot_checksum_mismatch", "Recovery payload checksum does not match", 1, { payload: entry.name });
-        if (entry.git.index_format === "entries@1" && (!entry.git.index_objects_sha256 || fileHash(path.join(snapshot, `${entry.name}.index.pack`)) !== entry.git.index_objects_sha256))
-            throw new AppError("snapshot_checksum_mismatch", "Recovery Git object checksum does not match", 1, { payload: entry.name });
         if (checkWorkingState && (treeHash(entry.root, true) !== entry.hash || git(entry.root, ["rev-parse", "HEAD"]) !== entry.head || git(entry.root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) !== entry.git.branch || (entry.git.index_sha256 && crypto.createHash("sha256").update(entry.git.index_format === "entries@1" ? indexEntries(entry.root) : indexPatch(entry.root)).digest("hex") !== entry.git.index_sha256)))
             throw new AppError("recovery_workspace_drift", "Working files or Git state changed after recovery capture", 1, { payload: entry.name });
     }
 }
+/** Reuse an already published boundary only after checking its identity and
+ * every payload, including its Git index objects. Never overwrite evidence. */
+export function verifyControllerBoundarySnapshot(snapshot, input) {
+    const manifest = readManifest(snapshot), boundary = manifest.boundary_capture;
+    if (!boundary || manifest.consistency !== "controller_boundary_writer_barrier@1" || manifest.run_id !== input.runId || boundary.controller_id !== input.controllerId || boundary.operation_id !== input.operationId || boundary.boundary_key !== input.boundaryKey || manifest.stage_entry !== input.stageEntry || manifest.purpose !== (input.stageEntry ? "stage_entry" : "candidate") || !/^[a-f0-9]{64}$/.test(boundary.source_sha256) || boundary.observation?.settled !== true || boundary.observation.operation_id !== input.operationId)
+        throw new AppError("controller_boundary_snapshot_invalid", "Published snapshot does not prove this controller boundary", 1, { snapshot });
+    verifySnapshotPayload(snapshot, manifest);
+    const file = path.join(snapshot, "snapshot.json");
+    if (input.manifestSha256 !== undefined && fileHash(file) !== input.manifestSha256)
+        throw new AppError("snapshot_checksum_mismatch", "Boundary manifest no longer matches its retained publication receipt", 1, { snapshot });
+    return { snapshot, manifest: file, manifest_sha256: fileHash(file), purpose: manifest.purpose, stage_entry: manifest.stage_entry };
+}
+function verifySnapshotPayload(snapshot, manifest) {
+    if (treeHash(path.join(snapshot, "runtime")) !== manifest.runtime_sha256)
+        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 });
+    }
+}
 function git(root, args) {
     const result = spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
     return result.status === 0 ? result.stdout.trim() : null;
@@ -547,13 +713,158 @@ function snapshotPayloadAllowed(source) {
     return ![".git", "node_modules", ".cache", ".npm", ".pnpm-store"].includes(name)
         && name !== ".env" && !name.startsWith(".env.");
 }
+function runtimePayloadAllowed(source) {
+    return snapshotPayloadAllowed(source) && !["auth.json", "auth.bk", "credentials.json", ".credentials.json", "credentials", ".credentials", "id_rsa", "id_ed25519", "engines", "checkouts"].includes(path.basename(source));
+}
+/** Productive writers are fenced separately. Recheck copied bytes and Git
+ * state so an uncoordinated file writer cannot publish a mixed boundary. */
+function snapshotSourceVersion(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = context.db.get("SELECT workspace_root FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
+    if (!run)
+        throw new AppError("not_found", "Snapshot RUN is not registered", 1);
+    const resources = path.join(context.ddFlowHome, "runtime.sqlite");
+    // Resource heartbeats are not productive writers. Their semantic identities
+    // are rechecked by the owner; each resource DB is copied consistently.
+    const runtimeFilter = (file) => runtimePayloadAllowed(file) && !file.endsWith("-shm") && ![resources, `${resources}-wal`, `${resources}-journal`].includes(file);
+    const roots = [...new Set([projectRoot, run.workspace_root])];
+    return crypto.createHash("sha256").update(JSON.stringify([
+        treeHash(context.ddFlowHome, runtimeFilter), treeModesHash(context.ddFlowHome, runtimeFilter),
+        ...roots.map(root => [treeHash(root, true), treeModesHash(root, true), git(root, ["symbolic-ref", "--quiet", "HEAD"]), gitBytes(root, ["show-ref", "--head"]).toString("base64"), indexEntries(root).toString("base64")])
+    ])).digest("hex");
+}
+/** Copy a dedicated home or scoped recovery tree, preserving SQLite WAL commits. */
+function copyRuntimeTree(source, destination, scoped = true, excluded = []) {
+    if (fs.lstatSync(source).isSymbolicLink())
+        throw new AppError("snapshot_runtime_symlink_outside_scope", "Recovery artifact roots must not be symbolic links", 1, { path: source });
+    const root = physicalPath(source);
+    if (isInside(root, physicalPath(destination)))
+        throw new AppError("snapshot_output_inside_runtime", "Recovery output must be outside its source artifact tree", 1);
+    const databases = [];
+    const sqlite = (file) => {
+        if (!fs.existsSync(file) || !fs.statSync(file).isFile())
+            return false;
+        const descriptor = fs.openSync(file, "r");
+        try {
+            const header = Buffer.alloc(16);
+            return fs.readSync(descriptor, header, 0, 16, 0) === 16 && header.toString() === "SQLite format 3\0";
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+    };
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.cpSync(source, destination, {
+        recursive: true, verbatimSymlinks: true,
+        filter: file => {
+            if (!runtimePayloadAllowed(file) || excluded.includes(file))
+                return false;
+            const stat = fs.lstatSync(file);
+            if (stat.isSymbolicLink()) {
+                if (scoped && !isInside(root, physicalPath(file)))
+                    throw new AppError("snapshot_runtime_symlink_outside_scope", "Recovery artifact link leaves its owned tree", 1, { path: file });
+                return true;
+            }
+            if (!stat.isDirectory() && !stat.isFile())
+                return false;
+            if (stat.isFile()) {
+                if (/-(?:wal|shm|journal)$/.test(file) && sqlite(file.replace(/-(?:wal|shm|journal)$/, "")))
+                    return false;
+                if (sqlite(file)) {
+                    databases.push(file);
+                    return false;
+                }
+            }
+            return true;
+        }
+    });
+    for (const file of databases) {
+        const db = new DatabaseSync(file, { readOnly: true });
+        try {
+            const target = source === file ? destination : path.join(destination, path.relative(source, file));
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            db.exec("PRAGMA busy_timeout = 4000");
+            db.exec(`VACUUM INTO '${target.replace(/'/g, "''")}'`);
+        }
+        finally {
+            db.close();
+        }
+    }
+}
+function captureRecoveryAuxiliary(context, captured, input) {
+    const runtime = path.join(input.output, "runtime");
+    const run = captured.db.get("SELECT run_root, project_root, workspace_root FROM runs WHERE project_id = ? AND id = ?", [input.projectId, input.runId]);
+    const roots = [run.run_root, runtimeRunDir(context.ddFlowHome, input.projectId, input.runId)];
+    for (const protocol of captured.db.all("SELECT id, state_path, plan_path FROM protocols")) {
+        const directory = runtimeProtocolDir(context.ddFlowHome, input.projectId, protocol.id);
+        if (!isInside(physicalPath(context.ddFlowHome), physicalPath(directory)))
+            throw new AppError("snapshot_protocol_scope_invalid", "Protocol runtime leaves DD_FLOW_HOME", 1);
+        if (fs.existsSync(directory)) {
+            copyRuntimeTree(directory, path.join(runtime, path.relative(context.ddFlowHome, directory)));
+            roots.push(directory);
+        }
+        for (const file of [protocol.state_path, protocol.plan_path]) {
+            if (!fs.existsSync(file) || roots.some(root => isInside(physicalPath(root), physicalPath(file))))
+                continue;
+            if (isInside(physicalPath(context.ddFlowHome), physicalPath(file)) && fs.statSync(file).isFile())
+                copyRuntimeTree(file, path.join(runtime, path.relative(context.ddFlowHome, file)));
+            else if (![run.project_root, run.workspace_root].some(root => isInside(physicalPath(root), physicalPath(file))))
+                throw new AppError("snapshot_protocol_scope_invalid", "Protocol evidence is outside captured payloads", 1, { path: file });
+        }
+    }
+    const homes = new Set([context.ddFlowHome, resourceHome(context)]);
+    const queries = {
+        run_controllers: "SELECT json_extract(manifest_json, '$.resource_home') AS home FROM run_controllers UNION SELECT json_extract(value, '$.owner.resource_home') FROM run_controllers, json_each(state_json, '$.sessions')",
+        run_control_workers: "SELECT resource_home AS home FROM run_control_workers",
+        work_launches: "SELECT json_extract(profile_json, '$.runtime_adapter.owner.resource_home') AS home FROM work_launches",
+        merge_requests: "SELECT json_extract(adapter_receipt_json, '$.owner.resource_home') AS home FROM merge_requests",
+        run_recovery_guards: "SELECT value AS home FROM run_recovery_guards, json_each(settlement_json, '$.resource_homes')"
+    };
+    const references = Object.entries(queries).flatMap(([table, query]) => captured.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?", [table]) ? captured.db.all(query) : []);
+    for (const { home } of references) {
+        if (home === null)
+            continue;
+        if (typeof home !== "string" || !path.isAbsolute(home))
+            throw new AppError("snapshot_resource_scope_invalid", "Retained resource home must be an absolute path", 1);
+        homes.add(home);
+    }
+    const nativeCaptures = new Map();
+    const registries = [];
+    for (const home of [...homes].sort()) {
+        if (!path.isAbsolute(home))
+            throw new AppError("snapshot_resource_scope_invalid", "Resource home must be an absolute path", 1);
+        const evidence = readRecoveryResourceEvidence(home, input.projectId, input.runId, { db: captured.db, ddFlowHome: context.ddFlowHome });
+        for (const process of evidence.processes) {
+            const directory = JSON.parse(process.metadata_json).state_dir;
+            if (directory === undefined)
+                continue;
+            if (typeof directory !== "string" || !path.isAbsolute(directory))
+                throw new AppError("snapshot_native_scope_invalid", "Native artifact root must be absolute", 1);
+            if (roots.some(root => isInside(physicalPath(root), physicalPath(directory))) || nativeCaptures.has(directory))
+                continue;
+            const state = JSON.parse(fs.readFileSync(path.join(directory, "daemon.json"), "utf8"));
+            const owner = state.config?.runtime_owner;
+            if (!owner || owner.project_id !== input.projectId || owner.run_id !== input.runId || owner.owner_id !== process.owner_id || owner.dd_flow_home !== context.ddFlowHome || owner.resource_home !== home || owner.state_dir !== directory)
+                throw new AppError("snapshot_native_scope_invalid", "External native artifact root has no matching RUN owner", 1, { state_dir: directory });
+            const relative = path.join("native-evidence", crypto.createHash("sha256").update(directory).digest("hex"));
+            copyRuntimeTree(directory, path.join(runtime, relative));
+            nativeCaptures.set(directory, relative);
+        }
+        const relative = path.join("resource-evidence", `${crypto.createHash("sha256").update(home).digest("hex")}.json`);
+        fs.mkdirSync(path.dirname(path.join(runtime, relative)), { recursive: true });
+        writeJson(path.join(runtime, relative), evidence);
+        registries.push(relative);
+    }
+    writeJson(path.join(runtime, "recovery-evidence.json"), { schema_id: "dd-flow/recovery-runtime-evidence@1", project_id: input.projectId, run_id: input.runId, registries, native_captures: [...nativeCaptures].map(([source_root, payload]) => ({ source_root, payload })) });
+}
 function treeHash(root, filtered = false) {
     const hash = crypto.createHash("sha256");
     const visit = (dir, relative) => {
         for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
             const file = path.join(dir, entry.name);
             const rel = path.join(relative, entry.name);
-            if (filtered && !snapshotPayloadAllowed(file))
+            if (typeof filtered === "function" ? !filtered(file) : filtered && !snapshotPayloadAllowed(file))
                 continue;
             if (entry.isDirectory())
                 visit(file, rel);
@@ -575,7 +886,7 @@ function treeModesHash(root, filtered = false) {
     const visit = (directory) => {
         for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
             const file = path.join(directory, entry.name);
-            if (filtered && !snapshotPayloadAllowed(file))
+            if (typeof filtered === "function" ? !filtered(file) : filtered && !snapshotPayloadAllowed(file))
                 continue;
             if (entry.isDirectory())
                 visit(file);