@deksden-com/dd-flow-cli 0.9.0-beta.37 → 0.9.0-beta.39

package/dist/services/merge-server.js

@@ -2,11 +2,12 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
+import { runtimeBudgetForRun } from "./runtime-budget.js";
 import { flowCommand } from "./stage-pause.js";
-import { validateSchema } from "./schema-validation.js";
-import { adapterSessionId, runHarnessAdapter } from "./harness-adapter.js";
+import { adapterSessionId, prepareHarnessFlowExecutable, runHarnessAdapter } from "./harness-adapter.js";
 import { harnessRuntimeArguments, resolveHarnessCommand } from "./harness-config.js";
 import { assertRunMutationAllowed, recoveryGuard } from "./run-recovery.js";
+import { loadAgentProfile, resolveExecutionPolicy } from "./execution-policy.js";
 /** A deterministic dispatcher; only the launched harness Session performs agent work. */
 export async function serveMergeRequests(context, input) {
     const running = context.db.get("SELECT server_id, pid FROM merge_servers WHERE status IN ('running','stopping') ORDER BY started_at LIMIT 1");
@@ -59,49 +60,80 @@ export async function serveMergeRequests(context, input) {
 export function mergeServerStatus(context) { return { ok: true, servers: context.db.all("SELECT server_id, profile_id, status, pid, started_at, heartbeat_at, stopped_at, journal_path FROM merge_servers ORDER BY started_at DESC") }; }
 export function stopMergeServer(context, input) { const changed = context.db.run("UPDATE merge_servers SET status = 'stopping', heartbeat_at = ? WHERE server_id = ? AND status = 'running'", [context.now(), input.serverId]); if (changed.changes !== 1)
     throw new AppError("not_found", "Running merge-server was not found", 1, { server_id: input.serverId }); return { ok: true, server_id: input.serverId, status: "stopping" }; }
-async function dispatch(context, input) {
-    let generation;
+/** Both dispatchers enter the same project FIFO before creating any provider Session. */
+export function claimQueuedMergeRequest(context, input) {
     context.db.exec("BEGIN IMMEDIATE");
-    const token = crypto.randomUUID();
-    const leaseUntil = new Date(Date.now() + 120_000).toISOString();
     try {
-        generation = assertRunMutationAllowed(context, input.request.project_id, input.request.run_id);
-        const claimed = context.db.run("UPDATE merge_requests SET status = 'dispatching', dispatch_owner = ?, dispatch_lease_token = ?, dispatch_lease_expires_at = ?, updated_at = ? WHERE merge_request_id = ? AND status = 'queued' AND execution_route = 'server'", [input.serverId, token, leaseUntil, context.now(), input.request.merge_request_id]);
+        const request = context.db.get("SELECT merge_request_id, project_id, run_id, executor_work_id, target_workspace, execution_route, status, created_at FROM merge_requests WHERE merge_request_id = ?", [input.requestId]);
+        if (!request)
+            throw new AppError("not_found", "MERGE request was not found", 1);
+        const generation = assertRunMutationAllowed(context, request.project_id, request.run_id, input.expectedGeneration);
+        const earlier = context.db.get("SELECT 1 FROM merge_requests WHERE project_id = ? AND status NOT IN ('completed','failed','cancelled','superseded') AND (created_at < ? OR (created_at = ? AND merge_request_id < ?)) LIMIT 1", [request.project_id, request.created_at, request.created_at, request.merge_request_id]);
+        if (request.status !== "queued" || request.execution_route !== "server" || earlier) {
+            context.db.exec("COMMIT");
+            return null;
+        }
+        const token = crypto.randomUUID();
+        context.db.run("UPDATE merge_requests SET status = 'dispatching', dispatch_owner = ?, dispatch_lease_token = ?, dispatch_lease_expires_at = ?, updated_at = ? WHERE merge_request_id = ? AND status = 'queued'", [input.ownerId, token, new Date(Date.now() + 120_000).toISOString(), context.now(), request.merge_request_id]);
         context.db.exec("COMMIT");
-        if (claimed.changes !== 1)
-            return;
+        return { request, token, generation };
     }
     catch (error) {
         context.db.exec("ROLLBACK");
         throw error;
     }
-    const leaseHeartbeat = setInterval(() => { if (guarded(context, input.request) || (recoveryGuard(context, input.request.project_id, input.request.run_id)?.generation ?? 0) !== generation)
-        return; const now = context.now(); context.db.run("UPDATE merge_requests SET dispatch_lease_expires_at = ?, updated_at = ? WHERE merge_request_id = ? AND status = 'dispatching' AND dispatch_owner = ? AND dispatch_lease_token = ?", [new Date(Date.now() + 120_000).toISOString(), now, input.request.merge_request_id, input.serverId, token]); }, 30_000);
-    leaseHeartbeat.unref();
+}
+async function dispatch(context, input) {
+    const run = context.db.get("SELECT index_json, project_root FROM runs WHERE project_id = ? AND id = ?", [input.request.project_id, input.request.run_id]);
+    if (!run)
+        throw new AppError("not_found", "MERGE RUN was not found", 1, { run_id: input.request.run_id });
+    const snapshot = JSON.parse(run.index_json).execution_profile;
+    if (snapshot?.settings?.execution) {
+        if (!snapshot.agent_profiles)
+            throw new AppError("execution_profile_not_frozen", "MERGE dispatch requires frozen RUN agent profiles", 1, { run_id: input.request.run_id });
+        const resolved = resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy: snapshot.settings.execution, profiles: snapshot.agent_profiles, stage: "merge" });
+        input = { ...input, profile: resolved.coordinator };
+    }
+    const claim = claimQueuedMergeRequest(context, { requestId: input.request.merge_request_id, ownerId: input.serverId });
+    if (!claim)
+        return;
+    const { generation, token } = claim;
     const stateDir = path.join(input.root, input.request.merge_request_id);
     fs.mkdirSync(stateDir, { recursive: true });
     const promptFile = path.join(stateDir, "launch.md");
     const adapterJournal = path.join(stateDir, "adapter.events.jsonl");
-    const stageCommand = `${flowCommand(context)} stage start ${input.request.run_id} --stage merge --project-root ${JSON.stringify(input.request.target_workspace)} --json --progress-jsonl`;
+    const flowExecutable = prepareHarnessFlowExecutable(context, stateDir);
+    const runtimeContext = { ...context, env: { ...context.env, DD_FLOW_BIN: flowExecutable } };
+    const stageCommand = `${flowCommand(runtimeContext)} stage start ${input.request.run_id} --stage merge --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`;
     fs.writeFileSync(promptFile, `Start the assigned MERGE stage now. Your first tool call must be this exact standalone command:\n\n${stageCommand}\n\nTrust and follow the complete stage packet it returns. Continue through merge apply and stage finish. Stop only when the stage reaches a terminal result or explicitly requests user/operator action.\n`);
+    const runtimeOwner = { schema_id: "dd-flow/runtime-owner@1", owner_id: `run:${input.request.run_id}:merge:${input.request.merge_request_id}`, role: "merge", project_id: input.request.project_id, run_id: input.request.run_id, work_id: input.request.executor_work_id, operation_id: `${input.request.merge_request_id}:${token}`, state_dir: stateDir, dd_flow_home: context.ddFlowHome, dd_flow_bin: flowExecutable, resource_home: context.env.DD_FLOW_RESOURCE_HOME ?? context.ddFlowHome, budget: runtimeBudgetForRun(context, input.request.project_id, input.request.run_id) };
     event(input.journal, { type: "launch_intent", server_id: input.serverId, request_id: input.request.merge_request_id, token, profile: input.profile, prompt_file: promptFile, at: context.now() });
     input.progress?.(`launching ${input.request.merge_request_id} with ${input.profile.id}`);
     const executable = resolveHarnessCommand(context.ddFlowHome, input.profile.harness, "adapter");
-    const common = ["--state-dir", stateDir, "--journal", adapterJournal, "--cwd", input.request.target_workspace, "--provider", input.profile.provider, "--model", input.profile.model, "--reasoning", input.profile.reasoning, "--mode", input.profile.mode, "--permission", input.profile.permission, "--project-root", input.request.target_workspace, "--dd-flow-home", context.ddFlowHome, ...harnessRuntimeArguments(context.ddFlowHome, input.profile.harness), "--json"];
+    const common = ["--dd-flow-bin", flowExecutable, "--state-dir", stateDir, "--journal", adapterJournal, "--cwd", input.request.target_workspace, "--provider", input.profile.provider, "--model", input.profile.model, "--reasoning", input.profile.reasoning, "--mode", input.profile.mode, "--permission", input.profile.permission, "--project-root", run.project_root, "--dd-flow-home", context.ddFlowHome, ...harnessRuntimeArguments(context.ddFlowHome, input.profile.harness), "--json"];
+    const retained = { profile: input.profile, executable, owner: runtimeOwner, session_id: null, state_dir: stateDir, create_operation_id: `${input.request.merge_request_id}:${token}:session.create`, prompt_operation_id: `${input.request.merge_request_id}:${token}:session.prompt` };
+    const retain = () => { 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(retained), context.now(), input.request.merge_request_id, input.serverId, token]); };
+    retain();
+    const leaseHeartbeat = setInterval(() => { if (guarded(context, input.request) || (recoveryGuard(context, input.request.project_id, input.request.run_id)?.generation ?? 0) !== generation)
+        return; const now = context.now(); context.db.run("UPDATE merge_requests SET dispatch_lease_expires_at = ?, updated_at = ? WHERE merge_request_id = ? AND status = 'dispatching' AND dispatch_owner = ? AND dispatch_lease_token = ?", [new Date(Date.now() + 120_000).toISOString(), now, input.request.merge_request_id, input.serverId, token]); }, 30_000);
+    leaseHeartbeat.unref();
     try {
-        const adapterCall = (args, timeoutMs, progressMessage) => { assertRunMutationAllowed(context, input.request.project_id, input.request.run_id, generation); return runHarnessAdapter({ executable, args, env: context.env, ...(timeoutMs ? { timeoutMs } : {}), ...(input.progress ? { progress: input.progress } : {}), ...(progressMessage ? { progressMessage } : {}), onEvidence: (value) => event(input.journal, { type: "adapter_call", ...value }) }); };
+        const adapterCall = (args, timeoutMs, progressMessage) => { assertRunMutationAllowed(context, input.request.project_id, input.request.run_id, generation); return runHarnessAdapter({ executable, args, env: runtimeContext.env, runtimeOwner, operationId: `${input.request.merge_request_id}:${token}:${args[0]}.${args[1]}`, ...(timeoutMs ? { timeoutMs } : {}), ...(input.progress ? { progress: input.progress } : {}), ...(progressMessage ? { progressMessage } : {}), onEvidence: (value) => event(input.journal, { type: "adapter_call", ...value }) }); };
         await adapterCall(["daemon", "start", ...common]);
         const created = await adapterCall(["session", "create", ...common]);
         const sessionId = adapterSessionId(created);
         if (!sessionId)
             throw new AppError("merge_adapter_invalid", "Harness adapter did not return a Session id", 1, { harness: input.profile.harness, response: created });
+        Object.assign(retained, { session_id: sessionId, create: created });
+        retain();
         const prompted = await adapterCall(["session", "prompt", "--session-id", sessionId, "--prompt-file", promptFile, ...common], 45 * 60 * 1000, `MERGE ${input.request.merge_request_id} Session ${sessionId} is still running`);
+        Object.assign(retained, { response: prompted });
+        retain();
         assertRunMutationAllowed(context, input.request.project_id, input.request.run_id, generation);
         const request = context.db.get("SELECT status FROM merge_requests WHERE merge_request_id = ?", [input.request.merge_request_id]);
-        context.db.run("UPDATE merge_requests SET adapter_receipt_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ profile: input.profile, executable, session_id: sessionId, response: prompted }), context.now(), input.request.merge_request_id]);
         event(input.journal, { type: "adapter_settled", request_id: input.request.merge_request_id, session_id: sessionId, request_status: request?.status ?? null, at: context.now() });
         if (request?.status === "dispatching")
-            context.db.run("UPDATE merge_requests SET status = 'queued', dispatch_owner = NULL, dispatch_lease_token = NULL, dispatch_lease_expires_at = NULL, last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "adapter_did_not_start_stage", response: prompted }), context.now(), input.request.merge_request_id]);
+            context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "adapter_did_not_start_stage", response: prompted }), context.now(), input.request.merge_request_id]);
     }
     catch (error) {
         if (error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale"].includes(error.code)) {
@@ -110,7 +142,7 @@ async function dispatch(context, input) {
         }
         const request = context.db.get("SELECT status FROM merge_requests WHERE merge_request_id = ?", [input.request.merge_request_id]);
         if (request?.status === "dispatching")
-            context.db.run("UPDATE merge_requests SET status = 'queued', dispatch_owner = NULL, dispatch_lease_token = NULL, dispatch_lease_expires_at = NULL, last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "adapter_launch_failed", error: String(error) }), context.now(), input.request.merge_request_id]);
+            context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "adapter_launch_failed", error: String(error) }), context.now(), input.request.merge_request_id]);
         else if (request?.status === "active")
             context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "adapter_lost_after_stage_start", error: String(error) }), context.now(), input.request.merge_request_id]);
         throw error;
