@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.151

package/dist/services/dashboard.js

@@ -1,10 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { commandResult } from '../harness-runtime/lib/process-json.mjs';
+import { SETUP_STARTUP_MS } from '../harness-runtime/lib/setup-progress.mjs';
 import { isActiveProtocolStatus, isActiveQueueStatus, isQueueHistoryStatus } from "../domain/contracts.js";
 import { AppError } from "../shared/errors.js";
-import { ensureDir, resolveProjectRoot } from "../storage/paths.js";
-import { dashboardMarkdownPath, globalDashboardHtmlPath, globalDashboardJsonPath, globalDashboardMarkdownPath, projectDashboardHtmlPath, projectDashboardJsonPath, projectSummaryJsonPath, protocolDashboardHtmlPath, protocolDashboardJsonPath, readProjectConfig } from "./config.js";
+import { prepareOutputFile } from "../cli/input-preparation.js";
+import { ensureDir, resolveProjectRoot, resolveProtocolPlanPath } from "../storage/paths.js";
+import { dashboardMarkdownPath, globalDashboardHtmlPath, globalDashboardJsonPath, globalDashboardMarkdownPath, projectDashboardHtmlPath, projectDashboardJsonPath, projectDashboardDir, projectSummaryJsonPath, protocolDashboardHtmlPath, protocolDashboardJsonPath, readProjectConfig } from "./config.js";
 import { queueForProject } from "./merge-queue.js";
 import { publishProjectSummary } from "./project-summary.js";
 import { requireProjectByRoot } from "./projects.js";
