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

package/dist/services/run-controller.js

@@ -1,4 +1,9 @@
 import { assertLifecycleOutcomes, currentLifecycleFailure, managedInvocationContext, managedLifecycleCommand } from "./lifecycle-invocations.js";
+export function recoveryPacketMatchesStage(packet, scope) {
+    return packet.schema_id === 'dd-flow/root-recovery-packet@1' && packet.continuation === 'unfinished_work'
+        && packet.run_id === scope.runId && packet.generation === scope.generation && packet.stage === scope.stage
+        && packet.work_id === scope.workId && packet.paused === false;
+}
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -13,10 +18,11 @@ import { prepareFileBytes, prepareJsonText } from "../cli/input-preparation.js";
 import { parseRuntimeBudget } from "./runtime-budget.js";
 import { requireProjectByRoot } from "./projects.js";
 import { assertRunMutationAllowed, recoveryGuard } from "./run-recovery.js";
-import { getFlowRunStatus, setFlowRunRecoveryPaused } from "./runs.js";
+import { getFlowRunStatus, setFlowRunRecoveryPaused, assertPreparedRunBundleSqlAuthority } from "./runs.js";
 import { loadExternalStageContext } from "./stage-context.js";
 import { flowCommand } from "./stage-pause.js";
-import { resolveStageTransition, sameSessionProfile, stageExecutionCwd, runtimeHarness } from "./execution-policy.js";
+import { sameSessionProfile, runtimeHarness } from "./execution-policy.js";
+import { selectControllerExecution } from "./controller-execution.js";
 import { resolveHarnessCommand, harnessRuntimeArguments } from "./harness-config.js";
 import { adapterSessionId, prepareHarnessFlowExecutable, runHarnessAdapter } from "./harness-adapter.js";
 import { assertManagedProcessLease, confirmManagedProcess, renewManagedProcess, finishManagedProcess, processStartedAt, processTreeIsAlive, resourceHome } from "./managed-processes.js";
@@ -29,17 +35,24 @@ import { claimQueuedMergeRequest } from "./merge-server.js";
 import { prepareVnextCodeWorkspace } from "./vnext-code.js";
 import { requireRun, requireController, controllerReceipt, appendEvent, saveState, retainControllerContinuation, retainControllerCapacityIntent, digest, digestBytes, errorRecord } from "./run-controller-state.js";
 import { assertNoCorrelatedRejection } from "./continuation-outcome.js";
-import { spawnController, recordControllerLauncher, claimControllerProcess, markControllerDispatchReady, assertControllerRecoveryAllowed } from "./run-controller-process.js";
+import { spawnController, recordControllerLauncher, claimControllerProcess, markControllerDispatchReady, assertControllerLeaseAllowed } from "./run-controller-process.js";
 import { controllerAdapter, controllerEnvironment, sessionArguments } from "./run-controller-adapter.js";
 import { retainedChildObserver } from "./controller-child-observer.js";
-import { capacityDelay, continueCodexCapacity, eligibleCodexChildOverload } from "./codex-capacity.js";
+import { capacityDelay, continueProviderCapacity, eligibleProviderChildOverload, providerChildFailure } from "./provider-capacity.js";
 import { resumeControllerSession, failControllerRecovery } from "./run-controller-recovery.js";
 import { captureControllerBoundary } from "./run-controller-capture.js";
 import { requestRunControl } from "./run-control-worker.js";
 import { storageSessionId } from "./session-identity.js";
-import { CAPACITY_POLICY, nativeItemsSettled, overloadBurst, refusalObservation, terminalCodexOverload } from "../harness-runtime/lib/codex-capacity-policy.mjs";
+import { CAPACITY_POLICY, nativeItemsSettled, overloadExhausted, refusalObservation, terminalProviderOverload } from "../harness-runtime/lib/provider-overload-policy.mjs";
+import { renderNativeChildFollowupInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { closeSuccessfulChildCapacity } from "./controller-child-capacity.js";
 import { isObservationLoss } from "../harness-runtime/lib/operation-errors.mjs";
 export { resumeRunController } from "./run-controller-recovery.js";
+const preparedLaunchInputs = new WeakMap();
+function launchInputDigest(input) {
+    return digest([input.projectRoot, input.runId, input.requestId, input.contextFile, input.contextSha256,
+        input.stopAfter ?? null, input.captureRoot ?? null]);
+}
 export function prepareRunControllerLaunch(context, input) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(input.requestId) || !/^[a-f0-9]{64}$/.test(input.contextSha256))
         throw new AppError("usage", "Managed launch needs a request id and context SHA-256", 2);
