@deksden-com/dd-flow-cli 0.9.0-beta.136 → 0.9.0-beta.138

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,8 +35,9 @@ 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 { resumeControllerSession, failControllerRecovery } from "./run-controller-recovery.js";
 import { captureControllerBoundary } from "./run-controller-capture.js";
@@ -39,6 +46,11 @@ import { storageSessionId } from "./session-identity.js";
 import { CAPACITY_POLICY, nativeItemsSettled, overloadBurst, refusalObservation, terminalCodexOverload } from "../harness-runtime/lib/codex-capacity-policy.mjs";
 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);
@@ -59,58 +71,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")
@@ -125,9 +158,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
@@ -178,6 +218,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 => {
@@ -193,21 +234,19 @@ 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();
+        if (state.merge_claim)
+            mergeLease.assertNoRenewal();
         assertManagedProcessLease({ ...context, databaseDeadlineAt: Date.now() + 5_000 }, { 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))
@@ -220,7 +259,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")
@@ -229,7 +269,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) {
@@ -448,8 +489,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,
@@ -460,6 +502,52 @@ async function executeController(context, row, manifest, state, assertOwnership,
     let fatal;
     let stopping;
     const cancellation = new AbortController();
+    const observationCancellation = new AbortController();
+    const childObservers = new Map();
+    let promptPending = false;
+    let observedPromptOperation = null;
+    const childObserver = (session) => {
+        if (runtimeHarness(session.profile) !== "zcode-acp" || !state.stage || !["plan-review", "code", "code-review"].includes(state.stage))
+            return undefined;
+        if (readNativeDaemonState(session.state_dir).capabilities?.retained_child_observation !== true)
+            return undefined;
+        const scope = { controller_id: row.controller_id, generation: row.generation, stage: state.stage, root_session_id: session.id };
+        const key = JSON.stringify(scope);
+        let retained = childObservers.get(key);
+        if (!retained) {
+            retained = retainedChildObserver({ file: path.join(row.state_dir, "native-child-observations.jsonl"), scope, assertOwner: assertOwnership,
+                gap: error => { process.stderr.write(`${JSON.stringify({ event: "native_child_observation_gap", scope, error_code: String(error?.code ?? "observation_unavailable") })}\n`); },
+                read: async () => {
+                    assertOwnership();
+                    const operation = observedPromptOperation;
+                    const binding = requireManagedDaemonBinding(executionContext, { stateDir: session.state_dir, projectId: row.project_id, runId: row.run_id });
+                    let receipt;
+                    try {
+                        receipt = await runHarnessAdapter({ executable: manifest.adapters["zcode-acp"].executable,
+                            args: ["session", "observe-children", "--session-id", session.id, ...sessionArguments(context, manifest, session)],
+                            env: controllerEnvironment(context, manifest, session), operationId: crypto.randomUUID(), harness: "zcode", timeoutMs: 30_000,
+                            signal: AbortSignal.any([cancellation.signal, observationCancellation.signal]) });
+                    }
+                    catch (error) {
+                        if (!promptPending || observedPromptOperation !== operation)
+                            return null;
+                        throw error;
+                    }
+                    if (!promptPending || observedPromptOperation !== operation || receipt.active_operation_id === null)
+                        return null;
+                    if (receipt.schema_id !== "dd-zcode/child-observation@1" || receipt.provider_session_id !== session.id || receipt.daemon_id !== binding.state.daemon_id)
+                        throw new AppError("native_child_observation_conflict", "Retained child observation has foreign daemon/root identity", 1);
+                    if (receipt.active_operation_id !== operation)
+                        throw new AppError("native_child_observation_conflict", "Retained observation has a foreign productive operation", 1);
+                    const children = controllerNativeChildren(receipt, session.id).filter(child => !(state.native_baseline ?? []).includes(child.session_id));
+                    if (children.some(child => child.status === "failed" && !child.terminal_turn_id))
+                        throw new AppError("operation_observation_lost", "Retained child terminal identity is unavailable", 1);
+                    return children;
+                } });
+            childObservers.set(key, retained);
+        }
+        return retained;
+    };
     const capacityUncertain = (error) => error instanceof AppError && ["capacity_continuation_blocked", "operation_observation_lost"].includes(error.code) && error.details.capacity_uncertainty === true || Boolean(state.pending_capacity) && (String(error?.code) === "capacity_continuation_blocked" || isObservationLoss(error));
     const stopAfterFailure = (error) => {
         // A retained successor may already be running. Fencing/recovery records
@@ -492,10 +580,15 @@ async function executeController(context, row, manifest, state, assertOwnership,
         }).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 setStatus = (status, terminalData) => {
+        context.db.writeTransaction(() => {
+            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 });
+                if (terminalData)
+                    appendEvent(context, row.controller_id, status, terminalData);
+            }
+        });
     };
     const call = (session, args, productive = true) => controllerAdapter(executionContext, row, manifest, session, args, productive ? assertOwner : undefined, undefined, productive ? cancellation.signal : undefined, productive ? renewLease : undefined);
     const confirmStopped = async (stateDir, receipt) => {
@@ -575,7 +668,17 @@ async function executeController(context, row, manifest, state, assertOwnership,
                         throw new AppError("capacity_continuation_conflict", "Retained capacity root has no failure receipt", 1);
                     throw JSON.parse(root.error_json);
                 }
-                receipt = await send(text, firstOperationId);
+                if (childObserver(session)?.failed().length)
+                    throw new AppError("fanout_dispatch_fenced", "A retained child failure forbids another coordinator dispatch", 1);
+                promptPending = true;
+                observedPromptOperation = firstOperationId;
+                try {
+                    receipt = await send(text, firstOperationId);
+                }
+                finally {
+                    promptPending = false;
+                    observedPromptOperation = null;
+                }
             }
             catch (error) {
                 if (!["codex-desktop", "opencode-server"].includes(runtimeHarness(session.profile)))
@@ -640,6 +743,11 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 receipt = resumed;
             }
             checkOutcomes();
