@deksden-com/dd-flow-cli 0.9.0-beta.7 → 0.9.0-beta.75

package/dist/services/run-controller.js

@@ -0,0 +1,733 @@
+import { assertLifecycleOutcomes, managedInvocationContext, managedLifecycleCommand } from "./lifecycle-invocations.js";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { ensureRunControllerStorage, getDatabase } from "../storage/database.js";
+import { canonicalPath, resolveProjectRoot } from "../storage/paths.js";
+import { AppError } from "../shared/errors.js";
+import { parseRuntimeBudget } from "./runtime-budget.js";
+import { requireProjectByRoot } from "./projects.js";
+import { assertRunMutationAllowed, recoveryGuard } from "./run-recovery.js";
+import { getFlowRunStatus, setFlowRunRecoveryPaused } from "./runs.js";
+import { loadExternalStageContext } from "./stage-context.js";
+import { flowCommand } from "./stage-pause.js";
+import { resolveStageTransition, sameSessionProfile, runtimeHarness } from "./execution-policy.js";
+import { resolveHarnessCommand, harnessRuntimeArguments } from "./harness-config.js";
+import { adapterSessionId, prepareHarnessFlowExecutable, runHarnessAdapter } from "./harness-adapter.js";
+import { confirmManagedProcess, heartbeatManagedProcess, finishManagedProcess, processTreeIsAlive, resourceHome } from "./managed-processes.js";
+import { readNativeDaemonState, requireManagedDaemonBinding } from "./managed-daemon-binding.js";
+import { initCodexHome } from "./hooks.js";
+import { launchExternalWork } from "./external-work-launch.js";
+import { controllerNativeChildren, controllerStageEntryPrompt, nextControllerFanout } from "./controller-fanout.js";
+import { claimQueuedMergeRequest } from "./merge-server.js";
+import { prepareVnextCodeWorkspace } from "./vnext-code.js";
+import { requireRun, requireController, controllerReceipt, appendEvent, saveState, digest, digestBytes, errorRecord } from "./run-controller-state.js";
+import { spawnController, recordControllerLauncher, claimControllerProcess, markControllerDispatchReady } from "./run-controller-process.js";
+import { controllerAdapter, controllerEnvironment, sessionArguments } from "./run-controller-adapter.js";
+import { resumeControllerSession, failControllerRecovery } from "./run-controller-recovery.js";
+import { captureControllerBoundary } from "./run-controller-capture.js";
+import { requestRunControl } from "./run-control-worker.js";
+export { resumeRunController } from "./run-controller-recovery.js";
+/** Persist intent before spawning. A repeated client observes the same owner. */
+export async function launchRunController(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);
+    ensureRunControllerStorage(context.db);
+    const existing = context.db.get("SELECT * FROM run_controllers WHERE project_id = ? AND run_id = ? AND request_id = ?", [project.id, run.id, input.requestId]);
+    if (existing) {
+        if (existing.request_hash !== requestHash)
+            throw new AppError("runtime_request_conflict", "Managed launch request id has different inputs", 1);
+        return { ...await spawnController(context, existing), reused: true };
+    }
+    const generation = assertRunMutationAllowed(context, project.id, run.id);
+    if (run.status !== "running")
+        throw new AppError("invalid_run_state", "Managed launch requires a running logical RUN", 1, { status: run.status });
+    const index = JSON.parse(run.index_json);
+    const execution = index.execution_profile;
+    if (!execution?.settings.execution || !execution.agent_profiles)
+        throw new AppError("execution_profile_not_frozen", "Managed launch requires the RUN's frozen execution profiles", 1);
+    const contexts = readContexts(input.contextFile, input.contextSha256);
+    const next = getFlowRunStatus(context, { projectRoot: project.root, runId: run.id }).continuation;
+    if (next.kind !== "start_stage" || !next.stage)
+        throw new AppError("controller_attach_required", "Managed launch cannot replace an attached or unfinished coordinator; reconcile its existing owner", 1, { continuation: next });
+    if (!contexts[next.stage])
+        throw new AppError("controller_context_missing", "Managed context omits the first stage", 2, { stage: next.stage });
+    const adapters = {};
+    for (const profile of Object.values(execution.agent_profiles)) {
+        const harness = runtimeHarness(profile);
+        adapters[harness] = { executable: resolveHarnessCommand(context.ddFlowHome, harness, "adapter"), runtime_args: harnessRuntimeArguments(context.ddFlowHome, harness) };
+    }
+    const controllerId = `DRV-${crypto.randomUUID()}`;
+    const root = path.join(run.run_root, "controllers", controllerId);
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    const flowExecutable = prepareHarnessFlowExecutable(context, root);
+    const 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 frozenContexts = {};
+    for (const [stage, value] of Object.entries(contexts)) {
+        const file = path.join(root, `${stage}.context.json`);
+        fs.writeFileSync(file, value.bytes, { flag: "wx", mode: 0o600 });
+        frozenContexts[stage] = { file, sha256: value.sha256 };
+    }
+    const manifest = { schema_id: "dd-flow/run-controller-manifest@1", request, execution_profile: execution, contexts: frozenContexts, adapters, flow_executable: flowExecutable, resource_home: resourceHome(context), budget };
+    const token = crypto.randomUUID();
+    const now = context.now();
+    const state = { stage: null, sessions: [], current_session: null, turns: 0, last_continuation: null };
+    context.db.beginWriteTransaction();
+    try {
+        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);
+            context.db.exec("COMMIT");
+            return { ...controllerReceipt(duplicate), reused: true };
+        }
+        assertRunMutationAllowed(context, project.id, run.id, generation);
+        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));
+        appendEvent(context, controllerId, "launch_requested", { request_id: input.requestId, generation, request_hash: requestHash });
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    return await spawnController(context, requireController(context, controllerId));
+}
+/**
+ * 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 function controllerLeaseMonitor(heartbeat) {
+    let lost = false;
+    let unconfirmed = null;
+    const lostError = () => new AppError("controller_lease_lost", "Managed owner lease could not be confirmed", 1);
+    return {
+        tick() {
+            try {
+                if (!heartbeat())
+                    lost = true;
+                else
+                    unconfirmed = null;
+            }
+            catch (error) {
+                unconfirmed = error;
+            }
+        },
+        isConfirmed() { return !lost && unconfirmed === null; },
+        assertConfirmed() {
+            if (lost)
+                throw lostError();
+            if (unconfirmed === null)
+                return;
+            try {
+                if (!heartbeat()) {
+                    lost = true;
+                    throw lostError();
+                }
+                unconfirmed = null;
+            }
+            catch (error) {
+                if (error instanceof AppError)
+                    throw error;
+                throw new AppError("controller_lease_unconfirmed", "Managed owner lease could not be refreshed", 1, { cause: error instanceof Error ? error.message : String(error) });
+            }
+        }
+    };
+}
+/** No initialization, provider calls or lease takeover on the observation path. */
+export function runControllerStatus(context, input) {
+    if (input.after !== undefined && (!Number.isSafeInteger(input.after) || input.after < 0))
+        throw new AppError("usage", "--after must be a non-negative cursor", 2);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    if (!context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controllers'"))
+        return { ok: true, run_id: run.id, controller: null, events: [], next_cursor: input.after ?? 0 };
+    const row = context.db.get("SELECT * FROM run_controllers WHERE project_id = ? AND run_id = ? ORDER BY created_at DESC, controller_id DESC LIMIT 1", [project.id, run.id]);
+    if (!row)
+        return { ok: true, run_id: run.id, controller: null, events: [], next_cursor: input.after ?? 0 };
+    const events = context.db.all("SELECT sequence, event_type, data_json, created_at FROM run_controller_events WHERE controller_id = ? AND sequence > ? ORDER BY sequence LIMIT 100", [row.controller_id, input.after ?? 0]);
+    return { ...controllerReceipt(row), events: events.map(event => ({ sequence: event.sequence, type: event.event_type, data: JSON.parse(event.data_json), at: event.created_at })), next_cursor: events.at(-1)?.sequence ?? input.after ?? 0 };
+}
+export async function serveRunController(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const row = requireController(context, input.controllerId);
+    if (row.project_id !== project.id || row.run_id !== input.runId || row.owner_token !== context.env.DD_FLOW_CONTROLLER_TOKEN)
+        throw new AppError("controller_owner_mismatch", "Managed serve does not own this launch", 1);
+    claimControllerProcess(context, row);
+    if (!row.process_id || !row.process_lease_token)
+        throw new AppError("controller_owner_mismatch", "Managed owner has no resource lease", 1);
+    confirmManagedProcess(context, { id: row.process_id, leaseToken: row.process_lease_token, pid: process.pid, processGroupId: process.pid, ownerPid: process.pid });
+    const lease = controllerLeaseMonitor(() => heartbeatManagedProcess(context, { id: row.process_id, leaseToken: row.process_lease_token }));
+    const heartbeat = setInterval(() => {
+        try {
+            lease.tick();
+            if (lease.isConfirmed()) {
+                const guard = recoveryGuard(context, row.project_id, row.run_id);
+                if ((guard?.generation ?? 0) === row.generation && !["draining", "sealed", "resuming"].includes(guard?.status ?? ""))
+                    context.db.run("UPDATE merge_requests SET dispatch_lease_expires_at = ?, updated_at = ? WHERE project_id = ? AND run_id = ? AND dispatch_owner = ? AND status = 'dispatching'", [new Date(Date.now() + 120_000).toISOString(), context.now(), row.project_id, row.run_id, row.controller_id]);
+            }
+        }
+        catch { /* The lease monitor distinguishes renewal uncertainty from loss. */ }
+    }, 30_000);
+    heartbeat.unref();
+    const manifest = JSON.parse(row.manifest_json);
+    const state = JSON.parse(row.state_json);
+    const assertPhysicalOwner = () => {
+        lease.assertConfirmed();
+        const current = requireController(context, row.controller_id);
+        if (current.owner_pid !== process.pid || current.owner_token !== row.owner_token || !["running", "capturing", "waiting_for_user", "waiting_for_context", "waiting_for_children", "waiting_for_capacity", "waiting_for_merge"].includes(current.status))
+            throw new AppError("controller_owner_mismatch", "Controller no longer owns productive dispatch", 1);
+    };
+    const assertOwner = () => { assertPhysicalOwner(); assertRunMutationAllowed(context, row.project_id, row.run_id, row.generation); };
+    let primaryFailure;
+    const retainSecondary = (phase, error) => {
+        process.stderr.write(`${JSON.stringify({ controller_id: row.controller_id, phase, primary: errorRecord(primaryFailure), secondary: errorRecord(error) })}\n`);
+    };
+    try {
+        context.db.exec("SAVEPOINT controller_ready_status");
+        try {
+            markControllerDispatchReady(context, row);
+            if (!state.recovery && (recoveryGuard(context, row.project_id, row.run_id)?.generation ?? 0) === row.generation && requireRun(context, row.project_id, row.run_id).status === "paused")
+                setFlowRunRecoveryPaused(context, row.project_id, row.run_id, false);
+            context.db.exec("RELEASE controller_ready_status");
+        }
+        catch (error) {
+            context.db.exec("ROLLBACK TO controller_ready_status; RELEASE controller_ready_status");
+            throw error;
+        }
+        appendEvent(context, row.controller_id, "owner_started", { pid: process.pid, generation: row.generation });
+        if (state.recovery)
+            await resumeControllerSession(context, row, manifest, state, assertPhysicalOwner);
+        await executeController(context, row, manifest, state, assertOwner, assertPhysicalOwner);
+        return controllerReceipt(requireController(context, row.controller_id));
+    }
+    catch (error) {
+        primaryFailure = error;
+        try {
+            try {
+                failControllerRecovery(context, row, state, error);
+            }
+            catch (secondary) {
+                retainSecondary("fail_controller_recovery", secondary);
+            }
+            if ((error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale"].includes(error.code) || (recoveryGuard(context, row.project_id, row.run_id)?.generation ?? 0) !== row.generation)
+                && context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controls'")) {
+                const guard = recoveryGuard(context, row.project_id, row.run_id);
+                const control = guard && ["draining", "sealed"].includes(guard.status) && context.db.get("SELECT control_id, action FROM run_controls WHERE project_id = ? AND run_id = ? AND recovery_id = ? AND status IN ('requested','settled')", [row.project_id, row.run_id, guard.recovery_id]);
+                if (control) {
+                    // Control is a later state transition, not evidence that the causal
+                    // failure which fenced admission disappeared.
+                    context.db.run("UPDATE run_controllers SET status = CASE WHEN last_error_json IS NULL THEN 'control_requested' ELSE status END, updated_at = ? WHERE controller_id = ? AND owner_token = ?", [context.now(), row.controller_id, row.owner_token]);
+                    appendEvent(context, row.controller_id, "control_boundary_reached", { control_id: control.control_id, action: control.action, generation: guard.generation, settled: false });
+                    return controllerReceipt(requireController(context, row.controller_id));
+                }
+            }
+            context.db.exec("SAVEPOINT controller_failure_status");
+            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));
+                context.db.exec("RELEASE controller_failure_status");
+            }
+            catch (failure) {
+                retainSecondary("persist_controller_failure", failure);
+                try {
+                    context.db.exec("ROLLBACK TO controller_failure_status; RELEASE controller_failure_status");
+                }
+                catch (rollback) {
+                    retainSecondary("rollback_controller_failure", rollback);
+                }
+            }
+        }
+        catch (secondary) {
+            retainSecondary("controller_failure_boundary", secondary);
+        }
+        throw error;
+    }
+    finally {
+        clearInterval(heartbeat);
+        finishOwner();
+    }
+    function finishOwner() {
+        try {
+            finishManagedProcess(context, { id: row.process_id, leaseToken: row.process_lease_token, state: "stopped", reason: "controller_owner_exited" });
+        }
+        catch (cleanup) {
+            if (!primaryFailure)
+                throw cleanup;
+            retainSecondary("finish_controller_process", cleanup);
+        }
+    }
+}
+/** Public HITL input: persist raw bytes, never deliver a turn from this client. */
+export function answerRunController(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 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 bytes = fs.readFileSync(path.resolve(input.answerFile));
+    if (!bytes.toString("utf8").trim())
+        throw new AppError("validation", "HITL answer must not be empty", 2);
+    const operationId = `${row.controller_id}:answer:${input.requestId}`;
+    const answerHash = digestBytes(bytes);
+    const hash = digest({ pause_id: input.pauseId, answer_sha256: answerHash });
+    context.db.beginWriteTransaction();
+    try {
+        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);
+            context.db.exec("COMMIT");
+            return { ok: true, operation_id: operationId, status: prior.status, reused: true };
+        }
+        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, project.id, 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);
+        const file = path.join(row.state_dir, `answer-${digest(operationId)}.md`);
+        try {
+            fs.writeFileSync(file, bytes, { flag: "wx", mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            // A crash before COMMIT may leave the immutable answer file behind.
+            if (!fs.readFileSync(file).equals(bytes))
+                throw new AppError("runtime_request_conflict", "Persisted answer bytes differ from this retry", 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: stage.pause.work_id, file, sha256: answerHash }), now, now]);
+        appendEvent(context, row.controller_id, "answer_accepted", { operation_id: operationId, pause_id: input.pauseId, answer_sha256: answerHash });
+        context.db.exec("COMMIT");
+        return { ok: true, operation_id: operationId, status: "accepted" };
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+}
+/** Publish a missing stage slice without giving the submitting client dispatch rights. */
+export function supplyRunControllerContext(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 });
+    context.db.beginWriteTransaction();
+    try {
+        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);
+            context.db.exec("COMMIT");
+            return { ok: true, operation_id: operationId, status: prior.status, reused: true };
+        }
+        assertRunMutationAllowed(context, 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);
+        loadExternalStageContext({ file: input.contextFile, expectedSha256: input.contextSha256, stage: input.stage });
+        const bytes = fs.readFileSync(input.contextFile);
+        if (digestBytes(bytes) !== input.contextSha256)
+            throw new AppError("context_checksum_mismatch", "Context changed before publication", 2);
+        const file = path.join(row.state_dir, `${input.stage}.context.json`);
+        try {
+            fs.writeFileSync(file, bytes, { flag: "wx", mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (!fs.readFileSync(file).equals(bytes))
+                throw new AppError("stage_context_replacement", "Unpublished context bytes differ from this request", 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 });
+        context.db.exec("COMMIT");
+        return { ok: true, operation_id: operationId, status: "accepted" };
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+}
+async function executeController(context, row, manifest, state, assertOwnership, assertPhysicalOwner) {
+    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 policy = manifest.execution_profile.settings.execution;
+    const profiles = manifest.execution_profile.agent_profiles;
+    let executionContext = { ...context, env: { ...context.env, DD_FLOW_BIN: manifest.flow_executable, DD_FLOW_RESOURCE_HOME: manifest.resource_home, DD_FLOW_RUNTIME_BUDGET: manifest.budget ? JSON.stringify(manifest.budget) : undefined, DD_FLOW_CODE_READINESS_OWNER: row.controller_id } };
+    const bindInvocationScope = (session) => {
+        executionContext = managedInvocationContext(executionContext, { harness: runtimeHarness(session.profile), stateDir: session.state_dir, sessionId: session.id,
+            projectRoot: manifest.request.project_root, runId: row.run_id, generation: row.generation });
+    };
+    let lastCapture = null;
+    let fatal;
+    let stopping;
+    const cancellation = new AbortController();
+    const stopAfterFailure = (error) => {
+        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) => {
+        const changed = context.db.run("UPDATE run_controllers SET status = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ? AND status <> ?", [status, context.now(), row.controller_id, row.owner_token, status]);
+        if (changed.changes)
+            appendEvent(context, row.controller_id, "status_changed", { status, stage: state.stage });
+    };
+    const call = (session, args, productive = true) => controllerAdapter(executionContext, row, manifest, session, args, productive ? assertOwner : undefined, undefined, productive ? cancellation.signal : undefined);
+    const confirmStopped = async (stateDir, receipt) => {
+        const fail = () => new AppError("controller_native_shutdown_unproven", "The managed daemon is not proven clean and closed", 1, { state_dir: stateDir, receipt });
+        if (receipt.stopped !== true || receipt.clean !== true)
+            throw fail();
+        const binding = requireManagedDaemonBinding(executionContext, { stateDir, projectId: row.project_id, runId: row.run_id });
+        const deadline = performance.now() + 30_000;
+        while (processTreeIsAlive(binding.process) && performance.now() < deadline)
+            await delay(100);
+        const current = readNativeDaemonState(stateDir);
+        if (processTreeIsAlive(binding.process) || current.shutdown_state !== "clean"
+            || current.pid !== binding.process.pid || (current.daemon_id ?? current.config?.daemonId) !== (binding.state.daemon_id ?? binding.state.config?.daemonId)
+            || current.resource_process?.id !== binding.process.id || current.resource_process?.lease_token !== binding.process.lease_token)
+            throw fail();
+    };
+    const stopSession = async (session) => {
+        if (session.stopped)
+            return;
+        const receipt = await call(session, ["daemon", "stop", "--state-dir", session.state_dir, "--json"], false);
+        await confirmStopped(session.state_dir, receipt);
+        session.stopped = true;
+        saveState(context, row, state);
+        appendEvent(context, row.controller_id, "session_stopped", { session_id: session.id || null, state_dir: session.state_dir, receipt });
+    };
+    const settle = async () => {
+        const results = await Promise.allSettled(state.sessions.map(stopSession));
+        const failure = results.find((result) => result.status === "rejected");
+        if (failure)
+            throw failure.reason;
+    };
+    const prompt = async (session, text, operationId) => {
+        const file = path.join(row.state_dir, `turn-${String(state.turns + 1).padStart(5, "0")}.md`);
+        fs.writeFileSync(file, `${text}\n`, { flag: "wx", mode: 0o600 });
+        state.turns += 1;
+        saveState(context, row, state);
+        let receipt;
+        try {
+            const adapter = controllerAdapter(executionContext, row, manifest, session, ["session", "prompt", "--session-id", session.id, "--prompt-file", file, ...sessionArguments(context, manifest, session)], assertOwner, operationId, cancellation.signal);
+            try {
+                receipt = await adapter;
+                checkOutcomes();
+                if (fatal)
+                    throw fatal;
+            }
+            catch (error) {
+                if (!fatal && error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale", "controller_owner_mismatch"].includes(error.code))
+                    throw error;
+                await stopAfterFailure(error);
+                cancellation.abort();
+                await adapter.catch(() => { });
+                throw fatal ?? error;
+            }
+        }
+        finally { /* Adapter settlement is joined before returning. */ }
+        state.last_receipt = receipt;
+        saveState(context, row, state);
+        return receipt;
+    };
+    const monitor = setInterval(() => {
+        if (fatal)
+            return;
+        try {
+            checkOutcomes();
+        }
+        catch (error) {
+            void stopAfterFailure(error);
+        }
+    }, 1000);
+    monitor.unref();
+    try {
+        for (;;) {
+            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;
+            const completed = state.stage && view.index.stage_runs.find(stage => stage.stage === state.stage && ["done", "skipped"].includes(stage.status));
+            if (completed && manifest.request.capture_root && ["start_stage", "terminal"].includes(next.kind)) {
+                const key = JSON.stringify([completed.stage, completed.attempt, completed.started_at, completed.completed_at]);
+                if (key !== lastCapture) {
+                    await captureControllerBoundary(executionContext, row, manifest, completed, next.kind === "start_stage" ? next.stage : null, assertPhysicalOwner);
+                    lastCapture = key;
+                }
+            }
+            if (completed && manifest.request.stop_after === state.stage) {
+                await settle();
+                setStatus("stop_target_reached");
+                appendEvent(context, row.controller_id, "stop_target_reached", { stage: state.stage, attempt: completed.attempt ?? null });
+                return;
+            }
+            if (next.kind === "terminal") {
+                await settle();
+                setStatus(run.status === "cancelled" ? "cancelled" : "completed");
+                appendEvent(context, row.controller_id, "terminal", { reason: next.reason });
+                return;
+            }
+            if (next.kind === "paused") {
+                setStatus("waiting_for_user");
+                const pause = view.index.stage_runs.find(stage => stage.stage === next.stage)?.pause;
+                if (!pause || state.current_session === null)
+                    throw new AppError("controller_hitl_missing", "Paused RUN has no managed Session or HITL receipt", 1);
+                const answer = context.db.get("SELECT operation_id, input_json FROM run_controller_operations WHERE controller_id = ? AND status = 'accepted' 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;
+                }
+                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);
+                assertOwner();
+                // The accepted answer is logical intent; only its generation-bound
+                // adapter operation represents a physical dispatch that stop must drain.
+                const command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage resume ${run.id} --stage ${next.stage} --work ${input.work_id} --project-root ${JSON.stringify(run.project_root)} --answer-stdin --json < ${JSON.stringify(input.file)}`);
+                const receipt = await prompt(state.sessions[state.current_session], `The user supplied the raw answer for pause ${pause.id}. Your first tool call must be this exact standalone command:\n\n${command}\n\nDo not alter the answer. Follow the returned packet, then stop at this Stage boundary.`, `${answer.operation_id}:prompt:${row.generation}`);
+                context.db.run("UPDATE run_controller_operations SET status = 'completed', receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify({ delivered: true, session_id: adapterSessionId(receipt) }), context.now(), answer.operation_id]);
+                state.last_continuation = null;
+                saveState(context, row, state);
+                setStatus("running");
+                continue;
+            }
+            if (next.kind === "blocked" || next.kind === "wait" || !next.stage)
+                throw new AppError("controller_continuation_blocked", "RUN has no legal managed continuation", 1, { continuation: next });
+            if (next.kind === "start_stage") {
+                // Only context slices can be added; profiles and launch inputs stay frozen.
+                manifest.contexts = JSON.parse(requireController(context, row.controller_id).manifest_json).contexts;
+                const stageContext = manifest.contexts[next.stage];
+                if (!stageContext) {
+                    if (requireController(context, row.controller_id).status !== "waiting_for_context")
+                        appendEvent(context, row.controller_id, "context_required", { stage: next.stage, attempt: next.attempt ?? null });
+                    setStatus("waiting_for_context");
+                    await delay(1000);
+                    continue;
+                }
+                loadExternalStageContext({ file: stageContext.file, expectedSha256: stageContext.sha256, stage: next.stage });
+                const transition = resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy, profiles, ...(state.stage ? { fromStage: state.stage } : {}), stage: next.stage, stageSessionMode: manifest.execution_profile.settings.stage_session_mode, mergeMode: manifest.execution_profile.settings.merge_mode });
+                if (next.stage === "merge" && manifest.execution_profile.settings.merge_mode === "server" && !state.merge_claim) {
+                    const 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 });
+                }
+                let session = state.current_session === null ? null : state.sessions[state.current_session];
+                if (!session || transition.session_mode === "new_session" || !sameSessionProfile(session.profile, transition.coordinator)) {
+                    if (session)
+                        await stopSession(session);
+                    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: next.stage === "merge" && state.merge_claim ? state.merge_claim.target_workspace : run.workspace_root, 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.last_continuation = null;
+                saveState(context, row, state);
+                setStatus("running");
+                if (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 });
+                    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`);
+                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, responseFile));
+                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 baseline = new Set(state.native_baseline ?? []);
+            const children = controllerNativeChildren(state.last_receipt ?? {}, session.id).filter(child => !baseline.has(child.session_id));
+            const fanout = await nextControllerFanout(executionContext, { projectRoot: run.project_root, runId: run.id, stage: next.stage, harness: runtimeHarness(session.profile), sessionId: session.id, children, policy, profiles });
+            assertOwner();
+            if (fanout.kind === "none")
+                throw new AppError("incomplete_subject_turn", "Managed Turn ended without a completed Stage or declared continuation", 1, { stage: next.stage });
+            if (fanout.kind === "wait") {
+                setStatus(fanout.reason === "qualified_capacity_required" ? "waiting_for_capacity" : "waiting_for_children");
+                await delay(1000);
+                state.last_receipt = await call(session, ["session", "inspect", "--session-id", session.id, "--state-dir", session.state_dir, "--json"], false);
+                saveState(context, row, state);
+                continue;
+            }
+            setStatus("running");
+            if (fanout.kind === "external") {
+                const results = await Promise.allSettled(fanout.works.map(async (work) => {
+                    try {
+                        assertOwner();
+                        const receipt = await launchExternalWork(executionContext, { workId: work.work_id, stage: next.stage });
+                        if (fatal)
+                            throw fatal;
+                        appendEvent(context, row.controller_id, "external_work_observed", { work_id: work.work_id, receipt });
+                        const launch = context.db.get("SELECT state_dir, profile_json FROM work_launches WHERE work_id = ?", [work.work_id]);
+                        const status = context.db.get("SELECT status FROM works WHERE work_id = ?", [work.work_id])?.status;
+                        if (!launch || !["completed", "failed", "cancelled"].includes(status ?? ""))
+                            throw new AppError("external_work_unsettled", "External launch returned without its terminal Work receipt; observe it rather than relaunching", 1, { work_id: work.work_id, status });
+                        const resolved = JSON.parse(launch.profile_json);
+                        const executable = manifest.adapters[runtimeHarness(resolved.worker)].executable;
+                        const stopped = await runHarnessAdapter({ executable, args: ["daemon", "stop", "--state-dir", launch.state_dir, "--json"], env: controllerEnvironment(context, manifest), operationId: `${row.controller_id}:${work.work_id}:settle` });
+                        await confirmStopped(launch.state_dir, stopped);
+                        appendEvent(context, row.controller_id, "external_work_settled", { work_id: work.work_id, receipt: stopped });
+                    }
+                    catch (error) {
+                        await stopAfterFailure(error);
+                        throw error;
+                    }
+                }));
+                const rejected = results.find((result) => result.status === "rejected");
+                if (rejected)
+                    throw fatal ?? rejected.reason;
+                state.last_continuation = null;
+                saveState(context, row, state);
+                continue;
+            }
+            if (state.last_continuation === fanout.fingerprint)
+                throw new AppError("fanout_stage_nonprogressing", "The coordinator repeated an unchanged Work-graph continuation", 1, { stage: next.stage });
+            state.last_continuation = fanout.fingerprint;
+            saveState(context, row, state);
+            await prompt(session, fanout.prompt);
+        }
+    }
+    catch (error) {
+        if (!fatal && error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale", "controller_owner_mismatch"].includes(error.code))
+            throw error;
+        await stopAfterFailure(fatal ?? error);
+        throw fatal ?? error;
+    }
+    finally {
+        clearInterval(monitor);
+        if (stopping)
+            await stopping;
+        observer.db.close?.();
+    }
+}
+function readContexts(file, expected) {
+    const bytes = fs.readFileSync(path.resolve(file));
+    if (digestBytes(bytes) !== expected)
+        throw new AppError("context_checksum_mismatch", "Managed context package SHA-256 differs", 2);
+    const value = JSON.parse(bytes.toString("utf8"));
+    if (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);
+        loadExternalStageContext({ file: source.file, expectedSha256: source.sha256, stage });
+        const content = fs.readFileSync(source.file);
+        if (digestBytes(content) !== source.sha256)
+            throw new AppError("context_checksum_mismatch", "Stage context changed while freezing the launch", 2);
+        result[stage] = { bytes: content, sha256: source.sha256 };
+    }
+    return result;
+}