@deksden-com/dd-flow-cli 0.9.0-beta.9 → 0.9.0-beta.90

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, continuationCommand } 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" && !(command && continuationCommand(command)))
+        return undefined;
+    const managed = (parsed.kind !== "none" && 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/command-context.js

@@ -0,0 +1,80 @@
+import path from "node:path";
+import { commandInputs, physicalPathOptions } from "../cli/command-inputs.js";
+import { parseCommandArgs } from "./lifecycle-command.js";
+import { assertPathWithin, canonicalPath } from "../storage/paths.js";
+import { AppError } from "../shared/errors.js";
+import { resolveWorkReference } from "../storage/work-references.js";
+export function normalizedPathAlias(value) {
+    return value.replace(/^\\+(?=@(?:project|workspace|run)(?:\/|$))/, "");
+}
+export function resolveContextualPaths(args, options, roots) {
+    const resolve = (option, original) => {
+        if (!options.has(option))
+            return original;
+        const value = normalizedPathAlias(original);
+        if (!value.startsWith("@"))
+            return value;
+        const match = /^@(project|workspace|run)(?:\/(.*))?$/.exec(value);
+        if (!match || !roots[match[1]])
+            throw new AppError("usage", `Unknown or unavailable path alias: ${value}`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: option });
+        const root = roots[match[1]];
+        return assertPathWithin(root, path.join(root, match[2] ?? ""), `${match[1]}_alias`);
+    };
+    return args.map((value, index) => {
+        const equal = /^--([^=]+)=(.*)$/s.exec(value);
+        if (equal)
+            return `--${equal[1]}=${resolve(equal[1], equal[2])}`;
+        const option = args[index - 1]?.match(/^--([^=]+)$/)?.[1];
+        return option ? resolve(option, value) : value;
+    });
+}
+/** Contextual paths are route semantics, not lifecycle invocation authority. */
+export function resolveCommandProjectRoot(context, args, explicit) {
+    if (explicit && !normalizedPathAlias(explicit).startsWith("@"))
+        return canonicalPath(explicit, false);
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'runs'"))
+        return null;
+    const parsed = parseCommandArgs(args);
+    const key = Object.keys(commandInputs).filter(key => key.split(" ").every((part, i) => parsed.positional[i] === part)).sort((a, b) => b.length - a.length)[0];
+    const reference = parsed.options.get("run")?.[0] ?? (key?.startsWith("stage ") ? parsed.positional[key.split(" ").length] : undefined);
+    if (reference) {
+        const rows = context.db.all("SELECT project_root FROM runs WHERE id = ? OR short_id = ?", [reference, reference]);
+        if (rows.length === 1)
+            return rows[0].project_root;
+        if (rows.length > 1)
+            throw new AppError("usage", "RUN reference requires an explicit project scope", 2, { phase: "prepare", effect: "no_effect" });
+    }
+    const work = parsed.options.get("parent")?.[0] ?? (key?.startsWith("work ") && !key.startsWith("work repair") ? parsed.positional[key.split(" ").length] : undefined);
+    if (work) {
+        const resolved = resolveWorkReference(context, work);
+        return context.db.get("SELECT root FROM projects WHERE id = ?", [resolved.project_id])?.root ?? null;
+    }
+    return null;
+}
+export function resolveCommandPaths(context, args, projectRoot) {
+    const parsed = parseCommandArgs(args);
+    const key = Object.keys(commandInputs).filter(key => key.split(" ").every((part, i) => parsed.positional[i] === part)).sort((a, b) => b.length - a.length)[0];
+    const options = new Set(key ? commandInputs[key]?.contextualPaths ?? [] : []);
+    if (!args.some(value => /(?:^|=)\\*@/.test(value)))
+        return args;
+    for (const [option, values] of parsed.options) {
+        if (physicalPathOptions.has(option) && !options.has(option) && values.some(value => normalizedPathAlias(value).startsWith("@")))
+            throw new AppError("usage", `--${option} requires a physical path on this route`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: option });
+    }
+    const project = projectRoot ? context.db.get("SELECT id FROM projects WHERE root = ?", [projectRoot]) : undefined;
+    const reference = parsed.options.get("run")?.[0] ?? (key?.startsWith("stage ") ? parsed.positional[key.split(" ").length] : undefined);
+    let run;
+    if (reference && project) {
+        const rows = context.db.all("SELECT id, workspace_root, run_root FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [project.id, reference, reference]);
+        if (rows.length !== 1)
+            throw new AppError("usage", "Path aliases require one RUN in the selected project", 2, { phase: "prepare", effect: "no_effect" });
+        run = rows[0];
+    }
+    const work = parsed.options.get("parent")?.[0] ?? (key?.startsWith("work ") && !key.startsWith("work repair") ? parsed.positional[key.split(" ").length] : undefined);
+    if (work && project) {
+        const resolved = resolveWorkReference(context, work, { projectId: project.id, ...(run ? { runId: run.id } : {}) });
+        if (!run)
+            run = context.db.get("SELECT id, workspace_root, run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, resolved.run_id]);
+    }
+    return resolveContextualPaths(args, options, { project: projectRoot, workspace: run?.workspace_root, run: run?.run_root });
+}

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/continuation-outcome.js

@@ -0,0 +1,20 @@
+import { AppError } from "../shared/errors.js";
+import { isRegisteredRepair } from "./repair-intents.js";
+import { stageAttempt } from "./stage-work-graph.js";
+/** Only the settled coordinator turn can explain a repeated continuation.
+ * A stale error from another stage/turn or an error followed by success is not
+ * authority. Never inspect the assistant's prose for this decision. */
+export function assertNoCorrelatedRejection(context, scope) {
+    const rows = context.db.all(`SELECT outcome_json FROM hook_events
+    WHERE project_id = ? AND json_extract(outcome_json, '$.run_id') = ?
+    AND json_extract(outcome_json, '$.generation') = ? AND json_extract(outcome_json, '$.stage') = ?
+    AND json_extract(outcome_json, '$.controller_turn') = ? AND json_extract(outcome_json, '$.attempt') = ? ORDER BY id`, [scope.projectId, scope.runId, scope.generation, scope.stage, scope.turn, stageAttempt(context, scope.projectId, scope.runId, scope.stage)]);
+    const latest = new Map();
+    for (const row of rows) {
+        const value = JSON.parse(row.outcome_json);
+        latest.set(value.operation, value);
+    }
+    for (const value of latest.values())
+        if (value.error && !isRegisteredRepair(context, value.error.details.continuation, scope))
+            throw new AppError(value.error.code, value.error.message, 1, { ...value.error.details, operation: value.operation, hook_event_id: value.hook_event_id, continuation_scope: scope });
+}

package/dist/services/controller-fanout.js

@@ -0,0 +1,132 @@
+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";
+function semanticCompletionPrompt(stage, completed) {
+    const task = stage === "plan-review"
+        ? "Classify the reviewer findings, apply every accepted correction in the current PLAN-REVIEW Work, and write the authoritative review decision."
+        : stage === "code-review"
+            ? "Classify the review findings and write or retain the authoritative review decision."
+            : "Integrate the accepted child results and update the Stage's authoritative verification evidence.";
+    return [
+        `All declared ${stage} child Work has settled (${completed} completed).`,
+        task,
+        "Then invoke the exact Stage finish command from the original authoritative packet.",
+        "Only if that command actually returns continuation.kind = repair_required has repair Work been registered; in that case end this Turn immediately so the controller can dispatch it. Otherwise follow the command's actual result.",
+        "Do not create speculative repair Work or start a successor Stage."
+    ].join(" ");
+}
+/** Stage entry acknowledges the packet before the controller issues child commands. */
+export function controllerStageEntryPrompt(stage, command) {
+    return [
+        `Start the assigned ${stage} Stage now. Your first tool call must be this exact standalone command:`,
+        command,
+        "Read the complete authoritative packet from the command's response_file result, 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 (fanout.state === "compatibility_required")
+        throw new AppError("stage_graph_compatibility_required", "The retained graph cannot be dispatched by this controller; use the RUN's pinned engine", 1, { stage: input.stage, run_id: input.runId, graph: fanout });
+    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 = (action, text) => ({ kind: "prompt", action, prompt: text, fingerprint: JSON.stringify({ stage: input.stage, parent: fanout.parent_work_id, state: fanout.state, graph: fanout.graph_revision }) });
+    if (fanout.state === "coordinator_required")
+        return prompt("materialize_graph", `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("repair_or_block", `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("dispatch_work", 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("semantic_completion", semanticCompletionPrompt(input.stage, fanout.works.completed));
+}
+/** 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;