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

package/dist/services/codex-hook-delivery.js

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { callDaemon } from "../harness-runtime/lib/dd-codex-daemon.mjs";
+import { AppError } from "../shared/errors.js";
+import { commandOption, lifecycleCommandFromPayload, parseLifecycleCommand } from "./lifecycle-command.js";
+/** The hook asks the existing daemon about native evidence; it cannot mint it. */
+export async function verifyCodexHookDelivery(env, payload) {
+    const command = lifecycleCommandFromPayload(payload);
+    const parsed = command ? parseLifecycleCommand(command) : { kind: "none" };
+    if (parsed.kind === "none")
+        return undefined;
+    const managed = commandOption(parsed.invocation, "invocation-id") || env.DD_FLOW_DAEMON_ID;
+    if (!managed)
+        return undefined; // Explicit legacy/unmanaged transport.
+    if (!env.DD_FLOW_CODEX_STATE_DIR || !env.DD_FLOW_DAEMON_ID)
+        throw new AppError("native_hook_unproven", "Managed hook has no owning native daemon", 1, { effect: "no_effect" });
+    const proof = await callDaemon(env.DD_FLOW_CODEX_STATE_DIR, "hook.verify", {
+        daemonId: env.DD_FLOW_DAEMON_ID, rootSessionId: payload.session_id,
+        sessionId: payload.agent_id ?? payload.session_id, toolCallId: payload.tool_use_id, turnId: payload.turn_id
+    }, 5000);
+    if (typeof proof.projectRoot !== "string"
+        || typeof proof.ddFlowHome !== "string" || !env.DD_FLOW_HOME || path.resolve(env.DD_FLOW_HOME) !== path.resolve(proof.ddFlowHome)
+        || proof.daemonId !== env.DD_FLOW_DAEMON_ID || typeof proof.rootSessionId !== "string" || typeof proof.sessionId !== "string"
+        || typeof proof.toolCallId !== "string" || !(proof.parentSessionId === null || typeof proof.parentSessionId === "string")) {
+        throw new AppError("native_hook_unproven", "Native hook proof differs from the requested project/runtime", 1, { effect: "no_effect" });
+    }
+    return { daemonId: proof.daemonId, rootSessionId: proof.rootSessionId, sessionId: proof.sessionId,
+        parentSessionId: proof.parentSessionId, toolCallId: proof.toolCallId, projectRoot: proof.projectRoot, command: command };
+}

package/dist/services/config.js

@@ -28,7 +28,8 @@ export function getProjectConfigStatus(context, project) {
     };
 }
 export function setProjectConfigValue(context, project, input) {
-    const value = parseConfigValue(input.key, input.value);
+    const value = prepareProjectConfigValue(input.key, input.value);
+    migrateLegacyConfig(context, project.id);
     const now = context.now();
     context.db.run(`INSERT INTO project_config (project_id, key, value_json, created_at, updated_at)
      VALUES (?, ?, ?, ?, ?)
@@ -38,13 +39,15 @@ export function setProjectConfigValue(context, project, input) {
     return getProjectConfigStatus(context, project);
 }
 export function readProjectConfig(context, projectId) {
-    // Status and dashboard reads intentionally open SQLite read-only. Legacy
-    // cleanup is a write-side concern and must not make those commands fail.
-    if (context.db.writable)
-        migrateLegacyConfig(context, projectId);
+    // Project legacy values without changing storage. Explicit writes migrate
+    // them; a canonical override always wins over its legacy alias.
+    const rows = configOverrides(context, projectId), keys = new Set(rows.map(row => row.key));
     const config = structuredClone(defaultProjectConfig);
-    for (const row of configOverrides(context, projectId)) {
-        applyConfigValue(config, row.key, JSON.parse(row.value_json));
+    for (const row of rows) {
+        const key = legacyConfigKey(row.key);
+        if (key !== row.key && keys.has(key))
+            continue;
+        applyConfigValue(config, key, JSON.parse(row.value_json));
     }
     return config;
 }
@@ -89,7 +92,7 @@ export function globalDashboardHtmlPath(context) {
 function configOverrides(context, projectId) {
     return context.db.all("SELECT key, value_json, updated_at FROM project_config WHERE project_id = ? ORDER BY key ASC", [projectId]);
 }
-function parseConfigValue(key, value) {
+export function prepareProjectConfigValue(key, value) {
     if (key === "integrations.cmux.mode") {
         if (!cmuxModes.includes(value)) {
             throw new AppError("validation", "--value for integrations.cmux.mode must be off, auto, or required", 2);

package/dist/services/controller-fanout.js

@@ -0,0 +1,116 @@
+import { AppError } from "../shared/errors.js";
+import { getVnextFanoutStatus, observeVnextNativeChildren, reconcileVnextFanout, subagentCapacityKey } from "./vnext-fanout.js";
+import { getFlowRunVariables } from "./runs.js";
+import { dispatchVnextPlanReview } from "./vnext-plan-review.js";
+import { resolveExecutionPolicy } from "./execution-policy.js";
+import { renderDelegationInstructions } from "../harness-runtime/lib/delegation-instructions.mjs";
+/** Stage entry acknowledges the packet before the controller issues child commands. */
+export function controllerStageEntryPrompt(stage, command, responseFile) {
+    return [
+        `Start the assigned ${stage} Stage now. Your first tool call must be this exact standalone command:`,
+        command,
+        `Read the complete authoritative packet saved to ${JSON.stringify(responseFile)}, including worker_prompt_markdown. If a read is truncated, continue until the entire packet has been read.`,
+        "If the returned packet has orchestration.kind = work_fanout, this Turn is only Stage entry: acknowledge the packet and end your Turn immediately. The packet describes the whole Stage, but its graph/dispatch/finish instructions belong to later controller continuations. Do not list, start, launch or finish Work, create children, change files, run checks, or finish the Stage in this entry Turn. The controller will inspect the graph and send the next assignment with exact issued commands (or dispatch external workers itself).",
+        "Otherwise perform this Stage's semantic work and stop at its boundary or a declared HITL boundary. Do not start a successor Stage.",
+        "Execute each runtime-issued lifecycle operation and target as one standalone call. Internal invocation IDs are intentionally absent; never add, copy or invent one. For a no-effect input rejection, correct the input and use its returned retry_command. If a required command is missing or no safe retry is returned, report the exact error and end the Turn so the controller can handle it."
+    ].join("\n\n");
+}
+/** The shared controller owns this former eval-only Work-graph decision. */
+export async function nextControllerFanout(context, input) {
+    const children = input.children.filter(child => child.status !== "settled_by_root");
+    const observations = { harness_id: input.harness, parent_session_id: input.sessionId, children };
+    if (children.length) {
+        const observed = observeVnextNativeChildren(context, { ...input, observations });
+        const issues = observed.issues;
+        if (issues.length)
+            throw new AppError("fanout_reconciliation_required", "Native children have unresolved lifecycle ownership", 1, { issues });
+    }
+    let fanout = getVnextFanoutStatus(context, input).orchestration;
+    if (!fanout)
+        return { kind: "none" };
+    if (children.length) {
+        const reconciled = await reconcileVnextFanout(context, { ...input, observations });
+        const issues = reconciled.issues.filter(issue => issue.code !== "child_check_in_progress");
+        if (issues.length)
+            throw new AppError("fanout_reconciliation_required", "Native child outcome requires reconciliation, not replay", 1, { issues });
+        if (children.some(child => child.status === "running" || child.status === "unknown"))
+            return { kind: "wait", reason: "native_children_unsettled" };
+        fanout = getVnextFanoutStatus(context, input).orchestration;
+    }
+    if (fanout.state === "dispatch_required") {
+        dispatchVnextPlanReview(context, input);
+        fanout = getVnextFanoutStatus(context, input).orchestration;
+        if (fanout.state === "dispatch_required" || fanout.state === "capacity_required")
+            return { kind: "wait", reason: "qualified_capacity_required" };
+    }
+    const prompt = (text) => ({ kind: "prompt", prompt: text, fingerprint: JSON.stringify({ stage: input.stage, parent: fanout.parent_work_id, works: fanout.works, text }) });
+    if (fanout.state === "coordinator_required")
+        return prompt(`Continue the current ${input.stage} Stage using its authoritative packet. Materialize only its required Work graph with real dependencies. Do not launch children, finish the Stage, or start a successor. Return after registering the graph; the runtime will dispatch its ready Work.`);
+    if (fanout.works.failed || fanout.works.cancelled)
+        return prompt(`Some ${input.stage} child Work failed or was cancelled. Inspect its recorded receipts. Choose a legal scoped repair/retry or block the Stage with the concrete reason. Do not relaunch settled siblings or infer success from a child that omitted work finish.`);
+    if (fanout.works.ready.length) {
+        const choices = fanout.works.ready.map(work => {
+            const payload = context.db.get("SELECT payload_json FROM works WHERE work_id = ?", [work.work_id])?.payload_json;
+            const override = payload ? JSON.parse(payload).execution_override : undefined;
+            return { work, resolved: resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy: input.policy, profiles: input.profiles, stage: input.stage, ...(override ? { work: override } : {}) }) };
+        });
+        const external = choices.filter(choice => choice.resolved.delegation.mode === "external");
+        if (external.length) {
+            const maximum = Math.min(...external.map(choice => choice.resolved.delegation.max_parallel ?? 1));
+            return { kind: "external", works: external.slice(0, maximum).map(choice => choice.work) };
+        }
+        const variables = getFlowRunVariables(context, input);
+        const capacity = variables.variables[subagentCapacityKey];
+        if (typeof capacity !== "number" || !Number.isInteger(capacity) || capacity < 1)
+            return { kind: "wait", reason: "qualified_capacity_required" };
+        const wave = choices.slice(0, capacity).map(choice => choice.work);
+        for (const work of wave)
+            if (!work.work_id || !work.start_command)
+                throw new AppError("fanout_contract_invalid", "Ready Work omits its trusted start command", 1);
+        return prompt(renderDelegationInstructions({ harness: input.harness, stage: input.stage, capacity, works: wave }));
+    }
+    if (fanout.works.running)
+        return { kind: "wait", reason: "work_receipts_pending" };
+    if (fanout.works.created)
+        throw new AppError("fanout_graph_stalled", "Created Work has no ready or running dependency path", 1);
+    return prompt(`All declared ${input.stage} child Work has settled (${fanout.works.completed} completed). Read the accepted result receipts and continue this Stage's semantic decision under its original packet. A rejected stage finish may return either a repair creation command or an already-registered repair Work. Execute only a returned repair creation command, then return. If it reports repair_required with an existing repair Work/start_command, do not invoke that start_command in this coordinator Session: return immediately so the controller can launch a fresh child. Do not start a successor Stage.`);
+}
+/** Normalize provider-observed topology only; never parse assistant prose. */
+export function controllerNativeChildren(receipt, rootSessionId) {
+    const candidates = [];
+    const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    const list = (value) => Array.isArray(value) ? value : [];
+    const text = (value, keys) => { for (const key of keys)
+        if (typeof value[key] === "string" && value[key])
+            return value[key]; return null; };
+    const settledTree = new Set(list(receipt.tree_observations)
+        .filter(value => object(value).settled === true)
+        .map(value => text(object(value), ["provider_session_id", "session_id"]))
+        .filter((id) => id !== null));
+    const add = (raw, source, scopedParent = null, fallback = "unknown") => {
+        const value = object(raw);
+        const id = text(value, ["provider_session_id", "session_id", "sessionId", "childSessionId", "conversation_id", "conversationId", "id", "subagentId"]);
+        const parent = text(value, ["parent_provider_session_id", "parent_session_id", "parentSessionId", "parentID", "parentId"]) ?? scopedParent;
+        if (!id || parent !== rootSessionId)
+            return;
+        const state = String(value.status ?? value.state ?? fallback).toLowerCase();
+        const status = ["completed", "complete", "done", "idle", "success", "succeeded"].includes(state) ? "completed" : state === "settled_by_root" ? "settled_by_root" : ["failed", "error"].includes(state) ? "failed" : ["cancelled", "canceled"].includes(state) ? "cancelled" : ["running", "active", "pending"].includes(state) ? "running" : fallback;
+        candidates.push({ session_id: id, parent_session_id: parent, status: status === "unknown" && settledTree.has(id) ? "settled_by_root" : status, source });
+    };
+    for (const value of list(receipt.descendants))
+        add(value, "adapter.descendants");
+    for (const value of list(receipt.children))
+        add(value, "opencode.session.children");
+    const subagents = object(object(receipt.evidence).subagents ?? receipt.subagents);
+    for (const value of list(subagents.running))
+        add(value, "zcode/session/subagents", rootSessionId, "running");
+    for (const value of [...list(subagents.completed), ...list(object(subagents.ended).items)])
+        add(value, "zcode/session/subagents", rootSessionId, "completed");
+    const unique = new Map();
+    for (const child of candidates) {
+        const previous = unique.get(child.session_id);
+        if (!previous || previous.status === "unknown" || previous.status === "running" && child.status !== "running")
+            unique.set(child.session_id, child);
+    }
+    return [...unique.values()].sort((left, right) => left.session_id.localeCompare(right.session_id));
+}

package/dist/services/dashboard.js

@@ -3,7 +3,8 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { isActiveProtocolStatus, isActiveQueueStatus, isQueueHistoryStatus } from "../domain/contracts.js";
 import { AppError } from "../shared/errors.js";
-import { ensureDir, resolveProjectRoot } from "../storage/paths.js";
+import { prepareOutputFile } from "../cli/input-preparation.js";
+import { ensureDir, resolveProjectRoot, resolveProtocolPlanPath } from "../storage/paths.js";
 import { dashboardMarkdownPath, globalDashboardHtmlPath, globalDashboardJsonPath, globalDashboardMarkdownPath, projectDashboardHtmlPath, projectDashboardJsonPath, projectSummaryJsonPath, protocolDashboardHtmlPath, protocolDashboardJsonPath, readProjectConfig } from "./config.js";
 import { queueForProject } from "./merge-queue.js";
 import { publishProjectSummary } from "./project-summary.js";
@@ -17,42 +18,58 @@ export function getCmuxStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     return { ok: true, project_root: project.root, cmux: 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) {
+    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,
@@ -62,9 +79,7 @@ export function openDashboard(context, input) {
     };
 }
 export function openGlobalDashboard(context, input = {}) {
-    if (input.viewer && input.viewer !== "cmux") {
-        throw new AppError("validation", "--viewer must be cmux", 2);
-    }
+    prepareDashboardOptions(input);
     const format = parseDashboardFormat(input.format, "html");
     const rendered = renderGlobalDashboard(context, { format });
     return {
@@ -74,9 +89,7 @@ export function openGlobalDashboard(context, input = {}) {
     };
 }
 export function openProtocolDashboard(context, input) {
-    if (input.viewer && input.viewer !== "cmux") {
-        throw new AppError("validation", "--viewer must be cmux", 2);
-    }
+    prepareDashboardOptions(input);
     const format = parseDashboardFormat(input.format, "html");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     if (format !== "html") {
@@ -93,14 +106,40 @@ export function openProtocolDashboard(context, input) {
         open: 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 function refreshDashboard(context, input) {
+    const { project, config, format, openMode } = prepareDashboardRefresh(context, input);
     if (!config.dashboard.project) {
         return {
             ok: true,
@@ -143,8 +182,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 +210,15 @@ export function refreshAllDashboards(context, input = {}) {
 }
 export function autoRefreshDashboards(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    // 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 config = readProjectConfig(context, project.id);
     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 +241,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 {
@@ -282,6 +330,14 @@ function detectCmux(context) {
         ? { available: true, source: "path", version: result.stdout.trim() }
         : { available: false, source: "path", reason: result.error?.message ?? 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;
     if (format !== "markdown" && format !== "html") {
@@ -294,15 +350,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 +380,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 +414,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 +960,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 +975,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;