+            await childObserver(session)?.drain();
+            childObserver(session)?.completePostTurn(receipt);
+            const observationGap = childObserver(session)?.gap();
+            if (observationGap)
+                throw new AppError("operation_observation_lost", "In-flight child observation remained unavailable at the safe Turn boundary", 1, { observation_error_code: observationGap, provider_session_id: session.id, stage: state.stage });
             if (fatal)
                 throw fatal;
         }
@@ -661,6 +769,8 @@ async function executeController(context, row, manifest, state, assertOwnership,
             return;
         try {
             checkOutcomes();
+            if (promptPending && state.current_session !== null)
+                childObserver(state.sessions[state.current_session])?.tick();
         }
         catch (error) {
             void stopAfterFailure(error);
@@ -676,7 +786,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]);
@@ -688,19 +801,17 @@ 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);
             if (completed && manifest.request.stop_after === state.stage) {
                 // A bounded run is final evidence, not an entry fixture for its successor.
                 // Stop owned observers before capture; keep the controller lease/fence.
                 await settle();
                 if (manifest.request.capture_root)
                     await captureControllerBoundary(executionContext, row, manifest, completed, null, assertPhysicalOwner);
-                setStatus("stop_target_reached");
                 setFlowRunRecoveryPaused(context, row.project_id, row.run_id, true);
-                appendEvent(context, row.controller_id, "stop_target_reached", { stage: state.stage, attempt: completed.attempt ?? null });
+                setStatus("stop_target_reached", { stage: state.stage, attempt: completed.attempt ?? null });
                 return;
             }
             if (completed && manifest.request.capture_root && ["start_stage", "terminal"].includes(next.kind)) {
@@ -763,8 +874,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);
+                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 });
@@ -777,10 +888,11 @@ 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);
                 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) {
@@ -820,7 +932,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 });
@@ -839,6 +951,8 @@ async function executeController(context, row, manifest, state, assertOwnership,
             const session = state.sessions[state.current_session];
             const baseline = new Set(state.native_baseline ?? []);
             let children = controllerNativeChildren(state.last_receipt ?? {}, session.id).filter(child => !baseline.has(child.session_id));
+            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 inspected = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
                 state.last_receipt = inspected;
@@ -941,9 +1055,28 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     continue;
                 }
             }
-            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 });
+            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)
@@ -1013,6 +1146,9 @@ async function executeController(context, row, manifest, state, assertOwnership,
     }
     finally {
         clearInterval(monitor);
+        const drainedObservations = [...childObservers.values()].map(retained => retained.close());
+        observationCancellation.abort();
+        await Promise.allSettled(drainedObservations);
         if (stopping)
             await stopping;
         observer.db.close?.();

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 { 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]))