@@ -125,18 +157,9 @@ function reconcileExpiredDispatches(context) { const expired = context.db.all("S
     if (guarded(context, request))
         continue;
     const work = context.db.get("SELECT status FROM works WHERE work_id = ?", [request.executor_work_id]);
-    if (work?.status === "created")
-        context.db.run("UPDATE merge_requests SET status = 'queued', dispatch_owner = NULL, dispatch_lease_token = NULL, dispatch_lease_expires_at = NULL, last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "expired_dispatch_requeued" }), context.now(), request.merge_request_id]);
-    else
-        context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "expired_dispatch_with_started_work", work_status: work?.status ?? null }), context.now(), request.merge_request_id]);
+    context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "expired_dispatch_outcome_unknown", work_status: work?.status ?? null }), context.now(), request.merge_request_id]);
 } }
-function loadProfile(context, id) { const file = path.join(context.ddFlowHome, "agent-profiles", `${id}.json`); let value; try {
-    value = JSON.parse(fs.readFileSync(file, "utf8"));
-}
-catch (error) {
-    throw new AppError("agent_profile_missing", "Merge-server agent profile is unavailable", 1, { id, file, cause: String(error) });
-} validateSchema({ schemaName: "agent-profile", file }); if (value.id !== id)
-    throw new AppError("agent_profile_invalid", "Agent profile id does not match its requested filename", 2, { file, expected: id, actual: value.id ?? null }); return value; }
+function loadProfile(context, id) { return loadAgentProfile(context.ddFlowHome, id); }
 function event(file, value) { fs.appendFileSync(file, `${JSON.stringify(value)}\n`); }
 function guarded(context, request) { const guard = recoveryGuard(context, request.project_id, request.run_id); return Boolean(guard && ["draining", "sealed", "resuming"].includes(guard.status)); }
 function delay(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }

