@deksden-com/dd-flow-cli 0.9.0-beta.1 → 0.9.0-beta.100

package/dist/services/run-engine-bindings.js

@@ -2,36 +2,18 @@ import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
 export const runEngineBindingSchemaId = "dd-flow/run-engine-binding@1";
-export function findRunHome(ddFlowHome, projectRoot, runIdOrAlias) {
-    const projectsRoot = path.join(ddFlowHome, "projects");
-    if (!fs.existsSync(projectsRoot))
+/** Resolve a RUN from SQLite authority; never discover one by scanning storage paths. */
+export function locateRunRoot(db, projectRoot, runIdOrAlias) {
+    const rows = db.all(`SELECT r.project_id, r.id AS run_id, r.run_root
+       FROM runs r JOIN projects p ON p.id = r.project_id
+      WHERE p.root = ? AND (r.id = ? OR r.short_id = ?)`, [realpathOrResolve(projectRoot), runIdOrAlias, runIdOrAlias]).filter((row) => Boolean(row.run_root));
+    if (rows.length > 1)
+        throw new AppError("ambiguous_id", `RUN id is ambiguous for project: ${runIdOrAlias}`, 2, { project_root: realpathOrResolve(projectRoot), candidates: rows.map((row) => row.run_id) });
+    const row = rows[0];
+    if (!row?.run_root)
         return null;
-    const expectedRoot = realpathOrResolve(projectRoot);
-    const matches = [];
-    for (const projectId of fs.readdirSync(projectsRoot)) {
-        const runsRoot = path.join(projectsRoot, projectId, "runs");
-        if (!isDirectory(runsRoot))
-            continue;
-        for (const runId of fs.readdirSync(runsRoot)) {
-            if (!runIdMatches(runId, runIdOrAlias))
-                continue;
-            const runHome = path.join(runsRoot, runId);
-            const authorityPath = path.join(runHome, "run.json");
-            const bindingPath = path.join(runHome, "engine-binding.json");
-            const binding = readRunEngineBinding(bindingPath, { allowMissing: true });
-            const authorityRoot = binding?.project_root ?? projectRootFromAuthority(authorityPath);
-            if (!authorityRoot || realpathOrResolve(authorityRoot) !== expectedRoot)
-                continue;
-            matches.push({ project_id: projectId, run_id: runId, run_home: runHome, authority_path: authorityPath, binding_path: bindingPath });
-        }
-    }
-    if (matches.length > 1) {
-        throw new AppError("ambiguous_id", `RUN id is ambiguous for project: ${runIdOrAlias}`, 2, {
-            project_root: expectedRoot,
-            candidates: matches.map((match) => match.run_id)
-        });
-    }
-    return matches[0] ?? null;
+    const runRoot = path.resolve(row.run_root);
+    return { project_id: row.project_id, run_id: row.run_id, run_root: runRoot, authority_path: path.join(runRoot, "run.json"), binding_path: path.join(runRoot, "engine-binding.json") };
 }
 export function readRunEngineBinding(file, options = {}) {
     if (!fs.existsSync(file)) {
@@ -86,6 +68,14 @@ export function allRunEngineBindings(ddFlowHome) {
     }
     return bindings;
 }
+function isDirectory(value) {
+    try {
+        return fs.statSync(value).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function isRunEngineBinding(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -96,7 +86,7 @@ function isRunEngineBinding(value) {
         && typeof record.run_id === "string"
         && typeof record.project_root === "string"
         && typeof record.bound_at === "string"
-        && ["run_creation", "legacy_recovery"].includes(String(record.source))
+        && ["run_creation", "legacy_recovery", "fork_upgrade"].includes(String(record.source))
         && typeof record.reason === "string"
         && Boolean(engine && typeof engine === "object" && !Array.isArray(engine)
             && typeof engine.package_name === "string"
@@ -115,32 +105,6 @@ function sameEngine(left, right) {
         && left.integrity_checksum === right.integrity_checksum
         && left.snapshot_root === right.snapshot_root;
 }
-function projectRootFromAuthority(file) {
-    try {
-        const value = JSON.parse(fs.readFileSync(file, "utf8"));
-        const execution = recordValue(value.execution);
-        const workspace = recordValue(value.workspace);
-        const project = recordValue(value.project);
-        return stringValue(execution?.project_root)
-            ?? stringValue(workspace?.project_root)
-            ?? stringValue(project?.root)
-            ?? stringValue(value.project_root);
-    }
-    catch {
-        return null;
-    }
-}
-function runIdMatches(fullId, idOrAlias) {
-    return fullId === idOrAlias || /^RUN-[0-9]+$/.test(idOrAlias) && fullId.startsWith(`${idOrAlias}-`);
-}
-function isDirectory(value) {
-    try {
-        return fs.statSync(value).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
 function realpathOrResolve(value) {
     try {
         return fs.realpathSync(value);
@@ -149,9 +113,3 @@ function realpathOrResolve(value) {
         return path.resolve(value);
     }
 }
-function recordValue(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
-}
-function stringValue(value) {
-    return typeof value === "string" && value.length > 0 ? value : null;
-}

package/dist/services/run-fork.js

@@ -0,0 +1,138 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { createContext } from "../runtime/context.js";
+import { AppError } from "../shared/errors.js";
+import { canonicalPath } from "../storage/paths.js";
+import { installCurrentEngine, upgradeForkedRunEngine, prepareForkEngine } from "./engines.js";
+import { restoreEvalRunSnapshot, prepareEvalRunSnapshot, prepareEvalRunRestore } from "./eval-snapshots.js";
+export function prepareRunFork(input) {
+    const requestId = requireId(input.requestId, "request-id");
+    const snapshot = canonicalPath(input.snapshot, false);
+    const output = canonicalPath(input.output, false);
+    if (snapshot === output || snapshot.startsWith(`${output}${path.sep}`) || output.startsWith(`${snapshot}${path.sep}`)) {
+        throw new AppError("fork_path_conflict", "Fork output must not contain or be contained by its source snapshot", 2, { snapshot, output });
+    }
+    const manifestFile = path.join(snapshot, "snapshot.json");
+    const intentFile = path.join(output, ".fork-intent.json");
+    const receiptFile = path.join(output, "fork.json");
+    const engineVersion = requireText(input.engineVersion, "engine-version");
+    if (fs.existsSync(receiptFile)) {
+        const receipt = readJson(receiptFile);
+        const prior = receipt?.intent;
+        if (!prior || prior.request_id !== requestId || prior.snapshot !== snapshot || prior.engine_version !== engineVersion || prior.integrity_checksum !== (input.integrityChecksum ?? null))
+            throw new AppError("fork_request_conflict", "Fork output already belongs to another request", 1, { output });
+        return { receipt, output };
+    }
+    prepareForkEngine(engineVersion, input.integrityChecksum);
+    const manifest = prepareEvalRunSnapshot(snapshot);
+    if (manifest.schema_id !== "dd-flow/eval-run-snapshot@5" || manifest.purpose !== "stage_entry" || typeof manifest.stage_entry !== "string" || typeof manifest.run_id !== "string") {
+        throw new AppError("fork_checkpoint_invalid", "Fork requires a sealed stage-entry snapshot", 2, { snapshot });
+    }
+    const intent = {
+        schema_id: "dd-flow/run-fork-intent@1",
+        request_id: requestId,
+        snapshot,
+        snapshot_sha256: fileHash(manifestFile),
+        engine_version: engineVersion,
+        integrity_checksum: input.integrityChecksum ?? null,
+        target_stage: manifest.stage_entry
+    };
+    assertForkOutput(output, intentFile, intent);
+    return { manifest, snapshot, output, intent, intentFile, receiptFile, requestId };
+}
+function assertForkOutput(output, intentFile, intent) {
+    if (fs.existsSync(output) && !fs.statSync(output).isDirectory())
+        throw new AppError("fork_output_not_empty", "Fork output must be a directory", 2, { output });
+    if (fs.existsSync(output) && fs.readdirSync(output).length > 0) {
+        if (!fs.existsSync(intentFile) || hash(readJson(intentFile).intent) !== hash(intent))
+            throw new AppError("fork_output_not_empty", "Fork output must be empty", 2, { output });
+        const unknown = fs.readdirSync(output).filter(name => ![".fork-intent.json", "project", "dd-flow-home"].includes(name));
+        if (unknown.length)
+            throw new AppError("fork_retry_inspect_required", "Fork output contains data not owned by the interrupted fork", 1, { output, unknown });
+    }
+}
+export function forkRunFromSnapshot(context, input, prepared = prepareRunFork(input)) {
+    if ("receipt" in prepared)
+        return prepared.receipt;
+    const { manifest, snapshot, output, intent, intentFile, receiptFile, requestId } = prepared;
+    assertForkOutput(output, intentFile, intent);
+    for (const name of ["project", "dd-flow-home"])
+        fs.rmSync(path.join(output, name), { recursive: true, force: true });
+    fs.mkdirSync(output, { recursive: true, mode: 0o700 });
+    writeJsonAtomic(intentFile, { schema_id: "dd-flow/run-fork-intent@1", intent });
+    const projectRoot = path.join(output, "project");
+    const home = path.join(output, "dd-flow-home");
+    fs.mkdirSync(projectRoot, { recursive: true, mode: 0o700 });
+    const targetContext = createContext({ ...context.env, DD_FLOW_HOME: home, DD_FLOW_ENGINE_MODE: "1" });
+    const restoreInput = { snapshot, projectRoot };
+    const restored = restoreEvalRunSnapshot(targetContext, restoreInput, prepareEvalRunRestore(targetContext, restoreInput, manifest));
+    const restoredContext = createContext({ ...context.env, DD_FLOW_HOME: home, DD_FLOW_ENGINE_MODE: "1" });
+    try {
+        const runHome = String(restored.run_home);
+        const previousBinding = readJson(path.join(runHome, "engine-binding.json"));
+        const lineage = {
+            schema_id: "dd-flow/run-fork-lineage@1",
+            request_id: requestId,
+            source_snapshot: snapshot,
+            source_snapshot_sha256: intent.snapshot_sha256,
+            source_run_id: manifest.run_id,
+            target_stage: manifest.stage_entry,
+            inherited_engine: previousBinding,
+            created_at: restoredContext.now()
+        };
+        writeJsonAtomic(path.join(runHome, "fork-lineage.json"), lineage);
+        // Install the immutable artifact belonging to the currently executing
+        // CLI into the new home. Its exact version/checksum were checked before
+        // any interrupted-copy cleanup; snapshots exclude installed engines.
+        installCurrentEngine(restoredContext, { forRouting: true });
+        const binding = upgradeForkedRunEngine(restoredContext, {
+            projectRoot,
+            runId: String(restored.run_id),
+            engineVersion: intent.engine_version,
+            ...(intent.integrity_checksum ? { integrityChecksum: intent.integrity_checksum } : {}),
+            reason: `Fork ${requestId} from sealed checkpoint ${intent.snapshot_sha256}.`
+        });
+        const receipt = {
+            ok: true,
+            schema_id: "dd-flow/run-fork@1",
+            status: "ready",
+            intent,
+            fork: {
+                project_root: projectRoot,
+                dd_flow_home: home,
+                run_id: restored.run_id,
+                run_home: runHome,
+                workspace_root: restored.workspace_root,
+                target_stage: manifest.stage_entry,
+                engine: binding.engine,
+                lineage_file: path.join(runHome, "fork-lineage.json")
+            },
+            next_command: `dd-flow stage start ${restored.run_id} --stage ${manifest.stage_entry} --project-root ${JSON.stringify(projectRoot)} --json`
+        };
+        writeJsonAtomic(receiptFile, receipt);
+        return receipt;
+    }
+    finally {
+        restoredContext.db.close?.();
+    }
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new AppError("fork_checkpoint_invalid", "Fork metadata is not valid JSON", 2, { file, cause: String(error) });
+    }
+}
+function writeJsonAtomic(file, value) {
+    const temporary = `${file}.tmp-${process.pid}-${crypto.randomUUID()}`;
+    fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, file);
+}
+function hash(value) { return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
+function fileHash(file) { return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); }
+function requireText(value, name) { const text = value.trim(); if (!text)
+    throw new AppError("usage", `Missing required value: ${name}`, 2); return text; }
+function requireId(value, name) { const text = requireText(value, name); if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(text))
+    throw new AppError("usage", `Invalid ${name}`, 2); return text; }

package/dist/services/run-observations.js

@@ -0,0 +1,112 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ToolObservations, replayToolJournal } from "../harness-runtime/lib/tool-observations.mjs";
+import { harnessKey } from "./harness-config.js";
+/** Evidence has ancestry, not executable ownership. Never open a source home. */
+export function runObservations(context, projectId, runId) {
+    const home = fs.realpathSync(context.ddFlowHome), sources = new Map(), reasons = [];
+    const sessions = context.db.all("SELECT session_id, provider_session_id, harness, transcript_path FROM sessions WHERE project_id = ? AND run_id = ?", [projectId, runId]);
+    const inside = (root, file) => { const p = path.relative(root, file); return p !== "" && p !== ".." && !p.startsWith(`..${path.sep}`) && !path.isAbsolute(p); };
+    const add = (id, nativeId, journal, origin, provenance, harness) => {
+        if (sources.has(id))
+            return;
+        const candidates = sessions.filter(s => (s.provider_session_id ?? s.session_id) === nativeId && (!harness || s.harness === harness));
+        if (candidates.length > 1) {
+            reasons.push("journal_session_ambiguous");
+            return;
+        }
+        const owner = candidates[0];
+        if (!owner)
+            return;
+        const source = { id, provenance, session: { harness_id: owner.harness, session_id: nativeId }, path: null, status: "unavailable" };
+        sources.set(id, source);
+        if (typeof journal !== "string" || !path.isAbsolute(journal) || !inside(origin, journal)) {
+            source.reason = "journal_outside_owned_home";
+            return;
+        }
+        source.path = path.relative(origin, journal);
+        const file = path.resolve(home, source.path);
+        try {
+            if (!inside(home, fs.realpathSync(file))) {
+                source.reason = "journal_outside_owned_home";
+                return;
+            }
+            if (!fs.statSync(file).isFile()) {
+                source.reason = "journal_not_file";
+                return;
+            }
+            source.status = "available";
+        }
+        catch {
+            source.reason = "journal_missing";
+        }
+    };
+    const controllers = (rows, origin, provenance) => {
+        for (const row of rows) {
+            if (row.project_id !== projectId || row.run_id !== runId)
+                continue;
+            try {
+                for (const session of JSON.parse(row.state_json).sessions ?? [])
+                    add(`${row.controller_id}:${session.id}`, session.id, session.journal, origin, provenance, session.profile?.harness ? harnessKey(session.profile.harness) : undefined);
+            }
+            catch {
+                reasons.push("controller_evidence_invalid");
+            }
+        }
+    };
+    if (context.db.all("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'run_controllers'").length) {
+        controllers(context.db.all("SELECT controller_id, project_id, run_id, state_json FROM run_controllers WHERE project_id = ? AND run_id = ?", [projectId, runId]), home, "current");
+    }
+    const imports = path.join(home, "snapshot-imports");
+    if (fs.existsSync(imports))
+        for (const file of fs.readdirSync(imports).filter(name => name.endsWith(".json")).sort()) {
+            try {
+                const location = path.join(imports, file);
+                if (!inside(home, fs.realpathSync(location))) {
+                    reasons.push("lineage_outside_owned_home");
+                    continue;
+                }
+                const archive = JSON.parse(fs.readFileSync(location, "utf8"));
+                if (archive.schema_id !== "dd-flow/snapshot-runtime-lineage@1" || archive.run_id !== runId)
+                    continue;
+                if (typeof archive.source_runtime !== "string" || !path.isAbsolute(archive.source_runtime)) {
+                    reasons.push("lineage_source_invalid");
+                    continue;
+                }
+                controllers(archive.run_tables?.run_controllers ?? [], archive.source_runtime, "inherited");
+            }
+            catch {
+                reasons.push("lineage_evidence_invalid");
+            }
+        }
+    // Native transcript adapters need no managed controller journal.
+    for (const session of sessions)
+        if (session.transcript_path && ![...sources.values()].some(s => s.session.harness_id === session.harness && s.session.session_id === (session.provider_session_id ?? session.session_id))) {
+            add(`transcript:${session.harness}:${session.provider_session_id ?? session.session_id}`, session.provider_session_id ?? session.session_id, session.transcript_path, home, "current", session.harness);
+        }
+    const reducer = new ToolObservations();
+    for (const reason of reasons)
+        reducer.gaps.add(reason);
+    for (const source of sources.values()) {
+        if (source.status !== "available") {
+            reducer.gaps.add(source.reason ?? "journal_unavailable");
+            continue;
+        }
+        replayToolJournal(path.join(home, source.path), { harness: source.session.harness_id, rootSessionId: source.session.session_id }, reducer);
+    }
+    const expected = [...new Map(sessions.map(s => { const session = { harness_id: s.harness, session_id: s.provider_session_id ?? s.session_id }; return [JSON.stringify(session), session]; })).values()];
+    const expectedIds = new Set(expected.map(s => JSON.stringify(s)));
+    for (const [key, event] of reducer.calls)
+        if (!expectedIds.has(JSON.stringify(event.session))) {
+            reducer.calls.delete(key);
+            reducer.gaps.add("tool_session_not_bound_to_run");
+        }
+    const summary = reducer.summary();
+    const observed = new Set(summary.sessions.map(s => JSON.stringify(s.session)));
+    const missing = expected.filter(s => !observed.has(JSON.stringify(s)));
+    const completeness = missing.length || summary.completeness !== "complete" ? "partial" : "complete";
+    return { schema_id: "dd-flow/run-observations@1", home, sources: [...sources.values()], tools: { ...summary,
+            completeness, status: observed.size === 0 ? "unavailable" : completeness === "complete" ? "measured" : "partial",
+            observed_sessions: expected.length - missing.length, expected_sessions: expected.length, unavailable_sessions: missing.map(s => s.session_id), missing_sessions: missing,
+            reasons: [...new Set([...summary.reasons, ...(missing.length ? ["sessions_without_tool_observations"] : [])])] } };
+}

package/dist/services/run-projection.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { reconcileSessionCoverageRows } from "../domain/session-coverage.js";
+import { publicSessionIdentity } from "./session-identity.js";
 export function refreshRunSessionProjection(context, projectId, runId) {
     const run = context.db.get("SELECT id, flow_kind, status, project_root, subject_type, subject_id, runtime_path, run_index_path, index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
     if (!run)
@@ -9,7 +10,8 @@ export function refreshRunSessionProjection(context, projectId, runId) {
     const sessionRows = context.db.all(`SELECT session_id, harness, provider_session_id, parent_session_id, role, session_kind, worker_id, current_stage, status,
             created_at, updated_at, stopped_at, coverage_units_json
        FROM sessions WHERE project_id = ? AND run_id = ? ORDER BY created_at, session_id`, [projectId, runId]);
-    const sessions = sessionRows.map(sessionProjection);
+    const sessionIdentities = new Map(sessionRows.map((row) => [row.session_id, publicSessionIdentity(row)]));
+    const sessions = sessionRows.map((row) => sessionProjection(row, sessionIdentities));
     const workRows = context.db.all("SELECT work_id, parent_work_id, status, depends_on_json, launch_policy, started_at, completed_at FROM works WHERE project_id = ? AND run_id = ? ORDER BY created_at, work_id", [projectId, runId]);
     const works = workRows.map((work) => ({ work_id: work.work_id, parent_work_id: work.parent_work_id, status: work.status, depends_on: parseStringArray(work.depends_on_json), launch_policy: work.launch_policy, started_at: work.started_at, completed_at: work.completed_at }));
     const rootWorkId = workRows.find((work) => work.parent_work_id === null)?.work_id ?? null;
@@ -123,10 +125,12 @@ function readPlanId(planPath) {
     return "unknown-plan";
 }
 function workerProjection(context, projectId, runId) {
-    return Object.fromEntries(context.db.all("SELECT job_id, plan_item_id, status, worker_session_id FROM flow_jobs WHERE project_id = ? AND run_id = ? ORDER BY job_id", [projectId, runId]).map((job) => [job.job_id, {
+    return Object.fromEntries(context.db.all(`SELECT j.job_id, j.plan_item_id, j.status, j.worker_session_id, s.harness, s.provider_session_id
+       FROM flow_jobs j LEFT JOIN sessions s ON s.project_id = j.project_id AND s.session_id = j.worker_session_id
+      WHERE j.project_id = ? AND j.run_id = ? ORDER BY j.job_id`, [projectId, runId]).map((job) => [job.job_id, {
             units: [job.plan_item_id],
             status: { pending: "registered", done: "completed" }[job.status] ?? job.status,
-            ...(job.worker_session_id ? { session_id: job.worker_session_id } : {})
+            ...(job.worker_session_id && job.harness ? { session: publicSessionIdentity({ harness: job.harness, provider_session_id: job.provider_session_id, session_id: job.worker_session_id }) } : {})
         }]));
 }
 function parseStringArray(value) {
@@ -138,12 +142,10 @@ function parseStringArray(value) {
         return [];
     }
 }
-function sessionProjection(row) {
+function sessionProjection(row, identities) {
     return {
-        session_id: row.session_id,
-        harness: row.harness,
-        provider_session_id: row.provider_session_id,
-        parent_session_id: row.parent_session_id,
+        session: publicSessionIdentity(row),
+        ...(row.parent_session_id ? { parent_session: identities.get(row.parent_session_id) ?? null } : {}),
         role: row.role,
         session_kind: row.session_kind,
         work_id: row.worker_id,

package/dist/services/run-recovery-runtime.js

@@ -0,0 +1,69 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { requireProjectByRoot } from "./projects.js";
+import { acceptanceCommand, recoveryGuard, recoveryPacketReceipt, requireRecoveryRun } from "./run-recovery.js";
+import { processIsAlive } from "./managed-processes.js";
+import { requireManagedDaemonBinding } from "./managed-daemon-binding.js";
+/** Pin retained Session loading and its first acknowledgement Turn, never a general fence bypass. */
+export function prepareRunRecoveryDispatch(context, input) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(input.operationId) || !path.isAbsolute(input.stateDir))
+        throw new AppError("usage", "Recovery dispatch requires an operation id and absolute state directory", 2);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRecoveryRun(context, project.id, input.runId);
+    context.db.beginWriteTransaction();
+    try {
+        const guard = recoveryGuard(context, project.id, run.id);
+        const binding = context.db.get("SELECT * FROM run_recovery_bindings WHERE recovery_id = ?", [input.recoveryId]);
+        if (!guard || guard.recovery_id !== input.recoveryId || !binding || !["resuming", "recovered"].includes(guard.status))
+            throw new AppError("recovery_state_changed", "Recovery dispatch no longer belongs to the current generation", 1);
+        recoveryPacketReceipt(binding);
+        if (binding.runtime_dispatch_json) {
+            const prior = JSON.parse(binding.runtime_dispatch_json);
+            if (prior.state_dir !== input.stateDir || prior.operation_id !== input.operationId)
+                throw new AppError("recovery_binding_mismatch", "Recovery dispatch is already pinned to another operation", 1);
+            context.db.exec("COMMIT");
+            return prior;
+        }
+        if (guard.status !== "resuming" || binding.status !== "prepared")
+            throw new AppError("recovery_state_changed", "Recovery acknowledgement is no longer awaiting dispatch", 1);
+        const { state, process: record } = requireManagedDaemonBinding(context, { stateDir: input.stateDir, projectId: project.id, runId: run.id });
+        if ((state.daemon_id ?? state.config?.daemonId) !== binding.daemon_id || record.state !== "running" || !processIsAlive(record))
+            throw new AppError("recovery_runtime_mismatch", "Recovery requires its live replacement daemon", 1);
+        const metadata = JSON.parse(record.metadata_json);
+        if (metadata.state_dir !== input.stateDir || metadata.run_generation !== guard.generation || metadata.dispatch_barrier !== "run-generation@1" || !["subject", "merge"].includes(metadata.role ?? ""))
+            throw new AppError("recovery_runtime_mismatch", "Replacement daemon lacks this recovery generation's native dispatch barrier", 1);
+        const prompt = `Resume this retained RUN in its existing native Session. Your first tool call must be this exact standalone command:\n\n${acceptanceCommand(context, run.id, guard.recovery_id, run.project_root)}\n\nFollow the verified recovery packet returned by that command. Preserve completed Work and existing HITL; do not start a successor Stage yourself. Stop at the Stage or declared Work-graph boundary.\n`;
+        const dispatch = { process_id: record.id, owner_id: record.owner_id, state_dir: input.stateDir, daemon_id: binding.daemon_id, operation_id: input.operationId, resume_operation_id: `${input.operationId}:load`, prompt_sha256: crypto.createHash("sha256").update(prompt).digest("hex"), prompt };
+        context.db.run("UPDATE run_recovery_bindings SET runtime_dispatch_json = ? WHERE recovery_id = ? AND status = 'prepared' AND runtime_dispatch_json IS NULL", [JSON.stringify(dispatch), binding.recovery_id]);
+        context.db.exec("COMMIT");
+        return dispatch;
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+}
+/** The caller has already checked PID/start/lease and runtime-home identity. */
+export function recoveryRuntimeAdmission(context, record, input) {
+    if (!record.project_id || !record.run_id || !input.daemonId)
+        return false;
+    const guard = recoveryGuard(context, record.project_id, record.run_id);
+    if (!guard || !["resuming", "recovered"].includes(guard.status))
+        return false;
+    const binding = context.db.get("SELECT * FROM run_recovery_bindings WHERE recovery_id = ? AND daemon_id = ?", [guard.recovery_id, input.daemonId]);
+    if (!binding?.runtime_dispatch_json)
+        return false;
+    const dispatch = JSON.parse(binding.runtime_dispatch_json);
+    if (dispatch.process_id !== record.id || dispatch.owner_id !== record.owner_id || dispatch.state_dir !== input.stateDir || dispatch.daemon_id !== input.daemonId)
+        return false;
+    const metadata = JSON.parse(record.metadata_json);
+    if (metadata.run_generation !== guard.generation)
+        return false;
+    if (guard.status === "recovered" && binding.status === "accepted")
+        return true;
+    if (guard.status === "resuming" && binding.status === "prepared" && input.operation === "session.resume")
+        return typeof dispatch.resume_operation_id === "string" && input.operationId === dispatch.resume_operation_id && input.nativeSessionId === binding.provider_session_id;
+    return guard.status === "resuming" && binding.status === "prepared" && input.operation === "session.prompt" && input.operationId === dispatch.operation_id && input.nativeSessionId === binding.provider_session_id && input.promptSha256 === dispatch.prompt_sha256;
+}