@deksden-com/dd-flow-cli 0.9.0-beta.7 → 0.9.0-beta.74

package/dist/services/eval-snapshots.js

@@ -2,12 +2,18 @@ import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { registerStoreWriter } from "../storage/writer-contract.js";
 import { createContext } from "../runtime/context.js";
 import { AppError } from "../shared/errors.js";
-import { resolveProjectRoot } from "../storage/paths.js";
+import { resolveProjectRoot, runtimeProtocolDir, runtimeRunDir } from "../storage/paths.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
-import { getFlowRunStatus, startFlowRun } from "./runs.js";
+import { freezeRunExecutionRouting, getFlowRunStatus, importFlowRunExecutionProfile, startFlowRun } from "./runs.js";
+import { loadExecutionRoutingInput, resolveExecutionPolicy } from "./execution-policy.js";
 import { readVnextFlowDefinition } from "./vnext-specify.js";
+import { captureRecoveryDatabase, readRecoveryResourceEvidence } from "./recovery-snapshot-database.js";
+import { resourceHome } from "./managed-processes.js";
+import { codexHomeSharedEntries } from "./hooks.js";
 /** Capture the only flow boundary which exists before `stage start --bootstrap` creates a RUN. */
 export function createEvalBootstrapSnapshot(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
@@ -19,7 +25,7 @@ export function createEvalBootstrapSnapshot(context, input) {
     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" });
+    fs.cpSync(projectRoot, path.join(output, "project"), { recursive: true, verbatimSymlinks: true, filter: snapshotPayloadAllowed });
     const manifest = {
         schema_id: "dd-eval/bootstrap-snapshot@1",
         stage: "specify",
@@ -44,18 +50,66 @@ export function restoreEvalBootstrapSnapshot(_context, input) {
     return { ok: true, schema_id: "dd-eval/bootstrap-restore@1", snapshot, project_root: projectRoot, target_stage: "specify" };
 }
 /**
- * Snapshot a deliberately dedicated DD_FLOW_HOME. Eval checkpoints are not a
- * general runtime export format: a shared home fails closed instead of trying
- * to infer a safe subset of SQLite rows.
+ * Eval fixtures require a dedicated home. Sealed recovery exports instead
+ * retain only the selected RUN's relational and filesystem evidence.
  */
 export function createEvalRunSnapshot(context, input) {
+    const output = path.resolve(input.output);
+    if (fs.existsSync(output))
+        throw new AppError("snapshot_exists", "Snapshot output already exists", 1, { output });
+    const temporary = `${output}.partial-${crypto.randomUUID()}`;
+    try {
+        input.boundary?.verify();
+        const sourceVersion = input.boundary ? snapshotSourceVersion(context, input) : null;
+        const result = captureEvalRunSnapshot(context, { ...input, output: temporary });
+        if (input.boundary && sourceVersion) {
+            Object.assign(result, { consistency: "controller_boundary_writer_barrier@1", boundary_capture: { controller_id: input.boundary.controllerId, operation_id: input.boundary.operationId, boundary_key: input.boundary.boundaryKey, source_sha256: sourceVersion, observation: input.boundary.observation } });
+            writeJson(path.join(temporary, "snapshot.json"), Object.fromEntries(Object.entries(result).filter(([key]) => key !== "ok" && key !== "snapshot")));
+        }
+        if (input.recoveryId) {
+            const projectRoot = resolveProjectRoot(input.projectRoot);
+            const project = requireProjectByRoot(context, projectRoot);
+            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 !== snapshotSourceVersion(context, input))
+                throw new AppError("snapshot_source_changed", "Snapshot source files or Git state changed during boundary capture", 1);
+            input.boundary.verify();
+        }
+        fs.renameSync(temporary, output);
+        syncPath(path.dirname(output));
+        return { ...result, snapshot: output };
+    }
+    catch (error) {
+        fs.rmSync(temporary, { recursive: true, force: true });
+        throw error;
+    }
+}
+function captureEvalRunSnapshot(context, input) {
     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 +119,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 +129,81 @@ 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))
-    });
+    fs.mkdirSync(output, { recursive: true, mode: 0o700 });
+    const resourceDatabase = path.join(context.ddFlowHome, "runtime.sqlite");
+    const databaseFiles = [context.db.path, resourceDatabase].flatMap(file => [file, `${file}-wal`, `${file}-shm`]);
+    const codexExclusions = codexHomeSnapshotExclusions(context, project.id, input.runId);
+    if (recovery) {
+        if (typeof status.run.run_root !== "string" || !isInside(physicalPath(context.ddFlowHome), physicalPath(status.run.run_root)) || samePath(physicalPath(context.ddFlowHome), physicalPath(status.run.run_root)))
+            throw new AppError("snapshot_run_scope_invalid", "Recovery requires a RUN artifact root within its runtime", 1);
+        for (const source of new Set([status.run.run_root, runtimeRunDir(context.ddFlowHome, project.id, input.runId)])) {
+            if (fs.existsSync(source))
+                copyRuntimeTree(source, path.join(output, "runtime", path.relative(context.ddFlowHome, source)), true, codexExclusions);
+        }
+    }
+    else
+        copyRuntimeTree(context.ddFlowHome, path.join(output, "runtime"), false, [...databaseFiles, ...codexExclusions]);
+    // 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: snapshotPayloadAllowed
     });
     const projectGit = snapshotProjectGit(projectRoot, output);
     const workspace = snapshotWorkspace(workspaceRoot, projectRoot, output);