@@ -60,58 +73,79 @@ export function prepareRunControllerLaunch(context, input) {
     if (existing) {
         if (existing.request_hash !== requestHash)
             throw new AppError("runtime_request_conflict", "Managed launch request id has different inputs", 1);
-        return { kind: "replay", existing };
+        selectControllerExecution(context, run, JSON.parse(existing.manifest_json));
+        const prepared = { kind: "replay", existing };
+        preparedLaunchInputs.set(prepared, { home: context.ddFlowHome, sha256: launchInputDigest(input) });
+        return prepared;
     }
     const generation = assertRunMutationAllowed(context, project.id, run.id);
     if (run.status !== "running")
         throw new AppError("invalid_run_state", "Managed launch requires a running logical RUN", 1, { status: run.status });
-    const index = JSON.parse(run.index_json);
-    const execution = index.execution_profile;
-    if (!execution?.settings.execution || !execution.agent_profiles)
-        throw new AppError("execution_profile_not_frozen", "Managed launch requires the RUN's frozen execution profiles", 1);
+    const routing = selectControllerExecution(context, run);
     const contexts = readContexts(input.contextFile, input.contextSha256);
+    if (routing.bundle) {
+        for (const stage of [...Object.keys(contexts), ...(input.stopAfter ? [input.stopAfter] : [])])
+            routing.bundle.descriptor.stage(stage);
+    }
     const next = getFlowRunStatus(context, { projectRoot: project.root, runId: run.id }).continuation;
     if (next.kind !== "start_stage" || !next.stage)
         throw new AppError("controller_attach_required", "Managed launch cannot replace an attached or unfinished coordinator; reconcile its existing owner", 1, { continuation: next });
     if (!contexts[next.stage])
         throw new AppError("controller_context_missing", "Managed context omits the first stage", 2, { stage: next.stage });
     const adapters = {};
-    for (const profile of Object.values(execution.agent_profiles)) {
+    for (const profile of Object.values(routing.profiles)) {
         const harness = runtimeHarness(profile);
         adapters[harness] = { executable: resolveHarnessCommand(context.ddFlowHome, harness, "adapter"), runtime_args: harnessRuntimeArguments(context.ddFlowHome, harness) };
     }
     const entry = fileURLToPath(new URL("../cli.js", import.meta.url));
     if (!fs.existsSync(entry))
         throw new AppError("harness_runtime_unbuilt", "Build the CLI before launching its detached controller", 1);
-    return { kind: "create", project, run, request, requestHash, generation, budget, execution, contexts, adapters };
+    const prepared = { kind: "create", project, run, request, requestHash, generation, budget, routing, contexts, adapters };
+    preparedLaunchInputs.set(prepared, { home: context.ddFlowHome, sha256: launchInputDigest(input) });
+    return prepared;
 }
-export async function launchRunController(context, input, prepared = prepareRunControllerLaunch(context, input)) {
-    if (prepared.kind === "replay")
-        return { ...await spawnController(context, prepared.existing), reused: true };
-    const { project, run, request, requestHash, generation, budget, execution, contexts, adapters } = prepared;
+/** Retain the existing launch intent and frozen inputs without starting a
+ * process. Dispatch remains exclusively owned by launchRunController. */
+export function retainRunControllerLaunch(context, input, prepared = prepareRunControllerLaunch(context, input)) {
+    const selection = preparedLaunchInputs.get(prepared);
+    if (!selection || selection.home !== context.ddFlowHome || selection.sha256 !== launchInputDigest(input)) {
+        throw new AppError("runtime_request_conflict", "Controller launch differs from its prepared request", 1, { effect: "no_effect" });
+    }
+    if (prepared.kind === "replay") {
+        const current = requireController(context, prepared.existing.controller_id);
+        if (current.request_hash !== prepared.existing.request_hash)
+            throw new AppError("runtime_request_conflict", "Controller launch authority changed after replay preparation", 1);
+        selectControllerExecution(context, requireRun(context, current.project_id, current.run_id), JSON.parse(current.manifest_json));
+        return { controller: current, reused: true };
+    }
+    const { project, run, request, requestHash, generation, budget, routing, contexts, adapters } = prepared;
     assertRunMutationAllowed(context, project.id, run.id, generation);
     ensureRunControllerStorage(context.db);
     const controllerId = `DRV-${crypto.randomUUID()}`;
     const root = path.join(run.run_root, "controllers", controllerId);
     fs.mkdirSync(root, { recursive: true, mode: 0o700 });
-    const flowExecutable = prepareHarnessFlowExecutable(context, root);
+    const flowExecutable = prepareHarnessFlowExecutable(context, root, routing.bundle?.engine());
     const frozenContexts = {};
     for (const [stage, value] of Object.entries(contexts)) {
         const file = path.join(root, `${stage}.context.json`);
         fs.writeFileSync(file, value.bytes, { flag: "wx", mode: 0o600 });
         frozenContexts[stage] = { file, sha256: value.sha256 };
     }
-    const manifest = { schema_id: "dd-flow/run-controller-manifest@1", request, execution_profile: execution, contexts: frozenContexts, adapters, flow_executable: flowExecutable, resource_home: resourceHome(context), budget };
+    const manifest = { schema_id: routing.kind === "descriptor" ? "dd-flow/run-controller-manifest@2" : "dd-flow/run-controller-manifest@1", request,
+        ...(routing.kind === "descriptor" ? { execution_binding: routing.binding } : { execution_profile: routing.legacy }),
+        contexts: frozenContexts, adapters, flow_executable: flowExecutable, resource_home: resourceHome(context), budget };
     const token = crypto.randomUUID();
     const now = context.now();
     const state = { stage: null, sessions: [], current_session: null, turns: 0, last_continuation: null };
     const launcher = { pid: process.pid, pid_started_at: processStartedAt(process.pid) };
     const duplicate = context.db.writeTransaction(() => {
+        if (routing.bundle)
+            assertPreparedRunBundleSqlAuthority(context, { projectId: project.id, runId: run.id }, routing.bundle);
         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) {
             if (duplicate.request_hash !== requestHash)
                 throw new AppError("runtime_request_conflict", "Managed launch request id has different inputs", 1);
-            return { ...controllerReceipt(duplicate), reused: true };
+            return duplicate;
         }
         assertRunMutationAllowed(context, project.id, run.id, generation);
         if (requireRun(context, project.id, run.id).status !== "running")
@@ -126,9 +160,16 @@ export async function launchRunController(context, input, prepared = prepareRunC
         appendEvent(context, controllerId, "launch_requested", { request_id: input.requestId, generation, request_hash: requestHash });
         return null;
     });
-    if (duplicate)
-        return duplicate;
-    return await spawnController(context, requireController(context, controllerId));
+    return { controller: duplicate ?? requireController(context, controllerId), reused: duplicate !== null };
+}
+export async function launchRunController(context, input, prepared = prepareRunControllerLaunch(context, input)) {
+    const retained = retainRunControllerLaunch(context, input, prepared);
+    // A simultaneous publisher already owns dispatch. Preserve the original
+    // race behavior: only an explicit replay may reconcile that existing owner.
+    if (prepared.kind === "create" && retained.reused)
+        return { ...controllerReceipt(retained.controller), reused: true };
+    const receipt = await spawnController(context, retained.controller);
+    return retained.reused ? { ...receipt, reused: true } : receipt;
 }
 /**
  * A registry write can be temporarily unavailable while another runtime client
@@ -179,6 +220,7 @@ export async function serveRunController(context, input) {
         throw new AppError("controller_owner_mismatch", "Managed owner has no resource lease", 1);
     const confirmed = confirmManagedProcess(context, { id: row.process_id, leaseToken: row.process_lease_token, pid: process.pid, processGroupId: process.pid, ownerPid: process.pid });
     const lease = controllerLeaseMonitor(attemptMs => renewManagedProcess({ ...context, resourceDatabaseMode: "prepared_existing", databaseDeadlineAt: Date.now() + attemptMs }, { id: row.process_id, leaseToken: row.process_lease_token }), confirmed.lease_expires_at);
+    const state = JSON.parse(row.state_json);
     // Resource and RUN commits are distinct effects. A RUN keepalive failure must
     // neither erase a resource receipt nor grant RUN dispatch authority.
     const mergeLease = controllerLeaseMonitor(attemptMs => {
@@ -194,22 +236,23 @@ export async function serveRunController(context, input) {
         return { owned: true, lease_expires_at: expiry };
     });
     const assertLeaseFence = () => {
-        const current = requireController(context, row.controller_id);
-        if (current.owner_token !== row.owner_token || current.generation !== row.generation)
-            throw new AppError("controller_owner_mismatch", "Lease renewal no longer owns this controller generation", 1);
-        assertControllerRecoveryAllowed(context, current);
+        assertControllerLeaseAllowed(context, row);
     };
     const heartbeat = setInterval(() => {
         lease.background(assertLeaseFence, () => { });
-        mergeLease.background(assertLeaseFence, () => { });
+        if (state.merge_claim)
+            mergeLease.background(assertLeaseFence, () => { });
     }, 30_000);
     heartbeat.unref();
     const manifest = JSON.parse(row.manifest_json);
-    const state = JSON.parse(row.state_json);
     const assertPhysicalOwner = () => {
         lease.assertNoRenewal();
-        mergeLease.assertNoRenewal();
-        assertManagedProcessLease({ ...context, databaseDeadlineAt: Date.now() + 5_000 }, { id: row.process_id, leaseToken: row.process_lease_token, pid: process.pid });
+        if (state.merge_claim)
+            mergeLease.assertNoRenewal();
+        // This isolated read already bounds SQLite contention. A wall deadline
+        // before opening the reader mistakes scheduler delay for heartbeat loss;
+        // the observed row's actual expiry/token still fences productive dispatch.
+        assertManagedProcessLease(context, { id: row.process_id, leaseToken: row.process_lease_token, pid: process.pid });
         const current = requireController(context, row.controller_id);
         if (current.owner_pid !== process.pid || current.owner_token !== row.owner_token || !["running", "capturing", "waiting_for_user", "waiting_for_context", "waiting_for_children", "waiting_for_capacity", "waiting_for_merge"].includes(current.status))
             throw new AppError("controller_owner_mismatch", "Controller no longer owns productive dispatch", 1);
@@ -221,7 +264,8 @@ export async function serveRunController(context, input) {
     };
     try {
         await lease.ensureConfirmed(assertLeaseFence);
-        await mergeLease.ensureConfirmed(assertLeaseFence);
+        if (state.merge_claim)
+            await mergeLease.ensureConfirmed(assertLeaseFence);
         context.db.writeTransaction(() => {
             markControllerDispatchReady(context, row);
             if (!state.recovery && (recoveryGuard(context, row.project_id, row.run_id)?.generation ?? 0) === row.generation && requireRun(context, row.project_id, row.run_id).status === "paused")
@@ -230,7 +274,8 @@ export async function serveRunController(context, input) {
         appendEvent(context, row.controller_id, "owner_started", { pid: process.pid, generation: row.generation });
         if (state.recovery && !["done", "failed", "cancelled"].includes(requireRun(context, row.project_id, row.run_id).status))
             await resumeControllerSession(context, row, manifest, state, assertPhysicalOwner);
-        await executeController(context, row, manifest, state, assertOwner, assertPhysicalOwner, async () => { await lease.ensureConfirmed(assertLeaseFence); await mergeLease.ensureConfirmed(assertLeaseFence); });
+        await executeController(context, row, manifest, state, assertOwner, assertPhysicalOwner, async () => { await lease.ensureConfirmed(assertLeaseFence); if (state.merge_claim)
+            await mergeLease.ensureConfirmed(assertLeaseFence); });
         return controllerReceipt(requireController(context, row.controller_id));
     }
     catch (error) {
@@ -449,8 +494,9 @@ async function executeController(context, row, manifest, state, assertOwnership,
             }
         }
     };
-    const policy = manifest.execution_profile.settings.execution;
-    const profiles = manifest.execution_profile.agent_profiles;
+    const routing = selectControllerExecution(context, requireRun(context, row.project_id, row.run_id), manifest);
+    const policy = routing.policy;
+    const profiles = routing.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, DD_FLOW_CODE_READINESS_OWNER: row.controller_id } };
     const bindInvocationScope = (session) => {
         executionContext = managedInvocationContext(executionContext, { harness: runtimeHarness(session.profile), stateDir: session.state_dir, sessionId: session.id,
@@ -640,14 +686,12 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 }
             }
             catch (error) {
-                if (!["codex-desktop", "opencode-server"].includes(runtimeHarness(session.profile)))
-                    throw error;
                 const resumeCommand = hitl ? text.split("\n\n")[1] : undefined;
                 if (hitl && !resumeCommand?.includes(" stage resume "))
                     throw error;
                 const inspect = (args, id) => runHarnessAdapter({ executable: manifest.adapters[runtimeHarness(session.profile)].executable,
                     args, env: controllerEnvironment(context, manifest, session), runtimeOwner: session.owner, operationId: id, timeoutMs: 30_000, signal: cancellation.signal });
-                const resumed = await continueCodexCapacity({ error, sessionId: session.id, operationId: firstOperationId, signal: cancellation.signal, allowSettledDescendants: true, atomicIntent: true,
+                const resumed = await continueProviderCapacity({ error, sessionId: session.id, operationId: firstOperationId, signal: cancellation.signal, allowSettledDescendants: true, atomicIntent: true,
                     retainedIntents: () => context.db.all("SELECT receipt_json FROM run_controller_operations WHERE controller_id = ? AND generation = ?", [row.controller_id, row.generation])
                         .flatMap(item => { const retained = JSON.parse(item.receipt_json || "null"); return retained?.capacity_intent?.root_operation_id === firstOperationId ? [retained.capacity_intent] : []; }).sort((a, b) => a.ordinal - b.ordinal),
                     retainedFailures: () => context.db.all("SELECT receipt_json FROM run_controller_operations WHERE controller_id = ? AND generation = ?", [row.controller_id, row.generation])
@@ -745,7 +789,10 @@ async function executeController(context, row, manifest, state, assertOwnership,
             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);
-            if (state.pending_capacity && !["done", "failed", "cancelled"].includes(run.status)) {
+            const view = getFlowRunStatus(executionContext, { projectRoot: run.project_root, runId: run.id });
+            const next = view.continuation;
+            terminalFinalization = next.kind === "terminal";
+            if (state.pending_capacity && next.kind !== "terminal" && !["done", "failed", "cancelled"].includes(run.status)) {
                 const pending = state.pending_capacity;
                 const session = state.sessions.find(item => item.id === pending.session_id && !item.stopped);
                 const operation = context.db.get("SELECT input_json FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND generation = ?", [pending.root_operation_id, row.controller_id, row.generation]);
@@ -757,9 +804,6 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 await prompt(session, fs.readFileSync(file, "utf8"), pending.root_operation_id, pending.kind === "stage" ? undefined : pending.kind);
                 continue;
             }
-            const view = getFlowRunStatus(executionContext, { projectRoot: run.project_root, runId: run.id });
-            const next = view.continuation;
-            terminalFinalization = next.kind === "terminal";
             const completed = state.stage && view.index.stage_runs.find(stage => stage.stage === state.stage && ["done", "skipped"].includes(stage.status));
             if (state.current_session !== null && (completed || next.stage !== state.stage) && childObserver(state.sessions[state.current_session])?.failed().length)
                 throw new AppError("fanout_dispatch_fenced", "A retained child failure forbids completing or advancing its Stage", 1);
@@ -833,8 +877,8 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 loadExternalStageContext({ file: stageContext.file, expectedSha256: stageContext.sha256, stage: next.stage });
                 const continuation = JSON.stringify(["start_stage", next.stage, next.attempt ?? null]);
                 retainControllerContinuation(state, continuation, { code: "stage_entry_nonprogressing", message: "The coordinator returned without starting the assigned Stage", details: { stage: next.stage, attempt: next.attempt ?? null, last_receipt: state.last_receipt ?? null } });
-                const transition = resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy, profiles, ...(state.stage ? { fromStage: state.stage } : {}), stage: next.stage, projectRoot: run.project_root, workspaceRoot: run.workspace_root, 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 transition = routing.transition(next.stage, state.stage ?? undefined, run);
+                if (routing.kind === "sdlc" && next.stage === "merge" && routing.mergeMode === "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 });
@@ -847,10 +891,26 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     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 });
+                    await renewLease();
                 }
-                const stageCwd = stageExecutionCwd({ stage: next.stage, projectRoot: run.project_root, workspaceRoot: run.workspace_root, ...(state.merge_claim ? { mergeTargetWorkspace: state.merge_claim.target_workspace } : {}) });
+                const stageCwd = routing.cwd(next.stage, state.merge_claim?.target_workspace, run);
+                const routeBinding = (current) => {
+                    const index = JSON.parse(current.index_json);
+                    return JSON.stringify([current.project_root, current.workspace_root, index.workspace_route ?? null, state.merge_claim ?? null]);
+                };
+                const preparedRoute = routeBinding(run);
+                const assertRoute = async () => {
+                    assertOwner();
+                    if (routeBinding(requireRun(context, row.project_id, row.run_id)) !== preparedRoute) {
+                        const current = state.current_session === null ? null : state.sessions[state.current_session];
+                        if (current && !current.stopped)
+                            await stopSession(current);
+                        throw new AppError("workspace_route_changed", "RUN workspace changed during native Session preparation", 1, { effect: "no_effect", stage: next.stage });
+                    }
+                };
+                await assertRoute();
                 let session = state.current_session === null ? null : state.sessions[state.current_session];
-                if (session && next.stage === "merge" && manifest.execution_profile.settings.merge_mode === "same_session" && path.resolve(session.cwd) !== stageCwd) {
+                if (session && routing.kind === "sdlc" && next.stage === "merge" && routing.mergeMode === "same_session" && path.resolve(session.cwd) !== stageCwd) {
                     throw new AppError("merge_session_workspace_conflict", "Same-session MERGE cannot change the native Session working directory", 1, { session_cwd: session.cwd, target_cwd: stageCwd });
                 }
                 if (!session || transition.session_mode === "new_session" || !sameSessionProfile(session.profile, transition.coordinator) || path.resolve(session.cwd) !== stageCwd) {
@@ -890,7 +950,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 state.child_capacity = {};
                 saveState(context, row, state);
                 setStatus("running");
-                if (next.stage === "code" || next.stage === "code-review") {
+                if (routing.kind === "sdlc" && (next.stage === "code" || next.stage === "code-review")) {
                     // A CODE_REVIEW fork has source files but intentionally no installed
                     // dependencies. Its repair Work executes checks just like CODE Work.
                     const readiness = await prepareVnextCodeWorkspace(executionContext, { projectRoot: run.project_root, runId: run.id, ownerId: row.controller_id, stage: next.stage });
@@ -900,6 +960,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 }
                 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`);
+                await assertRoute();
                 appendEvent(context, row.controller_id, "stage_entered", { stage: next.stage, session_id: session.id, context_sha256: stageContext.sha256 });
                 await prompt(session, controllerStageEntryPrompt(next.stage, command));
                 continue;
@@ -907,11 +968,19 @@ async function executeController(context, row, manifest, state, assertOwnership,
             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 childHarness = runtimeHarness(session.profile);
             const baseline = new Set(state.native_baseline ?? []);
             let children = controllerNativeChildren(state.last_receipt ?? {}, session.id).filter(child => !baseline.has(child.session_id));
+            childObserver(session)?.observeSettledChildren(children);
             const retainedFailures = childObserver(session)?.failed() ?? [];
             children = controllerNativeChildren({ descendants: [...children, ...retainedFailures] }, session.id);
-            if (runtimeHarness(session.profile) === "codex-desktop" && children.some(child => child.status === "failed")) {
+            const closedChildEpisodes = closeSuccessfulChildCapacity(state, children, session.id);
+            if (closedChildEpisodes.length)
+                await prepareMutation(() => {
+                    saveState(context, row, state);
+                    appendEvent(context, row.controller_id, "capacity_child_episodes_completed", { child_session_ids: closedChildEpisodes });
+                });
+            if (children.some(child => child.status === "failed" && renderNativeChildFollowupInstruction(childHarness, child.session_id))) {
                 const inspected = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
                 state.last_receipt = inspected;
                 saveState(context, row, state);
@@ -919,32 +988,31 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 const failed = children.filter(child => child.status === "failed");
                 // Freeze each distinct child refusal on its first exact observation,
                 // even while a healthy sibling still owns an active native Turn.
-                for (const failedChild of failed.filter(item => eligibleCodexChildOverload(item, session.id))) {
-                    const linked = context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: "codex-desktop", session_id: failedChild.session_id })]);
+                for (const failedChild of failed.filter(item => eligibleProviderChildOverload(item, session.id))) {
+                    const linked = context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: childHarness, session_id: failedChild.session_id })]);
                     if (linked.length > 1 || linked.some(link => link.status !== "running"))
                         continue;
                     const retained = state.child_capacity?.[failedChild.session_id];
                     const refusals = [...(retained?.refusals ?? [])];
                     if (refusals.some(item => item.turn_id === failedChild.terminal_turn_id))
                         continue;
-                    const nativeFailure = { code: "turn_interrupted", details: { provider_session_id: failedChild.session_id, turn_id: failedChild.terminal_turn_id, native_turn_id: failedChild.terminal_turn_id, terminal_status: "failed", provider_error: failedChild.provider_error, observed_at: failedChild.terminal_observed_at } };
+                    const nativeFailure = providerChildFailure(failedChild);
                     refusals.push(refusalObservation(nativeFailure, retained?.attempts ?? 0, failedChild.terminal_observed_at ?? context.now()));
                     state.child_capacity ??= {};
                     state.child_capacity[failedChild.session_id] = { ...retained, turn_id: retained?.turn_id ?? failedChild.terminal_turn_id, attempts: retained?.attempts ?? 0, policy: CAPACITY_POLICY, refusals };
                     await prepareMutation(() => { saveState(context, row, state); appendEvent(context, row.controller_id, "capacity_child_refusal", { child_session_id: failedChild.session_id, refusal: refusals.at(-1) }); });
-                    const burst = overloadBurst(refusals);
-                    if (burst)
-                        throw new AppError("provider_overload_burst", "Native child had two continuation refusals within two minutes", 1, { ...burst, child_session_id: failedChild.session_id, primary_error: nativeFailure });
+                    const exhausted = overloadExhausted(refusals);
+                    if (exhausted)
+                        throw new AppError("provider_unavailable", "Native child exhausted its overload continuation attempts", 1, { ...exhausted, reason: "overload_retries_exhausted", child_session_id: failedChild.session_id, primary_error: nativeFailure });
                 }
                 // Continue one existing child at a time; another failed child does not
                 // create a second fanout wave or share this child's refusal counter.
-                const child = children.every(item => item.status === "failed" || item.status === "completed") ? failed.find(item => item.parent_session_id === session.id && item.terminal_turn_id && nativeItemsSettled(item.native_turn_items) && terminalCodexOverload({ code: "turn_interrupted", details: { provider_session_id: item.session_id, turn_id: item.terminal_turn_id, native_turn_id: item.terminal_turn_id, terminal_status: "failed", provider_error: item.provider_error } }, item.session_id)) : undefined;
+                const child = children.every(item => item.status === "failed" || item.status === "completed") ? failed.find(item => renderNativeChildFollowupInstruction(childHarness, item.session_id) && eligibleProviderChildOverload(item, session.id)) : undefined;
                 const turnId = child?.terminal_turn_id;
-                const native = child && turnId ? { code: "turn_interrupted", details: { provider_session_id: child.session_id, turn_id: turnId, native_turn_id: turnId,
-                        terminal_status: "failed", provider_error: child.provider_error, observed_at: child.terminal_observed_at } } : null;
+                const native = child && turnId ? providerChildFailure(child) : null;
                 const prior = child && state.child_capacity?.[child.session_id];
-                const links = child ? context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: "codex-desktop", session_id: child.session_id })]) : [];
-                if (child && turnId && native && terminalCodexOverload(native, child.session_id, turnId)
+                const links = child ? context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: childHarness, session_id: child.session_id })]) : [];
+                if (child && turnId && native && terminalProviderOverload(native, child.session_id, turnId)
                     && nativeItemsSettled(child.native_turn_items)
                     && inspected.settled === true && child.parent_session_id === session.id && links.length <= 1
                     && (!links.length || links[0].status === "running")) {
@@ -962,10 +1030,17 @@ async function executeController(context, row, manifest, state, assertOwnership,
                         state.child_capacity[child.session_id] = { ...prior, turn_id: prior?.turn_id ?? turnId, attempts: prior?.attempts ?? 0, policy: CAPACITY_POLICY, refusals };
                         saveState(context, row, state);
                     }
-                    const burst = overloadBurst(refusals);
-                    if (burst)
-                        throw new AppError("provider_overload_burst", "Native child had two continuation refusals within two minutes", 1, { ...burst, child_session_id: child.session_id, primary_error: native });
-                    const wait = prepared ? Math.max(0, Date.parse(prepared.not_before) - Date.now()) : capacityDelay(native, attempt);
+                    const exhausted = overloadExhausted(refusals);
+                    if (exhausted)
+                        throw new AppError("provider_unavailable", "Native child exhausted its overload continuation attempts", 1, { ...exhausted, reason: "overload_retries_exhausted", child_session_id: child.session_id, primary_error: native });
+                    let wait;
+                    try {
+                        wait = prepared ? Math.max(0, Date.parse(prepared.not_before) - Date.now()) : capacityDelay(native, attempt);
+                    }
+                    catch (error) {
+                        const failure = error;
+                        throw new AppError(failure.code ?? "capacity_retry_metadata_invalid", failure.message ?? "Invalid child retry delay", 1, { ...failure.details, child_session_id: child.session_id, root_operation_id: prior?.root_operation_id ?? null, attempts: refusals.length, primary_error: native });
+                    }
                     if (!Number.isFinite(wait) || Date.now() + wait > 8.64e15)
                         throw new AppError("capacity_retry_metadata_invalid", "Native child retry time is invalid", 1, { child_session_id: child.session_id, delay_ms: wait });
                     const rootOperationId = prior?.root_operation_id ?? `${row.controller_id}:child:${digest([child.session_id, turnId]).slice(0, 16)}`;
@@ -988,7 +1063,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                         throw new AppError("capacity_child_followup_blocked", "RUN changed during native child capacity wait", 1, { child_session_id: child.session_id });
                     const fresh = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
                     const still = controllerNativeChildren(fresh, session.id).find(item => item.session_id === child.session_id);
-                    const currentLinks = context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: "codex-desktop", session_id: child.session_id })]);
+                    const currentLinks = context.db.all("SELECT w.status FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ?", [row.project_id, row.run_id, storageSessionId({ harness_id: childHarness, session_id: child.session_id })]);
                     if (currentLinks.length === 1 && ["completed", "cancelled", "paused"].includes(currentLinks[0].status)) {
                         state.last_receipt = fresh;
                         saveState(context, row, state);
@@ -1000,7 +1075,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                         throw new AppError("capacity_child_followup_blocked", "Native child or Work changed during capacity wait", 1, { child_session_id: child.session_id, turn_id: turnId });
                     await renewLease();
                     assertOwner();
-                    const text = `The existing native child ${child.session_id} has a confirmed terminal overloaded Turn. Use the native followup_task tool exactly once for that same child ID with this short message: "Continue your assigned Work from its current durable state. Do not repeat an observed lifecycle command. Finish only the original Work." Do not spawn another child, claim another Work, or perform the child's Work in this parent Turn. End this Turn after the followup_task response.`;
+                    const text = renderNativeChildFollowupInstruction(childHarness, child.session_id);
                     await prompt(session, text, operationId, "child");
                     state.child_capacity[child.session_id].dispatched = true;
                     saveState(context, row, state);
@@ -1016,6 +1091,25 @@ async function executeController(context, row, manifest, state, assertOwnership,
             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, dispatchFence: retainedFailures.length > 0 });
             assertOwner();
             if (fanout.kind === "none") {
+                // An ACK-only recovery Turn may leave the original root Work unfinished.
+                // Continue that retained packet once; never restart its Stage or repeat
+                // an unknown productive dispatch merely because the observer reattached.
+                const recovery = context.db.get(`SELECT o.operation_id,b.packet_json,b.packet_sha256,b.work_id
+        FROM run_controller_operations o JOIN run_recovery_bindings b ON b.recovery_id=json_extract(o.receipt_json,'$.recovery_id')
+        JOIN run_recovery_guards g ON g.recovery_id=b.recovery_id
+        WHERE o.controller_id=? AND o.generation=? AND o.status='completed' AND json_extract(o.input_json,'$.action')='control_resume'
+          AND b.status='accepted' AND g.status='recovered' AND g.project_id=? AND g.run_id=?
+          AND b.provider_session_id=? AND b.daemon_id=json_extract(o.receipt_json,'$.daemon_id') ORDER BY o.created_at DESC LIMIT 1`, [row.controller_id, row.generation, row.project_id, row.run_id, session.id]);
+                if (recovery && digestBytes(recovery.packet_json) === recovery.packet_sha256) {
+                    const packet = JSON.parse(recovery.packet_json);
+                    const operationId = `${recovery.operation_id}:unfinished-root`;
+                    const work = context.db.get('SELECT status FROM works WHERE work_id=? AND project_id=? AND run_id=? AND parent_work_id IS NULL', [recovery.work_id, row.project_id, row.run_id]);
+                    if (recoveryPacketMatchesStage(packet, { runId: row.run_id, generation: row.generation, stage: next.stage, workId: recovery.work_id }) && work?.status === 'running'
+                        && !context.db.get('SELECT 1 FROM run_controller_operations WHERE operation_id=?', [operationId])) {
+                        await prompt(session, `Continue the original unfinished root Work from this accepted recovery packet. Inspect retained receipts and partial effects first. Do not restart the Stage, repeat observed lifecycle operations, create another Work or start a successor Stage. Preserve the packet write scope and result schema; stop at its original boundary.\n\nAccepted recovery packet (JSON data):\n${recovery.packet_json}`, operationId);
+                        continue;
+                    }
+                }
                 assertNoCorrelatedRejection(context, { projectId: row.project_id, runId: row.run_id, generation: row.generation, stage: next.stage, turn: state.turns });
                 const cause = currentLifecycleFailure(executionContext, { runId: run.id, generation: row.generation, stage: next.stage, turn: state.turns, projectId: row.project_id, projectRoot: run.project_root });
                 if (cause)

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

@@ -1,5 +1,6 @@
 import { AppError } from "../shared/errors.js";
-import { CAPACITY_POLICY, overloadBurst } from "../harness-runtime/lib/codex-capacity-policy.mjs";
+import { CAPACITY_POLICY, MAX_OVERLOAD_RETRIES, overloadExhausted } from "../harness-runtime/lib/provider-overload-policy.mjs";
+import { assertRunStartupSettled } from "./run-start-custody.js";
 export function recoveryGuard(context, projectId, runId) { return context.db.get("SELECT recovery_id, project_id, run_id, generation, status, interruption_json, settlement_json, capture_path, created_at, updated_at, sealed_at, resumed_at FROM run_recovery_guards WHERE project_id = ? AND run_id = ? ORDER BY generation DESC LIMIT 1", [projectId, runId]) ?? null; }
 export function assertRunRecoveryAllowed(context, projectId, runId, expectedGeneration) {
     const guard = recoveryGuard(context, projectId, runId);
@@ -11,6 +12,7 @@ export function assertRunRecoveryAllowed(context, projectId, runId, expectedGene
     return generation;
 }
 export function assertRunMutationAllowed(context, projectId, runId, expectedGeneration) {
+    assertRunStartupSettled(context, projectId, runId);
     const generation = assertRunRecoveryAllowed(context, projectId, runId, expectedGeneration);
     if (context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controllers'")
         && context.db.get("SELECT 1 FROM run_controllers WHERE project_id = ? AND run_id = ? AND status IN ('capturing','capture_failed') LIMIT 1", [projectId, runId]))
@@ -41,7 +43,7 @@ export function recoveryRuntimeAdmission(context, record, input) {
     if (active) {
         const ordinal = dispatch.capacity_intents.length;
         const predecessor = ordinal === 1 ? dispatch.operation_id : dispatch.capacity_intents[ordinal - 2].operation_id;
-        if (active.policy !== CAPACITY_POLICY || active.ordinal !== ordinal || active.root_operation_id !== dispatch.operation_id || active.session_id !== binding.provider_session_id
+        if (ordinal > MAX_OVERLOAD_RETRIES || active.policy !== CAPACITY_POLICY || active.ordinal !== ordinal || active.root_operation_id !== dispatch.operation_id || active.session_id !== binding.provider_session_id
             || active.predecessor !== predecessor || active.operation_id !== `${dispatch.operation_id}:capacity:${ordinal}:session.prompt`
             || active.refusal?.policy !== CAPACITY_POLICY || active.refusal.ordinal !== ordinal - 1 || active.refusal.turn_id !== active.turn_id
             || active.refusal.session_id !== binding.provider_session_id || active.deadline !== null || !Number.isFinite(Date.parse(active.not_before)))
@@ -50,7 +52,7 @@ export function recoveryRuntimeAdmission(context, record, input) {
         if (!failure || JSON.stringify(failure) !== JSON.stringify(active.refusal))
             return false;
         try {
-            if (overloadBurst(dispatch.capacity_failures))
+            if (overloadExhausted(dispatch.capacity_failures))
                 return false;
         }
         catch {

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

@@ -8,7 +8,7 @@ import { managedProcessBinding, processIsAlive, resourceHome } from "./managed-p
 import { getResourceDatabase } from "../storage/database.js";
 import { requireManagedDaemonBinding } from "./managed-daemon-binding.js";
 import { lifecycleRetryInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
-import { CAPACITY_POLICY, overloadBurst } from "../harness-runtime/lib/codex-capacity-policy.mjs";
+import { CAPACITY_POLICY, MAX_OVERLOAD_RETRIES, overloadExhausted } from "../harness-runtime/lib/provider-overload-policy.mjs";
 /** Pin retained Session loading and its first acknowledgement Turn, never a general fence bypass. */
 export function prepareRunRecoveryDispatch(context, input) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(input.operationId) || !path.isAbsolute(input.stateDir))
@@ -60,7 +60,7 @@ export function prepareRunRecoveryDispatch(context, input) {
 /** Publish only an exact successor to a failed, effect-free recovery ACK Turn. */
 export function retainRecoveryCapacityIntent(context, input) {
     const { intent } = input;
-    if (!Number.isSafeInteger(intent.ordinal) || intent.ordinal < 1 || !intent.turn_id || !Number.isFinite(Date.parse(intent.not_before)) || intent.policy !== CAPACITY_POLICY
+    if (!Number.isSafeInteger(intent.ordinal) || intent.ordinal < 1 || intent.ordinal > MAX_OVERLOAD_RETRIES || !intent.turn_id || !Number.isFinite(Date.parse(intent.not_before)) || intent.policy !== CAPACITY_POLICY
         || !intent.refusal || intent.refusal.policy !== CAPACITY_POLICY || intent.refusal.ordinal !== intent.ordinal - 1 || intent.refusal.turn_id !== intent.turn_id
         || !Number.isFinite(Date.parse(intent.refusal.first_observed_at)) || intent.deadline !== null)
         throw new AppError("recovery_capacity_intent_invalid", "Recovery capacity successor is invalid", 1);
@@ -91,7 +91,7 @@ export function retainRecoveryCapacityIntent(context, input) {
         }
         const refusals = dispatch.capacity_failures ?? [];
         const observed = refusals.find(item => item.ordinal === intent.refusal.ordinal);
-        if (!observed || JSON.stringify(observed) !== JSON.stringify(intent.refusal) || overloadBurst(refusals))
+        if (!observed || JSON.stringify(observed) !== JSON.stringify(intent.refusal) || overloadExhausted(refusals))
             throw new AppError("recovery_capacity_intent_conflict", "Recovery successor lacks an immutable non-burst refusal binding", 1);
         const predecessor = intent.ordinal === 1 ? dispatch.operation_id : prior[intent.ordinal - 2]?.operation_id;
         if (prior.length !== intent.ordinal - 1 || predecessor !== intent.predecessor || intent.operation_id !== `${dispatch.operation_id}:capacity:${intent.ordinal}:session.prompt`)