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

package/dist/services/work-registry.js

@@ -4,12 +4,14 @@ import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { findRecentMatchingHookEvent, claimStageStartHookEvent, claimWorkStartHookEvent, hookSessionIdentity, workStartMatchKey } from "./hooks.js";
 import { validateSchema } from "./schema-validation.js";
-import { resolveProjectRoot, resolveRunReferences, writeJsonAtomic } from "../storage/paths.js";
+import { resolveProjectRoot, resolveRunReferences } from "../storage/paths.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
-import { readCodeCheckProfile, runCodeChecks } from "./code-checks.js";
+import { readCodeCheckProfile, runCodeChecks, workspaceFingerprint } from "./code-checks.js";
 import { nextWorkId, nextWorkIds } from "./ids.js";
 import { appendFlowRunTimelineEvent } from "./runs.js";
 import { flowCommand } from "./stage-pause.js";
+import { assertPortableArtifactRef } from "./portable-refs.js";
+import { publicSessionIdentity } from "./session-identity.js";
 const workColumns = "work_id, project_id, run_id, parent_work_id, task, launch_policy, result_schema, payload_json, depends_on_json, status, result, created_at, started_at, updated_at, completed_at";
 export function ensureWorkRegistry(context) { context.db.exec("SELECT 1 FROM works LIMIT 1"); context.db.exec("SELECT 1 FROM work_sessions LIMIT 1"); }
 export function createChildWork(context, input) {
@@ -111,7 +113,7 @@ export function listWorks(context, input) {
             return { ...work, payload: parsePayload(work), payload_json: undefined, depends_on: parseDependencies(work), ready: isReadyNow, ...(isReadyNow ? { start_command: workStartCommand(context, work) } : {}), ...(input.includeResults ? {} : { result: undefined }) };
         }) };
 }