package/dist/services/native-daemon-history.js

@@ -0,0 +1,49 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { managedProcessBinding, managedProcessStatus, processTreeIsAlive, resourceHome } from "./managed-processes.js";
+import { retainedDaemonOperations } from "./run-control.js";
+import { managedProviderBelongsToDaemon } from "./managed-daemon-binding.js";
+/** A replaced daemon is a settled resource, never another Session to resume. */
+export function historicalDaemonSettlement(context, scopeId, record) {
+    const metadata = JSON.parse(record.metadata_json);
+    if (!record.kind.endsWith("-daemon") || !metadata.state_dir || !path.isAbsolute(metadata.state_dir))
+        throw new AppError("runtime_scope_owner_unknown", "Native history requires an absolute daemon directory", 1);
+    const current = JSON.parse(fs.readFileSync(path.join(metadata.state_dir, "daemon.json"), "utf8"));
+    if (current.resource_process?.id === record.id)
+        return null;
+    if (record.state !== "stopped" || record.termination_reason !== "daemon_stopped" || !record.pid || !record.pid_started_at || processTreeIsAlive(record))
+        throw new AppError("runtime_scope_owner_unknown", "Previous daemon has no physical completion proof", 1);
+    const directory = path.join(metadata.state_dir, "daemon-history");
+    const matches = fs.readdirSync(directory).filter(name => /^[a-zA-Z0-9-]+\.json$/.test(name)).map(name => {
+        const file = path.join(directory, name);
+        if (!fs.lstatSync(file).isFile())
+            throw new AppError("runtime_scope_owner_unknown", "Daemon history must contain regular receipts", 1);
+        const bytes = fs.readFileSync(file, "utf8");
+        return { file, bytes, state: JSON.parse(bytes) };
+    }).filter(candidate => candidate.state.resource_process?.id === record.id);
+    if (matches.length !== 1)
+        throw new AppError("runtime_scope_owner_unknown", "Previous daemon has no unique retained receipt", 1);
+    const { file, bytes, state } = matches[0], owner = state.config?.runtime_owner;
+    if (!state.daemon_id || path.basename(file) !== `${state.daemon_id}.json` || !owner || owner.budget?.scope_id !== scopeId || owner.owner_id !== record.owner_id || owner.role !== metadata.role || owner.state_dir !== metadata.state_dir || owner.adapter_executable !== metadata.adapter_executable || owner.dd_flow_home !== metadata.dd_flow_home || owner.resource_home !== resourceHome(context) || (owner.project_id ?? null) !== record.project_id || (owner.run_id ?? null) !== record.run_id || (owner.work_id ?? null) !== record.work_id || !record.operation_id?.startsWith(`${owner.operation_id}:`) || state.resource_process?.lease_token !== record.lease_token || state.pid !== record.pid)
+        throw new AppError("runtime_scope_owner_unknown", "Archived daemon does not match its registration", 1);
+    const closed = state.shutdown_state === "clean" && state.active_tree === false
+        ? retainedDaemonOperations(metadata.state_dir).find(operation => operation.daemon_id === state.daemon_id && operation.operation === "daemon.stop" && operation.state === "completed" && operation.result?.stopped === true && operation.result?.clean === true) : undefined;
+    const fresh = managedProcessStatus(context).find(item => item.id === record.id);
+    if (!closed || !fresh || fresh.lease_token !== record.lease_token || fresh.pid !== record.pid || fresh.pid_started_at !== record.pid_started_at || fresh.metadata_json !== record.metadata_json || fresh.state !== "stopped" || fresh.termination_reason !== "daemon_stopped" || processTreeIsAlive(fresh) || fs.readFileSync(file, "utf8") !== bytes)
+        throw new AppError("runtime_scope_outcome_unknown", "Previous daemon lacks stable clean shutdown evidence", 1);
+    const providers = managedProcessStatus(context).filter(item => managedProviderBelongsToDaemon(item, fresh, state));
+    if (state.provider_process && (providers.length !== 1 || providers[0].state !== "stopped" || providers[0].termination_reason !== "daemon_stopped" || !providers[0].operation_id?.startsWith(`${owner.operation_id}:`) || processTreeIsAlive(providers[0])))
+        throw new AppError("runtime_scope_outcome_unknown", "Archived provider lacks its exact physical completion proof", 1);
+    return { historical: true, process_id: record.id, role: metadata.role, state_dir: metadata.state_dir, daemon_id: state.daemon_id,
+        processes: providers.map(item => ({ process_id: item.id, native_settled: true, binding: managedProcessBinding(item, resourceHome(context)) })),
+        settled: true, native_settled: true, operation_id: String(closed.operation_id), owner_operation_id: owner.operation_id,
+        inventory_version: crypto.createHash("sha256").update(JSON.stringify([bytes, closed])).digest("hex") };
+}
+export function assertHistoricalDaemonSettlement(context, scopeId, proof) {
+    const record = managedProcessStatus(context).find(item => item.id === proof.process_id);
+    const fresh = record && historicalDaemonSettlement(context, scopeId, record);
+    if (!fresh || proof.historical !== true || proof.native_settled !== true || fresh.inventory_version !== proof.inventory_version)
+        throw new AppError("runtime_scope_inventory_changed", "Archived daemon settlement changed after observation", 1);
+}

