@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.150

package/dist/services/eval-snapshots.js

@@ -2,14 +2,43 @@ 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 { canonicalPath, 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 { validateRunOperationalDecision } from "./vnext-execution-profile.js";
 import { readVnextFlowDefinition } from "./vnext-specify.js";
+import { captureRecoveryDatabase, readRecoveryResourceEvidence } from "./recovery-snapshot-database.js";
+import { resourceHome } from "./managed-processes.js";
+import { getResourceDatabase } from "../storage/database.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";
+import { PreparedInstalledFlowSource } from "./installed-flow-source.js";
+import { readSetupStatus } from "./setup.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { isObservationOperation, nativeInventoryVersion, retainedDaemonOperations } from "./run-control.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) {
+    let source;
+    if (input.flow !== undefined && input.flow !== "sdlc") {
+        if (input.flow !== "mb-init" && input.flow !== "mb-upgrade" && !isDiagnosticFlow(input.flow))
+            throw new AppError("snapshot_flow_unsupported", "Bootstrap snapshot flow is not registered", 2, { phase: "prepare", effect: "no_effect" });
+        const home = context.env.DD_FLOW_CONFIG_HOME ?? context.ddFlowHome;
+        const selected = readSetupStatus(home);
+        if (!selected.installation)
+            throw new AppError("snapshot_flow_unavailable", "Bootstrap snapshot requires the selected installed flow", 2, { phase: "prepare", effect: "no_effect" });
+        source = PreparedInstalledFlowSource.fromInstalledRelease(home, selected.installation.manifest_sha256, input.flow);
+        if (source.resolveRegisteredFlow().descriptor.stages[0]?.id !== "preflight")
+            throw new AppError("snapshot_flow_unsupported", "Memory bootstrap requires its preflight entry", 2, { phase: "prepare", effect: "no_effect" });
+    }
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const output = path.resolve(input.output);
     if (fs.existsSync(output))
@@ -18,44 +47,161 @@ 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, source };
+}
+export function createEvalBootstrapSnapshot(context, input) {
+    const { projectRoot, output, source } = 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: source ? "dd-eval/bootstrap-snapshot@2" : "dd-eval/bootstrap-snapshot@1",
+            stage: source?.resolveRegisteredFlow().descriptor.stages[0]?.id ?? "specify",
+            ...(source ? { flow: { id: source.resolveRegisteredFlow().descriptor.id, source_sha256: source.sha256, descriptor_sha256: source.descriptorReference().sha256 } } : {}),
+            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 });
+        source?.revalidate();
+        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"]),
+        git(projectRoot, ["rev-parse", "HEAD"]),
+        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" };
+    return { ok: true, schema_id: "dd-eval/bootstrap-restore@1", snapshot, project_root: projectRoot, target_stage: manifest.stage, ...(manifest.flow ? { flow: manifest.flow } : {}) };
 }
 /**
- * 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, ...(sourceVersion ? { journalCuts: sourceVersion.journals, observationCuts: sourceVersion.observations } : {}), 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, sourceVersion.journals);
+                }
+                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 });
+        // Native journal publication creates its directory before requested.json.
+        // Retry a gap during any capture phase, without classifying an incomplete
+        // request as read-only. Persistent missing inputs still exhaust the budget.
+        if (input.boundary && error.code === "ENOENT") {
+            const missing = error.path;
+            throw new AppError("snapshot_source_changed", "Snapshot source was not fully published during boundary capture", 1, { components: [missing && path.isAbsolute(missing) && isInside(context.ddFlowHome, missing) ? `runtime/${path.relative(context.ddFlowHome, missing)}` : "source_path_disappeared"] });
+        }
+        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 +211,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 +221,97 @@ 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, recovery && status.run.flow_kind === "mb-init");
+    prepareSnapshotWorkspace(workspaceRoot, projectRoot, isDiagnosticFlow(status.run.flow_kind));
+    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), ...input.journalCuts?.keys() ?? [], ...input.observationCuts?.keys() ?? []];
+    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, [], input.observationCuts);
+        }
+    }
+    else
+        copyRuntimeTree(context.ddFlowHome, path.join(output, "runtime"), false, [...databaseFiles, ...codexExclusions, ...(isDiagnosticFlow(status.run.flow_kind) ? [workspaceRoot] : [])], grokProviderHomes(context.ddFlowHome), input.observationCuts);
+    for (const [file, cut] of input.journalCuts ?? []) {
+        const target = path.join(output, "runtime", path.relative(context.ddFlowHome, file));
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, cut.payload, { mode: cut.mode });
+    }
+    // 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);
+    const projectGit = snapshotProjectGit(projectRoot, output, recovery && status.run.flow_kind === "mb-init");
+    const workspace = snapshotWorkspace(workspaceRoot, projectRoot, output, isDiagnosticFlow(status.run.flow_kind));
+    // 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",
+        schema_id: workspace.kind === "git_repository" ? "dd-flow/eval-run-snapshot@7" : projectGit.state === "unborn" ? "dd-flow/eval-run-snapshot@6" : "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" } : {}),
+        ...(input.journalCuts ? { journal_cuts: [...input.journalCuts].map(([file, cut]) => ({ path: path.relative(context.ddFlowHome, file), bytes: cut.payload.length, sha256: cut.sha256 })) } : {}),
+        ...(input.observationCuts ? { observation_cuts: [...input.observationCuts].map(([file, receipt]) => ({ path: path.relative(context.ddFlowHome, file), receipt })) } : {}),
         project_git: projectGit,
         workspace,
+        payload_modes: { project: treeModesHash(path.join(output, "project")), runtime: treeModesHash(path.join(output, "runtime")), ...(workspace.kind !== "project" ? { workspace: treeModesHash(path.join(output, "workspace")) } : {}) },
         source_status: status
     };
     writeJson(path.join(output, "snapshot.json"), manifest);
@@ -118,57 +325,251 @@ 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.operationalDecisionFile !== undefined)
+        throw new AppError("snapshot_recovery_policy_frozen", "Recovery cannot replace its accepted operational decision", 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 });
-    clearProjectTree(projectRoot, false);
-    restoreProjectGit(snapshot, manifest.project_git, projectRoot);
-    replaceProjectTree(projectRoot, sourceProject);
-    context.db.close?.();
-    fs.rmSync(context.ddFlowHome, { recursive: true, force: true });
-    fs.cpSync(sourceRuntime, context.ddFlowHome, { recursive: true, verbatimSymlinks: true });
-    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 routingInput = input.executionRoutingFile !== undefined ? loadExecutionRoutingInput(input.executionRoutingFile) : undefined;
+    const acceptedOperational = recovery ? undefined : prepareSnapshotOperationalDecision({ snapshot, runId: manifest.run_id, projectRoot, now: context.now(), ...(input.operationalDecisionFile ? { file: input.operationalDecisionFile } : {}) });
+    const operationalDecisionBytes = acceptedOperational?.bytes;
+    let selectedProfile = acceptedOperational?.profile;
+    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, selectedProfile ?? 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, operationalDecisionBytes };
+}
+/** Shared no-effect scope preparation for direct restore and run fork. */
+export function prepareSnapshotOperationalDecision(input) {
+    const sourceDb = new DatabaseSync(path.join(input.snapshot, "runtime", "db.sqlite"), { readOnly: true });
     try {
-        rebaseRuntime(restored, manifest.project_root, projectRoot, sourceWorkspaceRoot(manifest), workspaceRoot, manifest.dd_flow_home, context.ddFlowHome);
-        registerProject(restored, { root: projectRoot });
-        requireProjectByRoot(restored, projectRoot);
-        const status = getFlowRunStatus(restored, { projectRoot, runId: manifest.run_id });
-        assertStageEntry(status.index.stage_runs ?? [], manifest.stage_entry);
-        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 {
-            ok: true,
-            schema_id: "dd-flow/eval-run-restore@1",
-            snapshot,
-            run_id: status.run.id,
-            project_root: projectRoot,
-            workspace_root: workspaceRoot,
-            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`
-        };
+        const row = sourceDb.prepare("SELECT index_json FROM runs WHERE id = ?").get(input.runId);
+        const profile = row ? JSON.parse(row.index_json).execution_profile : undefined;
+        if (profile?.operational_decision && !input.file)
+            throw new AppError("snapshot_operational_acceptance_required", "A new stage-entry execution needs its own accepted operational decision", 2);
+        if (!input.file)
+            return undefined;
+        if (!profile)
+            throw new AppError("execution_profile_not_frozen", "Operational stage-entry decision needs a frozen vNext profile", 2);
+        const bytes = fs.readFileSync(input.file);
+        const decision = validateRunOperationalDecision(JSON.parse(bytes.toString("utf8")), profile.settings);
+        if (canonicalPath(decision.scope.project_root, false) !== canonicalPath(input.projectRoot, false))
+            throw new AppError("operational_decision_scope_mismatch", "Imported decision must name the new project root", 2);
+        const sourceProject = path.join(input.snapshot, "project"), policyFile = path.resolve(sourceProject, decision.policy.path);
+        if (!isInside(sourceProject, policyFile) || !fs.existsSync(policyFile) || !isInside(fs.realpathSync(sourceProject), fs.realpathSync(policyFile)) || fileHash(policyFile) !== decision.policy.sha256)
+            throw new AppError("operational_decision_policy_changed", "Imported decision policy must match the owned frozen project source", 2);
+        if (decision.exception?.expires_at && Date.parse(decision.exception.expires_at) <= Date.parse(input.now))
+            throw new AppError("operational_decision_expired", "Imported operational decision has explicitly expired", 2);
+        return { profile: { ...profile, operational_decision: decision }, bytes };
     }
     finally {
-        restored.db.close?.();
+        sourceDb.close();
+    }
+}
+function assertRunRestoreTargets(context, input, snapshot, projectRoot, manifest) {
+    assertRestoreTargetSeparation(snapshot, [projectRoot, context.ddFlowHome]);
+    if (manifest.workspace.kind !== "project") {
+        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;
+    if (input.operationalDecisionFile && (!prepared.operationalDecisionBytes || !fs.readFileSync(input.operationalDecisionFile).equals(prepared.operationalDecisionBytes)))
+        throw new AppError("operational_decision_changed", "Accepted operational decision changed after import preparation", 2);
+    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 });
+    try {
+        clearProjectTree(projectRoot, false);
+        restoreProjectGit(snapshot, manifest.project_git, projectRoot);
+        replaceProjectTree(projectRoot, sourceProject);
+        context.db.close?.();
+        fs.rmSync(context.ddFlowHome, { recursive: true, force: true });
+        fs.cpSync(sourceRuntime, context.ddFlowHome, { recursive: true, verbatimSymlinks: true });
+        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 }, "initialize", importId);
+        let result, primary, failed = false;
+        try {
+            const runtimeLineage = recovery ? null : detachSnapshotRuntimeOwners(restored, snapshot, manifest);
+            const originalRunRoot = restored.db.get("SELECT run_root FROM runs WHERE id = ?", [manifest.run_id])?.run_root;
+            rebaseRuntime(restored, manifest.project_root, projectRoot, sourceWorkspaceRoot(manifest), workspaceRoot, manifest.dd_flow_home, context.ddFlowHome, recovery);
+            const publicationRun = restored.db.get("SELECT project_id, run_root FROM runs WHERE id = ?", [manifest.run_id]);
+            if (!originalRunRoot || !publicationRun?.run_root || !isInside(manifest.dd_flow_home, originalRunRoot) || !isInside(context.ddFlowHome, publicationRun.run_root))
+                throw new AppError("snapshot_invalid", "Restored publication roots are not bound to their runtime", 1);
+            const pathMapping = [{ from: manifest.dd_flow_home, to: context.ddFlowHome }, { from: sourceWorkspaceRoot(manifest), to: workspaceRoot }, { from: manifest.project_root, to: projectRoot }];
+            restored.db.run("INSERT INTO audit_events (project_id, event_type, forced, payload_json, created_at) VALUES (?, 'flow_run.publication_relocation', 0, ?, ?)", [publicationRun.project_id, JSON.stringify({ run_id: manifest.run_id, from: originalRunRoot, to: publicationRun.run_root, source_manifest_sha256: sourceManifestSha256, import_id: importId, path_mapping: pathMapping }), restored.now()]);
+            registerProject(restored, { root: projectRoot });
+            requireProjectByRoot(restored, projectRoot);
+            if (selectedProfile && runtimeLineage) {
+                const run = restored.db.get("SELECT run_root FROM runs WHERE id = ?", [manifest.run_id]);
+                if (routingInput) {
+                    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 });
+                }
+                if (input.operationalDecisionFile) {
+                    if (!prepared.operationalDecisionBytes || !fs.readFileSync(input.operationalDecisionFile).equals(prepared.operationalDecisionBytes))
+                        throw new AppError("operational_decision_changed", "Accepted operational decision changed before import publication", 2);
+                    const binding = { project_id: publicationRun.project_id, run_id: manifest.run_id, ...selectedProfile.operational_decision.scope };
+                    const policyBytes = fs.readFileSync(path.resolve(projectRoot, selectedProfile.operational_decision.policy.path));
+                    const policySource = { path: `operational-policy.${selectedProfile.operational_decision.policy.sha256}.source.md`, sha256: crypto.createHash("sha256").update(policyBytes).digest("hex") };
+                    if (policySource.sha256 !== selectedProfile.operational_decision.policy.sha256)
+                        throw new AppError("operational_decision_policy_changed", "Imported policy changed before binding", 2);
+                    if (!fs.existsSync(path.join(run.run_root, policySource.path)))
+                        fs.writeFileSync(path.join(run.run_root, policySource.path), policyBytes, { flag: "wx" });
+                    const bytes = `${JSON.stringify({ schema_id: "dd-flow/run-operational-contract@1", binding, settings: { merge_delivery: selectedProfile.settings.merge_delivery, merge_cleanup: selectedProfile.settings.merge_cleanup }, decision: selectedProfile.operational_decision, policy_source: policySource }, null, 2)}\n`;
+                    const artifact = `operational-contract.${crypto.createHash("sha256").update(bytes).digest("hex")}.json`;
+                    fs.writeFileSync(path.join(run.run_root, artifact), bytes, { flag: "wx" });
+                    selectedProfile.operational_contract = { path: artifact, sha256: crypto.createHash("sha256").update(bytes).digest("hex"), policy_source: policySource, binding };
+                }
+                importFlowRunExecutionProfile(restored, { projectRoot, runId: manifest.run_id, stage: manifest.stage_entry, lineageFile: runtimeLineage, profile: selectedProfile });
+            }
+            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 status = getFlowRunStatus(restored, { projectRoot, runId: manifest.run_id });
+            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;
+            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,
+                run_id: status.run.id,
+                project_root: projectRoot,
+                workspace_root: workspaceRoot,
+                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`
+            };
+        }
+        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;
+    }
+    catch (error) {
+        // The import fence and target writes have already started. A nested
+        // prepare/read validator must not report this operation as no-effect.
+        if (error instanceof AppError)
+            Object.assign(error.details, { phase: "restore", effect: error.details.effect === "committed" ? "committed" : "partial", import_id: importId, next_action: "reconcile_snapshot_import" });
+        throw error;
     }
 }
 export function prepareVnextSpecifyRun(context, input) {
@@ -182,6 +583,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 +598,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 +690,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,47 +705,55 @@ 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`);
             }
         }
     };
     visit(root);
 }
-function rewriteDatabaseColumn(context, table, column, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) { for (const row of context.db.all(`SELECT rowid AS rid, ${column} AS value FROM ${table} WHERE ${column} IS NOT NULL`)) {
-    if (!row.value)
-        continue;
-    const value = column.endsWith("_json") || column === "index_json" ? JSON.stringify(rebaseStructuredValue(JSON.parse(row.value), oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome)) : rebasePathString(row.value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
-    if (value !== row.value)
-        context.db.run(`UPDATE ${table} SET ${column} = ? WHERE rowid = ?`, [value, row.rid]);
-} }
+function rewriteDatabaseColumn(context, table, column, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) {
+    for (const row of context.db.all(`SELECT rowid AS rid, ${column} AS value FROM ${table} WHERE ${column} IS NOT NULL`)) {
+        if (!row.value)
+            continue;
+        let value;
+        if (column.endsWith("_json") || column === "index_json") {
+            const original = JSON.parse(row.value);
+            const mapped = rebaseStructuredValue(original, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+            if (table === "runs" && column === "index_json" && original.execution_profile) {
+                // Accepted source/binding are logical provenance, not mutable physical locators.
+                if (original.execution_profile.operational_decision)
+                    mapped.execution_profile.operational_decision = original.execution_profile.operational_decision;
+                if (original.execution_profile.operational_contract)
+                    mapped.execution_profile.operational_contract = original.execution_profile.operational_contract;
+            }
+            value = JSON.stringify(mapped);
+        }
+        else
+            value = rebasePathString(row.value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+        if (value !== row.value)
+            context.db.run(`UPDATE ${table} SET ${column} = ? WHERE rowid = ?`, [value, row.rid]);
+    }
+}
 function rebaseStructuredValue(value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) { if (typeof value === "string")
     return rebasePathString(value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome); if (Array.isArray(value))
     return value.map((item) => rebaseStructuredValue(item, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome)); if (value && typeof value === "object")
@@ -274,20 +761,29 @@ 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, allowUnborn = false) {
     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)
+    if (!baseRef && !(allowUnborn && git(workspaceRoot, ['for-each-ref', '--format=%(refname)']) === ''))
         throw new AppError("snapshot_workspace_invalid", "Feature workspace has no readable HEAD", 1, { workspace_root: workspaceRoot });
+    return { branch, baseRef };
+}
+function snapshotWorkspace(workspaceRoot, projectRoot, output, independent = false) {
+    const prepared = prepareSnapshotWorkspace(workspaceRoot, projectRoot, independent);
+    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" });
-    runGit(projectRoot, ["bundle", "create", bundle, branch]);
-    return { kind: "git_worktree", source_root: workspaceRoot, branch, base_ref: baseRef, sha256: treeHash(workspace), bundle_sha256: fileHash(bundle) };
+    fs.cpSync(workspaceRoot, workspace, { recursive: true, verbatimSymlinks: true, filter: projectPayloadFilter(workspaceRoot) });
+    if (baseRef === null)
+        return { kind: 'git_repository', source_root: workspaceRoot, branch, base_ref: null, bundle_sha256: null, state: 'unborn', sha256: treeHash(workspace), ...snapshotIndex(workspaceRoot, output, 'workspace') };
+    runGit(independent ? workspaceRoot : projectRoot, ["bundle", "create", bundle, branch]);
+    return { kind: independent ? "git_repository" : "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")
@@ -296,42 +792,250 @@ function restoreWorkspace(snapshot, manifest, projectRoot, ddFlowHome) {
     const bundle = path.join(snapshot, "workspace.bundle");
     if (treeHash(source) !== manifest.workspace.sha256)
         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)
+    if (manifest.workspace.state === 'unborn' ? fs.existsSync(bundle) : !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}`]);
-    if (git(projectRoot, ["rev-parse", `refs/heads/${manifest.workspace.branch}`]) !== manifest.workspace.base_ref)
-        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]);
+    if (manifest.workspace.kind === 'git_repository') {
+        fs.mkdirSync(path.dirname(workspaceRoot), { recursive: true });
+        if (manifest.workspace.state === 'unborn') {
+            fs.mkdirSync(workspaceRoot);
+            runGit(workspaceRoot, ['-c', 'init.templateDir=', 'init', '--initial-branch', manifest.workspace.branch]);
+        }
+        else
+            runGit(projectRoot, ['clone', '--no-checkout', '--branch', manifest.workspace.branch, bundle, workspaceRoot]);
+    }
+    else {
+        runGit(projectRoot, ["fetch", bundle, `+refs/heads/${manifest.workspace.branch}:refs/heads/${manifest.workspace.branch}`]);
+        if (git(projectRoot, ["rev-parse", `refs/heads/${manifest.workspace.branch}`]) !== manifest.workspace.base_ref)
+            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]);
+    }
+    if (git(workspaceRoot, ["rev-parse", "HEAD"]) !== manifest.workspace.base_ref)
+        throw new AppError("snapshot_workspace_restore_failed", "Snapshot Git bundle did not restore the frozen workspace base", 1, { branch: manifest.workspace.branch, expected_base: manifest.workspace.base_ref });
     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, allowUnborn = false) {
     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 });
