@deksden-com/dd-flow-cli 0.9.0-beta.63 → 0.9.0-beta.64

package/dist/services/run-controller.js

@@ -1,10 +1,10 @@
-import { managedInvocationContext, managedLifecycleCommand } from "./lifecycle-invocations.js";
+import { assertLifecycleOutcomes, managedInvocationContext, managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
-import { ensureRunControllerStorage } from "../storage/database.js";
+import { ensureRunControllerStorage, getDatabase } from "../storage/database.js";
 import { canonicalPath, resolveProjectRoot } from "../storage/paths.js";
 import { AppError } from "../shared/errors.js";
 import { parseRuntimeBudget } from "./runtime-budget.js";
@@ -27,6 +27,7 @@ import { spawnController, recordControllerLauncher, claimControllerProcess, mark
 import { controllerAdapter, controllerEnvironment, sessionArguments } from "./run-controller-adapter.js";
 import { resumeControllerSession, failControllerRecovery } from "./run-controller-recovery.js";
 import { captureControllerBoundary } from "./run-controller-capture.js";
+import { requestRunControl } from "./run-control-worker.js";
 export { resumeRunController } from "./run-controller-recovery.js";
 /** Persist intent before spawning. A repeated client observes the same owner. */
 export async function launchRunController(context, input) {
@@ -86,7 +87,7 @@ export async function launchRunController(context, input) {
     const token = crypto.randomUUID();
     const now = context.now();
     const state = { stage: null, sessions: [], current_session: null, turns: 0, last_continuation: null };
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
         const duplicate = context.db.get("SELECT * FROM run_controllers WHERE project_id = ? AND run_id = ? AND request_id = ?", [project.id, run.id, input.requestId]);
         if (duplicate) {
@@ -201,6 +202,10 @@ export async function serveRunController(context, input) {
             throw new AppError("controller_owner_mismatch", "Controller no longer owns productive dispatch", 1);
     };
     const assertOwner = () => { assertPhysicalOwner(); assertRunMutationAllowed(context, row.project_id, row.run_id, row.generation); };
+    let primaryFailure;
+    const retainSecondary = (phase, error) => {
+        process.stderr.write(`${JSON.stringify({ controller_id: row.controller_id, phase, primary: errorRecord(primaryFailure), secondary: errorRecord(error) })}\n`);
+    };
     try {
         context.db.exec("SAVEPOINT controller_ready_status");
         try {
@@ -220,37 +225,65 @@ export async function serveRunController(context, input) {
         return controllerReceipt(requireController(context, row.controller_id));
     }
     catch (error) {
-        failControllerRecovery(context, row, state, error);
-        if ((error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale"].includes(error.code) || (recoveryGuard(context, row.project_id, row.run_id)?.generation ?? 0) !== row.generation)
-            && context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controls'")) {
-            const guard = recoveryGuard(context, row.project_id, row.run_id);
-            const control = guard && ["draining", "sealed"].includes(guard.status) && context.db.get("SELECT control_id, action FROM run_controls WHERE project_id = ? AND run_id = ? AND recovery_id = ? AND status IN ('requested','settled')", [row.project_id, row.run_id, guard.recovery_id]);
-            if (control) {
-                context.db.run("UPDATE run_controllers SET status = 'control_requested', last_error_json = NULL, updated_at = ? WHERE controller_id = ? AND owner_token = ?", [context.now(), row.controller_id, row.owner_token]);
-                appendEvent(context, row.controller_id, "control_boundary_reached", { control_id: control.control_id, action: control.action, generation: guard.generation, settled: false });
-                return controllerReceipt(requireController(context, row.controller_id));
-            }
-        }
-        context.db.exec("SAVEPOINT controller_failure_status");
+        primaryFailure = error;
         try {
-            // A failed capture must not reopen admission when this process exits.
-            const changed = context.db.run("UPDATE run_controllers SET status = CASE WHEN status IN ('capturing','capture_failed') THEN 'capture_failed' ELSE 'recovery_required' END, last_error_json = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ? AND status NOT IN ('completed','cancelled','superseded')", [JSON.stringify(errorRecord(error)), context.now(), row.controller_id, row.owner_token]);
-            context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE project_id = ? AND run_id = ? AND dispatch_owner = ? AND status IN ('dispatching','active')", [JSON.stringify(errorRecord(error)), context.now(), row.project_id, row.run_id, row.controller_id]);
-            if (changed.changes && (recoveryGuard(context, row.project_id, row.run_id)?.generation ?? 0) === row.generation) {
-                setFlowRunRecoveryPaused(context, row.project_id, row.run_id, true);
+            try {
+                failControllerRecovery(context, row, state, error);
+            }
+            catch (secondary) {
+                retainSecondary("fail_controller_recovery", secondary);
+            }
+            if ((error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale"].includes(error.code) || (recoveryGuard(context, row.project_id, row.run_id)?.generation ?? 0) !== row.generation)
+                && context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controls'")) {
+                const guard = recoveryGuard(context, row.project_id, row.run_id);
+                const control = guard && ["draining", "sealed"].includes(guard.status) && context.db.get("SELECT control_id, action FROM run_controls WHERE project_id = ? AND run_id = ? AND recovery_id = ? AND status IN ('requested','settled')", [row.project_id, row.run_id, guard.recovery_id]);
+                if (control) {
+                    // Control is a later state transition, not evidence that the causal
+                    // failure which fenced admission disappeared.
+                    context.db.run("UPDATE run_controllers SET status = CASE WHEN last_error_json IS NULL THEN 'control_requested' ELSE status END, updated_at = ? WHERE controller_id = ? AND owner_token = ?", [context.now(), row.controller_id, row.owner_token]);
+                    appendEvent(context, row.controller_id, "control_boundary_reached", { control_id: control.control_id, action: control.action, generation: guard.generation, settled: false });
+                    return controllerReceipt(requireController(context, row.controller_id));
+                }
+            }
+            context.db.exec("SAVEPOINT controller_failure_status");
+            try {
+                // A failed capture must not reopen admission when this process exits.
+                const changed = context.db.run("UPDATE run_controllers SET status = CASE WHEN status IN ('capturing','capture_failed') THEN 'capture_failed' ELSE 'recovery_required' END, last_error_json = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ? AND status NOT IN ('completed','cancelled','superseded')", [JSON.stringify(errorRecord(error)), context.now(), row.controller_id, row.owner_token]);
+                context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE project_id = ? AND run_id = ? AND dispatch_owner = ? AND status IN ('dispatching','active')", [JSON.stringify(errorRecord(error)), context.now(), row.project_id, row.run_id, row.controller_id]);
+                if (changed.changes && (recoveryGuard(context, row.project_id, row.run_id)?.generation ?? 0) === row.generation) {
+                    setFlowRunRecoveryPaused(context, row.project_id, row.run_id, true);
+                }
+                appendEvent(context, row.controller_id, "recovery_required", errorRecord(error));
+                context.db.exec("RELEASE controller_failure_status");
+            }
+            catch (failure) {
+                retainSecondary("persist_controller_failure", failure);
+                try {
+                    context.db.exec("ROLLBACK TO controller_failure_status; RELEASE controller_failure_status");
+                }
+                catch (rollback) {
+                    retainSecondary("rollback_controller_failure", rollback);
+                }
             }
-            appendEvent(context, row.controller_id, "recovery_required", errorRecord(error));
-            context.db.exec("RELEASE controller_failure_status");
         }
-        catch (failure) {
-            context.db.exec("ROLLBACK TO controller_failure_status; RELEASE controller_failure_status");
-            throw failure;
+        catch (secondary) {
+            retainSecondary("controller_failure_boundary", secondary);
         }
         throw error;
     }
     finally {
         clearInterval(heartbeat);
-        finishManagedProcess(context, { id: row.process_id, leaseToken: row.process_lease_token, state: "stopped", reason: "controller_owner_exited" });
+        finishOwner();
+    }
+    function finishOwner() {
+        try {
+            finishManagedProcess(context, { id: row.process_id, leaseToken: row.process_lease_token, state: "stopped", reason: "controller_owner_exited" });
+        }
+        catch (cleanup) {
+            if (!primaryFailure)
+                throw cleanup;
+            retainSecondary("finish_controller_process", cleanup);
+        }
     }
 }
 /** Public HITL input: persist raw bytes, never deliver a turn from this client. */
@@ -267,7 +300,7 @@ export function answerRunController(context, input) {
     const operationId = `${row.controller_id}:answer:${input.requestId}`;
     const answerHash = digestBytes(bytes);
     const hash = digest({ pause_id: input.pauseId, answer_sha256: answerHash });
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
         const prior = context.db.get("SELECT input_hash, status FROM run_controller_operations WHERE operation_id = ?", [operationId]);
         if (prior) {
@@ -319,7 +352,7 @@ export function supplyRunControllerContext(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const operationId = `${input.controllerId}:context:${input.requestId}`;
     const hash = digest({ stage: input.stage, sha256: input.contextSha256 });
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
         const row = requireController(context, input.controllerId);
         if (row.project_id !== project.id || row.run_id !== input.runId)
@@ -364,7 +397,12 @@ export function supplyRunControllerContext(context, input) {
         throw error;
     }
 }
-async function executeController(context, row, manifest, state, assertOwner, assertPhysicalOwner) {
+async function executeController(context, row, manifest, state, assertOwnership, assertPhysicalOwner) {
+    assertOwnership();
+    const observer = { ...context, db: getDatabase(context.ddFlowHome, "read_existing") };
+    const checkOutcomes = () => assertLifecycleOutcomes(observer, { projectRoot: manifest.request.project_root, runId: row.run_id, generation: row.generation });
+    const assertOwner = () => { if (fatal)
+        throw fatal; checkOutcomes(); assertOwnership(); };
     const policy = manifest.execution_profile.settings.execution;
     const profiles = manifest.execution_profile.agent_profiles;
     let executionContext = { ...context, env: { ...context.env, DD_FLOW_BIN: manifest.flow_executable, DD_FLOW_RESOURCE_HOME: manifest.resource_home, DD_FLOW_RUNTIME_BUDGET: manifest.budget ? JSON.stringify(manifest.budget) : undefined } };
@@ -373,12 +411,40 @@ async function executeController(context, row, manifest, state, assertOwner, ass
             projectRoot: manifest.request.project_root, runId: row.run_id, generation: row.generation });
     };
     let lastCapture = null;
+    let fatal;
+    let stopping;
+    const cancellation = new AbortController();
+    const stopAfterFailure = (error) => {
+        if (stopping)
+            return stopping;
+        fatal = error;
+        // Persist the cause before fencing/cancellation; later control is not an
+        // operator pause and cannot replace this execution failure.
+        stopping = (async () => {
+            try {
+                context.db.run("UPDATE run_controllers SET status = CASE WHEN status IN ('capturing','capture_failed') THEN 'capture_failed' ELSE 'recovery_required' END, last_error_json = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ?", [JSON.stringify(errorRecord(error)), context.now(), row.controller_id, row.owner_token]);
+            }
+            catch (persistence) {
+                process.stderr.write(`${JSON.stringify({ primary: errorRecord(error), persistence: errorRecord(persistence) })}\n`);
+            }
+            await requestRunControl(executionContext, { projectRoot: manifest.request.project_root, runId: row.run_id, requestId: `fatal:${row.controller_id}:${row.generation}`, action: "stop", waitMs: 0 });
+        })().catch(cleanup => {
+            // The caller still receives the primary failure if control cannot start.
+            try {
+                appendEvent(context, row.controller_id, "failure_control_error", { primary: errorRecord(error), cleanup: errorRecord(cleanup) });
+            }
+            catch {
+                process.stderr.write(`${JSON.stringify({ primary: errorRecord(error), cleanup: errorRecord(cleanup) })}\n`);
+            }
+        }).finally(() => cancellation.abort());
+        return stopping;
+    };
     const setStatus = (status) => {
         const changed = context.db.run("UPDATE run_controllers SET status = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ? AND status <> ?", [status, context.now(), row.controller_id, row.owner_token, status]);
         if (changed.changes)
             appendEvent(context, row.controller_id, "status_changed", { status, stage: state.stage });
     };
-    const call = (session, args, productive = true) => controllerAdapter(executionContext, row, manifest, session, args, productive ? assertOwner : undefined);
+    const call = (session, args, productive = true) => controllerAdapter(executionContext, row, manifest, session, args, productive ? assertOwner : undefined, undefined, productive ? cancellation.signal : undefined);
     const confirmStopped = async (stateDir, receipt) => {
         const fail = () => new AppError("controller_native_shutdown_unproven", "The managed daemon is not proven clean and closed", 1, { state_dir: stateDir, receipt });
         if (receipt.stopped !== true || receipt.clean !== true)
@@ -413,178 +479,229 @@ async function executeController(context, row, manifest, state, assertOwner, ass
         fs.writeFileSync(file, `${text}\n`, { flag: "wx", mode: 0o600 });
         state.turns += 1;
         saveState(context, row, state);
-        const receipt = await controllerAdapter(executionContext, row, manifest, session, ["session", "prompt", "--session-id", session.id, "--prompt-file", file, ...sessionArguments(context, manifest, session)], assertOwner, operationId);
+        let receipt;
+        try {
+            const adapter = controllerAdapter(executionContext, row, manifest, session, ["session", "prompt", "--session-id", session.id, "--prompt-file", file, ...sessionArguments(context, manifest, session)], assertOwner, operationId, cancellation.signal);
+            try {
+                receipt = await adapter;
+                checkOutcomes();
+                if (fatal)
+                    throw fatal;
+            }
+            catch (error) {
+                if (!fatal && error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale", "controller_owner_mismatch"].includes(error.code))
+                    throw error;
+                await stopAfterFailure(error);
+                cancellation.abort();
+                await adapter.catch(() => { });
+                throw fatal ?? error;
+            }
+        }
+        finally { /* Adapter settlement is joined before returning. */ }
         state.last_receipt = receipt;
         saveState(context, row, state);
         return receipt;
     };
-    for (;;) {
-        assertOwner();
-        if (state.current_session !== null && !state.sessions[state.current_session].stopped)
-            bindInvocationScope(state.sessions[state.current_session]);
-        const run = requireRun(context, row.project_id, row.run_id);
-        const view = getFlowRunStatus(executionContext, { projectRoot: run.project_root, runId: run.id });
-        const next = view.continuation;
-        const completed = state.stage && view.index.stage_runs.find(stage => stage.stage === state.stage && ["done", "skipped"].includes(stage.status));
-        if (completed && manifest.request.capture_root && ["start_stage", "terminal"].includes(next.kind)) {
-            const key = JSON.stringify([completed.stage, completed.attempt, completed.started_at, completed.completed_at]);
-            if (key !== lastCapture) {
-                await captureControllerBoundary(executionContext, row, manifest, completed, next.kind === "start_stage" ? next.stage : null, assertPhysicalOwner);
-                lastCapture = key;
-            }
-        }
-        if (completed && manifest.request.stop_after === state.stage) {
-            await settle();
-            setStatus("stop_target_reached");
-            appendEvent(context, row.controller_id, "stop_target_reached", { stage: state.stage, attempt: completed.attempt ?? null });
+    const monitor = setInterval(() => {
+        if (fatal)
             return;
+        try {
+            checkOutcomes();
         }
-        if (next.kind === "terminal") {
-            await settle();
-            setStatus(run.status === "cancelled" ? "cancelled" : "completed");
-            appendEvent(context, row.controller_id, "terminal", { reason: next.reason });
-            return;
+        catch (error) {
+            void stopAfterFailure(error);
         }
-        if (next.kind === "paused") {
-            setStatus("waiting_for_user");
-            const pause = view.index.stage_runs.find(stage => stage.stage === next.stage)?.pause;
-            if (!pause || state.current_session === null)
-                throw new AppError("controller_hitl_missing", "Paused RUN has no managed Session or HITL receipt", 1);
-            const answer = context.db.get("SELECT operation_id, input_json FROM run_controller_operations WHERE controller_id = ? AND status = 'accepted' AND json_extract(input_json, '$.action') = 'user_answer' AND json_extract(input_json, '$.pause_id') = ? ORDER BY created_at LIMIT 1", [row.controller_id, pause.id]);
-            if (!answer) {
-                await delay(1000);
-                continue;
-            }
-            const input = JSON.parse(answer.input_json);
-            if (digestBytes(fs.readFileSync(input.file)) !== input.sha256)
-                throw new AppError("context_checksum_mismatch", "Accepted HITL answer bytes changed", 1);
+    }, 1000);
+    monitor.unref();
+    try {
+        for (;;) {
             assertOwner();
-            // The accepted answer is logical intent; only its generation-bound
-            // adapter operation represents a physical dispatch that stop must drain.
-            const command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage resume ${run.id} --stage ${next.stage} --work ${input.work_id} --project-root ${JSON.stringify(run.project_root)} --answer-stdin --json < ${JSON.stringify(input.file)}`);
-            const receipt = await prompt(state.sessions[state.current_session], `The user supplied the raw answer for pause ${pause.id}. Your first tool call must be this exact standalone command:\n\n${command}\n\nDo not alter the answer. Follow the returned packet, then stop at this Stage boundary.`, `${answer.operation_id}:prompt:${row.generation}`);
-            context.db.run("UPDATE run_controller_operations SET status = 'completed', receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify({ delivered: true, session_id: adapterSessionId(receipt) }), context.now(), answer.operation_id]);
-            state.last_continuation = null;
-            saveState(context, row, state);
-            setStatus("running");
-            continue;
-        }
-        if (next.kind === "blocked" || next.kind === "wait" || !next.stage)
-            throw new AppError("controller_continuation_blocked", "RUN has no legal managed continuation", 1, { continuation: next });
-        if (next.kind === "start_stage") {
-            // Only context slices can be added; profiles and launch inputs stay frozen.
-            manifest.contexts = JSON.parse(requireController(context, row.controller_id).manifest_json).contexts;
-            const stageContext = manifest.contexts[next.stage];
-            if (!stageContext) {
-                if (requireController(context, row.controller_id).status !== "waiting_for_context")
-                    appendEvent(context, row.controller_id, "context_required", { stage: next.stage, attempt: next.attempt ?? null });
-                setStatus("waiting_for_context");
-                await delay(1000);
-                continue;
+            if (state.current_session !== null && !state.sessions[state.current_session].stopped)
+                bindInvocationScope(state.sessions[state.current_session]);
+            const run = requireRun(context, row.project_id, row.run_id);
+            const view = getFlowRunStatus(executionContext, { projectRoot: run.project_root, runId: run.id });
+            const next = view.continuation;
+            const completed = state.stage && view.index.stage_runs.find(stage => stage.stage === state.stage && ["done", "skipped"].includes(stage.status));
+            if (completed && manifest.request.capture_root && ["start_stage", "terminal"].includes(next.kind)) {
+                const key = JSON.stringify([completed.stage, completed.attempt, completed.started_at, completed.completed_at]);
+                if (key !== lastCapture) {
+                    await captureControllerBoundary(executionContext, row, manifest, completed, next.kind === "start_stage" ? next.stage : null, assertPhysicalOwner);
+                    lastCapture = key;
+                }
             }
-            loadExternalStageContext({ file: stageContext.file, expectedSha256: stageContext.sha256, stage: next.stage });
-            const transition = resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy, profiles, ...(state.stage ? { fromStage: state.stage } : {}), stage: next.stage, stageSessionMode: manifest.execution_profile.settings.stage_session_mode, mergeMode: manifest.execution_profile.settings.merge_mode });
-            if (next.stage === "merge" && manifest.execution_profile.settings.merge_mode === "server" && !state.merge_claim) {
-                const request = context.db.get("SELECT merge_request_id, status FROM merge_requests WHERE project_id = ? AND run_id = ? ORDER BY created_at DESC, merge_request_id DESC LIMIT 1", [row.project_id, row.run_id]);
-                if (!request || request.status !== "queued")
-                    throw new AppError("controller_attach_required", "Managed MERGE needs an unclaimed queued request; reconcile an existing owner", 1, { request });
-                const claim = claimQueuedMergeRequest(context, { requestId: request.merge_request_id, ownerId: row.controller_id, expectedGeneration: row.generation });
-                if (!claim) {
-                    setStatus("waiting_for_merge");
+            if (completed && manifest.request.stop_after === state.stage) {
+                await settle();
+                setStatus("stop_target_reached");
+                appendEvent(context, row.controller_id, "stop_target_reached", { stage: state.stage, attempt: completed.attempt ?? null });
+                return;
+            }
+            if (next.kind === "terminal") {
+                await settle();
+                setStatus(run.status === "cancelled" ? "cancelled" : "completed");
+                appendEvent(context, row.controller_id, "terminal", { reason: next.reason });
+                return;
+            }
+            if (next.kind === "paused") {
+                setStatus("waiting_for_user");
+                const pause = view.index.stage_runs.find(stage => stage.stage === next.stage)?.pause;
+                if (!pause || state.current_session === null)
+                    throw new AppError("controller_hitl_missing", "Paused RUN has no managed Session or HITL receipt", 1);
+                const answer = context.db.get("SELECT operation_id, input_json FROM run_controller_operations WHERE controller_id = ? AND status = 'accepted' AND json_extract(input_json, '$.action') = 'user_answer' AND json_extract(input_json, '$.pause_id') = ? ORDER BY created_at LIMIT 1", [row.controller_id, pause.id]);
+                if (!answer) {
                     await delay(1000);
                     continue;
                 }
-                state.merge_claim = { request_id: claim.request.merge_request_id, token: claim.token, target_workspace: claim.request.target_workspace, work_id: claim.request.executor_work_id };
+                const input = JSON.parse(answer.input_json);
+                if (digestBytes(fs.readFileSync(input.file)) !== input.sha256)
+                    throw new AppError("context_checksum_mismatch", "Accepted HITL answer bytes changed", 1);
+                assertOwner();
+                // The accepted answer is logical intent; only its generation-bound
+                // adapter operation represents a physical dispatch that stop must drain.
+                const command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage resume ${run.id} --stage ${next.stage} --work ${input.work_id} --project-root ${JSON.stringify(run.project_root)} --answer-stdin --json < ${JSON.stringify(input.file)}`);
+                const receipt = await prompt(state.sessions[state.current_session], `The user supplied the raw answer for pause ${pause.id}. Your first tool call must be this exact standalone command:\n\n${command}\n\nDo not alter the answer. Follow the returned packet, then stop at this Stage boundary.`, `${answer.operation_id}:prompt:${row.generation}`);
+                context.db.run("UPDATE run_controller_operations SET status = 'completed', receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify({ delivered: true, session_id: adapterSessionId(receipt) }), context.now(), answer.operation_id]);
+                state.last_continuation = null;
                 saveState(context, row, state);
-                appendEvent(context, row.controller_id, "merge_claimed", { request_id: claim.request.merge_request_id });
+                setStatus("running");
+                continue;
             }
-            let session = state.current_session === null ? null : state.sessions[state.current_session];
-            if (!session || transition.session_mode === "new_session" || !sameSessionProfile(session.profile, transition.coordinator)) {
-                if (session)
-                    await stopSession(session);
-                assertOwner();
-                const directory = path.join(row.state_dir, `session-${state.sessions.length + 1}`);
-                fs.mkdirSync(directory, { mode: 0o700 });
-                const owner = { schema_id: "dd-flow/runtime-owner@1", owner_id: row.controller_id, role: "subject", project_id: row.project_id, run_id: row.run_id, operation_id: `${row.controller_id}:session:${state.sessions.length + 1}`, state_dir: directory, dd_flow_home: context.ddFlowHome, dd_flow_bin: manifest.flow_executable, resource_home: manifest.resource_home, budget: manifest.budget };
-                if (next.stage === "merge" && state.merge_claim) {
-                    owner.role = "merge";
-                    owner.work_id = state.merge_claim.work_id;
+            if (next.kind === "blocked" || next.kind === "wait" || !next.stage)
+                throw new AppError("controller_continuation_blocked", "RUN has no legal managed continuation", 1, { continuation: next });
+            if (next.kind === "start_stage") {
+                // Only context slices can be added; profiles and launch inputs stay frozen.
+                manifest.contexts = JSON.parse(requireController(context, row.controller_id).manifest_json).contexts;
+                const stageContext = manifest.contexts[next.stage];
+                if (!stageContext) {
+                    if (requireController(context, row.controller_id).status !== "waiting_for_context")
+                        appendEvent(context, row.controller_id, "context_required", { stage: next.stage, attempt: next.attempt ?? null });
+                    setStatus("waiting_for_context");
+                    await delay(1000);
+                    continue;
+                }
+                loadExternalStageContext({ file: stageContext.file, expectedSha256: stageContext.sha256, stage: next.stage });
+                const transition = resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy, profiles, ...(state.stage ? { fromStage: state.stage } : {}), stage: next.stage, stageSessionMode: manifest.execution_profile.settings.stage_session_mode, mergeMode: manifest.execution_profile.settings.merge_mode });
+                if (next.stage === "merge" && manifest.execution_profile.settings.merge_mode === "server" && !state.merge_claim) {
+                    const request = context.db.get("SELECT merge_request_id, status FROM merge_requests WHERE project_id = ? AND run_id = ? ORDER BY created_at DESC, merge_request_id DESC LIMIT 1", [row.project_id, row.run_id]);
+                    if (!request || request.status !== "queued")
+                        throw new AppError("controller_attach_required", "Managed MERGE needs an unclaimed queued request; reconcile an existing owner", 1, { request });
+                    const claim = claimQueuedMergeRequest(context, { requestId: request.merge_request_id, ownerId: row.controller_id, expectedGeneration: row.generation });
+                    if (!claim) {
+                        setStatus("waiting_for_merge");
+                        await delay(1000);
+                        continue;
+                    }
+                    state.merge_claim = { request_id: claim.request.merge_request_id, token: claim.token, target_workspace: claim.request.target_workspace, work_id: claim.request.executor_work_id };
+                    saveState(context, row, state);
+                    appendEvent(context, row.controller_id, "merge_claimed", { request_id: claim.request.merge_request_id });
                 }
-                session = { id: "", profile: transition.coordinator, state_dir: directory, cwd: next.stage === "merge" && state.merge_claim ? state.merge_claim.target_workspace : run.workspace_root, journal: path.join(directory, "adapter.events.jsonl"), owner };
-                if (runtimeHarness(session.profile) === "codex-desktop") {
-                    session.codex_home = path.join(directory, "codex-home");
-                    initCodexHome(context, { projectRoot: run.project_root, profile: `controller-${digest(directory).slice(0, 16)}`, targetHome: session.codex_home, ...(context.env.CODEX_HOME ? { sourceHome: context.env.CODEX_HOME } : {}) });
+                let session = state.current_session === null ? null : state.sessions[state.current_session];
+                if (!session || transition.session_mode === "new_session" || !sameSessionProfile(session.profile, transition.coordinator)) {
+                    if (session)
+                        await stopSession(session);
+                    assertOwner();
+                    const directory = path.join(row.state_dir, `session-${state.sessions.length + 1}`);
+                    fs.mkdirSync(directory, { mode: 0o700 });
+                    const owner = { schema_id: "dd-flow/runtime-owner@1", owner_id: row.controller_id, role: "subject", project_id: row.project_id, run_id: row.run_id, operation_id: `${row.controller_id}:session:${state.sessions.length + 1}`, state_dir: directory, dd_flow_home: context.ddFlowHome, dd_flow_bin: manifest.flow_executable, resource_home: manifest.resource_home, budget: manifest.budget };
+                    if (next.stage === "merge" && state.merge_claim) {
+                        owner.role = "merge";
+                        owner.work_id = state.merge_claim.work_id;
+                    }
+                    session = { id: "", profile: transition.coordinator, state_dir: directory, cwd: next.stage === "merge" && state.merge_claim ? state.merge_claim.target_workspace : run.workspace_root, journal: path.join(directory, "adapter.events.jsonl"), owner };
+                    if (runtimeHarness(session.profile) === "codex-desktop") {
+                        session.codex_home = path.join(directory, "codex-home");
+                        initCodexHome(context, { projectRoot: run.project_root, profile: `controller-${digest(directory).slice(0, 16)}`, targetHome: session.codex_home, ...(context.env.CODEX_HOME ? { sourceHome: context.env.CODEX_HOME } : {}) });
+                    }
+                    state.sessions.push(session);
+                    state.current_session = state.sessions.length - 1;
+                    saveState(context, row, state);
+                    await call(session, ["daemon", "start", ...sessionArguments(context, manifest, session)]);
+                    const created = await call(session, ["session", "create", ...sessionArguments(context, manifest, session)]);
+                    const sessionId = adapterSessionId(created);
+                    if (!sessionId)
+                        throw new AppError("harness_adapter_invalid", "Managed adapter did not return its Session id", 1);
+                    session.id = sessionId;
+                    saveState(context, row, state);
+                    bindInvocationScope(session);
+                    if (next.stage === "merge" && state.merge_claim)
+                        context.db.run("UPDATE merge_requests SET adapter_receipt_json = ?, updated_at = ? WHERE merge_request_id = ? AND dispatch_owner = ? AND dispatch_lease_token = ?", [JSON.stringify({ controller_id: row.controller_id, profile: session.profile, session_id: session.id, state_dir: session.state_dir, create: created }), context.now(), state.merge_claim.request_id, row.controller_id, state.merge_claim.token]);
+                    appendEvent(context, row.controller_id, "session_created", { stage: next.stage, session_id: sessionId, harness: runtimeHarness(session.profile), profile: session.profile });
                 }
-                state.sessions.push(session);
-                state.current_session = state.sessions.length - 1;
+                state.native_baseline = controllerNativeChildren(state.last_receipt ?? {}, session.id).map(child => child.session_id);
+                state.stage = next.stage;
+                state.last_continuation = null;
                 saveState(context, row, state);
-                await call(session, ["daemon", "start", ...sessionArguments(context, manifest, session)]);
-                const created = await call(session, ["session", "create", ...sessionArguments(context, manifest, session)]);
-                const sessionId = adapterSessionId(created);
-                if (!sessionId)
-                    throw new AppError("harness_adapter_invalid", "Managed adapter did not return its Session id", 1);
-                session.id = sessionId;
+                setStatus("running");
+                const responseFile = path.join(row.state_dir, `${next.stage}-${next.attempt ?? 1}.stage-start-response.json`);
+                const command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage start ${run.id} --stage ${next.stage} --project-root ${JSON.stringify(run.project_root)} --context-file ${JSON.stringify(stageContext.file)} --context-sha256 ${stageContext.sha256} --require-session-binding --response-file ${JSON.stringify(responseFile)} --json --progress-jsonl`);
+                appendEvent(context, row.controller_id, "stage_entered", { stage: next.stage, session_id: session.id, context_sha256: stageContext.sha256 });
+                await prompt(session, `Start the assigned ${next.stage} Stage now. Your first tool call must be this exact standalone command:\n\n${command}\n\nRead the complete authoritative packet saved to ${JSON.stringify(responseFile)}, including worker_prompt_markdown. If a read is truncated, continue until the entire packet has been read before doing Stage work. Stop at this Stage boundary or a declared HITL/Work-graph boundary; do not start a successor Stage yourself.`);
+                continue;
+            }
+            if (state.current_session === null)
+                throw new AppError("controller_attach_required", "An unfinished Stage has no managed coordinator", 1);
+            const session = state.sessions[state.current_session];
+            const baseline = new Set(state.native_baseline ?? []);
+            const children = controllerNativeChildren(state.last_receipt ?? {}, session.id).filter(child => !baseline.has(child.session_id));
+            const fanout = await nextControllerFanout(executionContext, { projectRoot: run.project_root, runId: run.id, stage: next.stage, harness: runtimeHarness(session.profile), sessionId: session.id, children, policy, profiles });
+            assertOwner();
+            if (fanout.kind === "none")
+                throw new AppError("incomplete_subject_turn", "Managed Turn ended without a completed Stage or declared continuation", 1, { stage: next.stage });
+            if (fanout.kind === "wait") {
+                setStatus(fanout.reason === "qualified_capacity_required" ? "waiting_for_capacity" : "waiting_for_children");
+                await delay(1000);
+                state.last_receipt = await call(session, ["session", "inspect", "--session-id", session.id, "--state-dir", session.state_dir, "--json"], false);
                 saveState(context, row, state);
-                bindInvocationScope(session);
-                if (next.stage === "merge" && state.merge_claim)
-                    context.db.run("UPDATE merge_requests SET adapter_receipt_json = ?, updated_at = ? WHERE merge_request_id = ? AND dispatch_owner = ? AND dispatch_lease_token = ?", [JSON.stringify({ controller_id: row.controller_id, profile: session.profile, session_id: session.id, state_dir: session.state_dir, create: created }), context.now(), state.merge_claim.request_id, row.controller_id, state.merge_claim.token]);
-                appendEvent(context, row.controller_id, "session_created", { stage: next.stage, session_id: sessionId, harness: runtimeHarness(session.profile), profile: session.profile });
+                continue;
             }
-            state.native_baseline = controllerNativeChildren(state.last_receipt ?? {}, session.id).map(child => child.session_id);
-            state.stage = next.stage;
-            state.last_continuation = null;
-            saveState(context, row, state);
             setStatus("running");
-            const responseFile = path.join(row.state_dir, `${next.stage}-${next.attempt ?? 1}.stage-start-response.json`);
-            const command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage start ${run.id} --stage ${next.stage} --project-root ${JSON.stringify(run.project_root)} --context-file ${JSON.stringify(stageContext.file)} --context-sha256 ${stageContext.sha256} --require-session-binding --response-file ${JSON.stringify(responseFile)} --json --progress-jsonl`);
-            appendEvent(context, row.controller_id, "stage_entered", { stage: next.stage, session_id: session.id, context_sha256: stageContext.sha256 });
-            await prompt(session, `Start the assigned ${next.stage} Stage now. Your first tool call must be this exact standalone command:\n\n${command}\n\nRead the complete authoritative packet saved to ${JSON.stringify(responseFile)}, including worker_prompt_markdown. If a read is truncated, continue until the entire packet has been read before doing Stage work. Stop at this Stage boundary or a declared HITL/Work-graph boundary; do not start a successor Stage yourself.`);
-            continue;
-        }
-        if (state.current_session === null)
-            throw new AppError("controller_attach_required", "An unfinished Stage has no managed coordinator", 1);
-        const session = state.sessions[state.current_session];
-        const baseline = new Set(state.native_baseline ?? []);
-        const children = controllerNativeChildren(state.last_receipt ?? {}, session.id).filter(child => !baseline.has(child.session_id));
-        const fanout = await nextControllerFanout(executionContext, { projectRoot: run.project_root, runId: run.id, stage: next.stage, harness: runtimeHarness(session.profile), sessionId: session.id, children, policy, profiles });
-        assertOwner();
-        if (fanout.kind === "none")
-            throw new AppError("incomplete_subject_turn", "Managed Turn ended without a completed Stage or declared continuation", 1, { stage: next.stage });
-        if (fanout.kind === "wait") {
-            setStatus(fanout.reason === "qualified_capacity_required" ? "waiting_for_capacity" : "waiting_for_children");
-            await delay(1000);
-            state.last_receipt = await call(session, ["session", "inspect", "--session-id", session.id, "--state-dir", session.state_dir, "--json"], false);
-            saveState(context, row, state);
-            continue;
-        }
-        setStatus("running");
-        if (fanout.kind === "external") {
-            const results = await Promise.allSettled(fanout.works.map(async (work) => {
-                assertOwner();
-                const receipt = await launchExternalWork(executionContext, { workId: work.work_id, stage: next.stage });
-                appendEvent(context, row.controller_id, "external_work_observed", { work_id: work.work_id, receipt });
-                const launch = context.db.get("SELECT state_dir, profile_json FROM work_launches WHERE work_id = ?", [work.work_id]);
-                const status = context.db.get("SELECT status FROM works WHERE work_id = ?", [work.work_id])?.status;
-                if (!launch || !["completed", "failed", "cancelled"].includes(status ?? ""))
-                    throw new AppError("external_work_unsettled", "External launch returned without its terminal Work receipt; observe it rather than relaunching", 1, { work_id: work.work_id, status });
-                const resolved = JSON.parse(launch.profile_json);
-                const executable = manifest.adapters[runtimeHarness(resolved.worker)].executable;
-                const stopped = await runHarnessAdapter({ executable, args: ["daemon", "stop", "--state-dir", launch.state_dir, "--json"], env: controllerEnvironment(context, manifest), operationId: `${row.controller_id}:${work.work_id}:settle` });
-                await confirmStopped(launch.state_dir, stopped);
-                appendEvent(context, row.controller_id, "external_work_settled", { work_id: work.work_id, receipt: stopped });
-            }));
-            const failure = results.find((result) => result.status === "rejected");
-            if (failure)
-                throw failure.reason;
-            state.last_continuation = null;
+            if (fanout.kind === "external") {
+                const results = await Promise.allSettled(fanout.works.map(async (work) => {
+                    try {
+                        assertOwner();
+                        const receipt = await launchExternalWork(executionContext, { workId: work.work_id, stage: next.stage });
+                        if (fatal)
+                            throw fatal;
+                        appendEvent(context, row.controller_id, "external_work_observed", { work_id: work.work_id, receipt });
+                        const launch = context.db.get("SELECT state_dir, profile_json FROM work_launches WHERE work_id = ?", [work.work_id]);
+                        const status = context.db.get("SELECT status FROM works WHERE work_id = ?", [work.work_id])?.status;
+                        if (!launch || !["completed", "failed", "cancelled"].includes(status ?? ""))
+                            throw new AppError("external_work_unsettled", "External launch returned without its terminal Work receipt; observe it rather than relaunching", 1, { work_id: work.work_id, status });
+                        const resolved = JSON.parse(launch.profile_json);
+                        const executable = manifest.adapters[runtimeHarness(resolved.worker)].executable;
+                        const stopped = await runHarnessAdapter({ executable, args: ["daemon", "stop", "--state-dir", launch.state_dir, "--json"], env: controllerEnvironment(context, manifest), operationId: `${row.controller_id}:${work.work_id}:settle` });
+                        await confirmStopped(launch.state_dir, stopped);
+                        appendEvent(context, row.controller_id, "external_work_settled", { work_id: work.work_id, receipt: stopped });
+                    }
+                    catch (error) {
+                        await stopAfterFailure(error);
+                        throw error;
+                    }
+                }));
+                const rejected = results.find((result) => result.status === "rejected");
+                if (rejected)
+                    throw fatal ?? rejected.reason;
+                state.last_continuation = null;
+                saveState(context, row, state);
+                continue;
+            }
+            if (state.last_continuation === fanout.fingerprint)
+                throw new AppError("fanout_stage_nonprogressing", "The coordinator repeated an unchanged Work-graph continuation", 1, { stage: next.stage });
+            state.last_continuation = fanout.fingerprint;
             saveState(context, row, state);
-            continue;
+            await prompt(session, fanout.prompt);
         }
-        if (state.last_continuation === fanout.fingerprint)
-            throw new AppError("fanout_stage_nonprogressing", "The coordinator repeated an unchanged Work-graph continuation", 1, { stage: next.stage });
-        state.last_continuation = fanout.fingerprint;
-        saveState(context, row, state);
-        await prompt(session, fanout.prompt);
+    }
+    catch (error) {
+        if (!fatal && error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale", "controller_owner_mismatch"].includes(error.code))
+            throw error;
+        await stopAfterFailure(fatal ?? error);
+        throw fatal ?? error;
+    }
+    finally {
+        clearInterval(monitor);
+        if (stopping)
+            await stopping;
+        observer.db.close?.();
     }
 }
 function readContexts(file, expected) {

package/dist/services/run-recovery-runtime.js

@@ -12,7 +12,7 @@ export function prepareRunRecoveryDispatch(context, input) {
         throw new AppError("usage", "Recovery dispatch requires an operation id and absolute state directory", 2);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = requireRecoveryRun(context, project.id, input.runId);
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
         const guard = recoveryGuard(context, project.id, run.id);
         const binding = context.db.get("SELECT * FROM run_recovery_bindings WHERE recovery_id = ?", [input.recoveryId]);