@deksden-com/dd-flow-cli 0.9.0-beta.144 → 0.9.0-beta.149

package/dist/services/eval-snapshots.js

@@ -23,18 +23,21 @@ import { localEnvironmentAllowed, projectServicePathFilter } from "./workspace-f
 import { cleanupScopeWriters } from "./scope-writer-cleanup.js";
 import { PreparedInstalledFlowSource } from "./installed-flow-source.js";
 import { readSetupStatus } from "./setup.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
 import { isObservationOperation, nativeInventoryVersion, retainedDaemonOperations } from "./run-control.js";
 /** Capture the only flow boundary which exists before `stage start --bootstrap` creates a RUN. */
 export function prepareEvalBootstrapSnapshot(context, input) {
     let source;
     if (input.flow !== undefined && input.flow !== "sdlc") {
-        if (input.flow !== "mb-init")
+        if (input.flow !== "mb-init" && input.flow !== "mb-upgrade" && !isDiagnosticFlow(input.flow))
             throw new AppError("snapshot_flow_unsupported", "Bootstrap snapshot flow is not registered", 2, { phase: "prepare", effect: "no_effect" });
         const home = context.env.DD_FLOW_CONFIG_HOME ?? context.ddFlowHome;
         const selected = readSetupStatus(home);
         if (!selected.installation)
             throw new AppError("snapshot_flow_unavailable", "Bootstrap snapshot requires the selected installed flow", 2, { phase: "prepare", effect: "no_effect" });
         source = PreparedInstalledFlowSource.fromInstalledRelease(home, selected.installation.manifest_sha256, input.flow);
+        if (source.resolveRegisteredFlow().descriptor.stages[0]?.id !== "preflight")
+            throw new AppError("snapshot_flow_unsupported", "Memory bootstrap requires its preflight entry", 2, { phase: "prepare", effect: "no_effect" });
     }
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const output = path.resolve(input.output);
@@ -68,7 +71,7 @@ export function createEvalBootstrapSnapshot(context, input) {
         const manifest = {
             schema_id: source ? "dd-eval/bootstrap-snapshot@2" : "dd-eval/bootstrap-snapshot@1",
             stage: source?.resolveRegisteredFlow().descriptor.stages[0]?.id ?? "specify",
-            ...(source ? { flow: { id: "mb-init", source_sha256: source.sha256, descriptor_sha256: source.descriptorReference().sha256 } } : {}),
+            ...(source ? { flow: { id: source.resolveRegisteredFlow().descriptor.id, source_sha256: source.sha256, descriptor_sha256: source.descriptorReference().sha256 } } : {}),
             project_root: projectRoot,
             project_sha256: treeHash(path.join(temporary, "project")),
             project_git: snapshotProjectGit(projectRoot, temporary)
@@ -220,7 +223,7 @@ export function prepareEvalRunSnapshotCreation(context, input) {
         throw new AppError("snapshot_output_inside_project", "Snapshot output must be outside the project and RUN workspace trees", 1, { output });
     prepareOutputFile(output);
     prepareSnapshotProjectGit(projectRoot, recovery && status.run.flow_kind === "mb-init");
-    prepareSnapshotWorkspace(workspaceRoot, projectRoot);
+    prepareSnapshotWorkspace(workspaceRoot, projectRoot, isDiagnosticFlow(status.run.flow_kind));
     return { projectRoot, project, status, recovery, output, workspaceRoot, activeChildren };
 }
 function captureEvalRunSnapshot(context, input) {
@@ -238,7 +241,7 @@ function captureEvalRunSnapshot(context, input) {
         }
     }
     else
-        copyRuntimeTree(context.ddFlowHome, path.join(output, "runtime"), false, [...databaseFiles, ...codexExclusions], grokProviderHomes(context.ddFlowHome), input.observationCuts);
+        copyRuntimeTree(context.ddFlowHome, path.join(output, "runtime"), false, [...databaseFiles, ...codexExclusions, ...(isDiagnosticFlow(status.run.flow_kind) ? [workspaceRoot] : [])], grokProviderHomes(context.ddFlowHome), input.observationCuts);
     for (const [file, cut] of input.journalCuts ?? []) {
         const target = path.join(output, "runtime", path.relative(context.ddFlowHome, file));
         fs.mkdirSync(path.dirname(target), { recursive: true });
@@ -278,7 +281,7 @@ function captureEvalRunSnapshot(context, input) {
         filter: projectPayloadFilter(projectRoot)
     });
     const projectGit = snapshotProjectGit(projectRoot, output, recovery && status.run.flow_kind === "mb-init");
-    const workspace = snapshotWorkspace(workspaceRoot, projectRoot, output);
+    const workspace = snapshotWorkspace(workspaceRoot, projectRoot, output, isDiagnosticFlow(status.run.flow_kind));
     // Accepted Work results are captured in SQLite. Their file representations
     // are retained evidence, not a second authority or a checkpoint gate.
     if (recovery) {
@@ -291,7 +294,7 @@ function captureEvalRunSnapshot(context, input) {
         }
     }
     const manifest = {
-        schema_id: projectGit.state === "unborn" ? "dd-flow/eval-run-snapshot@6" : "dd-flow/eval-run-snapshot@5",
+        schema_id: workspace.kind === "git_repository" ? "dd-flow/eval-run-snapshot@7" : projectGit.state === "unborn" ? "dd-flow/eval-run-snapshot@6" : "dd-flow/eval-run-snapshot@5",
         run_id: input.runId,
         project_id: project.id,
         project_root: projectRoot,
@@ -308,7 +311,7 @@ function captureEvalRunSnapshot(context, input) {
         ...(input.observationCuts ? { observation_cuts: [...input.observationCuts].map(([file, receipt]) => ({ path: path.relative(context.ddFlowHome, file), receipt })) } : {}),
         project_git: projectGit,
         workspace,
-        payload_modes: { project: treeModesHash(path.join(output, "project")), runtime: treeModesHash(path.join(output, "runtime")), ...(workspace.kind === "git_worktree" ? { workspace: treeModesHash(path.join(output, "workspace")) } : {}) },
+        payload_modes: { project: treeModesHash(path.join(output, "project")), runtime: treeModesHash(path.join(output, "runtime")), ...(workspace.kind !== "project" ? { workspace: treeModesHash(path.join(output, "workspace")) } : {}) },
         source_status: status
     };
     writeJson(path.join(output, "snapshot.json"), manifest);
@@ -434,7 +437,7 @@ export function prepareSnapshotOperationalDecision(input) {
 }
 function assertRunRestoreTargets(context, input, snapshot, projectRoot, manifest) {
     assertRestoreTargetSeparation(snapshot, [projectRoot, context.ddFlowHome]);
-    if (manifest.workspace.kind === "git_worktree") {
+    if (manifest.workspace.kind !== "project") {
         const workspaceRoot = restoredWorkspaceRoot(manifest, projectRoot, context.ddFlowHome);
         assertRestoreTargetSeparation(snapshot, [workspaceRoot]);
         if (isInside(physicalPath(projectRoot), physicalPath(workspaceRoot)) || isInside(physicalPath(workspaceRoot), physicalPath(projectRoot)) || physicalPath(workspaceRoot) === physicalPath(context.ddFlowHome))
@@ -460,105 +463,114 @@ export function restoreEvalRunSnapshot(context, input, prepared = prepareEvalRun
     const sourceManifestSha256 = fileHash(path.join(snapshot, "snapshot.json"));
     const importId = prearmedImportId ?? beginSnapshotImport({ home: context.ddFlowHome, projectRoot,
         workspaceRoot: restoredWorkspaceRoot(manifest, projectRoot, context.ddFlowHome), sourceManifestSha256 });
-    clearProjectTree(projectRoot, false);
-    restoreProjectGit(snapshot, manifest.project_git, projectRoot);
-    replaceProjectTree(projectRoot, sourceProject);
-    context.db.close?.();
-    fs.rmSync(context.ddFlowHome, { recursive: true, force: true });
-    fs.cpSync(sourceRuntime, context.ddFlowHome, { recursive: true, verbatimSymlinks: true });
-    const workspaceRoot = restoreWorkspace(snapshot, manifest, projectRoot, context.ddFlowHome);
-    // The dispatch context was intentionally closed before replacing db.sqlite.
-    // A fresh process owns all subsequent normal commands.
-    const restored = createContext({ ...context.env, DD_FLOW_HOME: context.ddFlowHome }, "initialize", importId);
-    let result, primary, failed = false;
     try {
-        const runtimeLineage = recovery ? null : detachSnapshotRuntimeOwners(restored, snapshot, manifest);
-        const originalRunRoot = restored.db.get("SELECT run_root FROM runs WHERE id = ?", [manifest.run_id])?.run_root;
-        rebaseRuntime(restored, manifest.project_root, projectRoot, sourceWorkspaceRoot(manifest), workspaceRoot, manifest.dd_flow_home, context.ddFlowHome, recovery);
-        const publicationRun = restored.db.get("SELECT project_id, run_root FROM runs WHERE id = ?", [manifest.run_id]);
-        if (!originalRunRoot || !publicationRun?.run_root || !isInside(manifest.dd_flow_home, originalRunRoot) || !isInside(context.ddFlowHome, publicationRun.run_root))
-            throw new AppError("snapshot_invalid", "Restored publication roots are not bound to their runtime", 1);
-        const pathMapping = [{ from: manifest.dd_flow_home, to: context.ddFlowHome }, { from: sourceWorkspaceRoot(manifest), to: workspaceRoot }, { from: manifest.project_root, to: projectRoot }];
-        restored.db.run("INSERT INTO audit_events (project_id, event_type, forced, payload_json, created_at) VALUES (?, 'flow_run.publication_relocation', 0, ?, ?)", [publicationRun.project_id, JSON.stringify({ run_id: manifest.run_id, from: originalRunRoot, to: publicationRun.run_root, source_manifest_sha256: sourceManifestSha256, import_id: importId, path_mapping: pathMapping }), restored.now()]);
-        registerProject(restored, { root: projectRoot });
-        requireProjectByRoot(restored, projectRoot);
-        if (selectedProfile && runtimeLineage) {
-            const run = restored.db.get("SELECT run_root FROM runs WHERE id = ?", [manifest.run_id]);
-            if (routingInput) {
-                const artifact = path.join(run.run_root, selectedProfile.routing_input.artifact);
-                if (fs.existsSync(artifact)) {
-                    if (!fs.readFileSync(artifact).equals(routingInput.bytes))
-                        throw new AppError("snapshot_checksum_mismatch", "Existing routing input does not match its checksum", 1);
+        clearProjectTree(projectRoot, false);
+        restoreProjectGit(snapshot, manifest.project_git, projectRoot);
+        replaceProjectTree(projectRoot, sourceProject);
+        context.db.close?.();
+        fs.rmSync(context.ddFlowHome, { recursive: true, force: true });
+        fs.cpSync(sourceRuntime, context.ddFlowHome, { recursive: true, verbatimSymlinks: true });
+        const workspaceRoot = restoreWorkspace(snapshot, manifest, projectRoot, context.ddFlowHome);
+        // The dispatch context was intentionally closed before replacing db.sqlite.
+        // A fresh process owns all subsequent normal commands.
+        const restored = createContext({ ...context.env, DD_FLOW_HOME: context.ddFlowHome }, "initialize", importId);
+        let result, primary, failed = false;
+        try {
+            const runtimeLineage = recovery ? null : detachSnapshotRuntimeOwners(restored, snapshot, manifest);
+            const originalRunRoot = restored.db.get("SELECT run_root FROM runs WHERE id = ?", [manifest.run_id])?.run_root;
+            rebaseRuntime(restored, manifest.project_root, projectRoot, sourceWorkspaceRoot(manifest), workspaceRoot, manifest.dd_flow_home, context.ddFlowHome, recovery);
+            const publicationRun = restored.db.get("SELECT project_id, run_root FROM runs WHERE id = ?", [manifest.run_id]);
+            if (!originalRunRoot || !publicationRun?.run_root || !isInside(manifest.dd_flow_home, originalRunRoot) || !isInside(context.ddFlowHome, publicationRun.run_root))
+                throw new AppError("snapshot_invalid", "Restored publication roots are not bound to their runtime", 1);
+            const pathMapping = [{ from: manifest.dd_flow_home, to: context.ddFlowHome }, { from: sourceWorkspaceRoot(manifest), to: workspaceRoot }, { from: manifest.project_root, to: projectRoot }];
+            restored.db.run("INSERT INTO audit_events (project_id, event_type, forced, payload_json, created_at) VALUES (?, 'flow_run.publication_relocation', 0, ?, ?)", [publicationRun.project_id, JSON.stringify({ run_id: manifest.run_id, from: originalRunRoot, to: publicationRun.run_root, source_manifest_sha256: sourceManifestSha256, import_id: importId, path_mapping: pathMapping }), restored.now()]);
+            registerProject(restored, { root: projectRoot });
+            requireProjectByRoot(restored, projectRoot);
+            if (selectedProfile && runtimeLineage) {
+                const run = restored.db.get("SELECT run_root FROM runs WHERE id = ?", [manifest.run_id]);
+                if (routingInput) {
+                    const artifact = path.join(run.run_root, selectedProfile.routing_input.artifact);
+                    if (fs.existsSync(artifact)) {
+                        if (!fs.readFileSync(artifact).equals(routingInput.bytes))
+                            throw new AppError("snapshot_checksum_mismatch", "Existing routing input does not match its checksum", 1);
+                    }
+                    else
+                        fs.writeFileSync(artifact, routingInput.bytes, { flag: "wx", mode: 0o600 });
                 }
-                else
-                    fs.writeFileSync(artifact, routingInput.bytes, { flag: "wx", mode: 0o600 });
+                if (input.operationalDecisionFile) {
+                    if (!prepared.operationalDecisionBytes || !fs.readFileSync(input.operationalDecisionFile).equals(prepared.operationalDecisionBytes))
+                        throw new AppError("operational_decision_changed", "Accepted operational decision changed before import publication", 2);
+                    const binding = { project_id: publicationRun.project_id, run_id: manifest.run_id, ...selectedProfile.operational_decision.scope };
+                    const policyBytes = fs.readFileSync(path.resolve(projectRoot, selectedProfile.operational_decision.policy.path));
+                    const policySource = { path: `operational-policy.${selectedProfile.operational_decision.policy.sha256}.source.md`, sha256: crypto.createHash("sha256").update(policyBytes).digest("hex") };
+                    if (policySource.sha256 !== selectedProfile.operational_decision.policy.sha256)
+                        throw new AppError("operational_decision_policy_changed", "Imported policy changed before binding", 2);
+                    if (!fs.existsSync(path.join(run.run_root, policySource.path)))
+                        fs.writeFileSync(path.join(run.run_root, policySource.path), policyBytes, { flag: "wx" });
+                    const bytes = `${JSON.stringify({ schema_id: "dd-flow/run-operational-contract@1", binding, settings: { merge_delivery: selectedProfile.settings.merge_delivery, merge_cleanup: selectedProfile.settings.merge_cleanup }, decision: selectedProfile.operational_decision, policy_source: policySource }, null, 2)}\n`;
+                    const artifact = `operational-contract.${crypto.createHash("sha256").update(bytes).digest("hex")}.json`;
+                    fs.writeFileSync(path.join(run.run_root, artifact), bytes, { flag: "wx" });
+                    selectedProfile.operational_contract = { path: artifact, sha256: crypto.createHash("sha256").update(bytes).digest("hex"), policy_source: policySource, binding };
+                }
+                importFlowRunExecutionProfile(restored, { projectRoot, runId: manifest.run_id, stage: manifest.stage_entry, lineageFile: runtimeLineage, profile: selectedProfile });
             }
-            if (input.operationalDecisionFile) {
-                if (!prepared.operationalDecisionBytes || !fs.readFileSync(input.operationalDecisionFile).equals(prepared.operationalDecisionBytes))
-                    throw new AppError("operational_decision_changed", "Accepted operational decision changed before import publication", 2);
-                const binding = { project_id: publicationRun.project_id, run_id: manifest.run_id, ...selectedProfile.operational_decision.scope };
-                const policyBytes = fs.readFileSync(path.resolve(projectRoot, selectedProfile.operational_decision.policy.path));
-                const policySource = { path: `operational-policy.${selectedProfile.operational_decision.policy.sha256}.source.md`, sha256: crypto.createHash("sha256").update(policyBytes).digest("hex") };
-                if (policySource.sha256 !== selectedProfile.operational_decision.policy.sha256)
-                    throw new AppError("operational_decision_policy_changed", "Imported policy changed before binding", 2);
-                if (!fs.existsSync(path.join(run.run_root, policySource.path)))
-                    fs.writeFileSync(path.join(run.run_root, policySource.path), policyBytes, { flag: "wx" });
-                const bytes = `${JSON.stringify({ schema_id: "dd-flow/run-operational-contract@1", binding, settings: { merge_delivery: selectedProfile.settings.merge_delivery, merge_cleanup: selectedProfile.settings.merge_cleanup }, decision: selectedProfile.operational_decision, policy_source: policySource }, null, 2)}\n`;
-                const artifact = `operational-contract.${crypto.createHash("sha256").update(bytes).digest("hex")}.json`;
-                fs.writeFileSync(path.join(run.run_root, artifact), bytes, { flag: "wx" });
-                selectedProfile.operational_contract = { path: artifact, sha256: crypto.createHash("sha256").update(bytes).digest("hex"), policy_source: policySource, binding };
+            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);
             }
-            importFlowRunExecutionProfile(restored, { projectRoot, runId: manifest.run_id, stage: manifest.stage_entry, lineageFile: runtimeLineage, profile: selectedProfile });
+            const status = getFlowRunStatus(restored, { projectRoot, runId: manifest.run_id });
+            if (!recovery)
+                assertStageEntry(status.index.stage_runs ?? [], manifest.stage_entry);
+            else
+                restored.db.run("UPDATE run_recovery_guards SET capture_path = ? WHERE recovery_id = ? AND status = 'sealed'", [snapshot, input.recoveryId]);
+            if (!status.run.run_root)
+                throw new AppError("runtime_missing", "Restored RUN has no artifact root", 1, { run_id: manifest.run_id });
+            const runHome = status.run.run_root;
+            const expectedWorkspaceRoot = restoredWorkspaceRoot(manifest, projectRoot, context.ddFlowHome);
+            if (physicalPath(workspaceRoot) !== physicalPath(expectedWorkspaceRoot))
+                throw new AppError("snapshot_workspace_restore_failed", "Restored workspace differs from the import target", 1, { workspace_root: workspaceRoot, expected_workspace_root: expectedWorkspaceRoot });
+            completeSnapshotImport(context.ddFlowHome, importId, { projectRoot, workspaceRoot: expectedWorkspaceRoot, sourceManifestSha256 });
+            result = {
+                ok: true,
+                schema_id: "dd-flow/eval-run-restore@1",
+                snapshot,
+                run_id: status.run.id,
+                project_root: projectRoot,
+                workspace_root: workspaceRoot,
+                dd_flow_home: context.ddFlowHome,
+                run_home: runHome,
+                target_stage: manifest.stage_entry,
+                ...(runtimeLineage ? { runtime_lineage_file: runtimeLineage } : {}),
+                ...(recovery ? { recovery_id: input.recoveryId, native_session_portability: "requires_adapter_verification", relocation_file: relocationFile, relocation } : {}),
+                next_command: recovery ? `dd-flow run recovery inspect ${status.run.id} --project-root ${JSON.stringify(projectRoot)} --json` : `dd-flow stage start ${status.run.id} --stage ${manifest.stage_entry} --project-root ${JSON.stringify(projectRoot)} --json`
+            };
         }
-        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);
+        catch (error) {
+            primary = error;
+            failed = true;
         }
-        const status = getFlowRunStatus(restored, { projectRoot, runId: manifest.run_id });
-        if (!recovery)
-            assertStageEntry(status.index.stage_runs ?? [], manifest.stage_entry);
-        else
-            restored.db.run("UPDATE run_recovery_guards SET capture_path = ? WHERE recovery_id = ? AND status = 'sealed'", [snapshot, input.recoveryId]);
-        if (!status.run.run_root)
-            throw new AppError("runtime_missing", "Restored RUN has no artifact root", 1, { run_id: manifest.run_id });
-        const runHome = status.run.run_root;
-        const expectedWorkspaceRoot = restoredWorkspaceRoot(manifest, projectRoot, context.ddFlowHome);
-        if (physicalPath(workspaceRoot) !== physicalPath(expectedWorkspaceRoot))
-            throw new AppError("snapshot_workspace_restore_failed", "Restored workspace differs from the import target", 1, { workspace_root: workspaceRoot, expected_workspace_root: expectedWorkspaceRoot });
-        completeSnapshotImport(context.ddFlowHome, importId, { projectRoot, workspaceRoot: expectedWorkspaceRoot, sourceManifestSha256 });
-        result = {
-            ok: true,
-            schema_id: "dd-flow/eval-run-restore@1",
-            snapshot,
-            run_id: status.run.id,
-            project_root: projectRoot,
-            workspace_root: workspaceRoot,
-            dd_flow_home: context.ddFlowHome,
-            run_home: runHome,
-            target_stage: manifest.stage_entry,
-            ...(runtimeLineage ? { runtime_lineage_file: runtimeLineage } : {}),
-            ...(recovery ? { recovery_id: input.recoveryId, native_session_portability: "requires_adapter_verification", relocation_file: relocationFile, relocation } : {}),
-            next_command: recovery ? `dd-flow run recovery inspect ${status.run.id} --project-root ${JSON.stringify(projectRoot)} --json` : `dd-flow stage start ${status.run.id} --stage ${manifest.stage_entry} --project-root ${JSON.stringify(projectRoot)} --json`
-        };
+        const cleanup = cleanupScopeWriters([{ name: restored.ddFlowHome, db: restored.db, rollback: false, close: "always" }]);
+        if (failed) {
+            if (primary instanceof AppError && cleanup.length)
+                primary.details.import_cleanup_errors = cleanup;
+            throw primary;
+        }
+        if (cleanup.length)
+            throw new AppError("snapshot_import_cleanup_failed", "Snapshot imported but its connection could not be closed", 1, { effect: "committed", import_complete: true, import_cleanup_errors: cleanup });
+        return result;
     }
     catch (error) {
-        primary = error;
-        failed = true;
-    }
-    const cleanup = cleanupScopeWriters([{ name: restored.ddFlowHome, db: restored.db, rollback: false, close: "always" }]);
-    if (failed) {
-        if (primary instanceof AppError && cleanup.length)
-            primary.details.import_cleanup_errors = cleanup;
-        throw primary;
+        // The import fence and target writes have already started. A nested
+        // prepare/read validator must not report this operation as no-effect.
+        if (error instanceof AppError)
+            Object.assign(error.details, { phase: "restore", effect: error.details.effect === "committed" ? "committed" : "partial", import_id: importId, next_action: "reconcile_snapshot_import" });
+        throw error;
     }
-    if (cleanup.length)
-        throw new AppError("snapshot_import_cleanup_failed", "Snapshot imported but its connection could not be closed", 1, { effect: "committed", import_complete: true, import_cleanup_errors: cleanup });
-    return result;
 }
 export function prepareVnextSpecifyRun(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
@@ -749,27 +761,29 @@ function rebaseStructuredValue(value, oldRoot, newRoot, oldWorkspace, newWorkspa
 function rebasePathString(value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) { for (const [oldPrefix, newPrefix] of [[oldHome, newHome], [oldWorkspace, newWorkspace], [oldRoot, newRoot]])
     if (value === oldPrefix || value.startsWith(`${oldPrefix}${path.sep}`))
         return `${newPrefix}${value.slice(oldPrefix.length)}`; return value; }
-function prepareSnapshotWorkspace(workspaceRoot, projectRoot) {
+function prepareSnapshotWorkspace(workspaceRoot, projectRoot, allowUnborn = false) {
     if (samePath(workspaceRoot, projectRoot))
         return null;
     const branch = git(workspaceRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
     if (!branch)
         throw new AppError("snapshot_workspace_invalid", "Feature workspace must be on a named Git branch", 1, { workspace_root: workspaceRoot });
     const baseRef = git(workspaceRoot, ["rev-parse", "HEAD"]);
-    if (!baseRef)
+    if (!baseRef && !(allowUnborn && git(workspaceRoot, ['for-each-ref', '--format=%(refname)']) === ''))
         throw new AppError("snapshot_workspace_invalid", "Feature workspace has no readable HEAD", 1, { workspace_root: workspaceRoot });
     return { branch, baseRef };
 }
-function snapshotWorkspace(workspaceRoot, projectRoot, output) {
-    const prepared = prepareSnapshotWorkspace(workspaceRoot, projectRoot);
+function snapshotWorkspace(workspaceRoot, projectRoot, output, independent = false) {
+    const prepared = prepareSnapshotWorkspace(workspaceRoot, projectRoot, independent);
     if (!prepared)
         return { kind: "project" };
     const { branch, baseRef } = prepared;
     const workspace = path.join(output, "workspace");
     const bundle = path.join(output, "workspace.bundle");
     fs.cpSync(workspaceRoot, workspace, { recursive: true, verbatimSymlinks: true, filter: projectPayloadFilter(workspaceRoot) });
-    runGit(projectRoot, ["bundle", "create", bundle, branch]);
-    return { kind: "git_worktree", source_root: workspaceRoot, branch, base_ref: baseRef, sha256: treeHash(workspace), bundle_sha256: fileHash(bundle), ...snapshotIndex(workspaceRoot, output, "workspace") };
+    if (baseRef === null)
+        return { kind: 'git_repository', source_root: workspaceRoot, branch, base_ref: null, bundle_sha256: null, state: 'unborn', sha256: treeHash(workspace), ...snapshotIndex(workspaceRoot, output, 'workspace') };
+    runGit(independent ? workspaceRoot : projectRoot, ["bundle", "create", bundle, branch]);
+    return { kind: independent ? "git_repository" : "git_worktree", source_root: workspaceRoot, branch, base_ref: baseRef, sha256: treeHash(workspace), bundle_sha256: fileHash(bundle), ...snapshotIndex(workspaceRoot, output, "workspace") };
 }
 function restoreWorkspace(snapshot, manifest, projectRoot, ddFlowHome) {
     if (manifest.workspace.kind === "project")
@@ -778,15 +792,28 @@ function restoreWorkspace(snapshot, manifest, projectRoot, ddFlowHome) {
     const bundle = path.join(snapshot, "workspace.bundle");
     if (treeHash(source) !== manifest.workspace.sha256)
         throw new AppError("snapshot_checksum_mismatch", "Snapshot workspace checksum does not match manifest", 1, { snapshot });
-    if (!fs.existsSync(bundle) || fileHash(bundle) !== manifest.workspace.bundle_sha256)
+    if (manifest.workspace.state === 'unborn' ? fs.existsSync(bundle) : !fs.existsSync(bundle) || fileHash(bundle) !== manifest.workspace.bundle_sha256)
         throw new AppError("snapshot_checksum_mismatch", "Snapshot workspace Git bundle does not match manifest", 1, { snapshot });
     const workspaceRoot = restoredWorkspaceRoot(manifest, projectRoot, ddFlowHome);
     if (fs.existsSync(workspaceRoot))
         throw new AppError("snapshot_workspace_target_exists", "Snapshot feature workspace target already exists", 1, { workspace_root: workspaceRoot });
-    runGit(projectRoot, ["fetch", bundle, `+refs/heads/${manifest.workspace.branch}:refs/heads/${manifest.workspace.branch}`]);
-    if (git(projectRoot, ["rev-parse", `refs/heads/${manifest.workspace.branch}`]) !== manifest.workspace.base_ref)
-        throw new AppError("snapshot_workspace_restore_failed", "Snapshot Git bundle did not restore the frozen feature base", 1, { branch: manifest.workspace.branch, expected_base: manifest.workspace.base_ref });
-    runGit(projectRoot, ["worktree", "add", workspaceRoot, manifest.workspace.branch]);
+    if (manifest.workspace.kind === 'git_repository') {
+        fs.mkdirSync(path.dirname(workspaceRoot), { recursive: true });
+        if (manifest.workspace.state === 'unborn') {
+            fs.mkdirSync(workspaceRoot);
+            runGit(workspaceRoot, ['-c', 'init.templateDir=', 'init', '--initial-branch', manifest.workspace.branch]);
+        }
+        else
+            runGit(projectRoot, ['clone', '--no-checkout', '--branch', manifest.workspace.branch, bundle, workspaceRoot]);
+    }
+    else {
+        runGit(projectRoot, ["fetch", bundle, `+refs/heads/${manifest.workspace.branch}:refs/heads/${manifest.workspace.branch}`]);
+        if (git(projectRoot, ["rev-parse", `refs/heads/${manifest.workspace.branch}`]) !== manifest.workspace.base_ref)
+            throw new AppError("snapshot_workspace_restore_failed", "Snapshot Git bundle did not restore the frozen feature base", 1, { branch: manifest.workspace.branch, expected_base: manifest.workspace.base_ref });
+        runGit(projectRoot, ["worktree", "add", workspaceRoot, manifest.workspace.branch]);
+    }
+    if (git(workspaceRoot, ["rev-parse", "HEAD"]) !== manifest.workspace.base_ref)
+        throw new AppError("snapshot_workspace_restore_failed", "Snapshot Git bundle did not restore the frozen workspace base", 1, { branch: manifest.workspace.branch, expected_base: manifest.workspace.base_ref });
     replaceProjectTree(workspaceRoot, source);
     restoreIndex(snapshot, "workspace", manifest.workspace, workspaceRoot);
     return fs.realpathSync(workspaceRoot);
@@ -836,7 +863,7 @@ function restoreProjectGit(snapshot, source, projectRoot) {
     restoreIndex(snapshot, "project", source, projectRoot);
 }
 const mergeStateFiles = ["MERGE_HEAD", "MERGE_MSG", "MERGE_MODE", "ORIG_HEAD", "AUTO_MERGE"];
-function indexEntries(root) {
+function indexEntries(root, includeExclude = true) {
     const entries = Buffer.from(gitBytes(root, ["ls-files", "--stage", "-z"])
         .toString("utf8").split("\0").filter(entry => entry && localEnvironmentAllowed(entry.slice(entry.indexOf("\t") + 1)))
         .map(entry => `${entry}\0`).join(""));
@@ -849,7 +876,22 @@ function indexEntries(root) {
         if (fs.existsSync(resolved))
             merge[name] = fs.readFileSync(resolved).toString("base64");
     }
-    return Buffer.from(JSON.stringify({ entries: entries.toString("base64"), merge }));
+    if (!includeExclude)
+        return Buffer.from(JSON.stringify({ entries: entries.toString("base64"), merge }));
+    const excludePath = git(root, ["rev-parse", "--git-path", "info/exclude"]);
+    if (!excludePath)
+        throw new AppError("snapshot_index_invalid", "Could not locate Git local excludes", 1);
+    const excludeFile = path.resolve(root, excludePath);
+    let exclude = null;
+    if (fs.existsSync(excludeFile)) {
+        const stat = fs.lstatSync(excludeFile);
+        if (!stat.isFile() || stat.size > 1024 * 1024)
+            throw new AppError("snapshot_index_invalid", "Git local excludes must be a bounded regular file", 1);
+        exclude = fs.readFileSync(excludeFile).toString("base64");
+    }
+    // Local excludes affect review-visible inputs, but are not part of a Git
+    // bundle/index. Keep them in the existing hashed, non-executable Git payload.
+    return Buffer.from(JSON.stringify({ entries: entries.toString("base64"), merge, exclude }));
 }
 function snapshotIndex(root, output, name) {
     const bytes = indexEntries(root);
@@ -900,6 +942,8 @@ function restoreIndex(snapshot, name, metadata, root) {
         if (!metadata.index_objects_sha256 || fileHash(pack) !== metadata.index_objects_sha256)
             throw new AppError("snapshot_checksum_mismatch", "Snapshot Git index object checksum does not match", 1);
         const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (value.exclude !== undefined && value.exclude !== null && (typeof value.exclude !== "string" || Buffer.byteLength(value.exclude) > 1400000))
+            throw new AppError("snapshot_index_invalid", "Snapshot Git local excludes are invalid", 1);
         gitBytes(root, ["unpack-objects"], fs.readFileSync(pack));
         runGit(root, ["read-tree", "--empty"]);
         gitBytes(root, ["update-index", "-z", "--index-info"], Buffer.from(value.entries, "base64"));
@@ -912,18 +956,36 @@ function restoreIndex(snapshot, name, metadata, root) {
             else
                 fs.rmSync(path.resolve(root, target), { force: true });
         }
+        if (value.exclude !== undefined) {
+            const target = git(root, ["rev-parse", "--git-path", "info/exclude"]);
+            if (!target)
+                throw new AppError("snapshot_index_invalid", "Could not locate restored Git local excludes", 1);
+            const destination = path.resolve(root, target);
+            if (fs.existsSync(destination) && !fs.lstatSync(destination).isFile())
+                throw new AppError("snapshot_index_invalid", "Restored Git local excludes are not a regular file", 1);
+            if (value.exclude === null)
+                fs.rmSync(destination, { force: true });
+            else {
+                fs.mkdirSync(path.dirname(destination), { recursive: true });
+                fs.writeFileSync(destination, Buffer.from(value.exclude, "base64"));
+            }
+        }
         return;
     }
     if (fs.statSync(file).size)
         runGit(root, ["apply", "--cached", "--binary", file]);
 }
+function capturedIndexEntries(snapshot, name, root) {
+    const captured = JSON.parse(fs.readFileSync(path.join(snapshot, `${name}.index.patch`), "utf8"));
+    return indexEntries(root, Object.hasOwn(captured, "exclude"));
+}
 export function verifyRecoverySnapshot(snapshot, input, checkWorkingState = true) {
     const manifest = readManifest(snapshot);
     if (manifest.purpose !== "recovery" || manifest.recovery_id !== input.recoveryId || manifest.run_id !== input.runId)
         throw new AppError("recovery_capture_invalid", "Snapshot does not identify this recovery", 1);
     const entries = [
         { name: "project", root: input.projectRoot, hash: manifest.project_sha256, git: manifest.project_git, head: manifest.project_git.head },
-        ...(manifest.workspace.kind === "git_worktree" ? [{ name: "workspace", root: input.workspaceRoot, hash: manifest.workspace.sha256, git: manifest.workspace, head: manifest.workspace.base_ref }] : [])
+        ...(manifest.workspace.kind !== "project" ? [{ name: "workspace", root: input.workspaceRoot, hash: manifest.workspace.sha256, git: manifest.workspace, head: manifest.workspace.base_ref }] : [])
     ];
     verifySnapshotPayload(snapshot, manifest);
     for (const entry of entries) {
@@ -933,7 +995,7 @@ export function verifyRecoverySnapshot(snapshot, input, checkWorkingState = true
             throw new AppError("recovery_workspace_drift", "Executable file modes changed after recovery capture", 1, { payload: entry.name });
         if (checkWorkingState && (treeHash(entry.root, allowed) !== entry.hash || git(entry.root, ["rev-parse", "--verify", "HEAD"]) !== entry.head
             || entry.head === null && git(entry.root, ["for-each-ref", "--format=%(refname)"]) !== ""
-            || git(entry.root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) !== entry.git.branch || (entry.git.index_sha256 && crypto.createHash("sha256").update(entry.git.index_format === "entries@1" ? indexEntries(entry.root) : indexPatch(entry.root)).digest("hex") !== entry.git.index_sha256)))
+            || git(entry.root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) !== entry.git.branch || (entry.git.index_sha256 && crypto.createHash("sha256").update(entry.git.index_format === "entries@1" ? capturedIndexEntries(snapshot, entry.name, entry.root) : indexPatch(entry.root)).digest("hex") !== entry.git.index_sha256)))
             throw new AppError("recovery_workspace_drift", "Working files or Git state changed after recovery capture", 1, { payload: entry.name });
     }
 }
@@ -953,7 +1015,7 @@ 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 }] : [])];
+    const payloads = [{ name: "project", hash: manifest.project_sha256, git: manifest.project_git }, ...(manifest.workspace.kind !== "project" ? [{ name: "workspace", hash: manifest.workspace.sha256, git: manifest.workspace }] : [])];
     for (const payload of payloads)
         verifyGitSnapshotPayload(snapshot, payload);
     if (manifest.schema_id === "dd-flow/eval-run-snapshot@6") {
@@ -1422,7 +1484,7 @@ function treeModesHash(root, filtered = false) {
 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"] : [])]) {
+    for (const name of ["project", "runtime", ...(manifest.workspace.kind !== "project" ? ["workspace"] : [])]) {
         if (treeModesHash(path.join(snapshot, name)) !== manifest.payload_modes[name])
             throw new AppError("snapshot_checksum_mismatch", "Snapshot executable modes do not match manifest", 1, { payload: name });
     }
@@ -1454,7 +1516,7 @@ function readManifest(snapshot) {
     if (!fs.existsSync(file))
         throw new AppError("snapshot_missing", "Snapshot manifest is missing", 1, { snapshot });
     const value = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (!["dd-flow/eval-run-snapshot@5", "dd-flow/eval-run-snapshot@6"].includes(String(value.schema_id)) || !value.run_id || !value.project_root || !value.dd_flow_home || typeof value.purpose !== "string" || !["stage_entry", "candidate", "incomplete", "recovery"].includes(value.purpose) || (value.purpose === "stage_entry" && !value.stage_entry) || (value.purpose !== "stage_entry" && value.stage_entry !== null) || !value.runtime_sha256 || !value.project_sha256 || !value.project_git || !value.workspace)
+    if (!["dd-flow/eval-run-snapshot@5", "dd-flow/eval-run-snapshot@6", "dd-flow/eval-run-snapshot@7"].includes(String(value.schema_id)) || !value.run_id || !value.project_root || !value.dd_flow_home || typeof value.purpose !== "string" || !["stage_entry", "candidate", "incomplete", "recovery"].includes(value.purpose) || (value.purpose === "stage_entry" && !value.stage_entry) || (value.purpose !== "stage_entry" && value.stage_entry !== null) || !value.runtime_sha256 || !value.project_sha256 || !value.project_git || !value.workspace)
         throw new AppError("snapshot_invalid", "Snapshot manifest is invalid", 1, { snapshot });
     if (value.runtime_payload_policy !== undefined && (value.runtime_payload_policy !== "flow-evidence@1" || value.purpose === "recovery"))
         throw new AppError("snapshot_invalid", "Snapshot runtime payload policy is invalid for its purpose", 1, { snapshot });
@@ -1469,8 +1531,13 @@ function readManifest(snapshot) {
             || spawnSync("git", ["check-ref-format", "--branch", value.project_git.branch], { encoding: "utf8" }).status !== 0
         : value.project_git.state !== undefined || !value.project_git.head || !value.project_git.bundle_sha256))
         throw new AppError("snapshot_invalid", "Snapshot project Git metadata is incomplete", 1, { snapshot });
-    if (value.workspace.kind === "git_worktree" && (!value.workspace.branch || !value.workspace.base_ref || !value.workspace.bundle_sha256))
-        throw new AppError("snapshot_invalid", "Snapshot worktree manifest is incomplete", 1, { snapshot });
+    if (!['project', 'git_worktree', 'git_repository'].includes(value.workspace.kind)
+        || (value.schema_id === 'dd-flow/eval-run-snapshot@7') !== (value.workspace.kind === 'git_repository')
+        || value.workspace.kind !== 'project' && (!value.workspace.branch || (value.workspace.state === 'unborn'
+            ? value.workspace.kind !== 'git_repository' || value.workspace.base_ref !== null || value.workspace.bundle_sha256 !== null
+                || value.workspace.index_format !== 'entries@1' || !value.workspace.index_sha256 || !value.workspace.index_objects_sha256
+            : value.workspace.state !== undefined || !value.workspace.base_ref || !value.workspace.bundle_sha256)))
+        throw new AppError("snapshot_invalid", "Snapshot workspace manifest is incomplete or incompatible", 1, { snapshot });
     return value;
 }
 function readBootstrapManifest(snapshot) {
@@ -1479,7 +1546,7 @@ function readBootstrapManifest(snapshot) {
         throw new AppError("snapshot_missing", "Bootstrap snapshot manifest is missing", 1, { snapshot });
     const value = JSON.parse(fs.readFileSync(file, "utf8"));
     const validBoundary = value.schema_id === "dd-eval/bootstrap-snapshot@1" ? value.stage === "specify" && value.flow === undefined
-        : value.schema_id === "dd-eval/bootstrap-snapshot@2" && value.flow?.id === "mb-init" && value.stage === "preflight"
+        : value.schema_id === "dd-eval/bootstrap-snapshot@2" && (value.flow?.id === "mb-init" || value.flow?.id === "mb-upgrade" || isDiagnosticFlow(value.flow?.id)) && value.stage === "preflight"
             && Object.keys(value.flow).sort().join() === "descriptor_sha256,id,source_sha256"
             && /^[a-f0-9]{64}$/.test(value.flow.source_sha256) && /^[a-f0-9]{64}$/.test(value.flow.descriptor_sha256);
     if (!validBoundary || !value.project_root || !value.project_sha256 || !value.project_git?.branch || !value.project_git.head || !value.project_git.bundle_sha256)

package/dist/services/execution-bundles.js

@@ -9,6 +9,7 @@ import { FrozenGenericExecution } from "./generic-execution.js";
 import { hybridDigest, validateHybridContract, validateHybridShape } from "./hybrid-contracts.js";
 import { readBoundedReleaseFile } from "./release-source.js";
 import { acquireInstallationLock } from "./installation-lock.js";
+import { projectPacketLocators } from "./stage-context.js";
 const hash = (bytes) => crypto.createHash("sha256").update(bytes).digest("hex");
 const limit = 1024 * 1024;
 function refuse(reason, issues) {
@@ -54,7 +55,8 @@ export class RetainedExecutionBundle {
     #blobs;
     #admission;
     #engine;
-    constructor(bytes, manifest, blobs, admission, descriptor, execution) {
+    #engineRelocation;
+    constructor(bytes, manifest, blobs, admission, descriptor, execution, engineRelocation) {
         frozen(manifest);
         this.manifest = manifest;
         this.sha256 = hash(bytes);
@@ -63,9 +65,10 @@ export class RetainedExecutionBundle {
         this.#admission = admission;
         this.descriptor = descriptor;
         this.execution = execution;
+        this.#engineRelocation = engineRelocation && structuredClone(engineRelocation);
         Object.freeze(this);
     }
-    static admit(input, expectedSha256, sourceBlobs, selected) {
+    static admit(input, expectedSha256, sourceBlobs, selected, engineRelocation) {
         if (input.byteLength > limit || !/^[a-f0-9]{64}$/.test(expectedSha256))
             refuse("invalid_bundle_identity");
         const bytes = Buffer.from(input);
@@ -113,12 +116,12 @@ export class RetainedExecutionBundle {
         const snapshot = { schema_id: "dd-flow/frozen-execution@1", scope: admission.executionScope,
             settings: json(blobs.get(manifest.execution_settings.path)), profiles: profiles.profiles };
         const execution = FrozenGenericExecution.restore(snapshot, hybridDigest(snapshot), descriptor, admission.executionScope, admission.receipts);
-        const admitted = new RetainedExecutionBundle(bytes, manifest, blobs, admission, descriptor, execution);
+        const admitted = new RetainedExecutionBundle(bytes, manifest, blobs, admission, descriptor, execution, engineRelocation);
         admitted.engine();
         return admitted;
     }
     /** Read only the retained inventory. Mutable canon/profile sources are never consulted. */
-    static read(root, expectedSha256, admission) {
+    static read(root, expectedSha256, admission, engineRelocation) {
         try {
             directory(root);
             const bytes = readBoundedReleaseFile(path.join(root, "manifest.json"), limit);
@@ -130,7 +133,7 @@ export class RetainedExecutionBundle {
             const manifest = value, blobs = new Map();
             for (const ref of manifest.inventory)
                 blobs.set(ref.path, readBoundedReleaseFile(fileIn(root, ref.path), limit));
-            return RetainedExecutionBundle.admit(bytes, expectedSha256, blobs, admission);
+            return RetainedExecutionBundle.admit(bytes, expectedSha256, blobs, admission, engineRelocation);
         }
         catch (error) {
             if (error instanceof AppError && ["execution_bundle_invalid", "frozen_engine_invalid"].includes(error.code))
@@ -153,8 +156,17 @@ export class RetainedExecutionBundle {
     }
     #admitEngine() {
         const binding = json(this.blob(this.manifest.engine_binding.path));
-        const engine = AdmittedFrozenEngine.admit(binding, this.manifest.engine_manifest.sha256);
-        if (!engine.manifestBytes().equals(this.blob(this.manifest.engine_manifest.path)))
+        const retainedManifest = this.blob(this.manifest.engine_manifest.path), relocation = this.#engineRelocation;
+        if (relocation) {
+            const root = JSON.parse(projectPacketLocators(JSON.stringify({ root: binding.engine.snapshot_root }), relocation.relocations)).root;
+            if (!relocation.relocations.length || root === binding.engine.snapshot_root || root !== relocation.binding.engine.snapshot_root
+                || relocation.binding.run_id !== this.manifest.run_id)
+                refuse("foreign_engine_relocation");
+        }
+        const engine = relocation
+            ? AdmittedFrozenEngine.admitRelocation(binding, retainedManifest, this.manifest.engine_manifest.sha256, relocation.binding)
+            : AdmittedFrozenEngine.admit(binding, this.manifest.engine_manifest.sha256);
+        if (!relocation && !engine.manifestBytes().equals(retainedManifest))
             refuse("engine_manifest_bytes_changed");
         const manifest = engine.manifest(), contracts = new Set(Object.values(manifest.supports_contracts).flat());
         for (const id of ["dd-flow/flow-descriptor@1", "dd-flow/execution-settings@1", "dd-flow/execution-bundle@1"]) {