@deksden-com/dd-flow-cli 0.9.0-beta.7 → 0.9.0-beta.74

package/dist/services/runs.js

@@ -5,7 +5,7 @@ import { spawnSync } from "node:child_process";
 import { formatFullId, 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 { 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";
@@ -15,8 +15,10 @@ 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 { isLegalVnextTransition, vnextStages } from "../domain/stage-catalog.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";
 const runSchemaId = "dd-flow/flow-run@3";
 const runtimeSchemaId = "dd-flow/flow-run@3";
 const runIdType = "RUN";
@@ -37,20 +39,22 @@ const allowedRunFlowKinds = [
 ];
 export function startFlowRun(context, input) {
     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) : 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 } : {}),
@@ -126,7 +130,9 @@ export function startFlowRun(context, input) {
     };
     ensureDir(path.dirname(runtimePath));
     ensureDir(runHome);
-    bindCurrentEngineToRun(context, { projectRoot, runId, runHome });
+    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
@@ -173,10 +179,10 @@ export function startFlowRun(context, input) {
     });
     return { ok: true, run: flowRunSummary(requireRunById(context, project.id, runId)), index };
 }
-function snapshotVnextExecutionProfile(projectRoot) {
+function snapshotVnextExecutionProfile(projectRoot, ddFlowHome, routingInput) {
     const profile = loadVnextExecutionProfile(projectRoot);
     const sourcePath = executionProfilePath(projectRoot);
-    return {
+    return freezeRunExecutionRouting(ddFlowHome, {
         schema_id: "dd-flow/run-execution-profile@1",
         source_path: sourcePath,
         source_checksum: crypto.createHash("sha256").update(fs.readFileSync(sourcePath)).digest("hex"),
@@ -188,9 +194,41 @@ function snapshotVnextExecutionProfile(projectRoot) {
             merge_delivery: profile.merge_delivery,
             merge_cleanup: profile.merge_cleanup,
             stop_target: profile.stop_target,
-            code_bootstrap: profile.code_bootstrap
+            code_bootstrap: profile.code_bootstrap,
+            ...(profile.execution ? { execution: profile.execution } : {})
         }
-    };
+    }, routingInput);
+}
+/** 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(run.run_root, { 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,6 +238,7 @@ function snapshotVnextExecutionProfile(projectRoot) {
 export function rebindFlowRunWorkspace(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
     const workspaceRoot = resolveWorkspaceRoot(input.workspaceRoot);
     const index = authoritativeIndex(run);
     const now = context.now();
@@ -229,7 +268,41 @@ export function getFlowRunStatus(context, input) {
     const run = resolveRun(context, project.id, input.runId);
     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), ...(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) {
+    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 (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, ...(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));
@@ -270,6 +343,7 @@ export function setFlowRunConfig(context, input) {
     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)) {
@@ -292,6 +366,23 @@ export function setFlowRunConfig(context, input) {
     appendRunTimeline(runArtifactRoot(run), { 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 };
 }
+/** 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";
+    const current = settings[key];
+    if (current.mode !== "auto")
+        return;
+    const now = context.now();
+    index.settings = { ...settings, [key]: { mode: input.mode, source: input.source, reason: requiredPlain(input.reason, "reason"), updated_at: now } };
+    index.updated_at = now;
+    persistRunState(context, project, run, index);
+    appendAudit(context, { projectId: project.id, eventType: "flow_run.review_mode_frozen", payload: { run_id: run.id, review: input.review, mode: input.mode, source: input.source, reason: input.reason } });
+}
 export function getFlowRunFlagsStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
@@ -321,8 +412,9 @@ export function getFlowRunFlagsStatus(context, input) {
 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");
+    context.db.beginWriteTransaction();
     let committed = false;
     try {
         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]);
@@ -446,6 +538,7 @@ export function listFlowRuns(context, input) {
 export function attachFlowRunStage(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 now = context.now();
     const stage = requiredPlain(input.stage, "stage");
@@ -454,7 +547,7 @@ export function attachFlowRunStage(context, input) {
     const existing = index.stage_runs.find((item) => item.stage === stage);
     assertVnextStageStart(run, index, stage, status, existing);
     if (status === "running" && existing) {
-        archiveExistingStageAttempt(runArtifactRoot(run), dir);
+        archiveExistingStageAttempt(context, project.id, run.id, runArtifactRoot(run), dir);
     }
     const stageRun = {
         ...(existing ?? { order: index.stage_runs.length + 1 }),
@@ -490,9 +583,17 @@ export function attachFlowRunStage(context, input) {
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), stage_run: stageRun, index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
+/** Keep synchronous stage settlement atomic; files are projections, SQLite is authoritative. */
+export function withStageSettlement(context, operation) {
+    return context.db.writeTransaction(operation);
+}
 export function completeFlowRunStage(context, input) {
     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");
@@ -508,6 +609,7 @@ export function completeFlowRunStage(context, input) {
         ...(input.data ? { data: input.data } : {}),
         ...(input.dataSchemaId ? { data_schema_id: input.dataSchemaId } : {}),
         ...(input.report ? { report: input.report } : {}),
+        ...(input.usage ? { usage: input.usage } : {}),
         ...(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"
@@ -550,6 +652,7 @@ export function completeFlowRunStage(context, input) {
 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);
@@ -585,6 +688,7 @@ export function pauseFlowRunStage(context, input) {
 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);
@@ -616,6 +720,7 @@ export function resumeFlowRunStage(context, input) {
 export function blockFlowRunStage(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);
@@ -641,6 +746,7 @@ export function blockFlowRunStage(context, input) {
 export function unblockFlowRunStage(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);
@@ -671,9 +777,26 @@ 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";
 }
+/** 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);
+}
 export function completeFlowRun(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    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);
@@ -727,16 +850,85 @@ 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(runArtifactRoot(run), { 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
+ * product defect, so the source must be repaired and reviewed again.  Normal
+ * stage start remains fail-closed for completed stages.
+ */
+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");
+    if (!code || code.status !== "done" || !review || review.status !== "done" || !merge || merge.status !== "running") {
+        throw new AppError("invalid_merge_repair_state", "Source repair requires accepted CODE/CODE-REVIEW and a running MERGE attempt", 2, {
+            run_id: run.id,
+            code: code?.status ?? null,
+            code_review: review?.status ?? null,
+            merge: merge?.status ?? null
+        });
+    }
+    const root = runArtifactRoot(run);
+    for (const stage of ["code", "code-review", "merge"])
+        archiveExistingStageAttempt(context, project.id, run.id, root, vnextStageDirectory(stage));
+    const now = context.now();
+    const restarted = {
+        ...code,
+        status: "running",
+        started_at: now,
+        updated_at: now,
+        attempt: nextAttempt(code)
+    };
+    delete restarted.completed_at;
+    delete restarted.duration_ms;
+    delete restarted.stage_report;
+    delete restarted.data;
+    delete restarted.report;
+    delete restarted.artifact_aliases;
+    const cycle = `MRR-${input.mergeRequestId}`;
+    index.stage_runs = index.stage_runs.filter((item) => item.stage !== "code" && item.stage !== "code-review" && item.stage !== "merge");
+    index.stage_runs.push(restarted);
+    index.variables = { ...(index.variables ?? {}), "merge.source_repair": { cycle, merge_request_id: input.mergeRequestId, prepared_at: now } };
+    index.status = "running";
+    index.verdict = "merge_source_repair";
+    index.next_action = "start_code_repair";
+    index.current_stage = "code";
+    index.updated_at = now;
+    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
+    }));
+    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 });
+    return { run_id: run.id, cycle };
 }
 function closeOpenStagesForOverride(index, status, now) {
     const stageStatus = status === "cancelled" ? "skipped" : "failed";
@@ -1002,6 +1194,10 @@ 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" && ["draining", "sealed", "resuming"].includes(recoveryGuard(context, project.id, run.id)?.status ?? ""))
+        index.status = "paused";
     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;
@@ -1012,22 +1208,30 @@ function persistRunState(context, project, run, index, options = {}) {
     }
     const persistedIndex = persistedVnextIndex(index);
     ensureDir(path.dirname(runtimePath));
-    writeJsonFile(runtimePath, runtimeSnapshotForIndex(persistedIndex, runtimeRevision, history));
-    context.db.run(`UPDATE runs
+    context.db.exec("SAVEPOINT persist_run_state");
+    try {
+        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
-    ]);
+            index.status,
+            index.verdict,
+            index.next_action,
+            JSON.stringify(persistedIndex),
+            runtimePath,
+            runtimePath,
+            index.updated_at,
+            index.completed_at ?? null,
+            project.id,
+            run.id
+        ]);
+        writeJsonFile(runtimePath, runtimeSnapshotForIndex(persistedIndex, runtimeRevision, history));
+        context.db.exec("RELEASE persist_run_state");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK TO persist_run_state; RELEASE persist_run_state");
+        throw error;
+    }
 }
 /** vNext stores derived stage/work state only once: stage_runs, Works and Sessions. */
 function persistedVnextIndex(index) {
@@ -1072,6 +1276,7 @@ function materializedRunVariables(index) {
 function setRunVariable(context, input, value) {
     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);
     if (index.variables?.[input.key] === value)
         return { ok: true, run_id: run.id, key: input.key, value, idempotent: true };
@@ -1187,7 +1392,7 @@ function upsertStage(index, stageRun) {
     }
     index.stage_runs.sort((a, b) => a.order - b.order);
 }
-function resolveRun(context, projectId, idOrAlias) {
+export function resolveRun(context, projectId, idOrAlias) {
     if (isFullEntityId(idOrAlias)) {
         return requireRunById(context, projectId, idOrAlias);
     }
@@ -1245,7 +1450,7 @@ function flowRunSummary(run) {
         runtime_path: run.runtime_path,
         run_dir: run.run_dir,
         run_index_path: run.run_index_path,
-        run_home_path: run.run_home_path ?? null,
+        run_root: run.run_root,
         layout_version: run.layout_version ?? null,
         artifact_root_kind: run.artifact_root_kind ?? null,
         created_at: run.created_at,
@@ -1315,24 +1520,55 @@ function resolveWorkspaceRoot(workspaceRoot) {
     }
     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 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")}`);
+    if (!pending) {
+        const stored = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+        const prior = stored ? JSON.parse(stored.index_json) : null;
+        writeJsonFile(journal, { archiveDir, entries, stage_run: prior?.stage_runs.find((stage) => stage.dir === stageDir) ?? null });
+    }
     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 });
     }
+    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]);
+    // Retain the original stage facts with its immutable artifacts; current
+    // stage_runs stays a projection of the current attempt, not a second ledger.
+    fs.renameSync(journal, path.join(archiveDir, "archive.json"));
 }
 function writeJsonFile(file, value) {
     const tmpFile = `${file}.tmp-${process.pid}-${Date.now()}`;
@@ -1340,7 +1576,9 @@ function writeJsonFile(file, value) {
     fs.renameSync(tmpFile, file);
 }
 function runArtifactRoot(run) {
-    return run.run_home_path ?? path.dirname(run.runtime_path);
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1, { run_id: run.id });
+    return run.run_root;
 }
 export function gitFacts(workspaceRoot) {
     const read = (args) => {
@@ -1355,3 +1593,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";