package/dist/services/native-session-control.js

@@ -0,0 +1,31 @@
+import { AppError } from "../shared/errors.js";
+import { adapterSessionId, runHarnessAdapter } from "./harness-adapter.js";
+export async function cancelControlledNativeSession(input) {
+    input.assertCurrent();
+    const reply = await runHarnessAdapter({ executable: input.executable,
+        args: input.observe ? ["daemon", "operation", "--operation-id", input.operationId, "--state-dir", input.stateDir, "--json"] : ["session", "cancel", "--session-id", input.sessionId, "--state-dir", input.stateDir, "--json"],
+        env: input.env, operationId: input.observe ? `${input.operationId}:observe` : input.operationId, timeoutMs: 30_000 });
+    if (input.observe && (reply.operation_id !== input.operationId || reply.operation !== "session.cancel" || reply.session_id !== input.sessionId))
+        throw new AppError("controller_operation_mismatch", "Cancellation observation belongs to another operation or Session", 1);
+    const result = input.observe ? reply.state === "completed" ? reply.result : null : reply;
+    if (!input.observe || reply.state === "completed")
+        assertNativeCancellationReceipt(result, input.sessionId);
+    input.assertCurrent();
+    return { status: result ? "completed" : "outcome_unknown", receipt: (result ?? reply) };
+}
+export function assertNativeCancellationReceipt(value, sessionId) {
+    const identity = adapterSessionId(value);
+    if (!value || typeof value !== "object" || Array.isArray(value) || identity && identity !== sessionId)
+        throw new AppError("controller_operation_mismatch", "Cancellation receipt has no valid result for its target Session", 1);
+}
+/** Native observation is shared by RUN and non-Work EVAL owners. */
+export async function inspectControlledNativeSession(input) {
+    input.assertCurrent();
+    const receipt = await runHarnessAdapter({ executable: input.executable, args: ["session", "inspect", "--session-id", input.sessionId, "--state-dir", input.stateDir, "--json"], env: input.env, operationId: input.operationId, timeoutMs: 30_000 });
+    if (adapterSessionId(receipt) !== input.sessionId)
+        throw new AppError("controller_operation_mismatch", "Session observation belongs to another target", 1);
+    if (input.harness && receipt.harness !== undefined && receipt.harness !== input.harness)
+        throw new AppError("controller_operation_mismatch", "Session observation belongs to another harness", 1);
+    input.assertCurrent();
+    return receipt;
+}