+    // Accepted Work results are captured in SQLite. Their file representations
+    // are retained evidence, not a second authority or a checkpoint gate.
+    if (recovery) {
+        const copiedContext = createContext({ ...context.env, DD_FLOW_HOME: path.join(output, "runtime") }, "read_existing");
+        try {
+            captureRecoveryAuxiliary(context, copiedContext, { projectId: project.id, runId: input.runId, output });
+        }
+        finally {
+            copiedContext.db.close?.();
+        }
+    }
     const manifest = {
         schema_id: "dd-flow/eval-run-snapshot@5",
         run_id: input.runId,
         project_id: project.id,
         project_root: projectRoot,
         dd_flow_home: context.ddFlowHome,
-        purpose: input.candidate ? "candidate" : "stage_entry",
-        stage_entry: input.candidate ? null : input.stageEntry,
+        purpose: input.incomplete ? "incomplete" : recovery ? "recovery" : input.candidate ? "candidate" : "stage_entry",
+        stage_entry: input.incomplete || recovery || input.candidate ? null : input.stageEntry,
+        ...(input.incomplete ? { consistency: "sqlite_read_snapshot_files_copied_nonatomically", active_child_work_count: activeChildren, restorable: false } : recovery ? { recovery_id: input.recoveryId, consistency: "sealed_writer_barrier_required", active_child_work_count: activeChildren, restorable: "same-runtime-or-explicit-restore" } : {}),
         created_at: context.now(),
         runtime_sha256: treeHash(path.join(output, "runtime")),
         project_sha256: treeHash(path.join(output, "project")),
         project_git: projectGit,
         workspace,
+        payload_modes: { project: treeModesHash(path.join(output, "project")), runtime: treeModesHash(path.join(output, "runtime")), ...(workspace.kind === "git_worktree" ? { workspace: treeModesHash(path.join(output, "workspace")) } : {}) },
         source_status: status
     };
     writeJson(path.join(output, "snapshot.json"), manifest);
@@ -121,20 +220,57 @@ function createdWorkSchemaForStage(stage) {
 export function restoreEvalRunSnapshot(context, input) {
     const snapshot = path.resolve(input.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 });
+    const recovery = manifest.purpose === "recovery";
+    if (recovery && input.executionRoutingFile !== undefined)
+        throw new AppError("snapshot_recovery_policy_frozen", "Recovery must retain its frozen execution policy", 2);
+    if (recovery && input.recoveryId !== manifest.recovery_id)
+        throw new AppError("snapshot_recovery_requires_explicit_restore", "Recovery snapshots require their explicit --recovery-id", 1, { snapshot });
+    if (!recovery && input.recoveryId)
+        throw new AppError("snapshot_invalid", "Recovery ID cannot restore a non-recovery snapshot", 1, { snapshot });
     if (manifest.purpose === "candidate")
         throw new AppError("snapshot_candidate_not_restorable", "A terminal candidate snapshot is evidence, not a stage-entry fixture", 1, { snapshot });
-    if (!manifest.stage_entry)
+    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 (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);
+        verifyRecoverySnapshot(snapshot, { runId: manifest.run_id, recoveryId: input.recoveryId, projectRoot, workspaceRoot: projectRoot }, false);
+    }
+    const existing = fs.readdirSync(context.ddFlowHome).filter((name) => !["db.sqlite", "db.sqlite-wal", "db.sqlite-shm", ...(input.executionRoutingFile !== undefined ? ["agent-profiles"] : [])].includes(name));
     if (existing.length > 0)
         throw new AppError("restore_home_not_empty", "Snapshot restore requires an empty DD_FLOW_HOME", 1, { dd_flow_home: context.ddFlowHome, existing });
+    if (context.db.get("SELECT 1 FROM projects LIMIT 1") || context.db.get("SELECT 1 FROM runs LIMIT 1"))
+        throw new AppError("restore_home_not_empty", "Snapshot restore cannot replace an initialized runtime", 1);
     const sourceRuntime = path.join(snapshot, "runtime");
     const sourceProject = path.join(snapshot, "project");
