@deksden-com/dd-flow-cli 0.9.0-beta.11 → 0.9.0-beta.111

package/dist/services/eval-snapshots.js

@@ -2,14 +2,25 @@ 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 { beginSnapshotImport, completeSnapshotImport } from "../storage/import-guard.js";
+import { foreignKeyTransaction } from "../storage/foreign-key-transaction.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 { 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";
+import { localEnvironmentAllowed, projectServicePathFilter } from "./workspace-files.js";
+import { cleanupScopeWriters } from "./scope-writer-cleanup.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))
@@ -18,44 +29,152 @@ 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 });
-    fs.mkdirSync(output, { recursive: true });
-    fs.cpSync(projectRoot, path.join(output, "project"), { recursive: true, verbatimSymlinks: true, filter: (source) => path.basename(source) !== ".git" });
-    const manifest = {
-        schema_id: "dd-eval/bootstrap-snapshot@1",
-        stage: "specify",
-        project_root: projectRoot,
-        project_sha256: treeHash(path.join(output, "project")),
-        project_git: snapshotProjectGit(projectRoot, output)
-    };
-    writeJson(path.join(output, "bootstrap.json"), manifest);
-    return { ok: true, snapshot: output, ...manifest };
+    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);
+    const temporary = `${output}.partial-${crypto.randomUUID()}`;
+    const before = bootstrapSourceVersion(projectRoot);
+    try {
+        fs.mkdirSync(temporary, { recursive: true });
+        fs.cpSync(projectRoot, path.join(temporary, "project"), { recursive: true, verbatimSymlinks: true, filter: projectPayloadFilter(projectRoot) });
+        const after = bootstrapSourceVersion(projectRoot);
+        if (before !== after)
+            throw new AppError("snapshot_source_changed", "Bootstrap source changed during snapshot capture", 1, { phase: "bootstrap", recoverable: true });
+        const manifest = {
+            schema_id: "dd-eval/bootstrap-snapshot@1",
+            stage: "specify",
+            project_root: projectRoot,
+            project_sha256: treeHash(path.join(temporary, "project")),
+            project_git: snapshotProjectGit(projectRoot, temporary)
+        };
+        writeJson(path.join(temporary, "bootstrap.json"), manifest);
+        if (after !== bootstrapSourceVersion(projectRoot))
+            throw new AppError("snapshot_source_changed", "Bootstrap source changed while preserving Git evidence", 1, { phase: "bootstrap", recoverable: true });
+        syncSnapshotTree(temporary);
+        fs.renameSync(temporary, output);
+        syncPath(path.dirname(output));
+        return { ok: true, snapshot: output, ...manifest };
+    }
+    catch (error) {
+        fs.rmSync(temporary, { recursive: true, force: true });
+        throw error;
+    }
+}
+function bootstrapSourceVersion(projectRoot) {
+    return JSON.stringify([
+        treeHash(projectRoot, true),
+        treeModesHash(projectRoot, true),
+        git(projectRoot, ["symbolic-ref", "--quiet", "HEAD"]),
+        gitBytes(projectRoot, ["show-ref", "--head"]).toString("base64"),
+        indexEntries(projectRoot).toString("base64")
+    ]);
 }
 /** 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);
     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 } = prepareEvalRunSnapshotCreation(context, input);
+    const temporary = `${output}.partial-${crypto.randomUUID()}`;
+    let sourceVersion = null;
+    try {
+        input.boundary?.verify();
+        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.sha256, 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);
+            const run = context.db.get("SELECT workspace_root FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
+            verifyRecoverySnapshot(temporary, { runId: input.runId, recoveryId: input.recoveryId, projectRoot, workspaceRoot: run?.workspace_root ?? projectRoot });
+        }
+        if (fs.existsSync(output))
+            throw new AppError("snapshot_exists", "Snapshot output already exists", 1, { output });
+        syncSnapshotTree(temporary);
+        if (input.boundary) {
+            if (sourceVersion) {
+                let after;
+                try {
+                    after = snapshotSourceVersion(context, input, sourceVersion.databases);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                    const missing = error.path;
+                    throw new AppError("snapshot_source_changed", "Snapshot source disappeared during boundary capture", 1, { components: [missing && path.isAbsolute(missing) && isInside(context.ddFlowHome, missing) ? `runtime/${path.relative(context.ddFlowHome, missing)}` : "source_path_disappeared"] });
+                }
+                if (sourceVersion.sha256 !== after.sha256)
+                    throw new AppError("snapshot_source_changed", "Snapshot source files or Git state changed during boundary capture", 1, { components: snapshotSourceChanges(sourceVersion.entries, after.entries), changes: snapshotSourceChangeProofs(sourceVersion.entries, after.entries) });
+            }
+            input.boundary.verify();
+        }
+        fs.renameSync(temporary, output);
+        syncPath(path.dirname(output));
+        return { ...result, snapshot: output };
+    }
+    catch (error) {
+        fs.rmSync(temporary, { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        for (const db of sourceVersion?.databases.values() ?? [])
+            db.close();
+    }
+}
+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.
     const project = requireProjectByRoot(context, projectRoot);
     const status = getFlowRunStatus(context, { projectRoot, runId: input.runId });
-    assertDedicatedHome(context, project.id, input.runId);
-    if (input.candidate)
+    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 (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")
+            throw new AppError("recovery_invalid_state", "Recovery snapshots require the matching sealed recovery guard", 1, { run_id: input.runId, recovery_id: input.recoveryId ?? null, status: guard?.status ?? null });
+    }
+    if (input.incomplete || recovery) { /* Recovery captures only after the runner seals all writers. */ }
+    else if (input.candidate)
         assertTerminalCandidate(status.index.stage_runs ?? []);
     else if (input.stageEntry)
         assertStageEntry(status.index.stage_runs ?? [], input.stageEntry);
