@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.140

package/dist/services/controller-fanout.js

@@ -0,0 +1,202 @@
+import { AppError, errorRecord } from "../shared/errors.js";
+import { normalizeNativeChildren, safeNativeFailure } from "../harness-runtime/lib/native-children.mjs";
+import { getVnextFanoutStatus, observeVnextNativeChildren, reconcileVnextFanout, getStageFanoutCapacity, verifiedNativeWorkFailure } from "./vnext-fanout.js";
+import { dispatchVnextPlanReview } from "./vnext-plan-review.js";
+import { resolveExecutionPolicy } from "./execution-policy.js";
+import { lifecycleCommandCompletionInstruction, renderDelegationInstructions, stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { assertWorkLaunchReady, workStartCommand } from "./work-registry.js";
+import { prepareMemoryNativeReviewCopy } from "./memory-native-review-copy.js";
+import { registerMemoryRepairBaselineFromStage, reserveMemoryRepairWriterCopyFromStage, materializeMemoryRepairWriterCopyFromStage, prepareMemoryRepairDispatchFromStage, registerMemorySecondRepairBaselineFromStage, reserveMemorySecondRepairCopyFromStage, materializeMemorySecondRepairCopyFromStage, prepareMemorySecondRepairDispatchFromStage, registerMemoryRepairCurrentViewFromStage, registerMemorySecondRepairCurrentViewFromStage } from "./memory-review-handler.js";
+import { requireProjectByRoot } from "./projects.js";
+import { stageAttempt, stageWorkIds } from "./stage-work-graph.js";
+import { runtimeCommand } from "./runtime-command.js";
+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.",
+        "If that command returns either outcome = repair_required with a repair Work ID, or error.details.continuation.kind = repair_required, the repair Work is already registered. End this Turn 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.",
+        stageLifecycleInstruction
+    ].join("\n\n");
+}
+export function controllerStageResumePrompt(pauseId, command) {
+    return [
+        `The user supplied the raw answer for pause ${pauseId}. Your first tool call must be this exact standalone command:`,
+        command,
+        "Do not alter the answer. Follow the returned packet, then stop at this Stage boundary.",
+        stageLifecycleInstruction
+    ].join("\n\n");
+}
+/** The shared controller owns this former eval-only Work-graph decision. */
+export async function nextControllerFanout(context, input) {
+    // Tree settlement is not a Work result. Keep these children visible to the
+    // association check, especially when a hook rejected work start before CLI.
+    const children = input.children;
+    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) {
+        if (input.dispatchFence)
+            throw new AppError("fanout_reconciliation_required", "Observed native failure has no current graph; dispatch stays fenced", 1, { stage: input.stage, run_id: input.runId });
+        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 => !["child_check_in_progress", "child_capacity_pending"].includes(issue.code));
+        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 (input.dispatchFence && !fanout.works.failed)
+        throw new AppError("fanout_reconciliation_required", "Observed native failure has no proven failed Work; dispatch stays fenced", 1, { stage: input.stage, run_id: input.runId });
+    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: action === "dispatch_work" ? text : `${text}\n\n${lifecycleCommandCompletionInstruction}`, 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, declaring real dependencies at registration. If the packet's CLI command registers the graph, use its returned Work graph unchanged: do not add or alter dependencies after registration. Accepted predecessor Stages already fence their completed producers; do not add cross-stage edges merely to restate input provenance. 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) {
+        const projectId = requireProjectByRoot(context, input.projectRoot).id;
+        const members = stageWorkIds(context, projectId, input.runId, input.stage);
+        const failures = context.db.all("SELECT work_id,status,result FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id = ? AND status IN ('failed','cancelled')", [projectId, input.runId, fanout.parent_work_id]).filter(work => members.has(work.work_id)).map(work => {
+            let receipt = {};
+            try {
+                const value = work.result ? JSON.parse(work.result) : null;
+                if (value && typeof value === "object" && !Array.isArray(value))
+                    receipt = value;
+            }
+            catch { /* Missing legacy metadata is unknown. */ }
+            const providerError = safeNativeFailure(receipt.provider_error);
+            const nativeBinding = verifiedNativeWorkFailure(context, { projectRoot: input.projectRoot, runId: input.runId, stage: input.stage, parentSessionId: input.sessionId, parentWorkId: fanout.parent_work_id, workId: work.work_id, receipt });
+            return { work_id: work.work_id, status: work.status, ...(providerError ? { provider_error: providerError } : {}),
+                ...(nativeBinding ? { native_binding: nativeBinding } : {}),
+                ...Object.fromEntries(["terminal_turn_id", "terminal_observed_at"].filter(key => typeof receipt[key] === "string" && receipt[key].length <= 256).map(key => [key, receipt[key]])) };
+        });
+        throw new AppError("fanout_child_failed", "A child Work failed or was cancelled; no retry authority has been issued", 1, { stage: input.stage, run_id: input.runId, parent_work_id: fanout.parent_work_id, failed: fanout.works.failed, cancelled: fanout.works.cancelled, failures, effect: "unknown" });
+    }
+    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 prepareRepair = (work) => {
+            const row = context.db.get("SELECT payload_json,result_schema FROM works WHERE work_id=?", [work.work_id]);
+            const payload = JSON.parse(row?.payload_json ?? "null");
+            if (payload?.kind !== "memory-repair" || row?.result_schema !== "dd-flow/memory-repair-work-result@1")
+                return null;
+            const scope = { projectRoot: input.projectRoot, runId: input.runId, workId: work.work_id };
+            const second = payload.memory_repair?.wave === 2;
+            if (!second && payload.memory_repair?.wave !== 1)
+                throw new AppError("fanout_contract_invalid", "Memory repair wave is invalid", 1);
+            const registerBaseline = second ? registerMemorySecondRepairBaselineFromStage : registerMemoryRepairBaselineFromStage;
+            try {
+                registerBaseline(context, scope);
+            }
+            catch (error) {
+                const missing = error instanceof AppError && (second
+                    ? error.code === "memory_second_repair_source_invalid" && error.details.reason === "registered_second_current_view_required"
+                    : error.code === "memory_review_handler_invalid" && error.details.reason === "current_view_registration_required");
+                if (!missing)
+                    throw error;
+                (second ? registerMemorySecondRepairCurrentViewFromStage : registerMemoryRepairCurrentViewFromStage)(context, scope);
+                registerBaseline(context, scope);
+            }
+            (second ? reserveMemorySecondRepairCopyFromStage : reserveMemoryRepairWriterCopyFromStage)(context, scope);
+            (second ? materializeMemorySecondRepairCopyFromStage : materializeMemoryRepairWriterCopyFromStage)(context, scope);
+            return (second ? prepareMemorySecondRepairDispatchFromStage : prepareMemoryRepairDispatchFromStage)(context, scope);
+        };
+        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));
+            const selected = external.slice(0, maximum).map(choice => choice.work);
+            for (const work of selected)
+                prepareRepair(work);
+            return { kind: "external", works: selected };
+        }
+        const capacity = getStageFanoutCapacity(context, { ...input, nativeOnly: true }).available_slots;
+        if (typeof capacity !== "number" || !Number.isInteger(capacity) || capacity < 1)
+            return { kind: "wait", reason: "qualified_capacity_required" };
+        const wave = choices.slice(0, capacity).map(choice => {
+            const work = choice.work;
+            const row = context.db.get("SELECT payload_json,result_schema FROM works WHERE work_id=?", [work.work_id]);
+            const payload = JSON.parse(row?.payload_json ?? "null");
+            if (payload?.kind === "memory-review" && row?.result_schema === "dd-flow/memory-review-work-result@1") {
+                const copy = prepareMemoryNativeReviewCopy(context, work.work_id, true);
+                return { ...work, start_command: `cd '${copy.root.replaceAll("'", "'\\''")}' && ${workStartCommand(context, assertWorkLaunchReady(context, work.work_id))}` };
+            }
+            const packet = prepareRepair(work);
+            const command = workStartCommand(context, assertWorkLaunchReady(context, work.work_id));
+            if (!packet)
+                return { ...work, start_command: command };
+            // Ordinary literal shell grammar, not an invented native spawn CWD field.
+            const quotedRoot = "'" + packet.copy_root.replaceAll("'", "'\\''") + "'";
+            return { ...work, start_command: `cd ${quotedRoot} && ${command}` };
+        });
+        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);
+        const totalWorks = fanout.works.created + fanout.works.running + fanout.works.completed + fanout.works.failed + fanout.works.cancelled;
+        return prompt("dispatch_work", renderDelegationInstructions({ harness: input.harness, stage: input.stage, capacity, works: wave, totalWorks, remainingWorks: fanout.works.created - wave.length }));
+    }
+    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);
+    if (input.stage === "review") {
+        const projectId = requireProjectByRoot(context, input.projectRoot).id;
+        const run = context.db.get("SELECT flow_kind FROM runs WHERE project_id=? AND id=?", [projectId, input.runId]);
+        if (run?.flow_kind === "mb-init") {
+            const attempt = stageAttempt(context, projectId, input.runId, "review");
+            const repair = context.db.get(`SELECT CASE event_type WHEN 'memory.second_repair_registration' THEN 2 ELSE 1 END AS wave
+        FROM audit_events WHERE project_id=? AND event_type IN ('memory.repair_registration','memory.second_repair_registration')
+        AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.attempt')=?
+        AND json_extract(payload_json,'$.scope.parent_work_id')=? ORDER BY wave DESC LIMIT 1`, [projectId, input.runId, attempt, fanout.parent_work_id]);
+            if (repair && !context.db.get(`SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.corrected_review_registration'
+        AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.attempt')=?
+        AND json_extract(payload_json,'$.scope.parent_work_id')=? AND json_extract(payload_json,'$.wave')=?`, [projectId, input.runId, attempt, fanout.parent_work_id, repair.wave])) {
+                const args = ["--run", input.runId, "--project-root", input.projectRoot, "--wave", String(repair.wave), "--json"];
+                return prompt("semantic_completion", `Correction wave ${repair.wave} Work has settled. Before Stage finish, run ${runtimeCommand(context, ["memory", "corrections", "checks", ...args])}, then ${runtimeCommand(context, ["memory", "review", "selective-register", ...args])}. Read both complete responses, then end this Turn so the controller can dispatch the independent selective reviewers. Do not finish the Stage or treat repair Work completion as independent acceptance.`);
+            }
+        }
+    }
+    return prompt("semantic_completion", semanticCompletionPrompt(input.stage, fanout.works.completed));
+}
+/** Shared pinned runtime normalization; preserve structured errors at the TS boundary. */
+export function controllerNativeChildren(receipt, rootSessionId) {
+    try {
+        return normalizeNativeChildren(receipt, rootSessionId);
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        throw Object.assign(new AppError(record.code, record.message, record.exitCode, record.details), record);
+    }
+}

package/dist/services/dashboard.js

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