-    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 });
+    verifySnapshotPayload(snapshot, manifest);
+    const routingInput = input.executionRoutingFile !== undefined ? loadExecutionRoutingInput(input.executionRoutingFile) : undefined;
+    let selectedProfile;
+    if (routingInput) {
+        // Resolve selected profiles from the fresh caller home before replacing it.
+        // Source DB is read-only; no context or migrations may touch the snapshot.
+        const sourceDb = new DatabaseSync(path.join(sourceRuntime, "db.sqlite"), { readOnly: true });
+        try {
+            const row = sourceDb.prepare("SELECT index_json FROM runs WHERE id = ?").get(manifest.run_id);
+            const index = row ? JSON.parse(row.index_json) : null;
+            if (!index?.execution_profile || !["vnext_specify", "vnext_protocolize"].includes(index.flow_kind))
+                throw new AppError("execution_profile_not_frozen", "Stage-entry routing requires a vNext execution snapshot", 1);
+            assertStageEntry(index.stage_runs, manifest.stage_entry);
+            selectedProfile = freezeRunExecutionRouting(context.ddFlowHome, index.execution_profile, routingInput);
+            for (const row of sourceDb.prepare("SELECT payload_json FROM works WHERE run_id = ? AND status = 'created'").all(manifest.run_id)) {
+                const payload = row.payload_json ? JSON.parse(row.payload_json) : null;
+                if (payload?.execution_override !== undefined)
+                    resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy: routingInput.execution, profiles: selectedProfile.agent_profiles, stage: manifest.stage_entry, work: payload.execution_override });
+            }
+            selectedProfile.routing_input.artifact = `execution-routing.${routingInput.source_checksum}.input.json`;
+        }
+        finally {
+            sourceDb.close();
+        }
+    }
     clearProjectTree(projectRoot, false);
     restoreProjectGit(snapshot, manifest.project_git, projectRoot);
     replaceProjectTree(projectRoot, sourceProject);
