@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/services/run-controller.js

@@ -0,0 +1,1717 @@
+import { assertLifecycleOutcomes, currentLifecycleFailure, currentStageFinishAuthority, managedInvocationContext, managedLifecycleCommand, awaitLifecycleInvocation, assertLifecycleInvocationCurrent, bindControllerStageAssignment } from "./lifecycle-invocations.js";
+import { stageAttempt } from "./stage-work-graph.js";
+import { isSourceSnapshotFlow } from "../domain/source-snapshot-flows.js";
+import { isDeliveryFlow } from "../domain/delivery-flows.js";
+export function recoveryPacketMatchesStage(packet, scope) {
+    return packet.schema_id === 'dd-flow/root-recovery-packet@1' && packet.continuation === 'unfinished_work'
+        && packet.run_id === scope.runId && packet.generation === scope.generation && packet.stage === scope.stage
+        && packet.work_id === scope.workId && packet.paused === false;
+}
+import crypto from "node:crypto";
+import { nativeShutdownConfirmed } from "../harness-runtime/lib/native-children.mjs";
+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 { retainedBrowserEnvironment, validateCheckEnvironment } from "./check-environment.js";
+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, stageResumeSourcePath } 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, prepareManagedProcessConfirmation, renewManagedProcess, finishManagedProcess, processTreeIsAlive, resourceHome } from "./managed-processes.js";
+import { managedLeaseMonitor } from "./managed-lease-monitor.js";
+import { physicalStartup } from "./physical-startup.js";
+import { readNativeDaemonState, requireManagedDaemonBinding, managedDaemonExecutionAbsent, managedExecutionReusable } from "./managed-daemon-binding.js";
+import { initCodexHome } from "./hooks.js";
+import { launchExternalWork } from "./external-work-launch.js";
+import { runControllerMemoryTask } from "./controller-memory-task.js";
+import { controllerNativeChildren, controllerSemanticCheckpoint, controllerStageEntryPrompt, controllerStageResumePrompt, nextControllerFanout } from "./controller-fanout.js";
+import { publishPromptDelivery } from "./prompt-delivery.js";
+import { publishStagePacket } from "./stage-report-renderer.js";
+import { claimQueuedMergeRequest } from "./merge-server.js";
+import { prepareVnextCodeWorkspace } from "./vnext-code.js";
+import { requireRun, requireController, controllerReceipt, controllerDependencyDiagnostic, 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, ownedProviderBoundary, unavailableProviderChildRecovery } 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 { recordRunControlIntent } from "./run-control.js";
+import { storageSessionId } from "./session-identity.js";
+import { RECOVERY_POLICY as CAPACITY_POLICY, nativeItemsSettled, recoveryExhausted as overloadExhausted, recoveryRefusal as refusalObservation, terminalProviderRecovery as terminalProviderOverload, normalizeRecoveryFailure } from "../harness-runtime/lib/provider-overload-policy.mjs";
+import { renderNativeChildFollowupInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { childCapacityDispatchAllowed, childCapacityRecoveryDecision, closeSuccessfulChildCapacity, reconcileChildCapacity } from "./controller-child-capacity.js";
+import { completedChildRepair, reserveChildRepair } from "./controller-child-repair.js";
+import { prepareWorkFailureResolution, readFailureDecision, failureDecisionReady, acceptFailureDecision, applyWorkFailureDecision, reconcilePendingWorkFailure, workFailureResolutionPrompt, workFailureDiagnostic, workFailureBlockActive } from "./controller-work-failure.js";
+import { getVnextFanoutStatus } from "./vnext-fanout.js";
+import { isObservationLoss } from "../harness-runtime/lib/operation-errors.mjs";
+import { recordTechnicalNote } from "./technical-notes.js";
+import { acceptedChildWork, acceptedChildrenRetired, controllerObligation, controllerObligationAccepted, lateNativeFailure } from "./controller-result-authority.js";
+export { resumeRunController } from "./run-controller-recovery.js";
+const preparedLaunchInputs = new WeakMap();
+function launchInputDigest(input) {
+    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 async function retainRunControllerLaunch(context, input, prepared = prepareRunControllerLaunch(context, input)) {
+    const selection = preparedLaunchInputs.get(prepared);
+    if (!selection || selection.home !== context.ddFlowHome || selection.sha256 !== launchInputDigest(input)) {
+        throw new AppError("runtime_request_conflict", "Controller launch differs from its prepared request", 1, { effect: "no_effect" });
+    }
+    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;
+    const assertCurrent = () => {
+        if (selection.sha256 !== launchInputDigest(input))
+            throw new AppError("runtime_request_conflict", "Controller launch changed during physical observation", 1, { effect: "no_effect" });
+        assertRunMutationAllowed(context, project.id, run.id, generation);
+        if (requireRun(context, project.id, run.id).status !== "running")
+            throw new AppError("invalid_run_state", "Managed launch requires a running logical RUN", 1);
+    };
+    const launcher = await physicalStartup(context.databaseDeadlineAt).birth(assertCurrent);
+    ensureRunControllerStorage(context.db);
+    const controllerId = `DRV-${crypto.randomUUID()}`;
+    const root = path.join(run.run_root, "controllers", controllerId);
+    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,
+        ...(retainedBrowserEnvironment(context.env) ? { check_environment: retainedBrowserEnvironment(context.env) } : {}) };
+    const token = crypto.randomUUID();
+    const now = context.now();
+    const state = { stage: null, sessions: [], current_session: null, turns: 0, last_continuation: null };
+    const duplicate = context.db.writeTransaction(() => {
+        assertCurrent();
+        if (routing.bundle)
+            assertPreparedRunBundleSqlAuthority(context, { projectId: project.id, runId: run.id }, routing.bundle);
+        const duplicate = context.db.get("SELECT * FROM run_controllers WHERE project_id = ? AND run_id = ? AND request_id = ?", [project.id, run.id, input.requestId]);
+        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 = await retainRunControllerLaunch(context, input, prepared);
+    // A simultaneous publisher already owns dispatch. Preserve the original
+    // race behavior: only an explicit replay may reconcile that existing owner.
+    if (prepared.kind === "create" && retained.reused)
+        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, context), events: events.map(event => ({ sequence: event.sequence, type: event.event_type, data: JSON.parse(event.data_json), at: event.created_at })), next_cursor: events.at(-1)?.sequence ?? input.after ?? 0 };
+}
+export async function serveRunController(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    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);
+    let lease;
+    let mergeLease;
+    let heartbeat;
+    let state;
+    let claimedProcess = false;
+    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 {
+        const currentState = state = JSON.parse(row.state_json);
+        const startup = physicalStartup(context.databaseDeadlineAt);
+        const assertStartingOwner = () => {
+            const current = requireController(context, row.controller_id);
+            if (current.owner_token !== row.owner_token || current.generation !== row.generation || current.owner_pid !== null || current.status !== "starting")
+                throw new AppError("controller_owner_mismatch", "Controller startup no longer owns this launch", 1);
+            if (["done", "failed", "cancelled"].includes(requireRun(context, row.project_id, row.run_id).status))
+                throw new AppError("invalid_run_state", "A terminal RUN cannot start a physical controller", 1);
+        };
+        const owner = await startup.birth(assertStartingOwner);
+        try {
+            claimControllerProcess(context, row, owner);
+        }
+        finally {
+            claimedProcess = row.owner_pid === process.pid;
+        }
+        if (!row.process_id || !row.process_lease_token)
+            throw new AppError("controller_owner_mismatch", "Managed owner has no resource lease", 1);
+        const confirmation = { id: row.process_id, leaseToken: row.process_lease_token, pid: process.pid, processGroupId: process.pid, ownerPid: process.pid };
+        const originalLease = prepareManagedProcessConfirmation(context, confirmation).lease_expires_at;
+        const confirmed = await startup.observe(() => confirmManagedProcess(context, confirmation), () => assertControllerLeaseAllowed(context, row), originalLease);
+        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);
+        // Resource and RUN commits are distinct effects. A RUN keepalive failure must
+        // neither erase a resource receipt nor grant RUN dispatch authority.
+        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);
+        };
+        heartbeat = setInterval(() => {
+            lease.background(assertLeaseFence, () => { });
+            if (currentState.merge_claim)
+                mergeLease.background(assertLeaseFence, () => { });
+        }, 30_000);
+        heartbeat.unref();
+        const manifest = JSON.parse(row.manifest_json);
+        const assertPhysicalOwner = () => {
+            lease.assertNoRenewal();
+            if (currentState.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); };
+        await lease.ensureConfirmed(assertLeaseFence);
+        if (currentState.merge_claim)
+            await mergeLease.ensureConfirmed(assertLeaseFence);
+        context.db.writeTransaction(() => {
+            markControllerDispatchReady(context, row);
+            if (!currentState.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 (currentState.recovery && !["done", "failed", "cancelled"].includes(requireRun(context, row.project_id, row.run_id).status))
+            await resumeControllerSession(context, row, manifest, currentState, assertPhysicalOwner);
+        await executeController(context, row, manifest, currentState, assertOwner, assertPhysicalOwner, async () => { await lease.ensureConfirmed(assertLeaseFence); if (currentState.merge_claim)
+            await mergeLease.ensureConfirmed(assertLeaseFence); });
+        return controllerReceipt(requireController(context, row.controller_id), context);
+    }
+    catch (error) {
+        primaryFailure = error;
+        try {
+            const controlled = context.db.writeTransaction(() => {
+                const currentOwner = requireController(context, row.controller_id);
+                const sameBinding = currentOwner.owner_token === row.owner_token && currentOwner.generation === row.generation
+                    && currentOwner.process_id === row.process_id && currentOwner.process_lease_token === row.process_lease_token;
+                const ownsFailure = claimedProcess ? currentOwner.owner_pid === process.pid : row.owner_pid === null && currentOwner.owner_pid === null && row.status === "starting" && currentOwner.status === "starting";
+                if (!sameBinding || !ownsFailure || ["completed", "cancelled", "superseded"].includes(currentOwner.status))
+                    throw error;
+                try {
+                    if (state)
+                        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 {
+                    // 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);
+                }
+                return null;
+            });
+            if (controlled)
+                return controlled;
+        }
+        catch (secondary) {
+            retainSecondary("controller_failure_boundary", secondary);
+        }
+        throw error;
+    }
+    finally {
+        lease?.close();
+        mergeLease?.close();
+        if (heartbeat)
+            clearInterval(heartbeat);
+        finishOwner();
+    }
+    function finishOwner() {
+        if (!claimedProcess || row.owner_pid !== process.pid || !row.process_id || !row.process_lease_token)
+            return;
+        try {
+            finishManagedProcess(context, { id: row.process_id, leaseToken: row.process_lease_token, state: "stopped", reason: "controller_owner_exited" });
+        }
+        catch (cleanup) {
+            recordTechnicalNote(context, row.project_id, row.run_id, { code: "controller_resource_retirement_pending", message: "Controller execution ended; resource-registry retirement remains pending.", phase: "controller_cleanup", generation: row.generation, resource_identity: row.process_id, consequence: "cleanup_pending" });
+            retainSecondary("finish_controller_process", cleanup);
+        }
+    }
+}
+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, ...validateCheckEnvironment(manifest.check_environment), 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 technicalPauseRequested = 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) => {
+        // The published pause already fences this owner. A later observer failure
+        // must not supersede that same control with a second pause or fatal stop.
+        if (technicalPauseRequested)
+            return Promise.resolve();
+        // 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 (error instanceof AppError && error.code !== "child_work_repair_blocked" && (error.details.reconciliation_required === true || ["invocation_assignment_unproven", "invocation_outcome_pending", "invocation_receipt_timeout"].includes(error.code)) && state.current_session !== null)
+            return pauseDependency(state.sessions[state.current_session], undefined, error, "productive_continuation").catch(cause => {
+                if (!(cause instanceof AppError && cause.code === "controller_technical_dependency_paused"))
+                    return stopAfterFailure(new AppError("controller_dependency_control_unavailable", "The dependency pause could not be published safely", 1, { primary: errorRecord(error), control_error: errorRecord(cause) }));
+            });
+        if (stopping)
+            return stopping;
+        fatal = error;
+        // 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 = async (session, args, productive = true, operationId) => {
+        const receipt = await controllerAdapter(executionContext, row, manifest, session, args, productive ? assertOwner : undefined, operationId, productive ? cancellation.signal : undefined, productive ? renewLease : undefined);
+        const previous = state.last_receipt;
+        // A read refreshes native observations, not the already accepted engine
+        // boundary. Never copy native readiness/settlement fields from the old read.
+        return args[0] === "session" && args[1] === "inspect" && previous?.accepted_boundary && adapterSessionId(previous) === session.id
+            ? { ...receipt, accepted_boundary: previous.accepted_boundary } : receipt;
+    };
+    const note = (session, code, phase, consequence, operationId, noteState) => recordTechnicalNote(context, row.project_id, row.run_id, {
+        code, message: "The accepted result is retained independently of native session retirement or observation.", phase,
+        generation: row.generation, ...(state.stage ? { stage: state.stage } : {}), harness: runtimeHarness(session.profile),
+        resource_identity: session.state_dir, diagnostic_reference: session.state_dir, consequence, ...(operationId ? { source_operation_id: operationId } : {}), ...(noteState ? { state: noteState } : {})
+    });
+    const failedChildren = (session) => (childObserver(session)?.failed() ?? []).filter(child => {
+        if (!acceptedChildWork(context, row, runtimeHarness(session.profile), session.id, child.session_id))
+            return true;
+        note(session, "accepted_work_native_child_failed", "native_completion", "cleanup_pending", child.terminal_turn_id);
+        return false;
+    });
+    const pauseDependency = async (session, sourceOperationId, cause, protectedAction = "stage_transition") => {
+        // The control intent contains the retained productive failure; it must not
+        // require that same failure to disappear before the owner can pause it.
+        assertPhysicalOwner();
+        const recorded = cause ? errorRecord(cause) : { code: "native_writer_dependency_blocked", message: "Conflicting native execution has not settled" };
+        const dependency = controllerDependencyDiagnostic(recorded, protectedAction);
+        const primary = dependency.primary;
+        const details = cause instanceof AppError ? cause.details : {};
+        recordTechnicalNote(context, row.project_id, row.run_id, { code: primary.code, message: primary.message,
+            phase: protectedAction, generation: row.generation, ...(state.stage ? { stage: state.stage } : {}),
+            ...(typeof details.work_id === "string" ? { work_id: details.work_id } : {}),
+            harness: runtimeHarness(session.profile), resource_identity: session.state_dir,
+            consequence: "dependency_blocked", ...(sourceOperationId ? { source_operation_id: sourceOperationId } : {}),
+            diagnostic_reference: JSON.stringify(dependency) });
+        // Diagnostic observations can race (adapter read vs lifecycle monitor), but
+        // they own one pause of this execution, not one control per error message.
+        const requestId = `technical:${row.controller_id}:${row.generation}:${digest([state.stage, session.state_dir]).slice(0, 20)}`;
+        const input = { projectRoot: manifest.request.project_root, runId: row.run_id, requestId, action: "pause" };
+        // Publish source binding in the same SQL transaction as the control
+        // intent. A detached worker must never observe an unlabelled pause.
+        const intent = recordRunControlIntent(executionContext, input, receipt => {
+            const current = requireController(context, row.controller_id);
+            if (current.owner_token !== row.owner_token || current.generation !== row.generation || current.process_id !== row.process_id)
+                throw new AppError("controller_owner_mismatch", "Controller changed before its technical control was recorded", 1);
+            const controlId = receipt.control_id;
+            if (typeof controlId !== "string")
+                return;
+            const prior = context.db.get("SELECT 1 FROM run_controller_events WHERE controller_id=? AND event_type='technical_dependency_paused' AND json_extract(data_json,'$.control_id')=? AND COALESCE(json_extract(data_json,'$.source_operation_id'),'')=?", [row.controller_id, controlId, sourceOperationId ?? ""]);
+            if (!prior)
+                appendEvent(context, row.controller_id, "technical_dependency_paused", { schema_id: "dd-flow/controller-dependency@1", request_id: requestId, control_id: controlId, generation: row.generation, control: receipt, state_dir: session.state_dir, ...dependency, ...(sourceOperationId ? { source_operation_id: sourceOperationId } : {}) });
+        });
+        if (typeof intent.control_id !== "string")
+            throw new AppError("controller_dependency_control_unavailable", "Technical control was not created", 1, { intent });
+        technicalPauseRequested = true;
+        const control = await requestRunControl(executionContext, { ...input, waitMs: 0 });
+        throw new AppError("controller_technical_dependency_paused", "A retained dependency requires control reconciliation before continuation", 1, { control, ...dependency, effect: "no_effect" });
+    };
+    const confirmStopped = async (stateDir, receipt) => {
+        const fail = () => new AppError("controller_native_shutdown_unproven", "The managed daemon is not proven clean and closed", 1, { state_dir: stateDir, receipt });
+        const binding = requireManagedDaemonBinding(executionContext, { stateDir, projectId: row.project_id, runId: row.run_id });
+        if (!binding.state.daemon_id || receipt.stopped !== true || !nativeShutdownConfirmed(receipt, { daemonId: binding.state.daemon_id }))
+            throw fail();
+        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 retireSession = async (session) => {
+        session.retired = true;
+        saveState(context, row, state);
+        try {
+            await stopSession(session);
+            session.cleanup_pending = false;
+            note(session, "native_session_cleanup_pending", "native_cleanup", "none", undefined, "resolved");
+            return true;
+        }
+        catch {
+            session.cleanup_pending = true;
+            saveState(context, row, state);
+            note(session, "native_session_cleanup_pending", "native_cleanup", "cleanup_pending");
+            // Full cleanup remains truthful. Only physical absence or an already
+            // accepted native execution-settlement proof permits conflicting reuse.
+            try {
+                const binding = requireManagedDaemonBinding(executionContext, { stateDir: session.state_dir, projectId: row.project_id, runId: row.run_id });
+                if (managedDaemonExecutionAbsent(executionContext, { stateDir: session.state_dir, projectId: row.project_id, runId: row.run_id }))
+                    return true;
+                return managedExecutionReusable(binding.state, runtimeHarness(session.profile));
+            }
+            catch {
+                return false;
+            }
+        }
+    };
+    const settle = async () => {
+        await Promise.all(state.sessions.map(retireSession));
+    };
+    const captureBoundary = async (stage, nextStage) => {
+        try {
+            await captureControllerBoundary(executionContext, row, manifest, stage, nextStage, assertPhysicalOwner);
+        }
+        catch (error) {
+            const code = String(error?.code ?? "capture_unavailable");
+            if (["controller_owner_mismatch", "controller_capture_owner_lost", "run_recovery_guarded", "run_recovery_generation_stale"].includes(code))
+                throw error;
+            recordTechnicalNote(context, row.project_id, row.run_id, { code: "boundary_capture_unavailable", message: "The Stage result is accepted; its assessment snapshot is unavailable.", phase: "assessment_capture", generation: row.generation, stage: stage.stage, ...(manifest.request.capture_root ? { diagnostic_reference: manifest.request.capture_root } : {}), consequence: "none" });
+            context.db.run("UPDATE run_controllers SET status='running',last_error_json=NULL,updated_at=? WHERE controller_id=? AND owner_token=? AND generation=? AND status IN ('capturing','capture_failed')", [context.now(), row.controller_id, row.owner_token, row.generation]);
+            // A missing report is not a failed Stage. A real unstable source still
+            // fences its dependent successor until the existing control can seal it.
+            if (nextStage && ["recovery_observation_budget_exhausted", "controller_boundary_changed", "snapshot_source_changed", "owned_inventory_changed"].includes(code) && state.current_session !== null)
+                await pauseDependency(state.sessions[state.current_session], undefined, error, "boundary_capture");
+        }
+    };
+    const reconcilePromptPredecessor = async (session) => {
+        const prior = state.last_receipt?.settlement;
+        const accepted = state.last_receipt?.accepted_boundary;
+        if (!prior || typeof prior !== "object" || Array.isArray(prior) || !["pending", "blocked"].includes(String(prior.state)))
+            return;
+        const receipt = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false).catch(async (error) => {
+            if (accepted && controllerObligationAccepted(context, row, accepted) && lateNativeFailure(error, session.id))
+                await pauseDependency(session, undefined, error, "predecessor_settlement");
+            throw error;
+        });
+        state.last_receipt = receipt;
+        saveState(context, row, state);
+        const current = receipt.settlement;
+        if (current && typeof current === "object" && !Array.isArray(current) && ["pending", "blocked"].includes(String(current.state))) {
+            if (accepted && controllerObligationAccepted(context, row, accepted)) {
+                note(session, "accepted_boundary_settlement_pending", "native_observation", "cleanup_pending");
+                if (receipt.native_settled === true && receipt.settled === true)
+                    return;
+                await pauseDependency(session, undefined, new AppError("accepted_boundary_settlement_pending", "Accepted boundary still has an unsettled native predecessor", 1), "predecessor_settlement");
+            }
+            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, boundary = "finish", assignedWorkIds, failureResolution) => {
+        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 expectedBoundary = state.stage ? controllerObligation(context, row, state.stage, hitl ? "resume" : boundary, assignedWorkIds) : undefined;
+        if (expectedBoundary && failureResolution)
+            expectedBoundary.failure_resolution = failureResolution;
+        const hitlText = async () => {
+            const answerId = firstOperationId.slice(0, -`:prompt:${row.generation}`.length);
+            const answer = context.db.get("SELECT input_json,receipt_json FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND status IN ('accepted','completed')", [answerId, row.controller_id]);
+            const accepted = answer && JSON.parse(answer.input_json);
+            const packet = answer?.receipt_json && JSON.parse(answer.receipt_json).hitl_packet;
+            if (!packet || !accepted || packet.generation !== row.generation || packet.pause_id !== accepted.pause_id || packet.stage !== accepted.stage || packet.work_id !== accepted.work_id || packet.answer_file !== accepted.file || packet.answer_sha256 !== accepted.sha256)
+                throw new AppError("controller_hitl_packet_invalid", "Accepted HITL continuation lost its exact binding", 1);
+            const issued = context.db.get("SELECT id,status,scope_json,command FROM lifecycle_invocations WHERE id = ?", [packet.invocation_id ?? null]);
+            if (!issued || issued.scope_json !== executionContext.env.DD_FLOW_INVOCATION_SCOPE)
+                throw new AppError("controller_hitl_packet_invalid", "Accepted HITL command belongs to another scope", 1);
+            if (issued.status === "executing" || issued.status === "settled") {
+                const recovered = await awaitLifecycleInvocation(executionContext, { id: issued.id, command: issued.command, assertCurrent: scope => assertLifecycleInvocationCurrent(executionContext, scope, issued.command) });
+                if (!recovered.replay)
+                    throw new AppError("controller_hitl_reconciliation_required", "Accepted resume is not committed", 1);
+                const outcome = recovered.outcome;
+                if (!outcome.result)
+                    throw new AppError("controller_hitl_reconciliation_required", "Accepted resume has no committed continuation", 1);
+                if (outcome.result.resume_source_path !== packet.resume_source_path || typeof outcome.result.answer_path !== "string")
+                    throw new AppError("controller_hitl_packet_invalid", "Committed resume differs from the accepted packet locator", 1);
+                publishStagePacket(executionContext, row.project_id, row.run_id, packet.stage, outcome.result.answer_path);
+                publishStagePacket(executionContext, row.project_id, row.run_id, packet.stage, packet.resume_source_path);
+                const bytes = fs.readFileSync(outcome.result.answer_path);
+                if (digestBytes(bytes) !== packet.answer_sha256)
+                    throw new AppError("context_checksum_mismatch", "Committed answer differs from its accepted bytes", 1);
+                fs.mkdirSync(path.dirname(packet.answer_file), { recursive: true, mode: 0o700 });
+                publishImmutableInput(packet.answer_file, bytes, "hitl_answer_conflict");
+                publishPromptDelivery(outcome.result);
+                const delivery = outcome.result.prompt_delivery;
+                const promptPath = delivery?.path ?? outcome.result.prompt_path;
+                if (typeof promptPath !== "string" || !path.isAbsolute(promptPath))
+                    throw new AppError("controller_hitl_packet_invalid", "Committed resume has no absolute prompt delivery", 1);
+                // Keep continuation bytes stable across a retained overload episode.
+                // Its conditional instructions point at this restored exact custody.
+                return controllerStageResumePrompt(packet);
+            }
+            if (issued.status !== "issued" || digestBytes(fs.readFileSync(packet.answer_file)) !== packet.answer_sha256)
+                throw new AppError("context_checksum_mismatch", "Accepted HITL answer or command changed before resume", 1);
+            return controllerStageResumePrompt(packet);
+        };
+        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, JSON.parse(retained.input_json).obligation);
+            }
+            const file = path.join(row.state_dir, `turn-${String(state.turns + 1).padStart(5, "0")}.md`);
+            fs.writeFileSync(file, value, { flag: "wx", mode: 0o600 });
+            state.turns += 1;
+            saveState(context, row, state);
+            return controllerAdapter(executionContext, row, manifest, session, ["session", "prompt", "--session-id", session.id, "--prompt-file", file, ...sessionArguments(context, manifest, session)], assertOwner, id, cancellation.signal, renewLease, expectedBoundary);
+        };
+        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);
+                }
+                const failures = failedChildren(session);
+                if (failures.length && !(kind === "child" && childCapacityDispatchAllowed(state, failures, session.id, firstOperationId, digestBytes(text))))
+                    throw new AppError("fanout_dispatch_fenced", "A retained child failure forbids another coordinator dispatch", 1);
+                promptPending = true;
+                observedPromptOperation = firstOperationId;
+                try {
+                    receipt = await send(hitl ? await hitlText() : text, firstOperationId);
+                }
+                finally {
+                    promptPending = false;
+                    observedPromptOperation = null;
+                }
+            }
+            catch (error) {
+                const hitlContinuationText = hitl && terminalProviderOverload(error, session.id) ? await hitlText() : undefined;
+                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 (boundary, currentFailure) => {
+                        if (kind === "child") {
+                            const seen = await inspect(["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], `${firstOperationId}:child-followup-observe`);
+                            const parent = normalizeRecoveryFailure(currentFailure, session.id);
+                            const decision = childCapacityRecoveryDecision(state, controllerNativeChildren(seen, session.id), session.id, firstOperationId, parent?.request_proof.kind === "native_turn" ? parent.turn_id : undefined);
+                            if (decision !== "continue") {
+                                saveState(context, row, state);
+                                return decision;
+                            }
+                        }
+                        const view = getFlowRunStatus(executionContext, { projectRoot: manifest.request.project_root, runId: row.run_id });
+                        const next = view.continuation;
+                        if (boundary) {
+                            if (!ownedProviderBoundary(context, { projectId: row.project_id, runId: row.run_id, stage: state.stage, sessionId: session.id, generation: row.generation, scope: "stage" }, boundary))
+                                return "reconciliation_blocked";
+                            return boundary.outcome === "paused" ? "paused" : "completed";
+                        }
+                        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),
+                    ...(hitlContinuationText ? { continuationText: hitlContinuationText } : {}) });
+                if (!resumed)
+                    throw error;
+                receipt = resumed;
+            }
+            checkOutcomes();
+            await childObserver(session)?.drain();
+            childObserver(session)?.completePostTurn(receipt);
+            const observationGap = childObserver(session)?.gap();
+            if (observationGap) {
+                if (expectedBoundary && controllerObligationAccepted(context, row, expectedBoundary))
+                    note(session, "accepted_boundary_observation_gap", "native_observation", "cleanup_pending", firstOperationId);
+                else
+                    throw new AppError("operation_observation_lost", "In-flight child observation remained unavailable at the safe Turn boundary", 1, { observation_error_code: observationGap, provider_session_id: session.id, stage: state.stage });
+            }
+            if (fatal)
+                throw fatal;
+        }
+        catch (error) {
+            if (!fatal && error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale", "controller_owner_mismatch"].includes(error.code))
+                throw error;
+            if (!fatal && lateNativeFailure(error, session.id)) {
+                if (failureResolution && failureDecisionReady(failureResolution))
+                    acceptFailureDecision(executionContext, row, failureResolution, assertOwner);
+                await pauseDependency(session, firstOperationId, error, "productive_continuation");
+            }
+            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 || technicalPauseRequested)
+            return;
+        try {
+            checkOutcomes();
+            if (promptPending && state.current_session !== null)
+                childObserver(state.sessions[state.current_session])?.tick();
+        }
+        catch (error) {
+            void stopAfterFailure(error);
+        }
+    }, 1000);
+    monitor.unref();
+    const resolutionWriterSettled = async (session) => {
+        const inspected = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
+        state.last_receipt = inspected;
+        saveState(context, row, state);
+        return inspected.settled === true && !controllerNativeChildren(inspected, session.id).some(child => ["running", "unknown"].includes(child.status));
+    };
+    try {
+        for (;;) {
+            if (technicalPauseRequested)
+                return;
+            // Renewal touches the resource registry; never do it from a callback that
+            // may already own the RUN writer.
+            await renewLease();
+            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, dispatch?.obligation?.action ?? "finish", dispatch?.obligation?.work_ids, dispatch?.obligation?.failure_resolution);
+                continue;
+            }
+            const failureRecovery = await reconcilePendingWorkFailure(executionContext, row, state, next.kind, run.project_root, assertOwner, resolutionWriterSettled);
+            if (failureRecovery === "waiting") {
+                setStatus("waiting_for_children");
+                await delay(1000);
+                continue;
+            }
+            if (failureRecovery === "applied") {
+                saveState(context, row, state);
+                continue;
+            }
+            if (next.kind !== "paused" && state.current_session !== null) {
+                const committed = context.db.get("SELECT operation_id,receipt_json FROM run_controller_operations WHERE controller_id = ? AND status = 'accepted' AND json_extract(input_json,'$.action') = 'user_answer' AND json_extract(receipt_json,'$.hitl_packet.generation') = ? AND json_extract(receipt_json,'$.hitl_packet.stage') = ? ORDER BY created_at LIMIT 1", [row.controller_id, row.generation, state.stage]);
+                if (committed) {
+                    const packet = JSON.parse(committed.receipt_json).hitl_packet;
+                    const receipt = await prompt(state.sessions[state.current_session], controllerStageResumePrompt(packet), `${committed.operation_id}:prompt:${row.generation}`, "hitl");
+                    context.db.run("UPDATE run_controller_operations SET status = 'completed', receipt_json = json_set(receipt_json,'$.delivered',json('true'),'$.session_id',?), updated_at = ? WHERE operation_id = ? AND status = 'accepted'", [adapterSessionId(receipt), context.now(), committed.operation_id]);
+                    state.last_continuation = null;
+                    saveState(context, row, state);
+                    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)) {
+                const session = state.sessions[state.current_session], failures = failedChildren(session);
+                if (failures.length && !completed)
+                    throw new AppError("fanout_dispatch_fenced", "A retained child failure forbids advancing an unaccepted Stage", 1);
+                // The Stage gate is authoritative even for a native helper with no Work
+                // association. This does not claim that helper succeeded or stopped:
+                // normal Session retirement/predecessor reconciliation still fences writes.
+                for (const child of failures)
+                    note(session, "accepted_stage_native_child_failed", "native_completion", "cleanup_pending", child.terminal_turn_id);
+            }
+            if (completed && manifest.request.stop_after === state.stage) {
+                // A bounded run is final evidence, not an entry fixture for its successor.
+                // Stop owned observers before capture; keep the controller lease/fence.
+                await settle();
+                if (manifest.request.capture_root)
+                    await captureBoundary(completed, null);
+                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 captureBoundary(completed, next.kind === "start_stage" ? next.stage : null);
+                    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" || next.kind === "blocked") && workFailureBlockActive(executionContext, row, view.index)) {
+                setStatus("waiting_for_dependency");
+                await delay(1000, undefined, { signal: cancellation.signal });
+                continue;
+            }
+            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.
+                let invocationId;
+                const capture = executionContext.captureLifecycleAssignment;
+                executionContext.captureLifecycleAssignment = id => { invocationId = id; capture?.(id); };
+                let command;
+                try {
+                    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 });
+                }
+                finally {
+                    if (capture)
+                        executionContext.captureLifecycleAssignment = capture;
+                    else
+                        delete executionContext.captureLifecycleAssignment;
+                }
+                if (!invocationId)
+                    throw new AppError("controller_hitl_packet_invalid", "Accepted resume did not capture its issued identity", 1);
+                const packet = { pause_id: pause.id, stage: next.stage, work_id: input.work_id, answer_file: input.file, answer_sha256: input.sha256, command, generation: row.generation, invocation_id: invocationId, resume_source_path: stageResumeSourcePath(pause, fs.readFileSync(input.file, "utf8")) };
+                context.db.run("UPDATE run_controller_operations SET receipt_json = ?, updated_at = ? WHERE operation_id = ? AND status = 'accepted'", [JSON.stringify({ hitl_packet: packet }), context.now(), answer.operation_id]);
+                const receipt = await prompt(state.sessions[state.current_session], controllerStageResumePrompt(packet), `${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 = json_set(receipt_json,'$.delivered',json('true'),'$.session_id',?), updated_at = ? WHERE operation_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 retireSession(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 retireSession(session))
+                        await pauseDependency(session, undefined, new AppError("native_session_cleanup_pending", "Retired Session still prevents conflicting workspace reuse", 1), "stage_transition");
+                    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`);
+                bindControllerStageAssignment(executionContext, command, { controllerId: row.controller_id, sessionId: session.id, stateDir: session.state_dir, stage: next.stage, contextSha256: stageContext.sha256, ...(typeof next.attempt === "number" ? { attempt: next.attempt } : {}) });
+                await assertRoute();
+                appendEvent(context, row.controller_id, "stage_entered", { stage: next.stage, session_id: session.id, context_sha256: stageContext.sha256 });
+                await prompt(session, controllerStageEntryPrompt(next.stage, command), undefined, undefined, "entry");
+                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 ?? []);
+            for (const intent of Object.values(state.child_capacity ?? {})) {
+                if (!intent.dispatched || !intent.operation_id || intent.parent_turn_id || !intent.prompt_sha256)
+                    continue;
+                let saved = context.db.get("SELECT input_json,receipt_json,status FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND generation = ?", [intent.operation_id, row.controller_id, row.generation]);
+                if (!saved)
+                    continue;
+                const dispatch = JSON.parse(saved.input_json);
+                if (!saved.receipt_json && saved.status === "outcome_unknown" && dispatch.dispatch_phase !== "prepared" && dispatch.prompt_sha256 === intent.prompt_sha256 && Array.isArray(dispatch.args)) {
+                    // Existing adapter recovery reads its durable operation; it cannot
+                    // redispatch a productive operation past external_dispatch_possible.
+                    await controllerAdapter(executionContext, row, manifest, session, dispatch.args, assertOwner, intent.operation_id, cancellation.signal, renewLease);
+                    saved = context.db.get("SELECT input_json,receipt_json,status FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND generation = ?", [intent.operation_id, row.controller_id, row.generation]);
+                }
+                if (!saved?.receipt_json)
+                    continue;
+                const receipt = JSON.parse(saved.receipt_json);
+                if ((saved.status === "completed" || dispatch.dispatch_phase === "receipt_observed") && dispatch.prompt_sha256 === intent.prompt_sha256
+                    && receipt.provider_session_id === session.id && receipt.turn?._meta?.zcode?.ddFlowRecovery?.operation_id === intent.operation_id
+                    && typeof receipt.turn._meta.zcodeNativeTurnId === "string" && receipt.turn._meta.zcodeNativeTurnId) {
+                    intent.parent_turn_id = receipt.turn._meta.zcodeNativeTurnId;
+                    saveState(context, row, state);
+                }
+            }
+            let children = controllerNativeChildren(state.last_receipt ?? {}, session.id).filter(child => !baseline.has(child.session_id));
+            if (reconcileChildCapacity(state, children, session.id))
+                saveState(context, row, state);
+            childObserver(session)?.observeSettledChildren(children);
+            const retainedFailures = failedChildren(session);
+            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 });
+                });
+            const queuedChild = children.find(child => !acceptedChildWork(context, row, childHarness, session.id, child.session_id) && state.child_capacity?.[child.session_id]?.phase === "native_message_accepted"
+                && (child.status === "failed" && state.child_capacity[child.session_id].turn_id === child.terminal_turn_id
+                    || child.status === "running" && child.continuation_admission?.proof_kind === "parent_tool_admission"));
+            if (queuedChild) {
+                const observedAt = Date.parse(state.child_capacity[queuedChild.session_id].last_signal_at ?? "");
+                if (!Number.isFinite(observedAt) || Date.now() - observedAt >= 600_000)
+                    throw new AppError("operation_observation_lost", "Accepted native child continuation has no new observed signal", 1, { child_session_id: queuedChild.session_id });
+                setStatus("waiting_for_children");
+                await delay(1000, undefined, { signal: cancellation.signal });
+                state.last_receipt = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
+                saveState(context, row, state);
+                continue;
+            }
+            const recoveryUnavailable = children.map(child => {
+                const links = 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 })]);
+                return links.length > 1 || links.some(link => link.status !== "running") ? null : unavailableProviderChildRecovery(child, session.id);
+            }).find(Boolean);
+            if (recoveryUnavailable) {
+                if (children.every(child => ["completed", "failed", "cancelled", "settled_by_root"].includes(child.status)))
+                    throw recoveryUnavailable;
+                // A blocked child does not cancel healthy siblings. Observe their own
+                // native completion before reporting the unavailable continuation.
+                setStatus("waiting_for_children");
+                await delay(1000, undefined, { signal: cancellation.signal });
+                state.last_receipt = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
+                saveState(context, row, state);
+                continue;
+            }
+            if (children.some(child => child.status === "failed" && !acceptedChildWork(context, row, childHarness, session.id, child.session_id) && renderNativeChildFollowupInstruction(childHarness, child))) {
+                const inspected = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
+                state.last_receipt = inspected;
+                saveState(context, row, state);
+                children = controllerNativeChildren(inspected, session.id).filter(child => !baseline.has(child.session_id));
+                const failed = children.filter(child => child.status === "failed" && !acceptedChildWork(context, row, childHarness, session.id, child.session_id));
+                // Freeze each distinct child refusal on its first exact observation,
+                // even while a healthy sibling still owns an active native Turn.
+                for (const failedChild of failed.filter(item => eligibleProviderChildOverload(item, session.id))) {
+                    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];
+                    if (retained?.policy && retained.policy !== CAPACITY_POLICY)
+                        throw new AppError("capacity_policy_mismatch", "Retained child episode requires its original pinned recovery policy", 1);
+                    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 provider continuation attempts", 1, { ...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) && 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 provider continuation attempts", 1, { ...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 ??= {};
+                    const followupText = renderNativeChildFollowupInstruction(childHarness, child);
+                    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, phase: "prepare", prompt_sha256: digestBytes(followupText), ...(child.continuation_ref ? { continuation_ref: child.continuation_ref } : {}) };
+                    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);
+                    // Fence dispatch before awaiting the parent: a lost ack must never
+                    // resend SendMessage into a child which may already be running.
+                    state.child_capacity[child.session_id].dispatched = true;
+                    state.child_capacity[child.session_id].phase = "dispatched";
+                    saveState(context, row, state);
+                    await prompt(session, text, operationId, "child");
+                    const parentTurnId = state.last_receipt?.turn?._meta?.zcodeNativeTurnId;
+                    if (typeof parentTurnId === "string" && parentTurnId)
+                        state.child_capacity[child.session_id].parent_turn_id = parentTurnId;
+                    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);
+                    const afterChildren = controllerNativeChildren(after, session.id);
+                    reconcileChildCapacity(state, afterChildren, session.id);
+                    if (after.descendants)
+                        after.descendants = afterChildren;
+                    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 && state.child_capacity[child.session_id].phase !== "native_message_accepted")
+                        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 repairBlockedWorks = [];
+            if (!retainedFailures.length && children.some(child => child.status === "completed" && !acceptedChildWork(context, row, childHarness, session.id, child.session_id))) {
+                const inspected = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
+                state.last_receipt = inspected;
+                saveState(context, row, state);
+                children = controllerNativeChildren(inspected, session.id).filter(child => !baseline.has(child.session_id));
+                // Do not compete with an active parent/healthy sibling or turn a known
+                // repair into a replacement fanout wave.
+                if (inspected.settled !== true || children.some(child => ["running", "unknown"].includes(child.status))) {
+                    setStatus("waiting_for_children");
+                    await delay(1000, undefined, { signal: cancellation.signal });
+                    continue;
+                }
+                let repair = null;
+                const blockers = [];
+                for (const child of children) {
+                    try {
+                        repair ??= completedChildRepair(executionContext, row, { stage: next.stage, harness: childHarness, parentId: session.id, children: [child] });
+                    }
+                    catch (error) {
+                        if (!(error instanceof AppError) || error.code !== "child_work_repair_blocked")
+                            throw error;
+                        blockers.push(error);
+                    }
+                }
+                if (repair) {
+                    reserveChildRepair(executionContext, row, repair, assertOwner);
+                    await prompt(session, repair.prompt, repair.operation_id, undefined, "work", [repair.work_id]);
+                    continue;
+                }
+                if (blockers.length) {
+                    const graph = getVnextFanoutStatus(executionContext, { projectRoot: run.project_root, runId: run.id, stage: next.stage }).orchestration;
+                    if (!graph?.works.ready.length)
+                        throw blockers[0];
+                    for (const blocker of blockers) {
+                        const workId = String(blocker.details.work_id);
+                        repairBlockedWorks.push(workId);
+                        recordTechnicalNote(context, row.project_id, row.run_id, { code: "child_work_repair_blocked", message: blocker.message,
+                            phase: "work_repair", generation: row.generation, stage: next.stage, work_id: workId, harness: childHarness,
+                            resource_identity: workId, consequence: "dependency_blocked", diagnostic_reference: JSON.stringify({
+                                protected_action: "work_finish", reason: blocker.details.reason, primary: blocker.details.primary_error,
+                                refusal_invocation_id: blocker.details.refusal_invocation_id, successor_invocation_id: blocker.details.successor_invocation_id,
+                                operation_id: blocker.details.operation_id
+                            }) });
+                    }
+                }
+            }
+            const memoryFlow = ["mb-init", "mb-upgrade", "mb-fix", "interactive"].includes(run.flow_kind) || isSourceSnapshotFlow(run.flow_kind) || routing.kind === "descriptor" && isDeliveryFlow(run.flow_kind);
+            const fanoutInput = { projectRoot: run.project_root, runId: run.id, stage: next.stage, harness: runtimeHarness(session.profile), sessionId: session.id, children, policy, profiles, dispatchFence: retainedFailures.length > 0, repairBlockedWorks, ...(state.work_failure?.deferred ? { deferredFailure: state.work_failure.work_id } : {}) };
+            const fanout = memoryFlow ? await runControllerMemoryTask(executionContext, { operation: "fanout", input: fanoutInput }, cancellation.signal)
+                : await nextControllerFanout(executionContext, fanoutInput);
+            if (memoryFlow)
+                await renewLease();
+            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 === "failure") {
+                const resolution = state.work_failure ?? prepareWorkFailureResolution(executionContext, row, next.stage, fanout.failure);
+                if (resolution.work_id !== fanout.failure.work_id || resolution.work_session_id !== fanout.failure.work_session_id)
+                    throw new AppError("work_failure_scope_changed", "Pending resolution belongs to another failed attempt", 1);
+                state.work_failure = resolution;
+                saveState(context, row, state);
+                while (!failureDecisionReady(resolution)) {
+                    const attempt = state.work_failure.submission_attempt ?? 0;
+                    if (attempt >= 2)
+                        await pauseDependency(session, undefined, new AppError("work_failure_decision_invalid", "Coordinator did not submit a valid bound failure decision", 1, workFailureDiagnostic(resolution)), "work_failure_resolution");
+                    await prompt(session, workFailureResolutionPrompt(resolution, state.work_failure.submission_diagnostic), `${row.controller_id}:failure-resolution:${digest([resolution.accepted_file, attempt, row.generation])}`, undefined, "failure_resolution", undefined, resolution);
+                    try {
+                        readFailureDecision(resolution);
+                    }
+                    catch (error) {
+                        state.work_failure.submission_diagnostic = error instanceof Error ? error.message : String(error);
+                    }
+                    state.work_failure.submission_attempt = attempt + 1;
+                    saveState(context, row, state);
+                }
+                const decision = acceptFailureDecision(executionContext, row, resolution, assertOwner);
+                if (decision.action === "block" && fanout.ready) {
+                    state.work_failure.deferred = true;
+                    saveState(context, row, state);
+                    continue;
+                }
+                if (!await resolutionWriterSettled(session)) {
+                    setStatus("waiting_for_children");
+                    await delay(1000);
+                    continue;
+                }
+                applyWorkFailureDecision(executionContext, row, resolution, decision, run.project_root, assertOwner);
+                delete state.work_failure;
+                state.last_continuation = null;
+                saveState(context, row, state);
+                continue;
+            }
+            if (fanout.kind === "wait") {
+                if (fanout.reason === "accepted_work_native_cleanup") {
+                    const pending = children.filter(child => ["running", "unknown"].includes(child.status) && acceptedChildWork(context, row, childHarness, session.id, child.session_id));
+                    for (const child of pending) {
+                        note(session, "accepted_work_native_child_pending", "native_completion", "cleanup_pending", child.session_id);
+                        try {
+                            await call(session, ["session", "cancel", "--session-id", child.session_id, ...sessionArguments(context, manifest, session)], false);
+                        }
+                        catch (error) {
+                            await pauseDependency(session, undefined, error, "accepted_child_retirement");
+                        }
+                    }
+                    const operationId = `${row.controller_id}:child-retirement:${crypto.randomUUID()}`;
+                    const observed = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false, operationId).catch(async (error) => {
+                        if (lateNativeFailure(error, session.id))
+                            await pauseDependency(session, operationId, error, "accepted_child_retirement");
+                        throw error;
+                    });
+                    state.last_receipt = observed;
+                    saveState(context, row, state);
+                    if (!acceptedChildrenRetired(pending.map(child => child.session_id), observed, session.id, operationId))
+                        await pauseDependency(session, operationId, new AppError("accepted_child_retirement_unconfirmed", "Accepted child results are retained but native retirement remains unconfirmed", 1), "accepted_child_retirement");
+                    continue;
+                }
+                setStatus(fanout.reason === "qualified_capacity_required" ? "waiting_for_capacity" : "waiting_for_children");
+                await delay(1000);
+                state.last_receipt = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
+                saveState(context, row, state);
+                continue;
+            }
+            setStatus("running");
+            if (fanout.kind === "external") {
+                let cleanupConflict = false;
+                const results = await Promise.allSettled(fanout.works.map(async (work) => {
+                    try {
+                        await renewLease();
+                        assertOwner();
+                        const receipt = memoryFlow ? await runControllerMemoryTask(executionContext, { operation: "external", input: { projectRoot: run.project_root, runId: run.id, workId: work.work_id, stage: next.stage } }, cancellation.signal)
+                            : await launchExternalWork(executionContext, { workId: work.work_id, stage: next.stage, signal: cancellation.signal });
+                        if (memoryFlow) {
+                            await renewLease();
+                            assertOwner();
+                        }
+                        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;
+                        try {
+                            const stopped = await runHarnessAdapter({ executable, args: ["daemon", "stop", "--state-dir", launch.state_dir, "--json"], env: controllerEnvironment(context, manifest), operationId: `${row.controller_id}:${work.work_id}:settle` });
+                            await confirmStopped(launch.state_dir, stopped);
+                            appendEvent(context, row.controller_id, "external_work_settled", { work_id: work.work_id, receipt: stopped });
+                        }
+                        catch {
+                            recordTechnicalNote(context, row.project_id, row.run_id, { code: "external_work_cleanup_pending", message: "The Work outcome is committed; its native resources require retirement.", phase: "external_work_cleanup", generation: row.generation, stage: next.stage, work_id: work.work_id, harness: runtimeHarness(resolved.worker), resource_identity: launch.state_dir, diagnostic_reference: launch.state_dir, source_operation_id: `${row.controller_id}:${work.work_id}:settle`, consequence: "cleanup_pending" });
+                            try {
+                                cleanupConflict ||= !managedDaemonExecutionAbsent(executionContext, { stateDir: launch.state_dir, projectId: row.project_id, runId: row.run_id });
+                            }
+                            catch {
+                                cleanupConflict = true;
+                            }
+                        }
+                    }
+                    catch (error) {
+                        if (!(error instanceof AppError && error.code === "controller_technical_dependency_paused"))
+                            await stopAfterFailure(error);
+                        throw error;
+                    }
+                }));
+                const rejected = results.find((result) => result.status === "rejected");
+                if (rejected)
+                    throw fatal ?? rejected.reason;
+                if (cleanupConflict)
+                    await pauseDependency(session, undefined, new AppError("external_work_cleanup_pending", "Accepted external Work still has an unretired workspace writer", 1), "workspace_reuse");
+                state.last_continuation = null;
+                saveState(context, row, state);
+                continue;
+            }
+            if (state.last_continuation === fanout.fingerprint) {
+                // Re-read committed evidence before pausing; a settlement can race the
+                // graph observation. No new prompt or invocation is issued to reconcile.
+                const latest = executionContext.db.get("SELECT status,index_json FROM runs WHERE project_id=? AND id=?", [row.project_id, row.run_id]);
+                const latestStage = latest && [...(JSON.parse(latest.index_json).stage_runs ?? [])].reverse().find((stage) => stage.stage === next.stage);
+                if (latest?.status === "done" || latestStage?.status === "done")
+                    continue;
+                if (fanout.authority) {
+                    const current = currentStageFinishAuthority(executionContext, next.stage);
+                    if (current?.status === "issued" && current.command) {
+                        const checkpoint = controllerSemanticCheckpoint(executionContext, { stage: next.stage, phase: "stage_finish", command: current.command, invocationId: current.id });
+                        if (JSON.stringify(checkpoint) !== JSON.stringify(fanout.checkpoint))
+                            continue;
+                    }
+                }
+                let rejected;
+                try {
+                    assertNoCorrelatedRejection(context, { projectId: row.project_id, runId: row.run_id, generation: row.generation, stage: next.stage, turn: state.turns });
+                }
+                catch (error) {
+                    if (!(error instanceof AppError))
+                        throw error;
+                    rejected = error;
+                }
+                await pauseDependency(session, undefined, new AppError(rejected?.code ?? "fanout_stage_nonprogressing", rejected?.message ?? "The coordinator repeated an unchanged continuation", 1, { ...rejected?.details, stage: next.stage, attempt: stageAttempt(executionContext, row.project_id, row.run_id, next.stage), action: fanout.action,
+                    checkpoint: JSON.parse(fanout.fingerprint), ...(fanout.authority ? { authority: fanout.authority } : {}), reconciliation_required: true }), "productive_continuation");
+            }
+            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, undefined, undefined, fanout.action === "materialize_graph" ? "graph" : fanout.action === "dispatch_work" ? "work" : "finish", fanout.work_ids);
+        }
+    }
+    catch (error) {
+        if (technicalPauseRequested || error instanceof AppError && error.code === "controller_technical_dependency_paused")
+            return;
+        if (!fatal && error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale", "controller_owner_mismatch"].includes(error.code))
+            throw error;
+        let cause = fatal ?? error;
+        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;
+}