@deksden-com/dd-flow-cli 0.9.0-beta.137 → 0.9.0-beta.139

package/dist/services/runs.js

@@ -4,9 +4,10 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { withProjectionLock } from "../storage/projection-lock.js";
 import { reconcileRunStageReports } from "./stage-report-renderer.js";
-import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
+import { isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
 import { checksumForFlowFlagValues, isFlowFlagDowngrade, loadCanonicalFlowContract, loadProjectFlowContract, resolveFlowFlags } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
+import { nextRunId } from "./ids.js";
 import { ensureDir, canonicalPath, projectRunHome, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
@@ -22,9 +23,12 @@ import { assertSameSessionMerge, loadExecutionRoutingInput, resolveStageTransiti
 import { isLegalVnextTransition, vnextStageDirectory, vnextStages } from "../domain/stage-catalog.js";
 import { publicSessionIdentity } from "./session-identity.js";
 import { flowCommand } from "./stage-pause.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { admitBundledFlow, bundledHandlerContext } from "./stage-handlers.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { projectPacketLocators, runContextRelocations } from "./stage-context.js";
 const runSchemaId = "dd-flow/flow-run@3";
 const runtimeSchemaId = "dd-flow/flow-run@3";
-const runIdType = "RUN";
 const allowedRunFlowKinds = [
     "mb_sdlc",
     "coding",
@@ -231,7 +235,7 @@ function snapshotVnextExecutionProfile(projectRoot, ddFlowHome, routingInput, no
             merge_delivery: profile.merge_delivery,
             merge_cleanup: profile.merge_cleanup,
             stop_target: profile.stop_target,
-            code_bootstrap: profile.code_bootstrap,
+            ...(profile.code_bootstrap ? { code_bootstrap: profile.code_bootstrap } : {}),
             ...(profile.execution ? { execution: profile.execution } : {})
         }
     }, routingInput);
@@ -281,20 +285,82 @@ export function importFlowRunExecutionProfile(context, input) {
 export function rebindFlowRunWorkspace(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    assertRunMutationAllowed(context, project.id, run.id);
+    const generation = assertRunMutationAllowed(context, project.id, run.id, input.expectedGeneration);
     const workspaceRoot = resolveWorkspaceRoot(input.workspaceRoot);
     const index = authoritativeIndex(run);
+    const receipt = input.routeReceipt ? { ...input.routeReceipt, policy: { ...input.routeReceipt.policy,
+            worktree_path: input.routeReceipt.policy.worktree_path ? resolveWorkspaceRoot(input.routeReceipt.policy.worktree_path) : null } } : undefined;
+    if (index.execution_bundle && !["vnext_specify", "vnext_protocolize"].includes(run.flow_kind)) {
+        if (workspaceRoot === run.workspace_root)
+            return { ok: true, changed: false };
+        throw new AppError("workspace_route_invalid", "Only SDLC may provision a different RUN workspace", 1, { effect: "no_effect" });
+    }
+    if (workspaceRoot === run.workspace_root) {
+        if (receipt && index.workspace_route && hybridDigest(retainedWorkspaceRoute(context, run).receipt) !== hybridDigest(receipt)) {
+            throw new AppError("workspace_route_conflict", "Committed workspace route differs from the repeated request", 1, { effect: "no_effect" });
+        }
+        publishRunProjections(context, project.id, run.id);
+        return { ok: true, changed: false, workspace_root: workspaceRoot };
+    }
+    if (index.workspace_route)
+        throw new AppError("workspace_route_conflict", "RUN already has a committed workspace route", 1, { effect: "no_effect" });
+    if (input.expectedRevision !== undefined && (index.runtime_revision ?? 0) !== input.expectedRevision)
+        throw new AppError("run_revision_changed", "RUN changed while its workspace was provisioned", 1, { effect: "no_effect", expected_revision: input.expectedRevision, actual_revision: index.runtime_revision ?? 0 });
+    if (index.execution_bundle && !receipt)
+        throw new AppError("workspace_route_missing", "Bundled SDLC rebind requires its prepared route receipt", 1, { effect: "no_effect" });
+    if (receipt && (run.workspace_root !== project.root || receipt.schema_id !== "dd-flow/vnext-workspace-route@1" || receipt.policy.route !== "feature_worktree"
+        || !receipt.policy.provisioned || receipt.policy.worktree_path !== workspaceRoot || !receipt.created || !receipt.bootstrap)) {
+        throw new AppError("workspace_route_invalid", "Prepared workspace route does not match this RUN", 1, { effect: "no_effect" });
+    }
     const now = context.now();
     const facts = gitFacts(workspaceRoot);
+    if (receipt && (facts.branch !== receipt.policy.feature_branch || !receipt.policy.base_ref || !facts.head
+        || spawnSync("git", ["-C", workspaceRoot, "merge-base", "--is-ancestor", receipt.policy.base_ref, facts.head]).status !== 0)) {
+        throw new AppError("workspace_route_invalid", "Prepared checkout differs from the feature branch/base receipt", 1, { effect: "no_effect", run_id: run.id });
+    }
     index.workspace = { ...index.workspace, workspace_path: workspaceRoot, branch: facts.branch ?? "unknown", base: facts.head ?? "unknown", manager: "official-worktrunk" };
     index.execution = { ...index.execution, project_root: project.root, workspace_root: workspaceRoot, git: facts };
     index.updated_at = now;
-    context.db.run("UPDATE runs SET workspace_root = ? WHERE project_id = ? AND id = ?", [workspaceRoot, project.id, run.id]);
-    persistRunState(context, project, { ...run, workspace_root: workspaceRoot }, index);
-    appendAudit(context, { projectId: project.id, eventType: "flow_run.workspace_rebound", payload: { run_id: run.id, workspace_root: workspaceRoot, reason: input.reason } });
-    appendRunTimeline(context, project.id, run.id, { at: now, type: "workspace_rebound", run_id: run.id, workspace_root: workspaceRoot, reason: input.reason, git: facts });
+    const route = receipt ? { schema_id: "dd-flow/run-workspace-route@1", run_id: run.id, project_id: project.id, project_root: project.root,
+        generation, previous_workspace: run.workspace_root, workspace_root: workspaceRoot, revision: (index.runtime_revision ?? 0) + 1,
+        git: facts, receipt, receipt_sha256: hybridDigest(receipt) } : undefined;
+    if (route)
+        index.workspace_route = { revision: route.revision, sha256: hybridDigest(route) };
+    context.db.writeTransaction(() => {
+        assertRunMutationAllowed(context, project.id, run.id, generation);
+        const latest = resolveRun(context, project.id, run.id);
+        if (latest.workspace_root !== run.workspace_root)
+            throw new AppError("workspace_route_changed", "RUN route changed during preparation", 1, { effect: "no_effect" });
+        context.db.run("UPDATE runs SET workspace_root = ? WHERE project_id = ? AND id = ?", [workspaceRoot, project.id, run.id]);
+        persistRunState(context, project, { ...run, workspace_root: workspaceRoot }, index);
+        appendAudit(context, { projectId: project.id, eventType: "flow_run.workspace_rebound", payload: { run_id: run.id, workspace_root: workspaceRoot, reason: input.reason, ...(route ? { route } : {}) } });
+        appendRunTimeline(context, project.id, run.id, { at: now, type: "workspace_rebound", run_id: run.id, workspace_root: workspaceRoot, reason: input.reason, git: facts });
+    }, "runs.rebindWorkspace");
     return { ok: true, run_id: run.id, project_root: project.root, workspace_root: workspaceRoot, git: facts };
 }
+function retainedWorkspaceRoute(context, run) {
+    const index = authoritativeIndex(run), binding = index.workspace_route;
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.workspace_rebound' AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.route.revision') = ?", [run.project_id, run.id, binding?.revision ?? -1]);
+    const original = rows.length === 1 ? JSON.parse(rows[0].payload_json).route : undefined;
+    if (!binding || !original || original.schema_id !== "dd-flow/run-workspace-route@1" || hybridDigest(original) !== binding.sha256 || hybridDigest(original.receipt) !== original.receipt_sha256) {
+        throw new AppError("workspace_route_invalid", "RUN committed workspace route evidence changed", 1, { effect: "no_effect", run_id: run.id });
+    }
+    // Relocation receipts are admitted by snapshot import; never rewrite bundle
+    // or source route authority merely because a physical checkout moved.
+    const route = JSON.parse(projectPacketLocators(JSON.stringify(original), runContextRelocations(context, run.project_id, run.id)));
+    if (route.receipt_sha256 !== original.receipt_sha256
+        || route.run_id !== run.id || route.project_id !== run.project_id || route.project_root !== run.project_root || route.workspace_root !== run.workspace_root
+        || index.workspace.workspace_path !== run.workspace_root || index.execution?.workspace_root !== run.workspace_root || index.execution?.project_root !== run.project_root
+        || index.workspace.manager !== "official-worktrunk" || index.workspace.branch !== route.receipt.policy.feature_branch
+        // execution.git is the latest observation (stage completion/refresh updates
+        // it). The immutable review base is workspace.base, not that moving HEAD.
+        || index.workspace.base !== route.git.head
+        || !Number.isInteger(route.generation) || route.generation < 0
+        || route.receipt.policy.worktree_path !== run.workspace_root) {
+        throw new AppError("workspace_route_invalid", "RUN has no exact coherent committed workspace route", 1, { effect: "no_effect", run_id: run.id });
+    }
+    return route;
+}
 function loadUpgradeFlowContract(context, projectRoot) {
     const canon = resolveCanonRoot(context, context.env.DD_MEMORYBANK ? { explicitRoot: context.env.DD_MEMORYBANK } : {});
     if (!canon.ok || !canon.canon) {
@@ -306,17 +372,19 @@ function loadUpgradeFlowContract(context, projectRoot) {
     }
     return loadCanonicalFlowContract(canon.canon.flow_root);
 }
-export function getFlowRunStatus(context, input) {
+export function getFlowRunStatus(context, input, preparedBundle) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
+    if (preparedBundle)
+        assertPreparedRunBundleSqlAuthority(context, { projectId: project.id, runId: run.id }, preparedBundle);
     const index = authoritativeIndex(run);
     const runtime = readRuntimeSnapshot(run.runtime_path);
-    return { ok: true, run: flowRunSummary(run), index, continuation: runContinuation(context, run, index), ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, run, index) };
+    return { ok: true, run: flowRunSummary(run), index, continuation: runContinuation(context, run, index, preparedBundle), ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, run, index) };
 }
 /** A read-only projection of the next legal lifecycle action.
  * It is derived from the persisted RUN/Work facts so controllers never infer a
  * transition from a model's prose or a hard-coded stage array. */
-function runContinuation(context, run, index) {
+function runContinuation(context, run, index, preparedBundle) {
     if (["done", "failed", "cancelled"].includes(run.status))
         return { kind: "terminal", stage: null, attempt: null, work_id: null, reason: run.status, command: null };
     const control = runControlDirective(context, run.project_id, run.id);
@@ -332,6 +400,15 @@ function runContinuation(context, run, index) {
         return { kind: "paused", stage: index.current_stage ?? null, attempt: null, work_id: null, reason: run.status, command: null };
     if (run.status === "blocked")
         return { kind: "blocked", stage: index.current_stage ?? null, attempt: null, work_id: null, reason: run.status, command: null };
+    if (index.execution_bundle) {
+        const bundle = preparedBundle ?? readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: run.id });
+        const next = bundledNextStage(bundle.descriptor, index);
+        if (!next)
+            return { kind: "terminal", stage: null, attempt: null, work_id: null, reason: "flow_complete", command: null };
+        const command = bundle.engine().command(context.ddFlowHome, ["stage", "start", run.id, "--stage", next, "--project-root", run.project_root, "--json"]);
+        return { kind: "start_stage", stage: next, attempt: null, work_id: null, reason: "legal_successor", command,
+            execution: { status: "resolved", ...bundle.execution.stage(next) } };
+    }
     if (run.flow_kind === "vnext_specify" || run.flow_kind === "vnext_protocolize") {
         const completed = index.stage_runs.filter((stage) => stage.status === "done" || stage.status === "skipped").sort((left, right) => right.order - left.order)[0];
         const next = completed ? vnextStages.find((stage) => stage.id === completed.stage)?.next.find((candidate) => candidate !== "plan-review" || index.settings?.plan_review?.mode !== "off") : "specify";
@@ -587,14 +664,18 @@ export function prepareFlowRunStageAttachment(context, input, archive = false) {
     const index = authoritativeIndex(run);
     const status = parseStageStatus(input.status);
     const existing = index.stage_runs.find((item) => item.stage === stage);
-    assertVnextStageStart(run, index, stage, status, existing);
+    const bundle = index.execution_bundle ? readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: run.id }) : null;
+    if (bundle)
+        assertBundledStageStart(bundle.descriptor, index, stage, dir, status, existing);
+    else
+        assertVnextStageStart(run, index, stage, status, existing);
     if (archive) {
         const runRoot = runArtifactRoot(run);
         if (fs.existsSync(path.join(runRoot, `.archive-${dir}.json`)) || status === "running" && existing) {
             archiveExistingStageAttempt(context, project.id, run.id, runRoot, dir);
         }
     }
-    return { project, run, index, stage, dir, status, existing, generation, attempt: status === "running" ? nextAttempt(existing) : existing?.attempt ?? "try-001", git: status === "running" ? gitFacts(run.workspace_root) : undefined };
+    return { project, run, index, stage, dir, status, existing, generation, bundle, attempt: status === "running" ? nextAttempt(existing) : existing?.attempt ?? "try-001", git: status === "running" ? gitFacts(run.workspace_root) : undefined };
 }
 export function attachFlowRunStage(context, input, prepared = prepareFlowRunStageAttachment(context, input, true)) {
     // Filesystem archive and Git inspection are preparation, never writer work.
@@ -607,7 +688,13 @@ export function attachFlowRunStage(context, input, prepared = prepareFlowRunStag
         if ((index.runtime_revision ?? 0) !== (prepared.index.runtime_revision ?? 0) || existing?.attempt !== prepared.existing?.attempt) {
             throw new AppError("stage_revision_changed", "Stage changed during start preparation", 1, { run_id: run.id, stage });
         }
-        assertVnextStageStart(latest, index, stage, status, existing);
+        if (prepared.bundle) {
+            if (index.execution_bundle?.manifest_sha256 !== prepared.bundle.sha256)
+                throw new AppError("run_bundle_anchor_invalid", "RUN bundle changed during stage preparation", 1);
+            assertBundledStageStart(prepared.bundle.descriptor, index, stage, dir, status, existing);
+        }
+        else
+            assertVnextStageStart(latest, index, stage, status, existing);
         const now = context.now();
         const stageRun = {
             ...(existing ?? { order: index.stage_runs.length + 1 }),
@@ -652,7 +739,7 @@ export function attachFlowRunStage(context, input, prepared = prepareFlowRunStag
 export function withStageSettlement(context, operation) {
     return context.db.writeTransaction(operation, "stage.settle");
 }
-export function prepareFlowRunStageCompletion(context, input) {
+export function prepareFlowRunStageCompletion(context, input, admittedBundle) {
     for (const [name, value] of Object.entries({ stageReport: input.stageReport, data: input.data, dataSchemaId: input.dataSchemaId, report: input.report })) {
         if (value !== undefined)
             requiredPlain(value, name);
@@ -676,11 +763,37 @@ export function prepareFlowRunStageCompletion(context, input) {
     if (!existing) {
         throw new AppError("not_found", `Run stage is not attached: ${stage}`, 1, { run_id: run.id, stage });
     }
+    // Bound completion must admit the same immutable descriptor/engine authority
+    // as stage entry. Keep filesystem admission outside the SQLite writer.
+    const bundle = admittedBundle === undefined
+        ? readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: run.id }) : admittedBundle;
+    if (bundle && !index.execution_bundle)
+        throw new AppError("run_bundle_anchor_invalid", "RUN bundle anchor disappeared after finish admission", 1);
+    if (bundle)
+        assertCompletionBundleAuthority(context, run, index);
+    if (index.execution_bundle && (!bundle || bundle.sha256 !== index.execution_bundle.manifest_sha256
+        || bundle.manifest.descriptor.sha256 !== index.execution_bundle.descriptor_sha256
+        || hybridDigest(bundleAuthority(bundle.admission())) !== index.execution_bundle.admission_sha256)) {
+        throw new AppError("run_bundle_anchor_invalid", "Prepared finish bundle does not match authoritative RUN admission", 1);
+    }
+    if (bundle) {
+        const declared = bundle.descriptor.stage(stage);
+        if (declared.directory !== existing.dir || index.current_stage !== stage) {
+            throw new AppError("flow_stage_completion_invalid", "Completion does not belong to the active descriptor stage", 2, { phase: "prepare", effect: "no_effect", run_id: run.id, stage });
+        }
+    }
     const dataPath = input.data ? path.join(runArtifactRoot(run), existing.dir, input.data) : null;
     const dataSha256 = input.dataSha256 ?? (dataPath && fs.existsSync(dataPath) ? crypto.createHash("sha256").update(fs.readFileSync(dataPath)).digest("hex") : null);
     if (dataSha256 && !/^[a-f0-9]{64}$/.test(dataSha256))
         throw new AppError("validation", "Stage data SHA-256 is invalid", 2);
-    return { project, run, index, stage, status, existing, dataSha256, git: input.git ?? gitFacts(run.workspace_root), generation: ["done", "failed", "skipped"].includes(status) ? assertStageSettlementAllowed(context, project.id, run.id, stage) : assertRunMutationAllowed(context, project.id, run.id) };
+    return { project, run, index, stage, status, existing, bundle, dataSha256, git: input.git ?? gitFacts(run.workspace_root), generation: ["done", "failed", "skipped"].includes(status) ? assertStageSettlementAllowed(context, project.id, run.id, stage) : assertRunMutationAllowed(context, project.id, run.id) };
+}
+/** Raw historical control is not a finish-sealing bypass for a descriptor-bound RUN. */
+export function prepareRawFlowRunStageCompletion(context, input) {
+    const prepared = prepareFlowRunStageCompletion(context, input);
+    if (prepared.bundle)
+        throw new AppError("stage_finish_required", "Descriptor-bound stages must settle through their registered stage finish handler", 2, { phase: "prepare", effect: "no_effect", run_id: prepared.run.id, stage: prepared.stage });
+    return prepared;
 }
 function stageUsageProjection(context, run, stage, startedAt) {
     if (!startedAt)
@@ -705,6 +818,14 @@ export function completeFlowRunStage(context, input, prepared = prepareFlowRunSt
         if (!existing || existing.attempt !== prepared.existing.attempt || index.runtime_revision !== prepared.index.runtime_revision) {
             throw new AppError("stage_revision_changed", "Stage attempt changed during finish preparation", 1, { run_id: run.id, stage, expected_attempt: prepared.existing.attempt, actual_attempt: existing?.attempt ?? null });
         }
+        if (hybridDigest(index.execution_bundle ?? null) !== hybridDigest(prepared.index.execution_bundle ?? null)) {
+            throw new AppError("run_bundle_anchor_invalid", "RUN bundle authority changed during finish preparation", 1);
+        }
+        if (prepared.bundle && (index.current_stage !== stage || existing.dir !== prepared.bundle.descriptor.stage(stage).directory)) {
+            throw new AppError("flow_stage_completion_invalid", "Active descriptor stage changed during finish preparation", 1);
+        }
+        if (prepared.bundle)
+            assertCompletionBundleAuthority(context, latest, index);
         const now = context.now();
         const stageRun = {
             ...existing,
@@ -755,6 +876,42 @@ export function completeFlowRunStage(context, input, prepared = prepareFlowRunSt
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), stage_run: completed.stageRun, index: completed.index, flow_guidance: guidanceForRun(context, updatedRun, completed.index) };
 }
+/** Writer-safe readback of independently retained SQL authority; no filesystem admission. */
+function assertCompletionBundleAuthority(context, run, index) {
+    const anchor = index.execution_bundle;
+    if (!anchor)
+        throw new AppError("run_bundle_anchor_invalid", "RUN bundle anchor disappeared during finish", 1);
+    assertRunBundleSqlAuthority(context, { projectId: run.project_id, runId: run.id }, anchor);
+}
+/** Metadata-only fencing shared by lifecycle ownership and the settlement writer.
+ * False means genuine historical authority, never a lost/orphaned bundle anchor.
+ * Physical descriptor/engine admission remains an independent outside-writer check.
+ */
+export function assertRunBundleSqlAuthority(context, scope, anchor) {
+    const hasAuthority = context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'run_bundle_authorities'");
+    const row = hasAuthority ? context.db.get("SELECT manifest_sha256, admission_json FROM run_bundle_authorities WHERE project_id = ? AND run_id = ?", [scope.projectId, scope.runId]) : undefined;
+    if (!anchor) {
+        if (row)
+            throw new AppError("run_bundle_anchor_invalid", "Retained RUN authority exists without its execution anchor", 1);
+        return false;
+    }
+    if (anchor.schema_id !== "dd-flow/run-execution-bundle@1" || typeof anchor.flow_id !== "string"
+        || [anchor.manifest_sha256, anchor.descriptor_sha256, anchor.admission_sha256].some(hash => typeof hash !== "string" || !/^[a-f0-9]{64}$/.test(hash)))
+        throw new AppError("run_bundle_anchor_invalid", "RUN bundle anchor is invalid", 1);
+    if (!row || row.manifest_sha256 !== anchor.manifest_sha256)
+        throw new AppError("run_bundle_authority_missing", "RUN bundle admission authority disappeared during finish", 1);
+    let valid = false;
+    try {
+        if (Buffer.byteLength(row.admission_json, "utf8") <= 1024 * 1024) {
+            const retained = JSON.parse(row.admission_json);
+            valid = retained.runId === scope.runId && hybridDigest(retained) === anchor.admission_sha256;
+        }
+    }
+    catch { /* Corrupt authority cannot be replaced by a prepared object. */ }
+    if (!valid)
+        throw new AppError("run_bundle_authority_invalid", "RUN bundle admission authority changed during finish", 1);
+    return true;
+}
 /** Pause one live stage without completing it or creating a new attempt. */
 export function pauseFlowRunStage(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -1016,6 +1173,41 @@ export function completeFlowRun(context, input) {
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), index, usage, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
+/** SQL-only terminal writer for an independently prepared descriptor handler.
+ * This closes runtime state, not semantic or Git acceptance. The caller owns
+ * the outer transaction, root settlement and the handler-specific proof fence.
+ */
+export function completeDescriptorRunState(context, scope, bundle, git) {
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    assertRunMutationAllowed(context, scope.projectId, scope.runId);
+    const run = requireRunById(context, scope.projectId, scope.runId);
+    const index = authoritativeIndex(run);
+    const terminal = index.stage_runs.at(-1);
+    if (run.status !== "running" || !terminal || terminal.status !== "done"
+        || !bundle.descriptor.descriptor.terminal_stages.includes(terminal.stage)
+        || index.stage_runs.some(stage => ["running", "paused", "waiting_for_user", "blocked", "pending"].includes(stage.status))
+        || context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND status IN ('created','running','paused') LIMIT 1", [scope.projectId, scope.runId])
+        || context.db.get("SELECT 1 FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id WHERE w.project_id=? AND w.run_id=? AND ws.status='running' LIMIT 1", [scope.projectId, scope.runId])) {
+        throw new AppError("descriptor_run_settlement_invalid", "Descriptor RUN is not ready for terminal runtime settlement", 1, { effect: "no_effect" });
+    }
+    const project = context.db.get("SELECT * FROM projects WHERE id=?", [scope.projectId]);
+    if (!project)
+        throw new AppError("not_found", "Project is not registered", 1);
+    const now = context.now();
+    index.status = "done";
+    index.verdict = "accepted";
+    index.next_action = null;
+    index.updated_at = now;
+    index.completed_at = now;
+    index.finished_at = now;
+    index.duration_ms = durationMs(index.started_at ?? run.created_at, now);
+    index.execution = { project_root: run.project_root, workspace_root: run.workspace_root, git: { ...git } };
+    persistRunState(context, project, run, index);
+    closeRunOrchestrators(context, scope.projectId, run, "done", now);
+    refreshRunSessionProjection(context, scope.projectId, scope.runId);
+    appendAudit(context, { projectId: scope.projectId, eventType: "flow_run.completed", payload: { run_id: scope.runId, status: "done", verdict: "accepted", next_action: null } });
+    appendRunTimeline(context, scope.projectId, scope.runId, { at: now, type: "run_completed", run_id: scope.runId, status: "done" });
+}
 /** Update a live RUN between stages without manufacturing terminal evidence. */
 export function advanceFlowRun(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -1479,6 +1671,17 @@ export function publishRunProjections(context, projectId, runId) {
         if (!latest)
             throw new AppError("not_found", "RUN is not registered", 1, { run_id: runId });
         const index = authoritativeIndex(latest);
+        if (index.workspace_route) {
+            const route = retainedWorkspaceRoute(context, latest);
+            const file = path.join(runArtifactRoot(latest), "02-protocolize", "workspace-route.json");
+            ensureDir(path.dirname(file));
+            try {
+                writeJsonFile(file, route.receipt);
+            }
+            catch (error) {
+                throw new AppError("workspace_route_publication_failed", "Committed route projection could not be published", 1, { effect: "committed", run_id: runId, route_sha256: index.workspace_route.sha256, cause: String(error) });
+            }
+        }
         const mutations = context.db.get("SELECT 1 FROM sqlite_schema WHERE name = 'flow_run_flag_mutations'") ? context.db.all("SELECT resulting_revision, result_json, created_at, idempotency_key FROM flow_run_flag_mutations WHERE project_id = ? AND run_id = ? ORDER BY resulting_revision DESC LIMIT 32", [projectId, runId]) : [];
         const history = mutations.reverse().map((row) => ({
             revision: row.resulting_revision,
@@ -1524,12 +1727,187 @@ function authoritativeIndex(run) {
         const state = JSON.parse(run.index_json);
         if (!state || typeof state !== "object" || Array.isArray(state) || !Array.isArray(state.stage_runs))
             throw new Error("RUN index must contain stage_runs");
-        return { ...state, schema_id: runSchemaId };
+        const derivedStage = ["vnext_specify", "vnext_protocolize"].includes(run.flow_kind)
+            ? [...state.stage_runs].sort((left, right) => right.order - left.order)[0]?.stage : undefined;
+        return { ...state, schema_id: runSchemaId, ...(state.current_stage === undefined && derivedStage ? { current_stage: derivedStage } : {}) };
     }
     catch (error) {
         throw new AppError("runtime_state_invalid", "RUN mechanical state in SQLite is missing or invalid", 1, { run_id: run.id, cause: String(error) });
     }
 }
+function assertBundleWorkspaceIdentity(context, run, bundle) {
+    const scope = currentBundleScope(context, run, bundle);
+    const route = authoritativeIndex(run).workspace_route ? retainedWorkspaceRoute(context, run) : undefined;
+    if (scope.workspace === run.workspace_root)
+        return true;
+    if (bundle.descriptor.descriptor.id !== "sdlc" || !["vnext_specify", "vnext_protocolize"].includes(run.flow_kind) || scope.workspace !== run.project_root)
+        return false;
+    if (!route)
+        return false;
+    return route.previous_workspace === scope.workspace && route.receipt.policy.route === "feature_worktree"
+        && route.receipt.policy.base_ref !== null && route.receipt.policy.feature_branch !== null;
+}
+function currentBundleScope(context, run, bundle) {
+    return JSON.parse(projectPacketLocators(JSON.stringify(bundle.execution.snapshot().scope), runContextRelocations(context, run.project_id, run.id)));
+}
+function assertBundleRunIdentity(context, run, bundle) {
+    const scope = currentBundleScope(context, run, bundle);
+    const flowId = bundle.descriptor.descriptor.id;
+    const matchesFlow = flowId === "sdlc" ? ["vnext_specify", "vnext_protocolize"].includes(run.flow_kind) : flowId === run.flow_kind;
+    if (bundle.manifest.run_id !== run.id || scope.projectRoot !== run.project_root || !assertBundleWorkspaceIdentity(context, run, bundle) || !matchesFlow) {
+        throw new AppError("run_bundle_identity_invalid", "Execution bundle belongs to another RUN or workspace", 1, { phase: "prepare", effect: "no_effect", run_id: run.id });
+    }
+    const blobs = new Map(bundle.manifest.inventory.map(ref => [ref.path, bundle.blob(ref.path)]));
+    // File-owned handler inventories can never authorize executable code.
+    admitBundledFlow(bundle.blob(bundle.manifest.descriptor.path), bundle.manifest.descriptor.sha256, blobs);
+}
+function bundleAuthority(admission) {
+    const authority = { runId: admission.runId, executionScope: structuredClone(admission.executionScope),
+        receipts: structuredClone([...(admission.receipts ?? [])].sort(([left], [right]) => left.localeCompare(right, "en"))) };
+    for (const key of ["descriptorSha256", "engineChecksum", "engineBindingSha256", "engineManifestSha256", "bundleProjectRoot", "bundleProvenance", "bootstrapIdentity"]) {
+        if (admission[key] !== undefined)
+            Object.assign(authority, { [key]: structuredClone(admission[key]) });
+    }
+    return authority;
+}
+/** Copies the same SQL authority representation used by legacy bundle binding. */
+export function runBundleAuthorityMetadata(bundle) {
+    if (!(bundle instanceof RetainedExecutionBundle))
+        throw new AppError("run_bundle_anchor_invalid", "Bundle must be admitted before RUN allocation", 1);
+    const admissionJson = JSON.stringify(bundleAuthority(bundle.admission())), admissionSha256 = hybridDigest(JSON.parse(admissionJson));
+    if (Buffer.byteLength(admissionJson) > 1024 * 1024)
+        throw new AppError("run_bundle_authority_invalid", "RUN admission exceeds its bound", 1);
+    return { admissionJson, anchor: { schema_id: "dd-flow/run-execution-bundle@1",
+            manifest_sha256: bundle.sha256, descriptor_sha256: bundle.manifest.descriptor.sha256,
+            admission_sha256: admissionSha256, flow_id: bundle.manifest.flow_id } };
+}
+/** Recheck SQL authority and compiled descriptor admission. Schema loading
+ * belongs outside SQL writers; use the explicit SQL-only fence inside them.
+ */
+export function assertPreparedRunBundleAuthority(context, scope, bundle) {
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    assertBundleRunIdentity(context, run, bundle);
+}
+/** SQL-only fence after the caller has admitted compiled handlers outside the
+ * writer. Descriptor schema loading is deliberately excluded from this fence.
+ */
+export function assertPreparedRunBundleSqlAuthority(context, scope, bundle) {
+    if (!(bundle instanceof RetainedExecutionBundle))
+        throw new AppError("run_bundle_anchor_invalid", "Prepared bundle is not admitted", 1);
+    const run = context.db.get("SELECT * FROM runs WHERE project_id = ? AND id = ?", [scope.projectId, scope.runId]);
+    if (!run)
+        throw new AppError("not_found", "Prepared bundle RUN is unavailable", 1);
+    const index = authoritativeIndex(run), anchor = index.execution_bundle;
+    if (!assertRunBundleSqlAuthority(context, scope, anchor) || !anchor || anchor.manifest_sha256 !== bundle.sha256
+        || anchor.descriptor_sha256 !== bundle.manifest.descriptor.sha256 || anchor.flow_id !== bundle.manifest.flow_id
+        || anchor.admission_sha256 !== hybridDigest(bundleAuthority(bundle.admission())))
+        throw new AppError("run_bundle_anchor_invalid", "Prepared bundle differs from authoritative RUN", 1);
+    const execution = currentBundleScope(context, run, bundle);
+    const flow = bundle.descriptor.descriptor.id;
+    if (bundle.manifest.run_id !== run.id || execution.projectRoot !== run.project_root || !assertBundleWorkspaceIdentity(context, run, bundle)
+        || !(flow === "sdlc" ? ["vnext_specify", "vnext_protocolize"].includes(run.flow_kind) : flow === run.flow_kind)) {
+        throw new AppError("run_bundle_identity_invalid", "Execution bundle belongs to another RUN or workspace", 1, { effect: "no_effect", run_id: run.id });
+    }
+    return run;
+}
+export function readFlowRunExecutionBundle(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId), anchor = authoritativeIndex(run).execution_bundle;
+    if (!anchor) {
+        // Genuine historical RUNs have neither authority nor anchor. Lost new-RUN
+        // metadata must not silently switch their execution to the legacy engine path.
+        const hasAuthority = context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'run_bundle_authorities'");
+        if (hasAuthority && context.db.get("SELECT 1 FROM run_bundle_authorities WHERE project_id = ? AND run_id = ?", [project.id, run.id])) {
+            throw new AppError("run_bundle_anchor_invalid", "Retained RUN authority exists without its execution anchor", 1);
+        }
+        return null;
+    }
+    if (anchor.schema_id !== "dd-flow/run-execution-bundle@1" || !/^[a-f0-9]{64}$/.test(anchor.manifest_sha256)
+        || !/^[a-f0-9]{64}$/.test(anchor.descriptor_sha256) || !/^[a-f0-9]{64}$/.test(anchor.admission_sha256))
+        throw new AppError("run_bundle_anchor_invalid", "RUN bundle anchor is invalid", 1);
+    const hasAuthority = context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'run_bundle_authorities'");
+    const row = hasAuthority ? context.db.get("SELECT admission_json, manifest_sha256 FROM run_bundle_authorities WHERE project_id = ? AND run_id = ?", [project.id, run.id]) : undefined;
+    if (!row || row.manifest_sha256 !== anchor.manifest_sha256)
+        throw new AppError("run_bundle_authority_missing", "RUN bundle admission authority is unavailable", 1);
+    if (Buffer.byteLength(row.admission_json) > 1024 * 1024)
+        throw new AppError("run_bundle_authority_invalid", "RUN bundle admission authority exceeds its bound", 1);
+    let retained;
+    try {
+        retained = JSON.parse(row.admission_json);
+    }
+    catch {
+        throw new AppError("run_bundle_authority_invalid", "RUN bundle admission authority is invalid", 1);
+    }
+    if (hybridDigest(retained) !== anchor.admission_sha256 || !Array.isArray(retained.receipts)
+        || input.admission && hybridDigest(bundleAuthority(input.admission)) !== anchor.admission_sha256) {
+        throw new AppError("run_bundle_authority_invalid", "RUN bundle admission authority changed", 1);
+    }
+    const admission = { ...retained, receipts: new Map(retained.receipts), descriptorContext: bundledHandlerContext(new Map()) };
+    const bundle = RetainedExecutionBundle.read(path.join(runArtifactRoot(run), "execution-bundle"), anchor.manifest_sha256, admission);
+    assertBundleRunIdentity(context, run, bundle);
+    if (bundle.manifest.descriptor.sha256 !== anchor.descriptor_sha256 || bundle.manifest.flow_id !== anchor.flow_id) {
+        throw new AppError("run_bundle_anchor_invalid", "RUN bundle descriptor identity changed", 1);
+    }
+    return bundle;
+}
+/** Freeze once before physical owners exist. Publication precedes the fenced SQLite anchor. */
+export function bindFlowRunExecutionBundle(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId), index = authoritativeIndex(run);
+    const generation = assertRunMutationAllowed(context, project.id, run.id);
+    assertBundleRunIdentity(context, run, input.bundle);
+    if (input.bundle.manifest.flow_id !== "sdlc") {
+        throw new AppError("run_bundle_start_required", "Memory RUN and its bundle authority must be allocated together through the request-bound start", 1, { phase: "prepare", effect: "no_effect", run_id: run.id });
+    }
+    if (index.execution_bundle) {
+        if (index.execution_bundle.manifest_sha256 !== input.bundle.sha256)
+            throw new AppError("run_bundle_immutable", "RUN bundle cannot be replaced", 1);
+        readFlowRunExecutionBundle(context, { ...input, admission: input.bundle.admission() });
+        publishRunProjections(context, project.id, run.id);
+        return { changed: false, sha256: input.bundle.sha256 };
+    }
+    const assertUnstarted = (state) => {
+        if (state.status !== "running" || state.stage_runs.length || state.sessions.length
+            || context.db.get("SELECT 1 FROM sessions WHERE project_id = ? AND run_id = ? LIMIT 1", [project.id, run.id])
+            || context.db.get("SELECT 1 FROM works WHERE project_id = ? AND run_id = ? LIMIT 1", [project.id, run.id])) {
+            throw new AppError("run_bundle_active", "Execution bundle must be frozen before stages, Works or Sessions exist", 1);
+        }
+    };
+    assertUnstarted(index);
+    const authority = bundleAuthority(input.bundle.admission());
+    // Hash the JSON representation actually retained, not optional undefined fields.
+    const authorityJson = JSON.stringify(authority), authoritySha256 = hybridDigest(JSON.parse(authorityJson));
+    if (Buffer.byteLength(authorityJson) > 1024 * 1024)
+        throw new AppError("run_bundle_authority_invalid", "RUN bundle admission authority exceeds its bound", 1);
+    input.bundle.materialize(runArtifactRoot(run));
+    try {
+        context.db.writeTransaction(() => {
+            assertRunMutationAllowed(context, project.id, run.id, generation);
+            const latest = resolveRun(context, project.id, run.id), state = authoritativeIndex(latest);
+            assertUnstarted(state);
+            if (state.runtime_revision !== index.runtime_revision || state.execution_bundle || latest.workspace_root !== run.workspace_root
+                || latest.project_root !== run.project_root || latest.flow_kind !== run.flow_kind || latest.run_root !== run.run_root) {
+                throw new AppError("run_revision_changed", "RUN changed during bundle publication", 1);
+            }
+            state.execution_bundle = { schema_id: "dd-flow/run-execution-bundle@1", manifest_sha256: input.bundle.sha256,
+                descriptor_sha256: input.bundle.manifest.descriptor.sha256, admission_sha256: authoritySha256, flow_id: input.bundle.manifest.flow_id };
+            context.db.execSchema(`CREATE TABLE IF NOT EXISTS run_bundle_authorities (
+        project_id TEXT NOT NULL, run_id TEXT NOT NULL, manifest_sha256 TEXT NOT NULL, admission_json TEXT NOT NULL,
+        PRIMARY KEY(project_id, run_id), FOREIGN KEY(project_id, run_id) REFERENCES runs(project_id, id)
+      )`);
+            context.db.run("INSERT INTO run_bundle_authorities (project_id, run_id, manifest_sha256, admission_json) VALUES (?, ?, ?, ?)", [project.id, run.id, input.bundle.sha256, authorityJson]);
+            state.updated_at = context.now();
+            persistRunState(context, project, latest, state);
+        }, "runs.bindExecutionBundle");
+    }
+    catch (error) {
+        throw new AppError("run_bundle_binding_incomplete", "Bundle retained but RUN binding requires recovery", 1, {
+            phase: "publication", effect: "partial", run_id: run.id, sha256: input.bundle.sha256,
+            reason: error instanceof AppError ? error.code : "binding_io_failure",
+        });
+    }
+    return { changed: true, sha256: input.bundle.sha256 };
+}
 function sanitizeTimelineValue(value, key) {
     if (key && /(secret|password|authorization|cookie|api[_-]?key|private[_-]?key|access[_-]?token|refresh[_-]?token|transcript|prompt|tool[_-]?output|document[_-]?content)/i.test(key)) {
         return "[REDACTED]";
@@ -1556,6 +1934,24 @@ function nextAttempt(existing) {
     const number = Number(existing.attempt.replace("try-", ""));
     return `try-${String(Number.isFinite(number) ? number + 1 : 1).padStart(3, "0")}`;
 }
+function bundledNextStage(flow, index) {
+    const completed = index.stage_runs.filter(stage => ["done", "skipped"].includes(stage.status)).sort((left, right) => right.order - left.order)[0];
+    if (!completed)
+        return flow.descriptor.entry_stage;
+    // Optional SDLC review routing remains a flow-specific policy, not a generic stage list.
+    const outcome = flow.descriptor.id === "sdlc" && completed.stage === "plan" && index.settings?.plan_review?.mode === "off" ? "not-applicable" : "accepted";
+    return flow.successor(completed.stage, outcome);
+}
+function assertBundledStageStart(flow, index, stage, dir, status, existing) {
+    const selected = flow.stage(stage);
+    if (selected.directory !== dir)
+        throw new AppError("flow_stage_directory_invalid", "Stage directory differs from the frozen descriptor", 1, { stage });
+    if (status !== "running")
+        return;
+    if (existing || index.stage_runs.some(candidate => !["done", "skipped"].includes(candidate.status)) || bundledNextStage(flow, index) !== stage) {
+        throw new AppError("illegal_stage_transition", "Stage does not follow the frozen descriptor or an attempt already exists", 2, { run_id: index.run_id, stage });
+    }
+}
 function assertVnextStageStart(run, index, stage, status, existing) {
     if (status !== "running" || (run.flow_kind !== "vnext_specify" && run.flow_kind !== "vnext_protocolize"))
         return;
@@ -1614,19 +2010,6 @@ function requireRunById(context, projectId, runId) {
     }
     return run;
 }
-function nextRunId(context, projectId, slug) {
-    const rows = context.db.all("SELECT id FROM runs WHERE project_id = ? AND id LIKE 'RUN-%'", [projectId]);
-    const max = rows.reduce((value, row) => {
-        try {
-            const parsed = parseFullEntityId(row.id);
-            return parsed.type === runIdType ? Math.max(value, Number(parsed.shortId.slice(4))) : value;
-        }
-        catch {
-            return value;
-        }
-    }, 0);
-    return formatFullId(runIdType, max + 1, slug);
-}
 function flowRunSummary(run) {
     return {
         id: run.id,