@@ -146,12 +282,38 @@ export function restoreEvalRunSnapshot(context, input) {
     // A fresh process owns all subsequent normal commands.
     const restored = createContext({ ...context.env, DD_FLOW_HOME: context.ddFlowHome });
     try {
-        rebaseRuntime(restored, manifest.project_root, projectRoot, sourceWorkspaceRoot(manifest), workspaceRoot, manifest.dd_flow_home, context.ddFlowHome);
+        const runtimeLineage = recovery ? null : detachSnapshotRuntimeOwners(restored, snapshot, manifest);
+        rebaseRuntime(restored, manifest.project_root, projectRoot, sourceWorkspaceRoot(manifest), workspaceRoot, manifest.dd_flow_home, context.ddFlowHome, recovery);
         registerProject(restored, { root: projectRoot });
-        const project = requireProjectByRoot(restored, projectRoot);
+        requireProjectByRoot(restored, projectRoot);
+        if (selectedProfile && routingInput && runtimeLineage) {
+            const run = restored.db.get("SELECT run_root FROM runs WHERE id = ?", [manifest.run_id]);
+            const artifact = path.join(run.run_root, selectedProfile.routing_input.artifact);
+            if (fs.existsSync(artifact)) {
+                if (!fs.readFileSync(artifact).equals(routingInput.bytes))
+                    throw new AppError("snapshot_checksum_mismatch", "Existing routing input does not match its checksum", 1);
+            }
+            else
+                fs.writeFileSync(artifact, routingInput.bytes, { flag: "wx", mode: 0o600 });
+            importFlowRunExecutionProfile(restored, { projectRoot, runId: manifest.run_id, stage: manifest.stage_entry, lineageFile: runtimeLineage, profile: selectedProfile });
+        }
         const status = getFlowRunStatus(restored, { projectRoot, runId: manifest.run_id });
-        assertStageEntry(status.index.stage_runs ?? [], manifest.stage_entry);
-        const runHome = status.run.run_home_path ?? path.join(context.ddFlowHome, "projects", project.id, "runs", 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 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);
+        }
         return {
             ok: true,
             schema_id: "dd-flow/eval-run-restore@1",
@@ -162,7 +324,9 @@ export function restoreEvalRunSnapshot(context, input) {
             dd_flow_home: context.ddFlowHome,
             run_home: runHome,
             target_stage: manifest.stage_entry,
-            next_command: `dd-flow stage start ${status.run.id} --stage ${manifest.stage_entry} --project-root ${JSON.stringify(projectRoot)} --json`
+            ...(runtimeLineage ? { runtime_lineage_file: runtimeLineage } : {}),
+            ...(recovery ? { recovery_id: input.recoveryId, native_session_portability: "requires_adapter_verification", relocation_file: relocationFile, relocation } : {}),
+            next_command: recovery ? `dd-flow run recovery inspect ${status.run.id} --project-root ${JSON.stringify(projectRoot)} --json` : `dd-flow stage start ${status.run.id} --stage ${manifest.stage_entry} --project-root ${JSON.stringify(projectRoot)} --json`
         };
     }
     finally {
@@ -180,9 +344,10 @@ 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_home: started.run.run_home_path, target_stage: "specify" };
+    return { ok: true, run_id: started.run.id, run_root: started.run.run_root, target_stage: "specify" };
 }
 function assertDedicatedHome(context, projectId, runId) {
     const projects = context.db.get("SELECT COUNT(*) AS count FROM projects")?.count ?? 0;
@@ -194,18 +359,72 @@ 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) {
+/** A stage-entry import is a new experiment, not a lease takeover or recovery.
+ * Keep source authority as evidence, never as executable target inventory. */
+function detachSnapshotRuntimeOwners(context, snapshot, manifest) {
+    const hasTable = (table) => Boolean(context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?", [table]));
+    if (hasTable("run_recovery_guards") && context.db.get("SELECT 1 FROM run_recovery_guards WHERE status IN ('draining','sealed','resuming') LIMIT 1"))
+        throw new AppError("snapshot_control_requires_recovery", "A fenced RUN requires explicit recovery, not a stage-entry fork", 1);
+    if (context.db.get("SELECT 1 FROM merge_requests WHERE status IN ('dispatching','active','waiting_user','action_required','recovery_required') LIMIT 1"))
+        throw new AppError("snapshot_execution_active", "A stage-entry fork cannot discard an unresolved MERGE execution", 1);
+    const detachedTables = ["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;
+    try {
+        if (resources)
+            registerStoreWriter(resources);
+        const resourceTables = Object.fromEntries(["managed_resources", "managed_processes"].filter(table => resources?.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?").get(table)).map(table => [table, resources.prepare(`SELECT * FROM ${table}`).all()]));
+        const directory = path.join(context.ddFlowHome, "snapshot-imports");
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const file = path.join(directory, `${crypto.randomUUID()}.json`);
+        fs.writeFileSync(file, `${JSON.stringify({ schema_id: "dd-flow/snapshot-runtime-lineage@1", source_snapshot: snapshot, source_manifest_sha256: fileHash(path.join(snapshot, "snapshot.json")), source_runtime: manifest.dd_flow_home, restored_runtime: context.ddFlowHome, run_id: manifest.run_id, run_tables: runTables, resource_tables: resourceTables }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+        syncPath(file);
+        syncPath(directory);
+        context.db.beginWriteTransaction();
+        try {
+            context.db.run("UPDATE sessions SET metadata_json = json_set(metadata_json, '$.snapshot_import', json(?))", [JSON.stringify({ lineage_file: file, lineage_sha256: fileHash(file) })]);
+            for (const table of detachedTables)
+                context.db.exec(`DELETE FROM ${table}`);
+            context.db.run("UPDATE merge_requests SET dispatch_owner = NULL, dispatch_lease_token = NULL, dispatch_lease_expires_at = NULL, lock_acquired_at = NULL, adapter_receipt_json = NULL");
+            // Only the copied dedicated registry is touched. Source/external homes
+            // are historical references in the archive and are never opened here.
+            if (resources) {
+                resources.exec("BEGIN IMMEDIATE");
+                try {
+                    for (const table of Object.keys(resourceTables))
+                        resources.exec(`DELETE FROM ${table}`);
+                    resources.exec("COMMIT");
+                }
+                catch (error) {
+                    resources.exec("ROLLBACK");
+                    throw error;
+                }
+            }
+            context.db.exec("COMMIT");
+        }
+        catch (error) {
+            context.db.exec("ROLLBACK");
+            throw error;
+        }
+        return file;
+    }
+    finally {
+        resources?.close();
+    }
+}
+function rebaseRuntime(context, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome, recovery = false) {
     context.db.exec("PRAGMA foreign_keys = OFF");
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
         context.db.run("UPDATE projects SET root = ?", [newRoot]);
         context.db.run("UPDATE runs SET project_root = ?, workspace_root = ?", [newRoot, newWorkspace]);
@@ -214,7 +433,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"])
@@ -224,7 +448,10 @@ 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");
     }
@@ -235,24 +462,21 @@ function rebaseRuntime(context, oldRoot, newRoot, oldWorkspace, newWorkspace, ol
     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`);
             }
         }
     };
@@ -283,9 +507,9 @@ function snapshotWorkspace(workspaceRoot, projectRoot, output) {
         throw new AppError("snapshot_workspace_invalid", "Feature workspace has no readable HEAD", 1, { workspace_root: workspaceRoot });
     const workspace = path.join(output, "workspace");
     const bundle = path.join(output, "workspace.bundle");
-    fs.cpSync(workspaceRoot, workspace, { recursive: true, verbatimSymlinks: true, filter: (source) => path.basename(source) !== ".git" });
+    fs.cpSync(workspaceRoot, workspace, { recursive: true, verbatimSymlinks: true, filter: snapshotPayloadAllowed });
     runGit(projectRoot, ["bundle", "create", bundle, branch]);
-    return { kind: "git_worktree", source_root: workspaceRoot, branch, base_ref: baseRef, sha256: treeHash(workspace), bundle_sha256: fileHash(bundle) };
+    return { kind: "git_worktree", source_root: workspaceRoot, branch, base_ref: baseRef, sha256: treeHash(workspace), bundle_sha256: fileHash(bundle), ...snapshotIndex(workspaceRoot, output, "workspace") };
 }
 function restoreWorkspace(snapshot, manifest, projectRoot, ddFlowHome) {
     if (manifest.workspace.kind === "project")
@@ -308,6 +532,7 @@ function restoreWorkspace(snapshot, manifest, projectRoot, ddFlowHome) {
         throw new AppError("snapshot_workspace_restore_failed", "Snapshot Git bundle did not restore the frozen feature base", 1, { branch: manifest.workspace.branch, expected_base: manifest.workspace.base_ref });
     runGit(projectRoot, ["worktree", "add", workspaceRoot, manifest.workspace.branch]);
     replaceProjectTree(workspaceRoot, source);
+    restoreIndex(snapshot, "workspace", manifest.workspace, workspaceRoot);
     return fs.realpathSync(workspaceRoot);
 }
 function sourceWorkspaceRoot(manifest) {
@@ -320,7 +545,7 @@ function snapshotProjectGit(projectRoot, output) {
         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 bundle = path.join(output, "project.bundle");
     runGit(projectRoot, ["bundle", "create", bundle, "--all"]);
-    return { branch, head, bundle_sha256: fileHash(bundle) };
+    return { branch, head, bundle_sha256: fileHash(bundle), ...snapshotIndex(projectRoot, output, "project") };
 }
 function restoreProjectGit(snapshot, source, projectRoot) {
     const bundle = path.join(snapshot, "project.bundle");
@@ -330,6 +555,128 @@ function restoreProjectGit(snapshot, source, projectRoot) {
     runGit(projectRoot, ["init", "-b", source.branch]);
     runGit(projectRoot, ["fetch", bundle, `+refs/heads/${source.branch}:refs/remotes/snapshot/${source.branch}`]);
     runGit(projectRoot, ["checkout", "-B", source.branch, source.head]);
+    restoreIndex(snapshot, "project", source, projectRoot);
+}
+const mergeStateFiles = ["MERGE_HEAD", "MERGE_MSG", "MERGE_MODE", "ORIG_HEAD", "AUTO_MERGE"];
+function indexEntries(root) {
+    const entries = Buffer.from(gitBytes(root, ["ls-files", "--stage", "-z"])
+        .toString("utf8").split("\0").filter(entry => entry && snapshotEnvironmentAllowed(entry.slice(entry.indexOf("\t") + 1)))
+        .map(entry => `${entry}\0`).join(""));
+    const merge = {};
+    for (const name of mergeStateFiles) {
+        const file = git(root, ["rev-parse", "--git-path", name]);
+        if (!file)
+            throw new AppError("snapshot_index_invalid", "Could not locate Git merge state", 1);
+        const resolved = path.resolve(root, file);
+        if (fs.existsSync(resolved))
+            merge[name] = fs.readFileSync(resolved).toString("base64");
+    }
+    return Buffer.from(JSON.stringify({ entries: entries.toString("base64"), merge }));
+}
+function snapshotIndex(root, output, name) {
+    const bytes = indexEntries(root);
+    const value = JSON.parse(bytes.toString());
+    const objects = new Set();
+    for (const entry of Buffer.from(value.entries, "base64").toString("utf8").split("\0").filter(Boolean)) {
+        const match = /^\d{6} ([a-f0-9]{40,64}) [0-3]\t/.exec(entry);
+        if (!match)
+            throw new AppError("snapshot_index_invalid", "Malformed Git index entry", 1);
+        // Gitlinks belong to another repository and are preserved as index IDs.
+        if (!entry.startsWith("160000 "))
+            objects.add(match[1]);
+    }
+    for (const name of ["MERGE_HEAD", "ORIG_HEAD", "AUTO_MERGE"]) {
+        if (value.merge[name])
+            for (const oid of Buffer.from(value.merge[name], "base64").toString().trim().split("\n")) {
+                if (!/^[a-f0-9]{40,64}$/.test(oid))
+                    throw new AppError("snapshot_index_invalid", "Malformed Git merge reference", 1);
+                objects.add(oid);
+            }
+    }
+    const payload = path.join(output, `${name}.index.patch`);
+    const pack = path.join(output, `${name}.index.pack`);
+    fs.writeFileSync(payload, bytes);
+    fs.writeFileSync(pack, gitBytes(root, ["pack-objects", "--stdout", "--revs"], Buffer.from([...objects].sort().join("\n") + "\n")));
+    return { index_format: "entries@1", index_sha256: fileHash(payload), index_objects_sha256: fileHash(pack) };
+}
+function gitBytes(root, args, input) {
+    const result = spawnSync("git", ["-C", root, ...args], { input, maxBuffer: 64 * 1024 * 1024 });
+    if (result.status !== 0)
+        throw new AppError("snapshot_index_invalid", "Could not preserve Git index objects", 1, { args, stderr: result.stderr?.toString().trim() });
+    return result.stdout;
+}
+function indexPatch(root) {
+    const result = spawnSync("git", ["-C", root, "diff", "--cached", "--binary", "--full-index", "--no-ext-diff", "HEAD", "--", ".", ":(exclude)**/.env", ":(exclude)**/.env.*"], { maxBuffer: 64 * 1024 * 1024 });
+    if (result.status !== 0)
+        throw new AppError("snapshot_index_invalid", "Could not capture Git index", 1);
+    return result.stdout;
+}
+function restoreIndex(snapshot, name, metadata, root) {
+    if (!metadata.index_sha256)
+        return;
+    const file = path.join(snapshot, `${name}.index.patch`);
+    if (fileHash(file) !== metadata.index_sha256)
+        throw new AppError("snapshot_checksum_mismatch", "Snapshot Git index checksum does not match", 1);
+    if (metadata.index_format === "entries@1") {
+        const pack = path.join(snapshot, `${name}.index.pack`);
+        if (!metadata.index_objects_sha256 || fileHash(pack) !== metadata.index_objects_sha256)
+            throw new AppError("snapshot_checksum_mismatch", "Snapshot Git index object checksum does not match", 1);
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        gitBytes(root, ["unpack-objects"], fs.readFileSync(pack));
+        runGit(root, ["read-tree", "--empty"]);
+        gitBytes(root, ["update-index", "-z", "--index-info"], Buffer.from(value.entries, "base64"));
+        for (const name of mergeStateFiles) {
+            const target = git(root, ["rev-parse", "--git-path", name]);
+            if (!target)
+                throw new AppError("snapshot_index_invalid", "Could not locate restored Git merge state", 1);
+            if (value.merge[name] !== undefined)
+                fs.writeFileSync(path.resolve(root, target), Buffer.from(value.merge[name], "base64"));
+            else
+                fs.rmSync(path.resolve(root, target), { force: true });
+        }
+        return;
+    }
+    if (fs.statSync(file).size)
+        runGit(root, ["apply", "--cached", "--binary", file]);
+}
+export function verifyRecoverySnapshot(snapshot, input, checkWorkingState = true) {
+    const manifest = readManifest(snapshot);
+    if (manifest.purpose !== "recovery" || manifest.recovery_id !== input.recoveryId || manifest.run_id !== input.runId)
+        throw new AppError("recovery_capture_invalid", "Snapshot does not identify this recovery", 1);
+    const entries = [
+        { name: "project", root: input.projectRoot, hash: manifest.project_sha256, git: manifest.project_git, head: manifest.project_git.head },
+        ...(manifest.workspace.kind === "git_worktree" ? [{ name: "workspace", root: input.workspaceRoot, hash: manifest.workspace.sha256, git: manifest.workspace, head: manifest.workspace.base_ref }] : [])
+    ];
+    verifySnapshotPayload(snapshot, manifest);
+    for (const entry of entries) {
+        const expectedModes = manifest.payload_modes?.[entry.name];
+        if (checkWorkingState && expectedModes && treeModesHash(entry.root, true) !== expectedModes)
+            throw new AppError("recovery_workspace_drift", "Executable file modes changed after recovery capture", 1, { payload: entry.name });
+        if (checkWorkingState && (treeHash(entry.root, true) !== entry.hash || git(entry.root, ["rev-parse", "HEAD"]) !== entry.head || git(entry.root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) !== entry.git.branch || (entry.git.index_sha256 && crypto.createHash("sha256").update(entry.git.index_format === "entries@1" ? indexEntries(entry.root) : indexPatch(entry.root)).digest("hex") !== entry.git.index_sha256)))
+            throw new AppError("recovery_workspace_drift", "Working files or Git state changed after recovery capture", 1, { payload: entry.name });
+    }
+}
+/** Reuse an already published boundary only after checking its identity and
+ * every payload, including its Git index objects. Never overwrite evidence. */
+export function verifyControllerBoundarySnapshot(snapshot, input) {
+    const manifest = readManifest(snapshot), boundary = manifest.boundary_capture;
+    if (!boundary || manifest.consistency !== "controller_boundary_writer_barrier@1" || manifest.run_id !== input.runId || boundary.controller_id !== input.controllerId || boundary.operation_id !== input.operationId || boundary.boundary_key !== input.boundaryKey || manifest.stage_entry !== input.stageEntry || manifest.purpose !== (input.stageEntry ? "stage_entry" : "candidate") || !/^[a-f0-9]{64}$/.test(boundary.source_sha256) || boundary.observation?.settled !== true || boundary.observation.operation_id !== input.operationId)
+        throw new AppError("controller_boundary_snapshot_invalid", "Published snapshot does not prove this controller boundary", 1, { snapshot });
+    verifySnapshotPayload(snapshot, manifest);
+    const file = path.join(snapshot, "snapshot.json");
+    if (input.manifestSha256 !== undefined && fileHash(file) !== input.manifestSha256)
+        throw new AppError("snapshot_checksum_mismatch", "Boundary manifest no longer matches its retained publication receipt", 1, { snapshot });
+    return { snapshot, manifest: file, manifest_sha256: fileHash(file), purpose: manifest.purpose, stage_entry: manifest.stage_entry };
+}
+function verifySnapshotPayload(snapshot, manifest) {
+    if (treeHash(path.join(snapshot, "runtime")) !== manifest.runtime_sha256)
+        throw new AppError("snapshot_checksum_mismatch", "Snapshot runtime checksum does not match", 1);
+    verifySnapshotModes(snapshot, manifest);
+    const payloads = [{ name: "project", hash: manifest.project_sha256, git: manifest.project_git }, ...(manifest.workspace.kind === "git_worktree" ? [{ name: "workspace", hash: manifest.workspace.sha256, git: manifest.workspace }] : [])];
+    for (const payload of payloads) {
+        if (treeHash(path.join(snapshot, payload.name)) !== payload.hash || fileHash(path.join(snapshot, `${payload.name}.bundle`)) !== payload.git.bundle_sha256 || payload.git.index_sha256 && fileHash(path.join(snapshot, `${payload.name}.index.patch`)) !== payload.git.index_sha256 || payload.git.index_format === "entries@1" && (!payload.git.index_objects_sha256 || fileHash(path.join(snapshot, `${payload.name}.index.pack`)) !== payload.git.index_objects_sha256))
+            throw new AppError("snapshot_checksum_mismatch", "Snapshot payload or Git index checksum does not match", 1, { payload: payload.name });
+    }
 }
 function git(root, args) {
     const result = spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
@@ -341,12 +688,199 @@ 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 snapshotEnvironmentAllowed(source) {
+    const name = path.basename(source);
+    // Public configuration template, not a local environment/credential file.
+    return name === ".env.example" || (name !== ".env" && !name.startsWith(".env."));
+}
+function snapshotPayloadAllowed(source) {
+    const name = path.basename(source);
+    return ![".git", "node_modules", ".cache", ".npm", ".pnpm-store"].includes(name)
+        && snapshotEnvironmentAllowed(source);
+}
+function runtimePayloadAllowed(source) {
+    return snapshotPayloadAllowed(source) && !["auth.json", "auth.bk", "credentials.json", ".credentials.json", "credentials", ".credentials", "id_rsa", "id_ed25519", "engines", "checkouts"].includes(path.basename(source));
+}
+/** Productive writers are fenced separately. Recheck copied bytes and Git
+ * state so an uncoordinated file writer cannot publish a mixed boundary. */
+function snapshotSourceVersion(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = context.db.get("SELECT workspace_root FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
+    if (!run)
+        throw new AppError("not_found", "Snapshot RUN is not registered", 1);
+    const resources = path.join(context.ddFlowHome, "runtime.sqlite");
+    // Resource heartbeats are not productive writers. Their semantic identities
+    // are rechecked by the owner; each resource DB is copied consistently.
+    const runtimeFilter = (file) => runtimePayloadAllowed(file) && !file.endsWith("-shm") && ![resources, `${resources}-wal`, `${resources}-journal`].includes(file);
+    const roots = [...new Set([projectRoot, run.workspace_root])];
+    return crypto.createHash("sha256").update(JSON.stringify([
+        treeHash(context.ddFlowHome, runtimeFilter), treeModesHash(context.ddFlowHome, runtimeFilter),
+        ...roots.map(root => [treeHash(root, true), treeModesHash(root, true), git(root, ["symbolic-ref", "--quiet", "HEAD"]), gitBytes(root, ["show-ref", "--head"]).toString("base64"), indexEntries(root).toString("base64")])
+    ])).digest("hex");
+}
+/** 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 = []) {
+    if (fs.lstatSync(source).isSymbolicLink())
+        throw new AppError("snapshot_runtime_symlink_outside_scope", "Recovery artifact roots must not be symbolic links", 1, { path: source });
+    const root = physicalPath(source);
+    if (isInside(root, physicalPath(destination)))
+        throw new AppError("snapshot_output_inside_runtime", "Recovery output must be outside its source artifact tree", 1);
+    const databases = [];
+    const sqlite = (file) => {
+        if (!fs.existsSync(file) || !fs.statSync(file).isFile())
+            return false;
+        const descriptor = fs.openSync(file, "r");
+        try {
+            const header = Buffer.alloc(16);
+            return fs.readSync(descriptor, header, 0, 16, 0) === 16 && header.toString() === "SQLite format 3\0";
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+    };
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.cpSync(source, destination, {
+        recursive: true, verbatimSymlinks: true,
+        filter: file => {
+            if (!runtimePayloadAllowed(file) || excluded.includes(file))
+                return false;
+            const stat = fs.lstatSync(file);
+            if (stat.isSymbolicLink()) {
+                if (scoped && !isInside(root, physicalPath(file)))
+                    throw new AppError("snapshot_runtime_symlink_outside_scope", "Recovery artifact link leaves its owned tree", 1, { path: file });
+                return true;
+            }
+            if (!stat.isDirectory() && !stat.isFile())
+                return false;
+            if (stat.isFile()) {
+                if (/-(?:wal|shm|journal)$/.test(file) && sqlite(file.replace(/-(?:wal|shm|journal)$/, "")))
+                    return false;
+                if (sqlite(file)) {
+                    databases.push(file);
+                    return false;
+                }
+            }
+            return true;
+        }
+    });
+    for (const file of databases) {
+        const db = new DatabaseSync(file, { readOnly: true });
+        try {
+            const target = source === file ? destination : path.join(destination, path.relative(source, file));
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            db.exec("PRAGMA busy_timeout = 4000");
+            db.exec(`VACUUM INTO '${target.replace(/'/g, "''")}'`);
+        }
+        finally {
+            db.close();
+        }
+    }
+}
+function captureRecoveryAuxiliary(context, captured, input) {
+    const runtime = path.join(input.output, "runtime");
+    const 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 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 (typeof filtered === "function" ? !filtered(file) : filtered && !snapshotPayloadAllowed(file))
+                continue;
             if (entry.isDirectory())
                 visit(file, rel);
             else if (entry.isFile()) {
@@ -362,13 +896,58 @@ function treeHash(root) {
     visit(root, "");
     return hash.digest("hex");
 }
+function treeModesHash(root, filtered = false) {
+    const entries = [];
+    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 (typeof filtered === "function" ? !filtered(file) : filtered && !snapshotPayloadAllowed(file))
+                continue;
+            if (entry.isDirectory())
+                visit(file);
+            else if (entry.isFile())
+                entries.push([path.relative(root, file), fs.statSync(file).mode & 0o111]);
+        }
+    };
+    visit(root);
+    return crypto.createHash("sha256").update(JSON.stringify(entries)).digest("hex");
+}
+function verifySnapshotModes(snapshot, manifest) {
+    if (!manifest.payload_modes)
+        return; // Legacy snapshots did not attest modes.
+    for (const name of ["project", "runtime", ...(manifest.workspace.kind === "git_worktree" ? ["workspace"] : [])]) {
+        if (treeModesHash(path.join(snapshot, name)) !== manifest.payload_modes[name])
+            throw new AppError("snapshot_checksum_mismatch", "Snapshot executable modes do not match manifest", 1, { payload: name });
+    }
+}
 function fileHash(file) { return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); }
+// Flush children before their directory entries, then publish and flush the
+// parent. Never follow snapshot symlinks into the original project tree.
+function syncSnapshotTree(root) {
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        const file = path.join(root, entry.name);
+        if (entry.isDirectory())
+            syncSnapshotTree(file);
+        else if (entry.isFile())
+            syncPath(file);
+    }
+    syncPath(root);
+}
+function syncPath(file) {
+    const descriptor = fs.openSync(file, "r");
+    try {
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
 function readManifest(snapshot) {
     const file = path.join(snapshot, "snapshot.json");
     if (!fs.existsSync(file))
         throw new AppError("snapshot_missing", "Snapshot manifest is missing", 1, { snapshot });
     const value = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (value.schema_id !== "dd-flow/eval-run-snapshot@5" || !value.run_id || !value.project_root || !value.dd_flow_home || typeof value.purpose !== "string" || !["stage_entry", "candidate"].includes(value.purpose) || (value.purpose === "stage_entry" && !value.stage_entry) || (value.purpose === "candidate" && value.stage_entry !== null) || !value.runtime_sha256 || !value.project_sha256 || !value.project_git || !value.workspace)
+    if (value.schema_id !== "dd-flow/eval-run-snapshot@5" || !value.run_id || !value.project_root || !value.dd_flow_home || typeof value.purpose !== "string" || !["stage_entry", "candidate", "incomplete", "recovery"].includes(value.purpose) || (value.purpose === "stage_entry" && !value.stage_entry) || (value.purpose !== "stage_entry" && value.stage_entry !== null) || !value.runtime_sha256 || !value.project_sha256 || !value.project_git || !value.workspace)
         throw new AppError("snapshot_invalid", "Snapshot manifest is invalid", 1, { snapshot });
     if (!value.project_git.branch || !value.project_git.head || !value.project_git.bundle_sha256)
         throw new AppError("snapshot_invalid", "Snapshot project Git metadata is incomplete", 1, { snapshot });