+    const head = git(projectRoot, ["rev-parse", "--verify", "HEAD"]);
+    if (!branch || !head && !(allowUnborn && git(projectRoot, ["for-each-ref", "--format=%(refname)"]) === ""))
+        throw new AppError("snapshot_project_git_invalid", "Snapshot requires a named Git branch and readable HEAD, or an admitted empty-ref Memory recovery", 1, { project_root: projectRoot });
+    return { branch, head };
+}
+function snapshotProjectGit(projectRoot, output, allowUnborn = false) {
+    const { branch, head } = prepareSnapshotProjectGit(projectRoot, allowUnborn);
+    if (head === null)
+        return { branch, head: null, bundle_sha256: null, state: "unborn", ...snapshotIndex(projectRoot, output, "project") };
     const bundle = path.join(output, "project.bundle");
-    runGit(projectRoot, ["bundle", "create", bundle, "--all"]);
-    return { branch, head, bundle_sha256: fileHash(bundle) };
+    runGit(projectRoot, ["bundle", "create", bundle, `refs/heads/${branch}`]);
+    return { branch, head, bundle_sha256: fileHash(bundle), ...snapshotIndex(projectRoot, output, "project") };
 }
 function restoreProjectGit(snapshot, source, projectRoot) {
     const bundle = path.join(snapshot, "project.bundle");
-    if (!fs.existsSync(bundle) || fileHash(bundle) !== source.bundle_sha256)
+    if (source.state === "unborn" ? fs.existsSync(bundle) : !fs.existsSync(bundle) || fileHash(bundle) !== source.bundle_sha256)
         throw new AppError("snapshot_checksum_mismatch", "Snapshot project Git bundle checksum does not match manifest", 1, { snapshot });
     fs.rmSync(path.join(projectRoot, ".git"), { recursive: true, force: true });
     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]);
