@deksden-com/dd-flow-cli 0.9.0-beta.74 → 0.9.0-beta.79

package/dist/services/cleanup.js

@@ -2,8 +2,7 @@ import fs from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-import { parseJsonObject } from "../shared/json.js";
-import { ensureReadableFile } from "../storage/database.js";
+import { prepareJsonFile } from "../cli/input-preparation.js";
 import { projectCheckoutRoot, resolveProjectRoot, runtimeStateJsonPath } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
@@ -173,20 +172,29 @@ export function cleanupScan(context, input) {
         plan: { project_root: project.root, project_id: project.id, actions }
     };
 }
-export function cleanupApply(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+export function prepareCleanupApply(context, input) {
     const reason = input.reason.trim();
     if (!reason) {
         throw new AppError("validation", "cleanup apply requires --reason", 2);
     }
-    ensureReadableFile(input.planFile);
-    const plan = validateCleanupPlan(parseJsonObject(fs.readFileSync(input.planFile, "utf8"), input.planFile), project);
+    const value = prepareJsonFile(input.planFile, "cleanup plan").value;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new AppError("validation", "cleanup plan must be an object", 2);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const plan = validateCleanupPlan(value, project);
     validateNoDestructiveSurprises(context, plan, input.force);
+    return { project, reason, plan };
+}
+export function cleanupApply(context, input) {
+    const { project, reason, plan } = input.prepared ?? prepareCleanupApply(context, input);
     const now = context.now();
     const results = [];
     context.db.beginWriteTransaction();
+    let executing = false;
     try {
+        validateNoDestructiveSurprises(context, plan, input.force);
         for (const action of plan.actions) {
+            executing = true;
             results.push(applyAction(context, action, reason, input.force, now));
         }
         const changed = results.filter((result) => result.changed).length;
@@ -203,6 +211,8 @@ export function cleanupApply(context, input) {
     }
     catch (error) {
         context.db.exec("ROLLBACK");
+        if (executing)
+            throw new AppError("cleanup_apply_failed", "Cleanup failed after execution began; inspect retained artifacts before retrying", 1, { effect: "unknown", database_rolled_back: true, attempted_results: results, cause: error instanceof Error ? error.message : String(error), ...(error instanceof AppError ? { cause_code: error.code } : {}) });
         throw error;
     }
     return {
@@ -251,11 +261,29 @@ function validateCleanupPlan(value, project) {
                 throw new AppError("validation", "close_flow_session requires a native session identity", 2);
             }
         }
+        const requiredField = action.kind === "discard_stale_run" ? "run_id"
+            : ["repair_protocol_state", "cancel_queue_job", "close_worktree_record"].includes(String(action.kind)) ? "protocol_id" : undefined;
+        if (requiredField && (typeof action[requiredField] !== "string" || !action[requiredField].trim()))
+            throw new AppError("validation", `cleanup ${String(action.kind)} requires ${requiredField}`, 2);
+        const numericField = action.kind === "expire_lane_lock" ? "lock_id" : action.kind === "expire_lane_waiter" ? "waiter_id" : undefined;
+        if (numericField && (!Number.isSafeInteger(action[numericField]) || action[numericField] < 1))
+            throw new AppError("validation", `cleanup ${String(action.kind)} requires a positive integer ${numericField}`, 2);
+        if (action.worktree_path !== undefined && (typeof action.worktree_path !== "string" || !path.isAbsolute(action.worktree_path)))
+            throw new AppError("validation", "cleanup worktree_path must be an absolute path", 2);
         return action;
     });
     return { project_root: project.root, project_id: project.id, actions };
 }
 function validateNoDestructiveSurprises(context, plan, force) {
+    for (const action of plan.actions) {
+        if (action.kind === "repair_protocol_state")
+            requireProtocol(context, action.protocol_id, action.project_id);
+        if (action.kind === "discard_stale_run") {
+            const run = context.db.get("SELECT index_json, status FROM runs WHERE project_id = ? AND id = ?", [action.project_id, action.run_id]);
+            if (run && ["running", "discarded"].includes(run.status))
+                cleanupRunIndex(run.index_json);
+        }
+    }
     const destructive = plan.actions.find((action) => action.kind === "close_worktree_record" && action.worktree_path && dirtyGit(action.worktree_path));
     if (destructive && !force) {
         throw new AppError("worktree_dirty", "cleanup apply refuses dirty worktree actions without --force --reason", 1, {
@@ -410,7 +438,7 @@ function applyAction(context, action, reason, force, now) {
     return { kind: action.kind, changed: false, skipped: true, reason: "invalid_action" };
 }
 function discardedRunIndex(indexJson, reason, now) {
-    const index = JSON.parse(indexJson);
+    const index = cleanupRunIndex(indexJson);
     index.schema_id = "dd-flow/flow-run@3";
     index.status = "discarded";
     index.verdict = "discarded";
@@ -420,12 +448,25 @@ function discardedRunIndex(indexJson, reason, now) {
     index.finished_at ??= now;
     return index;
 }
+function cleanupRunIndex(indexJson) {
+    try {
+        const index = JSON.parse(indexJson);
+        if (!index || typeof index !== "object" || Array.isArray(index))
+            throw new Error("RUN index must be an object");
+        return index;
+    }
+    catch (error) {
+        throw new AppError("runtime_state_invalid", "Cleanup cannot read retained RUN state", 1, { cause: String(error) });
+    }
+}
 function dirtyGit(worktreePath) {
     if (!fs.existsSync(worktreePath)) {
         return false;
     }
     const result = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { encoding: "utf8" });
-    return result.status === 0 && result.stdout.trim().length > 0;
+    if (result.error || result.status !== 0)
+        throw new AppError("workspace_status_failed", "Cannot establish worktree status before cleanup", 1, { path: worktreePath, cause: result.error?.message ?? result.stderr });
+    return result.stdout.trim().length > 0;
 }
 function safeCleanupWorktreePath(context, projectId, worktreePath) {
     if (!fs.existsSync(worktreePath)) {

package/dist/services/cli-operation-classifier.js

@@ -1,3 +1,4 @@
+import { parseCommandArgs } from "./lifecycle-command.js";
 export function classifyCliOperation(args, env = process.env) {
     const positional = positionalArgs(args);
     const [family = null, command = null, action = null] = positional;
@@ -14,19 +15,7 @@ export function classifyCliOperation(args, env = process.env) {
     return { mode: "normal_write", operation, family, command, action };
 }
 function positionalArgs(args) {
-    const positional = [];
-    for (let index = 0; index < args.length; index += 1) {
-        const value = args[index];
-        if (!value)
-            continue;
-        if (value.startsWith("--")) {
-            if (!value.includes("=") && args[index + 1] && !args[index + 1]?.startsWith("--"))
-                index += 1;
-            continue;
-        }
-        positional.push(value);
-    }
-    return positional;
+    return parseCommandArgs(args).positional;
 }
 export function isReadOnlyCliOperation(args, env = process.env) {
     return classifyCliOperation(args, env).mode === "read_only_diagnostics";
@@ -57,7 +46,7 @@ function isMbUpgradeMode(args, env) {
     }
     return marked && isUpgradeAllowlisted(args);
 }
-function isUpgradeAllowlisted(args) {
+export function isUpgradeAllowlisted(args) {
     const positional = positionalArgs(args);
     const [family, command] = positional;
     if (family === "status")
@@ -82,14 +71,9 @@ function hasRunBinding(args) {
     return Boolean(optionValue(args, "run") || positionalArgs(args).some((value) => value.startsWith("RUN-")));
 }
 function optionValue(args, name) {
-    for (let index = args.length - 1; index >= 0; index -= 1) {
-        const arg = args[index];
-        if (arg === `--${name}`)
-            return args[index + 1] ?? null;
-        if (arg?.startsWith(`--${name}=`))
-            return arg.slice(name.length + 3);
-    }
-    return null;
+    const values = parseCommandArgs(args).options.get(name);
+    const value = values?.[values.length - 1];
+    return value && value !== "__dd_flow_flag__" ? value : null;
 }
 function isRouterNative(args) {
     const first = args[0];
@@ -125,13 +109,17 @@ function isReadOnlyDiagnostic(family, command, action) {
     if (family === "canon")
         return command === "status" || command === "resolve";
     if (family === "project")
-        return command === "status" || command === "resolve";
+        return command === "status" || command === "resolve" || (command === "config" && action === "status");
     if (family === "protocol")
         return ["status", "branch-status", "ready", "blockers", "implement"].includes(command ?? "");
     if (family === "plan")
         return command === "status";
     if (family === "run")
-        return command === "status" || command === "list" || (command === "recovery" && action === "inspect") || (["drive", "control"].includes(command ?? "") && action === "status");
+        return ["status", "list", "timeline"].includes(command ?? "") || (["config", "flags", "drive", "control"].includes(command ?? "") && action === "status") || (command === "vars" && ["ls", "get"].includes(action ?? "")) || (command === "recovery" && action === "inspect");
+    if (family === "runtime" && command === "process" && ["status", "check-admission"].includes(action ?? ""))
+        return true;
+    if (family === "runtime" && command === "scope" && action === "status")
+        return true;
     if (family === "work")
         return ["status", "ls", "show"].includes(command ?? "");
     if (family === "stage")

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

@@ -3,6 +3,7 @@ import { getVnextFanoutStatus, observeVnextNativeChildren, reconcileVnextFanout,
 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 [
@@ -11,7 +12,7 @@ export function controllerStageEntryPrompt(stage, command, responseFile) {
         `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.",
-        "Copy runtime-issued lifecycle commands verbatim as standalone calls. Never generate an invocation ID, substitute a shell variable for it, or borrow one from another command. If a required command is missing or rejected without a returned retry command, report the exact error and end the Turn so the controller can handle it."
+        "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. */
@@ -63,21 +64,16 @@ export async function nextControllerFanout(context, input) {
         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);
-        return prompt([
-            `Launch exactly ${wave.length} direct native children for the current ${input.stage} Stage; the recorded capacity is ${capacity}.`,
-            "Use this harness's native child mechanism, not external roots or forks. Wait for these children to settle; do not cancel siblings because one failed. Do not finish this Stage or start a successor in this Turn.",
-            ...wave.map(work => {
-                if (!work.work_id || !work.start_command)
-                    throw new AppError("fanout_contract_invalid", "Ready Work omits its trusted start command", 1);
-                return `Assign one leaf child Work ${work.work_id}. ${work.launch_policy === "fresh_agent_required" ? "Use empty, non-inherited context when supported; a new Session id alone does not prove empty context." : "Inherit context only through the harness's declared mechanism."}\nIts first technical action must be this exact standalone command:\n${work.start_command}\nUse only the Work packet returned by it. Complete its declared result and exact work finish command, then stop. Do not create children or start another Work. Missing facts go through the Work's failure/result contract; only the coordinator handles Stage HITL.`;
-            })
-        ].join("\n\n"));
+        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. Execute an exact repair command returned by a rejected stage finish; a rejection alone does not create repair Work. Return after finish or after declaring a repair graph. Do not start a successor Stage.`);
+    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) {

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,44 +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,
@@ -64,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 {
@@ -76,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") {
@@ -95,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,
@@ -145,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) {
@@ -180,6 +218,7 @@ export function autoRefreshDashboards(context, input) {
     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 });
@@ -291,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") {
@@ -303,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,
@@ -330,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 {
@@ -353,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);
@@ -897,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 {
@@ -912,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;