-export function showWork(context, id) { const work = requireWork(context, id); const sessions = context.db.all("SELECT id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, completed_at FROM work_sessions WHERE work_id = ? ORDER BY created_at", [work.work_id]); return { work: { ...work, short_id: shortWorkId(work.work_id), payload: parsePayload(work), payload_json: undefined, depends_on: parseDependencies(work), sessions } }; }
+export function showWork(context, id) { const work = requireWork(context, id); const sessions = context.db.all("SELECT ws.id, ws.work_id, ws.session_id, ws.hook_event_id, ws.status, ws.prompt_path, ws.result_path, ws.created_at, ws.completed_at, s.harness AS harness_id, COALESCE(s.provider_session_id, s.session_id) AS native_session_id FROM work_sessions ws LEFT JOIN sessions s ON s.project_id = ? AND s.session_id = ws.session_id WHERE ws.work_id = ? ORDER BY ws.created_at", [work.project_id, work.work_id]); return { work: { ...work, short_id: shortWorkId(work.work_id), payload: parsePayload(work), payload_json: undefined, depends_on: parseDependencies(work), sessions: sessions.map(({ session_id, harness_id, native_session_id, ...session }) => ({ ...session, ...(harness_id && native_session_id ? { session: publicSessionIdentity({ harness: harness_id, provider_session_id: native_session_id, session_id }) } : {}) })) } }; }
 export function mutateWorkDeps(context, input) {
     const work = requireWork(context, input.workId);
     if (input.action === "list")
@@ -262,6 +264,17 @@ export function startBoundWork(context, work, run, identity, hookEventId) {
     fs.mkdirSync(directory, { recursive: true });
     const promptPath = path.join(directory, "prompt.md");
     const resultPath = path.join(directory, "result.json");
+    const contextPath = path.join(directory, "context.json");
+    const dependencyResults = parseDependencies(work).map((dependency) => context.db.get("SELECT work_id, result FROM works WHERE work_id = ?", [dependency])).filter(Boolean);
+    const prompt = renderWorkerPrompt(context, work, run, dependencyResults);
+    const payload = parsePayload(work);
+    const readOnly = payload?.read_only === true;
+    const workContext = { schema_id: "dd-flow/work-context@1", run_id: work.run_id, work_id: work.work_id, parent_work_id: work.parent_work_id, project_root: run.project_root, workspace_root: run.workspace_root, run_root: requireRunHome(run), depends_on: parseDependencies(work), launch_policy: work.launch_policy, result_schema: work.result_schema, read_only: readOnly, ...(readOnly ? { workspace_fingerprint: workspaceFingerprint(run.workspace_root) } : {}) };
+    const token = crypto.randomUUID();
+    const promptCandidate = `${promptPath}.${token}.tmp`;
+    const contextCandidate = `${contextPath}.${token}.tmp`;
+    fs.writeFileSync(promptCandidate, prompt);
+    fs.writeFileSync(contextCandidate, `${JSON.stringify(workContext, null, 2)}\n`);
     context.db.exec("BEGIN IMMEDIATE");
     try {
         bindSession(context, work, run, identity, now);
@@ -271,23 +284,23 @@ export function startBoundWork(context, work, run, identity, hookEventId) {
         if (claimed.changes !== 1)
             throw new AppError("conflict", "Work was claimed concurrently", 1, { work_id: work.work_id });
         context.db.run(`INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, NULL)`, [linkId, work.work_id, identity.sessionId, hookEventId, promptPath, resultPath, now, now]);
+        fs.renameSync(promptCandidate, promptPath);
+        fs.renameSync(contextCandidate, contextPath);
         context.db.exec("COMMIT");
     }
     catch (error) {
         context.db.exec("ROLLBACK");
+        fs.rmSync(promptCandidate, { force: true });
+        fs.rmSync(contextCandidate, { force: true });
         throw error;
     }
-    const dependencyResults = parseDependencies(work).map((dependency) => context.db.get("SELECT work_id, result FROM works WHERE work_id = ?", [dependency])).filter(Boolean);
-    const prompt = renderWorkerPrompt(context, work, run, dependencyResults, resultPath);
-    writeJsonAtomic(path.join(directory, "context.json"), { schema_id: "dd-flow/work-context@1", run_id: work.run_id, work_id: work.work_id, parent_work_id: work.parent_work_id, project_root: run.project_root, workspace_root: run.workspace_root, run_root: requireRunHome(run), depends_on: parseDependencies(work), launch_policy: work.launch_policy, result_schema: work.result_schema });
-    fs.writeFileSync(promptPath, prompt);
     refreshRunWorkProjection(context, work.project_id, work.run_id);
-    return { ok: true, work_id: work.work_id, work_session_id: linkId, worker_prompt_markdown: prompt, prompt_path: promptPath, session_binding: { source: "PreToolUse", session_id: identity.sessionId } };
+    return { ok: true, work_id: work.work_id, work_session_id: linkId, worker_prompt_markdown: prompt, prompt_path: promptPath, session_binding: { source: "PreToolUse", session: { harness_id: identity.harness, session_id: identity.nativeSessionId } } };
 }
 export function finishWork(context, id, result, progress) { return settle(context, id, "completed", result, progress); }
 /** Structured fan-in closes a parent after its Session was handed to a child. */
 export function finishFanInWork(context, id, result) { const work = requireWork(context, id); if (work.status !== "running")
-    throw new AppError("invalid_work_state", "Fan-in Work is not running", 2, { work_id: work.work_id, status: work.status }); if (context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? AND status IN ('created','running') LIMIT 1", [work.work_id]))
+    throw new AppError("invalid_work_state", "Fan-in Work is not running", 2, { work_id: work.work_id, status: work.status }); if (context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? AND status IN ('created','running','paused') LIMIT 1", [work.work_id]))
     throw new AppError("active_child_work", "Fan-in Work still has active children", 2, { work_id: work.work_id }); const now = context.now(); context.db.run("UPDATE works SET status = 'completed', result = ?, completed_at = ?, updated_at = ? WHERE work_id = ?", [result, now, now, work.work_id]); context.db.run("UPDATE work_sessions SET status = 'completed', completed_at = COALESCE(completed_at, ?), updated_at = ? WHERE work_id = ? AND status = 'running'", [now, now, work.work_id]); refreshRunWorkProjection(context, work.project_id, work.run_id); appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: "work_completed", work_id: work.work_id, fan_in: true }); return { ok: true, work_id: work.work_id, status: "completed", fan_in: true }; }
 export function failWork(context, id, reason) { return settle(context, id, "failed", reason); }
 export function cancelWork(context, id, reason) { return settle(context, id, "cancelled", reason); }
@@ -302,7 +315,7 @@ async function settle(context, id, status, result, progress) {
     id = work.work_id;
     if (work.status !== "running" && !(status === "cancelled" && work.status === "created"))
         throw new AppError("invalid_work_state", "Work is not running", 2, { status: work.status });
-    if (status === "completed" && context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? AND status IN ('created', 'running') LIMIT 1", [id]))
+    if (status === "completed" && context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? AND status IN ('created', 'running', 'paused') LIMIT 1", [id]))
         throw new AppError("active_child_work", "Work cannot complete while a child Work is active", 2, { work_id: id });
     const run = requireRun(context, work.project_id, work.run_id);
     const link = context.db.get("SELECT id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, completed_at FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [id]);
@@ -311,7 +324,14 @@ async function settle(context, id, status, result, progress) {
     let receipts = [];
     let coordinationDrift = [];
     if (status === "completed") {
-        validateWorkResult(work, result, run.project_root, run.workspace_root, run.id, link?.result_path ?? null);
+        if (parsePayload(work)?.read_only === true) {
+            const contextFile = link ? path.join(path.dirname(link.prompt_path), "context.json") : "";
+            const baseline = contextFile && fs.existsSync(contextFile) ? JSON.parse(fs.readFileSync(contextFile, "utf8")).workspace_fingerprint : null;
+            const current = workspaceFingerprint(run.workspace_root);
+            if (typeof baseline !== "string" || baseline !== current)
+                throw new AppError("read_only_work_mutated_workspace", "Read-only Work changed the accepted workspace", 2, { work_id: work.work_id, baseline, current });
+        }
+        validateWorkResult(work, result, run.project_root, run.workspace_root, requireRunHome(run), run.id, link?.result_path ?? null);
         const packet = codePacket(work);
         if (packet) {
             // CODE packets are projected from a PLAN that already validated this
@@ -362,21 +382,33 @@ function bindSession(context, work, run, identity, now) {
     const inferredParentSession = work.parent_work_id
         ? context.db.get("SELECT session_id FROM work_sessions WHERE work_id = ? ORDER BY created_at DESC LIMIT 1", [work.parent_work_id])?.session_id ?? null
         : priorWorkSession && priorWorkSession !== identity.sessionId ? priorWorkSession : null;
-    const parentSession = identity.parentSessionId ?? inferredParentSession;
+    // Work ancestry and provider-tree containment are different relations. An
+    // isolated worker is logically a child Work but physically a provider root.
+    const parentSession = inferredParentSession ?? identity.parentSessionId;
+    const providerParentSession = identity.parentSessionId;
     if (work.parent_work_id && !parentSession)
         throw new AppError("parent_session_required", "Child Work requires a confirmed parent Work/Session link", 1, { work_id: work.work_id, parent_work_id: work.parent_work_id });
     if (work.launch_policy === "fresh_agent_required" && (identity.sessionId === parentSession || context.db.get("SELECT 1 FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ? LIMIT 1", [work.project_id, work.run_id, identity.sessionId])))
         throw new AppError("fresh_session_required", "This Work requires a fresh Session in this RUN", 1, { work_id: work.work_id, session_id: identity.sessionId });
-    const existing = context.db.get("SELECT session_id, parent_session_id FROM sessions WHERE project_id = ? AND session_id = ?", [work.project_id, identity.sessionId]);
+    const existing = context.db.get("SELECT session_id, parent_session_id, provider_parent_session_id FROM sessions WHERE project_id = ? AND session_id = ?", [work.project_id, identity.sessionId]);
     if (existing && existing.parent_session_id && parentSession && existing.parent_session_id !== parentSession)
         throw new AppError("session_parent_conflict", "Observed Session already has a different immutable parent", 1, { session_id: identity.sessionId });
-    context.db.run(`INSERT INTO sessions (session_id, project_id, harness, provider_session_id, agent_id, parent_session_id, provider, model, reasoning, mode, agent_type, project_root, flow_kind, status, run_id, protocol_id, worker_id, workspace_path, continuation_policy, current_stage, next_action, last_action_hash, continuation_count, stop_reason, transcript_path, cwd, metadata_json, coverage_units_json, created_at, updated_at, stopped_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'vnext', 'active', ?, NULL, ?, ?, 'go_router', 'work', NULL, NULL, 0, NULL, ?, ?, '{}', '[]', ?, ?, NULL) ON CONFLICT(session_id, project_id) DO UPDATE SET harness = excluded.harness, provider_session_id = COALESCE(excluded.provider_session_id, provider_session_id), agent_id = COALESCE(excluded.agent_id, agent_id), parent_session_id = COALESCE(excluded.parent_session_id, parent_session_id), provider = COALESCE(excluded.provider, provider), model = COALESCE(excluded.model, model), reasoning = COALESCE(excluded.reasoning, reasoning), mode = COALESCE(excluded.mode, mode), agent_type = COALESCE(excluded.agent_type, agent_type), flow_kind = excluded.flow_kind, run_id = excluded.run_id, worker_id = excluded.worker_id, workspace_path = excluded.workspace_path, transcript_path = COALESCE(excluded.transcript_path, transcript_path), cwd = excluded.cwd, updated_at = excluded.updated_at`, [identity.sessionId, work.project_id, identity.harness, identity.providerSessionId, identity.agentId, existing?.parent_session_id ?? (parentSession === identity.sessionId ? null : parentSession), identity.provider, identity.model, identity.reasoning, identity.mode, identity.agentType, run.project_root, work.run_id, work.work_id, run.workspace_root, identity.transcriptPath, run.workspace_root, now, now]);
+    if (existing?.provider_parent_session_id && providerParentSession && existing.provider_parent_session_id !== providerParentSession)
+        throw new AppError("provider_session_parent_conflict", "Observed provider Session already has a different immutable provider parent", 1, { session_id: identity.sessionId });
+    context.db.run(`INSERT INTO sessions (session_id, project_id, harness, provider_session_id, provider_parent_session_id, agent_id, parent_session_id, provider, model, reasoning, mode, agent_type, project_root, flow_kind, status, run_id, protocol_id, worker_id, workspace_path, continuation_policy, current_stage, next_action, last_action_hash, continuation_count, stop_reason, transcript_path, cwd, metadata_json, coverage_units_json, created_at, updated_at, stopped_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'vnext', 'active', ?, NULL, ?, ?, 'go_router', 'work', NULL, NULL, 0, NULL, ?, ?, '{}', '[]', ?, ?, NULL) ON CONFLICT(session_id, project_id) DO UPDATE SET harness = excluded.harness, provider_session_id = COALESCE(excluded.provider_session_id, provider_session_id), provider_parent_session_id = COALESCE(excluded.provider_parent_session_id, provider_parent_session_id), agent_id = COALESCE(excluded.agent_id, agent_id), parent_session_id = COALESCE(excluded.parent_session_id, parent_session_id), provider = COALESCE(excluded.provider, provider), model = COALESCE(excluded.model, model), reasoning = COALESCE(excluded.reasoning, reasoning), mode = COALESCE(excluded.mode, mode), agent_type = COALESCE(excluded.agent_type, agent_type), flow_kind = excluded.flow_kind, run_id = excluded.run_id, worker_id = excluded.worker_id, workspace_path = excluded.workspace_path, transcript_path = COALESCE(excluded.transcript_path, transcript_path), cwd = excluded.cwd, updated_at = excluded.updated_at`, [identity.sessionId, work.project_id, identity.harness, identity.providerSessionId, providerParentSession, identity.agentId, existing?.parent_session_id ?? (parentSession === identity.sessionId ? null : parentSession), identity.provider, identity.model, identity.reasoning, identity.mode, identity.agentType, run.project_root, work.run_id, work.work_id, run.workspace_root, identity.transcriptPath, run.workspace_root, now, now]);
     reactivateBoundSession(context, work.project_id, identity.sessionId, now);
 }
+/** Register the trusted physical Session before a paused Work moves to it. */
+export function bindSessionForResume(context, workId, identity, now) {
+    const work = requireWork(context, workId);
+    if (work.status !== "paused")
+        throw new AppError("invalid_work_state", "Only a paused Work can bind a resume Session", 1, { work_id: work.work_id, status: work.status });
+    bindSession(context, work, requireRun(context, work.project_id, work.run_id), identity, now);
+}
 function reactivateBoundSession(context, projectId, sessionId, now) {
     context.db.run("UPDATE sessions SET status = 'active', stop_reason = NULL, stopped_at = NULL, updated_at = ? WHERE project_id = ? AND session_id = ?", [now, projectId, sessionId]);
 }
-function validateWorkResult(work, result, projectRoot, workspaceRoot, runId, resultPath) {
+function validateWorkResult(work, result, projectRoot, workspaceRoot, runHome, runId, resultPath) {
     if (!work.result_schema)
         return;
     if (!resultPath)
@@ -388,20 +420,35 @@ function validateWorkResult(work, result, projectRoot, workspaceRoot, runId, res
     catch {
         throw new AppError("validation", "Work result must be JSON for its declared result schema", 2, { work_id: work.work_id, result_schema: work.result_schema });
     }
-    fs.writeFileSync(resultPath, result);
-    validateSchema({ schemaName: work.result_schema.replace(/^dd-flow\//, "").replace(/@\d+$/, ""), file: resultPath, projectRoot, runId });
+    const candidate = `${resultPath}.candidate-${process.pid}`;
+    fs.writeFileSync(candidate, result);
+    try {
+        validateSchema({ schemaName: work.result_schema.replace(/^dd-flow\//, "").replace(/@\d+$/, ""), file: candidate, projectRoot, runId, runRoot: runHome });
+    }
+    finally {
+        fs.rmSync(candidate, { force: true });
+    }
     if (work.result_schema === "dd-flow/code-work-result@2")
-        validateCodeWorkResult(work, parsed, workspaceRoot);
+        validateCodeWorkResult(work, parsed, workspaceRoot, runHome, runId);
     if (work.result_schema === "dd-flow/code-review-result@1")
-        validateCodeReviewResultIdentity(work, parsed);
+        validateCodeReviewResult(work, parsed, { workspaceRoot, runHome, runId });
+    if (work.result_schema === "dd-flow/plan-review-result@1")
+        validatePlanReviewResult(work, parsed, { workspaceRoot, runHome, runId });
 }
-function validateCodeWorkResult(work, value, projectRoot) {
+function validateCodeWorkResult(work, value, projectRoot, runHome, runId) {
     const result = value;
     if ((result.deviations?.length ?? 0) > 0 || (result.blockers?.length ?? 0) > 0)
         throw new AppError("work_contract_incomplete", "CODE Work cannot complete with unresolved deviations or blockers; fail the Work and report the contract mismatch", 2, { work_id: work.work_id, deviations: result.deviations ?? [], blockers: result.blockers ?? [] });
     const packet = codePacket(work);
     if (!packet)
         return;
+    const acceptedCriteria = new Set(packet.acceptance.map((item) => item.criterion_id).filter((item) => typeof item === "string"));
+    for (const item of result.evidence ?? []) {
+        if (!item.criterion_id || !acceptedCriteria.has(item.criterion_id))
+            throw new AppError("evidence_criterion_unknown", "CODE Work evidence must reference an acceptance criterion assigned to this Work", 2, { work_id: work.work_id, criterion_id: item.criterion_id ?? null });
+        for (const ref of item.refs ?? [])
+            assertPortableArtifactRef(ref, { workspaceRoot: projectRoot, runHome, runId });
+    }
     const documentUpdates = (packet.document_updates ?? []);
     const changed = new Set(result.changed_paths ?? []);
     const missingDocuments = documentUpdates.map((entry) => entry.path).filter((entry) => !changed.has(entry));
@@ -411,33 +458,43 @@ function validateCodeWorkResult(work, value, projectRoot) {
         return true; const current = crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); return entry.action === "create" ? entry.baseline_sha256 !== null : current === entry.baseline_sha256; }).map((entry) => entry.path);
     if (unchangedDocuments.length)
         throw new AppError("document_update_not_materialized", "Assigned durable document updates must exist and differ from their PLAN baseline", 2, { work_id: work.work_id, unchanged_paths: unchangedDocuments });
-    const assigned = packet.repair?.review_finding_ids ?? [];
+    const assigned = packet.repair?.review_findings?.map((finding) => finding.finding_ref) ?? [];
     if (assigned.length) {
-        const resolved = new Set(result.resolved_finding_refs ?? []);
-        const missing = assigned.filter((finding) => !resolved.has(finding));
-        const unexpected = [...resolved].filter((finding) => !assigned.includes(finding));
-        if (missing.length || unexpected.length)
-            throw new AppError("review_repair_incomplete", "Review repair must explicitly resolve exactly its assigned finding references", 2, { work_id: work.work_id, missing, unexpected });
+        if ((result.changed_paths?.length ?? 0) === 0)
+            throw new AppError("review_repair_no_change", "Review repair must materialize a project change; a no-op cannot resolve a finding", 2, { work_id: work.work_id, findings: assigned });
+        validateReviewResolutions(work.work_id, assigned, result.resolutions ?? []);
+        for (const resolution of result.resolutions ?? [])
+            for (const ref of resolution.evidence_refs ?? [])
+                assertPortableArtifactRef(ref, { workspaceRoot: projectRoot, runHome, runId });
     }
 }
-function renderWorkerPrompt(context, work, run, dependencies, resultPath) {
+export function validateReviewResolutions(workId, assigned, resolutions) {
+    const resolved = new Set(resolutions.map((resolution) => resolution.finding_ref).filter((ref) => Boolean(ref)));
+    const missing = assigned.filter((finding) => !resolved.has(finding));
+    const unexpected = [...resolved].filter((finding) => !assigned.includes(finding));
+    const duplicate = resolutions.length !== resolved.size;
+    if (missing.length || unexpected.length || duplicate)
+        throw new AppError("review_repair_incomplete", "Review repair must include exactly one resolution for each assigned finding reference", 2, { work_id: workId, missing, unexpected, duplicate });
+}
+function renderWorkerPrompt(context, work, run, dependencies) {
     const command = flowCommand(context);
     const packet = codePacket(work);
-    const codeContext = packet ? ["<semantic_spine>", JSON.stringify(packet.semantic_spine, null, 2), "</semantic_spine>", "", ...(packet.repair ? ["<repair_context>", JSON.stringify(packet.repair, null, 2), "Read the failed receipt and its linked stdout/stderr before editing. Preserve the accepted origin context and fix only the evidenced failure.", "</repair_context>", ""] : []), "<accepted_requirements>", JSON.stringify(packet.requirements, null, 2), "</accepted_requirements>", "", "<acceptance_context>", "The criteria below are end-to-end context. Complete this Work's semantic contribution and declared checks; another ordered Work may own a different acceptance surface.", JSON.stringify(packet.acceptance, null, 2), "</acceptance_context>", "", "<required_read>", "These are mandatory starting sources, not a read allowlist. Read any additional project files needed to implement the Work correctly.", ...packet.required_read.map((item) => `- ${resolveRunReferences(item, work.run_id, requireRunHome(run))}`), "</required_read>", "", "<discovery_boundary>", "These are likely discovery areas, not a hard boundary. Expand project-local investigation when required and report material additions.", ...packet.discovery_boundary.map((item) => `- ${item}`), "</discovery_boundary>", "", "<planned_write_areas>", "SOFT COORDINATION HINT ONLY. These paths help the coordinator avoid concurrent collisions. They do not grant or deny write permission and do not limit the files needed for this Work. You may create or change any project file under workspace_root that is necessary and in semantic scope; report every actual changed path.", ...(packet.planned_write_areas.length ? packet.planned_write_areas.map((item) => `- ${item}`) : ["- none predicted; derive the necessary files from the task"]), "</planned_write_areas>", "", ...(packet.provides_checks.length ? ["<provided_checks>", ...packet.provides_checks.map((item) => `- ${item.id}: materialize ${item.command}${item.definition ? ` as ${item.definition}` : ""}; it is not usable until this Work finishes.`), "Update the declared project command or alias before Work finish. The CLI verifies the materialization and then executes the check.", "</provided_checks>", ""] : []), "<verification>", ...packet.checks.map((item) => `- ${item.id} at ${item.run_at}: ${item.command} — ${item.purpose}`), "The CLI executes work-scoped checks and retains their receipts. Report semantic evidence only; do not rerun declared checks manually.", "</verification>", "", "<stop_conditions>", ...packet.stop_conditions.map((item) => `- ${item}`), "</stop_conditions>", ""] : [];
+    const codeContext = packet ? ["<semantic_spine>", JSON.stringify(packet.semantic_spine, null, 2), "</semantic_spine>", "", ...(packet.repair ? ["<repair_context>", JSON.stringify(packet.repair, null, 2), "Read the failed receipt and its linked stdout/stderr before editing. Preserve the accepted origin context and fix only the evidenced failure.", "</repair_context>", ""] : []), "<accepted_requirements>", JSON.stringify(packet.requirements, null, 2), "</accepted_requirements>", "", "<write_boundary_invariant>", "For a mutation guarded by membership, ownership, authorization or parent lifecycle state, preserve that predicate in the write statement or make guard and write one explicit transaction with the needed lock. A prior read may diagnose an error but never proves a later write remains allowed. Apply this to create, update, delete and parent-state mutations.", "</write_boundary_invariant>", "", "<acceptance_context>", "The criteria below are end-to-end context. Complete this Work's semantic contribution and declared checks; another ordered Work may own a different acceptance surface.", JSON.stringify(packet.acceptance, null, 2), "</acceptance_context>", "", "<required_read>", "These are mandatory starting sources, not a read allowlist. Read any additional project files needed to implement the Work correctly.", ...packet.required_read.map((item) => `- ${resolveRunReferences(item, work.run_id, requireRunHome(run))}`), "</required_read>", "", "<discovery_boundary>", "These are likely discovery areas, not a hard boundary. Expand project-local investigation when required and report material additions.", ...packet.discovery_boundary.map((item) => `- ${item}`), "</discovery_boundary>", "", "<planned_write_areas>", "SOFT COORDINATION HINT ONLY. These paths help the coordinator avoid concurrent collisions. They do not grant or deny write permission and do not limit the files needed for this Work. You may create or change any project file under workspace_root that is necessary and in semantic scope; report every actual changed path.", ...(packet.planned_write_areas.length ? packet.planned_write_areas.map((item) => `- ${item}`) : ["- none predicted; derive the necessary files from the task"]), "</planned_write_areas>", "", ...(packet.provides_checks.length ? ["<provided_checks>", ...packet.provides_checks.map((item) => `- ${item.id}: materialize ${item.command}${item.definition ? ` as ${item.definition}` : ""}; it is not usable until this Work finishes.`), "Update the declared project command or alias before Work finish. The CLI verifies the materialization and then executes the check.", "</provided_checks>", ""] : []), "<verification>", ...packet.checks.map((item) => `- ${item.id} at ${item.run_at}: ${item.command} — ${item.purpose}`), "The CLI executes work-scoped checks and retains their receipts. Report semantic evidence only; do not rerun declared checks manually.", "</verification>", "", "<stop_conditions>", ...packet.stop_conditions.map((item) => `- ${item}`), "</stop_conditions>", ""] : [];
     if (packet)
         codeContext.push("<document_updates>", JSON.stringify(packet.document_updates, null, 2), "Materialize every listed update. dd-flow verifies the resulting file against its PLAN-time baseline.", "</document_updates>", "", "<completion_contract>", "Successful completion requires empty deviations and blockers and every assigned document update in changed_paths. A necessary path outside planned_write_areas is normal coordination drift, not a blocker; include it in changed_paths and continue.", "</completion_contract>", "");
-    return ["<work>", `- work_id: ${work.work_id}`, `- run_id: ${work.run_id}`, `- project_root: ${run.project_root}`, `- workspace_root: ${run.workspace_root}`, `- run_home: ${requireRunHome(run)}`, "</work>", "", "<hard_write_boundary>", `HARD RULE: all project reads and writes must remain under ${run.workspace_root}.`, "Do not write through project_root, outside workspace_root, into another RUN, or into Git/worktree control data. Do not create, switch, merge or delete branches/worktrees.", "Accepted requirements, non-goals and stop_conditions are semantic hard boundaries. planned_write_areas is not.", "</hard_write_boundary>", "", ...codeContext, "<dependency_results>", JSON.stringify(dependencies.filter(Boolean), null, 2), "</dependency_results>", "", "<task>", resolveRunReferences(work.task, work.run_id, requireRunHome(run)), "</task>", "", ...(work.result_schema ? ["<result_contract>", `Return JSON matching \`${work.result_schema}\`.`, ...resultSchemaGuidance(work), `Write it to ${resultPath}.`, "</result_contract>", ""] : []), "<completion>", "The CLI runs every declared required check before accepting this Work. A failed receipt means only that the check failed; it is not proof of an engine, harness, dependency, or environment blocker.", "Read the failed receipt and its stdout/stderr. Fix project-owned source, migration, test, formatting, or configuration errors in this same Work, then call Finish again. Do not invent a cause that does not appear in the retained output.", "Use Fail only for a concrete external blocker after deterministic bootstrap or a contradiction with an accepted requirement/non-goal. Never fail merely because a necessary project path was absent from planned_write_areas.", "Finish may run for several minutes. Preserve the shell tool's process/session handle and poll that same invocation until it exits; progress arrives as JSONL on stderr. Never reissue Finish merely because final stdout has not arrived.", `Finish as one standalone command: ${command} work finish ${work.work_id} --result-file ${JSON.stringify(resultPath)} --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`, `Fail only for an evidenced external or semantic-contract blocker: ${command} work fail ${work.work_id} --reason "receipt path + exact external or semantic blocker" --project-root ${JSON.stringify(run.project_root)} --json`, "</completion>", ""].join("\n");
+    return ["<work>", `- work_id: ${work.work_id}`, `- run_id: ${work.run_id}`, `- project_root: ${run.project_root}`, `- workspace_root: ${run.workspace_root}`, `- run_home: ${requireRunHome(run)}`, "</work>", "", "<hard_write_boundary>", `HARD RULE: project source reads and writes must remain under ${run.workspace_root}.`, "Do not write through project_root, outside workspace_root, into another RUN, or into Git/worktree control data. Do not create, switch, merge or delete branches/worktrees.", "RUN artifacts are read-only evidence: refer to them with run:// URIs and let dd-flow persist your submitted result. Accepted requirements, non-goals and stop_conditions are semantic hard boundaries. planned_write_areas is not.", "</hard_write_boundary>", "", ...codeContext, "<dependency_results>", JSON.stringify(dependencies.filter(Boolean), null, 2), "</dependency_results>", "", "<task>", resolveRunReferences(work.task, work.run_id, requireRunHome(run)), "</task>", "", ...(work.result_schema ? ["<result_contract>", `Return JSON matching \`${work.result_schema}\`.`, ...resultSchemaGuidance(work, run.id), "Do not create result.json yourself. Send the JSON to dd-flow on stdin; it atomically validates and stores the canonical receipt.", "</result_contract>", ""] : []), "<completion>", "The CLI runs every declared required check before accepting this Work. A failed receipt means only that the check failed; it is not proof of an engine, harness, dependency, or environment blocker.", "Read the failed receipt and its stdout/stderr. Fix project-owned source, migration, test, formatting, or configuration errors in this same Work, then call Finish again. Do not invent a cause that does not appear in the retained output.", "Use Fail only for a concrete external blocker after deterministic bootstrap or a contradiction with an accepted requirement/non-goal. Never fail merely because a necessary project path was absent from planned_write_areas.", "Finish may run for several minutes. Preserve the shell tool's process/session handle and poll that same invocation until it exits; progress arrives as JSONL on stderr. Never reissue Finish merely because final stdout has not arrived.", `Finish as one standalone command, piping your JSON object to stdin: ${command} work finish ${work.work_id} --result-stdin --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`, `Fail only for an evidenced external or semantic-contract blocker: ${command} work fail ${work.work_id} --reason "receipt path + exact external or semantic blocker" --project-root ${JSON.stringify(run.project_root)} --json`, "</completion>", ""].join("\n");
 }
-function resultSchemaGuidance(work) {
+function resultSchemaGuidance(work, runId) {
     const schema = work.result_schema;
+    const refs = `Evidence refs for project source are relative to workspace_root; RUN evidence uses run://${runId}/path/to/artifact.`;
     if (schema === "dd-flow/code-work-result@2")
-        return ["Use this complete minimal shape. For a review repair, also include resolved_finding_refs with exactly the finding references assigned in repair_context:", "```json", JSON.stringify({ schema_id: schema, summary: "What was implemented.", changed_paths: ["project-relative/path"], evidence: [{ criterion_id: "AC-001", refs: ["project-relative/evidence"] }], deviations: [], blockers: [], resolved_finding_refs: [] }, null, 2), "```"];
+        return [refs, "Use this complete minimal shape. For a review repair, include exactly one resolution per assigned finding; explain what changed and cite evidence that demonstrates the required outcome:", "```json", JSON.stringify({ schema_id: schema, summary: "What was implemented.", changed_paths: ["project-relative/path"], evidence: [{ criterion_id: "AC-001", refs: ["project-relative/evidence", `run://${runId}/05-code/checks/receipt.json`] }], deviations: [], blockers: [], resolutions: [{ finding_ref: "WRK-000/FIND-001", summary: "How the required outcome was achieved.", evidence_refs: ["project-relative/evidence"] }] }, null, 2), "```"];
     if (schema === "dd-flow/code-review-result@1") {
-        return ["Assess every assigned aspect exactly once. Number findings locally inside this reviewer Work as FIND-001, FIND-002, ...; dd-flow adds the Work id to form the canonical reference.", "Use this complete minimal shape. Report only material, direct-evidence findings; taste and cosmetics are not findings:", "```json", JSON.stringify({ schema_id: schema, verdict: "pass | findings | blocked", summary: "Concise evidence-backed conclusion.", aspects: [{ aspect_id: "assigned_aspect_id", verdict: "pass | findings | blocked", summary: "Conclusion.", evidence_refs: ["path/to/file"] }], findings: [{ finding_id: "FIND-001", aspect_id: "assigned_aspect_id", priority: "p0 | p1 | p2 | p3", problem: "Violated obligation or rule.", impact: "Concrete risk or failure.", evidence_refs: ["path/to/file"], obligation_refs: ["R-001 | AC-001 | policy ref"] }] }, null, 2), "```"];
+        return [refs, "Assess every assigned aspect exactly once. Number findings locally inside this reviewer Work as FIND-001, FIND-002, ...; dd-flow adds the Work id to form the canonical reference.", "Use this complete minimal shape. Report only material, direct-evidence findings; taste and cosmetics are not findings:", "```json", JSON.stringify({ schema_id: schema, verdict: "pass | findings | blocked", summary: "Concise evidence-backed conclusion.", aspects: [{ aspect_id: "assigned_aspect_id", verdict: "pass | findings | blocked", summary: "Conclusion.", evidence_refs: ["path/to/file", `run://${runId}/05-code/checks/receipt.json`] }], findings: [{ finding_id: "FIND-001", aspect_id: "assigned_aspect_id", priority: "p0 | p1 | p2 | p3", problem: "Violated obligation or rule.", impact: "Concrete risk or failure.", required_outcome: "Smallest observable result that closes the defect.", evidence_refs: ["path/to/file"], obligation_refs: ["R-001 | AC-001 | policy ref"] }] }, null, 2), "```"];
     }
     if (schema !== "dd-flow/plan-review-result@1")
         return [];
-    return ["Use this complete minimal shape; do not add fields. Number findings locally inside this reviewer Work as FIND-001, FIND-002, ...; dd-flow adds the Work id when the coordinator classifies them:", "```json", JSON.stringify({ schema_id: schema, plan_revision: 1, overall_verdict: "pass | watch | needs_changes | blocked", summary: "Concise evidence-backed conclusion.", aspects: [{ aspect_id: "assigned_aspect_id", verdict: "pass | watch | needs_changes | blocked", summary: "Conclusion for this aspect.", evidence_refs: ["path/to/file"], findings: [{ finding_id: "FIND-001", severity: "high | medium | low | info", summary: "Problem, if any.", evidence_refs: ["path/to/file"] }] }] }, null, 2), "```"];
+    return [refs, "Use this complete minimal shape; do not add fields. Number findings locally inside this reviewer Work as FIND-001, FIND-002, ...; dd-flow adds the Work id when the coordinator classifies them:", "```json", JSON.stringify({ schema_id: schema, plan_revision: 1, overall_verdict: "pass | watch | needs_changes | blocked", summary: "Concise evidence-backed conclusion.", aspects: [{ aspect_id: "assigned_aspect_id", verdict: "pass | watch | needs_changes | blocked", summary: "Conclusion for this aspect.", evidence_refs: ["path/to/file", `run://${runId}/03-plan/plan.json`], findings: [{ finding_id: "FIND-001", severity: "high | medium | low | info", summary: "Problem, if any.", evidence_refs: ["path/to/file"] }] }] }, null, 2), "```"];
 }
 export function validateCodeReviewResultIdentity(work, value) {
     const group = codeReviewGroup(work);
@@ -458,6 +515,57 @@ export function validateCodeReviewResultIdentity(work, value) {
         throw new AppError("review_evidence_invalid", "CODE reviewer finding ids must be local FIND-NNN ids and aspect refs must stay inside the assigned review group", 2, { work_id: work.work_id, group: group.key, required_format: "FIND-NNN", invalid, wrong_aspect: wrongAspect });
     }
 }
+/**
+ * CODE review evidence is part of the Work contract, not a late stage-level
+ * concern.  Reject it before `works.result` becomes authoritative so a later
+ * fan-in cannot discover a malformed accepted reviewer result.
+ */
+function validateCodeReviewResult(work, value, input) {
+    validateCodeReviewResultIdentity(work, value);
+    const result = value;
+    const findings = result.findings ?? [];
+    // A reviewer is a child Work and cannot pause its coordinator-owned Stage.
+    // Its structured blocked result is evidence for the coordinator, which then
+    // either resolves the gap or pauses the Stage itself.
+    if ((result.verdict === "pass" && findings.length > 0) || (result.verdict === "findings" && findings.length === 0)) {
+        throw new AppError("review_evidence_invalid", "CODE reviewer verdict must agree with whether material findings are present", 2, { work_id: work.work_id, verdict: result.verdict, findings: findings.length });
+    }
+    const references = [
+        ...(result.aspects ?? []).flatMap((aspect) => Array.isArray(aspect.evidence_refs) ? aspect.evidence_refs : []),
+        ...(result.findings ?? []).flatMap((finding) => Array.isArray(finding.evidence_refs) ? finding.evidence_refs : [])
+    ];
+    for (const ref of references) {
+        if (typeof ref !== "string")
+            throw new AppError("review_evidence_invalid", "CODE reviewer evidence references must be strings", 2, { work_id: work.work_id, ref });
+        assertPortableArtifactRef(ref, input);
+    }
+}
+export function validatePlanReviewResult(work, value, input) {
+    const group = codeReviewGroup(work);
+    if (!group)
+        throw new AppError("review_evidence_invalid", "PLAN reviewer Work has no assigned review group", 2, { work_id: work.work_id });
+    const result = value;
+    const aspects = result.aspects ?? [];
+    const ids = aspects.map((item) => item.aspect_id ?? "");
+    const expected = new Set(group.aspect_ids);
+    const missing = group.aspect_ids.filter((id) => !ids.includes(id));
+    const unexpected = ids.filter((id) => !expected.has(id));
+    if (new Set(ids).size !== ids.length || missing.length || unexpected.length)
+        throw new AppError("review_evidence_invalid", "PLAN reviewer result must assess every assigned aspect exactly once", 2, { work_id: work.work_id, group: group.key, missing, unexpected });
+    const findingIds = aspects.flatMap((aspect) => aspect.findings ?? []).map((finding) => finding.finding_id ?? "");
+    const invalid = findingIds.filter((id) => !/^FIND-\d{3}$/.test(id));
+    if (new Set(findingIds).size !== findingIds.length || invalid.length)
+        throw new AppError("review_evidence_invalid", "PLAN reviewer finding ids must be unique local FIND-NNN ids", 2, { work_id: work.work_id, invalid });
+    const refs = aspects.flatMap((aspect) => [
+        ...(Array.isArray(aspect.evidence_refs) ? aspect.evidence_refs : []),
+        ...(aspect.findings ?? []).flatMap((finding) => Array.isArray(finding.evidence_refs) ? finding.evidence_refs : [])
+    ]);
+    for (const ref of refs) {
+        if (typeof ref !== "string")
+            throw new AppError("review_evidence_invalid", "PLAN reviewer evidence references must be strings", 2, { work_id: work.work_id, ref });
+        assertPortableArtifactRef(ref, input);
+    }
+}
 function codeReviewGroup(work) {
     const payload = parsePayload(work);
     const group = payload?.group;
@@ -472,10 +580,10 @@ function requireWork(context, id) { ensureWorkRegistry(context); const exact = c
     return exact; if (!/^WRK-\d{3,}$/.test(id))
     throw new AppError("not_found", "Work is not registered", 1, { work_id: id }); const matches = context.db.all(`SELECT ${workColumns} FROM works WHERE work_id LIKE ? ORDER BY work_id`, [`${id}-%`]); if (matches.length !== 1)
     throw new AppError(matches.length ? "ambiguous_work_alias" : "not_found", matches.length ? "Short Work alias is ambiguous" : "Work is not registered", 1, { work_id: id, matches: matches.map((work) => work.work_id) }); return matches[0]; }
-function requireRun(context, projectId, runId) { const run = context.db.get("SELECT r.id, r.run_home_path, r.workspace_root, p.root AS project_root FROM runs r JOIN projects p ON p.id = r.project_id WHERE r.project_id = ? AND r.id = ?", [projectId, runId]); if (!run?.run_home_path)
-    throw new AppError("runtime_missing", "RUN workspace is unavailable", 1, { run_id: runId }); return run; }
-function requireRunHome(run) { if (!run.run_home_path)
-    throw new AppError("runtime_missing", "RUN workspace is unavailable", 1, { run_id: run.id }); return run.run_home_path; }
+function requireRun(context, projectId, runId) { const run = context.db.get("SELECT r.id, r.run_root, r.workspace_root, p.root AS project_root FROM runs r JOIN projects p ON p.id = r.project_id WHERE r.project_id = ? AND r.id = ?", [projectId, runId]); if (!run?.run_root)
+    throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1, { run_id: runId }); return run; }
+function requireRunHome(run) { if (!run.run_root)
+    throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1, { run_id: run.id }); return run.run_root; }
 function parseDependencies(work) { try {
     const value = JSON.parse(work.depends_on_json);
     return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : [];
@@ -505,20 +613,22 @@ function validateItem(value, requireExecutionContext = false) { if (!value || ty
     throw new AppError("validation", "work item must be an object", 2); const item = value; if (typeof item.key !== "string" || !item.key || typeof item.task !== "string" || !item.task.trim())
     throw new AppError("validation", "work item requires key and task", 2); const code = item.schema_id === "dd-flow/code-work-packet@5"; if (requireExecutionContext && !code)
     throw new AppError("validation", "CODE batch requires code-work-packet@5 items", 2, { key: item.key }); for (const key of code ? ["required_read", "discovery_boundary", "planned_write_areas", "checks", "provides_checks", "stop_conditions"] : [])
-    if (!Array.isArray(item[key]) || (!['provides_checks', 'planned_write_areas'].includes(key) && item[key].length === 0))
+    if (!Array.isArray(item[key]) || (!['provides_checks', 'planned_write_areas', 'checks'].includes(key) && item[key].length === 0) || (key === "checks" && item[key].length === 0 && !allowsEmptyRepairChecks(item)))
         throw new AppError("validation", `CODE work item requires ${['provides_checks', 'planned_write_areas'].includes(key) ? "an array" : `non-empty ${key}`}`, 2, { key: item.key }); if (item.depends_on !== undefined && (!Array.isArray(item.depends_on) || !item.depends_on.every((entry) => typeof entry === "string")))
     throw new AppError("validation", "depends_on must be a string array", 2); if (item.parent !== undefined && typeof item.parent !== "string")
     throw new AppError("validation", "parent must be a string", 2); if (item.launch_policy !== undefined && item.launch_policy !== "reuse_allowed" && item.launch_policy !== "fresh_agent_required")
     throw new AppError("validation", "launch_policy must be reuse_allowed or fresh_agent_required", 2); if (item.result_schema !== undefined && (typeof item.result_schema !== "string" || !item.result_schema))
     throw new AppError("validation", "result_schema must be a non-empty schema id", 2); const payload = code ? item : (item.payload && typeof item.payload === "object" && !Array.isArray(item.payload) ? item.payload : undefined); return { key: item.key, task: item.task, ...(Array.isArray(item.depends_on) ? { depends_on: item.depends_on } : {}), ...(typeof item.parent === "string" ? { parent: item.parent } : {}), ...(typeof item.launch_policy === "string" ? { launch_policy: item.launch_policy } : {}), ...(typeof item.result_schema === "string" ? { result_schema: item.result_schema } : {}), ...(payload ? { payload } : {}) }; }
+function allowsEmptyRepairChecks(item) { const repair = item.repair; if (!repair || typeof repair !== "object" || Array.isArray(repair))
+    return false; const value = repair; return typeof value.check_receipt_id === "string" || (Array.isArray(value.review_findings) && value.review_findings.some((finding) => typeof finding === "object" && finding !== null && Array.isArray(finding.check_refs) && finding.check_refs.some((ref) => typeof ref === "string"))) || (Array.isArray(value.semantic_unresolved) && value.semantic_unresolved.some((item) => typeof item === "string")); }
 function readJson(file) { try {
     return JSON.parse(fs.readFileSync(path.resolve(file), "utf8"));
 }
 catch (error) {
     throw new AppError("validation", `Invalid JSON file: ${String(error)}`, 2, { file });
 } }
-export function refreshRunWorkProjection(context, projectId, runId) { refreshRunSessionProjection(context, projectId, runId); const run = context.db.get("SELECT run_home_path FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]); if (run?.run_home_path) {
-    const obsolete = path.join(run.run_home_path, "work.json");
+export function refreshRunWorkProjection(context, projectId, runId) { refreshRunSessionProjection(context, projectId, runId); const run = context.db.get("SELECT run_root FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]); if (run?.run_root) {
+    const obsolete = path.join(run.run_root, "work.json");
     if (fs.existsSync(obsolete))
         fs.rmSync(obsolete);
 } }

package/dist/storage/database.js

@@ -1,10 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
 import { createRequire } from "node:module";
 import { ensureDir } from "./paths.js";
 import { AppError } from "../shared/errors.js";
 const require = createRequire(import.meta.url);
 const { DatabaseSync } = require("node:sqlite");
+const resourceDatabases = new Map();
 /** Creates the single Work/Session authority used by a fresh vNext beta runtime. */
 export function ensureVnextWorkStorage(db) {
     const legacy = db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('vnext_works', 'vnext_agent_turns', 'flow_agent_turns') LIMIT 1");
@@ -94,7 +96,7 @@ export function getDatabase(ddFlowHome, mode = "initialize") {
     // Internal additive schema changes must be available to every write command.
     // Higher-level Memory Bank migrations remain explicit in services/migrations.
     if (mode !== "read_existing")
-        migrate(db);
+        migrate(db, dbPath);
     if (mode === "read_existing")
         db.exec("PRAGMA query_only = ON");
     db.exec("PRAGMA foreign_keys = ON");
@@ -108,6 +110,72 @@ export function getDatabase(ddFlowHome, mode = "initialize") {
         all: (sql, params = []) => db.prepare(sql).all(...params)
     };
 }
+/**
+ * Opens the small host-wide resource registry.  It is intentionally separate
+ * from a RUN database: a process or a port can outlive the CLI client that
+ * created it, while a RUN database belongs to one flow home.
+ */
+export function getResourceDatabase(resourceHome) {
+    ensureDir(resourceHome);
+    const dbPath = path.join(resourceHome, "runtime.sqlite");
+    const cached = resourceDatabases.get(dbPath);
+    if (cached)
+        return cached;
+    const db = new DatabaseSync(dbPath);
+    configureDatabase(db, "initialize");
+    db.exec("PRAGMA foreign_keys = ON");
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS managed_processes (
+      id TEXT PRIMARY KEY,
+      kind TEXT NOT NULL,
+      pid INTEGER,
+      pid_started_at TEXT,
+      owner_id TEXT NOT NULL,
+      lease_token TEXT NOT NULL,
+      lease_expires_at TEXT NOT NULL,
+      project_id TEXT,
+      run_id TEXT,
+      work_id TEXT,
+      check_id TEXT,
+      operation_id TEXT,
+      stdout_path TEXT,
+      stderr_path TEXT,
+      state TEXT NOT NULL,
+      started_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      finished_at TEXT,
+      termination_reason TEXT,
+      metadata_json TEXT NOT NULL DEFAULT '{}'
+    );
+    CREATE INDEX IF NOT EXISTS idx_managed_processes_lease
+      ON managed_processes(state, lease_expires_at, updated_at);
+    CREATE TABLE IF NOT EXISTS managed_resources (
+      resource_kind TEXT NOT NULL,
+      resource_key TEXT NOT NULL,
+      owner_id TEXT NOT NULL,
+      lease_token TEXT NOT NULL,
+      lease_expires_at TEXT NOT NULL,
+      process_id TEXT,
+      metadata_json TEXT NOT NULL DEFAULT '{}',
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY(resource_kind, resource_key)
+    );
+    CREATE INDEX IF NOT EXISTS idx_managed_resources_lease
+      ON managed_resources(lease_expires_at, updated_at);
+  `);
+    const database = {
+        path: dbPath,
+        writable: true,
+        close: () => { resourceDatabases.delete(dbPath); db.close?.(); },
+        exec: (sql) => db.exec(sql),
+        run: (sql, params = []) => db.prepare(sql).run(...params),
+        get: (sql, params = []) => db.prepare(sql).get(...params),
+        all: (sql, params = []) => db.prepare(sql).all(...params)
+    };
+    resourceDatabases.set(dbPath, database);
+    return database;
+}
 function emptyReadOnlyDatabase(dbPath) {
     return {
         path: dbPath,
@@ -125,7 +193,7 @@ function configureDatabase(db, mode) {
         db.exec("PRAGMA synchronous = NORMAL");
     }
 }
-function migrate(db) {
+function migrate(db, dbPath) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS projects (
       id TEXT PRIMARY KEY,
@@ -351,6 +419,7 @@ function migrate(db) {
       project_id TEXT NOT NULL,
       harness TEXT NOT NULL DEFAULT 'codex-desktop',
       provider_session_id TEXT,
+      provider_parent_session_id TEXT,
       agent_id TEXT,
       parent_id TEXT,
       provider TEXT,
@@ -495,6 +564,7 @@ function migrate(db) {
       target_branch TEXT NOT NULL,
       enqueue_target_head TEXT,
       execution_target_head TEXT,
+      accepted_tree TEXT,
       integration_commit TEXT,
       execution_route TEXT NOT NULL,
       status TEXT NOT NULL,
@@ -713,6 +783,7 @@ function migrate(db) {
     ensureColumn(db, "sessions", "metadata_json", "ALTER TABLE sessions ADD COLUMN metadata_json TEXT NOT NULL DEFAULT '{}'");
     ensureColumn(db, "sessions", "run_id", "ALTER TABLE sessions ADD COLUMN run_id TEXT");
     ensureColumn(db, "sessions", "provider_session_id", "ALTER TABLE sessions ADD COLUMN provider_session_id TEXT");
+    ensureColumn(db, "sessions", "provider_parent_session_id", "ALTER TABLE sessions ADD COLUMN provider_parent_session_id TEXT");
     ensureColumn(db, "sessions", "harness", "ALTER TABLE sessions ADD COLUMN harness TEXT NOT NULL DEFAULT 'codex-desktop'");
     ensureColumn(db, "sessions", "agent_id", "ALTER TABLE sessions ADD COLUMN agent_id TEXT");
     ensureColumn(db, "sessions", "provider", "ALTER TABLE sessions ADD COLUMN provider TEXT");
@@ -727,6 +798,7 @@ function migrate(db) {
     ensureColumn(db, "sessions", "plan_item_id", "ALTER TABLE sessions ADD COLUMN plan_item_id TEXT");
     ensureColumn(db, "sessions", "session_kind", "ALTER TABLE sessions ADD COLUMN session_kind TEXT");
     ensureColumn(db, "sessions", "coverage_units_json", "ALTER TABLE sessions ADD COLUMN coverage_units_json TEXT NOT NULL DEFAULT '[]'");
+    migrateSessionStorageKeys(db, dbPath);
     ensureColumn(db, "usage", "cache_read_input_tokens", "ALTER TABLE usage ADD COLUMN cache_read_input_tokens INTEGER");
     ensureColumn(db, "usage", "cache_write_input_tokens", "ALTER TABLE usage ADD COLUMN cache_write_input_tokens INTEGER");
     ensureColumn(db, "usage", "uncached_input_tokens", "ALTER TABLE usage ADD COLUMN uncached_input_tokens INTEGER");
@@ -737,6 +809,8 @@ function migrate(db) {
     db.prepare("UPDATE usage SET cache_read_input_tokens = cached_input_tokens WHERE cache_read_input_tokens IS NULL AND cached_input_tokens IS NOT NULL").run();
     ensureColumn(db, "runs", "run_home_path", "ALTER TABLE runs ADD COLUMN run_home_path TEXT");
     ensureColumn(db, "runs", "run_root", "ALTER TABLE runs ADD COLUMN run_root TEXT");
+    db.prepare("UPDATE runs SET run_root = COALESCE(run_root, run_home_path, run_dir) WHERE run_root IS NULL OR run_root = ''").run();
+    ensureColumn(db, "merge_requests", "accepted_tree", "ALTER TABLE merge_requests ADD COLUMN accepted_tree TEXT");
     ensureColumn(db, "runs", "layout_version", "ALTER TABLE runs ADD COLUMN layout_version TEXT");
     ensureColumn(db, "runs", "artifact_root_kind", "ALTER TABLE runs ADD COLUMN artifact_root_kind TEXT");
     ensureColumn(db, "works", "payload_json", "ALTER TABLE works ADD COLUMN payload_json TEXT");
@@ -783,6 +857,58 @@ function migrate(db) {
       ON runs(short_id);
   `);
 }
+/**
+ * Older builds used public or `harness:native` strings as foreign keys.  Move
+ * those keys once to an opaque storage key while preserving the original
+ * native value in provider_session_id.  We deliberately never split a native
+ * value on `:`: rows without a recorded provider ID remain untouched and are
+ * reported by normal preflight instead of guessed.
+ */
+function migrateSessionStorageKeys(db, dbPath) {
+    const rows = db.prepare("SELECT project_id, session_id, harness, provider_session_id, parent_session_id FROM sessions WHERE provider_session_id IS NOT NULL").all();
+    const changed = rows.map((row) => ({ ...row, next: storageSessionKey(row.harness, row.provider_session_id) })).filter((row) => row.session_id !== row.next);
+    if (changed.length === 0)
+        return;
+    // This is the only non-additive storage migration.  `VACUUM INTO` captures
+    // a consistent SQLite snapshot (including WAL state) before keys change.
+    if (dbPath && fs.existsSync(dbPath)) {
+        const backup = `${dbPath}.pre-session-key-v1-${Date.now()}.sqlite`;
+        db.exec(`VACUUM INTO '${backup.replace(/'/g, "''")}'`);
+    }
+    const duplicate = new Set();
+    for (const row of changed) {
+        const key = `${row.project_id}\0${row.next}`;
+        if (duplicate.has(key) || db.prepare("SELECT 1 FROM sessions WHERE project_id = ? AND session_id = ? AND session_id <> ?").get(row.project_id, row.next, row.session_id)) {
+            throw new AppError("session_identity_migration_conflict", "Cannot migrate ambiguous harness/native Session identity", 1, { project_id: row.project_id, harness_id: row.harness, session_id: row.provider_session_id });
+        }
+        duplicate.add(key);
+    }
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        // First update references. Session rows themselves are updated afterwards,
+        // so every dependent row remains resolvable throughout the transaction.
+        for (const row of changed) {
+            db.prepare("UPDATE work_sessions SET session_id = ? WHERE session_id = ? AND work_id IN (SELECT work_id FROM works WHERE project_id = ?)").run(row.next, row.session_id, row.project_id);
+            db.prepare("UPDATE flow_session_segments SET session_id = ? WHERE project_id = ? AND session_id = ?").run(row.next, row.project_id, row.session_id);
+            db.prepare("UPDATE usage SET session_id = ? WHERE project_id = ? AND session_id = ?").run(row.next, row.project_id, row.session_id);
+            const parameters = [row.next, row.project_id, row.session_id];
+            db.prepare("UPDATE hook_events SET session_id = ? WHERE project_id = ? AND session_id = ?").run(...parameters);
+            db.prepare("UPDATE flow_jobs SET worker_session_id = ? WHERE project_id = ? AND worker_session_id = ?").run(...parameters);
+            db.prepare("UPDATE merge_queue SET claimed_by_session_id = ? WHERE project_id = ? AND claimed_by_session_id = ?").run(...parameters);
+            db.prepare("UPDATE sessions SET parent_session_id = ? WHERE project_id = ? AND parent_session_id = ?").run(...parameters);
+            db.prepare("UPDATE sessions SET session_id = ? WHERE project_id = ? AND session_id = ?").run(...parameters);
+        }
+        db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_sessions_harness_native ON sessions(project_id, harness, provider_session_id) WHERE provider_session_id IS NOT NULL");
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+function storageSessionKey(harness, native) {
+    return `SES-${crypto.createHash("sha256").update(harness).update("\0").update(native).digest("hex").slice(0, 24)}`;
+}
 function migrateProjectScopedIdentity(db) {
     const protocolColumns = db.prepare("PRAGMA table_info(protocols)").all();
     const legacyGlobalPrimaryKey = protocolColumns.some((column) => column.name === "id" && column.pk === 1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.9.0-beta.1",
+  "version": "0.9.0-beta.11",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {