@deksden-com/dd-flow-cli 0.9.0-beta.152 → 0.9.0-beta.156

package/dist/services/run-controller.js

@@ -1,5 +1,6 @@
-import { assertLifecycleOutcomes, currentLifecycleFailure, managedInvocationContext, managedLifecycleCommand, awaitLifecycleInvocation, assertLifecycleInvocationCurrent } from "./lifecycle-invocations.js";
-import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { assertLifecycleOutcomes, currentLifecycleFailure, managedInvocationContext, managedLifecycleCommand, awaitLifecycleInvocation, assertLifecycleInvocationCurrent, bindControllerStageAssignment } from "./lifecycle-invocations.js";
+import { isSourceSnapshotFlow } from "../domain/source-snapshot-flows.js";
+import { isDeliveryFlow } from "../domain/delivery-flows.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
@@ -28,10 +29,10 @@ 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, prepareManagedProcessConfirmation, renewManagedProcess, finishManagedProcess, processStartedAt, processTreeIsAlive, resourceHome } from "./managed-processes.js";
+import { assertManagedProcessLease, confirmManagedProcess, prepareManagedProcessConfirmation, renewManagedProcess, finishManagedProcess, processTreeIsAlive, resourceHome } from "./managed-processes.js";
 import { managedLeaseMonitor } from "./managed-lease-monitor.js";
 import { physicalStartup } from "./physical-startup.js";
-import { readNativeDaemonState, requireManagedDaemonBinding } from "./managed-daemon-binding.js";
+import { readNativeDaemonState, requireManagedDaemonBinding, managedDaemonExecutionAbsent, managedExecutionReusable } from "./managed-daemon-binding.js";
 import { initCodexHome } from "./hooks.js";
 import { launchExternalWork } from "./external-work-launch.js";
 import { runControllerMemoryTask } from "./controller-memory-task.js";