@@ -13,70 +15,82 @@ import { activeFlowSessionsForProject } from "./sessions.js";
 import { usageForRun } from "./usage.js";
 import { normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
 import { planSummary, planWithProgress } from "./plan-runtime.js";
-export function getCmuxStatus(context, input) {
+export async function getCmuxStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    return { ok: true, project_root: project.root, cmux: detectCmux(context) };
+    return { ok: true, project_root: project.root, cmux: await detectCmux(context) };
 }
-export function renderDashboard(context, input) {
+export function prepareDashboardRender(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    if (projectRecoveryGuarded(context, project.id))
+        throw new AppError("run_recovery_guarded", "Project dashboard is frozen while its RUN is retained for recovery", 1);
     const format = parseDashboardFormat(input.format);
+    if (input.protocol)
+        requireProtocol(context, input.protocol, project.id);
+    const config = readProjectConfig(context, project.id);
+    const output = input.output
+        ? path.resolve(project.root, input.output)
+        : format === "html"
+            ? input.protocol ? protocolDashboardHtmlPath(context, project.id, input.protocol) : projectDashboardHtmlPath(context, project.id)
+            : dashboardMarkdownPath(project.root, config);
+    prepareOutputFile(output);
+    if (format === "html")
+        prepareOutputFile(input.protocol ? protocolDashboardJsonPath(context, project.id, input.protocol) : projectDashboardJsonPath(context, project.id));
+    return { project, format, output };
+}
+export function renderDashboard(context, input) {
+    const { project, format, output } = prepareDashboardRender(context, input);
     if (format === "html") {
         if (input.protocol) {
             return renderProtocolDashboardHtml(context, project, input.protocol, input.output);
         }
         return renderProjectDashboardHtml(context, project, input.output);
     }
-    const config = readProjectConfig(context, project.id);
-    const output = input.output
-        ? path.resolve(path.isAbsolute(input.output) ? input.output : path.join(project.root, input.output))
-        : dashboardMarkdownPath(project.root, config);
     const markdown = renderProjectDashboardMarkdown(context, project, output);
     writeMarkdown(output, markdown);
     return { ok: true, project_root: project.root, dashboard: { path: output, bytes: Buffer.byteLength(markdown) } };
 }
-export function renderGlobalDashboard(context, input = {}) {
+export function prepareGlobalDashboardRender(context, input = {}) {
     const format = parseDashboardFormat(input.format);
+    const output = input.output ? path.resolve(input.output) : format === "html" ? globalDashboardHtmlPath(context) : globalDashboardMarkdownPath(context);
+    prepareOutputFile(output);
+    if (format === "html")
+        prepareOutputFile(globalDashboardJsonPath(context));
+    return { format, output };
+}
+export function renderGlobalDashboard(context, input = {}) {
+    const { format, output } = prepareGlobalDashboardRender(context, input);
     if (format === "html") {
         return renderGlobalDashboardHtml(context, input.output);
     }
-    const output = input.output
-        ? path.resolve(input.output)
-        : globalDashboardMarkdownPath(context);
     const markdown = renderGlobalDashboardMarkdown(context, output);
     writeMarkdown(output, markdown);
     return { ok: true, dashboard: { path: output, bytes: Buffer.byteLength(markdown) } };
 }
-export function openDashboard(context, input) {
+export async function openDashboard(context, input) {
+    prepareDashboardOptions(input);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const config = readProjectConfig(context, project.id);
     const format = parseDashboardFormat(input.format, "html");
-    if (input.viewer && input.viewer !== "cmux") {
-        throw new AppError("validation", "--viewer must be cmux", 2);
-    }
     const dashboardPath = format === "html" ? projectDashboardHtmlPath(context, project.id) : dashboardMarkdownPath(project.root, config);
     return {
         ok: true,
         project_root: project.root,
         dashboard: { path: dashboardPath },
-        open: openCmuxDashboard(context, project.root, dashboardPath, format)
+        open: await openCmuxDashboard(context, project.root, dashboardPath, format)
     };
 }
-export function openGlobalDashboard(context, input = {}) {
-    if (input.viewer && input.viewer !== "cmux") {
-        throw new AppError("validation", "--viewer must be cmux", 2);
-    }
+export async function openGlobalDashboard(context, input = {}) {
+    prepareDashboardOptions(input);
     const format = parseDashboardFormat(input.format, "html");
     const rendered = renderGlobalDashboard(context, { format });
     return {
         ok: true,
         dashboard: rendered.dashboard,
-        open: openDashboardPath(context, rendered.dashboard.path, format)
+        open: await openDashboardPath(context, rendered.dashboard.path, format)
     };
 }
-export function openProtocolDashboard(context, input) {
-    if (input.viewer && input.viewer !== "cmux") {
-        throw new AppError("validation", "--viewer must be cmux", 2);
-    }
+export async function openProtocolDashboard(context, input) {
+    prepareDashboardOptions(input);
     const format = parseDashboardFormat(input.format, "html");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     if (format !== "html") {
@@ -90,17 +104,43 @@ export function openProtocolDashboard(context, input) {
         project_root: project.root,
         protocol_id: input.protocol,
         dashboard: rendered.dashboard,
-        open: openCmuxDashboard(context, project.root, rendered.dashboard.path, format)
+        open: await openCmuxDashboard(context, project.root, rendered.dashboard.path, format)
     };
 }
-export function refreshDashboard(context, input) {
+export function prepareDashboardRefresh(context, input) {
+    prepareDashboardOptions(input);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const config = readProjectConfig(context, project.id);
     const format = parseDashboardFormat(input.format);
     const openMode = input.open ?? "auto";
-    if (!["auto", "true", "false"].includes(openMode)) {
-        throw new AppError("validation", "--open must be auto, true, or false", 2);
+    if (config.dashboard.project) {
+        if (projectRecoveryGuarded(context, project.id))
+            throw new AppError("run_recovery_guarded", "Project dashboard is frozen while its RUN is retained for recovery", 1);
+        if (input.protocol)
+            requireProtocol(context, input.protocol, project.id);
+        prepareRefreshOutputs(context, project, config, format, input.protocol);
     }
+    return { project, config, format, openMode };
+}
+function prepareRefreshOutputs(context, project, config, format, protocol) {
+    if (config.dashboard.project) {
+        if (!protocol)
+            prepareOutputFile(projectSummaryJsonPath(context, project.id));
+        if (format === "html") {
+            prepareOutputFile(protocol ? protocolDashboardHtmlPath(context, project.id, protocol) : projectDashboardHtmlPath(context, project.id));
+            prepareOutputFile(protocol ? protocolDashboardJsonPath(context, project.id, protocol) : projectDashboardJsonPath(context, project.id));
+        }
+        else
+            prepareOutputFile(dashboardMarkdownPath(project.root, config));
+    }
+    if (config.dashboard.global) {
+        prepareOutputFile(format === "html" ? globalDashboardHtmlPath(context) : globalDashboardMarkdownPath(context, config));
+        if (format === "html")
+            prepareOutputFile(globalDashboardJsonPath(context));
+    }
+}
+export async function refreshDashboard(context, input) {
+    const { project, config, format, openMode } = prepareDashboardRefresh(context, input);
     if (!config.dashboard.project) {
         return {
             ok: true,
@@ -124,7 +164,7 @@ export function refreshDashboard(context, input) {
         dashboard: rendered.dashboard,
         project_summary: projectSummary,
         global_dashboard: global.dashboard,
-        open: shouldOpen ? openCmuxDashboard(context, project.root, rendered.dashboard.path, format) : { ok: true, skipped: true, reason: "open_disabled" }
+        open: shouldOpen ? await openCmuxDashboard(context, project.root, rendered.dashboard.path, format) : { ok: true, skipped: true, reason: "open_disabled" }
     };
 }
 export function refreshGlobalDashboard(context, input = {}) {
@@ -143,8 +183,9 @@ export function refreshAllDashboards(context, input = {}) {
             return { ok: true, project_id: project.id, project_root: project.root, skipped: true, reason: "dashboard_project_disabled" };
         }
         try {
-            const projectSummary = publishProjectSummary(context, { project });
+            prepareRefreshOutputs(context, project, { ...config, dashboard: { ...config.dashboard, global: false } }, format);
             const rendered = renderDashboard(context, { projectRoot: project.root, format });
+            const projectSummary = publishProjectSummary(context, { project });
             return { ok: true, project_id: project.id, project_root: project.root, dashboard: rendered.dashboard, project_summary: projectSummary };
         }
         catch (error) {
@@ -170,10 +211,21 @@ export function refreshAllDashboards(context, input = {}) {
 }
 export function autoRefreshDashboards(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const config = readProjectConfig(context, project.id);
+    // Hooks and usage ingestion continue to record receipts after capture.
+    // Their derived timestamp must not mutate the captured workspace.
+    if (projectRecoveryGuarded(context, project.id))
+        return { ok: true, skipped: true, reason: "run_recovery_guarded" };
+    const configured = readProjectConfig(context, project.id);
+    // Automatic observation must not change a memory or diagnostic source baseline.
+    // Keep projections in Home; do not hide runtime-created paths in Git or
+    // weaken source preservation by excluding user-owned .tasks directories.
+    const initializing = context.db.get("SELECT 1 FROM runs WHERE project_id=? AND flow_kind IN ('mb-init','mb-upgrade','mb-audit','project-review') AND (id=? OR status IN ('created','running','paused','waiting_for_user','blocked')) LIMIT 1", [project.id, input.runId ?? null]);
+    const config = initializing ? { ...configured, dashboard: { ...configured.dashboard,
+            markdown_path: path.join(projectDashboardDir(context.ddFlowHome, project.id), "project-dashboard.md") } } : configured;
     if (!config.dashboard.auto_refresh) {
         return { ok: true, skipped: true, reason: "dashboard_auto_refresh_disabled" };
     }
+    prepareRefreshOutputs(context, project, config, "markdown");
     const result = { ok: true, project_root: project.root };
     if (config.dashboard.project) {
         publishProjectSummary(context, { project });
@@ -196,6 +248,9 @@ export function autoRefreshDashboards(context, input) {
     }
     return result;
 }
+function projectRecoveryGuarded(context, projectId) {
+    return Boolean(context.db.get("SELECT 1 FROM run_recovery_guards WHERE project_id = ? AND status IN ('draining', 'sealed', 'resuming') LIMIT 1", [projectId]));
+}
 export function dashboardSummary(context, projectId, projectRoot) {
     const config = readProjectConfig(context, projectId);
     return {
@@ -221,13 +276,13 @@ export function dashboardData(context, input) {
     }
     return { ok: true, dashboard: buildProjectDashboardData(context, project, projectDashboardHtmlPath(context, project.id)) };
 }
-function openCmuxDashboard(context, projectRoot, dashboardPath, format = "markdown") {
+async function openCmuxDashboard(context, projectRoot, dashboardPath, format = "markdown") {
     const project = requireProjectByRoot(context, resolveProjectRoot(projectRoot));
     const config = readProjectConfig(context, project.id);
     if (config.integrations.cmux.mode === "off") {
         return { ok: true, skipped: true, reason: "cmux_off" };
     }
-    const cmux = detectCmux(context);
+    const cmux = await detectCmux(context);
     if (!cmux.available) {
         if (config.integrations.cmux.mode === "required") {
             throw new AppError("cmux_unavailable", "cmux is required by project config but is unavailable", 1, { cmux });
@@ -238,20 +293,20 @@ function openCmuxDashboard(context, projectRoot, dashboardPath, format = "markdo
         return { ok: true, opened: false, dry_run: true, command: cmuxOpenCommand(format, dashboardPath) };
     }
     const command = cmuxOpenCommand(format, dashboardPath);
-    const result = spawnSync(command[0], command.slice(1), { encoding: "utf8" });
-    if (result.status !== 0) {
+    const result = await commandResult(command[0], command.slice(1), { startupMs: SETUP_STARTUP_MS });
+    if (result.exit_code !== 0) {
         if (config.integrations.cmux.mode === "required") {
             throw new AppError("cmux_open_failed", "cmux markdown open failed", 1, {
-                status: result.status,
+                status: result.exit_code,
                 stderr: result.stderr.trim()
             });
         }
-        return { ok: true, skipped: true, reason: "cmux_open_failed", status: result.status, stderr: result.stderr.trim() };
+        return { ok: true, skipped: true, reason: "cmux_open_failed", status: result.exit_code, stderr: result.stderr.trim() };
     }
     return { ok: true, opened: true, command };
 }
-function openDashboardPath(context, dashboardPath, format) {
-    const cmux = detectCmux(context);
+async function openDashboardPath(context, dashboardPath, format) {
+    const cmux = await detectCmux(context);
     if (!cmux.available) {
         return { ok: true, skipped: true, reason: "cmux_unavailable", cmux };
     }
@@ -259,9 +314,9 @@ function openDashboardPath(context, dashboardPath, format) {
         return { ok: true, opened: false, dry_run: true, command: cmuxOpenCommand(format, dashboardPath) };
     }
     const command = cmuxOpenCommand(format, dashboardPath);
-    const result = spawnSync(command[0], command.slice(1), { encoding: "utf8" });
-    if (result.status !== 0) {
-        return { ok: true, skipped: true, reason: "cmux_open_failed", status: result.status, stderr: result.stderr.trim() };
+    const result = await commandResult(command[0], command.slice(1), { startupMs: SETUP_STARTUP_MS });
+    if (result.exit_code !== 0) {
+        return { ok: true, skipped: true, reason: "cmux_open_failed", status: result.exit_code, stderr: result.stderr.trim() };
     }
     return { ok: true, opened: true, command };
 }
@@ -270,17 +325,31 @@ function cmuxOpenCommand(format, dashboardPath) {
         ? ["cmux", "browser", "open", pathToFileUrl(dashboardPath)]
         : ["cmux", "markdown", "open", dashboardPath];
 }
-function detectCmux(context) {
+async function detectCmux(context) {
     if (context.env.DD_FLOW_CMUX_AVAILABLE === "true") {
         return { available: true, source: "env" };
     }
     if (context.env.DD_FLOW_CMUX_AVAILABLE === "false") {
         return { available: false, source: "env", reason: "forced_unavailable" };
     }
-    const result = spawnSync("cmux", ["--version"], { encoding: "utf8" });
-    return result.status === 0
+    let result;
+    try {
+        result = await commandResult("cmux", ["--version"], { startupMs: SETUP_STARTUP_MS, phase: 'native-version' });
+    }
+    catch (error) {
+        return { available: false, source: 'path', reason: error instanceof Error ? error.message : String(error) };
+    }
+    return result.exit_code === 0
         ? { available: true, source: "path", version: result.stdout.trim() }
-        : { available: false, source: "path", reason: result.error?.message ?? result.stderr.trim() ?? "cmux not found" };
+        : { available: false, source: "path", reason: result.stderr.trim() || "cmux not found" };
+}
+export function prepareDashboardOptions(input) {
+    if (input.format !== undefined)
+        parseDashboardFormat(input.format);
+    if (input.viewer !== undefined && input.viewer !== "cmux")
+        throw new AppError("validation", "--viewer must be cmux", 2);
+    if (input.open !== undefined && !["auto", "true", "false"].includes(input.open))
+        throw new AppError("validation", "--open must be auto, true, or false", 2);
 }
 function parseDashboardFormat(value, defaultFormat = "markdown") {
     const format = value ?? defaultFormat;
@@ -294,15 +363,18 @@ function renderProjectDashboardHtml(context, project, output) {
         ? path.resolve(path.isAbsolute(output) ? output : path.join(project.root, output))
         : projectDashboardHtmlPath(context, project.id);
     const jsonPath = projectDashboardJsonPath(context, project.id);
+    prepareOutputFile(htmlPath);
+    prepareOutputFile(jsonPath);
     const data = buildProjectDashboardData(context, project, htmlPath);
     const html = renderDashboardHtmlPage(data);
-    writeJsonFile(jsonPath, data);
-    writeTextFile(htmlPath, html);
     const protocolCards = Array.isArray(data.protocol_cards) ? data.protocol_cards : [];
-    const protocolPages = protocolCards
+    const preparedPages = protocolCards
         .filter((card) => card.generate_page !== false)
         .slice(0, 24)
-        .map((card) => renderProtocolDashboardHtml(context, project, String(card.id)))
+        .map((card) => prepareProtocolDashboardHtml(context, project, String(card.id)));
+    writeJsonFile(jsonPath, data);
+    writeTextFile(htmlPath, html);
+    const protocolPages = preparedPages.map(writeProtocolDashboardHtml)
         .map((result) => ({
         id: String(result.protocol_id),
         path: result.dashboard.path,
@@ -321,12 +393,23 @@ function renderProjectDashboardHtml(context, project, output) {
     };
 }
 function renderProtocolDashboardHtml(context, project, protocolId, output) {
+    return writeProtocolDashboardHtml(prepareProtocolDashboardHtml(context, project, protocolId, output));
+}
+function prepareProtocolDashboardHtml(context, project, protocolId, output) {
+    if (projectRecoveryGuarded(context, project.id))
+        throw new AppError("run_recovery_guarded", "Project dashboard is frozen while its RUN is retained for recovery", 1);
     const htmlPath = output
         ? path.resolve(path.isAbsolute(output) ? output : path.join(project.root, output))
         : protocolDashboardHtmlPath(context, project.id, protocolId);
     const jsonPath = protocolDashboardJsonPath(context, project.id, protocolId);
+    prepareOutputFile(htmlPath);
+    prepareOutputFile(jsonPath);
     const data = buildProtocolDashboardData(context, project, protocolId, htmlPath);
     const html = renderDashboardHtmlPage(data);
+    return { project, protocolId, htmlPath, jsonPath, data, html };
+}
+function writeProtocolDashboardHtml(prepared) {
+    const { project, protocolId, htmlPath, jsonPath, data, html } = prepared;
     writeJsonFile(jsonPath, data);
     writeTextFile(htmlPath, html);
     return {
@@ -344,6 +427,8 @@ function renderProtocolDashboardHtml(context, project, protocolId, output) {
 function renderGlobalDashboardHtml(context, output) {
     const htmlPath = output ? path.resolve(output) : globalDashboardHtmlPath(context);
     const jsonPath = globalDashboardJsonPath(context);
+    prepareOutputFile(htmlPath);
+    prepareOutputFile(jsonPath);
     const data = buildGlobalDashboardData(context, htmlPath);
     const html = renderDashboardHtmlPage(data);
     writeJsonFile(jsonPath, data);
@@ -888,12 +973,12 @@ function protocolsForProject(context, projectId) {
      FROM protocols WHERE project_id = ? ORDER BY updated_at DESC`, [projectId]);
 }
 function planSummaryForProtocol(context, projectId, protocolId) {
-    const protocol = context.db.get("SELECT plan_path FROM protocols WHERE project_id = ? AND id = ?", [projectId, protocolId]);
+    const protocol = context.db.get("SELECT plan_path, project_root FROM protocols WHERE project_id = ? AND id = ?", [projectId, protocolId]);
     if (!protocol) {
         return { plan_id: "none", total: 0, done: 0, blocked: 0 };
     }
     try {
-        const summary = planSummary(context, { projectId, protocolId, planPath: protocol.plan_path }, { bind: false });
+        const summary = planSummary(context, { projectId, protocolId, planPath: resolveProtocolPlanPath(protocol.project_root, protocolId, protocol.plan_path) }, { bind: false });
         return { plan_id: summary.plan_id, total: summary.total, done: summary.done, blocked: summary.blocked };
     }
     catch {
@@ -903,13 +988,13 @@ function planSummaryForProtocol(context, projectId, protocolId) {
 function activePlanItems(context, projectId, protocols) {
     const items = [];
     for (const protocol of protocols) {
-        const record = context.db.get("SELECT plan_path FROM protocols WHERE project_id = ? AND id = ?", [projectId, protocol.id]);
+        const record = context.db.get("SELECT plan_path, project_root FROM protocols WHERE project_id = ? AND id = ?", [projectId, protocol.id]);
         if (!record) {
             continue;
         }
         let plan;
         try {
-            plan = planWithProgress(context, { projectId, protocolId: protocol.id, planPath: record.plan_path }, { bind: false }).plan;
+            plan = planWithProgress(context, { projectId, protocolId: protocol.id, planPath: resolveProtocolPlanPath(record.project_root, protocol.id, record.plan_path) }, { bind: false }).plan;
         }
         catch {
             continue;

package/dist/services/descriptor-coordinator-session.js

@@ -0,0 +1,35 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { readDescriptorStageInput, readDescriptorStageInputForRecovery } from "./descriptor-stage-coordinator.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+/** SQL-only physical coordinator proof, independent of allocation/prompt
+ * custody. It creates no Session, hook claim or provider operation.
+ */
+export function readDescriptorCoordinatorSession(context, input, refuse = reason => {
+    throw new AppError("descriptor_coordinator_session_invalid", "Coordinator has no matching physical Session custody", 1, { reason, effect: "no_effect" });
+}) {
+    const { scope, bundle, workId } = input;
+    const rows = context.db.all("SELECT ws.id,ws.session_id,ws.hook_event_id,ws.prompt_path,ws.result_path,s.harness,s.provider_session_id FROM work_sessions ws JOIN sessions s ON s.session_id=ws.session_id AND s.project_id=? WHERE ws.work_id=? AND ws.status='running' AND s.run_id=? AND s.current_stage=? AND s.status='active' LIMIT 2", [scope.projectId, workId, scope.runId, scope.stage]);
+    if (rows.length !== 1)
+        refuse("active_coordinator_session_required");
+    const session = rows[0], route = bundle.execution.stage(scope.stage);
+    const selected = input.recoveryRead ? readDescriptorStageInputForRecovery(context, scope, bundle, input.recoveryRead) : readDescriptorStageInput(context, scope, bundle), directory = bundle.descriptor.stage(scope.stage).directory;
+    if (session.prompt_path !== path.join(selected.runRoot, directory, "coordinator-prompt.md")
+        || session.result_path !== path.join(selected.runRoot, directory, "result-input.json"))
+        refuse("coordinator_packet_link_changed");
+    if (session.harness !== runtimeHarness(route.profile)
+        || !context.db.get("SELECT 1 FROM hook_events WHERE project_id=? AND event_key=? AND session_id=? AND harness=? AND provider_session_id=? AND status='claimed' AND event_name='PreToolUse'", [scope.projectId, session.hook_event_id, session.session_id, session.harness, session.provider_session_id]))
+        refuse("coordinator_start_custody_missing");
+    const bindings = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='stage.coordinator_binding' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.stage')=? AND json_extract(payload_json,'$.work_session_id')=? LIMIT 33", [scope.projectId, scope.runId, scope.stage, session.id]);
+    if (!bindings.length || bindings.length > 32 || bindings.some(row => Buffer.byteLength(row.payload_json) > 32768))
+        refuse("physical_binding_missing");
+    const binding = JSON.parse(bindings[0].payload_json);
+    if (bindings.some(row => hybridDigest(JSON.parse(row.payload_json)) !== hybridDigest(binding))
+        || binding.work_id !== workId || binding.session_id !== session.session_id || binding.harness !== session.harness || binding.provider_session_id !== session.provider_session_id
+        || binding.execution_sha256 !== bundle.execution.sha256 || binding.profile_id !== route.profile.id || binding.profile_sha256 !== hybridDigest(route.profile)
+        || binding.session_mode !== route.session_mode || hybridDigest(binding.scope) !== hybridDigest({ ...stageGraphScope(context, scope.projectId, scope.runId, scope.stage), stage: scope.stage }))
+        refuse("physical_binding_changed");
+    return hybridDigest({ session, binding });
+}

package/dist/services/descriptor-root-work.js

@@ -0,0 +1,53 @@
+import { AppError } from "../shared/errors.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { nextWorkId } from "./ids.js";
+import { appendAudit } from "./audit.js";
+const event = "flow_run.descriptor_root_work";
+function refuse(reason) {
+    throw new AppError("descriptor_root_work_invalid", "RUN root Work lacks independent allocation custody", 1, { reason, effect: "no_effect" });
+}
+const binding = (scope, bundle) => ({ projectId: scope.projectId, runId: scope.runId, bundle_sha256: bundle.sha256 });
+/** SQL-only read. Root identity is retained independently, never discovered
+ * from an arbitrary root row or reconstructed after receipt loss.
+ */
+export function readDescriptorRootWork(context, scope, bundle) {
+    return context.db.readSnapshot(() => {
+        const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        const receipts = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? LIMIT 2", [scope.projectId, event, scope.runId]);
+        if (receipts.length !== 1 || Buffer.byteLength(receipts[0].payload_json) > 16 * 1024)
+            refuse("root_work_receipt_missing");
+        const receipt = JSON.parse(receipts[0].payload_json);
+        const expected = binding(scope, bundle);
+        if (typeof receipt.work_id !== "string" || hybridDigest(receipt) !== hybridDigest({ run_id: scope.runId, work_id: receipt.work_id, binding: expected }))
+            refuse("root_work_changed");
+        const roots = context.db.all("SELECT work_id,task,payload_json,status,launch_policy,result_schema,depends_on_json FROM works WHERE project_id=? AND run_id=? AND parent_work_id IS NULL LIMIT 2", [scope.projectId, scope.runId]);
+        if (roots.length !== 1)
+            refuse("ambiguous_root_work");
+        const root = roots[0];
+        if (root.work_id !== receipt.work_id || root.task !== `Coordinate ${bundle.descriptor.descriptor.id}`
+            || root.payload_json !== JSON.stringify({ descriptor_run_coordinator: expected })
+            || root.launch_policy !== "reuse_allowed" || root.result_schema !== null || root.depends_on_json !== "[]")
+            refuse("root_work_custody_missing");
+        if (JSON.parse(run.index_json).root_work_id !== root.work_id)
+            refuse("root_work_anchor_missing");
+        return { workId: root.work_id, status: root.status };
+    });
+}
+/** Called only in the same writer as fresh descriptor RUN allocation. Stage
+ * handlers consume this identity; they never allocate a second RUN root.
+ */
+export function allocateDescriptorRootWork(context, scope, bundle) {
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    if (context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND parent_work_id IS NULL", [scope.projectId, scope.runId])
+        || context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=?", [scope.projectId, event, scope.runId]))
+        refuse("root_work_already_allocated");
+    const workId = nextWorkId(context, scope.projectId, bundle.descriptor.descriptor.id), now = context.now();
+    const expected = binding(scope, bundle);
+    context.db.run("INSERT INTO works (work_id,project_id,run_id,parent_work_id,task,launch_policy,depends_on_json,status,payload_json,created_at,updated_at) VALUES (?,?,?,NULL,?,'reuse_allowed','[]','created',?,?,?)", [workId, scope.projectId, scope.runId, `Coordinate ${bundle.descriptor.descriptor.id}`, JSON.stringify({ descriptor_run_coordinator: expected }), now, now]);
+    context.db.run("UPDATE runs SET index_json=json_set(index_json,'$.root_work_id',?) WHERE project_id=? AND id=?", [workId, scope.projectId, scope.runId]);
+    appendAudit(context, { projectId: scope.projectId, eventType: event, payload: { run_id: scope.runId, work_id: workId, binding: expected } });
+    if (readDescriptorRootWork(context, scope, bundle).workId !== workId)
+        refuse("root_work_not_retained");
+    return workId;
+}

package/dist/services/descriptor-run-settlement.js

@@ -0,0 +1,107 @@
+import { AppError } from "../shared/errors.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { appendFlowRunTimelineEvent, assertPreparedRunBundleSqlAuthority, completeDescriptorRunState, gitFacts, publishRunProjections, readFlowRunExecutionBundle, withStageSettlement } from "./runs.js";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { readAcceptedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { entityReferenceVariants } from "../shared/entity-references.js";
+import { stageLifecycleMatchKey } from "./hooks.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { assertRunMutationAllowed } from "./run-recovery-guard.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const event = "flow_run.descriptor_run_settlement";
+function refuse(reason) {
+    throw new AppError("descriptor_run_settlement_invalid", "Terminal descriptor RUN lacks exact settlement custody", 1, { reason, effect: "no_effect" });
+}
+function selected(context, scope, bundle, matchKeys) {
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    const root = readDescriptorRootWork(context, scope, bundle);
+    const run = context.db.get("SELECT status,index_json FROM runs WHERE project_id=? AND id=?", [scope.projectId, scope.runId]);
+    const index = JSON.parse(run.index_json);
+    const terminal = index.stage_runs.at(-1);
+    if (!bundle.descriptor.descriptor.terminal_stages.includes(scope.stage)
+        || terminal?.stage !== scope.stage || terminal.status !== "done")
+        refuse("terminal_stage_not_accepted");
+    const data = readAcceptedStageData(context, scope);
+    const stageReceipt = readAcceptedDescriptorStageSettlement(context, scope, bundle, matchKeys);
+    if (context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND work_id<>? AND status IN ('created','running','paused') LIMIT 1", [scope.projectId, scope.runId, root.workId])
+        || context.db.get("SELECT 1 FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id WHERE w.project_id=? AND w.run_id=? AND ws.status='running' LIMIT 1", [scope.projectId, scope.runId]))
+        refuse("work_still_active");
+    const prior = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? LIMIT 2", [scope.projectId, event, scope.runId]);
+    if (prior.length > 1 || prior.some(row => Buffer.byteLength(row.payload_json) > 32 * 1024))
+        refuse("ambiguous_receipt");
+    if (root.status !== (prior.length ? "completed" : "running") || run.status !== (prior.length ? "done" : "running"))
+        refuse("terminal_state_changed");
+    return { rootId: root.workId, result: data.bytes.toString("utf8"), binding: { ...scope, work_id: root.workId, bundle_sha256: bundle.sha256, result_sha256: data.result.sha256, input_sha256: data.input_sha256, stage_receipt_sha256: hybridDigest(stageReceipt) }, prior: prior[0] ? JSON.parse(prior[0].payload_json) : null };
+}
+/** Runtime closure only. A terminal handler must first verify semantic/check/
+ * review/Git acceptance, revalidate physical proof, and supply its SQL fence.
+ * Transcript usage collection is deliberately outside this atomic writer.
+ */
+export class PreparedDescriptorRunSettlement {
+    #scope;
+    #bundle;
+    #owner;
+    #git;
+    #generation;
+    #matchKeys;
+    constructor(scope, bundle, owner, git, generation, matchKeys) {
+        this.#scope = scope;
+        this.#bundle = bundle;
+        this.#owner = owner;
+        this.#git = git;
+        this.#generation = generation;
+        this.#matchKeys = matchKeys;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), bundle = readFlowRunExecutionBundle(context, input);
+        if (!bundle)
+            refuse("bundle_required");
+        const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+        const matchKeys = entityReferenceVariants(input.runId).map(reference => stageLifecycleMatchKey("stage_finish", reference, input.stage, input.projectRoot));
+        const snapshot = context.db.readSnapshot(() => ({ owner: selected(context, scope, bundle, matchKeys), generation: assertRunMutationAllowed(context, scope.projectId, scope.runId) }));
+        const operational = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        const git = snapshot.owner.prior?.git ?? gitFacts(operational.workspace_root ?? operational.project_root);
+        return new PreparedDescriptorRunSettlement(scope, bundle, snapshot.owner, git, snapshot.generation, matchKeys);
+    }
+    apply(context, assertHandlerCustody) {
+        if (typeof assertHandlerCustody !== "function")
+            refuse("handler_fence_required");
+        const operational = assertPreparedRunBundleSqlAuthority(context, this.#scope, this.#bundle);
+        const bundle = readFlowRunExecutionBundle(context, { projectRoot: operational.project_root, runId: this.#scope.runId });
+        if (!bundle || bundle.sha256 !== this.#bundle.sha256)
+            refuse("bundle_changed");
+        const observed = context.db.readSnapshot(() => selected(context, this.#scope, this.#bundle, this.#matchKeys));
+        if (!observed.prior && hybridDigest(gitFacts(operational.workspace_root ?? operational.project_root)) !== hybridDigest(this.#git))
+            refuse("git_observation_changed");
+        const receipt = { run_id: this.#scope.runId, work_id: this.#owner.rootId, binding: this.#owner.binding, git: this.#git };
+        const changed = withStageSettlement(context, () => {
+            assertRunMutationAllowed(context, this.#scope.projectId, this.#scope.runId, this.#generation);
+            assertHandlerCustody(context);
+            const current = selected(context, this.#scope, this.#bundle, this.#matchKeys);
+            if (hybridDigest(current.binding) !== hybridDigest(this.#owner.binding) || current.result !== this.#owner.result)
+                refuse("terminal_custody_changed");
+            if (current.prior) {
+                if (hybridDigest(current.prior) !== hybridDigest(receipt)
+                    || context.db.get("SELECT result FROM works WHERE work_id=?", [current.rootId])?.result !== current.result)
+                    refuse("settlement_changed");
+                return false;
+            }
+            if (this.#owner.prior)
+                refuse("settlement_receipt_missing");
+            const now = context.now();
+            if (context.db.run("UPDATE works SET status='completed',result=?,completed_at=?,updated_at=? WHERE work_id=? AND project_id=? AND run_id=? AND status='running'", [current.result, now, now, current.rootId, this.#scope.projectId, this.#scope.runId]).changes !== 1)
+                refuse("root_changed");
+            appendFlowRunTimelineEvent(context, this.#scope.projectId, this.#scope.runId, { at: now, type: "work_completed", work_id: current.rootId, descriptor_terminal: true });
+            completeDescriptorRunState(context, this.#scope, this.#bundle, this.#git);
+            appendAudit(context, { projectId: this.#scope.projectId, eventType: event, payload: receipt });
+            return true;
+        });
+        // A committed terminal receipt can outlive an interrupted file publisher.
+        // Replay restores projections from current SQL, without settling again.
+        publishRunProjections(context, this.#scope.projectId, this.#scope.runId);
+        return { changed, run_id: this.#scope.runId, work_id: this.#owner.rootId, status: "done" };
+    }
+}