@@ -65,7 +184,7 @@ export function createEvalRunSnapshot(context, input) {
     const activeChildren = input.candidate
         ? context.db.get("SELECT COUNT(*) AS count FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NOT NULL AND status IN ('created', 'running', 'paused')", [project.id, input.runId])?.count ?? 0
         : context.db.get("SELECT COUNT(*) AS count FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NOT NULL AND (status IN ('running', 'paused') OR (status = 'created' AND (? IS NULL OR COALESCE(result_schema, '') NOT LIKE ?)))", [project.id, input.runId, allowedCreatedResultSchema, allowedCreatedResultSchema ? `${allowedCreatedResultSchema}@%` : ""])?.count ?? 0;
-    if (activeChildren > 0)
+    if (!input.incomplete && !recovery && activeChildren > 0)
         throw new AppError("snapshot_not_quiescent", `${input.candidate ? "Candidate" : "Stage-entry"} snapshot requires no active child Work`, 1, { run_id: input.runId, active_children: activeChildren });
     const output = path.resolve(input.output);
     if (fs.existsSync(output))
@@ -75,36 +194,90 @@ export function createEvalRunSnapshot(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 });
-    context.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
-    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) => !["engines", "checkouts"].includes(path.basename(source))
-    });
+    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`]);
+    const codexExclusions = codexHomeSnapshotExclusions(context, project.id, input.runId);
+    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)), true, codexExclusions);
+        }
+    }
+    else
+        copyRuntimeTree(context.ddFlowHome, path.join(output, "runtime"), false, [...databaseFiles, ...codexExclusions], grokProviderHomes(context.ddFlowHome));
+    // 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 });
+    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,
-        filter: (source) => path.basename(source) !== ".git"
+        filter: projectPayloadFilter(projectRoot)
     });
     const projectGit = snapshotProjectGit(projectRoot, output);
     const workspace = snapshotWorkspace(workspaceRoot, projectRoot, output);
+    // Accepted Work results are captured in SQLite. Their file representations
+    // are retained evidence, not a second authority or a checkpoint gate.
+    if (recovery) {
+        const copiedContext = createContext({ ...context.env, DD_FLOW_HOME: path.join(output, "runtime") }, "read_existing");
+        try {
+            captureRecoveryAuxiliary(context, copiedContext, { projectId: project.id, runId: input.runId, output });
+        }
+        finally {
+            copiedContext.db.close?.();
+        }
+    }
     const manifest = {
         schema_id: "dd-flow/eval-run-snapshot@5",
         run_id: input.runId,
         project_id: project.id,
         project_root: projectRoot,
         dd_flow_home: context.ddFlowHome,
-        purpose: input.candidate ? "candidate" : "stage_entry",
-        stage_entry: input.candidate ? null : input.stageEntry,
+        purpose: input.incomplete ? "incomplete" : recovery ? "recovery" : input.candidate ? "candidate" : "stage_entry",
+        stage_entry: input.incomplete || recovery || input.candidate ? null : input.stageEntry,
+        ...(input.incomplete ? { consistency: "sqlite_read_snapshot_files_copied_nonatomically", active_child_work_count: activeChildren, restorable: false } : recovery ? { recovery_id: input.recoveryId, consistency: "sealed_writer_barrier_required", active_child_work_count: activeChildren, restorable: "same-runtime-or-explicit-restore" } : {}),
         created_at: context.now(),
         runtime_sha256: treeHash(path.join(output, "runtime")),
         project_sha256: treeHash(path.join(output, "project")),
+        project_payload_policy: "service-files@1",
+        ...(!recovery ? { runtime_payload_policy: "flow-evidence@1" } : {}),
         project_git: projectGit,
         workspace,
+        payload_modes: { project: treeModesHash(path.join(output, "project")), runtime: treeModesHash(path.join(output, "runtime")), ...(workspace.kind === "git_worktree" ? { workspace: treeModesHash(path.join(output, "workspace")) } : {}) },
         source_status: status
     };
     writeJson(path.join(output, "snapshot.json"), manifest);
@@ -118,23 +291,111 @@ 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 });
-    if (!manifest.stage_entry)
+    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";
+    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)
+        throw new AppError("snapshot_invalid", "Recovery ID cannot restore a non-recovery snapshot", 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 });
+    if (!recovery && !manifest.stage_entry)
         throw new AppError("snapshot_invalid", "Stage-entry snapshot has no target stage", 1, { snapshot });
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    const existing = fs.readdirSync(context.ddFlowHome).filter((name) => !["db.sqlite", "db.sqlite-wal", "db.sqlite-shm"].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 });
+    assertRunRestoreTargets(context, input, snapshot, projectRoot, manifest);
+    if (recovery)
+        verifyRecoverySnapshot(snapshot, { runId: manifest.run_id, recoveryId: input.recoveryId, projectRoot, workspaceRoot: projectRoot }, false);
     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 });
+    const routingInput = input.executionRoutingFile !== undefined ? loadExecutionRoutingInput(input.executionRoutingFile) : undefined;
+    let selectedProfile;
+    if (routingInput) {
+        // 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);
+            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`;
+            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), prearmedImportId) {
+    const { snapshot, manifest, recovery, projectRoot, sourceRuntime, sourceProject, routingInput, selectedProfile } = prepared;
+    assertRunRestoreTargets(context, input, snapshot, projectRoot, manifest);
+    const sourceManifestSha256 = fileHash(path.join(snapshot, "snapshot.json"));
+    const importId = prearmedImportId ?? beginSnapshotImport({ home: context.ddFlowHome, projectRoot,
+        workspaceRoot: restoredWorkspaceRoot(manifest, projectRoot, context.ddFlowHome), sourceManifestSha256 });
     clearProjectTree(projectRoot, false);
     restoreProjectGit(snapshot, manifest.project_git, projectRoot);
     replaceProjectTree(projectRoot, sourceProject);
@@ -144,17 +405,46 @@ export function restoreEvalRunSnapshot(context, input) {
     const workspaceRoot = restoreWorkspace(snapshot, manifest, projectRoot, context.ddFlowHome);
     // The dispatch context was intentionally closed before replacing db.sqlite.
     // A fresh process owns all subsequent normal commands.
-    const restored = createContext({ ...context.env, DD_FLOW_HOME: context.ddFlowHome });
+    const restored = createContext({ ...context.env, DD_FLOW_HOME: context.ddFlowHome }, "initialize", importId);
+    let result, primary, failed = false;
     try {
-        rebaseRuntime(restored, manifest.project_root, projectRoot, sourceWorkspaceRoot(manifest), workspaceRoot, manifest.dd_flow_home, context.ddFlowHome);
+        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 });
-        assertStageEntry(status.index.stage_runs ?? [], manifest.stage_entry);
+        if (!recovery)
+            assertStageEntry(status.index.stage_runs ?? [], manifest.stage_entry);
+        else
+            restored.db.run("UPDATE run_recovery_guards SET capture_path = ? WHERE recovery_id = ? AND status = 'sealed'", [snapshot, input.recoveryId]);
         if (!status.run.run_root)
             throw new AppError("runtime_missing", "Restored RUN has no artifact root", 1, { run_id: manifest.run_id });
         const runHome = status.run.run_root;
-        return {
+        const relocation = recovery ? {
+            schema_id: "dd-flow/recovery-relocation@1", physical_runtime_id: crypto.randomUUID(), recovery_id: input.recoveryId, run_id: manifest.run_id,
+            path_mapping: [{ from: manifest.dd_flow_home, to: context.ddFlowHome }, { from: sourceWorkspaceRoot(manifest), to: workspaceRoot }, { from: manifest.project_root, to: projectRoot }]
+        } : null;
+        const relocationFile = relocation ? path.join(context.ddFlowHome, "recovery-imports", `${relocation.physical_runtime_id}.json`) : null;
+        if (relocationFile) {
+            fs.mkdirSync(path.dirname(relocationFile), { recursive: true });
+            writeJson(relocationFile, relocation);
+        }
+        const expectedWorkspaceRoot = restoredWorkspaceRoot(manifest, projectRoot, context.ddFlowHome);
+        if (physicalPath(workspaceRoot) !== physicalPath(expectedWorkspaceRoot))
+            throw new AppError("snapshot_workspace_restore_failed", "Restored workspace differs from the import target", 1, { workspace_root: workspaceRoot, expected_workspace_root: expectedWorkspaceRoot });
+        completeSnapshotImport(context.ddFlowHome, importId, { projectRoot, workspaceRoot: expectedWorkspaceRoot, sourceManifestSha256 });
+        result = {
             ok: true,
             schema_id: "dd-flow/eval-run-restore@1",
             snapshot,
@@ -164,12 +454,24 @@ export function restoreEvalRunSnapshot(context, input) {
             dd_flow_home: context.ddFlowHome,
             run_home: runHome,
             target_stage: manifest.stage_entry,
-            next_command: `dd-flow stage start ${status.run.id} --stage ${manifest.stage_entry} --project-root ${JSON.stringify(projectRoot)} --json`
+            ...(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`
         };
     }
-    finally {
-        restored.db.close?.();
+    catch (error) {
+        primary = error;
+        failed = true;
     }
+    const cleanup = cleanupScopeWriters([{ name: restored.ddFlowHome, db: restored.db, rollback: false, close: "always" }]);
+    if (failed) {
+        if (primary instanceof AppError && cleanup.length)
+            primary.details.import_cleanup_errors = cleanup;
+        throw primary;
+    }
+    if (cleanup.length)
+        throw new AppError("snapshot_import_cleanup_failed", "Snapshot imported but its connection could not be closed", 1, { effect: "committed", import_complete: true, import_cleanup_errors: cleanup });
+    return result;
 }
 export function prepareVnextSpecifyRun(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
@@ -182,6 +484,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" };
@@ -196,19 +499,91 @@ 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 });
 }
-function rebaseRuntime(context, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) {
-    context.db.exec("PRAGMA foreign_keys = OFF");
-    context.db.exec("BEGIN IMMEDIATE");
+/** 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 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 (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_packet_assignments", "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");
+    const resources = fs.existsSync(resourceFile) ? new DatabaseSync(resourceFile) : null;
+    let resourceHeld = false, resourceCommitted = false, result, primary, failed = false;
     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);
+        const lineage = JSON.stringify({ lineage_file: file, lineage_sha256: fileHash(file) });
+        context.db.writeTransaction(() => {
+            assertSnapshotRuntimeDetachAllowed(sql => context.db.get(sql));
+            for (const [table, rows] of Object.entries(runTables))
+                if (JSON.stringify(context.db.all(`SELECT * FROM ${table}`)) !== JSON.stringify(rows))
+                    throw new AppError("snapshot_runtime_changed", "Imported runtime changed during lineage preparation", 1, { table });
+            context.db.run("UPDATE sessions SET metadata_json = json_set(metadata_json, '$.snapshot_import', json(?))", [lineage]);
+            for (const table of detachedTables) {
+                try {
+                    context.db.exec(`DELETE FROM ${table}`);
+                }
+                catch (error) {
+                    throw new AppError("snapshot_runtime_detach_failed", `Could not detach imported ${table} authority`, 1, { table, cause: String(error) });
+                }
+            }
+            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");
+                resourceHeld = true;
+                for (const [table, rows] of Object.entries(resourceTables)) {
+                    if (JSON.stringify(resources.prepare(`SELECT * FROM ${table}`).all()) !== JSON.stringify(rows))
+                        throw new AppError("snapshot_runtime_changed", "Imported resource evidence changed during lineage preparation", 1, { table });
+                    resources.exec(`DELETE FROM ${table}`);
+                }
+                resources.exec("COMMIT");
+                resourceHeld = false;
+                resourceCommitted = true;
+            }
+        });
+        result = file;
+    }
+    catch (error) {
+        primary = error;
+        failed = true;
+    }
+    const cleanup = resources ? cleanupScopeWriters([{ name: resourceFile, db: resources, rollback: resourceHeld, close: "always" }]) : [];
+    if (failed || cleanup.length) {
+        const details = { effect: resourceCommitted ? "partial" : "unknown", ...(cleanup.length ? { import_cleanup_errors: cleanup } : {}) };
+        if (primary instanceof AppError) {
+            Object.assign(primary.details, details);
+            throw primary;
+        }
+        throw new AppError("snapshot_runtime_detach_failed", primary instanceof Error ? primary.message : "Imported runtime authority could not be detached", 1, { ...details, ...(failed ? { cause: String(primary) } : {}) });
+    }
+    return result;
+}
+function rebaseRuntime(context, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome, recovery = false) {
+    foreignKeyTransaction(context.db, () => {
         context.db.run("UPDATE projects SET root = ?", [newRoot]);
         context.db.run("UPDATE runs SET project_root = ?, workspace_root = ?", [newRoot, newWorkspace]);
         for (const column of ["runtime_path", "run_dir", "run_index_path", "run_home_path", "run_root", "index_json"])
@@ -216,7 +591,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"])
@@ -226,35 +606,27 @@ function rebaseRuntime(context, oldRoot, newRoot, oldWorkspace, newWorkspace, ol
         rewriteDatabaseColumn(context, "usage", "source_locator", oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
         for (const column of ["worktree_path", "worktrunk_metadata_json", "last_command_result_json"])
             rewriteDatabaseColumn(context, "worktree_records", column, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
-        context.db.run("UPDATE work_sessions SET status = CASE WHEN status = 'running' THEN 'completed' ELSE status END, completed_at = COALESCE(completed_at, ?), updated_at = ?", [context.now(), context.now()]);
+        // Recovery imports remain sealed. Their old Work sessions are historical
+        // bindings, not completed work; explicit recovery closes them interrupted.
+        if (!recovery)
+            context.db.run("UPDATE work_sessions SET status = CASE WHEN status = 'running' THEN 'completed' ELSE status END, completed_at = COALESCE(completed_at, ?), updated_at = ?", [context.now(), context.now()]);
         context.db.run("DELETE FROM codex_session_bindings");
-        context.db.run("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
-    finally {
-        context.db.exec("PRAGMA foreign_keys = ON");
-    }
-    rewriteStructuredFiles(context.ddFlowHome, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+    });
+    // Only operational database paths move. Imported packets, results and
+    // journals retain their historical bytes, including interrupted JSONL tails.
+    // The frozen workspace route is an operational receipt consumed by later
+    // stages, so its relocated path is the sole structured-file exception.
+    rewriteOperationalRouteReceipts(context.ddFlowHome, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
 }
-function rewriteStructuredFiles(root, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) {
-    const visit = (dir) => {
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            const file = path.join(dir, entry.name);
-            // 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))
+function rewriteOperationalRouteReceipts(root, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) {
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const file = path.join(directory, entry.name);
+            if (entry.isDirectory())
                 visit(file);
-            else if (entry.isFile() && entry.name.endsWith(".json")) {
+            else if (entry.isFile() && entry.name === "workspace-route.json") {
                 const value = JSON.parse(fs.readFileSync(file, "utf8"));
-                writeJson(file, rebaseStructuredValue(value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome));
-            }
-            else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
-                const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean).map((line) => JSON.stringify(rebaseStructuredValue(JSON.parse(line), oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome)));
-                fs.writeFileSync(file, `${lines.join("\n")}\n`);
+                fs.writeFileSync(file, `${JSON.stringify(rebaseStructuredValue(value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome), null, 2)}\n`);
             }
         }
     };
@@ -274,20 +646,27 @@ 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: (source) => path.basename(source) !== ".git" });
+    fs.cpSync(workspaceRoot, workspace, { recursive: true, verbatimSymlinks: true, filter: projectPayloadFilter(workspaceRoot) });
     runGit(projectRoot, ["bundle", "create", bundle, branch]);
-    return { kind: "git_worktree", source_root: workspaceRoot, branch, base_ref: baseRef, sha256: treeHash(workspace), bundle_sha256: fileHash(bundle) };
+    return { kind: "git_worktree", source_root: workspaceRoot, branch, base_ref: baseRef, sha256: treeHash(workspace), bundle_sha256: fileHash(bundle), ...snapshotIndex(workspaceRoot, output, "workspace") };
 }
 function restoreWorkspace(snapshot, manifest, projectRoot, ddFlowHome) {
     if (manifest.workspace.kind === "project")
@@ -298,11 +677,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}`]);
@@ -310,19 +685,38 @@ function restoreWorkspace(snapshot, manifest, projectRoot, ddFlowHome) {
         throw new AppError("snapshot_workspace_restore_failed", "Snapshot Git bundle did not restore the frozen feature base", 1, { branch: manifest.workspace.branch, expected_base: manifest.workspace.base_ref });
     runGit(projectRoot, ["worktree", "add", workspaceRoot, manifest.workspace.branch]);
     replaceProjectTree(workspaceRoot, source);
+    restoreIndex(snapshot, "workspace", manifest.workspace, workspaceRoot);
     return fs.realpathSync(workspaceRoot);
 }
+export 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) };
+    return { branch, head, bundle_sha256: fileHash(bundle), ...snapshotIndex(projectRoot, output, "project") };
 }
 function restoreProjectGit(snapshot, source, projectRoot) {
     const bundle = path.join(snapshot, "project.bundle");
@@ -332,6 +726,131 @@ function restoreProjectGit(snapshot, source, projectRoot) {
     runGit(projectRoot, ["init", "-b", source.branch]);
     runGit(projectRoot, ["fetch", bundle, `+refs/heads/${source.branch}:refs/remotes/snapshot/${source.branch}`]);
     runGit(projectRoot, ["checkout", "-B", source.branch, source.head]);
+    restoreIndex(snapshot, "project", source, projectRoot);
+}
+const mergeStateFiles = ["MERGE_HEAD", "MERGE_MSG", "MERGE_MODE", "ORIG_HEAD", "AUTO_MERGE"];
+function indexEntries(root) {
+    const entries = Buffer.from(gitBytes(root, ["ls-files", "--stage", "-z"])
+        .toString("utf8").split("\0").filter(entry => entry && localEnvironmentAllowed(entry.slice(entry.indexOf("\t") + 1)))
+        .map(entry => `${entry}\0`).join(""));
+    const merge = {};
+    for (const name of mergeStateFiles) {
+        const file = git(root, ["rev-parse", "--git-path", name]);
+        if (!file)
+            throw new AppError("snapshot_index_invalid", "Could not locate Git merge state", 1);
+        const resolved = path.resolve(root, file);
+        if (fs.existsSync(resolved))
+            merge[name] = fs.readFileSync(resolved).toString("base64");
+    }
+    return Buffer.from(JSON.stringify({ entries: entries.toString("base64"), merge }));
+}
+function snapshotIndex(root, output, name) {
+    const bytes = indexEntries(root);
+    const value = JSON.parse(bytes.toString());
+    const objects = new Set();
+    for (const entry of Buffer.from(value.entries, "base64").toString("utf8").split("\0").filter(Boolean)) {
+        const match = /^\d{6} ([a-f0-9]{40,64}) [0-3]\t/.exec(entry);
+        if (!match)
+            throw new AppError("snapshot_index_invalid", "Malformed Git index entry", 1);
+        // Gitlinks belong to another repository and are preserved as index IDs.
+        if (!entry.startsWith("160000 "))
+            objects.add(match[1]);
+    }
+    for (const name of ["MERGE_HEAD", "ORIG_HEAD", "AUTO_MERGE"]) {
+        if (value.merge[name])
+            for (const oid of Buffer.from(value.merge[name], "base64").toString().trim().split("\n")) {
+                if (!/^[a-f0-9]{40,64}$/.test(oid))
+                    throw new AppError("snapshot_index_invalid", "Malformed Git merge reference", 1);
+                objects.add(oid);
+            }
+    }
+    const payload = path.join(output, `${name}.index.patch`);
+    const pack = path.join(output, `${name}.index.pack`);
+    fs.writeFileSync(payload, bytes);
+    fs.writeFileSync(pack, gitBytes(root, ["pack-objects", "--stdout", "--revs"], Buffer.from([...objects].sort().join("\n") + "\n")));
+    return { index_format: "entries@1", index_sha256: fileHash(payload), index_objects_sha256: fileHash(pack) };
+}
+function gitBytes(root, args, input) {
+    const result = spawnSync("git", ["-C", root, ...args], { input, maxBuffer: 64 * 1024 * 1024 });
+    if (result.status !== 0)
+        throw new AppError("snapshot_index_invalid", "Could not preserve Git index objects", 1, { args, stderr: result.stderr?.toString().trim() });
+    return result.stdout;
+}
+function indexPatch(root) {
+    const result = spawnSync("git", ["-C", root, "diff", "--cached", "--binary", "--full-index", "--no-ext-diff", "HEAD", "--", ".", ":(exclude)**/.env", ":(exclude)**/.env.*"], { maxBuffer: 64 * 1024 * 1024 });
+    if (result.status !== 0)
+        throw new AppError("snapshot_index_invalid", "Could not capture Git index", 1);
+    return result.stdout;
+}
+function restoreIndex(snapshot, name, metadata, root) {
+    if (!metadata.index_sha256)
+        return;
+    const file = path.join(snapshot, `${name}.index.patch`);
+    if (fileHash(file) !== metadata.index_sha256)
+        throw new AppError("snapshot_checksum_mismatch", "Snapshot Git index checksum does not match", 1);
+    if (metadata.index_format === "entries@1") {
+        const pack = path.join(snapshot, `${name}.index.pack`);
+        if (!metadata.index_objects_sha256 || fileHash(pack) !== metadata.index_objects_sha256)
+            throw new AppError("snapshot_checksum_mismatch", "Snapshot Git index object checksum does not match", 1);
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        gitBytes(root, ["unpack-objects"], fs.readFileSync(pack));
+        runGit(root, ["read-tree", "--empty"]);
+        gitBytes(root, ["update-index", "-z", "--index-info"], Buffer.from(value.entries, "base64"));
+        for (const name of mergeStateFiles) {
+            const target = git(root, ["rev-parse", "--git-path", name]);
+            if (!target)
+                throw new AppError("snapshot_index_invalid", "Could not locate restored Git merge state", 1);
+            if (value.merge[name] !== undefined)
+                fs.writeFileSync(path.resolve(root, target), Buffer.from(value.merge[name], "base64"));
+            else
+                fs.rmSync(path.resolve(root, target), { force: true });
+        }
+        return;
+    }
+    if (fs.statSync(file).size)
+        runGit(root, ["apply", "--cached", "--binary", file]);
+}
+export function verifyRecoverySnapshot(snapshot, input, checkWorkingState = true) {
+    const manifest = readManifest(snapshot);
+    if (manifest.purpose !== "recovery" || manifest.recovery_id !== input.recoveryId || manifest.run_id !== input.runId)
+        throw new AppError("recovery_capture_invalid", "Snapshot does not identify this recovery", 1);
+    const entries = [
+        { 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 }] : [])
+    ];
+    verifySnapshotPayload(snapshot, manifest);
+    for (const entry of entries) {
+        const allowed = manifest.project_payload_policy === "service-files@1" ? projectPayloadFilter(entry.root) : snapshotPayloadAllowed;
+        const expectedModes = manifest.payload_modes?.[entry.name];
+        if (checkWorkingState && expectedModes && treeModesHash(entry.root, allowed) !== expectedModes)
+            throw new AppError("recovery_workspace_drift", "Executable file modes changed after recovery capture", 1, { payload: entry.name });
+        if (checkWorkingState && (treeHash(entry.root, allowed) !== 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)
+        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" });
@@ -343,12 +862,342 @@ function runGit(root, args) {
         throw new AppError("snapshot_workspace_restore_failed", "Could not restore feature worktree", 1, { stderr: result.stderr.trim(), args });
 }
 function samePath(left, right) { return path.resolve(left) === path.resolve(right); }
-function treeHash(root) {
+function snapshotPayloadAllowed(source) {
+    const name = path.basename(source);
+    return ![".git", "node_modules", ".cache", ".npm", ".pnpm-store"].includes(name)
+        && localEnvironmentAllowed(source);
+}
+function projectPayloadFilter(root) {
+    const serviceAllowed = projectServicePathFilter(root);
+    return file => snapshotPayloadAllowed(file) && serviceAllowed(file);
+}
+function runtimePayloadAllowed(source) {
+    return snapshotPayloadAllowed(source) && !["auth.json", "auth.bk", "auth.encrypted", "auth.v2.key", "auth.v2.file", "credentials.json", ".credentials.json", "credentials", ".credentials", "id_rsa", "id_ed25519", "engines", "checkouts"].includes(path.basename(source));
+}
+/** Only a Grok daemon's verified provider root is excluded from flow evidence.
+ * An unrelated directory named grok-home remains ordinary project data. */
+function grokProviderHomes(runtimeRoot) {
+    const homes = [];
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const file = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (![".git", "node_modules", "grok-home"].includes(entry.name))
+                    visit(file);
+            }
+            else if (entry.isFile() && entry.name === "daemon.json") {
+                let state;
+                try {
+                    state = JSON.parse(fs.readFileSync(file, "utf8"));
+                }
+                catch {
+                    continue;
+                }
+                if (state.schema_id !== "dd-grok/daemon-state@1")
+                    continue;
+                const expected = path.join(directory, "grok-home");
+                if (state.config?.grokHome !== expected || state.config?.ddFlowHome !== runtimeRoot)
+                    throw new AppError("snapshot_native_scope_invalid", "Grok provider home differs from its retained daemon binding", 1, { state_dir: directory });
+                homes.push(expected);
+            }
+        }
+    };
+    visit(runtimeRoot);
+    return homes;
+}
+function sqliteFile(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);
+    }
+}
+function sqliteIdentifier(value) { return `"${value.replaceAll('"', '""')}"`; }
+function sqliteValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : String(value);
+    if (typeof value === "bigint")
+        return `${value}n`;
+    if (Buffer.isBuffer(value))
+        return `blob:${value.toString("base64")}`;
+    if (value instanceof Uint8Array)
+        return `blob:${Buffer.from(value).toString("base64")}`;
+    return String(value);
+}
+/**
+ * SQLite page layout is not semantic identity: VACUUM, checkpoint and a
+ * delete/insert rewrite can change serialized bytes without changing the
+ * logical database. Snapshot only the schema and ordered logical row values.
+ * This intentionally applies to the small set of managed SQLite files, not
+ * to arbitrary provider databases.
+ */
+function sqliteSemanticFingerprint(db, resourceRegistry = false) {
+    db.exec("PRAGMA busy_timeout = 4000");
+    db.exec("BEGIN");
+    try {
+        const schema = db.prepare("SELECT type, name, tbl_name, sql FROM sqlite_schema WHERE name NOT LIKE 'sqlite_%' ORDER BY type, name, tbl_name, sql").all();
+        const tables = schema.filter(row => row.type === "table").map(row => {
+            const columns = db.prepare(`PRAGMA table_info(${sqliteIdentifier(row.name)})`).all()
+                .sort((left, right) => Number(left.cid ?? 0) - Number(right.cid ?? 0))
+                .map(column => ({ name: String(column.name ?? ""), type: String(column.type ?? ""), notnull: Number(column.notnull ?? 0), default: sqliteValue(column.dflt_value ?? null), pk: Number(column.pk ?? 0) }));
+            const names = columns.map(column => column.name);
+            const stableNames = resourceRegistry && row.name === "managed_processes" ? names.filter(name => name !== "lease_expires_at" && name !== "updated_at") : names;
+            const rows = db.prepare(`SELECT * FROM ${sqliteIdentifier(row.name)}`).all()
+                .map(record => stableNames.map(name => [name, sqliteValue(record[name])]))
+                .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+            return { name: row.name, columns, rows };
+        });
+        return crypto.createHash("sha256").update(JSON.stringify({ schema, tables })).digest("hex");
+    }
+    finally {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch { /* The read transaction may already have closed on provider error. */ }
+    }
+}
+/** A WAL is copied through its SQLite read snapshot, not as raw bytes. */
+function runtimeSnapshotKind(file, excluded, providerHomes = []) {
+    if (!runtimePayloadAllowed(file) || providerHomes.some(home => file === home || isInside(home, file)) || excluded.includes(file))
+        return "excluded";
+    if (fs.lstatSync(file).isFile()) {
+        if (/-(?:wal|shm|journal)$/.test(file) && sqliteFile(file.replace(/-(?:wal|shm|journal)$/, "")))
+            return "sidecar";
+        if (sqliteFile(file))
+            return "sqlite";
+    }
+    return "ordinary";
+}
+/** Productive writers are fenced separately. Compare exactly the copied
+ * source set; SQLite serialization includes committed WAL pages without
+ * mistaking a physical checkpoint for new logical content. */
+function snapshotSourceVersion(context, input, retainedDatabases) {
+    const databases = retainedDatabases ?? new Map();
+    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 entries = new Map();
+    const excluded = codexHomeSnapshotExclusions(context, project.id, input.runId);
+    const providerHomes = input.recoveryId === undefined ? grokProviderHomes(context.ddFlowHome) : [];
+    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);
+            const kind = runtimeSnapshotKind(file, excluded, providerHomes);
+            if (kind === "excluded" || kind === "sidecar")
+                continue;
+            const key = `runtime/${path.relative(context.ddFlowHome, file)}`;
+            const stat = fs.lstatSync(file);
+            if (stat.isDirectory()) {
+                entries.set(key, "directory");
+                visit(file);
+            }
+            else if (stat.isSymbolicLink())
+                entries.set(key, `link:${fs.readlinkSync(file)}`);
+            else if (kind === "sqlite") {
+                let db = databases.get(file);
+                if (!db) {
+                    db = new DatabaseSync(file, { readOnly: true });
+                    databases.set(file, db);
+                }
+                // Resource heartbeats are copied consistently but are not productive
+                // RUN writers; owner identity is fenced by boundary.verify().
+                if (file === path.join(resourceHome(context), "runtime.sqlite")) {
+                    entries.set(key, `resource-sqlite:${sqliteSemanticFingerprint(db, true)}:${stat.mode & 0o111}`);
+                    continue;
+                }
+                entries.set(key, `sqlite:${sqliteSemanticFingerprint(db)}:${stat.mode & 0o111}`);
+            }
+            else if (stat.isFile())
+                entries.set(key, `file:${crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex")}:${stat.mode & 0o111}`);
+        }
+    };
+    try {
+        visit(context.ddFlowHome);
+        for (const root of new Set([projectRoot, run.workspace_root]))
+            entries.set(`source/${root}`, JSON.stringify([
+                treeHash(root, true), treeModesHash(root, true), git(root, ["symbolic-ref", "--quiet", "HEAD"]), gitBytes(root, ["show-ref", "--head"]).toString("base64"), indexEntries(root).toString("base64")
+            ]));
+        return { entries, databases, sha256: crypto.createHash("sha256").update(JSON.stringify([...entries].sort(([a], [b]) => a.localeCompare(b)))).digest("hex") };
+    }
+    catch (error) {
+        if (!retainedDatabases)
+            for (const db of databases.values())
+                try {
+                    db.close();
+                }
+                catch { /* Preserve the original source error. */ }
+        throw error;
+    }
+}
+function snapshotSourceChanges(before, after) {
+    return [...new Set([...before.keys(), ...after.keys()])].filter(key => before.get(key) !== after.get(key)).sort().slice(0, 8);
+}
+function snapshotSourceChangeProofs(before, after) {
+    return snapshotSourceChanges(before, after).map(component => ({
+        component,
+        before: before.has(component) ? crypto.createHash("sha256").update(before.get(component)).digest("hex") : null,
+        after: after.has(component) ? crypto.createHash("sha256").update(after.get(component)).digest("hex") : null
+    }));
+}
+/** Managed Codex homes share host configuration, not owned snapshot payload. */
+function codexHomeSnapshotExclusions(context, projectId, runId) {
+    const homes = new Set(context.db.all("SELECT target_home FROM codex_home_profiles WHERE project_id = ?", [projectId]).map(row => row.target_home));
+    if (context.db.get("SELECT 1 FROM sqlite_schema WHERE name = 'run_controllers'")) {
+        for (const { home } of context.db.all("SELECT json_extract(value, '$.codex_home') AS home FROM run_controllers, json_each(state_json, '$.sessions') WHERE project_id = ? AND run_id = ?", [projectId, runId]))
+            if (home)
+                homes.add(home);
+    }
+    const excluded = [];
+    for (const home of homes) {
+        if (!path.isAbsolute(home) || !fs.existsSync(home) || fs.lstatSync(home).isSymbolicLink())
+            continue;
+        const marker = path.join(home, ".dd-flow-home.json");
+        if (!fs.existsSync(marker) || fs.lstatSync(marker).isSymbolicLink())
+            continue;
+        const identity = JSON.parse(fs.readFileSync(marker, "utf8"));
+        if (identity.managed_by !== "dd-flow-cli" || identity.project_id !== projectId || identity.target_home !== home || !identity.source_home || !path.isAbsolute(identity.source_home))
+            continue;
+        for (const entry of codexHomeSharedEntries) {
+            const file = path.join(home, entry);
+            // Skip only the exact links installed by initCodexHome, never arbitrary
+            // external links or owned local files with the same convenient name.
+            if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink() && fs.readlinkSync(file) === path.join(identity.source_home, entry))
+                excluded.push(file);
+        }
+        excluded.push(path.join(home, "tmp"), path.join(home, ".tmp"));
+    }
+    return excluded;
+}
+/** Copy a dedicated home or scoped recovery tree, preserving SQLite WAL commits. */
+function copyRuntimeTree(source, destination, scoped = true, excluded = [], providerHomes = []) {
+    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 = [];
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.cpSync(source, destination, {
+        recursive: true, verbatimSymlinks: true,
+        filter: file => {
+            const kind = runtimeSnapshotKind(file, excluded, providerHomes);
+            if (kind === "excluded" || kind === "sidecar")
+                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 (kind === "sqlite") {
+                    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 codexExclusions = codexHomeSnapshotExclusions(context, input.projectId, input.runId);
+    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)), true, codexExclusions);
+            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), true, codexExclusions);
+            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 allowed = typeof filtered === "function" ? filtered : filtered ? projectPayloadFilter(root) : () => true;
     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 (!allowed(file))
