@deksden-com/dd-flow-cli 0.9.0-beta.19 → 0.9.0-beta.22

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.22
+
+### Patch Changes
+
+- Reject conflicting or ambiguous lifecycle receipts before any harness can
+  mutate a Session binding. Restore a Work-start receipt when its binding
+  fails, so the same verified invocation remains safely retryable.
+
+## 0.9.0-beta.21
+
+### Patch Changes
+
+- Validate every selected engine artifact and execute its pinned snapshot even when its version matches the router. Retain a new recovery interruption before root acknowledgement.
+
+## 0.9.0-beta.20
+
+### Patch Changes
+
+- Verify recovery payloads and workspace drift before resuming, preserve staged Git changes, publish snapshots through a temporary directory, and allow explicit recovery restoration into fresh targets. Fence RUN mutations and late asynchronous Work completion while recovery is active.
+
 ## 0.9.0-beta.19
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,8 +1,8 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.19",
-  "cli_commit": "02648aa2db37e9332089ca941b06f5735b563496",
-  "built_at": "2026-09-06T13:33:22.164Z",
+  "cli_version": "0.9.0-beta.22",
+  "cli_commit": "7a08ac0550694b06cec5438d5ed938d19f772418",
+  "built_at": "2026-09-07T02:03:13.276Z",
   "built_with_canon": {
     "version": "4.0.6",
     "commit": "2aafb30d23e3f646b736b7ead25438cab97b16bf",

package/dist/cli/help.js

@@ -157,7 +157,7 @@ Usage:
   dd-flow run prepare-vnext-specify --project-root <root> --slug <slug> --json
   dd-flow run recovery inspect|begin|seal|capture|resume <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run snapshot create <RUN-ID|RUN-short-id> (--stage-entry <stage>|--candidate|--incomplete|--recovery-id <RCV-ID>) --project-root <root> --output <directory> --json
-  dd-flow run snapshot restore --snapshot <directory> --project-root <prepared-root> --json
+  dd-flow run snapshot restore --snapshot <directory> --project-root <prepared-root> [--recovery-id <RCV-ID>] --json
   dd-flow run snapshot bootstrap create --project-root <root> --output <directory> --json
   dd-flow run snapshot bootstrap restore --snapshot <directory> --project-root <prepared-root> --json
   dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> --json

package/dist/cli/run-cli.js

@@ -49,7 +49,7 @@ import { renderWorkerPrompt } from "../services/prompts.js";
 import { finishStage, startStage } from "../services/stage-lifecycle.js";
 import { addWorkBatch, assertStageLifecycleOwner, assertWorkLifecycleOwner, cancelWork, deleteWork, failWork, finishWork, listWorks, mutateWorkDeps, retryWork, showWork, startWork } from "../services/work-registry.js";
 import { createEvalBootstrapSnapshot, createEvalRunSnapshot, prepareVnextSpecifyRun, restoreEvalBootstrapSnapshot, restoreEvalRunSnapshot } from "../services/eval-snapshots.js";
-import { beginRunRecovery, inspectRunRecovery, recordRecoveryCapture, resumeRunRecovery, sealRunRecovery } from "../services/run-recovery.js";
+import { acceptRunRecovery, beginRunRecovery, inspectRunRecovery, recordRecoveryCapture, resumeRunRecovery, sealRunRecovery } from "../services/run-recovery.js";
 import { loadExternalStageContext } from "../services/stage-context.js";
 import { stopManagedProcess, confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, reconcileExpiredManagedProcesses, registerManagedProcess } from "../services/managed-processes.js";
 import { startRuntimeService } from "../services/runtime-service.js";
@@ -763,8 +763,9 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         return deleteWork(context, requiredPosition(parsed, 0, "work-id"));
     if (family === "work" && command === "start") {
         const hookEventId = optionalOption(parsed, "hook-event-id");
+        const recoveryId = optionalOption(parsed, "recovery-id");
         const projectRoot = requiredScopeProjectRoot(scopeProjectRoot, "work start");
-        return startWork(context, requiredPosition(parsed, 0, "work-id"), { ...(hookEventId ? { hookEventId } : {}), projectRoot });
+        return startWork(context, requiredPosition(parsed, 0, "work-id"), { ...(hookEventId ? { hookEventId } : {}), ...(recoveryId ? { recoveryId } : {}), projectRoot });
     }
     if (family === "work" && command === "finish") {
         const resultFile = optionalOption(parsed, "result-file");
@@ -1476,8 +1477,10 @@ function dispatchRun(context, command, parsed) {
         if (action === "capture")
             return recordRecoveryCapture(context, { projectRoot, runId, recoveryId: requiredOption(parsed, "recovery-id"), capturePath: requiredOption(parsed, "capture-path") });
         if (action === "resume")
-            return resumeRunRecovery(context, { projectRoot, runId, recoveryId: requiredOption(parsed, "recovery-id") });
-        throw new AppError("usage", "Use: dd-flow run recovery inspect|begin|seal|capture|resume", 2);
+            return resumeRunRecovery(context, { projectRoot, runId, recoveryId: requiredOption(parsed, "recovery-id"), daemonId: requiredOption(parsed, "daemon-id"), harness: requiredOption(parsed, "harness"), nativeSessionId: requiredOption(parsed, "native-session-id") });
+        if (action === "accept")
+            return acceptRunRecovery(context, { projectRoot, runId, recoveryId: requiredOption(parsed, "recovery-id"), ...(optionalOption(parsed, "hook-event-id") ? { hookEventId: optionalOption(parsed, "hook-event-id") } : {}) });
+        throw new AppError("usage", "Use: dd-flow run recovery inspect|begin|seal|capture|resume|accept", 2);
     }
     if (command === "snapshot") {
         const action = requiredPosition(parsed, 0, "snapshot action");
@@ -1518,6 +1521,7 @@ function dispatchRun(context, command, parsed) {
         if (action === "restore")
             return restoreEvalRunSnapshot(context, {
                 snapshot: requiredOption(parsed, "snapshot"),
+                ...(optionalOption(parsed, "recovery-id") ? { recoveryId: requiredOption(parsed, "recovery-id") } : {}),
                 projectRoot: requiredOption(parsed, "project-root")
             });
         throw new AppError("usage", "Use: dd-flow run snapshot bootstrap create|restore | dd-flow run snapshot create <RUN> (--stage-entry <stage>|--candidate) --project-root <path> --output <directory> | dd-flow run snapshot restore --snapshot <directory> --project-root <path>", 2);

package/dist/services/dashboard.js

@@ -19,6 +19,8 @@ export function getCmuxStatus(context, input) {
 }
 export function renderDashboard(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    if (projectRecoveryGuarded(context, project.id))
+        throw new AppError("run_recovery_guarded", "Project dashboard is frozen while its RUN is retained for recovery", 1);
     const format = parseDashboardFormat(input.format);
     if (format === "html") {
         if (input.protocol) {
@@ -170,6 +172,10 @@ export function refreshAllDashboards(context, input = {}) {
 }
 export function autoRefreshDashboards(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    // Hooks and usage ingestion continue to record receipts after capture.
+    // Their derived timestamp must not mutate the captured workspace.
+    if (projectRecoveryGuarded(context, project.id))
+        return { ok: true, skipped: true, reason: "run_recovery_guarded" };
     const config = readProjectConfig(context, project.id);
     if (!config.dashboard.auto_refresh) {
         return { ok: true, skipped: true, reason: "dashboard_auto_refresh_disabled" };
@@ -196,6 +202,9 @@ export function autoRefreshDashboards(context, input) {
     }
     return result;
 }
+function projectRecoveryGuarded(context, projectId) {
+    return Boolean(context.db.get("SELECT 1 FROM run_recovery_guards WHERE project_id = ? AND status IN ('draining', 'sealed', 'resuming') LIMIT 1", [projectId]));
+}
 export function dashboardSummary(context, projectId, projectRoot) {
     const config = readProjectConfig(context, projectId);
     return {

package/dist/services/engines.js

@@ -174,7 +174,9 @@ export function routeArgsThroughEngine(context, args, io, stdin, env, resolvedPr
     if (!selection.selected)
         return Promise.resolve(null);
     const current = getCliBuildInfo();
-    if (selection.selected.package_name === current.package_name && selection.selected.package_version === current.version) {
+    const currentRoot = findPackageRoot(path.dirname(sourceFile));
+    if (selection.selected.package_name === current.package_name && selection.selected.package_version === current.version
+        && currentRoot !== null && fs.realpathSync(selection.selected.snapshot_root) === fs.realpathSync(currentRoot)) {
         return Promise.resolve({ routed: true, exitCode: 0, inProcess: true });
     }
     const entrypoint = resolveManifestEntrypoint(selection.selected);
@@ -383,11 +385,7 @@ export function selectEngine(context, input, options = {}, classification = inpu
     const manifests = readInstalledManifests(engineStoreRoot(context.ddFlowHome))
         .filter((manifest) => manifest.package_name === packageName)
         .filter((manifest) => requiredRange !== null && satisfiesRange(manifest.package_version, requiredRange))
-        .filter((manifest) => options.allowCurrentInProcess
-        && manifest.package_name === build.package_name
-        && manifest.package_version === build.version
-        ? true
-        : manifestHealthy(manifest))
+        .filter((manifest) => manifestHealthy(manifest))
         .sort((a, b) => {
         const versionOrder = compareSemverStrings(b.package_version, a.package_version);
         if (versionOrder !== 0)

package/dist/services/eval-snapshots.js

@@ -49,6 +49,31 @@ export function restoreEvalBootstrapSnapshot(_context, input) {
  * to infer a safe subset of SQLite rows.
  */
 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 {
+        const result = captureEvalRunSnapshot(context, { ...input, output: temporary });
+        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);
+        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.
@@ -117,6 +142,7 @@ export function createEvalRunSnapshot(context, input) {
         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);
@@ -135,13 +161,21 @@ export function restoreEvalRunSnapshot(context, input) {
     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 === "recovery")
-        throw new AppError("snapshot_recovery_requires_explicit_restore", "Recovery snapshots require the recovery runner; they are not a generic stage-entry fixture", 1, { snapshot });
+    const recovery = manifest.purpose === "recovery";
+    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);
+    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"].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 });
@@ -151,6 +185,7 @@ export function restoreEvalRunSnapshot(context, input) {
         throw new AppError("snapshot_checksum_mismatch", "Snapshot runtime checksum does not match manifest", 1, { snapshot });
     if (treeHash(sourceProject) !== manifest.project_sha256)
         throw new AppError("snapshot_checksum_mismatch", "Snapshot project checksum does not match manifest", 1, { snapshot });
+    verifySnapshotModes(snapshot, manifest);
     clearProjectTree(projectRoot, false);
     restoreProjectGit(snapshot, manifest.project_git, projectRoot);
     replaceProjectTree(projectRoot, sourceProject);
@@ -162,14 +197,26 @@ 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);
+        rebaseRuntime(restored, manifest.project_root, projectRoot, sourceWorkspaceRoot(manifest), workspaceRoot, manifest.dd_flow_home, context.ddFlowHome, recovery);
         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 (!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",
@@ -180,7 +227,8 @@ 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`
+            ...(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 {
@@ -221,7 +269,7 @@ function assertTerminalCandidate(stages) {
     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) {
+function rebaseRuntime(context, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome, recovery = false) {
     context.db.exec("PRAGMA foreign_keys = OFF");
     context.db.exec("BEGIN IMMEDIATE");
     try {
@@ -242,7 +290,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");
     }
@@ -253,7 +304,10 @@ 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);
+    // SQLite owns operational paths. Imported packets, results and journals are
+    // historical bytes; the relocation receipt records their path mapping.
+    if (!recovery)
+        rewriteStructuredFiles(context.ddFlowHome, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
 }
 function rewriteStructuredFiles(root, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) {
     const visit = (dir) => {
@@ -303,7 +357,7 @@ function snapshotWorkspace(workspaceRoot, projectRoot, output) {
     const bundle = path.join(output, "workspace.bundle");
     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")
@@ -326,6 +380,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) {
@@ -338,7 +393,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");
@@ -348,6 +403,110 @@ 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 = gitBytes(root, ["ls-files", "--stage", "-z", "--", ".", ":(exclude)**/.env", ":(exclude)**/.env.*"]);
+    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 }] : [])
+    ];
+    if (treeHash(path.join(snapshot, "runtime")) !== manifest.runtime_sha256)
+        throw new AppError("snapshot_checksum_mismatch", "Recovery runtime checksum does not match", 1);
+    verifySnapshotModes(snapshot, manifest);
+    for (const entry of entries) {
+        const expectedModes = manifest.payload_modes?.[entry.name];
+        if (checkWorkingState && expectedModes && treeModesHash(entry.root, true) !== expectedModes)
+            throw new AppError("recovery_workspace_drift", "Executable file modes changed after recovery capture", 1, { payload: entry.name });
+        if (treeHash(path.join(snapshot, entry.name)) !== entry.hash || fileHash(path.join(snapshot, `${entry.name}.bundle`)) !== entry.git.bundle_sha256 || (entry.git.index_sha256 && fileHash(path.join(snapshot, `${entry.name}.index.patch`)) !== entry.git.index_sha256))
+            throw new AppError("snapshot_checksum_mismatch", "Recovery payload checksum does not match", 1, { payload: entry.name });
+        if (entry.git.index_format === "entries@1" && (!entry.git.index_objects_sha256 || fileHash(path.join(snapshot, `${entry.name}.index.pack`)) !== entry.git.index_objects_sha256))
+            throw new AppError("snapshot_checksum_mismatch", "Recovery Git object checksum does not match", 1, { payload: entry.name });
+        if (checkWorkingState && (treeHash(entry.root, true) !== entry.hash || git(entry.root, ["rev-parse", "HEAD"]) !== entry.head || git(entry.root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) !== entry.git.branch || (entry.git.index_sha256 && crypto.createHash("sha256").update(entry.git.index_format === "entries@1" ? indexEntries(entry.root) : indexPatch(entry.root)).digest("hex") !== entry.git.index_sha256)))
+            throw new AppError("recovery_workspace_drift", "Working files or Git state changed after recovery capture", 1, { payload: entry.name });
+    }
 }
 function git(root, args) {
     const result = spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
@@ -364,12 +523,14 @@ function snapshotPayloadAllowed(source) {
     return ![".git", "node_modules", ".cache", ".npm", ".pnpm-store"].includes(name)
         && name !== ".env" && !name.startsWith(".env.");
 }
-function treeHash(root) {
+function treeHash(root, filtered = false) {
     const hash = crypto.createHash("sha256");
     const visit = (dir, relative) => {
         for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
             const file = path.join(dir, entry.name);
             const rel = path.join(relative, entry.name);
+            if (filtered && !snapshotPayloadAllowed(file))
+                continue;
             if (entry.isDirectory())
                 visit(file, rel);
             else if (entry.isFile()) {
@@ -385,7 +546,52 @@ 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 (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))