@@ -49,11 +50,16 @@ import { capacityDelay, continueProviderCapacity, eligibleProviderChildOverload,
 import { resumeControllerSession, failControllerRecovery } from "./run-controller-recovery.js";
 import { captureControllerBoundary } from "./run-controller-capture.js";
 import { requestRunControl } from "./run-control-worker.js";
+import { recordRunControlIntent } from "./run-control.js";
 import { storageSessionId } from "./session-identity.js";
 import { RECOVERY_POLICY as CAPACITY_POLICY, nativeItemsSettled, recoveryExhausted as overloadExhausted, recoveryRefusal as refusalObservation, terminalProviderRecovery as terminalProviderOverload, normalizeRecoveryFailure } from "../harness-runtime/lib/provider-overload-policy.mjs";
 import { renderNativeChildFollowupInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
 import { childCapacityDispatchAllowed, childCapacityRecoveryDecision, closeSuccessfulChildCapacity, reconcileChildCapacity } from "./controller-child-capacity.js";
+import { completedChildRepair, reserveChildRepair } from "./controller-child-repair.js";
+import { getVnextFanoutStatus } from "./vnext-fanout.js";
 import { isObservationLoss } from "../harness-runtime/lib/operation-errors.mjs";
+import { recordTechnicalNote } from "./technical-notes.js";
+import { acceptedChildWork, acceptedChildrenRetired, controllerObligation, controllerObligationAccepted, lateNativeFailure } from "./controller-result-authority.js";
 export { resumeRunController } from "./run-controller-recovery.js";
 const preparedLaunchInputs = new WeakMap();
 function launchInputDigest(input) {
@@ -113,7 +119,7 @@ export function prepareRunControllerLaunch(context, input) {
 }
 /** 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)) {
+export async 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" });
@@ -126,7 +132,14 @@ export function retainRunControllerLaunch(context, input, prepared = prepareRunC
         return { controller: current, reused: true };
     }
     const { project, run, request, requestHash, generation, budget, routing, contexts, adapters } = prepared;
-    assertRunMutationAllowed(context, project.id, run.id, generation);
+    const assertCurrent = () => {
+        if (selection.sha256 !== launchInputDigest(input))
+            throw new AppError("runtime_request_conflict", "Controller launch changed during physical observation", 1, { effect: "no_effect" });
+        assertRunMutationAllowed(context, project.id, run.id, generation);
+        if (requireRun(context, project.id, run.id).status !== "running")
+            throw new AppError("invalid_run_state", "Managed launch requires a running logical RUN", 1);
+    };
+    const launcher = await physicalStartup(context.databaseDeadlineAt).birth(assertCurrent);
     ensureRunControllerStorage(context.db);
     const controllerId = `DRV-${crypto.randomUUID()}`;
     const root = path.join(run.run_root, "controllers", controllerId);
@@ -145,8 +158,8 @@ export function retainRunControllerLaunch(context, input, prepared = prepareRunC
     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(() => {
+        assertCurrent();
         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]);
@@ -171,7 +184,7 @@ export function retainRunControllerLaunch(context, input, prepared = prepareRunC
     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);
+    const retained = await 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)
@@ -216,7 +229,7 @@ export function runControllerStatus(context, input) {
     if (!row)
         return { ok: true, run_id: run.id, controller: null, events: [], next_cursor: input.after ?? 0 };
     const events = context.db.all("SELECT sequence, event_type, data_json, created_at FROM run_controller_events WHERE controller_id = ? AND sequence > ? ORDER BY sequence LIMIT 100", [row.controller_id, input.after ?? 0]);
-    return { ...controllerReceipt(row), events: events.map(event => ({ sequence: event.sequence, type: event.event_type, data: JSON.parse(event.data_json), at: event.created_at })), next_cursor: events.at(-1)?.sequence ?? input.after ?? 0 };
+    return { ...controllerReceipt(row, context), events: events.map(event => ({ sequence: event.sequence, type: event.event_type, data: JSON.parse(event.data_json), at: event.created_at })), next_cursor: events.at(-1)?.sequence ?? input.after ?? 0 };
 }
 export async function serveRunController(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -305,7 +318,7 @@ export async function serveRunController(context, input) {
             await resumeControllerSession(context, row, manifest, currentState, assertPhysicalOwner);
         await executeController(context, row, manifest, currentState, assertOwner, assertPhysicalOwner, async () => { await lease.ensureConfirmed(assertLeaseFence); if (currentState.merge_claim)
             await mergeLease.ensureConfirmed(assertLeaseFence); });
-        return controllerReceipt(requireController(context, row.controller_id));
+        return controllerReceipt(requireController(context, row.controller_id), context);
     }
     catch (error) {
         primaryFailure = error;
@@ -372,8 +385,7 @@ export async function serveRunController(context, input) {
             finishManagedProcess(context, { id: row.process_id, leaseToken: row.process_lease_token, state: "stopped", reason: "controller_owner_exited" });
         }
         catch (cleanup) {
-            if (!primaryFailure)
-                throw cleanup;
+            recordTechnicalNote(context, row.project_id, row.run_id, { code: "controller_resource_retirement_pending", message: "Controller execution ended; resource-registry retirement remains pending.", phase: "controller_cleanup", generation: row.generation, resource_identity: row.process_id, consequence: "cleanup_pending" });
             retainSecondary("finish_controller_process", cleanup);
         }
     }
@@ -546,6 +558,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
     };
     let lastCapture = null;
     let terminalFinalization = false;
+    let technicalPauseRequested = false;
     let fatal;
     let stopping;
     const cancellation = new AbortController();
@@ -603,6 +616,11 @@ async function executeController(context, row, manifest, state, assertOwnership,
             return Promise.resolve();
         if (retainControllerLeaseUncertainty(context, row, error))
             return Promise.resolve();
+        if (error instanceof AppError && (error.details.reconciliation_required === true || ["invocation_assignment_unproven", "invocation_outcome_pending", "invocation_receipt_timeout"].includes(error.code)) && state.current_session !== null)
+            return pauseDependency(state.sessions[state.current_session]).catch(cause => {
+                if (!(cause instanceof AppError && cause.code === "controller_technical_dependency_paused"))
+                    return stopAfterFailure(new AppError("controller_dependency_control_unavailable", "The dependency pause could not be published safely", 1, { primary: errorRecord(error), control_error: errorRecord(cause) }));
+            });
         if (stopping)
             return stopping;
         fatal = error;
@@ -637,7 +655,51 @@ async function executeController(context, row, manifest, state, assertOwnership,
             }
         });
     };
-    const call = (session, args, productive = true) => controllerAdapter(executionContext, row, manifest, session, args, productive ? assertOwner : undefined, undefined, productive ? cancellation.signal : undefined, productive ? renewLease : undefined);
+    const call = async (session, args, productive = true, operationId) => {
+        const receipt = await controllerAdapter(executionContext, row, manifest, session, args, productive ? assertOwner : undefined, operationId, productive ? cancellation.signal : undefined, productive ? renewLease : undefined);
+        const previous = state.last_receipt;
+        // A read refreshes native observations, not the already accepted engine
+        // boundary. Never copy native readiness/settlement fields from the old read.
+        return args[0] === "session" && args[1] === "inspect" && previous?.accepted_boundary && adapterSessionId(previous) === session.id
+            ? { ...receipt, accepted_boundary: previous.accepted_boundary } : receipt;
+    };
+    const note = (session, code, phase, consequence, operationId, noteState) => recordTechnicalNote(context, row.project_id, row.run_id, {
+        code, message: "The accepted result is retained independently of native session retirement or observation.", phase,
+        generation: row.generation, ...(state.stage ? { stage: state.stage } : {}), harness: runtimeHarness(session.profile),
+        resource_identity: session.state_dir, diagnostic_reference: session.state_dir, consequence, ...(operationId ? { source_operation_id: operationId } : {}), ...(noteState ? { state: noteState } : {})
+    });
+    const failedChildren = (session) => (childObserver(session)?.failed() ?? []).filter(child => {
+        if (!acceptedChildWork(context, row, runtimeHarness(session.profile), session.id, child.session_id))
+            return true;
+        note(session, "accepted_work_native_child_failed", "native_completion", "cleanup_pending", child.terminal_turn_id);
+        return false;
+    });
+    const pauseDependency = async (session, sourceOperationId) => {
+        // The control intent contains the retained productive failure; it must not
+        // require that same failure to disappear before the owner can pause it.
+        assertPhysicalOwner();
+        note(session, "native_writer_dependency_blocked", "stage_transition", "dependency_blocked");
+        const requestId = `technical:${row.controller_id}:${row.generation}:${digest([state.stage, session.state_dir]).slice(0, 20)}`;
+        const input = { projectRoot: manifest.request.project_root, runId: row.run_id, requestId, action: "pause" };
+        // Publish source binding in the same SQL transaction as the control
+        // intent. A detached worker must never observe an unlabelled pause.
+        const intent = recordRunControlIntent(executionContext, input, receipt => {
+            const current = requireController(context, row.controller_id);
+            if (current.owner_token !== row.owner_token || current.generation !== row.generation || current.process_id !== row.process_id)
+                throw new AppError("controller_owner_mismatch", "Controller changed before its technical control was recorded", 1);
+            const controlId = receipt.control_id;
+            if (typeof controlId !== "string")
+                return;
+            const prior = context.db.get("SELECT 1 FROM run_controller_events WHERE controller_id=? AND event_type='technical_dependency_paused' AND json_extract(data_json,'$.control_id')=? AND COALESCE(json_extract(data_json,'$.source_operation_id'),'')=?", [row.controller_id, controlId, sourceOperationId ?? ""]);
+            if (!prior)
+                appendEvent(context, row.controller_id, "technical_dependency_paused", { schema_id: "dd-flow/controller-dependency@1", request_id: requestId, control_id: controlId, generation: row.generation, control: receipt, state_dir: session.state_dir, ...(sourceOperationId ? { source_operation_id: sourceOperationId } : {}) });
+        });
+        if (typeof intent.control_id !== "string")
+            throw new AppError("controller_dependency_control_unavailable", "Technical control was not created", 1, { intent });
+        technicalPauseRequested = true;
+        const control = await requestRunControl(executionContext, { ...input, waitMs: 0 });
+        throw new AppError("controller_technical_dependency_paused", "Conflicting native execution requires control reconciliation before continuation", 1, { control, effect: "no_effect" });
+    };
     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 });
         const binding = requireManagedDaemonBinding(executionContext, { stateDir, projectId: row.project_id, runId: row.run_id });
@@ -661,25 +723,75 @@ async function executeController(context, row, manifest, state, assertOwnership,
         saveState(context, row, state);
         appendEvent(context, row.controller_id, "session_stopped", { session_id: session.id || null, state_dir: session.state_dir, receipt });
     };
+    const retireSession = async (session) => {
+        session.retired = true;
+        saveState(context, row, state);
+        try {
+            await stopSession(session);
+            session.cleanup_pending = false;
+            note(session, "native_session_cleanup_pending", "native_cleanup", "none", undefined, "resolved");
+            return true;
+        }
+        catch {
+            session.cleanup_pending = true;
+            saveState(context, row, state);
+            note(session, "native_session_cleanup_pending", "native_cleanup", "cleanup_pending");
+            // Full cleanup remains truthful. Only physical absence or an already
+            // accepted native execution-settlement proof permits conflicting reuse.
+            try {
+                const binding = requireManagedDaemonBinding(executionContext, { stateDir: session.state_dir, projectId: row.project_id, runId: row.run_id });
+                if (managedDaemonExecutionAbsent(executionContext, { stateDir: session.state_dir, projectId: row.project_id, runId: row.run_id }))
+                    return true;
+                return managedExecutionReusable(binding.state, runtimeHarness(session.profile));
+            }
+            catch {
+                return false;
+            }
+        }
+    };
     const settle = async () => {
-        const results = await Promise.allSettled(state.sessions.map(stopSession));
-        const failure = results.find((result) => result.status === "rejected");
-        if (failure)
-            throw failure.reason;
+        await Promise.all(state.sessions.map(retireSession));
+    };
+    const captureBoundary = async (stage, nextStage) => {
+        try {
+            await captureControllerBoundary(executionContext, row, manifest, stage, nextStage, assertPhysicalOwner);
+        }
+        catch (error) {
+            const code = String(error?.code ?? "capture_unavailable");
+            if (["controller_owner_mismatch", "controller_capture_owner_lost", "run_recovery_guarded", "run_recovery_generation_stale"].includes(code))
+                throw error;
+            recordTechnicalNote(context, row.project_id, row.run_id, { code: "boundary_capture_unavailable", message: "The Stage result is accepted; its assessment snapshot is unavailable.", phase: "assessment_capture", generation: row.generation, stage: stage.stage, ...(manifest.request.capture_root ? { diagnostic_reference: manifest.request.capture_root } : {}), consequence: "none" });
+            context.db.run("UPDATE run_controllers SET status='running',last_error_json=NULL,updated_at=? WHERE controller_id=? AND owner_token=? AND generation=? AND status IN ('capturing','capture_failed')", [context.now(), row.controller_id, row.owner_token, row.generation]);
+            // A missing report is not a failed Stage. A real unstable source still
+            // fences its dependent successor until the existing control can seal it.
+            if (nextStage && ["recovery_observation_budget_exhausted", "controller_boundary_changed", "snapshot_source_changed", "owned_inventory_changed"].includes(code) && state.current_session !== null)
+                await pauseDependency(state.sessions[state.current_session]);
+        }
     };
     const reconcilePromptPredecessor = async (session) => {
         const prior = state.last_receipt?.settlement;
+        const accepted = state.last_receipt?.accepted_boundary;
         if (!prior || typeof prior !== "object" || Array.isArray(prior) || !["pending", "blocked"].includes(String(prior.state)))
             return;
-        const receipt = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
+        const receipt = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false).catch(async (error) => {
+            if (accepted && controllerObligationAccepted(context, row, accepted) && lateNativeFailure(error, session.id))
+                await pauseDependency(session);
+            throw error;
+        });
         state.last_receipt = receipt;
         saveState(context, row, state);
         const current = receipt.settlement;
         if (current && typeof current === "object" && !Array.isArray(current) && ["pending", "blocked"].includes(String(current.state))) {
+            if (accepted && controllerObligationAccepted(context, row, accepted)) {
+                note(session, "accepted_boundary_settlement_pending", "native_observation", "cleanup_pending");
+                if (receipt.native_settled === true && receipt.settled === true)
+                    return;
+                await pauseDependency(session);
+            }
             throw new AppError("settlement_reconciliation_required", "The managed Session still has an unsettled productive predecessor", 1, { session_id: session.id, settlement: current });
         }
     };
-    const prompt = async (session, text, operationId, kind) => {
+    const prompt = async (session, text, operationId, kind, boundary = "finish", assignedWorkIds) => {
         const hitl = kind === "hitl";
         const pending = state.pending_capacity;
         if (pending && (pending.session_id !== session.id || pending.generation !== row.generation || pending.kind !== (kind ?? "stage") || operationId && operationId !== pending.root_operation_id))
@@ -687,6 +799,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
         if (!pending)
             await reconcilePromptPredecessor(session);
         const firstOperationId = pending?.root_operation_id ?? operationId ?? `${row.controller_id}:prompt:${crypto.randomUUID()}`;
+        const expectedBoundary = state.stage ? controllerObligation(context, row, state.stage, hitl ? "resume" : boundary, assignedWorkIds) : undefined;
         const hitlText = async () => {
             const answerId = firstOperationId.slice(0, -`:prompt:${row.generation}`.length);
             const answer = context.db.get("SELECT input_json,receipt_json FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND status IN ('accepted','completed')", [answerId, row.controller_id]);
@@ -732,13 +845,13 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 const dispatch = JSON.parse(retained.input_json);
                 if (![value, `${value}\n`].some(text => dispatch.prompt_sha256 === crypto.createHash("sha256").update(text).digest("hex")))
                     throw new AppError("capacity_continuation_conflict", "Retained prompt differs from continuation", 1);
-                return controllerAdapter(executionContext, row, manifest, session, dispatch.args, assertOwner, id, cancellation.signal, renewLease);
+                return controllerAdapter(executionContext, row, manifest, session, dispatch.args, assertOwner, id, cancellation.signal, renewLease, JSON.parse(retained.input_json).obligation);
             }
             const file = path.join(row.state_dir, `turn-${String(state.turns + 1).padStart(5, "0")}.md`);
             fs.writeFileSync(file, value, { flag: "wx", mode: 0o600 });
             state.turns += 1;
             saveState(context, row, state);
-            return controllerAdapter(executionContext, row, manifest, session, ["session", "prompt", "--session-id", session.id, "--prompt-file", file, ...sessionArguments(context, manifest, session)], assertOwner, id, cancellation.signal, renewLease);
+            return controllerAdapter(executionContext, row, manifest, session, ["session", "prompt", "--session-id", session.id, "--prompt-file", file, ...sessionArguments(context, manifest, session)], assertOwner, id, cancellation.signal, renewLease, expectedBoundary);
         };
         let receipt;
         try {
@@ -754,8 +867,8 @@ 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);
                 }
-                const failedChildren = childObserver(session)?.failed() ?? [];
-                if (failedChildren.length && !(kind === "child" && childCapacityDispatchAllowed(state, failedChildren, session.id, firstOperationId, digestBytes(text))))
+                const failures = failedChildren(session);
+                if (failures.length && !(kind === "child" && childCapacityDispatchAllowed(state, failures, session.id, firstOperationId, digestBytes(text))))
                     throw new AppError("fanout_dispatch_fenced", "A retained child failure forbids another coordinator dispatch", 1);
                 promptPending = true;
                 observedPromptOperation = firstOperationId;
@@ -834,14 +947,20 @@ async function executeController(context, row, manifest, state, assertOwnership,
             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 (observationGap) {
+                if (expectedBoundary && controllerObligationAccepted(context, row, expectedBoundary))
+                    note(session, "accepted_boundary_observation_gap", "native_observation", "cleanup_pending", firstOperationId);
+                else
+                    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;
         }
         catch (error) {
             if (!fatal && error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale", "controller_owner_mismatch"].includes(error.code))
                 throw error;
+            if (!fatal && lateNativeFailure(error, session.id))
+                await pauseDependency(session, firstOperationId);
             await stopAfterFailure(error);
             if (!capacityUncertain(error) && !(error instanceof AppError && error.code === "controller_lease_unconfirmed"))
                 cancellation.abort();
@@ -867,6 +986,8 @@ async function executeController(context, row, manifest, state, assertOwnership,
     monitor.unref();
     try {
         for (;;) {
+            if (technicalPauseRequested)
+                return;
             // Renewal touches the resource registry; never do it from a callback that
             // may already own the RUN writer.
             await renewLease();
@@ -901,14 +1022,22 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 }
             }
             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 (state.current_session !== null && (completed || next.stage !== state.stage)) {
+                const session = state.sessions[state.current_session], failures = failedChildren(session);
+                if (failures.length && !completed)
+                    throw new AppError("fanout_dispatch_fenced", "A retained child failure forbids advancing an unaccepted Stage", 1);
+                // The Stage gate is authoritative even for a native helper with no Work
+                // association. This does not claim that helper succeeded or stopped:
+                // normal Session retirement/predecessor reconciliation still fences writes.
+                for (const child of failures)
+                    note(session, "accepted_stage_native_child_failed", "native_completion", "cleanup_pending", child.terminal_turn_id);
+            }
             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);
+                    await captureBoundary(completed, null);
                 setFlowRunRecoveryPaused(context, row.project_id, row.run_id, true);
                 setStatus("stop_target_reached", { stage: state.stage, attempt: completed.attempt ?? null });
                 return;
@@ -916,7 +1045,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
             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);
+                    await captureBoundary(completed, next.kind === "start_stage" ? next.stage : null);
                     lastCapture = key;
                 }
             }
@@ -1016,7 +1145,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     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);
+                            await retireSession(current);
                         throw new AppError("workspace_route_changed", "RUN workspace changed during native Session preparation", 1, { effect: "no_effect", stage: next.stage });
                     }
                 };
@@ -1026,8 +1155,8 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     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) {
-                    if (session)
-                        await stopSession(session);
+                    if (session && !await retireSession(session))
+                        await pauseDependency(session);
                     await renewLease();
                     assertOwner();
                     const directory = path.join(row.state_dir, `session-${state.sessions.length + 1}`);
@@ -1072,9 +1201,10 @@ 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`);
+                bindControllerStageAssignment(executionContext, command, { controllerId: row.controller_id, sessionId: session.id, stateDir: session.state_dir, stage: next.stage, contextSha256: stageContext.sha256, ...(typeof next.attempt === "number" ? { attempt: next.attempt } : {}) });
                 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));
+                await prompt(session, controllerStageEntryPrompt(next.stage, command), undefined, undefined, "entry");
                 continue;
             }
             if (state.current_session === null)
@@ -1109,7 +1239,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
             if (reconcileChildCapacity(state, children, session.id))
                 saveState(context, row, state);
             childObserver(session)?.observeSettledChildren(children);
-            const retainedFailures = childObserver(session)?.failed() ?? [];
+            const retainedFailures = failedChildren(session);
             children = controllerNativeChildren({ descendants: [...children, ...retainedFailures] }, session.id);
             const closedChildEpisodes = closeSuccessfulChildCapacity(state, children, session.id);
             if (closedChildEpisodes.length)
@@ -1117,7 +1247,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     saveState(context, row, state);
                     appendEvent(context, row.controller_id, "capacity_child_episodes_completed", { child_session_ids: closedChildEpisodes });
                 });
-            const queuedChild = children.find(child => state.child_capacity?.[child.session_id]?.phase === "native_message_accepted"
+            const queuedChild = children.find(child => !acceptedChildWork(context, row, childHarness, session.id, child.session_id) && state.child_capacity?.[child.session_id]?.phase === "native_message_accepted"
                 && (child.status === "failed" && state.child_capacity[child.session_id].turn_id === child.terminal_turn_id
                     || child.status === "running" && child.continuation_admission?.proof_kind === "parent_tool_admission"));
             if (queuedChild) {
@@ -1145,12 +1275,12 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 saveState(context, row, state);
                 continue;
             }
-            if (children.some(child => child.status === "failed" && renderNativeChildFollowupInstruction(childHarness, child))) {
+            if (children.some(child => child.status === "failed" && !acceptedChildWork(context, row, childHarness, session.id, child.session_id) && renderNativeChildFollowupInstruction(childHarness, child))) {
                 const inspected = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
                 state.last_receipt = inspected;
                 saveState(context, row, state);
                 children = controllerNativeChildren(inspected, session.id).filter(child => !baseline.has(child.session_id));
-                const failed = children.filter(child => child.status === "failed");
+                const failed = children.filter(child => child.status === "failed" && !acceptedChildWork(context, row, childHarness, session.id, child.session_id));
                 // 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 => eligibleProviderChildOverload(item, session.id))) {
@@ -1268,8 +1398,51 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     continue;
                 }
             }
-            const memoryFlow = ["mb-init", "mb-upgrade"].includes(run.flow_kind) || isDiagnosticFlow(run.flow_kind);
-            const fanoutInput = { projectRoot: run.project_root, runId: run.id, stage: next.stage, harness: runtimeHarness(session.profile), sessionId: session.id, children, policy, profiles, dispatchFence: retainedFailures.length > 0 };
+            const repairBlockedWorks = [];
+            if (!retainedFailures.length && children.some(child => child.status === "completed" && !acceptedChildWork(context, row, childHarness, session.id, 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);
+                children = controllerNativeChildren(inspected, session.id).filter(child => !baseline.has(child.session_id));
+                // Do not compete with an active parent/healthy sibling or turn a known
+                // repair into a replacement fanout wave.
+                if (inspected.settled !== true || children.some(child => ["running", "unknown"].includes(child.status))) {
+                    setStatus("waiting_for_children");
+                    await delay(1000, undefined, { signal: cancellation.signal });
+                    continue;
+                }
+                let repair = null;
+                const blockers = [];
+                for (const child of children) {
+                    try {
+                        repair ??= completedChildRepair(executionContext, row, { stage: next.stage, harness: childHarness, parentId: session.id, children: [child] });
+                    }
+                    catch (error) {
+                        if (!(error instanceof AppError) || error.code !== "child_work_repair_blocked")
+                            throw error;
+                        blockers.push(error);
+                    }
+                }
+                if (repair) {
+                    reserveChildRepair(executionContext, row, repair, assertOwner);
+                    await prompt(session, repair.prompt, repair.operation_id, undefined, "work", [repair.work_id]);
+                    continue;
+                }
+                if (blockers.length) {
+                    const graph = getVnextFanoutStatus(executionContext, { projectRoot: run.project_root, runId: run.id, stage: next.stage }).orchestration;
+                    if (!graph?.works.ready.length)
+                        throw blockers[0];
+                    for (const blocker of blockers) {
+                        const workId = String(blocker.details.work_id);
+                        repairBlockedWorks.push(workId);
+                        recordTechnicalNote(context, row.project_id, row.run_id, { code: "child_work_repair_blocked", message: blocker.message,
+                            phase: "work_repair", generation: row.generation, stage: next.stage, work_id: workId, harness: childHarness,
+                            resource_identity: workId, consequence: "dependency_blocked", diagnostic_reference: String(blocker.details.reason) });
+                    }
+                }
+            }
+            const memoryFlow = ["mb-init", "mb-upgrade", "mb-fix", "interactive"].includes(run.flow_kind) || isSourceSnapshotFlow(run.flow_kind) || routing.kind === "descriptor" && isDeliveryFlow(run.flow_kind);
+            const fanoutInput = { projectRoot: run.project_root, runId: run.id, stage: next.stage, harness: runtimeHarness(session.profile), sessionId: session.id, children, policy, profiles, dispatchFence: retainedFailures.length > 0, repairBlockedWorks };
             const fanout = memoryFlow ? await runControllerMemoryTask(executionContext, { operation: "fanout", input: fanoutInput }, cancellation.signal)
                 : await nextControllerFanout(executionContext, fanoutInput);
             if (memoryFlow)
@@ -1302,6 +1475,29 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 throw new AppError("incomplete_subject_turn", "Managed Turn ended without a completed Stage or declared continuation", 1, { stage: next.stage });
             }
             if (fanout.kind === "wait") {
+                if (fanout.reason === "accepted_work_native_cleanup") {
+                    const pending = children.filter(child => ["running", "unknown"].includes(child.status) && acceptedChildWork(context, row, childHarness, session.id, child.session_id));
+                    for (const child of pending) {
+                        note(session, "accepted_work_native_child_pending", "native_completion", "cleanup_pending", child.session_id);
+                        try {
+                            await call(session, ["session", "cancel", "--session-id", child.session_id, ...sessionArguments(context, manifest, session)], false);
+                        }
+                        catch {
+                            await pauseDependency(session);
+                        }
+                    }
+                    const operationId = `${row.controller_id}:child-retirement:${crypto.randomUUID()}`;
+                    const observed = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false, operationId).catch(async (error) => {
+                        if (lateNativeFailure(error, session.id))
+                            await pauseDependency(session);
+                        throw error;
+                    });
+                    state.last_receipt = observed;
+                    saveState(context, row, state);
+                    if (!acceptedChildrenRetired(pending.map(child => child.session_id), observed, session.id, operationId))
+                        await pauseDependency(session);
+                    continue;
+                }
                 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, ...sessionArguments(context, manifest, session)], false);
@@ -1310,6 +1506,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
             }
             setStatus("running");
             if (fanout.kind === "external") {
+                let cleanupConflict = false;
                 const results = await Promise.allSettled(fanout.works.map(async (work) => {
                     try {
                         await renewLease();
@@ -1329,18 +1526,32 @@ async function executeController(context, row, manifest, state, assertOwnership,
                             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 });
+                        try {
+                            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 {
+                            recordTechnicalNote(context, row.project_id, row.run_id, { code: "external_work_cleanup_pending", message: "The Work outcome is committed; its native resources require retirement.", phase: "external_work_cleanup", generation: row.generation, stage: next.stage, work_id: work.work_id, harness: runtimeHarness(resolved.worker), resource_identity: launch.state_dir, diagnostic_reference: launch.state_dir, source_operation_id: `${row.controller_id}:${work.work_id}:settle`, consequence: "cleanup_pending" });
+                            try {
+                                cleanupConflict ||= !managedDaemonExecutionAbsent(executionContext, { stateDir: launch.state_dir, projectId: row.project_id, runId: row.run_id });
+                            }
+                            catch {
+                                cleanupConflict = true;
+                            }
+                        }
                     }
                     catch (error) {
-                        await stopAfterFailure(error);
+                        if (!(error instanceof AppError && error.code === "controller_technical_dependency_paused"))
+                            await stopAfterFailure(error);
                         throw error;
                     }
                 }));
                 const rejected = results.find((result) => result.status === "rejected");
                 if (rejected)
                     throw fatal ?? rejected.reason;
+                if (cleanupConflict)
+                    await pauseDependency(session);
                 state.last_continuation = null;
                 saveState(context, row, state);
                 continue;
@@ -1349,10 +1560,12 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 assertNoCorrelatedRejection(context, { projectId: row.project_id, runId: row.run_id, generation: row.generation, stage: next.stage, turn: state.turns });
             retainControllerContinuation(state, fanout.fingerprint, { code: "fanout_stage_nonprogressing", message: "The coordinator repeated an unchanged Work-graph continuation", details: { stage: next.stage, action: fanout.action, before: state.last_continuation, after: fanout.fingerprint, controller_turn: state.turns } });
             saveState(context, row, state);
-            await prompt(session, fanout.prompt);
+            await prompt(session, fanout.prompt, undefined, undefined, fanout.action === "materialize_graph" ? "graph" : fanout.action === "dispatch_work" ? "work" : "finish", fanout.work_ids);
         }
     }
     catch (error) {
+        if (technicalPauseRequested || error instanceof AppError && error.code === "controller_technical_dependency_paused")
+            return;
         if (!fatal && error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale", "controller_owner_mismatch"].includes(error.code))
             throw error;
         let cause = fatal ?? error;