@deksden-com/dd-flow-cli 0.9.0-beta.8 → 0.9.0-beta.80

package/dist/services/run-control.js

@@ -0,0 +1,876 @@
+import { setFlowRunRecoveryPaused } from "./runs.js";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { ensureRunControlStorage } from "../storage/database.js";
+import { canonicalPath, resolveProjectRoot } from "../storage/paths.js";
+import { AppError } from "../shared/errors.js";
+import { requireProjectByRoot } from "./projects.js";
+import { recoveryGuard } from "./run-recovery.js";
+import path from "node:path";
+import { adapterSessionId, runHarnessAdapter } from "./harness-adapter.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { harnessKey } from "./harness-config.js";
+import { finishManagedProcess, managedLeaseReleased, managedProcessBinding, managedProcessRuntimeHome, managedProcessStatus, processIsAlive, processTreeIsAlive, resourceHome, stopManagedProcess } from "./managed-processes.js";
+import { reconcileUnfinishedChecks } from "./code-checks.js";
+import { controlStatusReceipt } from "./run-control-receipt.js";
+import { assertNativeCancellationReceipt, cancelControlledNativeSession, inspectControlledNativeSession } from "./native-session-control.js";
+/** Durable projection only: status never probes a provider or acquires an owner. */
+export function runControlStatus(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    // One read snapshot prevents a concurrent stop/resume from mixing generations
+    // across the request, arbiter and worker projections. Savepoints also nest.
+    context.db.exec("SAVEPOINT run_control_status");
+    try {
+        return readControlStatus(context, input, project);
+    }
+    finally {
+        context.db.exec("RELEASE run_control_status");
+    }
+}
+function readControlStatus(context, input, project) {
+    const run = context.db.get("SELECT status FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
+    if (!run)
+        throw new AppError("not_found", "RUN is not registered", 1);
+    const scope = { project_id: project.id, run_id: input.runId };
+    const empty = controlStatusReceipt({ ok: true, scope, run_status: run.status, control: null, operations: [], worker: null, resume_operation: null }, input);
+    if (input.controlId === null)
+        return empty;
+    if (!context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controls'"))
+        return empty;
+    const row = context.db.get("SELECT c.*, g.generation, g.status AS guard_status, g.settlement_json, g.capture_path FROM run_controls c JOIN run_recovery_guards g ON g.recovery_id = c.recovery_id WHERE c.project_id = ? AND c.run_id = ? AND (? IS NULL OR c.control_id = ?) ORDER BY g.generation DESC LIMIT 1", [project.id, input.runId, input.controlId ?? null, input.controlId ?? null]);
+    if (!row)
+        return empty;
+    const current = recoveryGuard(context, project.id, input.runId);
+    const operations = context.db.all("SELECT operation_id, target_json, status, receipt_json, error_json, updated_at FROM run_control_operations WHERE control_id = ? ORDER BY created_at, operation_id", [row.control_id]);
+    const worker = context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_control_workers'")
+        ? context.db.get("SELECT status, process_id, owner_pid, snapshot_json, error_json, updated_at FROM run_control_workers WHERE control_id = ?", [row.control_id]) : undefined;
+    const resume = context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controller_operations'")
+        ? context.db.get("SELECT o.operation_id, o.controller_id, json_extract(o.input_json, '$.request_id') AS request_id, o.status, o.receipt_json, o.error_json, o.updated_at 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 json_extract(o.input_json, '$.action') = 'control_resume' AND json_extract(o.input_json, '$.control_id') = ? ORDER BY o.created_at DESC, o.rowid DESC LIMIT 1", [project.id, input.runId, row.control_id]) : undefined;
+    return controlStatusReceipt({
+        ...empty,
+        control: {
+            control_id: row.control_id, request_id: row.request_id, recovery_id: row.recovery_id,
+            generation: row.generation, requested_mode: row.action, status: row.status,
+            current: current?.recovery_id === row.recovery_id,
+            admission: row.guard_status,
+            request: JSON.parse(row.request_json),
+            // A completed interrupt operation is not evidence of whole-tree quiescence.
+            settlement: row.settlement_json ? JSON.parse(row.settlement_json) : null,
+            capture_path: row.capture_path,
+            created_at: row.created_at, updated_at: row.updated_at
+        },
+        operations: operations.map(operation => ({ operation_id: operation.operation_id, target: JSON.parse(operation.target_json), status: operation.status, receipt: operation.receipt_json ? JSON.parse(operation.receipt_json) : null, error: operation.error_json ? JSON.parse(operation.error_json) : null, updated_at: operation.updated_at })),
+        worker: worker ? { status: worker.status, process_id: worker.process_id, owner_pid: worker.owner_pid, snapshot: worker.snapshot_json ? JSON.parse(worker.snapshot_json) : null, error: worker.error_json ? JSON.parse(worker.error_json) : null, updated_at: worker.updated_at } : null,
+        resume_operation: resume ? { operation_id: resume.operation_id, controller_id: resume.controller_id, request_id: resume.request_id, status: resume.status, receipt: resume.receipt_json ? JSON.parse(resume.receipt_json) : null, error: resume.error_json ? JSON.parse(resume.error_json) : null, updated_at: resume.updated_at } : null
+    }, input);
+}
+/** Interrupt retained managed roots independently; a reply does not prove tree settlement. */
+export async function interruptControlledSessions(context, input) {
+    return await reconcileOwnedSessions(context, input, true);
+}
+export async function observeControlledSessions(context, input) {
+    return await reconcileOwnedSessions(context, input, false);
+}
+/** The capturing owner is the sole live controller exempted from settlement.
+ * Its caller retains the verified inventory until immutable publication. */
+export async function observeControllerBoundary(context, input) {
+    return await reconcileOwnedSessions(context, input, false, input);
+}
+async function reconcileOwnedSessions(context, input, interrupt, boundary) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const control = input.controlId ? context.db.get("SELECT * FROM run_controls WHERE project_id = ? AND run_id = ? AND control_id = ?", [project.id, input.runId, input.controlId]) : undefined;
+    const request = control && JSON.parse(control.request_json);
+    const pauseEscalated = control?.action === "pause" && request?.escalate === "interrupt" && Number.isSafeInteger(request.grace_ms) && Date.now() >= Date.parse(control.created_at) + request.grace_ms;
+    if (boundary ? interrupt || control : !control || interrupt && !(control.action === "stop" || pauseEscalated) || control.status !== "requested")
+        throw new AppError("run_control_invalid_state", "Interrupt requires the current stop intent or its explicitly elapsed pause escalation", 1);
+    const observationId = boundary?.operationId ?? control.control_id;
+    const assertCurrent = () => {
+        if (boundary) {
+            boundary.assertCurrent();
+            return;
+        }
+        const guard = recoveryGuard(context, project.id, input.runId);
+        if (guard?.recovery_id !== control.recovery_id || guard.status !== "draining")
+            throw new AppError("run_control_superseded", "Stop intent no longer owns this RUN", 1);
+    };
+    assertCurrent();
+    const databaseVersion = () => JSON.stringify([context.db.get("PRAGMA data_version"), context.db.get("SELECT total_changes() AS changes")]);
+    const initialDatabaseVersion = databaseVersion();
+    const readBindings = () => context.db.all("SELECT project_id, session_id, provider_session_id, harness, parent_session_id, provider_parent_session_id, run_id, status, stop_reason, metadata_json FROM sessions");
+    const foreign = (binding) => binding.project_id !== project.id || Boolean(binding.run_id && binding.run_id !== input.runId);
+    let bindings = readBindings();
+    const underRoot = (binding, root, harness) => {
+        const seen = new Set();
+        let current = binding;
+        while (current && !seen.has(current.session_id)) {
+            if (harness && current.harness !== harness)
+                return false;
+            if (current.provider_session_id === root)
+                return true;
+            seen.add(current.session_id);
+            const parent = current.parent_session_id, nativeParent = current.provider_parent_session_id, currentHarness = current.harness, currentProject = current.project_id;
+            if (nativeParent === root)
+                return true;
+            current = bindings.find(candidate => candidate.project_id === currentProject && candidate.harness === currentHarness && (parent ? candidate.session_id === parent : nativeParent && candidate.provider_session_id === nativeParent));
+        }
+        return false;
+    };
+    const controllers = context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controllers'")
+        ? context.db.all("SELECT controller_id, state_json, manifest_json, process_id, process_lease_token FROM run_controllers WHERE project_id = ? AND run_id = ?", [project.id, input.runId]) : [];
+    const targets = new Map();
+    const unresolved = [];
+    const conflicts = new Set();
+    const directoryAdapters = new Map();
+    const directoryHarnesses = new Map();
+    const resourceHomes = new Set([resourceHome(context)]);
+    const addTarget = (session, executable, harness = null) => {
+        if (session.owner.project_id !== project.id || session.owner.run_id !== input.runId || session.owner.state_dir !== session.state_dir || !path.isAbsolute(session.state_dir))
+            throw new AppError("controller_owner_mismatch", "Stored Session does not belong to the controlled RUN", 1);
+        if (!executable || !path.isAbsolute(executable))
+            throw new AppError("harness_runtime_missing", "Controlled Session has no frozen adapter executable", 1);
+        const key = JSON.stringify([session.state_dir, session.id]);
+        if (conflicts.has(session.state_dir) || directoryAdapters.has(session.state_dir) && directoryAdapters.get(session.state_dir) !== executable || harness && directoryHarnesses.has(session.state_dir) && directoryHarnesses.get(session.state_dir) !== harness) {
+            for (const [targetKey, target] of targets)
+                if (target.session.state_dir === session.state_dir)
+                    targets.delete(targetKey);
+            conflicts.add(session.state_dir);
+            throw new AppError("controller_target_conflict", "Stored Session has conflicting adapter identities", 1);
+        }
+        directoryAdapters.set(session.state_dir, executable);
+        if (harness)
+            directoryHarnesses.set(session.state_dir, harness);
+        if (session.owner.resource_home && path.isAbsolute(session.owner.resource_home))
+            resourceHomes.add(session.owner.resource_home);
+        targets.set(key, { session, executable, harness: harness ?? directoryHarnesses.get(session.state_dir) ?? null });
+    };
+    for (const row of controllers) {
+        let state, manifest;
+        try {
+            state = JSON.parse(row.state_json);
+            manifest = JSON.parse(row.manifest_json);
+            if (!Array.isArray(state?.sessions) || !manifest?.adapters || typeof manifest.adapters !== "object")
+                throw new Error("Invalid retained inventory");
+            if (manifest.resource_home !== undefined) {
+                if (!path.isAbsolute(manifest.resource_home))
+                    throw new Error("Invalid controller resource home");
+                resourceHomes.add(manifest.resource_home);
+            }
+        }
+        catch {
+            unresolved.push({ controller_id: row.controller_id, status: "pending", reason: "controller_inventory_invalid" });
+            continue;
+        }
+        for (const session of state.sessions) {
+            try {
+                const executable = manifest.adapters[runtimeHarness(session.profile)]?.executable;
+                if (!session.id) {
+                    const create = context.db.get("SELECT operation_id FROM run_controller_operations WHERE controller_id = ? AND json_extract(input_json, '$.state_dir') = ? AND json_extract(input_json, '$.args[0]') = 'session' AND json_extract(input_json, '$.args[1]') = 'create' ORDER BY created_at DESC LIMIT 1", [row.controller_id, session.state_dir]);
+                    if (create)
+                        session.create_operation_id = create.operation_id;
+                }
+                addTarget(session, executable, runtimeHarness(session.profile));
+            }
+            catch (error) {
+                unresolved.push({ controller_id: row.controller_id, session_id: typeof session?.id === "string" ? session.id : null, status: "pending", reason: error instanceof AppError ? error.code : "controller_inventory_invalid" });
+            }
+        }
+    }
+    const launches = context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'work_launches'")
+        ? context.db.all("SELECT l.* FROM work_launches l JOIN works w ON w.work_id = l.work_id WHERE w.project_id = ? AND w.run_id = ?", [project.id, input.runId]) : [];
+    for (const launch of launches) {
+        try {
+            const profile = JSON.parse(launch.profile_json);
+            const binding = profile.runtime_adapter;
+            if (!binding)
+                throw new AppError("harness_runtime_missing", "External launch has no frozen adapter binding", 1);
+            if (binding.owner.work_id !== launch.work_id || binding.owner.operation_id !== launch.operation_id)
+                throw new AppError("controller_owner_mismatch", "External launch owner does not match its retained operation", 1);
+            addTarget({ id: launch.provider_session_id ?? "", state_dir: launch.state_dir, create_operation_id: `${launch.operation_id}:session.create`, owner: binding.owner }, binding.executable, runtimeHarness(profile.worker));
+        }
+        catch (error) {
+            unresolved.push({ work_id: launch.work_id, operation_id: launch.operation_id, status: "pending", reason: error instanceof AppError ? error.code : "external_inventory_invalid" });
+        }
+    }
+    const merges = context.db.all("SELECT merge_request_id, executor_work_id, dispatch_owner, dispatch_lease_token, adapter_receipt_json FROM merge_requests WHERE project_id = ? AND run_id = ? AND (dispatch_owner IS NOT NULL OR adapter_receipt_json IS NOT NULL)", [project.id, input.runId]);
+    for (const merge of merges) {
+        try {
+            if (!merge.adapter_receipt_json)
+                throw new AppError("merge_inventory_missing", "Claimed MERGE has no retained launch receipt", 1);
+            const receipt = JSON.parse(merge.adapter_receipt_json);
+            if (receipt.controller_id) {
+                const controller = controllers.find(row => row.controller_id === receipt.controller_id && row.controller_id === merge.dispatch_owner);
+                const state = controller && JSON.parse(controller.state_json);
+                if (!state || !state.sessions.some(session => session.id === receipt.session_id && session.state_dir === receipt.state_dir))
+                    throw new AppError("controller_owner_mismatch", "MERGE receipt has no matching managed Session", 1);
+                // The controller inventory already validates and controls this physical root.
+                continue;
+            }
+            if (!receipt.owner)
+                throw new AppError("harness_runtime_missing", "MERGE launch has no frozen owner binding", 1);
+            if (receipt.owner.role !== "merge" || receipt.owner.work_id !== merge.executor_work_id || !merge.dispatch_lease_token || receipt.owner.operation_id !== `${merge.merge_request_id}:${merge.dispatch_lease_token}`)
+                throw new AppError("controller_owner_mismatch", "MERGE owner does not match its retained dispatch", 1);
+            addTarget({ id: receipt.session_id ?? "", state_dir: receipt.state_dir, create_operation_id: `${receipt.owner.operation_id}:session.create`, owner: receipt.owner }, receipt.executable, runtimeHarness(receipt.profile));
+        }
+        catch (error) {
+            unresolved.push({ merge_request_id: merge.merge_request_id, status: "pending", reason: error instanceof AppError ? error.code : "merge_inventory_invalid" });
+        }
+    }
+    const processTargets = [];
+    const registeredProcesses = [];
+    const daemonInventories = new Map();
+    const unsafeDaemons = new Set();
+    for (const home of resourceHomes) {
+        let processes;
+        try {
+            const all = managedProcessStatus({ ...context, env: { ...context.env, DD_FLOW_RESOURCE_HOME: home } });
+            const homeMatches = (record) => { const ownHome = managedProcessRuntimeHome(record, context); return ownHome === null || ownHome === context.ddFlowHome; };
+            for (const record of all.filter(record => record.project_id !== project.id || record.run_id !== input.runId || !homeMatches(record))) {
+                try {
+                    const directory = JSON.parse(record.metadata_json).state_dir;
+                    if (typeof directory === "string")
+                        unsafeDaemons.add(canonicalPath(directory, false));
+                }
+                catch { /* No directory attribution is available. */ }
+            }
+            processes = all.filter(record => record.project_id === project.id && record.run_id === input.runId && homeMatches(record));
+        }
+        catch {
+            unresolved.push({ resource_home: home, status: "pending", reason: "resource_inventory_unavailable" });
+            continue;
+        }
+        for (const record of processes) {
+            registeredProcesses.push({ home, record });
+            if (managedProcessRuntimeHome(record, context) !== context.ddFlowHome) {
+                unresolved.push({ process_id: record.id, status: "pending", reason: "managed_process_runtime_scope_unknown" });
+                continue;
+            }
+            if (["run-controller", "run-control"].includes(record.kind))
+                continue;
+            try {
+                const metadata = JSON.parse(record.metadata_json);
+                if (!metadata.state_dir) {
+                    // Retain explicit physical evidence for exited resources too; omitting
+                    // them would make the sealed inventory impossible to account for.
+                    processTargets.push({ home, record });
+                    continue;
+                }
+                if (!path.isAbsolute(metadata.state_dir))
+                    throw new AppError("controller_owner_mismatch", "Registered state directory is not absolute", 1);
+                const executable = metadata.adapter_executable ?? directoryAdapters.get(metadata.state_dir);
+                if (!executable)
+                    throw new AppError("harness_runtime_missing", "Registered runtime has no frozen adapter executable", 1);
+                const state = JSON.parse(fs.readFileSync(path.join(metadata.state_dir, "daemon.json"), "utf8"));
+                const owner = state.config?.runtime_owner;
+                if (!owner || owner.owner_id !== record.owner_id || owner.role !== metadata.role || owner.project_id !== project.id || owner.run_id !== input.runId || owner.state_dir !== metadata.state_dir || (owner.work_id ?? null) !== record.work_id || !owner.operation_id || !record.operation_id?.startsWith(`${owner.operation_id}:`) || owner.dd_flow_home !== context.ddFlowHome || owner.resource_home !== home || owner.adapter_executable !== undefined && owner.adapter_executable !== executable)
+                    throw new AppError("controller_owner_mismatch", "Retained daemon owner differs from its registered runtime", 1);
+                if (!Array.isArray(state.sessions))
+                    throw new AppError("daemon_inventory_invalid", "Retained daemon has no Session inventory", 1);
+                const inventory = daemonInventories.get(metadata.state_dir);
+                if (inventory)
+                    inventory.records.push(record);
+                else
+                    daemonInventories.set(metadata.state_dir, { state, records: [record] });
+                // All bindings are checked; the target map deduplicates shared-daemon Sessions.
+                for (const item of state.sessions) {
+                    const id = typeof item === "string" && item.trim() ? item : adapterSessionId(item);
+                    if (!id)
+                        throw new AppError("daemon_inventory_invalid", "Retained daemon Session identity is invalid", 1);
+                    const alias = typeof state.schema_id === "string" ? /^dd-([a-z]+)\/daemon-state@/.exec(state.schema_id)?.[1] : null;
+                    addTarget({ id, state_dir: metadata.state_dir, owner }, executable, alias ? harnessKey(alias) : null);
+                }
+            }
+            catch (error) {
+                try {
+                    const directory = JSON.parse(record.metadata_json).state_dir;
+                    if (typeof directory === "string")
+                        unsafeDaemons.add(canonicalPath(directory, false));
+                }
+                catch { /* The invalid record remains unresolved below. */ }
+                unresolved.push({ process_id: record.id, status: "pending", reason: error instanceof AppError ? error.code : "daemon_inventory_unavailable" });
+            }
+        }
+    }
+    const closedDaemons = new Map();
+    const nativeVersions = new Map();
+    for (const [directory, { state, records }] of daemonInventories) {
+        if (!interrupt) {
+            try {
+                const nativeOperations = retainedDaemonOperations(directory);
+                nativeVersions.set(directory, nativeInventoryVersion(directory, nativeOperations));
+                for (const operation of nativeOperations)
+                    if (!["completed", "failed", "interrupted"].includes(String(operation.state)))
+                        unresolved.push({ state_dir: directory, operation_id: operation.operation_id, status: "pending", reason: "native_operation_unsettled" });
+                if (state.shutdown_state !== "clean" && !records.some(record => record.kind.endsWith("-daemon") && record.id === state.resource_process?.id && record.pid === state.pid && record.pid_started_at && record.lease_token === state.resource_process.lease_token && JSON.parse(record.metadata_json).dispatch_barrier === "run-generation@1"))
+                    unresolved.push({ state_dir: directory, status: "pending", reason: "native_dispatch_barrier_unverified" });
+            }
+            catch {
+                unresolved.push({ state_dir: directory, status: "pending", reason: "daemon_operation_inventory_invalid" });
+            }
+        }
+        if (state.shutdown_state !== "clean") {
+            if (state.shutdown_state === "unclean")
+                unresolved.push({ state_dir: directory, status: "pending", reason: "native_shutdown_unclean" });
+            if (!state.sessions.length)
+                unresolved.push({ state_dir: directory, status: "pending", reason: "daemon_sessions_unknown" });
+            continue;
+        }
+        try {
+            const daemonId = state.daemon_id ?? state.config?.daemonId;
+            if (!daemonId || state.active_tree === true || state.active_operation || !records.some(record => record.kind.endsWith("-daemon") && record.id === state.resource_process?.id && record.pid === state.pid && record.lease_token === state.resource_process.lease_token))
+                throw new AppError("shutdown_identity_unknown", "Closed daemon has no exact retained physical owner", 1);
+            if (records.some(record => !record.pid || !record.pid_started_at || processTreeIsAlive(record)))
+                throw new AppError("shutdown_process_unsettled", "Closed daemon still has an unconfirmed or live owned process", 1);
+            const receipts = retainedDaemonOperations(directory);
+            // A whole-RUN stop is also the recovery fence for a create whose reply
+            // was lost after native allocation. Keep that one outstanding operation
+            // observable until terminalization below; unrelated unfinished work is
+            // still a shutdown proof failure.
+            const unfinished = receipts.filter(receipt => !["completed", "failed", "interrupted"].includes(String(receipt.state)));
+            if (unfinished.some(receipt => receipt.daemon_id !== daemonId || String(receipt.operation) !== "session.create" || receipt.session_id !== null))
+                throw new AppError("shutdown_operation_unsettled", "Closed daemon retains an unfinished non-create operation", 1);
+            const stopped = receipts.find(receipt => receipt.daemon_id === daemonId && receipt.operation === "daemon.stop" && receipt.state === "completed" && receipt.result?.stopped === true && receipt.result?.clean === true);
+            if (!stopped)
+                throw new AppError("shutdown_receipt_required", "Closed daemon has no clean native shutdown receipt for its current identity", 1);
+            closedDaemons.set(directory, { source: "retained_clean_shutdown", daemon_id: daemonId, operation_id: stopped.operation_id, session_ids: state.sessions.map(item => typeof item === "string" ? item : adapterSessionId(item)), stopped: true, settled: true, processes: records.map(record => ({ process_id: record.id, pid: record.pid, pid_started_at: record.pid_started_at })), result: stopped.result });
+        }
+        catch (error) {
+            unresolved.push({ state_dir: directory, status: "pending", reason: error instanceof AppError ? error.code : "shutdown_receipt_invalid" });
+        }
+    }
+    for (const [key, target] of targets) {
+        if (target.session.id && bindings.some(binding => foreign(binding) && underRoot(binding, target.session.id, target.harness))) {
+            targets.delete(key);
+            unresolved.push({ session_id: target.session.id, state_dir: target.session.state_dir, status: "pending", reason: "session_scope_conflict" });
+        }
+    }
+    if (!interrupt)
+        for (const controller of controllers) {
+            const matches = registeredProcesses.filter(item => item.record.id === controller.process_id && item.record.kind === "run-controller" && item.record.owner_id === controller.controller_id && item.record.lease_token === controller.process_lease_token);
+            const record = matches.length === 1 ? matches[0].record : null;
+            if (boundary?.controllerId === controller.controller_id && record?.pid === process.pid && record.pid_started_at && processIsAlive(record))
+                continue;
+            if (!record?.pid || !record.pid_started_at || processTreeIsAlive(record))
+                unresolved.push({ controller_id: controller.controller_id, process_id: controller.process_id, status: "pending", reason: record?.pid && record.pid_started_at ? "controller_process_running" : "controller_process_identity_unknown" });
+            else
+                unresolved.push({ controller_id: controller.controller_id, process_id: record.id, status: "completed", receipt: { source: "controller_exited", resource_home: matches[0].home, pid: record.pid, pid_started_at: record.pid_started_at, registration_sha256: crypto.createHash("sha256").update(JSON.stringify([matches[0].home, record.id, record.owner_id, record.lease_token, record.pid, record.pid_started_at])).digest("hex") } });
+        }
+    const controllerOperations = !interrupt && controllers.length
+        ? context.db.all("SELECT o.operation_id, o.controller_id, o.input_json, o.status 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.status IN ('dispatching','outcome_unknown')", [project.id, input.runId]) : [];
+    const operationNodes = Promise.all(controllerOperations.map(async (operation) => {
+        try {
+            const saved = JSON.parse(operation.input_json);
+            const args = saved.args;
+            if (!Array.isArray(args) || args.some(value => typeof value !== "string") || !saved.state_dir || !saved.executable || saved.owner !== operation.controller_id || conflicts.has(saved.state_dir) || directoryAdapters.get(saved.state_dir) !== saved.executable)
+                throw new AppError("controller_operation_binding_unknown", "Unfinished controller operation has no matching frozen runtime binding", 1);
+            const method = `${args[0]}.${args[1]}`;
+            if (!["session.create", "session.prompt", "session.start", "session.fork", "session.cancel", "session.resume", "daemon.start", "daemon.stop"].includes(method))
+                throw new AppError("controller_operation_receipt_required", "Unfinished controller operation needs its original receipt", 1);
+            const target = args.includes("--session-id") ? args[args.indexOf("--session-id") + 1] : null;
+            if (!args.includes("--state-dir") || args[args.indexOf("--state-dir") + 1] !== saved.state_dir || args.includes("--session-id") && (!target || !targets.has(JSON.stringify([saved.state_dir, target]))))
+                throw new AppError("controller_operation_binding_unknown", "Unfinished operation arguments differ from the retained Session", 1);
+            const retained = JSON.parse(controllers.find(row => row.controller_id === operation.controller_id).state_json).sessions.find(session => session.state_dir === saved.state_dir && (!target || session.id === target));
+            if (!retained)
+                throw new AppError("controller_operation_binding_unknown", "Unfinished operation has no retained controller Session", 1);
+            // A create without a native daemon state file has no provider-side
+            // receipt to inspect. Do not invoke the adapter again merely to discover
+            // that fact; retain the original outcome-unknown operation for the
+            // explicit controller fence/recovery path.
+            if (method === "session.create" && !fs.existsSync(path.join(saved.state_dir, "daemon.json")))
+                return { operation_id: operation.operation_id, status: "pending", reason: "create_observation_unavailable" };
+            const harness = runtimeHarness(retained.profile);
+            const env = { ...context.env, DD_FLOW_HOME: context.ddFlowHome };
+            delete env.DD_FLOW_CONTROLLER_TOKEN;
+            delete env.DD_FLOW_CONTROL_TOKEN;
+            assertCurrent();
+            const receipt = await runHarnessAdapter({ executable: saved.executable, args: ["daemon", "operation", "--operation-id", operation.operation_id, "--state-dir", saved.state_dir, "--json"], env, operationId: `${observationId}:observe:${operation.operation_id}`, timeoutMs: 30_000 });
+            if (receipt.operation_id !== operation.operation_id || receipt.operation !== method || target && receipt.session_id !== target)
+                throw new AppError("controller_operation_mismatch", "Operation observation belongs to another retained dispatch", 1);
+            if (!["completed", "failed", "interrupted"].includes(String(receipt.state)))
+                return { operation_id: operation.operation_id, status: "pending", reason: "controller_operation_unsettled", receipt };
+            if (receipt.state === "completed" && (!receipt.result || typeof receipt.result !== "object" || Array.isArray(receipt.result) || target && method !== "daemon.start" && adapterSessionId(receipt.result) !== target || method === "session.create" && !adapterSessionId(receipt.result)))
+                throw new AppError("controller_operation_mismatch", "Terminal operation has no valid result for its retained Session", 1);
+            if (receipt.state === "completed" && method === "daemon.start" && (typeof receipt.started_daemon_id !== "string" || !receipt.started_daemon_id || receipt.result.daemon_id !== receipt.started_daemon_id))
+                throw new AppError("controller_operation_mismatch", "Startup receipt has no confirmed daemon identity", 1);
+            if (receipt.state === "completed" && receipt.result.harness !== undefined && receipt.result.harness !== harness)
+                throw new AppError("controller_operation_mismatch", "Terminal operation returned another harness identity", 1);
+            if (receipt.state === "failed" && (!receipt.error || typeof receipt.error !== "object" || Array.isArray(receipt.error)))
+                throw new AppError("controller_operation_mismatch", "Failed operation has no durable error receipt", 1);
+            assertCurrent();
+            context.db.run("UPDATE run_controller_operations SET status = ?, receipt_json = ?, error_json = ?, updated_at = ? WHERE operation_id = ? AND status IN ('dispatching','outcome_unknown')", [receipt.state, JSON.stringify(receipt.result ?? receipt), receipt.state === "failed" ? JSON.stringify(receipt.error) : null, context.now(), operation.operation_id]);
+            return { operation_id: operation.operation_id, status: "completed", receipt };
+        }
+        catch (error) {
+            return { operation_id: operation.operation_id, status: "pending", reason: error instanceof AppError ? error.code : "controller_operation_observation_failed" };
+        }
+    }));
+    for (const check of context.db.all("SELECT id FROM check_receipts WHERE project_id = ? AND run_id = ? AND status = 'running'", [project.id, input.runId])) {
+        let reason = "check_settlement_required";
+        if (!interrupt) {
+            const matches = registeredProcesses.filter(item => item.record.check_id === check.id);
+            // A missing/ambiguous registration is not proof that a writer exited.
+            // Reuse normal check reconciliation only after exact physical evidence.
+            if (matches.length === 1 && matches[0].record.pid && matches[0].record.pid_started_at && !processTreeIsAlive(matches[0].record)) {
+                try {
+                    assertCurrent();
+                    const run = context.db.get("SELECT workspace_root, run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
+                    reconcileUnfinishedChecks({ ...context, env: { ...context.env, DD_FLOW_RESOURCE_HOME: matches[0].home } }, { projectId: project.id, runId: input.runId, workspaceRoot: run.workspace_root, runHome: run.run_root, receiptId: check.id });
+                    if (context.db.get("SELECT status FROM check_receipts WHERE project_id = ? AND run_id = ? AND id = ?", [project.id, input.runId, check.id])?.status !== "running")
+                        continue;
+                }
+                catch (error) {
+                    reason = error instanceof AppError ? error.code : "check_reconciliation_failed";
+                }
+            }
+        }
+        unresolved.push({ check_id: check.id, status: "pending", reason });
+    }
+    const uncreatedDirectories = new Map();
+    const sessionNodes = Promise.all([...targets.values()].map(async ({ session, executable, harness }) => {
+        const env = { ...context.env, DD_FLOW_HOME: context.ddFlowHome };
+        delete env.DD_FLOW_CONTROLLER_TOKEN;
+        delete env.DD_FLOW_CONTROL_TOKEN;
+        // An explicit pre-registration rejection proves there is no Session to
+        // cancel. A missing id or an arbitrary startup failure does not.
+        if (!session.id && !session.create_operation_id && !daemonInventories.has(session.state_dir) && !unsafeDaemons.has(canonicalPath(session.state_dir, false)) && !fs.existsSync(path.join(session.state_dir, "daemon.json"))) {
+            const operations = context.db.all("SELECT o.operation_id, 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 json_extract(o.input_json, '$.state_dir') = ?", [project.id, input.runId, session.state_dir]);
+            if (operations.length === 1)
+                try {
+                    const operation = operations[0];
+                    const saved = JSON.parse(operation.input_json);
+                    const journal = retainedDaemonOperations(session.state_dir);
+                    const receipt = journal.length === 1 ? journal[0] : null;
+                    const error = receipt?.error;
+                    if (saved.executable === executable && saved.owner === session.owner.owner_id && saved.args?.[0] === "daemon" && saved.args?.[1] === "start" && receipt?.operation_id === operation.operation_id && receipt.operation === "daemon.start" && receipt.predecessor_daemon_id === null && receipt.state === "failed" && error?.details?.startup_resources === "not_created" && !registeredProcesses.some(({ record }) => JSON.parse(record.metadata_json).state_dir === session.state_dir)) {
+                        uncreatedDirectories.set(session.state_dir, JSON.stringify(journal));
+                        return { state_dir: session.state_dir, status: "completed", receipt: { source: "startup_resources_not_created", operation_id: operation.operation_id, error } };
+                    }
+                }
+                catch { /* Incomplete evidence retains the normal unknown outcome. */ }
+        }
+        if (!session.id && session.create_operation_id) {
+            try {
+                assertCurrent();
+                const create = await runHarnessAdapter({ executable, args: ["daemon", "operation", "--operation-id", session.create_operation_id, "--state-dir", session.state_dir, "--json"], env, operationId: `${observationId}:observe:${session.create_operation_id}`, timeoutMs: 30_000 });
+                if (create.operation_id !== session.create_operation_id || create.operation !== "session.create")
+                    throw new AppError("controller_operation_mismatch", "Create observation belongs to another operation", 1);
+                if (create.state === "completed")
+                    session.id = adapterSessionId(create.result) ?? "";
+            }
+            catch (error) {
+                return { state_dir: session.state_dir, status: "pending", reason: error instanceof AppError ? error.code : "create_observation_failed" };
+            }
+        }
+        const closed = closedDaemons.get(session.state_dir);
+        if (!session.id)
+            return closed && !session.create_operation_id && Array.isArray(closed.session_ids) && closed.session_ids.length === 0
+                ? { state_dir: session.state_dir, status: "completed", receipt: closed }
+                : { state_dir: session.state_dir, create_operation_id: session.create_operation_id ?? null, status: "pending", reason: "provider_identity_unknown" };
+        bindings = readBindings();
+        if (bindings.some(binding => foreign(binding) && underRoot(binding, session.id, harness)))
+            return { session_id: session.id, state_dir: session.state_dir, status: "pending", reason: "session_scope_conflict" };
+        if (closed)
+            return Array.isArray(closed.session_ids) && closed.session_ids.includes(session.id)
+                ? { session_id: session.id, state_dir: session.state_dir, harness, status: "completed", receipt: closed }
+                : { session_id: session.id, state_dir: session.state_dir, harness, status: "pending", reason: "shutdown_session_unproven" };
+        if (!interrupt) {
+            try {
+                const receipt = await inspectControlledNativeSession({ executable, sessionId: session.id, stateDir: session.state_dir, harness, env, operationId: `${observationId}:inspect:${crypto.randomUUID()}`, assertCurrent });
+                return { session_id: session.id, state_dir: session.state_dir, harness: harness ?? (typeof receipt.harness === "string" ? receipt.harness : null), status: receipt.settled === true ? "completed" : "pending", receipt };
+            }
+            catch (error) {
+                return { session_id: session.id, state_dir: session.state_dir, status: "pending", reason: error instanceof AppError ? error.code : "session_observation_failed" };
+            }
+        }
+        const key = JSON.stringify([session.state_dir, session.id]);
+        const operationId = `${observationId}:cancel:${crypto.createHash("sha256").update(key).digest("hex")}`;
+        const now = context.now();
+        assertCurrent();
+        const inserted = context.db.run("INSERT OR IGNORE INTO run_control_operations (operation_id, control_id, target_json, status, created_at, updated_at) VALUES (?, ?, ?, 'dispatching', ?, ?)", [operationId, observationId, JSON.stringify({ session_id: session.id, state_dir: session.state_dir, executable }), now, now]);
+        const prior = context.db.get("SELECT status, receipt_json FROM run_control_operations WHERE operation_id = ?", [operationId]);
+        let cancellation;
+        let cancellationError;
+        try {
+            if (!inserted.changes && prior.status === "completed") {
+                const saved = JSON.parse(prior.receipt_json);
+                assertNativeCancellationReceipt(saved, session.id);
+                cancellation = saved;
+            }
+            else {
+                const { status, receipt } = await cancelControlledNativeSession({ executable, sessionId: session.id, stateDir: session.state_dir, env, operationId, observe: !inserted.changes, assertCurrent });
+                const terminalFailure = status === "failed" ? receipt.error && typeof receipt.error === "object" && !Array.isArray(receipt.error) ? receipt.error : { code: "native_cancel_failed" } : null;
+                context.db.run("UPDATE run_control_operations SET status = ?, receipt_json = ?, error_json = ?, updated_at = ? WHERE operation_id = ?", [status, JSON.stringify(receipt), terminalFailure ? JSON.stringify(terminalFailure) : null, context.now(), operationId]);
+                cancellation = receipt;
+                if (terminalFailure)
+                    cancellationError = { code: typeof terminalFailure.code === "string" ? terminalFailure.code : "native_cancel_failed", receipt };
+            }
+        }
+        catch (error) {
+            cancellationError = { code: error instanceof AppError ? error.code : "control_observation_failed", message: String(error) };
+            context.db.run("UPDATE run_control_operations SET status = 'outcome_unknown', error_json = ?, updated_at = ? WHERE operation_id = ? AND status != 'completed'", [JSON.stringify(cancellationError), context.now(), operationId]);
+            if (cancellationError.code === "controller_operation_mismatch")
+                return { operation_id: operationId, session_id: session.id, status: "outcome_unknown", error: cancellationError };
+        }
+        try {
+            const observed = await inspectControlledNativeSession({ executable, sessionId: session.id, stateDir: session.state_dir, harness, env, operationId: `${observationId}:inspect:${crypto.randomUUID()}`, assertCurrent });
+            return { operation_id: operationId, session_id: session.id, status: observed.settled === true ? "completed" : "pending", receipt: observed, cancellation, reused: !inserted.changes, ...(cancellationError ? { cancellation_error: cancellationError } : {}) };
+        }
+        catch (error) {
+            return { operation_id: operationId, session_id: session.id, status: "pending", cancellation, cancellation_error: cancellationError, error: { code: error instanceof AppError ? error.code : "control_observation_failed", message: String(error) } };
+        }
+    }));
+    const processResults = Promise.all(processTargets.map(async ({ home, record }) => {
+        if (managedLeaseReleased(record))
+            return { process_id: record.id, kind: record.kind, status: "completed", receipt: { source: "managed_lease_released", ...managedProcessBinding(record, home), finished_at: record.finished_at } };
+        if (record.kind === "workspace-gate")
+            return { process_id: record.id, kind: record.kind, status: "pending", reason: "managed_lease_unsettled" };
+        if (!record.pid || !record.pid_started_at)
+            return { process_id: record.id, kind: record.kind, status: "pending", reason: "managed_process_identity_unknown" };
+        if (!interrupt && processTreeIsAlive(record))
+            return { process_id: record.id, kind: record.kind, status: "pending", reason: "managed_process_running" };
+        if (boundary)
+            return { process_id: record.id, kind: record.kind, status: "completed", receipt: { source: "owned_process_exited", pid: record.pid, pid_started_at: record.pid_started_at } };
+        const resourceContext = { ...context, env: { ...context.env, DD_FLOW_RESOURCE_HOME: home } };
+        const operationId = `${observationId}:${interrupt ? "interrupt" : "settle"}-process:${crypto.createHash("sha256").update(JSON.stringify([home, record.id, record.pid, record.pid_started_at, record.lease_token])).digest("hex")}`;
+        assertCurrent();
+        if (!interrupt) {
+            const retained = context.db.get("SELECT status, receipt_json FROM run_control_operations WHERE operation_id = ?", [operationId]);
+            const receipt = retained?.receipt_json ? JSON.parse(retained.receipt_json) : null;
+            // The physical exit was checked above. Do not invalidate the inventory
+            // snapshot by rewriting our own already-completed observation each pass.
+            if (retained?.status === "completed" && receipt?.process_id === record.id && receipt.settled === true)
+                return { operation_id: operationId, process_id: record.id, status: "completed", receipt, reused: true };
+        }
+        const inserted = context.db.run("INSERT OR IGNORE INTO run_control_operations (operation_id, control_id, target_json, status, created_at, updated_at) VALUES (?, ?, ?, 'dispatching', ?, ?)", [operationId, observationId, JSON.stringify({ resource_home: home, process_id: record.id, pid: record.pid, pid_started_at: record.pid_started_at }), context.now(), context.now()]);
+        try {
+            assertCurrent();
+            const current = managedProcessStatus(resourceContext).find(candidate => candidate.id === record.id);
+            if (!current || current.lease_token !== record.lease_token || current.pid !== record.pid || current.pid_started_at !== record.pid_started_at)
+                throw new AppError("process_lease_lost", "Controlled process identity changed before settlement", 1);
+            // The previous owner may have persisted intent without sending its signal.
+            // Stop is repeatable for this exact lease/PID/birth; no work is replayed.
+            if (interrupt)
+                await stopManagedProcess(resourceContext, { id: record.id, leaseToken: record.lease_token, force: JSON.parse(control.request_json).force === true, graceMs: 500, reason: `run_control:${observationId}` });
+            else if (processTreeIsAlive(current))
+                throw new AppError("process_tree_not_settled", "This owned process tree is still running", 1);
+            else if (!finishManagedProcess(resourceContext, { id: record.id, leaseToken: record.lease_token, state: current.state === "failed" ? "failed" : "stopped", reason: `run_control:${observationId}` }))
+                throw new AppError("process_lease_lost", "Controlled process ownership changed before settlement", 1);
+            const receipt = { process_id: record.id, settled: true };
+            context.db.run("UPDATE run_control_operations SET status = 'completed', receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify(receipt), context.now(), operationId]);
+            return { operation_id: operationId, process_id: record.id, status: "completed", receipt, reused: !inserted.changes };
+        }
+        catch (error) {
+            const failure = { code: error instanceof AppError ? error.code : error.code ?? "process_control_failed", message: String(error) };
+            context.db.run("UPDATE run_control_operations SET status = 'outcome_unknown', error_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify(failure), context.now(), operationId]);
+            return { operation_id: operationId, process_id: record.id, status: "pending", reason: failure.code };
+        }
+    }));
+    const [nodes, processNodes, operations] = await Promise.all([sessionNodes, processResults, operationNodes]);
+    // Every whole-RUN stop retires its owned daemon boundary once cancellation
+    // has been admitted. `force` controls escalation inside that lifecycle; it
+    // must not decide whether the lifecycle exists at all.
+    const closeNodes = interrupt && control?.action === "stop" ? await Promise.all([...daemonInventories].map(async ([directory, { state, records }]) => {
+        if (closedDaemons.has(directory)) {
+            const receipt = closedDaemons.get(directory);
+            return { state_dir: directory, status: "completed", operation_id: receipt.operation_id, receipt };
+        }
+        bindings = readBindings();
+        const ids = state.sessions.map(item => typeof item === "string" ? item : adapterSessionId(item));
+        const harness = directoryHarnesses.get(directory) ?? null;
+        if (conflicts.has(directory) || unsafeDaemons.has(canonicalPath(directory, false)) || ids.some(id => !id || bindings.some(binding => foreign(binding) && underRoot(binding, id, harness))))
+            return { state_dir: directory, status: "pending", reason: "daemon_scope_conflict" };
+        const daemonId = state.daemon_id ?? state.config?.daemonId;
+        const leader = records.find(record => record.kind.endsWith("-daemon") && record.id === state.resource_process?.id && record.pid === state.pid && record.pid_started_at && record.lease_token === state.resource_process.lease_token);
+        const executable = directoryAdapters.get(directory) ?? (leader && JSON.parse(leader.metadata_json).adapter_executable);
+        if (!daemonId || !leader || !executable)
+            return { state_dir: directory, status: "pending", reason: "daemon_close_owner_unproven" };
+        let operationId = `${observationId}:close-daemon:${crypto.createHash("sha256").update(JSON.stringify([directory, daemonId])).digest("hex")}`;
+        const nativeOperations = retainedDaemonOperations(directory);
+        const targetList = [...targets.values()];
+        const sessionsSettled = ids.every(id => nodes.some((node, index) => targetList[index]?.session.state_dir === directory && targetList[index]?.session.id === id && node.status === "completed"));
+        // A confirmed failed tree guard admits a new shutdown attempt only after
+        // fresh tree settlement. Unknown outcomes retain their original ID.
+        if (sessionsSettled) {
+            while (nativeOperations.some(operation => operation.operation_id === operationId && operation.daemon_id === daemonId && operation.operation === "daemon.stop"
+                && operation.state === "failed" && operation.error?.code === "tree_not_settled"))
+                operationId += ":finalize";
+        }
+        assertCurrent();
+        const inserted = context.db.run("INSERT OR IGNORE INTO run_control_operations (operation_id, control_id, target_json, status, created_at, updated_at) VALUES (?, ?, ?, 'dispatching', ?, ?)", [operationId, observationId, JSON.stringify({ state_dir: directory, daemon_id: daemonId, executable, cancel_tree: true }), context.now(), context.now()]);
+        const prior = context.db.get("SELECT status, receipt_json FROM run_control_operations WHERE operation_id = ?", [operationId]);
+        try {
+            if (!inserted.changes && prior.status === "completed") {
+                const receipt = JSON.parse(prior.receipt_json);
+                assertDaemonCloseReceipt(receipt);
+                return { operation_id: operationId, state_dir: directory, status: "completed", receipt, reused: true };
+            }
+            if (inserted.changes) {
+                const fresh = JSON.parse(fs.readFileSync(path.join(directory, "daemon.json"), "utf8"));
+                const owned = registeredProcesses.find(item => item.record === leader);
+                const record = managedProcessStatus({ ...context, env: { ...context.env, DD_FLOW_RESOURCE_HOME: owned.home } }).find(item => item.id === leader.id);
+                if (!record || record.lease_token !== leader.lease_token || record.pid !== leader.pid || record.pid_started_at !== leader.pid_started_at || !processIsAlive(record) || (fresh.daemon_id ?? fresh.config?.daemonId) !== daemonId || fresh.resource_process?.id !== leader.id || fresh.resource_process.lease_token !== leader.lease_token || JSON.stringify(fresh.config?.runtime_owner) !== JSON.stringify(state.config?.runtime_owner))
+                    throw new AppError("daemon_close_owner_changed", "Daemon ownership changed before its forced close", 1);
+            }
+            assertCurrent();
+            const env = { ...context.env, DD_FLOW_HOME: context.ddFlowHome };
+            delete env.DD_FLOW_CONTROL_TOKEN;
+            delete env.DD_FLOW_CONTROLLER_TOKEN;
+            const receipt = await runHarnessAdapter({ executable, args: inserted.changes ? ["daemon", "stop", "--cancel-tree", "--state-dir", directory, "--json"] : ["daemon", "operation", "--operation-id", operationId, "--state-dir", directory, "--json"], env, operationId: inserted.changes ? operationId : `${operationId}:observe`, timeoutMs: 30_000 });
+            if (!inserted.changes && (receipt.operation_id !== operationId || receipt.operation !== "daemon.stop" || receipt.daemon_id !== daemonId))
+                throw new AppError("controller_operation_mismatch", "Daemon close observation belongs to another operation or incarnation", 1);
+            if (receipt.state === "failed") {
+                const failure = receipt.error && typeof receipt.error === "object" && !Array.isArray(receipt.error) ? receipt.error : { code: "daemon_close_failed" };
+                context.db.run("UPDATE run_control_operations SET status = 'failed', receipt_json = ?, error_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify(receipt), JSON.stringify(failure), context.now(), operationId]);
+                return { operation_id: operationId, state_dir: directory, status: "pending", reason: typeof failure.code === "string" ? failure.code : "daemon_close_failed", receipt };
+            }
+            const observed = inserted.changes ? receipt : receipt.state === "completed" ? receipt.result : null;
+            if (observed)
+                assertDaemonCloseReceipt(observed);
+            const status = observed ? "completed" : "outcome_unknown";
+            context.db.run("UPDATE run_control_operations SET status = ?, receipt_json = ?, error_json = NULL, updated_at = ? WHERE operation_id = ?", [status, JSON.stringify(observed ?? receipt), context.now(), operationId]);
+            return { operation_id: operationId, state_dir: directory, status, receipt: observed ?? receipt };
+        }
+        catch (error) {
+            const failure = { code: error instanceof AppError ? error.code : "daemon_close_failed", message: String(error) };
+            context.db.run("UPDATE run_control_operations SET status = 'outcome_unknown', error_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify(failure), context.now(), operationId]);
+            return { operation_id: operationId, state_dir: directory, status: "pending", reason: failure.code };
+        }
+    })) : [];
+    // Once the same control owns a clean whole-tree stop, an older productive
+    // request cannot gain a provider reply through this daemon. Seal that fact in
+    // the shared native journal before the next observation pass. This prevents a
+    // closed daemon from becoming a permanent prerequisite for its own recovery.
+    const terminalizedOperations = [];
+    if (interrupt && control?.action === "stop")
+        for (const node of closeNodes) {
+            if (node.status !== "completed")
+                continue;
+            const directory = node.state_dir;
+            const inventory = daemonInventories.get(directory);
+            const daemonId = inventory?.state.daemon_id ?? inventory?.state.config?.daemonId;
+            const executable = directoryAdapters.get(directory);
+            if (!inventory)
+                continue;
+            if (!daemonId || !executable || !node.operation_id) {
+                terminalizedOperations.push({ state_dir: directory, status: "pending", reason: "operation_terminalization_binding_unknown" });
+                continue;
+            }
+            const pending = retainedDaemonOperations(directory).filter(operation => operation.daemon_id === daemonId && ["running", "awaiting_provider"].includes(String(operation.state)) && ["session.create", "session.prompt", "session.start", "session.fork", "session.resume"].includes(String(operation.operation)) && typeof operation.operation_id === "string");
+            terminalizedOperations.push(...await Promise.all(pending.map(async (operation) => {
+                try {
+                    const operationId = operation.operation_id, sessionId = typeof operation.session_id === "string" ? operation.session_id : null;
+                    assertCurrent();
+                    const env = { ...context.env, DD_FLOW_HOME: context.ddFlowHome };
+                    delete env.DD_FLOW_CONTROL_TOKEN;
+                    delete env.DD_FLOW_CONTROLLER_TOKEN;
+                    const interruptArgs = ["daemon", "operation", "interrupt", "--operation-id", operationId, "--control-id", control.control_id, "--stop-operation-id", String(node.operation_id), "--daemon-id", String(daemonId)];
+                    if (sessionId)
+                        interruptArgs.push("--session-id", sessionId);
+                    interruptArgs.push("--state-dir", directory, "--json");
+                    const receipt = await runHarnessAdapter({ executable, args: interruptArgs, env, operationId: `${observationId}:interrupt-operation:${operationId}`, timeoutMs: 30_000 });
+                    if (receipt.operation_id !== operationId || receipt.state !== "interrupted" || receipt.daemon_id !== daemonId || receipt.session_id !== sessionId)
+                        throw new AppError("controller_operation_mismatch", "Interrupted operation receipt belongs to another native request", 1);
+                    return { operation_id: operationId, state_dir: directory, status: "completed", receipt };
+                }
+                catch (error) {
+                    return { operation_id: operation.operation_id, state_dir: directory, status: "pending", reason: error instanceof AppError ? error.code : "operation_terminalization_failed" };
+                }
+            })));
+        }
+    let verifyInventory = assertCurrent;
+    if (!interrupt) {
+        const importVersions = new Map();
+        const historicalImport = (binding) => {
+            if (binding.status !== "stopped" || binding.stop_reason !== "snapshot_restored"
+                || context.db.get("SELECT 1 FROM work_sessions WHERE session_id = ? AND status = 'running' LIMIT 1", [binding.session_id]))
+                return false;
+            try {
+                const marker = JSON.parse(binding.metadata_json).snapshot_import;
+                if (typeof marker?.lineage_file !== "string" || typeof marker.lineage_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(marker.lineage_sha256))
+                    return false;
+                if (!fs.lstatSync(marker.lineage_file).isFile() || path.dirname(fs.realpathSync(marker.lineage_file)) !== path.join(fs.realpathSync(context.ddFlowHome), "snapshot-imports"))
+                    return false;
+                const bytes = fs.readFileSync(marker.lineage_file);
+                if (crypto.createHash("sha256").update(bytes).digest("hex") !== marker.lineage_sha256)
+                    return false;
+                const lineage = JSON.parse(bytes.toString("utf8"));
+                if (lineage.schema_id !== "dd-flow/snapshot-runtime-lineage@1" || lineage.restored_runtime !== context.ddFlowHome || lineage.source_runtime === context.ddFlowHome || lineage.run_id !== input.runId || !Array.isArray(lineage.run_tables?.sessions))
+                    return false;
+                const found = lineage.run_tables.sessions.some((row) => ["project_id", "session_id", "provider_session_id", "harness", "run_id"].every(key => row[key] === binding[key]));
+                if (found)
+                    importVersions.set(marker.lineage_file, marker.lineage_sha256);
+                return found;
+            }
+            catch {
+                return false;
+            }
+        };
+        bindings = readBindings();
+        for (const target of targets.values())
+            if (!daemonInventories.has(target.session.state_dir) && !uncreatedDirectories.has(target.session.state_dir))
+                unresolved.push({ state_dir: target.session.state_dir, status: "pending", reason: "runtime_inventory_unverified" });
+        for (const node of nodes)
+            if ("harness" in node && "session_id" in node && typeof node.session_id === "string" && bindings.some(binding => foreign(binding) && underRoot(binding, node.session_id, node.harness ?? null)))
+                unresolved.push({ session_id: node.session_id, status: "pending", reason: "session_scope_conflict" });
+        const scoped = new Set(bindings.filter(binding => binding.project_id === project.id && binding.run_id === input.runId).map(binding => binding.session_id));
+        for (const link of context.db.all("SELECT ws.id, ws.session_id FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ?", [project.id, input.runId])) {
+            scoped.add(link.session_id);
+            if (!bindings.some(binding => binding.project_id === project.id && binding.session_id === link.session_id))
+                unresolved.push({ work_session_id: link.id, status: "pending", reason: "work_session_binding_unknown" });
+        }
+        for (const binding of bindings.filter(item => item.project_id === project.id && scoped.has(item.session_id))) {
+            // Imported history is not a live native owner. Keep it in `bindings`
+            // above so it can never hide foreign descendants or actual process nodes.
+            if (historicalImport(binding))
+                continue;
+            const covered = nodes.some(node => "harness" in node && node.harness === binding.harness && node.status === "completed" && "session_id" in node && typeof node.session_id === "string" && underRoot(binding, node.session_id, node.harness));
+            if (!covered)
+                unresolved.push({ session_id: binding.provider_session_id, harness: binding.harness, status: "pending", reason: binding.run_id && binding.run_id !== input.runId ? "session_scope_conflict" : "bound_session_settlement_required" });
+        }
+        for (const work of context.db.all("SELECT w.work_id FROM works w WHERE w.project_id = ? AND w.run_id = ? AND w.status = 'running' AND NOT EXISTS (SELECT 1 FROM work_sessions ws WHERE ws.work_id = w.work_id)", [project.id, input.runId]))
+            unresolved.push({ work_id: work.work_id, status: "pending", reason: "running_work_binding_unknown" });
+        const processVersion = (items) => JSON.stringify(items.map(({ home, record }) => [home, record.id, record.kind, record.owner_id, record.project_id, record.run_id, record.work_id, record.check_id, record.operation_id, record.pid, record.pid_started_at, record.lease_token, record.state, record.metadata_json]).sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right))));
+        verifyInventory = () => {
+            assertCurrent();
+            for (const [directory, journal] of uncreatedDirectories)
+                if (fs.existsSync(path.join(directory, "daemon.json")) || JSON.stringify(retainedDaemonOperations(directory)) !== journal)
+                    throw new AppError("owned_inventory_changed", "Rejected startup acquired new runtime evidence", 1);
+            const currentProcesses = [...resourceHomes].flatMap(home => managedProcessStatus({ ...context, env: { ...context.env, DD_FLOW_RESOURCE_HOME: home } }).filter(record => record.project_id === project.id && record.run_id === input.runId && [null, context.ddFlowHome].includes(managedProcessRuntimeHome(record, context))).map(record => ({ home, record })));
+            if (initialDatabaseVersion !== databaseVersion() || processVersion(registeredProcesses) !== processVersion(currentProcesses) || [...nativeVersions].some(([directory, version]) => version !== nativeInventoryVersion(directory)) || [...importVersions].some(([file, version]) => crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") !== version))
+                throw new AppError("owned_inventory_changed", "Owned writers changed after their settlement observation", 1);
+        };
+        try {
+            verifyInventory();
+        }
+        catch (error) {
+            unresolved.push({ status: "pending", reason: error instanceof AppError && error.code === "owned_inventory_changed" ? error.code : "owned_inventory_recheck_failed" });
+        }
+    }
+    assertCurrent();
+    // A clean daemon close plus a sealed interruption terminalizes an in-flight
+    // create even though its controller Session row never received an id. Do
+    // not leave the pre-terminalization `provider_identity_unknown` shadow node
+    // in the final result.
+    const terminalized = new Set(terminalizedOperations.filter(node => node.status === "completed").map(node => node.operation_id));
+    const reconciledNodes = nodes.map(node => {
+        const createId = "create_operation_id" in node && typeof node.create_operation_id === "string" ? node.create_operation_id : null;
+        return createId && terminalized.has(createId) ? { ...node, status: "completed", reason: undefined, receipt: terminalizedOperations.find(item => item.operation_id === createId)?.receipt } : node;
+    });
+    const allNodes = [...reconciledNodes, ...processNodes, ...operations, ...closeNodes, ...terminalizedOperations, ...unresolved];
+    const settled = !interrupt && allNodes.every(node => node.status === "completed");
+    if (settled)
+        boundary?.retainVerification(verifyInventory);
+    const processBindings = settled ? registeredProcesses.filter(({ record }) => record.kind !== "run-control" && !(boundary && record.kind === "run-controller" && record.owner_id === boundary.controllerId)).map(({ home, record }) => managedProcessBinding(record, home)) : [];
+    const pendingReasons = settled ? [] : [...new Set([...(interrupt ? ["settlement_observation_required"] : []), ...allNodes.filter(node => node.status !== "completed").map(node => "reason" in node && typeof node.reason === "string" ? node.reason : "node_settlement_required")])];
+    return { ok: true, ...(boundary ? { operation_id: observationId } : { control_id: observationId }), status: "requested", settled, nodes: allNodes, process_bindings: processBindings, resource_homes: [...resourceHomes].sort(), pending_reasons: pendingReasons };
+}
+export function nativeInventoryVersion(directory, operations = retainedDaemonOperations(directory)) {
+    const state = JSON.parse(fs.readFileSync(path.join(directory, "daemon.json"), "utf8"));
+    const keys = ["schema_id", "daemon_id", "config", "pid", "provider_pid", "shutdown_state", "active_operation", "active_tree", "sessions", "descendants", "root_session_id", "resource_process", "provider_process", "owned_processes"];
+    return crypto.createHash("sha256").update(JSON.stringify([Object.fromEntries(keys.map(key => [key, state[key]])), operations])).digest("hex");
+}
+/** Read the bundled runtime's durable operation journal, including lost replies. */
+export function retainedDaemonOperations(directory) {
+    const root = path.join(directory, "operations");
+    if (!fs.existsSync(root))
+        return [];
+    return fs.readdirSync(root, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name)).map(entry => {
+        if (!entry.isDirectory() || !/^[a-f0-9]{64}$/.test(entry.name))
+            throw new AppError("daemon_operation_inventory_invalid", "Native operation journal has an invalid entry", 1);
+        const folder = path.join(root, entry.name);
+        const requested = JSON.parse(fs.readFileSync(path.join(folder, "requested.json"), "utf8"));
+        if (requested.schema_id !== "dd-flow/daemon-operation@1" || typeof requested.operation_id !== "string" || crypto.createHash("sha256").update(requested.operation_id).digest("hex") !== entry.name || typeof requested.operation !== "string")
+            throw new AppError("daemon_operation_inventory_invalid", "Native operation request has a conflicting identity", 1);
+        const outcomePath = ["result.json", "interrupted.json", "observation-lost.json"].map(file => path.join(folder, file)).find(file => fs.existsSync(file));
+        const outcome = outcomePath ? JSON.parse(fs.readFileSync(outcomePath, "utf8")) : { state: "running" };
+        if (!outcome || typeof outcome !== "object" || Array.isArray(outcome) || !["completed", "failed", "interrupted", "running", "awaiting_provider"].includes(String(outcome.state)) || ["operation_id", "operation", "daemon_id", "session_id"].some(key => key in outcome && outcome[key] !== requested[key]))
+            throw new AppError("daemon_operation_inventory_invalid", "Native operation result has an invalid identity or state", 1);
+        if (outcome.state === "completed" && (!outcome.result || typeof outcome.result !== "object" || Array.isArray(outcome.result)) || ["failed", "interrupted"].includes(String(outcome.state)) && (!outcome.error || typeof outcome.error !== "object" || Array.isArray(outcome.error)))
+            throw new AppError("daemon_operation_inventory_invalid", "Native operation omits its terminal evidence", 1);
+        return { ...requested, ...outcome };
+    });
+}
+function assertDaemonCloseReceipt(value) {
+    if (!value || typeof value !== "object" || value.stopped !== true)
+        throw new AppError("daemon_close_receipt_invalid", "Daemon close has no stopped acknowledgement", 1);
+}
+export function controlLifecycleReply(context, input, result) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const control = runControlDirective(context, project.id, input.runId);
+    if (!control || !result || typeof result !== "object" || Array.isArray(result))
+        return result;
+    return { ...result, control, next: null, next_command: null, next_action: "operator_control", flow_guidance: null, newly_ready: [] };
+}
+/** A lifecycle reply can carry the trusted stop request; it is not a physical ACK. */
+export function runControlDirective(context, projectId, runId) {
+    if (!context.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_controls'"))
+        return null;
+    const current = context.db.get("SELECT c.* FROM run_controls c JOIN run_recovery_guards g ON g.recovery_id = c.recovery_id WHERE c.project_id = ? AND c.run_id = ? AND c.status IN ('requested','settled','resuming') AND g.status IN ('draining','sealed','resuming') AND g.generation = (SELECT MAX(generation) FROM run_recovery_guards WHERE project_id = c.project_id AND run_id = c.run_id)", [projectId, runId]);
+    if (!current)
+        return null;
+    return { control_id: current.control_id, action: current.action, status: current.status, stop_turn: true, instruction: "The operator has fenced this RUN. Preserve the recorded result and end this Turn now. Do not start another Work, check, Stage or provider operation, and do not wait for resume in a sleep loop. Only the runtime may authorize continuation.", acknowledged: false, settled: false };
+}
+/** The durable fence is committed before observation, steering or interruption. */
+export function recordRunControlIntent(context, input) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(input.requestId) || !["pause", "stop"].includes(input.action)
+        || input.graceMs !== undefined && (!Number.isSafeInteger(input.graceMs) || input.graceMs < 0 || input.graceMs > 3_600_000)
+        || input.force !== undefined && typeof input.force !== "boolean"
+        || input.escalate !== undefined && input.escalate !== "interrupt"
+        || input.action === "pause" && input.force !== undefined
+        || input.action === "stop" && (input.graceMs !== undefined || input.escalate !== undefined))
+        throw new AppError("usage", "Invalid RUN control intent", 2);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const request = { project_root: project.root, run_id: input.runId, action: input.action, ...(input.action === "pause" ? { grace_ms: input.graceMs ?? 30_000, escalate: input.escalate ?? null } : { force: input.force ?? false }) };
+    const requestHash = crypto.createHash("sha256").update(JSON.stringify(request)).digest("hex");
+    ensureRunControlStorage(context.db);
+    context.db.beginWriteTransaction();
+    try {
+        const existing = context.db.get("SELECT * FROM run_controls WHERE project_id = ? AND run_id = ? AND request_id = ?", [project.id, input.runId, input.requestId]);
+        if (existing) {
+            if (existing.request_hash !== requestHash)
+                throw new AppError("runtime_request_conflict", "Control request id has different inputs", 1);
+            context.db.exec("COMMIT");
+            return { ok: true, control_id: existing.control_id, recovery_id: existing.recovery_id, action: existing.action, status: existing.status, reused: true };
+        }
+        const run = context.db.get("SELECT status FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
+        if (!run)
+            throw new AppError("not_found", "RUN is not registered", 1);
+        if (["done", "failed", "cancelled"].includes(run.status)) {
+            context.db.exec("COMMIT");
+            return { ok: true, terminal: true, status: run.status, control_id: null };
+        }
+        const prior = recoveryGuard(context, project.id, input.runId);
+        const active = context.db.get("SELECT * FROM run_controls WHERE project_id = ? AND run_id = ? AND status IN ('requested','settled','resuming')", [project.id, input.runId]);
+        const strongerStop = active?.action === "stop" && input.force === true && JSON.parse(active.request_json).force !== true;
+        const escalates = active && (active.action === "pause" || strongerStop || active.status === "resuming" || prior?.status === "resuming") && input.action === "stop" && prior?.recovery_id === active.recovery_id && (["draining", "sealed", "resuming"].includes(prior.status) || active.status === "resuming" && prior.status === "recovered");
+        if (active && !escalates)
+            throw new AppError("run_control_in_progress", "RUN already has an unresolved control intent", 1, { control_id: active.control_id });
+        if (prior && ["draining", "sealed", "resuming"].includes(prior.status) && !escalates)
+            throw new AppError("run_recovery_guarded", "Existing recovery must be reconciled before another control intent", 1);
+        const now = context.now();
+        if (escalates) {
+            context.db.run("UPDATE run_controls SET status = 'superseded', updated_at = ? WHERE control_id = ?", [now, active.control_id]);
+            context.db.run("UPDATE run_recovery_guards SET status = 'abandoned', updated_at = ? WHERE recovery_id = ?", [now, prior.recovery_id]);
+            context.db.run("UPDATE run_recovery_bindings SET status = 'abandoned' WHERE recovery_id = ? AND status = 'prepared'", [prior.recovery_id]);
+        }
+        const controlId = `CTL-${crypto.randomUUID()}`;
+        const recoveryId = `RCV-${crypto.randomUUID()}`;
+        const generation = (prior?.generation ?? 0) + 1;
+        context.db.run("INSERT INTO run_recovery_guards (recovery_id, project_id, run_id, generation, status, interruption_json, created_at, updated_at) VALUES (?, ?, ?, ?, 'draining', ?, ?, ?)", [recoveryId, project.id, input.runId, generation, JSON.stringify({ control_id: controlId, action: input.action }), now, now]);
+        context.db.run("INSERT INTO run_controls (control_id, project_id, run_id, request_id, request_hash, request_json, recovery_id, action, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'requested', ?, ?)", [controlId, project.id, input.runId, input.requestId, requestHash, JSON.stringify(request), recoveryId, input.action, now, now]);
+        context.db.run("INSERT INTO run_control_admissions (control_id, work_session_id, work_id, session_id, admitted_at) SELECT ?, ws.id, w.work_id, ws.session_id, ? 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' AND w.status = 'running'", [controlId, now, project.id, input.runId]);
+        context.db.run(`INSERT INTO run_control_stage_admissions (control_id, stage, attempt, work_session_id)
+      SELECT ?, json_extract(stage.value, '$.stage'), COALESCE(json_extract(stage.value, '$.attempt'), 'try-001'),
+        (SELECT a.work_session_id FROM run_control_admissions a JOIN sessions s ON s.session_id = a.session_id AND s.project_id = r.project_id JOIN works w ON w.work_id = a.work_id
+         WHERE a.control_id = ? AND s.current_stage = json_extract(stage.value, '$.stage') ORDER BY (w.parent_work_id IS NULL) DESC, a.work_session_id LIMIT 1)
+      FROM runs r, json_each(r.index_json, '$.stage_runs') stage
+      WHERE r.project_id = ? AND r.id = ? AND json_extract(stage.value, '$.status') = 'running'
+        AND EXISTS (SELECT 1 FROM run_control_admissions a JOIN sessions s ON s.session_id = a.session_id AND s.project_id = r.project_id WHERE a.control_id = ? AND s.current_stage = json_extract(stage.value, '$.stage'))`, [controlId, controlId, project.id, input.runId, controlId]);
+        setFlowRunRecoveryPaused(context, project.id, input.runId, true);
+        context.db.exec("COMMIT");
+        return { ok: true, control_id: controlId, recovery_id: recoveryId, generation, action: input.action, status: "requested", settled: false };
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+}