@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.140

package/dist/services/run-controller.js

@@ -0,0 +1,1205 @@
+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";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { quote } from "shell-quote";
+import { ensureRunControllerStorage, getDatabase } from "../storage/database.js";
+import { canonicalPath, resolveProjectRoot } from "../storage/paths.js";
+import { publishImmutableInput } from "../storage/immutable-input.js";
+import { AppError } from "../shared/errors.js";
+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, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { loadExternalStageContext } from "./stage-context.js";
+import { flowCommand } from "./stage-pause.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";
+import { managedLeaseMonitor } from "./managed-lease-monitor.js";
+import { readNativeDaemonState, requireManagedDaemonBinding } from "./managed-daemon-binding.js";
+import { initCodexHome } from "./hooks.js";
+import { launchExternalWork } from "./external-work-launch.js";
+import { controllerNativeChildren, controllerStageEntryPrompt, controllerStageResumePrompt, nextControllerFanout } from "./controller-fanout.js";
+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, assertControllerLeaseAllowed } from "./run-controller-process.js";
+import { controllerAdapter, controllerEnvironment, sessionArguments } from "./run-controller-adapter.js";
+import { retainedChildObserver } from "./controller-child-observer.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, 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);
+    if (input.stopAfter !== undefined && !/^[a-z][a-z-]*$/.test(input.stopAfter))
+        throw new AppError("usage", "Invalid stop-after stage", 2);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    const captureRoot = input.captureRoot === undefined ? undefined : canonicalPath(input.captureRoot, false);
+    if (captureRoot && [context.ddFlowHome, project.root, run.workspace_root].some(root => { const relative = path.relative(canonicalPath(root, false), captureRoot); return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative); }))
+        throw new AppError("snapshot_output_inside_runtime", "Controller captures require a root outside the runtime, project and workspace", 2);
+    if (captureRoot && fs.existsSync(captureRoot) && !fs.statSync(captureRoot).isDirectory())
+        throw new AppError("usage", "Controller capture root must be a directory", 2);
+    const budget = parseRuntimeBudget(context.env.DD_FLOW_RUNTIME_BUDGET);
+    const request = { project_root: project.root, run_id: run.id, context_sha256: input.contextSha256, stop_after: input.stopAfter ?? null, ...(captureRoot ? { capture_root: captureRoot } : {}), ...(budget ? { budget_sha256: digest(budget) } : {}) };
+    const requestHash = digest(request);
+    const existing = context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controllers'")
+        ? context.db.get("SELECT * FROM run_controllers WHERE project_id = ? AND run_id = ? AND request_id = ?", [project.id, run.id, input.requestId]) : undefined;
+    if (existing) {
+        if (existing.request_hash !== requestHash)
+            throw new AppError("runtime_request_conflict", "Managed launch request id has different inputs", 1);
+        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 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(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);
+    const prepared = { kind: "create", project, run, request, requestHash, generation, budget, routing, contexts, adapters };
+    preparedLaunchInputs.set(prepared, { home: context.ddFlowHome, sha256: launchInputDigest(input) });
+    return 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, 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: 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 duplicate;
+        }
+        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 owner = context.db.get("SELECT * FROM run_controllers WHERE project_id = ? AND run_id = ? AND status NOT IN ('completed','cancelled','superseded')", [project.id, run.id]);
+        if (owner)
+            throw new AppError("controller_already_owned", "RUN already has an unresolved managed owner; observe or reconcile it", 1, { controller_id: owner.controller_id });
+        if (context.db.get("SELECT 1 FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.status = 'running' LIMIT 1", [project.id, run.id]))
+            throw new AppError("controller_attach_required", "A WorkSession acquired the RUN before managed launch", 1);
+        context.db.run("INSERT INTO run_controllers (controller_id, project_id, run_id, request_id, request_hash, generation, status, owner_token, manifest_json, state_json, state_dir, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, 'starting', ?, ?, ?, ?, ?, ?)", [controllerId, project.id, run.id, input.requestId, requestHash, generation, token, JSON.stringify(manifest), JSON.stringify(state), root, now, now]);
+        recordControllerLauncher(context, requireController(context, controllerId), undefined, launcher);
+        appendEvent(context, controllerId, "launch_requested", { request_id: input.requestId, generation, request_hash: requestHash });
+        return null;
+    });
+    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
+ * owns SQLite's writer lock.  That is not evidence that this controller lost
+ * its lease.  Productive dispatch still requires a successful recheck before
+ * proceeding, while an explicit negative renewal remains a hard ownership
+ * loss.
+ */
+export const controllerLeaseMonitor = managedLeaseMonitor;
+/** Unconfirmed ownership is not evidence authorizing a native cancellation. */
+export function retainControllerLeaseUncertainty(context, row, error) {
+    if (!(error instanceof AppError) || error.code !== "controller_lease_unconfirmed")
+        return false;
+    try {
+        const db = context.db.withDeadline(Date.now() + 5_000);
+        db.writeTransaction(() => {
+            const changed = db.run("UPDATE run_controllers SET status = CASE WHEN status IN ('capturing','capture_failed') THEN 'capture_failed' ELSE 'recovery_required' END, last_error_json = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ? AND generation = ? AND status NOT IN ('completed','cancelled','superseded','recovery_required','capture_failed')", [JSON.stringify(errorRecord(error)), context.now(), row.controller_id, row.owner_token, row.generation]);
+            if (changed.changes)
+                appendEvent({ ...context, db }, row.controller_id, "owner_confirmation_required", { ...errorRecord(error), native_cancelled: false });
+        });
+    }
+    catch (persistence) {
+        process.stderr.write(`${JSON.stringify({ controller_id: row.controller_id, primary: errorRecord(error), persistence: errorRecord(persistence), native_cancelled: false })}\n`);
+    }
+    return true;
+}
+/** No initialization, provider calls or lease takeover on the observation path. */
+export function runControllerStatus(context, input) {
+    if (input.after !== undefined && (!Number.isSafeInteger(input.after) || input.after < 0))
+        throw new AppError("usage", "--after must be a non-negative cursor", 2);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    if (!context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controllers'"))
+        return { ok: true, run_id: run.id, controller: null, events: [], next_cursor: input.after ?? 0 };
+    const row = context.db.get("SELECT * FROM run_controllers WHERE project_id = ? AND run_id = ? ORDER BY created_at DESC, controller_id DESC LIMIT 1", [project.id, run.id]);
+    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 };
+}
+export async function serveRunController(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const row = requireController(context, input.controllerId);
+    if (row.project_id !== project.id || row.run_id !== input.runId || row.owner_token !== context.env.DD_FLOW_CONTROLLER_TOKEN)
+        throw new AppError("controller_owner_mismatch", "Managed serve does not own this launch", 1);
+    claimControllerProcess(context, row);
+    if (!row.process_id || !row.process_lease_token)
+        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 => {
+        const expiry = new Date(Date.now() + 120_000).toISOString();
+        const db = context.db.withDeadline(Date.now() + attemptMs);
+        if (db.get("SELECT 1 FROM merge_requests WHERE project_id = ? AND run_id = ? AND dispatch_owner = ? AND status = 'dispatching' LIMIT 1", [row.project_id, row.run_id, row.controller_id]))
+            db.writeTransaction(() => {
+                const guard = recoveryGuard({ ...context, db }, row.project_id, row.run_id);
+                if ((guard?.generation ?? 0) !== row.generation || ["draining", "sealed", "resuming"].includes(guard?.status ?? ""))
+                    throw new AppError("controller_lease_lost", "RUN generation changed before MERGE keepalive", 1);
+                db.run("UPDATE merge_requests SET dispatch_lease_expires_at = ?, updated_at = ? WHERE project_id = ? AND run_id = ? AND dispatch_owner = ? AND status = 'dispatching'", [expiry, context.now(), row.project_id, row.run_id, row.controller_id]);
+            });
+        return { owned: true, lease_expires_at: expiry };
+    });
+    const assertLeaseFence = () => {
+        assertControllerLeaseAllowed(context, row);
+    };
+    const heartbeat = setInterval(() => {
+        lease.background(assertLeaseFence, () => { });
+        if (state.merge_claim)
+            mergeLease.background(assertLeaseFence, () => { });
+    }, 30_000);
+    heartbeat.unref();
+    const manifest = JSON.parse(row.manifest_json);
+    const assertPhysicalOwner = () => {
+        lease.assertNoRenewal();
+        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);
+    };
+    const assertOwner = () => { assertPhysicalOwner(); assertRunMutationAllowed(context, row.project_id, row.run_id, row.generation); };
+    let primaryFailure;
+    const retainSecondary = (phase, error) => {
+        process.stderr.write(`${JSON.stringify({ controller_id: row.controller_id, phase, primary: errorRecord(primaryFailure), secondary: errorRecord(error) })}\n`);
+    };
+    try {
+        await lease.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")
+                setFlowRunRecoveryPaused(context, row.project_id, row.run_id, false);
+        });
+        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); if (state.merge_claim)
+            await mergeLease.ensureConfirmed(assertLeaseFence); });
+        return controllerReceipt(requireController(context, row.controller_id));
+    }
+    catch (error) {
+        primaryFailure = error;
+        try {
+            try {
+                failControllerRecovery(context, row, state, error);
+            }
+            catch (secondary) {
+                retainSecondary("fail_controller_recovery", secondary);
+            }
+            if ((error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale"].includes(error.code) || (recoveryGuard(context, row.project_id, row.run_id)?.generation ?? 0) !== row.generation)
+                && context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controls'")) {
+                const guard = recoveryGuard(context, row.project_id, row.run_id);
+                const control = guard && ["draining", "sealed"].includes(guard.status) && context.db.get("SELECT control_id, action FROM run_controls WHERE project_id = ? AND run_id = ? AND recovery_id = ? AND status IN ('requested','settled')", [row.project_id, row.run_id, guard.recovery_id]);
+                if (control) {
+                    // Control is a later state transition, not evidence that the causal
+                    // failure which fenced admission disappeared.
+                    context.db.run("UPDATE run_controllers SET status = CASE WHEN last_error_json IS NULL THEN 'control_requested' ELSE status END, updated_at = ? WHERE controller_id = ? AND owner_token = ?", [context.now(), row.controller_id, row.owner_token]);
+                    appendEvent(context, row.controller_id, "control_boundary_reached", { control_id: control.control_id, action: control.action, generation: guard.generation, settled: false });
+                    return controllerReceipt(requireController(context, row.controller_id));
+                }
+            }
+            try {
+                context.db.writeTransaction(() => {
+                    // A failed capture must not reopen admission when this process exits.
+                    const changed = context.db.run("UPDATE run_controllers SET status = CASE WHEN status IN ('capturing','capture_failed') THEN 'capture_failed' ELSE 'recovery_required' END, last_error_json = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ? AND status NOT IN ('completed','cancelled','superseded')", [JSON.stringify(errorRecord(error)), context.now(), row.controller_id, row.owner_token]);
+                    context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE project_id = ? AND run_id = ? AND dispatch_owner = ? AND status IN ('dispatching','active')", [JSON.stringify(errorRecord(error)), context.now(), row.project_id, row.run_id, row.controller_id]);
+                    if (changed.changes && (recoveryGuard(context, row.project_id, row.run_id)?.generation ?? 0) === row.generation) {
+                        setFlowRunRecoveryPaused(context, row.project_id, row.run_id, true);
+                    }
+                    appendEvent(context, row.controller_id, "recovery_required", errorRecord(error));
+                });
+            }
+            catch (failure) {
+                retainSecondary("persist_controller_failure", failure);
+            }
+        }
+        catch (secondary) {
+            retainSecondary("controller_failure_boundary", secondary);
+        }
+        throw error;
+    }
+    finally {
+        lease.close();
+        mergeLease.close();
+        clearInterval(heartbeat);
+        finishOwner();
+    }
+    function finishOwner() {
+        try {
+            finishManagedProcess(context, { id: row.process_id, leaseToken: row.process_lease_token, state: "stopped", reason: "controller_owner_exited" });
+        }
+        catch (cleanup) {
+            if (!primaryFailure)
+                throw cleanup;
+            retainSecondary("finish_controller_process", cleanup);
+        }
+    }
+}
+export function prepareRunControllerAnswer(context, input) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(input.requestId) || !input.pauseId.trim())
+        throw new AppError("usage", "Answer requires request-id and pause-id", 2);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const prior = context.db.get(`SELECT o.operation_id, o.status, o.input_json
+    FROM run_controller_operations o JOIN run_controllers c ON c.controller_id = o.controller_id
+    WHERE c.project_id = ? AND c.run_id = ? AND o.operation_id = c.controller_id || ':answer:' || ?`, [project.id, input.runId, input.requestId]);
+    if (prior) {
+        const retained = JSON.parse(prior.input_json);
+        if (retained.pause_id !== input.pauseId)
+            throw new AppError("runtime_request_conflict", "HITL answer request id belongs to another pause", 1, { operation_id: prior.operation_id });
+        return { kind: "replay", operationId: prior.operation_id, status: prior.status };
+    }
+    const { bytes } = prepareFileBytes(input.answerFile, "HITL answer");
+    if (!bytes.toString("utf8").trim())
+        throw new AppError("validation", "HITL answer must not be empty", 2);
+    const row = context.db.get("SELECT * FROM run_controllers WHERE project_id = ? AND run_id = ? AND status NOT IN ('completed','cancelled','superseded')", [project.id, input.runId]);
+    if (!row)
+        throw new AppError("not_found", "RUN has no managed controller for this answer", 1);
+    const operationId = `${row.controller_id}:answer:${input.requestId}`;
+    const answerHash = digestBytes(bytes);
+    const hash = digest({ pause_id: input.pauseId, answer_sha256: answerHash });
+    const previous = prepareControllerAnswerAcceptance(context, input, project.id, row, operationId, hash);
+    if (previous.prior)
+        return { kind: "replay", operationId, status: previous.prior.status };
+    return { kind: "create", project, row, bytes, operationId, answerHash, hash };
+}
+function prepareControllerAnswerAcceptance(context, input, projectId, row, operationId, hash) {
+    const prior = context.db.get("SELECT input_hash, status FROM run_controller_operations WHERE operation_id = ?", [operationId]);
+    if (prior) {
+        if (prior.input_hash !== hash)
+            throw new AppError("runtime_request_conflict", "HITL answer request id has different raw input", 1);
+        return { prior };
+    }
+    const currentOwner = requireController(context, row.controller_id);
+    if (["completed", "cancelled", "superseded"].includes(currentOwner.status))
+        throw new AppError("invalid_run_state", "The answer's controller is no longer current", 1);
+    const competing = context.db.get("SELECT operation_id FROM run_controller_operations WHERE controller_id = ? AND json_extract(input_json, '$.action') = 'user_answer' AND json_extract(input_json, '$.pause_id') = ? LIMIT 1", [row.controller_id, input.pauseId]);
+    if (competing)
+        throw new AppError("runtime_request_conflict", "This HITL pause already has an accepted answer", 1, { operation_id: competing.operation_id });
+    const run = requireRun(context, projectId, input.runId);
+    if (["done", "failed", "cancelled"].includes(run.status))
+        throw new AppError("invalid_run_state", "A terminal RUN cannot accept a new answer", 1);
+    const index = JSON.parse(run.index_json);
+    const stage = index.stage_runs.find(stage => stage.pause?.id === input.pauseId && ["paused", "waiting_for_user"].includes(stage.status));
+    if (!stage?.pause?.work_id)
+        throw new AppError("hitl_pause_mismatch", "Answer does not match the RUN's current HITL pause", 1);
+    return { run, stage, workId: stage.pause.work_id };
+}
+export function answerRunController(context, input, prepared = prepareRunControllerAnswer(context, input)) {
+    if (prepared.kind === "replay")
+        return { ok: true, operation_id: prepared.operationId, status: prepared.status, reused: true };
+    const { project, row, bytes, operationId, answerHash, hash } = prepared;
+    const previous = prepareControllerAnswerAcceptance(context, input, project.id, row, operationId, hash);
+    if (previous.prior)
+        return { ok: true, operation_id: operationId, status: previous.prior.status, reused: true };
+    const file = path.join(row.state_dir, `answer-${digest(operationId)}-${answerHash}.md`);
+    publishImmutableInput(file, bytes, "runtime_request_conflict");
+    return context.db.writeTransaction(() => {
+        // Recheck only mutable acceptance state under the write transaction; bytes are already prepared.
+        const acceptance = prepareControllerAnswerAcceptance(context, input, project.id, row, operationId, hash);
+        if (acceptance.prior) {
+            return { ok: true, operation_id: operationId, status: acceptance.prior.status, reused: true };
+        }
+        const { run, stage, workId } = acceptance;
+        if (requireController(context, row.controller_id).state_dir !== row.state_dir)
+            throw new AppError("controller_owner_mismatch", "Controller input directory changed before acceptance", 1);
+        const now = context.now();
+        const generation = recoveryGuard(context, project.id, run.id)?.generation ?? row.generation;
+        context.db.run("INSERT INTO run_controller_operations (operation_id, controller_id, generation, input_hash, input_json, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'accepted', ?, ?)", [operationId, row.controller_id, generation, hash, JSON.stringify({ action: "user_answer", pause_id: input.pauseId, stage: stage.stage, work_id: workId, file, sha256: answerHash }), now, now]);
+        appendEvent(context, row.controller_id, "answer_accepted", { operation_id: operationId, pause_id: input.pauseId, answer_sha256: answerHash });
+        return { ok: true, operation_id: operationId, status: "accepted" };
+    });
+}
+export function prepareRunControllerContext(context, input) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(input.requestId) || !/^[a-z][a-z-]*$/.test(input.stage) || !/^[a-f0-9]{64}$/.test(input.contextSha256))
+        throw new AppError("usage", "Context submission requires request id, stage and SHA-256", 2);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const operationId = `${input.controllerId}:context:${input.requestId}`;
+    const hash = digest({ stage: input.stage, sha256: input.contextSha256 });
+    const row = requireController(context, input.controllerId);
+    if (row.project_id !== project.id || row.run_id !== input.runId)
+        throw new AppError("controller_owner_mismatch", "Context submission belongs to another RUN", 1);
+    const prior = context.db.get("SELECT input_hash, status FROM run_controller_operations WHERE operation_id = ?", [operationId]);
+    if (prior) {
+        if (prior.input_hash !== hash)
+            throw new AppError("runtime_request_conflict", "Context request id has different inputs", 1);
+        return { kind: "replay", operationId, status: prior.status };
+    }
+    availableControllerContext(context, input, row);
+    const { bytes } = loadExternalStageContext({ file: input.contextFile, expectedSha256: input.contextSha256, stage: input.stage });
+    return { kind: "create", project, operationId, hash, bytes };
+}
+export function supplyRunControllerContext(context, input, prepared = prepareRunControllerContext(context, input)) {
+    if (prepared.kind === "replay")
+        return { ok: true, operation_id: prepared.operationId, status: prepared.status, reused: true };
+    const { project, operationId, hash, bytes } = prepared;
+    const preparedOwner = requireController(context, input.controllerId);
+    if (preparedOwner.project_id !== project.id || preparedOwner.run_id !== input.runId)
+        throw new AppError("controller_owner_mismatch", "Context submission belongs to another RUN", 1);
+    const existing = context.db.get("SELECT input_hash, status FROM run_controller_operations WHERE operation_id = ?", [operationId]);
+    if (existing) {
+        if (existing.input_hash !== hash)
+            throw new AppError("runtime_request_conflict", "Context request id has different inputs", 1);
+        return { ok: true, operation_id: operationId, status: existing.status, reused: true };
+    }
+    availableControllerContext(context, input, preparedOwner);
+    const file = path.join(preparedOwner.state_dir, `${input.stage}-${input.contextSha256}.context.json`);
+    publishImmutableInput(file, bytes, "stage_context_replacement");
+    return context.db.writeTransaction(() => {
+        const row = requireController(context, input.controllerId);
+        if (row.project_id !== project.id || row.run_id !== input.runId)
+            throw new AppError("controller_owner_mismatch", "Context submission belongs to another RUN", 1);
+        const prior = context.db.get("SELECT input_hash, status FROM run_controller_operations WHERE operation_id = ?", [operationId]);
+        if (prior) {
+            if (prior.input_hash !== hash)
+                throw new AppError("runtime_request_conflict", "Context request id has different inputs", 1);
+            return { ok: true, operation_id: operationId, status: prior.status, reused: true };
+        }
+        const manifest = availableControllerContext(context, input, row);
+        if (row.state_dir !== preparedOwner.state_dir)
+            throw new AppError("controller_owner_mismatch", "Controller input directory changed before acceptance", 1);
+        manifest.contexts[input.stage] = { file, sha256: input.contextSha256 };
+        const now = context.now();
+        context.db.run("UPDATE run_controllers SET manifest_json = ?, updated_at = ? WHERE controller_id = ?", [JSON.stringify(manifest), now, row.controller_id]);
+        context.db.run("INSERT INTO run_controller_operations (operation_id, controller_id, generation, input_hash, input_json, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'accepted', ?, ?)", [operationId, row.controller_id, row.generation, hash, JSON.stringify({ action: "stage_context", stage: input.stage, file, sha256: input.contextSha256 }), now, now]);
+        appendEvent(context, row.controller_id, "context_accepted", { operation_id: operationId, stage: input.stage, context_sha256: input.contextSha256 });
+        return { ok: true, operation_id: operationId, status: "accepted" };
+    });
+}
+function availableControllerContext(context, input, row) {
+    assertRunMutationAllowed(context, row.project_id, input.runId, row.generation);
+    if (!["starting", "running", "waiting_for_context", "waiting_for_user", "waiting_for_children", "waiting_for_capacity", "waiting_for_merge"].includes(row.status))
+        throw new AppError("invalid_run_state", "Controller cannot accept a new context in its current state", 1);
+    const manifest = JSON.parse(row.manifest_json);
+    if (manifest.contexts[input.stage])
+        throw new AppError("stage_context_replacement", "Controller already has an immutable context for this stage", 1);
+    return manifest;
+}
+async function executeController(context, row, manifest, state, assertOwnership, assertPhysicalOwner, renewLease) {
+    assertOwnership();
+    const observer = { ...context, db: getDatabase(context.ddFlowHome, "read_existing") };
+    const checkOutcomes = () => assertLifecycleOutcomes(observer, { projectRoot: manifest.request.project_root, runId: row.run_id, generation: row.generation });
+    const assertOwner = () => { if (fatal)
+        throw fatal; checkOutcomes(); assertOwnership(); };
+    const prepareMutation = async (action) => {
+        for (;;) {
+            await renewLease();
+            try {
+                context.db.writeTransaction(() => { assertOwner(); action(); });
+                return;
+            }
+            catch (error) {
+                if (!(error instanceof AppError) || error.code !== "controller_lease_unconfirmed")
+                    throw error;
+            }
+        }
+    };
+    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,
+            projectRoot: manifest.request.project_root, runId: row.run_id, generation: row.generation });
+    };
+    let lastCapture = null;
+    let terminalFinalization = false;
+    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
+        // uncertainty; cancellation is not evidence of its missing outcome.
+        if (capacityUncertain(error))
+            return Promise.resolve();
+        if (retainControllerLeaseUncertainty(context, row, error))
+            return Promise.resolve();
+        if (stopping)
+            return stopping;
+        fatal = error;
+        // Persist the cause before fencing/cancellation; later control is not an
+        // operator pause and cannot replace this execution failure.
+        stopping = (async () => {
+            try {
+                context.db.run("UPDATE run_controllers SET status = CASE WHEN status IN ('capturing','capture_failed') THEN 'capture_failed' ELSE 'recovery_required' END, last_error_json = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ?", [JSON.stringify(errorRecord(error)), context.now(), row.controller_id, row.owner_token]);
+            }
+            catch (persistence) {
+                process.stderr.write(`${JSON.stringify({ primary: errorRecord(error), persistence: errorRecord(persistence) })}\n`);
+            }
+            await requestRunControl(executionContext, { projectRoot: manifest.request.project_root, runId: row.run_id, requestId: `fatal:${row.controller_id}:${row.generation}`, action: "stop", waitMs: 0 });
+        })().catch(cleanup => {
+            // The caller still receives the primary failure if control cannot start.
+            try {
+                appendEvent(context, row.controller_id, "failure_control_error", { primary: errorRecord(error), cleanup: errorRecord(cleanup) });
+            }
+            catch {
+                process.stderr.write(`${JSON.stringify({ primary: errorRecord(error), cleanup: errorRecord(cleanup) })}\n`);
+            }
+        }).finally(() => cancellation.abort());
+        return stopping;
+    };
+    const setStatus = (status, 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) => {
+        const fail = () => new AppError("controller_native_shutdown_unproven", "The managed daemon is not proven clean and closed", 1, { state_dir: stateDir, receipt });
+        if (receipt.stopped !== true || receipt.clean !== true)
+            throw fail();
+        const binding = requireManagedDaemonBinding(executionContext, { stateDir, projectId: row.project_id, runId: row.run_id });
+        const deadline = performance.now() + 30_000;
+        while (processTreeIsAlive(binding.process) && performance.now() < deadline)
+            await delay(100);
+        const current = readNativeDaemonState(stateDir);
+        if (processTreeIsAlive(binding.process) || current.shutdown_state !== "clean"
+            || current.pid !== binding.process.pid || (current.daemon_id ?? current.config?.daemonId) !== (binding.state.daemon_id ?? binding.state.config?.daemonId)
+            || current.resource_process?.id !== binding.process.id || current.resource_process?.lease_token !== binding.process.lease_token)
+            throw fail();
+    };
+    const stopSession = async (session) => {
+        if (session.stopped)
+            return;
+        const receipt = await call(session, ["daemon", "stop", "--state-dir", session.state_dir, "--json"], false);
+        await confirmStopped(session.state_dir, receipt);
+        session.stopped = true;
+        saveState(context, row, state);
+        appendEvent(context, row.controller_id, "session_stopped", { session_id: session.id || null, state_dir: session.state_dir, receipt });
+    };
+    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;
+    };
+    const reconcilePromptPredecessor = async (session) => {
+        const prior = state.last_receipt?.settlement;
+        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);
+        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))) {
+            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 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))
+            throw new AppError("capacity_continuation_conflict", "Retained capacity owner reference differs from its Session/task", 1);
+        if (!pending)
+            await reconcilePromptPredecessor(session);
+        const firstOperationId = pending?.root_operation_id ?? operationId ?? `${row.controller_id}:prompt:${crypto.randomUUID()}`;
+        const send = (value, id) => {
+            const retained = context.db.get("SELECT input_json FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND generation = ?", [id, row.controller_id, row.generation]);
+            if (retained) {
+                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);
+            }
+            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);
+        };
+        let receipt;
+        try {
+            try {
+                if (pending) {
+                    const predecessor = context.db.get("SELECT error_json FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND generation = ? AND status = 'failed'", [pending.predecessor, row.controller_id, row.generation]);
+                    if (!predecessor?.error_json)
+                        throw new AppError("capacity_continuation_conflict", "Retained capacity predecessor has no failure receipt", 1);
+                    // The root identifies the whole chain; inspect its frozen failure,
+                    // then reconcile all retained successors before any dispatch.
+                    const root = context.db.get("SELECT error_json FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND generation = ?", [firstOperationId, row.controller_id, row.generation]);
+                    if (!root?.error_json)
+                        throw new AppError("capacity_continuation_conflict", "Retained capacity root has no failure receipt", 1);
+                    throw JSON.parse(root.error_json);
+                }
+                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) {
+                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 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])
+                        .flatMap(item => { const retained = JSON.parse(item.receipt_json || "null"); return retained?.capacity_root === firstOperationId && retained.capacity_failure ? [retained.capacity_failure] : []; }),
+                    retainFailure: (id, refusal) => {
+                        const changed = context.db.run("UPDATE run_controller_operations SET receipt_json = ?, updated_at = ? WHERE operation_id = ? AND controller_id = ? AND generation = ? AND status = 'outcome_unknown'", [JSON.stringify({ capacity_root: firstOperationId, capacity_failure: refusal }), context.now(), id, row.controller_id, row.generation]);
+                        if (changed.changes !== 1)
+                            throw new AppError("capacity_continuation_blocked", "Failed Turn owner changed before its refusal was retained", 1);
+                    },
+                    inspectOperation: id => inspect(["daemon", "operation", "--state-dir", session.state_dir, "--operation-id", id, "--json"], `${id}:capacity-observe`),
+                    inspectSession: turnId => inspect(["session", "inspect", "--session-id", session.id, ...(turnId ? ["--turn-id", turnId] : []), ...sessionArguments(context, manifest, session)], `${firstOperationId}:capacity-inspect`),
+                    assertCurrent: () => {
+                        assertOwner();
+                    },
+                    decision: async () => {
+                        if (kind === "child") {
+                            const target = Object.entries(state.child_capacity ?? {}).find(([, retained]) => retained.operation_id === firstOperationId);
+                            if (!target)
+                                return "reconciliation_blocked";
+                            const seen = await inspect(["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], `${firstOperationId}:child-followup-observe`);
+                            const child = controllerNativeChildren(seen, session.id).find(item => item.session_id === target[0]);
+                            if (child?.parent_session_id === session.id && (child.status === "running" || child.terminal_turn_id && child.terminal_turn_id !== target[1].turn_id))
+                                return "completed";
+                        }
+                        const view = getFlowRunStatus(executionContext, { projectRoot: manifest.request.project_root, runId: row.run_id });
+                        const next = view.continuation;
+                        if (next.kind === "blocked")
+                            return "reconciliation_blocked";
+                        if (next.kind === "paused" && next.stage !== state.stage)
+                            return "paused";
+                        if (next.kind === "terminal" || next.stage !== state.stage)
+                            return "completed";
+                        if (hitl) {
+                            const answerId = firstOperationId.slice(0, -`:prompt:${row.generation}`.length);
+                            const answer = context.db.get("SELECT input_json FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND status = 'accepted'", [answerId, row.controller_id]);
+                            const accepted = answer && JSON.parse(answer.input_json);
+                            const pause = view.index.stage_runs.find(item => item.stage === accepted?.stage)?.pause;
+                            if (next.kind !== "paused")
+                                return "continue";
+                            if (!accepted || pause?.id !== accepted.pause_id || pause.work_id !== accepted.work_id || pause.answer_path)
+                                return "paused";
+                        }
+                        else if (next.kind === "paused")
+                            return "paused";
+                        return next.kind === "wait" && !["native_children_unsettled", "work_receipts_pending", "qualified_capacity_required"].includes(next.reason) ? "reconciliation_blocked" : "continue";
+                    },
+                    retainIntent: intent => retainControllerCapacityIntent(context, row, state, intent, session.id, kind ?? "stage", assertOwner),
+                    prompt: (id, value) => send(value, id),
+                    ...(resumeCommand ? { continuationText: `Continue the same accepted HITL task in this Session. First inspect current durable RUN and pause state. Only if the exact pause still awaits the accepted answer, run this previously issued command once:\n\n${resumeCommand}\n\nNever replay an already committed answer. Otherwise use only the current issued successor.` } : {}) });
+                if (!resumed)
+                    throw error;
+                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;
+        }
+        catch (error) {
+            if (!fatal && error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale", "controller_owner_mismatch"].includes(error.code))
+                throw error;
+            await stopAfterFailure(error);
+            if (!capacityUncertain(error) && !(error instanceof AppError && error.code === "controller_lease_unconfirmed"))
+                cancellation.abort();
+            throw fatal ?? error;
+        }
+        state.last_receipt = receipt;
+        delete state.pending_capacity;
+        saveState(context, row, state);
+        return receipt;
+    };
+    const monitor = setInterval(() => {
+        if (fatal)
+            return;
+        try {
+            checkOutcomes();
+            if (promptPending && state.current_session !== null)
+                childObserver(state.sessions[state.current_session])?.tick();
+        }
+        catch (error) {
+            void stopAfterFailure(error);
+        }
+    }, 1000);
+    monitor.unref();
+    try {
+        for (;;) {
+            // Renewal touches the resource registry; never do it from a callback that
+            // may already own the RUN writer.
+            await renewLease();
+            assertOwner();
+            if (state.current_session !== null && !state.sessions[state.current_session].stopped)
+                bindInvocationScope(state.sessions[state.current_session]);
+            const run = requireRun(context, row.project_id, row.run_id);
+            const view = getFlowRunStatus(executionContext, { projectRoot: run.project_root, runId: run.id });
+            const next = view.continuation;
+            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]);
+                const dispatch = operation && JSON.parse(operation.input_json);
+                const args = dispatch?.args;
+                const file = args?.includes("--prompt-file") ? args[args.indexOf("--prompt-file") + 1] : undefined;
+                if (!session || pending.generation !== row.generation || !file || digestBytes(fs.readFileSync(file)) !== dispatch?.prompt_sha256)
+                    throw new AppError("capacity_continuation_conflict", "Retained capacity resume reference has no exact owned prompt", 1);
+                await prompt(session, fs.readFileSync(file, "utf8"), pending.root_operation_id, pending.kind === "stage" ? undefined : pending.kind);
+                continue;
+            }
+            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);
+                setFlowRunRecoveryPaused(context, row.project_id, row.run_id, true);
+                setStatus("stop_target_reached", { stage: state.stage, attempt: completed.attempt ?? null });
+                return;
+            }
+            if (completed && manifest.request.capture_root && ["start_stage", "terminal"].includes(next.kind)) {
+                const key = JSON.stringify([completed.stage, completed.attempt, completed.started_at, completed.completed_at]);
+                if (key !== lastCapture) {
+                    await captureControllerBoundary(executionContext, row, manifest, completed, next.kind === "start_stage" ? next.stage : null, assertPhysicalOwner);
+                    lastCapture = key;
+                }
+            }
+            if (next.kind === "terminal") {
+                await settle();
+                setStatus(run.status === "cancelled" ? "cancelled" : "completed");
+                appendEvent(context, row.controller_id, "terminal", { reason: next.reason });
+                return;
+            }
+            if (next.kind === "paused") {
+                setStatus("waiting_for_user");
+                const pause = view.index.stage_runs.find(stage => stage.stage === next.stage)?.pause;
+                if (!pause || state.current_session === null)
+                    throw new AppError("controller_hitl_missing", "Paused RUN has no managed Session or HITL receipt", 1);
+                const answer = context.db.get("SELECT operation_id, input_json, status FROM run_controller_operations WHERE controller_id = ? AND status IN ('accepted','completed') AND json_extract(input_json, '$.action') = 'user_answer' AND json_extract(input_json, '$.pause_id') = ? ORDER BY created_at LIMIT 1", [row.controller_id, pause.id]);
+                if (!answer) {
+                    await delay(1000);
+                    continue;
+                }
+                if (answer.status === "completed")
+                    throw new AppError("controller_answer_not_applied", "Completed answer operation still has its original HITL pause", 1, { pause_id: pause.id, operation_id: answer.operation_id, stage: next.stage });
+                const input = JSON.parse(answer.input_json);
+                if (digestBytes(fs.readFileSync(input.file)) !== input.sha256)
+                    throw new AppError("context_checksum_mismatch", "Accepted HITL answer bytes changed", 1);
+                await renewLease();
+                assertOwner();
+                // The accepted answer is logical intent; only its generation-bound
+                // adapter operation represents a physical dispatch that stop must drain.
+                const command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage resume ${run.id} --stage ${next.stage} --work ${input.work_id} --project-root ${quote([run.project_root])} --answer-file ${quote([input.file])} --json`, { replaceUnobservedAnswer: true });
+                const receipt = await prompt(state.sessions[state.current_session], controllerStageResumePrompt(pause.id, command), `${answer.operation_id}:prompt:${row.generation}`, "hitl");
+                const afterAnswer = getFlowRunStatus(executionContext, { projectRoot: run.project_root, runId: run.id });
+                if (afterAnswer.index.stage_runs.some(stage => stage.status === "paused" && stage.pause?.id === pause.id)) {
+                    throw new AppError("controller_answer_not_applied", "The answer Turn completed without resuming the assigned HITL pause", 1, { pause_id: pause.id, operation_id: answer.operation_id, stage: next.stage, effect: "no_progress" });
+                }
+                context.db.run("UPDATE run_controller_operations SET status = 'completed', receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify({ delivered: true, session_id: adapterSessionId(receipt) }), context.now(), answer.operation_id]);
+                state.last_continuation = null;
+                saveState(context, row, state);
+                setStatus("running");
+                continue;
+            }
+            if (next.kind === "blocked" || next.kind === "wait" || !next.stage)
+                throw new AppError("controller_continuation_blocked", "RUN has no legal managed continuation", 1, { continuation: next });
+            if (next.kind === "start_stage") {
+                // Only context slices can be added; profiles and launch inputs stay frozen.
+                manifest.contexts = JSON.parse(requireController(context, row.controller_id).manifest_json).contexts;
+                const stageContext = manifest.contexts[next.stage];
+                if (!stageContext) {
+                    if (requireController(context, row.controller_id).status !== "waiting_for_context")
+                        appendEvent(context, row.controller_id, "context_required", { stage: next.stage, attempt: next.attempt ?? null });
+                    setStatus("waiting_for_context");
+                    await delay(1000);
+                    continue;
+                }
+                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 = 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 });
+                    const claim = claimQueuedMergeRequest(context, { requestId: request.merge_request_id, ownerId: row.controller_id, expectedGeneration: row.generation });
+                    if (!claim) {
+                        setStatus("waiting_for_merge");
+                        await delay(1000);
+                        continue;
+                    }
+                    state.merge_claim = { request_id: claim.request.merge_request_id, token: claim.token, target_workspace: claim.request.target_workspace, work_id: claim.request.executor_work_id };
+                    saveState(context, row, state);
+                    appendEvent(context, row.controller_id, "merge_claimed", { request_id: claim.request.merge_request_id });
+                    await renewLease();
+                }
+                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 && 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) {
+                    if (session)
+                        await stopSession(session);
+                    await renewLease();
+                    assertOwner();
+                    const directory = path.join(row.state_dir, `session-${state.sessions.length + 1}`);
+                    fs.mkdirSync(directory, { mode: 0o700 });
+                    const owner = { schema_id: "dd-flow/runtime-owner@1", owner_id: row.controller_id, role: "subject", project_id: row.project_id, run_id: row.run_id, operation_id: `${row.controller_id}:session:${state.sessions.length + 1}`, state_dir: directory, dd_flow_home: context.ddFlowHome, dd_flow_bin: manifest.flow_executable, resource_home: manifest.resource_home, budget: manifest.budget };
+                    if (next.stage === "merge" && state.merge_claim) {
+                        owner.role = "merge";
+                        owner.work_id = state.merge_claim.work_id;
+                    }
+                    session = { id: "", profile: transition.coordinator, state_dir: directory, cwd: stageCwd, journal: path.join(directory, "adapter.events.jsonl"), owner };
+                    if (runtimeHarness(session.profile) === "codex-desktop") {
+                        session.codex_home = path.join(directory, "codex-home");
+                        initCodexHome(context, { projectRoot: run.project_root, profile: `controller-${digest(directory).slice(0, 16)}`, targetHome: session.codex_home, ...(context.env.CODEX_HOME ? { sourceHome: context.env.CODEX_HOME } : {}) });
+                    }
+                    state.sessions.push(session);
+                    state.current_session = state.sessions.length - 1;
+                    saveState(context, row, state);
+                    await call(session, ["daemon", "start", ...sessionArguments(context, manifest, session)]);
+                    const created = await call(session, ["session", "create", ...sessionArguments(context, manifest, session)]);
+                    const sessionId = adapterSessionId(created);
+                    if (!sessionId)
+                        throw new AppError("harness_adapter_invalid", "Managed adapter did not return its Session id", 1);
+                    session.id = sessionId;
+                    saveState(context, row, state);
+                    bindInvocationScope(session);
+                    if (next.stage === "merge" && state.merge_claim)
+                        context.db.run("UPDATE merge_requests SET adapter_receipt_json = ?, updated_at = ? WHERE merge_request_id = ? AND dispatch_owner = ? AND dispatch_lease_token = ?", [JSON.stringify({ controller_id: row.controller_id, profile: session.profile, session_id: session.id, state_dir: session.state_dir, create: created }), context.now(), state.merge_claim.request_id, row.controller_id, state.merge_claim.token]);
+                    appendEvent(context, row.controller_id, "session_created", { stage: next.stage, session_id: sessionId, harness: runtimeHarness(session.profile), profile: session.profile });
+                }
+                state.native_baseline = controllerNativeChildren(state.last_receipt ?? {}, session.id).map(child => child.session_id);
+                state.stage = next.stage;
+                state.child_capacity = {};
+                saveState(context, row, state);
+                setStatus("running");
+                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 });
+                    await renewLease();
+                    assertOwner();
+                    appendEvent(context, row.controller_id, "code_workspace_prepared", { stage: next.stage, readiness_status: readiness.status ?? null });
+                }
+                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;
+            }
+            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);
+            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);
+                children = controllerNativeChildren(inspected, session.id).filter(child => !baseline.has(child.session_id));
+                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 => 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 = 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 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 => renderNativeChildFollowupInstruction(childHarness, item.session_id) && eligibleProviderChildOverload(item, session.id)) : undefined;
+                const turnId = child?.terminal_turn_id;
+                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: 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")) {
+                    const prepared = prior?.turn_id === turnId && prior.dispatched === false && prior.operation_id && prior.not_before ? prior : null;
+                    if (prior?.turn_id === turnId && prior.dispatched === true && !prepared)
+                        throw new AppError("capacity_child_followup_unconfirmed", "Parent continuation did not start a new native child Turn", 1, { child_session_id: child.session_id, turn_id: turnId });
+                    const attempt = prepared ? prepared.attempts : (prior?.attempts ?? 0) + 1;
+                    if (!Number.isSafeInteger(attempt) || prior && prior.policy !== CAPACITY_POLICY)
+                        throw new AppError("capacity_continuation_conflict", "Native child continuation policy or ordinal is incompatible", 1);
+                    const refusals = [...(prior?.refusals ?? [])];
+                    if (!refusals.some(item => item.turn_id === turnId)) {
+                        const refusal = refusalObservation(native, attempt - 1, child.terminal_observed_at ?? context.now());
+                        refusals.push(refusal);
+                        state.child_capacity ??= {};
+                        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 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)}`;
+                    const operationId = prepared?.operation_id ?? `${rootOperationId}:followup:${attempt}`;
+                    state.child_capacity ??= {};
+                    state.child_capacity[child.session_id] = { turn_id: turnId, attempts: attempt, operation_id: operationId, root_operation_id: rootOperationId, policy: CAPACITY_POLICY, refusals, not_before: prepared?.not_before ?? new Date(Date.now() + wait).toISOString(), dispatched: false };
+                    await prepareMutation(() => { saveState(context, row, state); appendEvent(context, row.controller_id, "capacity_child_followup", { child_session_id: child.session_id, turn_id: turnId, attempt, operation_id: operationId }); });
+                    const until = performance.now() + wait;
+                    while (performance.now() < until) {
+                        await delay(Math.min(250, Math.max(0, until - performance.now())), undefined, { signal: cancellation.signal });
+                        await renewLease();
+                        assertOwner();
+                    }
+                    await renewLease();
+                    assertOwner();
+                    const current = getFlowRunStatus(executionContext, { projectRoot: manifest.request.project_root, runId: row.run_id });
+                    if (current.continuation.stage !== state.stage || ["terminal", "paused"].includes(current.continuation.kind))
+                        continue;
+                    if (["blocked", "wait"].includes(current.continuation.kind))
+                        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: 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);
+                        continue;
+                    }
+                    if (fresh.settled !== true || !still || still.parent_session_id !== session.id || still.status !== "failed" || still.terminal_turn_id !== turnId
+                        || !nativeItemsSettled(still.native_turn_items) || currentLinks.length > 1
+                        || currentLinks.some(link => link.status !== "running"))
+                        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 = renderNativeChildFollowupInstruction(childHarness, child.session_id);
+                    await prompt(session, text, operationId, "child");
+                    state.child_capacity[child.session_id].dispatched = true;
+                    saveState(context, row, state);
+                    const after = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
+                    state.last_receipt = after;
+                    saveState(context, row, state);
+                    const observed = controllerNativeChildren(after, session.id).find(item => item.session_id === child.session_id);
+                    if (!observed || observed.status === "failed" && observed.terminal_turn_id === turnId)
+                        throw new AppError("capacity_child_followup_unconfirmed", "Native child did not advance to a new Turn after parent followup", 1, { child_session_id: child.session_id, turn_id: turnId });
+                    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, 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)
+                    throw new AppError(cause.code, cause.message, 1, { ...cause.details, ...(cause.invocation_id ? { invocation_id: cause.invocation_id } : {}), ...(cause.hook_event_id ? { hook_event_id: cause.hook_event_id } : {}), controller_wrapper: "incomplete_subject_turn", stage: next.stage });
+                throw new AppError("incomplete_subject_turn", "Managed Turn ended without a completed Stage or declared continuation", 1, { stage: next.stage });
+            }
+            if (fanout.kind === "wait") {
+                setStatus(fanout.reason === "qualified_capacity_required" ? "waiting_for_capacity" : "waiting_for_children");
+                await delay(1000);
+                state.last_receipt = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
+                saveState(context, row, state);
+                continue;
+            }
+            setStatus("running");
+            if (fanout.kind === "external") {
+                const results = await Promise.allSettled(fanout.works.map(async (work) => {
+                    try {
+                        await renewLease();
+                        assertOwner();
+                        const receipt = await launchExternalWork(executionContext, { workId: work.work_id, stage: next.stage, signal: cancellation.signal });
+                        if (fatal)
+                            throw fatal;
+                        appendEvent(context, row.controller_id, "external_work_observed", { work_id: work.work_id, receipt });
+                        const launch = context.db.get("SELECT state_dir, profile_json FROM work_launches WHERE work_id = ?", [work.work_id]);
+                        const status = context.db.get("SELECT status FROM works WHERE work_id = ?", [work.work_id])?.status;
+                        if (!launch || !["completed", "failed", "cancelled"].includes(status ?? ""))
+                            throw new AppError("external_work_unsettled", "External launch returned without its terminal Work receipt; observe it rather than relaunching", 1, { work_id: work.work_id, status });
+                        const resolved = JSON.parse(launch.profile_json);
+                        const executable = manifest.adapters[runtimeHarness(resolved.worker)].executable;
+                        const stopped = await runHarnessAdapter({ executable, args: ["daemon", "stop", "--state-dir", launch.state_dir, "--json"], env: controllerEnvironment(context, manifest), operationId: `${row.controller_id}:${work.work_id}:settle` });
+                        await confirmStopped(launch.state_dir, stopped);
+                        appendEvent(context, row.controller_id, "external_work_settled", { work_id: work.work_id, receipt: stopped });
+                    }
+                    catch (error) {
+                        await stopAfterFailure(error);
+                        throw error;
+                    }
+                }));
+                const rejected = results.find((result) => result.status === "rejected");
+                if (rejected)
+                    throw fatal ?? rejected.reason;
+                state.last_continuation = null;
+                saveState(context, row, state);
+                continue;
+            }
+            if (state.last_continuation === fanout.fingerprint)
+                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);
+        }
+    }
+    catch (error) {
+        if (!fatal && error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale", "controller_owner_mismatch"].includes(error.code))
+            throw error;
+        let cause = fatal ?? error;
+        if (!fatal && terminalFinalization) {
+            const record = errorRecord(error);
+            const provenance = { phase: "terminal_finalization", project_root: manifest.request.project_root, run_id: row.run_id, controller_id: row.controller_id };
+            if (error instanceof AppError)
+                Object.assign(error.details, provenance);
+            else
+                cause = new AppError(String(record.code), String(record.message), 1, { ...record.details, ...provenance, cause: record });
+        }
+        await stopAfterFailure(cause);
+        throw fatal ?? cause;
+    }
+    finally {
+        clearInterval(monitor);
+        const drainedObservations = [...childObservers.values()].map(retained => retained.close());
+        observationCancellation.abort();
+        await Promise.allSettled(drainedObservations);
+        if (stopping)
+            await stopping;
+        observer.db.close?.();
+    }
+}
+function readContexts(file, expected) {
+    const { bytes } = prepareFileBytes(file, "Managed context package");
+    if (digestBytes(bytes) !== expected)
+        throw new AppError("context_checksum_mismatch", "Managed context package SHA-256 differs", 2);
+    const value = prepareJsonText(bytes.toString("utf8"), { file, label: "Managed context package" }).value;
+    if (!value || value.schema_id !== "dd-flow/managed-context@1" || !value.stages || typeof value.stages !== "object" || Array.isArray(value.stages) || Object.keys(value).some(key => !["schema_id", "stages"].includes(key)))
+        throw new AppError("validation", "Expected dd-flow/managed-context@1 with stage file/hash references", 2);
+    const result = {};
+    for (const [stage, source] of Object.entries(value.stages)) {
+        if (!/^[a-z][a-z-]*$/.test(stage) || !source || typeof source !== "object" || Object.keys(source).some(key => !["file", "sha256"].includes(key)) || typeof source.file !== "string" || !path.isAbsolute(source.file) || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256))
+            throw new AppError("validation", "Invalid managed stage context reference", 2);
+        const { bytes: content } = loadExternalStageContext({ file: source.file, expectedSha256: source.sha256, stage });
+        result[stage] = { bytes: content, sha256: source.sha256 };
+    }
+    return result;
+}