+    if (source.state !== "unborn") {
+        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, includeExclude = true) {
+    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");
+    }
+    if (!includeExclude)
+        return Buffer.from(JSON.stringify({ entries: entries.toString("base64"), merge }));
+    const excludePath = git(root, ["rev-parse", "--git-path", "info/exclude"]);
+    if (!excludePath)
+        throw new AppError("snapshot_index_invalid", "Could not locate Git local excludes", 1);
+    const excludeFile = path.resolve(root, excludePath);
+    let exclude = null;
+    if (fs.existsSync(excludeFile)) {
+        const stat = fs.lstatSync(excludeFile);
+        if (!stat.isFile() || stat.size > 1024 * 1024)
+            throw new AppError("snapshot_index_invalid", "Git local excludes must be a bounded regular file", 1);
+        exclude = fs.readFileSync(excludeFile).toString("base64");
+    }
+    // Local excludes affect review-visible inputs, but are not part of a Git
+    // bundle/index. Keep them in the existing hashed, non-executable Git payload.
+    return Buffer.from(JSON.stringify({ entries: entries.toString("base64"), merge, exclude }));
+}
+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"));
+        if (value.exclude !== undefined && value.exclude !== null && (typeof value.exclude !== "string" || Buffer.byteLength(value.exclude) > 1400000))
+            throw new AppError("snapshot_index_invalid", "Snapshot Git local excludes are invalid", 1);
+        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 });
+        }
+        if (value.exclude !== undefined) {
+            const target = git(root, ["rev-parse", "--git-path", "info/exclude"]);
+            if (!target)
+                throw new AppError("snapshot_index_invalid", "Could not locate restored Git local excludes", 1);
+            const destination = path.resolve(root, target);
+            if (fs.existsSync(destination) && !fs.lstatSync(destination).isFile())
+                throw new AppError("snapshot_index_invalid", "Restored Git local excludes are not a regular file", 1);
+            if (value.exclude === null)
+                fs.rmSync(destination, { force: true });
+            else {
+                fs.mkdirSync(path.dirname(destination), { recursive: true });
+                fs.writeFileSync(destination, Buffer.from(value.exclude, "base64"));
+            }
+        }
+        return;
+    }
+    if (fs.statSync(file).size)
+        runGit(root, ["apply", "--cached", "--binary", file]);
+}
+function capturedIndexEntries(snapshot, name, root) {
+    const captured = JSON.parse(fs.readFileSync(path.join(snapshot, `${name}.index.patch`), "utf8"));
+    return indexEntries(root, Object.hasOwn(captured, "exclude"));
+}
+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 !== "project" ? [{ 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", "--verify", "HEAD"]) !== entry.head
+            || entry.head === null && git(entry.root, ["for-each-ref", "--format=%(refname)"]) !== ""
+            || 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" ? capturedIndexEntries(snapshot, entry.name, 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 !== "project" ? [{ name: "workspace", hash: manifest.workspace.sha256, git: manifest.workspace }] : [])];
+    for (const payload of payloads)
+        verifyGitSnapshotPayload(snapshot, payload);
+    if (manifest.schema_id === "dd-flow/eval-run-snapshot@6") {
+        const db = new DatabaseSync(path.join(snapshot, "runtime", "db.sqlite"), { readOnly: true });
+        try {
+            const row = db.prepare("SELECT flow_kind, project_root, workspace_root FROM runs WHERE id=?").get(manifest.run_id);
+            if (!row || row.flow_kind !== "mb-init" || row.project_root !== manifest.project_root || row.workspace_root !== manifest.project_root)
+                throw new AppError("snapshot_invalid", "Unborn recovery must belong to its captured Memory RUN", 1, { snapshot });
+        }
+        finally {
+            db.close();
+        }
+    }
+}
+function verifyGitSnapshotPayload(snapshot, payload) {
+    const bundle = path.join(snapshot, `${payload.name}.bundle`);
+    const invalidBundle = payload.git.state === "unborn" ? payload.git.bundle_sha256 !== null || fs.existsSync(bundle)
+        : !fs.existsSync(bundle) || fileHash(bundle) !== payload.git.bundle_sha256;
+    if (treeHash(path.join(snapshot, payload.name)) !== payload.hash || invalidBundle || 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 +1047,408 @@ 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 nativeDaemonFile(file) {
+    if (!fs.lstatSync(file, { throwIfNoEntry: false })?.isFile())
+        return false;
+    try {
+        const state = JSON.parse(fs.readFileSync(file, "utf8"));
+        return typeof state.daemon_id === "string" && (/^dd-(codex|zcode|grok|agy|opencode|droid)\/daemon-state@1$/.test(String(state.schema_id)) || state.schema_id === "dd-opencode/daemon-state@2");
+    }
+    catch {
+        return false;
+    } // Unrecognized files retain full-byte protection.
+}
+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) {
+    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 rows = db.prepare(`SELECT * FROM ${sqliteIdentifier(row.name)}`).all()
+                .map(record => names.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 the copied source set
+ * without idle diagnostic appends; SQLite includes committed WAL pages without
+ * mistaking a physical checkpoint for new logical content. */
+function snapshotSourceVersion(context, input, retainedDatabases, retainedJournals) {
+    const databases = retainedDatabases ?? new Map();
+    const journals = retainedJournals ?? 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 diagnosticLogs = new Set(getResourceDatabase(resourceHome(context), "read_existing").all("SELECT stdout_path,stderr_path,metadata_json FROM managed_processes WHERE project_id=? AND run_id=? AND kind IN ('codex-daemon','zcode-daemon','grok-daemon','agy-daemon','opencode-daemon','droid-daemon')", [project.id, input.runId]).flatMap(row => {
+        const directory = JSON.parse(row.metadata_json).state_dir;
+        const log = typeof directory === "string" && path.isAbsolute(directory) ? path.join(directory, "daemon.log") : null;
+        return log && isInside(context.ddFlowHome, log) && row.stdout_path === log && row.stderr_path === log ? [log] : [];
+    }));
+    const excluded = codexHomeSnapshotExclusions(context, project.id, input.runId);
+    const providerHomes = input.recoveryId === undefined ? grokProviderHomes(context.ddFlowHome) : [];
+    const observations = new Map();
+    const operationRoots = new Set();
+    const visit = (directory) => {
+        const daemon = path.join(directory, "daemon.json");
+        const native = nativeDaemonFile(daemon);
+        if (native) {
+            operationRoots.add(path.join(directory, "operations"));
+            for (const operation of retainedDaemonOperations(directory))
+                if (isObservationOperation(operation.operation))
+                    observations.set(path.join(directory, "operations", crypto.createHash("sha256").update(String(operation.operation_id)).digest("hex")), operation);
+        }
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const file = path.join(directory, entry.name);
+            // These diagnostic cuts are retained, but their creation cannot
+            // invalidate a productive boundary. Unknown operations remain protected.
+            if (observations.has(file))
+                continue;
+            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()) {
+                if (!operationRoots.has(file))
+                    entries.set(key, "directory");
+                visit(file);
+            }
+            else if (stat.isSymbolicLink())
+                entries.set(key, `link:${fs.readlinkSync(file)}`);
+            else if (native && file === daemon)
+                entries.set(key, `daemon:${nativeInventoryVersion(directory)}:${stat.mode & 0o111}`);
+            else if (kind === "sqlite") {
+                // Their productive identities are checked by boundary.verify(). A
+                // consistent backup is evidence, not a demand for global DB silence.
+                if (file === context.db.path || file === path.join(resourceHome(context), "runtime.sqlite")) {
+                    entries.set(key, `managed-sqlite:${stat.mode & 0o111}`);
+                    continue;
+                }
+                let db = databases.get(file);
+                if (!db) {
+                    db = new DatabaseSync(file, { readOnly: true });
+                    databases.set(file, db);
+                }
+                entries.set(key, `sqlite:${sqliteSemanticFingerprint(db)}:${stat.mode & 0o111}`);
+            }
+            else if (stat.isFile() && diagnosticLogs.has(file)) {
+                // Daemon stdout/stderr can append while an otherwise settled Session is idle.
+                // Keep its identity/mode fenced; the copied bytes remain sealed in the snapshot.
+                entries.set(key, `diagnostic-log:${stat.dev}:${stat.ino}:${stat.mode & 0o111}`);
+            }
+            else if (stat.isFile() && (["adapter.events.jsonl", "events.jsonl", "model-observations.jsonl", "timeline.jsonl", "controller.log"].includes(path.basename(file)) || native && file === path.join(directory, "daemon.log"))) {
+                const bytes = fs.readFileSync(file);
+                let cut = journals.get(file);
+                if (!cut && !retainedJournals) {
+                    const payload = bytes.subarray(0, bytes.lastIndexOf(10) + 1);
+                    cut = { payload, dev: stat.dev, ino: stat.ino, mode: stat.mode, sha256: crypto.createHash("sha256").update(payload).digest("hex") };
+                    journals.set(file, cut);
+                }
+                const valid = cut && cut.dev === stat.dev && cut.ino === stat.ino && bytes.length >= cut.payload.length && bytes.subarray(0, cut.payload.length).equals(cut.payload);
+                entries.set(key, valid && cut ? `journal:${cut.sha256}:${cut.payload.length}:${stat.mode & 0o111}` : "journal:changed");
+            }
+            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"]), git(root, ["rev-parse", "HEAD"]), indexEntries(root).toString("base64")
+            ]));
+        return { entries, databases, journals, observations, 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 = [], observationCuts) {
+    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 => {
+            if (observationCuts && path.basename(path.dirname(file)) === "operations" && fs.lstatSync(file).isDirectory() && nativeDaemonFile(path.join(path.dirname(path.dirname(file)), "daemon.json"))) {
+                let operations;
+                try {
+                    operations = retainedDaemonOperations(path.dirname(path.dirname(file)));
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                    throw new AppError("snapshot_source_changed", "Native operation was not fully published during capture", 1, { components: ["native_operation_publication"] });
+                }
+                const operation = operations.find(row => crypto.createHash("sha256").update(String(row.operation_id)).digest("hex") === path.basename(file));
+                if (operation && isObservationOperation(operation.operation)) {
+                    if (!observationCuts.has(file))
+                        observationCuts.set(file, operation);
+                    return false;
+                }
+            }
+            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,18 +1464,80 @@ 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 !== "project" ? ["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 (!["dd-flow/eval-run-snapshot@5", "dd-flow/eval-run-snapshot@6", "dd-flow/eval-run-snapshot@7"].includes(String(value.schema_id)) || !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.project_git.branch || !value.project_git.head || !value.project_git.bundle_sha256)
+    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 });
+    const unborn = value.schema_id === "dd-flow/eval-run-snapshot@6";
+    if (!value.project_git.branch || (unborn
+        ? value.purpose !== "recovery" || value.workspace.kind !== "project" || value.project_git.state !== "unborn"
+            || value.project_git.head !== null || value.project_git.bundle_sha256 !== null
+            || value.project_git.index_format !== "entries@1" || !/^[a-f0-9]{64}$/.test(value.project_git.index_sha256 ?? "")
+            || !/^[a-f0-9]{64}$/.test(value.project_git.index_objects_sha256 ?? "")
+            || Object.keys(value.project_git).sort().join() !== "branch,bundle_sha256,head,index_format,index_objects_sha256,index_sha256,state"
+            || typeof value.project_git.branch !== "string"
+            || spawnSync("git", ["check-ref-format", "--branch", value.project_git.branch], { encoding: "utf8" }).status !== 0
+        : value.project_git.state !== undefined || !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))
-        throw new AppError("snapshot_invalid", "Snapshot worktree manifest is incomplete", 1, { snapshot });
+    if (!['project', 'git_worktree', 'git_repository'].includes(value.workspace.kind)
+        || (value.schema_id === 'dd-flow/eval-run-snapshot@7') !== (value.workspace.kind === 'git_repository')
+        || value.workspace.kind !== 'project' && (!value.workspace.branch || (value.workspace.state === 'unborn'
+            ? value.workspace.kind !== 'git_repository' || value.workspace.base_ref !== null || value.workspace.bundle_sha256 !== null
+                || value.workspace.index_format !== 'entries@1' || !value.workspace.index_sha256 || !value.workspace.index_objects_sha256
+            : value.workspace.state !== undefined || !value.workspace.base_ref || !value.workspace.bundle_sha256)))
+        throw new AppError("snapshot_invalid", "Snapshot workspace manifest is incomplete or incompatible", 1, { snapshot });
     return value;
 }
 function readBootstrapManifest(snapshot) {
@@ -383,7 +1545,11 @@ function readBootstrapManifest(snapshot) {
     if (!fs.existsSync(file))
         throw new AppError("snapshot_missing", "Bootstrap snapshot manifest is missing", 1, { snapshot });
     const value = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (value.schema_id !== "dd-eval/bootstrap-snapshot@1" || value.stage !== "specify" || !value.project_root || !value.project_sha256 || !value.project_git?.branch || !value.project_git.head || !value.project_git.bundle_sha256)
+    const validBoundary = value.schema_id === "dd-eval/bootstrap-snapshot@1" ? value.stage === "specify" && value.flow === undefined
+        : value.schema_id === "dd-eval/bootstrap-snapshot@2" && (value.flow?.id === "mb-init" || value.flow?.id === "mb-upgrade" || isDiagnosticFlow(value.flow?.id)) && value.stage === "preflight"
+            && Object.keys(value.flow).sort().join() === "descriptor_sha256,id,source_sha256"
+            && /^[a-f0-9]{64}$/.test(value.flow.source_sha256) && /^[a-f0-9]{64}$/.test(value.flow.descriptor_sha256);
+    if (!validBoundary || !value.project_root || !value.project_sha256 || !value.project_git?.branch || !value.project_git.head || !value.project_git.bundle_sha256)
         throw new AppError("snapshot_invalid", "Bootstrap snapshot manifest is invalid", 1, { snapshot });
     return value;
 }