@deksden-com/dd-flow-cli 0.9.0-beta.18 → 0.9.0-beta.21

package/dist/services/eval-snapshots.js

@@ -49,13 +49,44 @@ 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.
     const project = requireProjectByRoot(context, projectRoot);
     const status = getFlowRunStatus(context, { projectRoot, runId: input.runId });
     assertDedicatedHome(context, project.id, input.runId);
-    if (input.incomplete) { /* Forensic evidence is not an accepted or restorable boundary. */ }
+    const recovery = typeof input.recoveryId === "string";
+    if (recovery) {
+        const guard = context.db.get("SELECT status, recovery_id FROM run_recovery_guards WHERE project_id = ? AND run_id = ? AND recovery_id = ?", [project.id, input.runId, input.recoveryId]);
+        if (!guard || guard.status !== "sealed")
+            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)
@@ -66,7 +97,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 (!input.incomplete && 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))
@@ -103,14 +134,15 @@ export function createEvalRunSnapshot(context, input) {
         project_id: project.id,
         project_root: projectRoot,
         dd_flow_home: context.ddFlowHome,
-        purpose: input.incomplete ? "incomplete" : input.candidate ? "candidate" : "stage_entry",
-        stage_entry: input.incomplete || input.candidate ? null : input.stageEntry,
-        ...(input.incomplete ? { consistency: "sqlite_read_snapshot_files_copied_nonatomically", active_child_work_count: activeChildren, restorable: false } : {}),
+        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);
@@ -129,11 +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 });
+    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 });
@@ -143,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);
@@ -154,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",
@@ -172,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 {
@@ -213,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 {
@@ -234,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");
     }
@@ -245,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) => {
@@ -295,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")
@@ -318,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) {
@@ -330,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");
@@ -340,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" });
@@ -356,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()) {
@@ -377,13 +546,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 (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", "incomplete"].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)
+    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 });