+                continue;
             if (entry.isDirectory())
                 visit(file, rel);
             else if (entry.isFile()) {
@@ -364,14 +1213,62 @@ function treeHash(root) {
     visit(root, "");
     return hash.digest("hex");
 }
+function treeModesHash(root, filtered = false) {
+    const entries = [];
+    const allowed = typeof filtered === "function" ? filtered : filtered ? projectPayloadFilter(root) : () => true;
+    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 (!allowed(file))
+                continue;
+            if (entry.isDirectory())
+                visit(file);
+            else if (entry.isFile())
+                entries.push([path.relative(root, file), fs.statSync(file).mode & 0o111]);
+        }
+    };
+    visit(root);
+    return crypto.createHash("sha256").update(JSON.stringify(entries)).digest("hex");
+}
+function verifySnapshotModes(snapshot, manifest) {
+    if (!manifest.payload_modes)
+        return; // Legacy snapshots did not attest modes.
+    for (const name of ["project", "runtime", ...(manifest.workspace.kind === "git_worktree" ? ["workspace"] : [])]) {
+        if (treeModesHash(path.join(snapshot, name)) !== manifest.payload_modes[name])
+            throw new AppError("snapshot_checksum_mismatch", "Snapshot executable modes do not match manifest", 1, { payload: name });
+    }
+}
 function fileHash(file) { return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); }
