@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/services/controller-work-failure.js

@@ -0,0 +1,198 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { publishImmutableInput } from "../storage/immutable-input.js";
+import { prepareAgentOutputFile } from "../storage/agent-output.js";
+import { parseLifecycleCommand } from "./lifecycle-command.js";
+import { stageAttempt, stageCycle, stageWorkIds } from "./stage-work-graph.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+import { appendEvent, digest } from "./run-controller-state.js";
+import { retryWork } from "./work-registry.js";
+import { blockStageForRuntime } from "./stage-blocker.js";
+import { pauseStageForUser } from "./stage-pause.js";
+/** SQL settlement provenance, never the worker's prose, distinguishes a semantic refusal. */
+export function explicitWorkFailure(context, projectId, runId, workId) {
+    const work = context.db.get("SELECT w.status,w.result,w.parent_work_id,w.payload_json,r.run_root FROM works w JOIN runs r ON r.project_id=w.project_id AND r.id=w.run_id WHERE w.project_id=? AND w.run_id=? AND w.work_id=?", [projectId, runId, workId]);
+    if (!work || work.status !== "failed" || !work.parent_work_id || work.result === null || !work.run_root)
+        return null;
+    const payload = JSON.parse(work.payload_json ?? "null");
+    if (typeof payload?.kind === "string" && /^(memory|interactive)/.test(payload.kind))
+        return null;
+    if (!context.db.get("SELECT 1 FROM sqlite_schema WHERE name='audit_events'") || !context.db.get("SELECT 1 FROM sqlite_schema WHERE name='lifecycle_invocations'"))
+        return null;
+    const resultHash = digestBytes(work.result);
+    const receipts = context.db.all(`SELECT a.payload_json,l.command,l.status AS invocation_status FROM audit_events a JOIN lifecycle_invocations l ON l.id=json_extract(a.payload_json,'$.invocation_id')
+    WHERE a.project_id=? AND a.event_type='lifecycle.work_settlement' AND json_extract(a.payload_json,'$.run_id')=? AND json_extract(a.payload_json,'$.work_id')=? ORDER BY a.rowid DESC`, [projectId, runId, workId]);
+    for (const row of receipts) {
+        const receipt = JSON.parse(row.payload_json), parsed = parseLifecycleCommand(row.command);
+        if (row.invocation_status !== "settled" || parsed.kind !== "standalone" || parsed.invocation.operation !== "work_fail" || receipt.result_sha256 !== resultHash || receipt.response?.status !== "failed")
+            continue;
+        if (!context.db.get("SELECT 1 FROM work_sessions WHERE id=? AND work_id=? AND status='failed'", [receipt.work_session_id, workId]))
+            continue;
+        return { work_id: workId, work_session_id: receipt.work_session_id, parent_work_id: work.parent_work_id, result_sha256: resultHash, primary_reason: work.result, result_ref: path.join(work.run_root, "works", workId, "result.json") };
+    }
+    return null;
+}
+import { createHash } from "node:crypto";
+const digestBytes = (text) => createHash("sha256").update(text).digest("hex");
+function events(context, row, type) {
+    return context.db.all(`SELECT e.data_json FROM run_controller_events e JOIN run_controllers c ON c.controller_id=e.controller_id WHERE c.project_id=? AND c.run_id=? AND e.event_type=? ORDER BY e.rowid`, [row.project_id, row.run_id, type]).map(e => JSON.parse(e.data_json));
+}
+export function prepareWorkFailureResolution(context, row, stage, failure) {
+    if (!stageWorkIds(context, row.project_id, row.run_id, stage).has(failure.work_id))
+        throw new AppError("work_failure_scope_changed", "Failed Work no longer belongs to this Stage", 1);
+    const current = explicitWorkFailure(context, row.project_id, row.run_id, failure.work_id);
+    if (!current || current.work_session_id !== failure.work_session_id || current.result_sha256 !== failure.result_sha256)
+        throw new AppError("work_failure_scope_changed", "Failed Work receipt changed before resolution", 1);
+    const attempt = stageAttempt(context, row.project_id, row.run_id, stage), cycle = stageCycle(context, row.project_id, row.run_id, stage);
+    const episode = digest([row.project_id, row.run_id, stage, attempt, cycle, failure.work_id, failure.work_session_id, failure.result_sha256]);
+    const run = context.db.get("SELECT run_root FROM runs WHERE project_id=? AND id=?", [row.project_id, row.run_id]);
+    const round = events(context, row, "work_failure_action_applied").filter(e => e.episode_id === episode).length;
+    const root = path.join(run.run_root, "work-failure-resolutions", episode, `round-${round}`);
+    const resolution = { ...failure, episode_id: episode, stage, attempt, cycle, decision_file: path.join(root, "decision-input.json"), accepted_file: path.join(root, "decision.json"), diagnostic_file: path.join(root, "failure.json"),
+        retry_used: events(context, row, "work_failure_action_reserved").some(e => e.action === "retry" && e.work_id === failure.work_id) };
+    fs.mkdirSync(root, { recursive: true });
+    publishImmutableInput(resolution.diagnostic_file, Buffer.from(JSON.stringify({ schema_id: "work-failure-context@1", ...failure, episode_id: episode, stage, attempt, cycle, packet: path.join(run.run_root, "works", failure.work_id, "starts") }, null, 2)), "work_failure_context_changed");
+    if (!fs.existsSync(resolution.decision_file)) {
+        prepareAgentOutputFile(resolution.decision_file);
+        fs.writeFileSync(resolution.decision_file, "", { flag: "wx", mode: 0o600 });
+    }
+    return resolution;
+}
+const text = (value) => typeof value === "string" && value.trim().length > 0;
+export function readFailureDecision(resolution) {
+    const file = fs.existsSync(resolution.accepted_file) ? resolution.accepted_file : resolution.decision_file;
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+        throw new AppError("work_failure_decision_invalid", "Expected a regular decision JSON file", 2);
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        throw new AppError("work_failure_decision_invalid", "Write one complete decision JSON object", 2);
+    }
+    const keys = ["schema_id", "episode_id", "action", "reason", "evidence_refs", "correction", "blocker", "question"];
+    if (!value || Array.isArray(value) || typeof value !== "object" || Object.keys(value).some(k => !keys.includes(k)) || value.schema_id !== "work-failure-decision@1" || value.episode_id !== resolution.episode_id || !["retry", "block", "pause", "fail"].includes(value.action) || !text(value.reason) || !Array.isArray(value.evidence_refs) || !value.evidence_refs.length || !value.evidence_refs.every(text)
+        || value.action === "retry" && !text(value.correction) || value.action === "pause" && !text(value.question)
+        || value.action === "block" && (!value.blocker || !["engine", "harness", "environment"].includes(value.blocker.kind) || !text(value.blocker.code) || !text(value.blocker.summary) || typeof value.blocker.retryable !== "boolean" || Object.keys(value.blocker).some(k => !["kind", "code", "summary", "retryable"].includes(k)))
+        || value.action !== "retry" && value.correction !== undefined || value.action !== "pause" && value.question !== undefined || value.action !== "block" && value.blocker !== undefined)
+        throw new AppError("work_failure_decision_invalid", "Decision must match its episode and selected action", 2, { episode_id: resolution.episode_id });
+    return value;
+}
+export function failureDecisionReady(resolution) { try {
+    readFailureDecision(resolution);
+    return true;
+}
+catch {
+    return false;
+} }
+export function workFailureResolutionPrompt(resolution, diagnostic) {
+    return [`Resolve only the retained explicit worker refusal in ${resolution.diagnostic_file}. Read that complete file and its Work packet/results.`,
+        "Current implementation is a baseline, not a requirement. Necessary project-local cross-layer corrections are allowed within accepted scope; planned write areas are hints. A worker-authored stop condition cannot silently cancel accepted intent. Do not edit product files, call lifecycle commands, spawn children or run checks in this decision Turn.",
+        `Write the decision to this precreated absolute file: ${resolution.decision_file}. No other writes. Return after writing it.`,
+        `Use schema_id=work-failure-decision@1, episode_id=${resolution.episode_id}, action=retry|block|pause|fail, nonempty reason and evidence_refs[]. For retry include concrete correction; for block include blocker {kind:engine|harness|environment,code,summary,retryable:boolean}; for pause include question. No extra fields.`,
+        resolution.retry_used ? "The one automatic corrective attempt has already been consumed. Select block/pause/fail; another retry cannot be applied automatically." : "Select retry if the Work can be completed in accepted scope; a fresh worker receives your correction. Select pause only for genuinely missing user intent, block for a proven technical dependency, fail only for an explained terminal outcome.",
+        "An unsupported exact browser key sequence does not prove all UI work is impossible and selectOption is not keyboard evidence. Preserve unverified mandatory criteria and original requirements.", diagnostic ? `Correct only the rejected decision: ${diagnostic}` : ""].filter(Boolean).join("\n\n");
+}
+export function acceptFailureDecision(context, row, resolution, assertOwner) {
+    assertOwner();
+    const decision = readFailureDecision(resolution), bytes = Buffer.from(JSON.stringify(decision));
+    publishImmutableInput(resolution.accepted_file, bytes, "work_failure_decision_changed");
+    context.db.writeTransaction(() => { assertOwner(); if (!events(context, row, "work_failure_decision_accepted").some(e => e.decision_ref === resolution.accepted_file))
+        appendEvent(context, row.controller_id, "work_failure_decision_accepted", { episode_id: resolution.episode_id, work_id: resolution.work_id, decision_ref: resolution.accepted_file, decision }); });
+    return decision;
+}
+export function workFailureDiagnostic(resolution, decision) {
+    return { source: "explicit_work_failure", episode_id: resolution.episode_id, work_id: resolution.work_id, work_session_id: resolution.work_session_id, result_ref: resolution.diagnostic_file, primary_reason: resolution.primary_reason, ...(decision ? { disposition: decision } : {}) };
+}
+/** Repair file-before-event and mutation-before-ack crash windows before HITL delivery. */
+export async function reconcilePendingWorkFailure(context, row, state, continuationKind, projectRoot, assertOwner, writerSettled) {
+    const resolution = state.work_failure;
+    if (!resolution || resolution.deferred || !fs.existsSync(resolution.accepted_file) || continuationKind === "terminal")
+        return "none";
+    const session = state.current_session === null ? undefined : state.sessions[state.current_session];
+    if (!session)
+        throw new AppError("work_failure_scope_changed", "Failure resolution lost its coordinator", 1);
+    if (!await writerSettled(session))
+        return "waiting";
+    const decision = acceptFailureDecision(context, row, resolution, assertOwner);
+    applyWorkFailureDecision(context, row, resolution, decision, projectRoot, assertOwner);
+    delete state.work_failure;
+    state.last_continuation = null;
+    return "applied";
+}
+/** Reserve first; a committed retry is recovered through its start authority, never replayed blindly. */
+export function applyWorkFailureDecision(context, row, resolution, decision, projectRoot, assertOwner) {
+    assertOwner();
+    assertRunMutationAllowed(context, row.project_id, row.run_id, row.generation);
+    const index = JSON.parse(context.db.get("SELECT index_json FROM runs WHERE project_id=? AND id=?", [row.project_id, row.run_id])?.index_json ?? "{}");
+    if (resolution.stage !== index.current_stage
+        || resolution.attempt !== stageAttempt(context, row.project_id, row.run_id, resolution.stage) || resolution.cycle !== stageCycle(context, row.project_id, row.run_id, resolution.stage)
+        || !stageWorkIds(context, row.project_id, row.run_id, resolution.stage).has(resolution.work_id))
+        throw new AppError("work_failure_scope_changed", "Failure resolution belongs to a stale Stage attempt", 1);
+    const applied = events(context, row, "work_failure_action_applied").find(e => e.decision_ref === resolution.accepted_file);
+    if (applied)
+        return applied;
+    const reserved = events(context, row, "work_failure_action_reserved").find(e => e.decision_ref === resolution.accepted_file);
+    const current = context.db.get("SELECT status,current_start_invocation_id FROM works WHERE project_id=? AND run_id=? AND work_id=?", [row.project_id, row.run_id, resolution.work_id]);
+    if (!current)
+        throw new AppError("work_failure_scope_changed", "Work disappeared before resolution", 1);
+    let action = decision.action;
+    const used = events(context, row, "work_failure_action_reserved").some(e => e.action === "retry" && e.work_id === resolution.work_id && e.decision_ref !== resolution.accepted_file);
+    const retainedDecision = events(context, row, "work_failure_decision_accepted").find(e => e.decision_ref === resolution.accepted_file);
+    if (!retainedDecision || JSON.stringify(retainedDecision.decision) !== JSON.stringify(decision))
+        throw new AppError("work_failure_scope_changed", "Failure decision was not accepted or changed after acceptance", 1);
+    const exhausted = action === "retry" && used;
+    if (exhausted)
+        action = "block";
+    if (!reserved) {
+        if (current.status !== "failed" || explicitWorkFailure(context, row.project_id, row.run_id, resolution.work_id)?.work_session_id !== resolution.work_session_id)
+            throw new AppError("work_failure_scope_changed", "Failure changed before action reservation", 1);
+        context.db.writeTransaction(() => { assertOwner(); appendEvent(context, row.controller_id, "work_failure_action_reserved", { episode_id: resolution.episode_id, work_id: resolution.work_id, work_session_id: resolution.work_session_id, action, decision_ref: resolution.accepted_file }); });
+    }
+    else if (reserved.action !== action)
+        throw new AppError("work_failure_scope_changed", "Reserved failure action differs", 1);
+    let receipt;
+    if (action === "retry") {
+        receipt = retryWork(context, resolution.work_id, decision.reason, { episode_id: resolution.episode_id, decision_ref: resolution.accepted_file, correction: decision.correction, failed_result_sha256: resolution.result_sha256 });
+    }
+    else if (action === "fail")
+        throw new AppError("work_failure_unresolved", decision.reason, 1, workFailureDiagnostic(resolution, decision));
+    else {
+        const coordinator = context.db.get("SELECT status FROM works WHERE project_id=? AND run_id=? AND work_id=?", [row.project_id, row.run_id, resolution.parent_work_id]);
+        const blocker = exhausted ? { kind: "engine", code: "work_resolution_exhausted", summary: JSON.stringify(workFailureDiagnostic(resolution, decision)), retryable: false } : decision.blocker;
+        const boundBlocker = blocker ? { ...blocker, summary: `${blocker.summary}\n[work-failure:${resolution.episode_id}:${digest(resolution.accepted_file)}]` } : undefined;
+        if (coordinator?.status === "paused" && reserved) {
+            const stage = index.stage_runs?.find((s) => s.stage === resolution.stage);
+            const matches = action === "pause" ? stage?.pause?.work_id === resolution.parent_work_id && typeof stage.pause.question_path === "string" && fs.readFileSync(stage.pause.question_path, "utf8") === decision.question
+                : stage?.blocker?.work_id === resolution.parent_work_id && stage.blocker.code === boundBlocker?.code && stage.blocker.kind === boundBlocker?.kind && stage.blocker.summary === boundBlocker?.summary;
+            if (!matches)
+                throw new AppError("work_failure_scope_changed", "Coordinator pause belongs to another failure action", 1);
+            receipt = { ok: true, reconciled: true, outcome: action === "pause" ? "paused" : "blocked", run_id: row.run_id, stage: resolution.stage, work_id: resolution.parent_work_id, ...(boundBlocker ? { blocker: boundBlocker } : {}) };
+        }
+        else {
+            if (coordinator?.status !== "running")
+                throw new AppError("work_failure_scope_changed", "Failure resolution needs the running coordinator Work", 1);
+            const scope = { projectRoot, runId: row.run_id, stage: resolution.stage, workId: resolution.parent_work_id };
+            receipt = action === "pause" ? pauseStageForUser(context, { ...scope, question: decision.question }) : blockStageForRuntime(context, { ...scope, ...boundBlocker });
+        }
+    }
+    const outcome = { episode_id: resolution.episode_id, decision_ref: resolution.accepted_file, stage: resolution.stage, attempt: resolution.attempt, cycle: resolution.cycle, work_id: resolution.work_id, work_session_id: resolution.work_session_id, action, receipt };
+    context.db.writeTransaction(() => { assertOwner(); appendEvent(context, row.controller_id, "work_failure_action_applied", outcome); });
+    return outcome;
+}
+/** Match only this current bound block; an old unrelated pause must not be hidden. */
+export function workFailureBlockActive(context, row, index) {
+    const stage = index.current_stage;
+    const blocker = index.stage_runs?.find(s => s.stage === stage)?.blocker;
+    if (!stage || !blocker)
+        return false;
+    return events(context, row, "work_failure_action_applied").some(e => {
+        const receipt = e.receipt;
+        if (!receipt)
+            return false;
+        return e.action === "block" && e.stage === stage && e.attempt === stageAttempt(context, row.project_id, row.run_id, stage) && e.cycle === stageCycle(context, row.project_id, row.run_id, stage)
+            && receipt?.work_id === blocker.work_id && receipt.blocker?.summary === blocker.summary && receipt.blocker?.code === blocker.code && receipt.blocker?.kind === blocker.kind;
+    });
+}

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,22 @@ export function refreshAllDashboards(context, input = {}) {
 }
 export function autoRefreshDashboards(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const config = readProjectConfig(context, project.id);
+    // Hooks and usage ingestion continue to record receipts after capture.
+    // Their derived timestamp must not mutate the captured workspace.
+    if (projectRecoveryGuarded(context, project.id))
+        return { ok: true, skipped: true, reason: "run_recovery_guarded" };
+    const configured = readProjectConfig(context, project.id);
+    // Automatic observation must not change a memory/diagnostic baseline or
+    // invalidate accepted delivery checks by rewriting workspace projections.
+    // Keep projections in Home; do not hide runtime-created paths in Git or
+    // weaken source preservation by excluding user-owned .tasks directories.
+    const initializing = context.db.get("SELECT 1 FROM runs WHERE project_id=? AND (flow_kind IN ('mb-init','mb-upgrade','mb-fix','mb-audit','project-review','review-fix','interactive') OR flow_kind='mb-distill' AND json_extract(index_json,'$.execution_bundle.flow_id')='mb-distill' OR flow_kind IN ('release','deploy','publish') AND json_extract(index_json,'$.execution_bundle.flow_id')=flow_kind) 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 +249,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 +277,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 +294,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 +315,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 +326,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 +364,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 +394,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 +428,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 +974,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 +989,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;
@@ -1222,6 +1308,7 @@ function normalizeFlowKind(flowKind) {
         "mb-upgrade",
         "mb-audit",
         "mb-fix",
+        "review-fix",
         "mb-distill",
         "mb-upgrade-review",
         "mb-sdlc-review",