@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.150

package/dist/services/runs.js

@@ -2,10 +2,13 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
+import { withProjectionLock } from "../storage/projection-lock.js";
+import { reconcileRunStageReports } from "./stage-report-renderer.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 { ensureDir, projectRunHome, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.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";
 import { buildRunFlowGuidance } from "./flow-guidance.js";
@@ -14,12 +17,19 @@ import { recalculateRunUsage } from "./usage.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
 import { resolveCanonRoot } from "./canon.js";
 import { bindCurrentEngineToRun } from "./engines.js";
-import { executionProfilePath, loadVnextExecutionProfile } from "./vnext-execution-profile.js";
+import { assertOperationalDecisionSource, executionProfilePath, loadVnextExecutionProfileSnapshot } from "./vnext-execution-profile.js";
+import { loadVnextWorkspacePolicy } from "./vnext-workspace-policy.js";
+import { assertSameSessionMerge, loadExecutionRoutingInput, resolveStageTransition, snapshotAgentProfiles } from "./execution-policy.js";
 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";
+import { readRunEngineBinding } from "./run-engine-bindings.js";
 const runSchemaId = "dd-flow/flow-run@3";
 const runtimeSchemaId = "dd-flow/flow-run@3";
-const runIdType = "RUN";
 const allowedRunFlowKinds = [
     "mb_sdlc",
     "coding",
@@ -27,6 +37,7 @@ const allowedRunFlowKinds = [
     "mb-init",
     "mb-upgrade",
     "mb-audit",
+    "project-review",
     "mb-distill",
     "mb-upgrade-review",
     "mb-sdlc-review",
@@ -35,22 +46,26 @@ const allowedRunFlowKinds = [
     "review",
     "custom"
 ];
-export function startFlowRun(context, input) {
+export function prepareFlowRunStart(context, input) {
+    const subjectId = requiredPlain(input.subjectId, "subject-id");
+    const subjectType = requiredPlain(input.subjectType, "subject-type");
+    const slug = normalizeSlug(input.slug);
+    for (const [name, value] of [["task profile", input.taskProfile], ["protocol overrides", input.protocolOverrides], ["RUN overrides", input.runOverrides]]) {
+        if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value)))
+            throw new AppError("validation", `${name} must be a JSON object`, 2);
+    }
     const projectRoot = resolveProjectRoot(input.projectRoot);
+    const flowKind = parseRunFlowKind(input.flowKind);
+    const vnext = flowKind === "vnext_protocolize" || flowKind === "vnext_specify";
+    if (input.executionRoutingFile !== undefined && !vnext)
+        throw new AppError("usage", "Execution routing input is supported only for vNext RUNs", 2);
+    const routingInput = input.executionRoutingFile !== undefined ? loadExecutionRoutingInput(input.executionRoutingFile) : undefined;
+    const executionProfile = vnext ? snapshotVnextExecutionProfile(projectRoot, context.ddFlowHome, routingInput, context.now()) : undefined;
     const flowContract = input.flowKind === "mb-upgrade"
         ? loadUpgradeFlowContract(context, projectRoot)
         : loadProjectFlowContract(projectRoot);
-    registerProject(context, { root: projectRoot });
-    const project = requireProjectByRoot(context, projectRoot);
     const workspaceRoot = resolveWorkspaceRoot(input.workspaceRoot ?? projectRoot);
-    const flowKind = parseRunFlowKind(input.flowKind);
-    const slug = normalizeSlug(input.slug);
-    const runId = nextRunId(context, project.id, slug);
-    const { shortId } = parseFullEntityId(runId);
     const now = context.now();
-    const executionProfile = (flowKind === "vnext_protocolize" || flowKind === "vnext_specify")
-        ? snapshotVnextExecutionProfile(projectRoot)
-        : undefined;
     const flowFlags = resolveFlowFlags(flowContract, {
         flowKind,
         ...(input.preset ? { preset: input.preset } : {}),
@@ -60,17 +75,42 @@ export function startFlowRun(context, input) {
         snapshotRevision: 1,
         now
     });
+    return { projectRoot, flowKind, routingInput, executionProfile, workspaceRoot, slug, subjectId, subjectType, now, flowFlags };
+}
+export function startFlowRun(context, input, prepared = prepareFlowRunStart(context, input)) {
+    const { projectRoot, flowKind, routingInput, executionProfile, workspaceRoot, slug, subjectId, subjectType, now, flowFlags } = prepared;
+    // Ordinary settings are already frozen by preparation; only scoped authority
+    // requires its live acceptance source to survive final binding unchanged.
+    if (executionProfile?.operational_decision) {
+        if (crypto.createHash("sha256").update(fs.readFileSync(executionProfile.source_path)).digest("hex") !== executionProfile.source_checksum)
+            throw new AppError("execution_profile_changed", "Execution profile changed after RUN preparation", 2);
+        if (executionProfile.operational_decision)
+            assertOperationalDecisionSource(executionProfile.operational_decision, projectRoot, context.now());
+    }
+    registerProject(context, { root: projectRoot });
+    const project = requireProjectByRoot(context, projectRoot);
+    const runId = nextRunId(context, project.id, slug);
+    const { shortId } = parseFullEntityId(runId);
     const runHome = projectRunHome(context.ddFlowHome, project.id, runId);
     const runDirRelative = path.posix.join("runs", runId);
     const runtimePath = projectRunJsonPath(context.ddFlowHome, project.id, runId);
+    const policyBytes = executionProfile?.operational_decision ? fs.readFileSync(path.resolve(projectRoot, executionProfile.operational_decision.policy.path)) : undefined;
+    const policySource = policyBytes ? { path: "operational-policy.source.md", sha256: crypto.createHash("sha256").update(policyBytes).digest("hex") } : undefined;
+    if (policySource && policySource.sha256 !== executionProfile?.operational_decision?.policy.sha256)
+        throw new AppError("operational_decision_policy_changed", "Policy changed during final RUN binding", 2);
+    const binding = { project_id: project.id, run_id: runId, project_root: projectRoot, ...(executionProfile?.operational_decision?.scope.eval_id ? { eval_id: executionProfile.operational_decision.scope.eval_id } : {}), ...(executionProfile?.operational_decision?.scope.execution_id ? { execution_id: executionProfile.operational_decision.scope.execution_id } : {}) };
+    const operationalBytes = executionProfile ? `${JSON.stringify({ schema_id: "dd-flow/run-operational-contract@1", binding, settings: { merge_delivery: executionProfile.settings.merge_delivery, merge_cleanup: executionProfile.settings.merge_cleanup }, ...(executionProfile.operational_decision ? { decision: executionProfile.operational_decision, policy_source: policySource } : {}) }, null, 2)}\n` : undefined;
+    if (executionProfile && operationalBytes)
+        executionProfile.operational_contract = { path: "operational-contract.json", sha256: crypto.createHash("sha256").update(operationalBytes).digest("hex"), ...(policySource ? { policy_source: policySource } : {}), binding };
     const index = {
         schema_id: runSchemaId,
         run_id: runId,
         short_id: shortId,
         flow_kind: flowKind,
+        ...(["vnext_specify", "vnext_protocolize"].includes(flowKind) ? { verification_matrix_contract: "dd-flow/verification-matrix@1", final_check_coverage_contract: "dd-flow/final-check-coverage@1" } : {}),
         subject: {
-            id: requiredPlain(input.subjectId, "subject-id"),
-            title: requiredPlain(input.subjectId, "subject-id")
+            id: subjectId,
+            title: subjectId
         },
         project: {
             id: project.id,
@@ -126,9 +166,14 @@ export function startFlowRun(context, input) {
     };
     ensureDir(path.dirname(runtimePath));
     ensureDir(runHome);
+    if (policyBytes && policySource)
+        fs.writeFileSync(path.join(runHome, policySource.path), policyBytes, { flag: "wx" });
+    if (operationalBytes)
+        fs.writeFileSync(path.join(runHome, "operational-contract.json"), operationalBytes, { flag: "wx" });
+    if (routingInput)
+        fs.writeFileSync(path.join(runHome, "execution-routing.input.json"), routingInput.bytes, { flag: "wx", mode: 0o600 });
     bindCurrentEngineToRun(context, { projectRoot, runId, runRoot: runHome });
     const persistedIndex = persistedVnextIndex(index);
-    writeJsonFile(runtimePath, runtimeSnapshotForIndex(persistedIndex, 1));
     context.db.run(`INSERT INTO runs
       (id, short_id, slug, project_id, project_root, workspace_root, flow_kind, subject_type, subject_id,
        status, verdict, next_action, runtime_path, run_dir, run_index_path, run_home_path, run_root, layout_version, artifact_root_kind,
@@ -141,7 +186,7 @@ export function startFlowRun(context, input) {
         project.root,
         workspaceRoot,
         flowKind,
-        requiredPlain(input.subjectType, "subject-type"),
+        subjectType,
         index.subject.id,
         index.status,
         index.verdict,
@@ -162,8 +207,9 @@ export function startFlowRun(context, input) {
         eventType: "flow_run.started",
         payload: { run_id: runId, flow_kind: flowKind, subject: index.subject, workspace_root: workspaceRoot, run_home: runHome }
     });
-    appendRunTimeline(runHome, { at: now, type: "run_started", run_id: runId });
-    appendRunTimeline(runHome, {
+    context.db.afterCommit(() => publishRunProjections(context, project.id, runId));
+    appendRunTimeline(context, project.id, runId, { at: now, type: "run_started", run_id: runId });
+    appendRunTimeline(context, project.id, runId, {
         at: now,
         type: "flow_flags_resolved",
         run_id: runId,
@@ -173,13 +219,16 @@ export function startFlowRun(context, input) {
     });
     return { ok: true, run: flowRunSummary(requireRunById(context, project.id, runId)), index };
 }
-function snapshotVnextExecutionProfile(projectRoot) {
-    const profile = loadVnextExecutionProfile(projectRoot);
+function snapshotVnextExecutionProfile(projectRoot, ddFlowHome, routingInput, now = new Date().toISOString()) {
+    const { profile, bytes } = loadVnextExecutionProfileSnapshot(projectRoot);
+    if (profile.operational_decision)
+        assertOperationalDecisionSource(profile.operational_decision, projectRoot, now);
     const sourcePath = executionProfilePath(projectRoot);
-    return {
+    const frozen = freezeRunExecutionRouting(ddFlowHome, {
         schema_id: "dd-flow/run-execution-profile@1",
         source_path: sourcePath,
-        source_checksum: crypto.createHash("sha256").update(fs.readFileSync(sourcePath)).digest("hex"),
+        source_checksum: crypto.createHash("sha256").update(bytes).digest("hex"),
+        ...(profile.operational_decision ? { operational_decision: profile.operational_decision } : {}),
         settings: {
             stage_session_mode: profile.stage_session_mode,
             plan_review_mode: profile.plan_review_mode,
@@ -188,9 +237,47 @@ function snapshotVnextExecutionProfile(projectRoot) {
             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);
+    if (frozen.settings.merge_mode === "same_session" && frozen.settings.stop_target === "merge_completed"
+        && fs.existsSync(path.join(projectRoot, ".memory-bank", "dd-flow", "project-workspace.json"))
+        && loadVnextWorkspacePolicy(projectRoot).workspace.route === "feature_worktree") {
+        throw new AppError("merge_session_workspace_conflict", "Feature-worktree MERGE targets the integration checkout; use server MERGE or a qualified new Session", 2, { project_root: projectRoot });
+    }
+    return frozen;
+}
+/** Fresh RUN and fresh stage-entry experiments freeze through the same resolver. */
+export function freezeRunExecutionRouting(ddFlowHome, base, input) {
+    const execution = input?.execution ?? base.settings.execution;
+    const profiles = execution ? snapshotAgentProfiles(ddFlowHome, execution) : undefined;
+    if (execution && profiles && base.settings.merge_mode === "same_session" && base.settings.stop_target === "merge_completed") {
+        const mode = base.settings.code_review_mode;
+        assertSameSessionMerge({ ddFlowHome, policy: execution, profiles, previousStages: mode === "off" ? ["code"] : mode === "auto" ? ["code", "code-review"] : ["code-review"] });
+    }
+    return { ...base, ...(profiles ? { agent_profiles: profiles } : {}),
+        ...(input ? { routing_input: { source_path: input.source_path, source_checksum: input.source_checksum, artifact: "execution-routing.input.json" } } : {}),
+        settings: { ...base.settings, ...(execution ? { execution } : {}) } };
+}
+/** Called only after a stage-entry import has archived and detached source owners. */
+export function importFlowRunExecutionProfile(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
+    const index = authoritativeIndex(run);
+    const lineage = JSON.parse(fs.readFileSync(input.lineageFile, "utf8"));
+    if (lineage.schema_id !== "dd-flow/snapshot-runtime-lineage@1" || lineage.run_id !== run.id || path.resolve(lineage.restored_runtime ?? "") !== path.resolve(context.ddFlowHome)
+        || !vnextStages.some(stage => stage.id === input.stage)
+        || (context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'run_controllers'") && context.db.get("SELECT 1 FROM run_controllers WHERE project_id = ? AND run_id = ? LIMIT 1", [project.id, run.id]))
+        || index.stage_runs.some(stage => stage.stage === input.stage || !["done", "skipped"].includes(stage.status))
+        || context.db.get("SELECT 1 FROM sessions WHERE project_id = ? AND run_id = ? AND status IN ('active','idle') LIMIT 1", [project.id, run.id])) {
+        throw new AppError("snapshot_execution_active", "Execution policy can be selected only at a detached stage-entry import", 1);
+    }
+    index.execution_profile = { ...input.profile, stage_entry_import: { stage: input.stage, lineage_file: input.lineageFile } };
+    index.updated_at = context.now();
+    persistRunState(context, project, run, index);
+    appendRunTimeline(context, project.id, run.id, { at: index.updated_at, type: "execution_policy_imported", stage: input.stage, lineage_file: input.lineageFile, source_checksum: input.profile.routing_input?.source_checksum });
 }
 /**
  * A vNext route may materialize a feature checkout after its semantic
@@ -200,19 +287,82 @@ function snapshotVnextExecutionProfile(projectRoot) {
 export function rebindFlowRunWorkspace(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
+    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(runArtifactRoot(run), { 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) {
@@ -224,12 +374,57 @@ 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, ...(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, 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);
+    if (control)
+        return { kind: "wait", stage: index.current_stage ?? null, attempt: null, work_id: null, reason: "operator_control", command: null, control };
+    const active = index.stage_runs.find((stage) => !["done", "skipped"].includes(stage.status));
+    if (active) {
+        const runningWork = context.db.get("SELECT work_id FROM works WHERE project_id = ? AND run_id = ? AND status = 'running' ORDER BY updated_at DESC LIMIT 1", [run.project_id, run.id]);
+        const kind = active.status === "running" ? "continue_stage" : active.status === "paused" || active.status === "waiting_for_user" ? "paused" : "blocked";
+        return { kind, stage: active.stage, attempt: active.attempt ?? null, work_id: active.pause?.work_id ?? runningWork?.work_id ?? null, reason: active.status, command: null };
+    }
+    if (run.status === "waiting_for_user" || run.status === "paused")
+        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";
+        if (!next)
+            return { kind: "terminal", stage: null, attempt: null, work_id: null, reason: "flow_complete", command: null };
+        const command = `${flowCommand(context)} stage start ${run.id} --stage ${next} --project-root ${JSON.stringify(run.project_root)} --json`;
+        const profile = index.execution_profile;
+        const execution = profile?.settings.execution ? profile.agent_profiles
+            ? { status: "resolved", ...resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy: profile.settings.execution, profiles: profile.agent_profiles, projectRoot: run.project_root, workspaceRoot: run.workspace_root, ...(completed ? { fromStage: completed.stage } : {}), stage: next, stageSessionMode: profile.settings.stage_session_mode, mergeMode: profile.settings.merge_mode }) }
+            : { status: "unfrozen", reason: "execution_profile_not_frozen" }
+            : undefined;
+        return { kind: "start_stage", stage: next, attempt: null, work_id: null, reason: "legal_successor", command, ...(execution ? { execution } : {}) };
+    }
+    return { kind: "wait", stage: index.current_stage ?? null, attempt: null, work_id: null, reason: "no_vnext_continuation", command: null };
 }
 export function getFlowRunConfig(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -250,9 +445,12 @@ export function getFlowRunVariables(context, input) {
     return { ok: true, run_id: run.id, variables };
 }
 export function setFlowRunVariable(context, input) {
+    return setRunVariable(context, input, input.value, prepareFlowRunVariable(context, input));
+}
+export function prepareFlowRunVariable(context, input) {
     if (!input.key.startsWith("user."))
         throw new AppError("validation", "Only user.* RUN variables may be set directly", 2, { key: input.key });
-    return setRunVariable(context, input, input.value);
+    return prepareRunVariable(context, input);
 }
 /** Controllers own policy.* and runtime.* values; agents never call this directly. */
 export function setRuntimeRunVariable(context, input) {
@@ -261,20 +459,7 @@ export function setRuntimeRunVariable(context, input) {
     return setRunVariable(context, input, input.value);
 }
 export function setFlowRunConfig(context, input) {
-    if (input.key !== "plan_review.mode" && input.key !== "code_review.mode") {
-        throw new AppError("validation", `Unknown RUN config key: ${input.key}`, 2);
-    }
-    if (!["auto", "off", "standard", "deep"].includes(input.value)) {
-        throw new AppError("validation", "--value for review mode must be auto, off, standard, or deep", 2);
-    }
-    const reason = requiredPlain(input.reason, "reason");
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const run = resolveRun(context, project.id, input.runId);
-    const index = authoritativeIndex(run);
-    const stageName = input.key === "plan_review.mode" ? "plan-review" : "code-review";
-    if (index.stage_runs.some((stage) => stage.stage === stageName)) {
-        throw new AppError("invalid_run_config_state", `${input.key} is frozen after ${stageName} starts`, 2, { run_id: run.id });
-    }
+    const { reason, project, run, index } = prepareFlowRunConfig(context, input);
     const now = context.now();
     const settings = runSettings(index);
     const previous = input.key === "plan_review.mode" ? settings.plan_review : settings.code_review;
@@ -289,13 +474,32 @@ export function setFlowRunConfig(context, input) {
     index.updated_at = now;
     persistRunState(context, project, run, index);
     appendAudit(context, { projectId: project.id, eventType: "flow_run.config_set", payload: { run_id: run.id, key: input.key, value: mode, source, reason } });
-    appendRunTimeline(runArtifactRoot(run), { at: now, type: "run_config_set", run_id: run.id, key: input.key, value: mode, source, reason });
+    appendRunTimeline(context, project.id, run.id, { at: now, type: "run_config_set", run_id: run.id, key: input.key, value: mode, source, reason });
     return { ok: true, run_id: run.id, settings: runSettings(index), idempotent: false };
 }
+export function prepareFlowRunConfig(context, input) {
+    if (input.key !== "plan_review.mode" && input.key !== "code_review.mode") {
+        throw new AppError("validation", `Unknown RUN config key: ${input.key}`, 2);
+    }
+    if (!["auto", "off", "standard", "deep"].includes(input.value)) {
+        throw new AppError("validation", "--value for review mode must be auto, off, standard, or deep", 2);
+    }
+    const reason = requiredPlain(input.reason, "reason");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
+    const index = authoritativeIndex(run);
+    const stageName = input.key === "plan_review.mode" ? "plan-review" : "code-review";
+    if (index.stage_runs.some((stage) => stage.stage === stageName)) {
+        throw new AppError("invalid_run_config_state", `${input.key} is frozen after ${stageName} starts`, 2, { run_id: run.id });
+    }
+    return { reason, project, run, index };
+}
 /** Freeze an automatic review request once from already accepted policy or PLAN facts. */
 export function freezeFlowRunReviewMode(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
     const settings = runSettings(index);
     const key = input.review === "plan" ? "plan_review" : "code_review";
@@ -312,8 +516,8 @@ export function getFlowRunFlagsStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
     const index = authoritativeIndex(run);
-    const runtime = readRuntimeSnapshot(run.runtime_path);
-    const flags = runtime?.flow_flags ?? index.flow_flags;
+    const legacyRuntime = index.flow_flags ? null : readRuntimeSnapshot(run.runtime_path);
+    const flags = index.flow_flags ?? legacyRuntime?.flow_flags;
     if (!flags) {
         return {
             ok: true,
@@ -331,29 +535,31 @@ export function getFlowRunFlagsStatus(context, input) {
         snapshot_revision: flags.snapshot_revision,
         snapshot_checksum: flags.snapshot_checksum,
         flow_flags: flags,
-        runtime_revision: runtime?.runtime_revision ?? index.runtime_revision ?? null
+        runtime_revision: index.runtime_revision ?? legacyRuntime?.runtime_revision ?? null
     };
 }
 export function reviseFlowRunFlags(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
     const idempotencyKey = requiredPlain(input.idempotencyKey, "idempotency-key");
-    context.db.exec("BEGIN IMMEDIATE");
-    let committed = false;
-    try {
+    const priorMutation = context.db.get("SELECT result_json FROM flow_run_flag_mutations WHERE project_id = ? AND run_id = ? AND idempotency_key = ?", [project.id, run.id, idempotencyKey]);
+    if (priorMutation)
+        return { ...JSON.parse(priorMutation.result_json), idempotent: true };
+    // Canonical contract bytes are prepared before taking the writer. Revision
+    // and idempotency are compared again against SQL authority under the lock.
+    const contract = loadProjectFlowContract(run.project_root);
+    return context.db.writeTransaction(() => {
         const existingMutation = context.db.get("SELECT result_json FROM flow_run_flag_mutations WHERE project_id = ? AND run_id = ? AND idempotency_key = ?", [project.id, run.id, idempotencyKey]);
         if (existingMutation) {
             const result = { ...JSON.parse(existingMutation.result_json), idempotent: true };
-            context.db.exec("COMMIT");
-            committed = true;
             return result;
         }
         // Read the authority only after the write lock: two callers with the same
         // expected revision must not both pass the compare-and-set check.
         const lockedRun = requireRunById(context, project.id, run.id);
         const index = authoritativeIndex(lockedRun);
-        const runtime = readRuntimeSnapshot(lockedRun.runtime_path);
-        const current = runtime?.flow_flags ?? index.flow_flags;
+        const current = index.flow_flags;
         if (!current) {
             throw new AppError("validation", "Legacy RUN has no flow-flag snapshot; revise is unavailable", 2, { run_id: run.id });
         }
@@ -370,7 +576,6 @@ export function reviseFlowRunFlags(context, input) {
             });
         }
         const now = context.now();
-        const contract = loadProjectFlowContract(lockedRun.project_root);
         const next = resolveFlowFlags(contract, {
             flowKind: index.flow_kind,
             preset: input.preset ?? current.preset.applied,
@@ -426,14 +631,12 @@ export function reviseFlowRunFlags(context, input) {
         context.db.run(`INSERT INTO flow_run_flag_mutations
         (project_id, run_id, idempotency_key, expected_revision, resulting_revision, result_json, created_at)
        VALUES (?, ?, ?, ?, ?, ?, ?)`, [project.id, run.id, idempotencyKey, input.expectedRevision, next.snapshot_revision, JSON.stringify(result), now]);
-        context.db.exec("COMMIT");
-        committed = true;
         appendAudit(context, {
             projectId: project.id,
             eventType: "flow_run.flags_revised",
             payload: { run_id: run.id, snapshot_revision: next.snapshot_revision, snapshot_checksum: next.snapshot_checksum, ...(reason ? { reason } : {}) }
         });
-        appendRunTimeline(runArtifactRoot(run), {
+        appendRunTimeline(context, project.id, run.id, {
             at: now,
             type: "flow_flags_revised",
             run_id: run.id,
@@ -443,12 +646,7 @@ export function reviseFlowRunFlags(context, input) {
             ...(reason ? { reason } : {})
         });
         return result;
-    }
-    catch (error) {
-        if (!committed)
-            context.db.exec("ROLLBACK");
-        throw error;
-    }
+    }, "runs.reviseFlowFlags");
 }
 export function listFlowRuns(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -459,113 +657,268 @@ export function listFlowRuns(context, input) {
         .map(flowRunSummary);
     return { ok: true, project, runs };
 }
-export function attachFlowRunStage(context, input) {
+export function prepareFlowRunStageAttachment(context, input, archive = false) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    const index = authoritativeIndex(run);
-    const now = context.now();
+    const generation = assertRunMutationAllowed(context, project.id, run.id);
     const stage = requiredPlain(input.stage, "stage");
-    const dir = requiredStageDir(input.dir);
+    const dir = prepareStageDirectory(input.dir);
+    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);
-    if (status === "running" && existing) {
-        archiveExistingStageAttempt(runArtifactRoot(run), dir);
-    }
-    const stageRun = {
-        ...(existing ?? { order: index.stage_runs.length + 1 }),
-        stage,
-        dir,
-        status,
-        ...(input.dataSchemaId ? { data_schema_id: input.dataSchemaId } : existing?.data_schema_id ? { data_schema_id: existing.data_schema_id } : {}),
-        updated_at: now
-    };
-    if (status === "running") {
-        stageRun.started_at = now;
-        delete stageRun.completed_at;
-        stageRun.duration_ms = null;
-        stageRun.git = gitFacts(run.workspace_root);
-        stageRun.attempt = nextAttempt(existing);
-    }
-    upsertStage(index, stageRun);
-    index.current_stage = stage;
-    index.attempts = index.stage_runs.map((item) => ({ stage: item.stage, attempt_number: Number((item.attempt ?? "try-001").replace("try-", "")) || 1, root: item.dir, archive: null, status: item.status, started_at: item.started_at ?? now, finished_at: item.completed_at ?? null }));
-    index.updated_at = now;
-    persistRunState(context, project, run, index);
-    appendAudit(context, {
-        projectId: project.id,
-        eventType: "flow_run.stage_attached",
-        payload: { run_id: run.id, stage, dir, status }
-    });
-    appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_attached", run_id: run.id, stage, status, attempt: stageRun.attempt ?? null });
-    // A stage transition must not rewrite every Session in the RUN.  A RUN may
-    // contain independent reviewer/worker sessions; their stage is set by the
-    // stage/work binding that actually owns that Session.
-    if (status === "running")
-        refreshRunSessionProjection(context, project.id, run.id);
+    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, 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.
+    const { project, run, stage, dir, status, generation, git } = prepared;
+    const attached = context.db.writeTransaction(() => {
+        assertRunMutationAllowed(context, project.id, run.id, generation);
+        const latest = requireRunById(context, project.id, run.id);
+        const index = authoritativeIndex(latest);
+        const existing = index.stage_runs.find((item) => item.stage === stage);
+        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 });
+        }
+        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 }),
+            stage,
+            dir,
+            status,
+            ...(input.inputSha256 ? { input_sha256: input.inputSha256 } : {}),
+            ...(input.dataSchemaId ? { data_schema_id: input.dataSchemaId } : existing?.data_schema_id ? { data_schema_id: existing.data_schema_id } : {}),
+            updated_at: now
+        };
+        if (status === "running") {
+            stageRun.started_at = now;
+            delete stageRun.completed_at;
+            stageRun.duration_ms = null;
+            if (git)
+                stageRun.git = git;
+            stageRun.attempt = prepared.attempt;
+        }
+        upsertStage(index, stageRun);
+        index.current_stage = stage;
+        index.attempts = index.stage_runs.map((item) => ({ stage: item.stage, attempt_number: Number((item.attempt ?? "try-001").replace("try-", "")) || 1, root: item.dir, archive: null, status: item.status, started_at: item.started_at ?? now, finished_at: item.completed_at ?? null }));
+        index.updated_at = now;
+        persistRunState(context, project, run, index);
+        appendAudit(context, {
+            projectId: project.id,
+            eventType: "flow_run.stage_attached",
+            payload: { run_id: run.id, stage, dir, status }
+        });
+        appendRunTimeline(context, project.id, run.id, { at: now, type: "stage_attached", run_id: run.id, stage, status, attempt: stageRun.attempt ?? null });
+        context.db.afterCommit(() => reconcileRunStageReports(context, project.id, run.id, stage));
+        // A stage transition must not rewrite every Session in the RUN.  A RUN may
+        // contain independent reviewer/worker sessions; their stage is set by the
+        // stage/work binding that actually owns that Session.
+        if (status === "running")
+            context.db.afterCommit(() => refreshRunSessionProjection(context, project.id, run.id));
+        return { stageRun, index };
+    }, "stage.attach");
     const updatedRun = requireRunById(context, project.id, run.id);
-    return { ok: true, run: flowRunSummary(updatedRun), stage_run: stageRun, index, flow_guidance: guidanceForRun(context, updatedRun, index) };
+    return { ok: true, run: flowRunSummary(updatedRun), stage_run: attached.stageRun, index: attached.index, flow_guidance: guidanceForRun(context, updatedRun, attached.index) };
+}
+/** Keep synchronous stage settlement atomic; files are projections, SQLite is authoritative. */
+export function withStageSettlement(context, operation) {
+    return context.db.writeTransaction(operation, "stage.settle");
 }
-export function completeFlowRunStage(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);
+    }
+    if (input.aliases !== undefined) {
+        if (!Array.isArray(input.aliases))
+            throw new AppError("validation", "artifact aliases must be an array", 2);
+        for (const alias of input.aliases)
+            requiredPlain(alias, "artifact alias");
+    }
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
+    if (["done", "failed", "skipped"].includes(input.status))
+        assertStageSettlementAllowed(context, project.id, run.id, input.stage);
+    else
+        assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
-    const now = context.now();
     const stage = requiredPlain(input.stage, "stage");
     const status = parseStageStatus(input.status);
     const existing = index.stage_runs.find((item) => item.stage === stage);
     if (!existing) {
         throw new AppError("not_found", `Run stage is not attached: ${stage}`, 1, { run_id: run.id, stage });
     }
-    const stageRun = {
-        ...existing,
-        status,
-        ...(input.stageReport ? { stage_report: input.stageReport } : {}),
-        ...(input.data ? { data: input.data } : {}),
-        ...(input.dataSchemaId ? { data_schema_id: input.dataSchemaId } : {}),
-        ...(input.report ? { report: input.report } : {}),
-        ...(input.aliases && input.aliases.length > 0 ? { artifact_aliases: input.aliases } : {}),
-        updated_at: now,
-        ...(status === "done" || status === "waiting_for_user" || status === "blocked" || status === "failed" || status === "skipped"
-            ? { completed_at: now, duration_ms: durationMs(existing.started_at ?? null, now), git: gitFacts(run.workspace_root) }
-            : {})
-    };
-    upsertStage(index, stageRun);
-    if (status === "waiting_for_user") {
-        index.status = "waiting_for_user";
-        index.verdict = "waiting_for_user";
-    }
-    else if (status === "blocked" || status === "failed") {
-        index.status = status;
-        index.verdict = status;
+    // 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);
     }
-    else if (status === "done" && index.status === "waiting_for_user") {
-        index.status = "running";
-        index.verdict = "running";
+    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 });
+        }
     }
-    index.current_stage = stage;
-    index.attempts = index.stage_runs.map((item) => ({ stage: item.stage, attempt_number: Number((item.attempt ?? "try-001").replace("try-", "")) || 1, root: item.dir, archive: null, status: item.status, started_at: item.started_at ?? now, finished_at: item.completed_at ?? null }));
-    index.updated_at = now;
-    index.execution = {
-        project_root: index.execution?.project_root ?? run.project_root,
-        workspace_root: index.execution?.workspace_root ?? run.workspace_root,
-        git: gitFacts(run.workspace_root)
-    };
-    persistRunState(context, project, run, index);
-    refreshRunSessionProjection(context, project.id, run.id);
-    appendAudit(context, {
-        projectId: project.id,
-        eventType: "flow_run.stage_completed",
-        payload: { run_id: run.id, stage, status, stage_report: input.stageReport ?? null, data: input.data ?? null }
-    });
-    appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_completed", run_id: run.id, stage, status, attempt: stageRun.attempt ?? null });
+    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, 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)
+        return { status: "unavailable", input_tokens: null, cached_input_tokens: null, output_tokens: null, total_tokens: null, session_count: 0, observed_at: context.now() };
+    const value = recalculateRunUsage(context, { projectId: run.project_id, runId: run.id, stage: { name: stage, startedAt, completedAt: context.now() } });
+    const totals = value.totals, coverage = value.coverage;
+    const count = (name) => typeof coverage?.[name] === "number" ? coverage[name] : 0;
+    const measured = count("measured"), other = Object.values(coverage ?? {}).reduce((total, item) => total + (typeof item === "number" ? item : 0), 0) - measured;
+    const tokens = (name) => typeof totals?.[name] === "number" ? totals[name] : null;
+    return { status: measured === 0 ? "unavailable" : other > 0 || ["input_tokens", "cache_read_input_tokens", "output_tokens", "total_tokens"].some(name => tokens(name) === null) ? "partial" : "measured", input_tokens: tokens("input_tokens"), cached_input_tokens: tokens("cache_read_input_tokens"), output_tokens: tokens("output_tokens"), total_tokens: tokens("total_tokens"), session_count: Array.isArray(value.sessions) ? value.sessions.length : 0, observed_at: typeof value.observed_at === "string" ? value.observed_at : context.now() };
+}
+export function completeFlowRunStage(context, input, prepared = prepareFlowRunStageCompletion(context, input)) {
+    const { project, run, stage, status, dataSha256, git, generation } = prepared;
+    const completed = context.db.writeTransaction(() => {
+        if (["done", "failed", "skipped"].includes(status))
+            assertStageSettlementAllowed(context, project.id, run.id, stage, generation);
+        else
+            assertRunMutationAllowed(context, project.id, run.id, generation);
+        const latest = requireRunById(context, project.id, run.id);
+        const index = authoritativeIndex(latest);
+        const existing = index.stage_runs.find((item) => item.stage === stage);
+        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,
+            status,
+            ...(input.stageReport ? { stage_report: input.stageReport } : {}),
+            ...(input.data ? { data: input.data } : {}),
+            ...(dataSha256 ? { data_sha256: dataSha256 } : {}),
+            ...(input.dataSchemaId ? { data_schema_id: input.dataSchemaId } : {}),
+            ...(input.report ? { report: input.report } : {}),
+            usage: input.usage ?? stageUsageProjection(context, latest, stage, existing.started_at),
+            ...(input.aliases && input.aliases.length > 0 ? { artifact_aliases: input.aliases } : {}),
+            updated_at: now,
+            ...(status === "done" || status === "waiting_for_user" || status === "blocked" || status === "failed" || status === "skipped"
+                ? { completed_at: now, duration_ms: durationMs(existing.started_at ?? null, now), git }
+                : {})
+        };
+        upsertStage(index, stageRun);
+        if (status === "waiting_for_user") {
+            index.status = "waiting_for_user";
+            index.verdict = "waiting_for_user";
+        }
+        else if (status === "blocked" || status === "failed") {
+            index.status = status;
+            index.verdict = status;
+        }
+        else if (status === "done" && index.status === "waiting_for_user") {
+            index.status = "running";
+            index.verdict = "running";
+        }
+        index.current_stage = stage;
+        index.attempts = index.stage_runs.map((item) => ({ stage: item.stage, attempt_number: Number((item.attempt ?? "try-001").replace("try-", "")) || 1, root: item.dir, archive: null, status: item.status, started_at: item.started_at ?? now, finished_at: item.completed_at ?? null }));
+        index.updated_at = now;
+        index.execution = {
+            project_root: index.execution?.project_root ?? run.project_root,
+            workspace_root: index.execution?.workspace_root ?? run.workspace_root,
+            git
+        };
+        persistRunState(context, project, latest, index);
+        context.db.afterCommit(() => refreshRunSessionProjection(context, project.id, run.id));
+        appendAudit(context, {
+            projectId: project.id,
+            eventType: "flow_run.stage_completed",
+            payload: { run_id: run.id, stage, status, stage_report: input.stageReport ?? null, data: input.data ?? null }
+        });
+        appendRunTimeline(context, project.id, run.id, { at: now, type: "stage_completed", run_id: run.id, stage, status, attempt: stageRun.attempt ?? null });
+        return { index, stageRun };
+    }, "runs.completeFlowRunStage");
     const updatedRun = requireRunById(context, project.id, run.id);
-    return { ok: true, run: flowRunSummary(updatedRun), stage_run: stageRun, index, flow_guidance: guidanceForRun(context, updatedRun, index) };
+    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));
     const run = resolveRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
     const stage = requiredPlain(input.stage, "stage");
     const stageRun = index.stage_runs.find((item) => item.stage === stage);
@@ -594,13 +947,14 @@ export function pauseFlowRunStage(context, input) {
     persistRunState(context, project, run, index);
     refreshRunSessionProjection(context, project.id, run.id);
     appendAudit(context, { projectId: project.id, eventType: "flow_run.stage_paused", payload: { run_id: run.id, stage, work_id: input.workId, pause_id: input.pauseId, reason: "waiting_for_user" } });
-    appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_waiting_for_user", run_id: run.id, stage, work_id: input.workId, pause_id: input.pauseId, question_path: input.questionPath });
+    appendRunTimeline(context, project.id, run.id, { at: now, type: "stage_waiting_for_user", run_id: run.id, stage, work_id: input.workId, pause_id: input.pauseId, question_path: input.questionPath });
     return { run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
 }
 /** Resume the same stage, Work and attempt after a user answer is recorded. */
 export function resumeFlowRunStage(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
     const stage = requiredPlain(input.stage, "stage");
     const stageRun = index.stage_runs.find((item) => item.stage === stage);
@@ -624,19 +978,28 @@ export function resumeFlowRunStage(context, input) {
     persistRunState(context, project, run, index);
     refreshRunSessionProjection(context, project.id, run.id);
     appendAudit(context, { projectId: project.id, eventType: "flow_run.stage_resumed", payload: { run_id: run.id, stage, work_id: input.workId, pause_id: pause.id, answer_path: input.answerPath } });
-    appendRunTimeline(runArtifactRoot(run), { at: now, type: "user_answer_received", run_id: run.id, stage, work_id: input.workId, pause_id: pause.id, answer_path: input.answerPath });
-    appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_resumed", run_id: run.id, stage, work_id: input.workId, pause_id: pause.id, paused_ms: pausedMs });
+    appendRunTimeline(context, project.id, run.id, { at: now, type: "user_answer_received", run_id: run.id, stage, work_id: input.workId, pause_id: pause.id, answer_path: input.answerPath });
+    appendRunTimeline(context, project.id, run.id, { at: now, type: "stage_resumed", run_id: run.id, stage, work_id: input.workId, pause_id: pause.id, paused_ms: pausedMs });
     return { run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
 }
 /** Pause the current stage for a non-user runtime blocker. */
-export function blockFlowRunStage(context, input) {
+export function prepareFlowRunStageBlock(context, input) {
+    if (!["engine", "harness", "environment"].includes(input.kind) || typeof input.retryable !== "boolean")
+        throw new AppError("validation", "stage block requires a valid kind and boolean retryable", 2);
+    requiredPlain(input.code, "code");
+    requiredPlain(input.summary, "summary");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
     const stage = requiredPlain(input.stage, "stage");
     const stageRun = index.stage_runs.find((item) => item.stage === stage);
     if (!stageRun || stageRun.status !== "running")
         throw new AppError("invalid_stage_state", "Only a running stage can be blocked", 1, { run_id: run.id, stage, status: stageRun?.status ?? "missing" });
+    return { project, run, index, stage, stageRun };
+}
+export function blockFlowRunStage(context, input, prepared = prepareFlowRunStageBlock(context, input)) {
+    const { project, run, index, stage, stageRun } = prepared;
     const now = context.now();
     stageRun.status = "blocked";
     stageRun.updated_at = now;
@@ -650,20 +1013,24 @@ export function blockFlowRunStage(context, input) {
     persistRunState(context, project, run, index);
     refreshRunSessionProjection(context, project.id, run.id);
     appendAudit(context, { projectId: project.id, eventType: "flow_run.stage_blocked", payload: { run_id: run.id, stage, work_id: input.workId, kind: input.kind, code: input.code, retryable: input.retryable } });
-    appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_blocked", run_id: run.id, stage, work_id: input.workId, kind: input.kind, code: input.code, summary: input.summary, retryable: input.retryable });
+    appendRunTimeline(context, project.id, run.id, { at: now, type: "stage_blocked", run_id: run.id, stage, work_id: input.workId, kind: input.kind, code: input.code, summary: input.summary, retryable: input.retryable });
     return { run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
 }
 /** Continue the same stage after its non-user blocker was repaired externally. */
-export function unblockFlowRunStage(context, input) {
+export function prepareFlowRunStageUnblock(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
     const stage = requiredPlain(input.stage, "stage");
     const stageRun = index.stage_runs.find((item) => item.stage === stage);
     if (!stageRun || stageRun.status !== "blocked" || !stageRun.blocker || stageRun.blocker.work_id !== input.workId)
         throw new AppError("invalid_stage_state", "Stage unblock requires its matching runtime blocker", 1, { run_id: run.id, stage, work_id: input.workId, status: stageRun?.status ?? "missing" });
+    return { project, run, index, stage, stageRun, blocker: stageRun.blocker };
+}
+export function unblockFlowRunStage(context, input, prepared = prepareFlowRunStageUnblock(context, input)) {
+    const { project, run, index, stage, stageRun, blocker } = prepared;
     const now = context.now();
-    const blocker = stageRun.blocker;
     const blockedMs = durationMs(blocker.blocked_at, now) ?? 0;
     stageRun.status = "running";
     stageRun.updated_at = now;
@@ -678,7 +1045,7 @@ export function unblockFlowRunStage(context, input) {
     persistRunState(context, project, run, index);
     refreshRunSessionProjection(context, project.id, run.id);
     appendAudit(context, { projectId: project.id, eventType: "flow_run.stage_unblocked", payload: { run_id: run.id, stage, work_id: input.workId, code: blocker.code } });
-    appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_unblocked", run_id: run.id, stage, work_id: input.workId, code: blocker.code, blocked_ms: blockedMs });
+    appendRunTimeline(context, project.id, run.id, { at: now, type: "stage_unblocked", run_id: run.id, stage, work_id: input.workId, code: blocker.code, blocked_ms: blockedMs });
     return { run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
 }
 function operationalRunStatus(context, projectId, runId) {
@@ -687,11 +1054,76 @@ function operationalRunStatus(context, projectId, runId) {
     const leaves = unfinished.filter((work) => !parents.has(work.work_id));
     return leaves.length > 0 && leaves.every((work) => work.status === "paused") ? "paused" : "running";
 }
-export function completeFlowRun(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+/** Keep the logical RUN projection aligned with recovery authority. Stage/Work
+ * evidence and verdicts survive a reversible stop; terminal runs never reopen. */
+export function setFlowRunRecoveryPaused(context, projectId, runId, paused) {
+    const run = resolveRun(context, projectId, runId);
+    if (!["running", "paused"].includes(run.status))
+        return;
+    const index = authoritativeIndex(run);
+    const status = paused || index.stage_runs.some(stage => ["paused", "waiting_for_user", "blocked"].includes(stage.status))
+        ? "paused" : operationalRunStatus(context, projectId, runId);
+    if (run.status === status && index.status === status)
+        return;
+    index.status = status;
+    index.updated_at = context.now();
+    const project = requireProjectByRoot(context, run.project_root);
+    persistRunState(context, project, run, index);
+}
+/** Reconciliation repairs projections under the same revision CAS as normal
+ * lifecycle writes. Unknown physical ownership never closes child records. */
+export function reconcileStoredFlowRun(context, expected, health, transition, childrenSettled = false) {
+    const run = resolveRun(context, expected.project_id, expected.id);
+    if (run.index_json !== expected.index_json || run.status !== expected.status)
+        throw new AppError("run_revision_changed", "RUN changed during health observation", 1);
+    const index = authoritativeIndex(run), now = context.now();
+    index.health = health;
+    if (transition && !["done", "failed", "cancelled", "discarded"].includes(run.status)) {
+        index.status = transition;
+        if (transition === "failed") {
+            index.verdict = "failed";
+            // Observation time is not the historical exit time. Without a retained
+            // finish receipt, keep timing unknown rather than manufacturing days of work.
+            delete index.completed_at;
+            delete index.finished_at;
+            index.duration_ms = null;
+            index.timing_status = 'legacy_incomplete';
+            closeOpenStagesForOverride(index, "failed", now, false);
+            closeOpenWorksForOverride(context, run.project_id, run.id, "failed", now, false);
+        }
+        else if (childrenSettled && health.state === "owner_lost") {
+            for (const stage of index.stage_runs)
+                if (stage.status === "running") {
+                    stage.status = "paused";
+                    stage.updated_at = now;
+                }
+        }
+    }
+    if (childrenSettled && ["failed", "cancelled", "discarded"].includes(index.status)) {
+        closeOpenStagesForOverride(index, index.status === "failed" ? "failed" : "cancelled", now, false);
+        closeOpenWorksForOverride(context, run.project_id, run.id, index.status === "failed" ? "failed" : "cancelled", now, false);
+        context.db.run("UPDATE sessions SET status = 'stopped', stop_reason = ?, updated_at = ? WHERE project_id = ? AND run_id = ? AND status IN ('pending','active','waiting_user','blocked','stopping')", [`run_${index.status}`, now, run.project_id, run.id]);
+        context.db.run("UPDATE check_receipts SET status = 'aborted' WHERE project_id = ? AND run_id = ? AND status = 'running'", [run.project_id, run.id]);
+    }
+    // Health observation is not semantic progress or a new completion timestamp.
+    const project = requireProjectByRoot(context, run.project_root);
+    persistRunState(context, project, run, index, { healthOnly: true });
+    appendAudit(context, { projectId: project.id, eventType: "flow_run.health_reconciled", payload: { run_id: run.id, previous_status: run.status, status: index.status, health } });
+}
+export function prepareFlowRunCompletion(context, input) {
+    if (input.manualOverrideReason !== undefined) {
+        requiredPlain(input.manualOverrideReason, "override reason");
+        if (!["cancelled", "failed"].includes(input.status))
+            throw new AppError("validation", "Manual RUN override may only cancel or fail a RUN", 2);
+    }
+    if (input.verdict !== undefined)
+        requiredPlain(input.verdict, "verdict");
+    if (input.nextAction !== undefined)
+        requiredPlain(input.nextAction, "next action");
+    const project = requireProjectByRoot(context, input.manualOverrideReason ? canonicalPath(input.projectRoot, false) : resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
-    const now = context.now();
     const status = parseRunStatus(input.status);
     if (!['done', 'cancelled', 'failed'].includes(status)) {
         throw new AppError('validation', 'completeFlowRun accepts only done, cancelled, or failed; use stage block/unblock for a recoverable blocker', 2, { status });
@@ -701,6 +1133,11 @@ export function completeFlowRun(context, input) {
         if (activeWork)
             throw new AppError("active_work", "RUN cannot complete while Work remains active", 2, { run_id: run.id, work_id: activeWork.work_id, status: activeWork.status });
     }
+    return { project, run, index, status };
+}
+export function completeFlowRun(context, input) {
+    const { project, run, index, status } = prepareFlowRunCompletion(context, input);
+    const now = context.now();
     if (input.manualOverrideReason && (status === "cancelled" || status === "failed")) {
         closeOpenStagesForOverride(index, status, now);
         closeOpenWorksForOverride(context, project.id, run.id, status, now);
@@ -734,25 +1171,65 @@ export function completeFlowRun(context, input) {
         eventType: input.manualOverrideReason ? "flow_run.manual_override" : "flow_run.completed",
         payload: { run_id: run.id, status, verdict: index.verdict, next_action: index.next_action, ...(input.manualOverrideReason ? { reason: input.manualOverrideReason } : {}) }
     });
-    appendRunTimeline(runArtifactRoot(run), { at: now, type: input.manualOverrideReason ? "run_manual_override" : "run_completed", run_id: run.id, status, ...(input.manualOverrideReason ? { reason: input.manualOverrideReason } : {}) });
+    appendRunTimeline(context, project.id, run.id, { at: now, type: input.manualOverrideReason ? "run_manual_override" : "run_completed", run_id: run.id, status, ...(input.manualOverrideReason ? { reason: input.manualOverrideReason } : {}) });
     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));
     const run = resolveRun(context, project.id, input.runId);
     const index = authoritativeIndex(run);
+    if (input.settlementStage && input.status === "running" && index.current_stage === input.settlementStage && index.stage_runs.some(stage => stage.stage === input.settlementStage && ["done", "skipped"].includes(stage.status)))
+        assertStageSettlementAllowed(context, project.id, run.id, input.settlementStage);
+    else
+        assertRunMutationAllowed(context, project.id, run.id);
+    const control = runControlDirective(context, project.id, run.id);
     const now = context.now();
     index.status = input.status;
     index.verdict = input.verdict;
-    index.next_action = input.nextAction ?? null;
+    index.next_action = control ? null : input.nextAction ?? null;
     index.updated_at = now;
     persistRunState(context, project, run, index);
-    appendAudit(context, { projectId: project.id, eventType: "flow_run.progressed", payload: { run_id: run.id, status: input.status, verdict: input.verdict, next_action: index.next_action } });
-    appendRunTimeline(runArtifactRoot(run), { at: now, type: "run_progressed", run_id: run.id, status: input.status, next_action: index.next_action });
+    appendAudit(context, { projectId: project.id, eventType: "flow_run.progressed", payload: { run_id: run.id, status: index.status, verdict: input.verdict, next_action: index.next_action } });
+    appendRunTimeline(context, project.id, run.id, { at: now, type: "run_progressed", run_id: run.id, status: index.status, next_action: index.next_action });
     const updatedRun = requireRunById(context, project.id, run.id);
-    return { ok: true, run: flowRunSummary(updatedRun), index, flow_guidance: guidanceForRun(context, updatedRun, index) };
+    return { ok: true, ...(control ? { control } : {}), run: flowRunSummary(updatedRun), index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
 /**
  * The only legal backward edge in vNext: an integration gate exposed a
@@ -762,7 +1239,11 @@ export function advanceFlowRun(context, input) {
 export function prepareVnextMergeSourceRepairAttempt(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
+    const priorRepair = index.variables?.["merge.source_repair"];
+    if (priorRepair?.merge_request_id === input.mergeRequestId && priorRepair.cycle)
+        return { run_id: run.id, cycle: priorRepair.cycle };
     const code = index.stage_runs.find((item) => item.stage === "code");
     const review = index.stage_runs.find((item) => item.stage === "code-review");
     const merge = index.stage_runs.find((item) => item.stage === "merge");
@@ -776,7 +1257,7 @@ export function prepareVnextMergeSourceRepairAttempt(context, input) {
     }
     const root = runArtifactRoot(run);
     for (const stage of ["code", "code-review", "merge"])
-        archiveExistingStageAttempt(root, vnextStageDirectory(stage));
+        archiveExistingStageAttempt(context, project.id, run.id, root, vnextStageDirectory(stage));
     const now = context.now();
     const restarted = {
         ...code,
@@ -811,18 +1292,24 @@ export function prepareVnextMergeSourceRepairAttempt(context, input) {
     }));
     persistRunState(context, project, run, index);
     appendAudit(context, { projectId: project.id, eventType: "flow_run.merge_source_repair_prepared", payload: { run_id: run.id, merge_request_id: input.mergeRequestId, cycle } });
-    appendRunTimeline(root, { at: now, type: "merge_source_repair_prepared", run_id: run.id, merge_request_id: input.mergeRequestId, cycle });
+    appendRunTimeline(context, project.id, run.id, { at: now, type: "merge_source_repair_prepared", run_id: run.id, merge_request_id: input.mergeRequestId, cycle });
     return { run_id: run.id, cycle };
 }
-function closeOpenStagesForOverride(index, status, now) {
+function closeOpenStagesForOverride(index, status, now, timingKnown = true) {
     const stageStatus = status === "cancelled" ? "skipped" : "failed";
     for (const stage of index.stage_runs) {
-        if (stage.status !== "running" && stage.status !== "pending" && stage.status !== "paused" && stage.status !== "blocked")
+        if (stage.status !== "running" && stage.status !== "paused" && stage.status !== "waiting_for_user" && stage.status !== "blocked")
             continue;
         stage.status = stageStatus;
         stage.updated_at = now;
-        stage.completed_at = now;
-        stage.duration_ms = durationMs(stage.started_at ?? null, now);
+        if (timingKnown) {
+            stage.completed_at = now;
+            stage.duration_ms = durationMs(stage.started_at ?? null, now);
+        }
+        else {
+            delete stage.completed_at;
+            stage.duration_ms = null;
+        }
     }
     index.attempts = index.stage_runs.map((stage) => ({
         stage: stage.stage,
@@ -830,20 +1317,20 @@ function closeOpenStagesForOverride(index, status, now) {
         root: stage.dir,
         archive: null,
         status: stage.status,
-        started_at: stage.started_at ?? now,
+        started_at: stage.started_at ?? null,
         finished_at: stage.completed_at ?? null
     }));
 }
-function closeOpenWorksForOverride(context, projectId, runId, status, now) {
+function closeOpenWorksForOverride(context, projectId, runId, status, now, timingKnown = true) {
     const workStatus = status === "cancelled" ? "cancelled" : "failed";
     context.db.run(`UPDATE works
-       SET status = ?, updated_at = ?, completed_at = ?
+       SET status = ?, updated_at = ?, completed_at = CASE WHEN ? = 1 THEN ? ELSE completed_at END
      WHERE project_id = ? AND run_id = ?
-       AND status IN ('created', 'running', 'paused')`, [workStatus, now, now, projectId, runId]);
+       AND status IN ('created', 'running', 'paused')`, [workStatus, now, timingKnown ? 1 : 0, now, projectId, runId]);
     context.db.run(`UPDATE work_sessions
-       SET status = ?, updated_at = ?, completed_at = ?
+       SET status = ?, updated_at = ?, completed_at = CASE WHEN ? = 1 THEN ? ELSE completed_at END
      WHERE work_id IN (SELECT work_id FROM works WHERE project_id = ? AND run_id = ?)
-       AND status <> 'completed'`, [workStatus, now, now, projectId, runId]);
+       AND status <> 'completed'`, [workStatus, now, timingKnown ? 1 : 0, now, projectId, runId]);
 }
 function closeRunOrchestrators(context, projectId, run, status, now) {
     if (!["done", "blocked", "cancelled", "failed"].includes(status))
@@ -860,7 +1347,7 @@ function closeRunOrchestrators(context, projectId, run, status, now) {
     context.db.run(`UPDATE flow_session_segments SET ended_at = ?
      WHERE project_id = ? AND run_id = ? AND session_id IN (${active.map(() => "?").join(", ")}) AND ended_at IS NULL`, [now, projectId, run.id, ...active.map((session) => session.session_id)]);
     for (const session of active) {
-        appendRunTimeline(runArtifactRoot(run), {
+        appendRunTimeline(context, projectId, run.id, {
             at: now,
             type: "session_stopped",
             run_id: run.id,
@@ -983,7 +1470,7 @@ export function getFlowRunSessions(context, input) {
 }
 export function appendFlowRunTimelineEvent(context, projectId, runId, event) {
     const run = requireRunById(context, projectId, runId);
-    appendRunTimeline(runArtifactRoot(run), { run_id: run.id, ...event });
+    appendRunTimeline(context, projectId, run.id, { run_id: run.id, ...event });
 }
 function guidanceForRun(context, run, index) {
     if (run.flow_kind === "vnext_specify")
@@ -1078,32 +1565,33 @@ function vnextSpecifyGuidance(run, index) {
     };
 }
 function persistRunState(context, project, run, index, options = {}) {
+    // Fenced productive admission is a logical pause, even while physical work
+    // drains. Late admitted Stage results must not revive a stopped RUN.
+    if (index.status === "running" && (!options.healthOnly || context.db.get("SELECT 1 FROM sqlite_schema WHERE name = 'run_recovery_guards'")) && ["draining", "sealed", "resuming"].includes(recoveryGuard(context, project.id, run.id)?.status ?? ""))
+        index.status = "paused";
+    if (!options.healthOnly)
+        delete index.health;
     const runtimePath = run.runtime_path || projectRunJsonPath(context.ddFlowHome, project.id, run.id);
-    const previousRuntime = readRuntimeSnapshot(runtimePath);
-    const runtimeRevision = Math.max(index.runtime_revision ?? 0, previousRuntime?.runtime_revision ?? 0) + 1;
-    index.runtime_revision = runtimeRevision;
-    const history = [...(previousRuntime?.flag_revision_history ?? [])];
-    if (options.flagRevision) {
-        history.push(options.flagRevision);
-    }
-    const persistedIndex = persistedVnextIndex(index);
-    ensureDir(path.dirname(runtimePath));
-    writeJsonFile(runtimePath, runtimeSnapshotForIndex(persistedIndex, runtimeRevision, history));
-    context.db.run(`UPDATE runs
-     SET status = ?, verdict = ?, next_action = ?, index_json = ?, runtime_path = ?, run_index_path = ?,
-       updated_at = ?, completed_at = ?
-     WHERE project_id = ? AND id = ?`, [
-        index.status,
-        index.verdict,
-        index.next_action,
-        JSON.stringify(persistedIndex),
-        runtimePath,
-        runtimePath,
-        index.updated_at,
-        index.completed_at ?? null,
-        project.id,
-        run.id
-    ]);
+    context.db.writeTransaction(() => {
+        const stored = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, run.id]);
+        if (!stored)
+            throw new AppError("not_found", "RUN is not registered", 1, { run_id: run.id });
+        const previous = JSON.parse(stored.index_json);
+        const actualRevision = previous.runtime_revision ?? 0;
+        const expectedRevision = index.runtime_revision ?? 0;
+        if (actualRevision !== expectedRevision)
+            throw new AppError("run_revision_changed", "RUN changed during preparation", 1, { run_id: run.id, expected_revision: expectedRevision, actual_revision: actualRevision });
+        index.runtime_revision = actualRevision + 1;
+        const history = [...(previous.flag_revision_history ?? [])];
+        if (options.flagRevision)
+            history.push(options.flagRevision);
+        index.flag_revision_history = history.slice(-32);
+        const updated = options.healthOnly ? context.db.run("UPDATE runs SET status = ?, verdict = ?, next_action = ?, index_json = ?, updated_at = ?, completed_at = ? WHERE project_id = ? AND id = ? AND index_json = ?", [index.status, index.verdict, index.next_action, JSON.stringify(persistedVnextIndex(index)), index.updated_at, index.completed_at ?? null, project.id, run.id, stored.index_json]) : context.db.run(`UPDATE runs SET status = ?, verdict = ?, next_action = ?, index_json = ?, runtime_path = ?, run_index_path = ?, updated_at = ?, completed_at = ?
+       WHERE project_id = ? AND id = ? AND index_json = ?`, [index.status, index.verdict, index.next_action, JSON.stringify(persistedVnextIndex(index)), runtimePath, runtimePath, index.updated_at, index.completed_at ?? null, project.id, run.id, stored.index_json]);
+        if (updated.changes !== 1)
+            throw new AppError("run_revision_changed", "RUN changed during preparation", 1, { run_id: run.id });
+        context.db.afterCommit(() => publishRunProjections(context, project.id, run.id));
+    }, "runs.persistRunState");
 }
 /** vNext stores derived stage/work state only once: stage_runs, Works and Sessions. */
 function persistedVnextIndex(index) {
@@ -1145,35 +1633,75 @@ function materializedRunVariables(index) {
         ...(index.variables ?? {})
     };
 }
-function setRunVariable(context, input, value) {
+function prepareRunVariable(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
+    return { project, run, index };
+}
+function setRunVariable(context, input, value, prepared = prepareRunVariable(context, input)) {
+    const { project, run, index } = prepared;
     if (index.variables?.[input.key] === value)
         return { ok: true, run_id: run.id, key: input.key, value, idempotent: true };
     index.variables = { ...(index.variables ?? {}), [input.key]: value };
     index.updated_at = context.now();
     persistRunState(context, project, run, index);
-    appendRunTimeline(runArtifactRoot(run), { at: index.updated_at, type: "run_variable_set", run_id: run.id, key: input.key });
+    appendRunTimeline(context, project.id, run.id, { at: index.updated_at, type: "run_variable_set", run_id: run.id, key: input.key });
     return { ok: true, run_id: run.id, key: input.key, value, idempotent: false };
 }
-function appendRunTimeline(runHome, event) {
-    ensureDir(runHome);
-    const timelinePath = path.join(runHome, "timeline.jsonl");
-    let sequence = 0;
-    if (fs.existsSync(timelinePath)) {
-        const lines = fs.readFileSync(timelinePath, "utf8").trim().split(/\r?\n/).filter(Boolean);
-        const last = lines.length > 0 ? JSON.parse(lines[lines.length - 1]) : undefined;
-        sequence = typeof last?.sequence === "number" ? last.sequence : lines.length;
-    }
-    const safeEvent = sanitizeTimelineValue(event);
-    const enriched = {
-        event_id: crypto.randomUUID(),
-        sequence: sequence + 1,
-        at: typeof safeEvent.at === "string" ? safeEvent.at : new Date().toISOString(),
-        ...safeEvent
-    };
-    fs.appendFileSync(timelinePath, `${JSON.stringify(enriched)}\n`);
+function appendRunTimeline(context, projectId, runId, event) {
+    context.db.writeTransaction(() => {
+        const last = context.db.get("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.timeline' AND json_extract(payload_json, '$.run_id') = ? ORDER BY id DESC LIMIT 1", [projectId, runId]);
+        const sequence = last ? Number(JSON.parse(last.payload_json).sequence) + 1 : 1;
+        const safeEvent = sanitizeTimelineValue(event);
+        const enriched = { event_id: crypto.randomUUID(), sequence, at: typeof safeEvent.at === "string" ? safeEvent.at : context.now(), ...safeEvent };
+        appendAudit(context, { projectId, eventType: "flow_run.timeline", payload: { run_id: runId, sequence, event: enriched } });
+        context.db.afterCommit(() => publishRunProjections(context, projectId, runId));
+    }, "runs.appendRunTimeline");
+}
+/** Rebuild projections from committed SQL after taking a per-RUN filesystem lock. */
+export function publishRunProjections(context, projectId, runId) {
+    const run = context.db.get("SELECT * FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!run)
+        throw new AppError("not_found", "RUN is not registered", 1, { run_id: runId });
+    const runtimePath = run.runtime_path || projectRunJsonPath(context.ddFlowHome, projectId, runId);
+    ensureDir(path.dirname(runtimePath));
+    withProjectionLock(`${runtimePath}.publish-lock`, () => {
+        // A delayed publisher must observe the latest commit after acquiring its lock.
+        const latest = context.db.get("SELECT * FROM runs WHERE project_id = ? AND id = ?", [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,
+            checksum: String(JSON.parse(row.result_json).snapshot_checksum ?? ""),
+            at: row.created_at,
+            idempotency_key: row.idempotency_key
+        }));
+        writeJsonFile(runtimePath, runtimeSnapshotForIndex(index, index.runtime_revision ?? 1, history.length ? history : index.flag_revision_history ?? []));
+        const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.timeline' AND json_extract(payload_json, '$.run_id') = ? ORDER BY id", [projectId, runId]);
+        if (latest.run_root) {
+            const timelinePath = path.join(latest.run_root, "timeline.jsonl");
+            ensureDir(path.dirname(timelinePath));
+            const bytes = rows.map((row) => JSON.stringify(JSON.parse(row.payload_json).event)).join("\n");
+            const temporary = `${timelinePath}.tmp-${process.pid}-${crypto.randomUUID()}`;
+            fs.writeFileSync(temporary, bytes ? `${bytes}\n` : "");
+            fs.renameSync(temporary, timelinePath);
+        }
+    });
 }
 function runtimeSnapshotForIndex(index, runtimeRevision, flagRevisionHistory = []) {
     const rest = { ...index };
@@ -1199,11 +1727,191 @@ function readRuntimeSnapshot(file) {
 function authoritativeIndex(run) {
     try {
         const state = JSON.parse(run.index_json);
-        return { ...state, schema_id: runSchemaId };
+        if (!state || typeof state !== "object" || Array.isArray(state) || !Array.isArray(state.stage_runs))
+            throw new Error("RUN index must contain stage_runs");
+        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("validation", "RUN mechanical state in SQLite is missing or invalid", 2, { run_id: run.id, cause: String(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 relocations = runContextRelocations(context, run.project_id, run.id);
+    const binding = relocations.length ? readRunEngineBinding(path.join(runArtifactRoot(run), "engine-binding.json")) : null;
+    const relocation = binding?.source === "fork_upgrade" ? { binding, relocations } : undefined;
+    const bundle = RetainedExecutionBundle.read(path.join(runArtifactRoot(run), "execution-bundle"), anchor.manifest_sha256, admission, relocation);
+    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)) {
@@ -1231,6 +1939,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;
@@ -1289,19 +2015,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,
@@ -1357,7 +2070,7 @@ function parseStageStatus(value) {
     }
     return value;
 }
-function requiredStageDir(value) {
+export function prepareStageDirectory(value) {
     const dir = requiredPlain(value, "dir");
     if (!/^\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(dir)) {
         throw new AppError("validation", "--dir must use NN-stage-slug format", 2, { dir });
@@ -1365,6 +2078,8 @@ function requiredStageDir(value) {
     return dir;
 }
 function requiredPlain(value, label) {
+    if (typeof value !== "string")
+        throw new AppError("validation", `${label} must be a string`, 2);
     const trimmed = value.trim();
     if (!trimmed) {
         throw new AppError("validation", `${label} must not be empty`, 2);
@@ -1372,6 +2087,8 @@ function requiredPlain(value, label) {
     return trimmed;
 }
 function normalizeSlug(value) {
+    if (typeof value !== "string")
+        throw new AppError("validation", "--slug must be a string", 2);
     const slug = value
         .normalize("NFKD")
         .replace(/[\u0300-\u036f]/g, "")
@@ -1389,26 +2106,84 @@ function resolveWorkspaceRoot(workspaceRoot) {
     if (!fs.existsSync(absolute)) {
         throw new AppError("not_found", `Workspace root does not exist: ${absolute}`, 1);
     }
+    if (!fs.statSync(absolute).isDirectory())
+        throw new AppError("validation", "Workspace root must be a directory", 2, { workspace_root: absolute });
     return fs.realpathSync(absolute);
 }
-function archiveExistingStageAttempt(runRoot, stageDir) {
+/** Move one completed stage attempt and update only known durable path columns.
+ * Receipt bytes remain immutable; readers resolve their new location through the DB. */
+export function archiveExistingStageAttempt(context, projectId, runId, runRoot, stageDir) {
     const currentStageDir = path.join(runRoot, stageDir);
     if (!fs.existsSync(currentStageDir) || !fs.statSync(currentStageDir).isDirectory()) {
         return;
     }
-    const entries = fs.readdirSync(currentStageDir).filter((entry) => !/^try-\d{3}$/.test(entry));
-    if (entries.length === 0) {
+    const journal = path.join(runRoot, `.archive-${stageDir}.json`);
+    const pending = fs.existsSync(journal) ? JSON.parse(fs.readFileSync(journal, "utf8")) : null;
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const prior = row ? JSON.parse(row.index_json) : null;
+    const live = prior?.stage_runs.find((stage) => stage.dir === stageDir);
+    const generation = row ? assertRunMutationAllowed(context, projectId, runId) : 0;
+    if (pending && (pending.project_id && pending.project_id !== projectId || pending.run_id && pending.run_id !== runId))
+        throw new AppError("archive_owner_changed", "Archive journal belongs to another RUN", 1, { journal });
+    if (pending?.generation !== undefined && pending.generation !== generation)
+        throw new AppError("archive_owner_changed", "RUN generation changed while an archive was pending", 1, { journal, expected_generation: pending.generation, generation });
+    if (pending?.prior_attempt && live?.attempt !== pending.prior_attempt && live?.attempt !== pending.next_attempt)
+        throw new AppError("archive_owner_changed", "Stage attempt changed while an archive was pending", 1, { journal, prior_attempt: pending.prior_attempt, actual_attempt: live?.attempt ?? null });
+    const entries = pending?.entries ?? fs.readdirSync(currentStageDir).filter((entry) => !/^try-\d{3}$/.test(entry));
+    if (entries.length === 0 && !pending) {
         return;
     }
     let attempt = 1;
     while (fs.existsSync(path.join(currentStageDir, `try-${String(attempt).padStart(3, "0")}`))) {
         attempt += 1;
     }
-    const archiveDir = path.join(currentStageDir, `try-${String(attempt).padStart(3, "0")}`);
+    const archiveDir = pending?.archiveDir ?? path.join(currentStageDir, `try-${String(attempt).padStart(3, "0")}`);
+    const intent = pending ?? { archiveDir, entries, stage_run: live ?? null, project_id: projectId, run_id: runId, prior_attempt: live?.attempt ?? null, next_attempt: nextAttempt(live), runtime_revision: prior?.runtime_revision ?? 0, generation };
+    if (!pending) {
+        writeJsonFile(journal, intent);
+    }
     ensureDir(archiveDir);
     for (const entry of entries) {
-        fs.renameSync(path.join(currentStageDir, entry), path.join(archiveDir, entry));
+        const source = path.join(currentStageDir, entry);
+        const target = path.join(archiveDir, entry);
+        if (fs.existsSync(source)) {
+            if (fs.existsSync(target))
+                throw new AppError("archive_conflict", "Both live and archived artifact exist; preserve both for recovery", 2, { source, target });
+            fs.renameSync(source, target);
+        }
+        else if (!fs.existsSync(target))
+            throw new AppError("archive_artifact_missing", "Artifact is absent from both archive locations", 2, { source, target });
     }
+    context.db.writeTransaction(() => {
+        const current = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+        const currentIndex = current ? JSON.parse(current.index_json) : null;
+        const currentAttempt = currentIndex?.stage_runs.find((stage) => stage.dir === stageDir)?.attempt;
+        if (currentIndex && intent.runtime_revision !== undefined && (currentIndex.runtime_revision ?? 0) !== intent.runtime_revision && currentAttempt !== intent.next_attempt)
+            throw new AppError("archive_owner_changed", "RUN revision changed while an archive was pending", 1, { journal });
+        if (intent.prior_attempt && currentAttempt !== intent.prior_attempt && currentAttempt !== intent.next_attempt)
+            throw new AppError("archive_owner_changed", "Stage attempt changed while an archive was pending", 1, { journal });
+        if (row && generation !== assertRunMutationAllowed(context, projectId, runId))
+            throw new AppError("archive_owner_changed", "RUN generation changed while an archive was pending", 1, { journal });
+        if (intent.next_attempt === undefined || currentAttempt !== intent.next_attempt) {
+            const oldPrefix = `${currentStageDir}${path.sep}`;
+            const newPrefix = `${archiveDir}${path.sep}`;
+            const rewrite = (table, column, where, values) => {
+                context.db.run(`UPDATE ${table} SET ${column} = ? || substr(${column}, ?) WHERE ${column} LIKE ? AND substr(${column}, ?, 4) != 'try-' AND ${where}`, [newPrefix, oldPrefix.length + 1, `${oldPrefix}%`, oldPrefix.length + 1, ...values]);
+            };
+            const workScope = "work_id IN (SELECT work_id FROM works WHERE project_id = ? AND run_id = ?)";
+            rewrite("work_sessions", "prompt_path", workScope, [projectId, runId]);
+            rewrite("work_sessions", "result_path", workScope, [projectId, runId]);
+            const receiptScope = "project_id = ? AND run_id = ?";
+            for (const column of ["stdout_path", "stderr_path", "receipt_path"])
+                rewrite("check_receipts", column, receiptScope, [projectId, runId]);
+        }
+        context.db.afterCommit(() => {
+            if (!fs.existsSync(journal))
+                return;
+            // Retain original Stage facts with the immutable attempt after SQL paths commit.
+            fs.renameSync(journal, path.join(archiveDir, "archive.json"));
+        });
+    });
 }
 function writeJsonFile(file, value) {
     const tmpFile = `${file}.tmp-${process.pid}-${Date.now()}`;
@@ -1433,3 +2208,5 @@ export function gitFacts(workspaceRoot) {
         status: status === null ? "unavailable" : status.length > 0 ? "dirty" : "clean"
     };
 }
+import { assertRunMutationAllowed, assertStageSettlementAllowed, recoveryGuard } from "./run-recovery.js";
+import { runControlDirective } from "./run-control.js";