+// Flush children before their directory entries, then publish and flush the
+// parent. Never follow snapshot symlinks into the original project tree.
+function syncSnapshotTree(root) {
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        const file = path.join(root, entry.name);
+        if (entry.isDirectory())
+            syncSnapshotTree(file);
+        else if (entry.isFile())
+            syncPath(file);
+    }
+    syncPath(root);
+}
+function syncPath(file) {
+    const descriptor = fs.openSync(file, "r");
+    try {
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
 function readManifest(snapshot) {
     const file = path.join(snapshot, "snapshot.json");
     if (!fs.existsSync(file))
         throw new AppError("snapshot_missing", "Snapshot manifest is missing", 1, { snapshot });
     const value = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (value.schema_id !== "dd-flow/eval-run-snapshot@5" || !value.run_id || !value.project_root || !value.dd_flow_home || typeof value.purpose !== "string" || !["stage_entry", "candidate"].includes(value.purpose) || (value.purpose === "stage_entry" && !value.stage_entry) || (value.purpose === "candidate" && value.stage_entry !== null) || !value.runtime_sha256 || !value.project_sha256 || !value.project_git || !value.workspace)
+    if (value.schema_id !== "dd-flow/eval-run-snapshot@5" || !value.run_id || !value.project_root || !value.dd_flow_home || typeof value.purpose !== "string" || !["stage_entry", "candidate", "incomplete", "recovery"].includes(value.purpose) || (value.purpose === "stage_entry" && !value.stage_entry) || (value.purpose !== "stage_entry" && value.stage_entry !== null) || !value.runtime_sha256 || !value.project_sha256 || !value.project_git || !value.workspace)
         throw new AppError("snapshot_invalid", "Snapshot manifest is invalid", 1, { snapshot });
+    if (value.runtime_payload_policy !== undefined && (value.runtime_payload_policy !== "flow-evidence@1" || value.purpose === "recovery"))
+        throw new AppError("snapshot_invalid", "Snapshot runtime payload policy is invalid for its purpose", 1, { snapshot });
     if (!value.project_git.branch || !value.project_git.head || !value.project_git.bundle_sha256)
         throw new AppError("snapshot_invalid", "Snapshot project Git metadata is incomplete", 1, { snapshot });
     if (value.workspace.kind === "git_worktree" && (!value.workspace.branch || !value.workspace.base_ref || !value.workspace.bundle_sha256))