package/dist/services/protocols.js

@@ -733,9 +733,18 @@ function releaseRelatedMergeLocks(context, protocol, reason) {
     return { ok: true, released: released.length, locks: released };
 }
 export function readProtocolRuntimeState(context, protocol) {
+    const expected = runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
+    if (protocol.state_path !== expected)
+        throw new AppError("protocol_state_migration_required", "Protocol runtime path requires explicit cleanup scan/apply before use", 1, { protocol_id: protocol.id, path: protocol.state_path, expected_path: expected });
+    return repairProtocolRuntimeState(context, protocol);
+}
+/** Explicit cleanup migration; productive readers accept only the current path. */
+export function repairProtocolRuntimeState(context, protocol) {
     const diagnostics = [];
     normalizeProtocolPlanPath(context, protocol, diagnostics);
     try {
+        if (protocol.state_path !== runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id))
+            throw new AppError("protocol_state_migration_required", "Retired state files are not runtime authority", 1);
         return { state: readStateFile(protocol.state_path, protocol.id), diagnostics };
     }
     catch {

package/dist/services/recovery-snapshot-database.js

@@ -0,0 +1,103 @@
+import { DatabaseSync } from "node:sqlite";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { registerStoreWriter } from "../storage/writer-contract.js";
+import { managedProcessRuntimeHome } from "./managed-processes.js";
+/** Export one RUN's relational evidence, never mutate the live authority. */
+export function captureRecoveryDatabase(source, output, projectId, runId, protocolIds = []) {
+    source.exec(`VACUUM INTO '${output.replace(/'/g, "''")}'`);
+    const db = new DatabaseSync(output);
+    let complete = false;
+    try {
+        registerStoreWriter(db);
+        db.exec("PRAGMA foreign_keys = OFF; PRAGMA secure_delete = ON; BEGIN IMMEDIATE");
+        db.exec("CREATE TEMP TABLE capture_scope (project_id TEXT, run_id TEXT)");
+        db.prepare("INSERT INTO capture_scope VALUES (?, ?)").run(projectId, runId);
+        db.exec("CREATE TEMP TABLE capture_protocols (id TEXT)");
+        for (const id of protocolIds)
+            db.prepare("INSERT INTO capture_protocols VALUES (?)").run(id);
+        if (!db.prepare("SELECT 1 FROM runs WHERE (project_id, id) IN (SELECT * FROM capture_scope)").get())
+            throw new AppError("snapshot_run_missing", "Recovery export requires the selected RUN", 1);
+        const ownRun = "(project_id, run_id) IN (SELECT * FROM capture_scope)";
+        const ownProject = "project_id IN (SELECT project_id FROM capture_scope)";
+        const works = `SELECT work_id FROM works WHERE ${ownRun}`;
+        if (db.prepare(`SELECT 1 FROM sessions WHERE ${ownProject} AND run_id IS NOT NULL AND run_id NOT IN (SELECT run_id FROM capture_scope) AND session_id IN (SELECT session_id FROM work_sessions WHERE work_id IN (${works})) LIMIT 1`).get())
+            throw new AppError("snapshot_scope_conflict", "Selected Work refers to a Session currently bound to another RUN", 1);
+        const sessions = `SELECT session_id FROM sessions WHERE ${ownProject} AND (run_id IN (SELECT run_id FROM capture_scope) OR session_id IN (SELECT session_id FROM work_sessions WHERE work_id IN (${works})))`;
+        const nativeSessions = `SELECT harness, provider_session_id FROM sessions WHERE ${ownProject} AND session_id IN (${sessions})`;
+        const protocols = `SELECT id FROM capture_protocols UNION SELECT subject_id FROM runs WHERE (project_id, id) IN (SELECT * FROM capture_scope) UNION SELECT value FROM merge_requests, json_each(merge_requests.protocol_ids_json) WHERE ${ownRun} UNION SELECT protocol_id FROM flow_jobs WHERE ${ownRun}`;
+        const rules = {
+            dd_flow_writer_contract: "1",
+            dd_flow_writer_migrations: "0",
+            projects: "id IN (SELECT project_id FROM capture_scope)",
+            runs: "(project_id, id) IN (SELECT * FROM capture_scope)",
+            sessions: `${ownProject} AND session_id IN (${sessions})`,
+            work_sessions: `work_id IN (${works})`, work_launches: `work_id IN (${works})`,
+            work_recovery_segments: `work_id IN (${works})`,
+            run_recovery_bindings: `recovery_id IN (SELECT recovery_id FROM run_recovery_guards WHERE ${ownRun})`,
+            hook_events: `${ownProject} AND (session_id IN (${sessions}) OR (harness, provider_session_id) IN (${nativeSessions}))`,
+            harness_usage_snapshots: `${ownProject} AND (harness, provider_session_id) IN (${nativeSessions})`,
+            protocols: `${ownProject} AND id IN (${protocols})`,
+            project_config: ownProject,
+            // Host installations, caches, queue owners and leases are not portable RUN authority.
+            runtime_config: "0", hook_installations: "0", codex_home_profiles: "0", codex_session_bindings: "0",
+            merge_servers: "0", merge_sessions: "0", merge_queue: "0", lanes: "0", lane_locks: "0", lane_waiters: "0",
+            sqlite_sequence: "0"
+        };
+        for (const table of ["works", "check_receipts", "merge_requests", "flow_run_flag_mutations", "usage", "flow_session_segments", "flow_jobs", "run_recovery_guards", "run_controllers", "run_controls"])
+            rules[table] = ownRun;
+        for (const table of ["plan_bindings", "plan_progress", "worktree_records", "audit_events"])
+            rules[table] = `${ownProject} AND protocol_id IN (${protocols})`;
+        for (const table of ["run_controller_events", "run_controller_operations"])
+            rules[table] = `controller_id IN (SELECT controller_id FROM run_controllers WHERE ${ownRun})`;
+        for (const table of ["run_control_admissions", "run_control_stage_admissions", "run_control_operations", "run_control_workers"])
+            rules[table] = `control_id IN (SELECT control_id FROM run_controls WHERE ${ownRun})`;
+        const tables = db.prepare("SELECT name FROM sqlite_schema WHERE type = 'table'").all();
+        const quote = (name) => `"${name.replaceAll('"', '""')}"`;
+        // Evaluate every relationship before deleting parents, including historical bindings.
+        for (const { name } of tables) {
+            const predicate = rules[name];
+            if (predicate === undefined && db.prepare(`SELECT 1 FROM ${quote(name)} LIMIT 1`).get())
+                throw new AppError("snapshot_scope_unknown", "Recovery export has no scope rule for a populated table", 1, { table: name });
+            db.exec(`CREATE TEMP TABLE ${quote(`keep_${name}`)} AS SELECT rowid AS retained_id FROM ${quote(name)} WHERE ${predicate ?? "0"}`);
+        }
+        for (const { name } of tables)
+            db.exec(`DELETE FROM ${quote(name)} WHERE rowid NOT IN (SELECT retained_id FROM ${quote(`keep_${name}`)})`);
+        const issues = db.prepare("PRAGMA foreign_key_check").all();
+        if (issues.length)
+            throw new AppError("snapshot_scope_inconsistent", "Scoped recovery export has unresolved relational references", 1, { issues });
+        db.exec("COMMIT; VACUUM");
+        complete = true;
+    }
+    finally {
+        db.close();
+        if (!complete)
+            fs.rmSync(output, { force: true });
+    }
+}
+/** Physical leases are evidence, not authority to resurrect on another host. */
+export function readRecoveryResourceEvidence(resourceHome, projectId, runId, authority) {
+    const file = path.join(resourceHome, "runtime.sqlite");
+    const scope = { schema_id: "dd-flow/recovery-resource-evidence@1", source_home: resourceHome, dd_flow_home: authority.ddFlowHome, project_id: projectId, run_id: runId };
+    if (!fs.existsSync(file))
+        return { ...scope, database_present: false, processes: [], resources: [] };
+    const db = new DatabaseSync(file, { readOnly: true });
+    try {
+        db.exec("PRAGMA busy_timeout = 4000; BEGIN");
+        const candidates = db.prepare("SELECT * FROM managed_processes WHERE project_id = ? AND run_id = ? ORDER BY id").all(projectId, runId).map(record => ({ record, home: managedProcessRuntimeHome(record, authority) }));
+        if (candidates.some(item => item.home === null))
+            throw new AppError("snapshot_resource_scope_unproven", "A retained process has no proven runtime-home identity", 1, { resource_home: resourceHome });
+        const processes = candidates.filter(item => item.home === authority.ddFlowHome).map(item => item.record);
+        const ids = new Set(processes.map(record => record.id)), owners = new Set(processes.map(record => record.owner_id));
+        const resources = db.prepare("SELECT r.* FROM managed_resources r JOIN managed_processes p ON p.id = r.process_id WHERE p.project_id = ? AND p.run_id = ? ORDER BY r.resource_kind, r.resource_key").all(projectId, runId).filter(row => typeof row.process_id === "string" && ids.has(row.process_id));
+        const unbound = db.prepare("SELECT owner_id FROM managed_resources WHERE process_id IS NULL AND owner_id IN (SELECT owner_id FROM managed_processes WHERE project_id = ? AND run_id = ?)").all(projectId, runId).some(row => typeof row.owner_id === "string" && owners.has(row.owner_id));
+        if (unbound)
+            throw new AppError("snapshot_resource_scope_unproven", "A retained resource has no process binding proving its RUN scope", 1, { resource_home: resourceHome });
+        db.exec("COMMIT");
+        return { ...scope, database_present: true, processes, resources };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/services/run-control-receipt.js

@@ -0,0 +1,56 @@
+import crypto from "node:crypto";
+const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+const records = (value) => Array.isArray(value) ? value.map(object) : [];
+const text = (value) => typeof value === "string" && value.length ? value : null;
+/** Pure projection of durable evidence. Never infer quiescence from an ACK,
+ * a terminal RUN label, or a settlement captured before a subsequent resume. */
+export function controlStatusReceipt(observation, request = {}) {
+    const control = object(observation.control), worker = object(observation.worker), resume = object(observation.resume_operation);
+    const present = Boolean(control.control_id), current = control.current === true;
+    const activeResume = Boolean(resume.operation_id);
+    const historical = !current || activeResume || ["resuming", "resumed"].includes(String(control.status));
+    const settlement = object(control.settlement);
+    const snapshot = historical ? {} : control.admission === "sealed" ? settlement : object(worker.snapshot);
+    const nodes = records(snapshot.nodes).map((node, index) => {
+        const identity = Object.fromEntries(["operation_id", "controller_id", "process_id", "check_id", "merge_request_id", "work_id", "work_session_id", "session_id", "harness", "state_dir", "resource_home"].filter(key => node[key] !== undefined).map(key => [key, node[key]]));
+        const settled = node.status === "completed";
+        const role = ["subject", "worker", "merge", "judge", "probe", "check", "process"].includes(String(node.role)) ? node.role : node.check_id ? "check" : node.merge_request_id ? "merge" : node.process_id ? "process" : "unknown";
+        return { id: `node:${crypto.createHash("sha256").update(JSON.stringify(Object.keys(identity).length ? identity : { index, reason: node.reason })).digest("hex")}`, role, status: settled ? "completed" : node.status === "outcome_unknown" ? "unknown" : "pending", acknowledged: settled || object(node.receipt).cancelled === true, settled, reason: settled ? null : text(node.reason) ?? "node_settlement_required", details: node };
+    });
+    const settled = present && current && !historical && control.status === "settled" && control.admission === "sealed" && Boolean(control.capture_path) && settlement.settled === true && Array.isArray(settlement.nodes) && nodes.every(node => node.settled);
+    let state;
+    if (!present)
+        state = request.action && ["done", "failed", "cancelled"].includes(String(observation.run_status)) ? "terminal_noop" : "not_requested";
+    else if (!current)
+        state = "superseded";
+    else if (resume.status === "failed" || worker.status === "failed")
+        state = "recovery_required";
+    else if (control.status === "resumed" && control.admission === "recovered" && resume.status === "completed")
+        state = "running";
+    else if (activeResume || control.status === "resuming")
+        state = "resuming";
+    else if (settled)
+        state = control.requested_mode === "pause" ? "paused" : "stopped";
+    else
+        state = control.requested_mode === "pause" ? "pause_requested" : "stop_requested";
+    const reasons = settled ? [] : [...new Set([
+            ...nodes.filter(node => !node.settled).map(node => node.reason),
+            ...(Array.isArray(snapshot.pending_reasons) ? snapshot.pending_reasons.filter((reason) => typeof reason === "string" && Boolean(reason)) : []),
+            ...(!present ? [state === "terminal_noop" ? "terminal_settlement_not_observed" : "control_not_requested"]
+                : !current ? ["control_superseded"]
+                    : state === "running" ? ["run_active"]
+                        : state === "resuming" ? ["recovery_acceptance_pending"]
+                            : state === "recovery_required" ? [text(object(resume.error).code) ?? text(object(worker.error).code) ?? "control_recovery_required"]
+                                : control.admission === "sealed" ? ["recovery_capture_required"] : ["settlement_observation_required"])
+        ])];
+    return {
+        ...observation, schema_id: "dd-flow/run-control-receipt@1", ok: true,
+        request_id: request.requestId ?? text(resume.request_id) ?? text(control.request_id), control_id: text(control.control_id),
+        generation: Number.isSafeInteger(control.generation) ? control.generation : 0,
+        requested_mode: request.action ?? (activeResume ? "resume" : text(control.requested_mode)),
+        applied_mode: settled ? control.requested_mode : state === "running" ? "resume" : null,
+        state, settled, nodes, unsettled_reasons: reasons,
+        resumability: settled || state === "recovery_required" ? "recovery_required" : ["running", "not_requested", "terminal_noop", "superseded"].includes(state) ? "not_applicable" : "pending",
+        recovery_id: text(control.recovery_id)
+    };
+}