@deksden-com/dd-flow-cli 0.2.0 → 0.3.1

package/dist/cli/run-cli.js

@@ -3,24 +3,31 @@ import { helpForArgs } from "./help.js";
 import { AppError, isAppError } from "../shared/errors.js";
 import { writeJson } from "../shared/json.js";
 import { archiveProject, getProjectStatus, migrateProjectIds, registerProject, resolveProject } from "../services/projects.js";
-import { cancelProtocol, getProtocolStatus, readyForMerge, registerProtocol, requireProtocol, transitionProtocol } from "../services/protocols.js";
+import { cancelProtocol, getProtocolBlockers, getProtocolStatus, getReadyProtocols, implementProtocol, readyForMerge, registerProtocol, requireProtocol, syncProtocolFromRun, transitionProtocol } from "../services/protocols.js";
 import { blockPlanItem, completePlanItem, getPlanStatus, setProtocolPlan, skipPlanItem, startPlanItem } from "../services/plans.js";
 import { cancelMergeQueueJob, claimNextMergeJob, completeMergeJob, failMergeJob, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
 import { getMergeWorkerStatus, oneShotMergeClaim, startMergeWorker, stopProjectMergeWorker } from "../services/merge-worker.js";
 import { cleanupApply, cleanupScan } from "../services/cleanup.js";
 import { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, initCodexHome, installCodexHooks, planCodexHome, printCodexHomeEnv, printCodexHooks, removeCodexHome, removeCodexHooks } from "../services/hooks.js";
 import { bootstrapWorktree, closeWorktree, createWorktreeRecord, getWorktreeStatus, planWorktree } from "../services/worktrees.js";
-import { acquireLaneLock, checkLaneWorkspace, getLaneStatus, heartbeatLaneLock, releaseLaneLock, setLaneWorkspace, waitForLaneLock } from "../services/lanes.js";
+import { acquireLaneLock, cancelLaneWaiter, checkLaneWorkspace, getLaneWaiters, getLaneStatus, heartbeatLaneLock, releaseLaneLock, setLaneWorkspace, waitAcquireLaneLock, waitForLaneLock } from "../services/lanes.js";
 import { getProjectConfigStatus, setProjectConfigValue } from "../services/config.js";
 import { getCanonStatus, registerCanonRoot, resolveCanonRoot } from "../services/canon.js";
 import { getRuntimeStatus } from "../services/status.js";
-import { autoRefreshDashboards, getCmuxStatus, openDashboard, refreshDashboard, refreshGlobalDashboard, renderDashboard, renderGlobalDashboard } from "../services/dashboard.js";
+import { getCliVersionReport } from "../services/build-info.js";
+import { autoRefreshDashboards, dashboardData, getCmuxStatus, openDashboard, openGlobalDashboard, openProtocolDashboard, refreshAllDashboards, refreshDashboard, refreshGlobalDashboard, renderDashboard, renderGlobalDashboard } from "../services/dashboard.js";
+import { dashboardTargetSummary, preferredDashboardCommand, relatedDashboardCommands, resolveDashboardTarget } from "../services/dashboard-targets.js";
 import { getFlowSessionStatus, registerFlowSession, stopFlowSession, stopMergeWorker } from "../services/sessions.js";
 import { attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunStatus, listFlowRuns, startFlowRun } from "../services/runs.js";
+import { previewNextEntityId } from "../services/ids.js";
 import { validateSchema } from "../services/schema-validation.js";
 import { preflightMemoryPermissions } from "../services/memory-permissions.js";
+import { planMigration, verifyMigrationReport } from "../services/migrations.js";
+import { publishProjectSummary } from "../services/project-summary.js";
 import { requireProjectByRoot } from "../services/projects.js";
 import { resolveProjectRoot } from "../storage/paths.js";
+import { doctorEngines, engineInfo, installCurrentEngine, listEngines, resolveEngine, routeArgsThroughEngine } from "../services/engines.js";
+import { preflightCliCompatibility } from "../services/compatibility-preflight.js";
 const defaultIo = {
     stdout: process.stdout,
     stderr: process.stderr,
@@ -34,6 +41,14 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         if (args.includes("--progress-jsonl")) {
             throw new AppError("usage", "--progress-jsonl is not implemented yet; use --json for final structured progress", 2);
         }
+        if (output.args.length === 1 && output.args[0] === "--version") {
+            const payload = getCliVersionReport();
+            if (output.json)
+                writeJson(io.stdout, payload);
+            else
+                io.stdout.write(`dd-flow ${payload.cli.version}\n`);
+            return 0;
+        }
         const help = helpForArgs(output.args);
         if (help) {
             io.stdout.write(`${help}\n`);
@@ -41,7 +56,16 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         }
         const context = createContext(env);
         emitHumanProgress(io, output, progress, "start");
-        const result = await dispatch(output.args, context, io);
+        const routed = await routeArgsThroughEngine(context, output.args, io, io.stdin, env);
+        if (routed?.routed && !routed.inProcess) {
+            emitHumanProgress(io, output, progress, "done");
+            return routed.exitCode;
+        }
+        const dispatchContext = routed?.inProcess
+            ? createContext({ ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: "in-process", DD_FLOW_ROUTED_FROM: getCliVersionReport().cli.version })
+            : context;
+        preflightCliCompatibility(dispatchContext, output.args, env);
+        const result = await dispatch(output.args, dispatchContext, io);
         refreshDashboardsAfterMutation(context, output.args, result);
         emitHumanProgress(io, output, progress, "done");
         const payload = attachProgress(result, progress, output);
@@ -60,10 +84,34 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         if (output.json)
             writeJson(io.stderr, errorPayload);
         else
-            io.stderr.write(`dd-flow: ${payload.error.message}\n`);
+            io.stderr.write(renderHumanError(payload));
         return isAppError(error) ? error.exitCode : 1;
     }
 }
+function renderHumanError(payload) {
+    const lines = [`dd-flow: ${payload.error.message}`];
+    const details = recordObject(payload.error.details);
+    const compatibility = recordObject(details?.compatibility);
+    const remediation = recordObject(details?.remediation);
+    if (compatibility) {
+        lines.push(`Compatibility: ${String(compatibility.verdict ?? "unknown")} (${String(compatibility.engine_resolution ?? "unknown")})`);
+        if (compatibility.blocked_operation)
+            lines.push(`Blocked operation: ${String(compatibility.blocked_operation)}`);
+        if (compatibility.install_hint)
+            lines.push(`Install compatible engine: ${String(compatibility.install_hint)}`);
+    }
+    if (remediation?.mb_upgrade_mode)
+        lines.push(`Upgrade mode: ${String(remediation.mb_upgrade_mode)}`);
+    if (details?.preferred_command)
+        lines.push(`Preferred command: ${String(details.preferred_command)}`);
+    const related = Array.isArray(details?.related_commands) ? details.related_commands.map(String) : [];
+    if (related.length > 0) {
+        lines.push("", "Related commands:");
+        for (const command of related)
+            lines.push(`  ${command}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
 function parseOutputOptions(args) {
     const stripped = [];
     let json = false;
@@ -86,7 +134,7 @@ function progressForCommand(args) {
             { phase: "done", message: "Merge queue wait finished", at: "" }
         ];
     }
-    if (family === "lane" && command === "lock" && subcommand === "wait") {
+    if (family === "lane" && command === "lock" && ["wait", "wait-acquire"].includes(subcommand ?? "")) {
         return [
             { phase: "start", message: "Starting lane lock wait", at: "" },
             { phase: "running", message: "Waiting for lane lock", at: "" },
@@ -152,6 +200,18 @@ function renderHumanResult(args, result) {
     if (family === "status") {
         return renderStatusHuman(record);
     }
+    if (family === "version") {
+        const cli = recordObject(record.cli);
+        const engine = recordObject(record.engine);
+        const engineSuffix = engine ? ` (engine: ${String(engine.mode ?? "unknown")})` : "";
+        return `dd-flow ${stringValue(cli?.version) ?? "unknown"}${engineSuffix}\n`;
+    }
+    if (family === "engine") {
+        return renderEngineHuman(args, record);
+    }
+    if (family === "dashboard") {
+        return renderDashboardHuman(args, record);
+    }
     const lines = [`dd-flow ${family ?? ""}${command ? ` ${command}` : ""}: ${ok}`.trim()];
     const project = record.project && typeof record.project === "object" ? record.project : null;
     const protocol = record.protocol && typeof record.protocol === "object" ? record.protocol : null;
@@ -176,6 +236,7 @@ function renderHumanResult(args, result) {
         if (run.run_index_path)
             lines.push(`run_index: ${String(run.run_index_path)}`);
     }
+    appendFlowGuidanceHuman(lines, record);
     return `${lines.join("\n")}\n`;
 }
 function renderStatusHuman(record) {
@@ -183,6 +244,8 @@ function renderStatusHuman(record) {
     const cli = recordObject(record.cli);
     const cliBuild = recordObject(cli?.build);
     const builtWithCanon = recordObject(cliBuild?.built_with_canon);
+    const cliCompatibility = recordObject(cli?.compatibility);
+    const registry = recordObject(cli?.registry);
     const canon = recordObject(record.canon);
     const resolvedCanon = recordObject(canon?.resolved);
     const project = recordObject(record.project);
@@ -190,16 +253,105 @@ function renderStatusHuman(record) {
     const flowPack = recordObject(project?.flow_pack);
     const drift = recordObject(project?.drift);
     lines.push(`CLI package: ${stringValue(cli?.package_name) ?? "unknown"} ${stringValue(cli?.version) ?? "unknown"}`);
+    if (cliCompatibility) {
+        lines.push(`CLI compatibility: ${stringValue(cliCompatibility.verdict) ?? "unknown"} (${stringValue(cliCompatibility.reason) ?? "no_reason"})`);
+        if (cliCompatibility.update_command)
+            lines.push(`CLI update: ${String(cliCompatibility.update_command)}`);
+    }
+    if (registry) {
+        lines.push(`CLI registry: ${stringValue(registry.latest) ?? "unknown"} (${stringValue(registry.status) ?? "unknown"})`);
+    }
     lines.push(`CLI tested with canon: ${stringValue(builtWithCanon?.version) ?? "unknown"} @ ${shortSha(stringValue(builtWithCanon?.commit))}`);
-    lines.push(`Active local canon: ${stringValue(resolvedCanon?.root) ?? "unresolved"} ${stringValue(resolvedCanon?.version) ?? "unknown"} @ ${shortSha(stringValue(resolvedCanon?.commit))}`);
+    lines.push(`Active local canon: ${stringValue(resolvedCanon?.root) ?? "unresolved"} ${stringValue(resolvedCanon?.version) ?? "unknown"} @ ${shortSha(stringValue(resolvedCanon?.commit))} (${stringValue(resolvedCanon?.layout) ?? "unknown"})`);
+    if (resolvedCanon?.memorybank_root)
+        lines.push(`Canon Memory Bank: ${String(resolvedCanon.memorybank_root)}`);
+    if (resolvedCanon?.flow_root)
+        lines.push(`Canon flow root: ${String(resolvedCanon.flow_root)}`);
     lines.push(`Project: ${stringValue(project?.root) ?? "unknown"}${project?.registered === true ? " (registered)" : " (unregistered)"}`);
     lines.push(`Project Memory Bank: ${stringValue(memoryBank?.version) ?? stringValue(memoryBank?.status) ?? "unknown"}`);
     lines.push(`Project flow pack: ${stringValue(flowPack?.pack_version) ?? stringValue(flowPack?.status) ?? "unknown"} @ ${shortSha(stringValue(flowPack?.source_commit))}`);
     lines.push(`Drift: ${stringValue(drift?.overall) ?? "unknown"}`);
     if (drift?.next_action)
         lines.push(`Next action: ${String(drift.next_action)}`);
+    appendFlowGuidanceHuman(lines, record);
     return `${lines.join("\n")}\n`;
 }
+function renderDashboardHuman(args, record) {
+    const [, command] = args;
+    const ok = record.ok === false ? "failed" : "ok";
+    const target = recordObject(record.target);
+    const targetLabel = stringValue(target?.kind) ?? "unknown";
+    const lines = [`dd-flow dashboard ${command ?? ""}: ${ok}`.trim()];
+    lines.push(`target: ${targetLabel}`);
+    if (target?.project_id)
+        lines.push(`project: ${String(target.project_id)}`);
+    if (target?.protocol_id)
+        lines.push(`protocol: ${String(target.protocol_id)}`);
+    const dashboard = recordObject(record.dashboard);
+    if (dashboard?.path)
+        lines.push(`dashboard: ${String(dashboard.path)}`);
+    if (record.compatibility_alias)
+        lines.push(`compatibility_alias: true`);
+    if (record.preferred_command)
+        lines.push(`Preferred command: ${String(record.preferred_command)}`);
+    const related = Array.isArray(record.related_commands) ? record.related_commands.map(String) : [];
+    if (related.length > 0) {
+        lines.push("", "Related dashboard commands:");
+        for (const item of related)
+            lines.push(`  ${item}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderEngineHuman(args, record) {
+    const [, command] = args;
+    const lines = [`dd-flow engine ${command ?? ""}: ${record.ok === false ? "failed" : "ok"}`.trim()];
+    if (record.engine_store)
+        lines.push(`engine_store: ${String(record.engine_store)}`);
+    const engine = recordObject(record.engine);
+    if (engine) {
+        lines.push(`engine: ${String(engine.package_name ?? "unknown")}@${String(engine.package_version ?? "unknown")}`);
+        if (engine.entrypoint)
+            lines.push(`entrypoint: ${String(engine.entrypoint)}`);
+        if (engine.healthy !== undefined)
+            lines.push(`healthy: ${String(engine.healthy)}`);
+    }
+    const engines = Array.isArray(record.engines) ? record.engines : [];
+    if (engines.length > 0)
+        lines.push(`engines: ${engines.length}`);
+    const selection = recordObject(record.selection);
+    if (selection) {
+        lines.push(`selection: ${String(selection.status ?? "unknown")}`);
+        if (selection.selected && typeof selection.selected === "object") {
+            const selected = selection.selected;
+            lines.push(`selected: ${String(selected.package_name ?? "unknown")}@${String(selected.package_version ?? "unknown")}`);
+        }
+        if (selection.install_hint)
+            lines.push(`install_hint: ${String(selection.install_hint)}`);
+    }
+    const checks = Array.isArray(record.checks) ? record.checks : [];
+    if (checks.length > 0)
+        lines.push(`checks: ${checks.length}`);
+    return `${lines.join("\n")}\n`;
+}
+function appendFlowGuidanceHuman(lines, record) {
+    const guidance = recordObject(record.flow_guidance);
+    if (!guidance)
+        return;
+    const currentStage = stringValue(guidance.current_stage);
+    const nextAction = stringValue(guidance.recommended_next_action);
+    const prompt = stringValue(guidance.recommended_prompt);
+    if (currentStage)
+        lines.push(`stage: ${currentStage}`);
+    if (nextAction)
+        lines.push(`next: ${nextAction}${prompt && prompt !== "none" ? ` (${prompt})` : ""}`);
+    const guards = Array.isArray(guidance.guards) ? guidance.guards : [];
+    const firstGuard = guards.find((item) => item && typeof item === "object" && !Array.isArray(item));
+    if (firstGuard?.id)
+        lines.push(`guard: ${String(firstGuard.id)} ${String(firstGuard.status ?? "unknown")}`);
+    const missing = Array.isArray(guidance.blocked_if_missing) ? guidance.blocked_if_missing : [];
+    if (missing.length > 0)
+        lines.push(`missing: ${missing.map(String).join(", ")}`);
+}
 function recordObject(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -212,9 +364,18 @@ function shortSha(value) {
 async function dispatch(args, context, io) {
     const [family, command, ...rest] = args;
     const parsed = parseArgs(rest);
+    if (family === "engine") {
+        return dispatchEngine(context, command, parsed);
+    }
     if (family === "status") {
         const rootParsed = parseArgs([command ?? "", ...rest]);
-        return getRuntimeStatus(context, { projectRoot: optionalOption(rootParsed, "project-root") ?? optionalOption(rootParsed, "root") });
+        return getRuntimeStatus(context, {
+            projectRoot: optionalOption(rootParsed, "project-root") ?? optionalOption(rootParsed, "root"),
+            checkRegistry: hasOption(rootParsed, "check-registry")
+        });
+    }
+    if (family === "version") {
+        return getCliVersionReport();
     }
     if (family === "canon") {
         return dispatchCanon(context, command, parsed);
@@ -225,6 +386,12 @@ async function dispatch(args, context, io) {
     if (family === "project" && command === "status") {
         return getProjectStatus(context, { root: requiredOption(parsed, "root") });
     }
+    if (family === "project" && command === "summary") {
+        return publishProjectSummary(context, {
+            project: requireProjectByRoot(context, resolveProjectRoot(requiredOption(parsed, "project-root"))),
+            write: parseOptionalBoolean(optionalOption(parsed, "write"), "write") ?? true
+        });
+    }
     if (family === "project" && command === "resolve") {
         return resolveProject(context, { idOrAlias: requiredPosition(parsed, 0, "id-or-alias") });
     }
@@ -255,9 +422,44 @@ async function dispatch(args, context, io) {
     if (family === "protocol" && command === "status") {
         return getProtocolStatus(context, { protocolId: requiredPosition(parsed, 0, "protocol-id") });
     }
+    if (family === "protocol" && command === "ready") {
+        return getReadyProtocols(context, { projectRoot: requiredOption(parsed, "project-root") });
+    }
+    if (family === "protocol" && command === "blockers") {
+        return getProtocolBlockers(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            projectRoot: requiredOption(parsed, "project-root")
+        });
+    }
+    if (family === "protocol" && command === "implement") {
+        const reason = optionalOption(parsed, "reason");
+        return implementProtocol(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            projectRoot: requiredOption(parsed, "project-root"),
+            force: hasOption(parsed, "force"),
+            ...(reason ? { reason } : {})
+        });
+    }
     if (family === "protocol" && command === "ready-for-merge") {
         return readyForMerge(context, { protocolId: requiredPosition(parsed, 0, "protocol-id") });
     }
+    if (family === "protocol" && command === "transition") {
+        const reason = optionalOption(parsed, "reason");
+        return transitionProtocol(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            to: requiredOption(parsed, "to"),
+            jsonFile: requiredOptionAlias(parsed, ["payload-file", "json-file"]),
+            force: hasOption(parsed, "force"),
+            ...(reason ? { reason } : {})
+        });
+    }
+    if (family === "protocol" && command === "sync-from-run") {
+        return syncProtocolFromRun(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            runId: requiredOption(parsed, "run"),
+            target: optionalOption(parsed, "target") ?? "auto"
+        });
+    }
     if (family === "protocol" && command === "cancel") {
         return cancelProtocol(context, {
             protocolId: requiredPosition(parsed, 0, "protocol-id"),
@@ -275,7 +477,7 @@ async function dispatch(args, context, io) {
         return transitionProtocol(context, {
             protocolId: requiredPosition(transitionParsed, 0, "protocol-id"),
             to: requiredOption(transitionParsed, "to"),
-            jsonFile: requiredOption(transitionParsed, "json-file"),
+            jsonFile: requiredOptionAlias(transitionParsed, ["payload-file", "json-file"]),
             force: hasOption(transitionParsed, "force"),
             ...(reason ? { reason } : {})
         });
@@ -313,6 +515,9 @@ async function dispatch(args, context, io) {
     if (family === "run") {
         return dispatchRun(context, command, parsed);
     }
+    if (family === "id") {
+        return dispatchId(context, command, parsed);
+    }
     if (family === "integration" && command === "cmux") {
         return dispatchCmux(context, parsed);
     }
@@ -325,6 +530,9 @@ async function dispatch(args, context, io) {
     if (family === "memory") {
         return dispatchMemory(command, parsed);
     }
+    if (family === "migration") {
+        return dispatchMigration(context, command, parsed);
+    }
     if (family === "codex" && command === "hooks") {
         return dispatchCodexHooks(context, parsed);
     }
@@ -339,6 +547,41 @@ async function dispatch(args, context, io) {
     }
     throw new AppError("usage", `Unknown command: ${args.join(" ") || "<empty>"}`, 2);
 }
+function dispatchEngine(context, command, parsed) {
+    if (command === "install") {
+        return installCurrentEngine(context, { force: hasOption(parsed, "force") });
+    }
+    if (command === "list") {
+        return listEngines(context);
+    }
+    if (command === "info") {
+        return engineInfo(context, { packageName: optionalOption(parsed, "package"), version: optionalOption(parsed, "version") });
+    }
+    if (command === "resolve") {
+        return resolveEngine(context, { projectRoot: optionalOption(parsed, "project-root") ?? optionalOption(parsed, "root") });
+    }
+    if (command === "doctor") {
+        return doctorEngines(context, { projectRoot: optionalOption(parsed, "project-root") ?? optionalOption(parsed, "root") });
+    }
+    throw new AppError("usage", `Unknown engine command: ${command ?? "<empty>"}`, 2);
+}
+function dispatchMigration(context, command, parsed) {
+    if (command === "plan" || command === "report") {
+        return planMigration(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            sourceVersion: optionalOption(parsed, "source-version"),
+            targetVersion: optionalOption(parsed, "target-version"),
+            runId: optionalOption(parsed, "run"),
+            backupPath: optionalOption(parsed, "backup-path"),
+            backupCreatedAt: optionalOption(parsed, "backup-created-at"),
+            allowActive: parseOptionalBoolean(optionalOption(parsed, "allow-active"), "allow-active") ?? false
+        });
+    }
+    if (command === "verify") {
+        return verifyMigrationReport(context, { file: requiredOption(parsed, "file") });
+    }
+    throw new AppError("usage", `Unknown migration command: ${command ?? "<empty>"}`, 2);
+}
 function dispatchCanon(context, command, parsed) {
     if (command === "register") {
         return registerCanonRoot(context, { root: requiredOption(parsed, "root") });
@@ -579,6 +822,16 @@ function dispatchRun(context, command, parsed) {
     }
     throw new AppError("usage", `Unknown run command: ${command ?? "<empty>"}`, 2);
 }
+function dispatchId(context, command, parsed) {
+    if (command === "next") {
+        return previewNextEntityId(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            type: requiredOption(parsed, "type"),
+            slug: requiredOption(parsed, "slug")
+        });
+    }
+    throw new AppError("usage", `Unknown id command: ${command ?? "<empty>"}`, 2);
+}
 function dispatchCmux(context, parsed) {
     const action = requiredPosition(parsed, 0, "integration cmux action");
     if (action === "status") {
@@ -587,30 +840,149 @@ function dispatchCmux(context, parsed) {
     throw new AppError("usage", `Unknown integration cmux action: ${action}`, 2);
 }
 function dispatchDashboard(context, command, parsed) {
+    const action = dashboardAction(command);
+    if (command === "data") {
+        const target = resolveDashboardTarget(context, {
+            action,
+            project: optionalOption(parsed, "project"),
+            projectRoot: optionalOption(parsed, "project-root"),
+            protocol: optionalOption(parsed, "protocol"),
+            global: hasOption(parsed, "global")
+        });
+        return withDashboardGuidance(action, target, dashboardDataForResolvedTarget(context, target));
+    }
     if (command === "render") {
-        return renderDashboard(context, { projectRoot: requiredOption(parsed, "project-root"), output: optionalOption(parsed, "output") });
+        const target = resolveDashboardTarget(context, {
+            action,
+            project: optionalOption(parsed, "project"),
+            projectRoot: optionalOption(parsed, "project-root"),
+            protocol: optionalOption(parsed, "protocol")
+        });
+        return withDashboardGuidance(action, target, renderDashboardForResolvedTarget(context, target, parsed));
     }
     if (command === "render-global") {
-        return renderGlobalDashboard(context, { output: optionalOption(parsed, "output") });
+        const target = resolveDashboardTarget(context, { action: "render", global: true });
+        return withDashboardGuidance("render", target, renderGlobalDashboard(context, { output: optionalOption(parsed, "output"), format: optionalOption(parsed, "format") }), {
+            compatibilityAlias: true,
+            preferredCommand: "dd-flow dashboard render"
+        });
     }
     if (command === "open") {
-        return openDashboard(context, { projectRoot: requiredOption(parsed, "project-root"), viewer: optionalOption(parsed, "viewer") });
+        const target = resolveDashboardTarget(context, {
+            action,
+            project: optionalOption(parsed, "project"),
+            projectRoot: optionalOption(parsed, "project-root"),
+            protocol: optionalOption(parsed, "protocol")
+        });
+        return withDashboardGuidance(action, target, openDashboardForResolvedTarget(context, target, parsed));
     }
     if (command === "refresh") {
         const open = optionalOption(parsed, "open");
         if (typeof open !== "undefined" && !["auto", "true", "false"].includes(open)) {
             throw new AppError("validation", "--open must be auto, true, or false", 2);
         }
-        return refreshDashboard(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
-            open: open
+        const target = resolveDashboardTarget(context, {
+            action,
+            project: optionalOption(parsed, "project"),
+            projectRoot: optionalOption(parsed, "project-root"),
+            protocol: optionalOption(parsed, "protocol"),
+            all: hasOption(parsed, "all")
         });
+        return withDashboardGuidance(action, target, refreshDashboardForResolvedTarget(context, target, parsed, open));
     }
     if (command === "refresh-global") {
-        return refreshGlobalDashboard(context, { output: optionalOption(parsed, "output") });
+        const target = resolveDashboardTarget(context, { action: "refresh", global: true });
+        return withDashboardGuidance("refresh", target, refreshGlobalDashboard(context, { output: optionalOption(parsed, "output"), format: optionalOption(parsed, "format") }), {
+            compatibilityAlias: true,
+            preferredCommand: "dd-flow dashboard refresh"
+        });
     }
     throw new AppError("usage", `Unknown dashboard command: ${command ?? "<empty>"}`, 2);
 }
+function dashboardAction(command) {
+    if (command === "data" || command === "render" || command === "open" || command === "refresh") {
+        return command;
+    }
+    if (command === "render-global")
+        return "render";
+    if (command === "refresh-global")
+        return "refresh";
+    throw new AppError("usage", `Unknown dashboard command: ${command ?? "<empty>"}`, 2);
+}
+function dashboardDataForResolvedTarget(context, target) {
+    if (target.kind === "all_projects") {
+        throw new AppError("validation", "dashboard data does not support --all", 2, { related_commands: relatedDashboardCommands("data") });
+    }
+    if (target.kind === "global") {
+        return dashboardData(context, { global: true });
+    }
+    if (target.kind === "protocol") {
+        return dashboardData(context, { projectRoot: target.project.root, protocol: target.protocolId });
+    }
+    return dashboardData(context, { projectRoot: target.project.root });
+}
+function renderDashboardForResolvedTarget(context, target, parsed) {
+    if (target.kind === "all_projects") {
+        throw new AppError("validation", "dashboard render does not support --all", 2, { related_commands: relatedDashboardCommands("render") });
+    }
+    if (target.kind === "global") {
+        return renderGlobalDashboard(context, { output: optionalOption(parsed, "output"), format: optionalOption(parsed, "format") ?? "html" });
+    }
+    return renderDashboard(context, {
+        projectRoot: target.project.root,
+        output: optionalOption(parsed, "output"),
+        format: optionalOption(parsed, "format") ?? (hasOption(parsed, "project") ? "html" : undefined),
+        ...(target.kind === "protocol" ? { protocol: target.protocolId } : {})
+    });
+}
+function openDashboardForResolvedTarget(context, target, parsed) {
+    if (target.kind === "all_projects") {
+        throw new AppError("validation", "dashboard open --all is not supported", 2, {
+            preferred_command: "dd-flow dashboard refresh --all",
+            related_commands: relatedDashboardCommands("open", "all_projects")
+        });
+    }
+    if (target.kind === "global") {
+        return openGlobalDashboard(context, { viewer: optionalOption(parsed, "viewer"), format: optionalOption(parsed, "format") ?? "html" });
+    }
+    if (target.kind === "protocol") {
+        return openProtocolDashboard(context, {
+            projectRoot: target.project.root,
+            protocol: target.protocolId,
+            viewer: optionalOption(parsed, "viewer"),
+            format: optionalOption(parsed, "format") ?? "html"
+        });
+    }
+    return openDashboard(context, {
+        projectRoot: target.project.root,
+        viewer: optionalOption(parsed, "viewer"),
+        format: optionalOption(parsed, "format") ?? (hasOption(parsed, "project") ? "html" : undefined)
+    });
+}
+function refreshDashboardForResolvedTarget(context, target, parsed, open) {
+    if (target.kind === "all_projects") {
+        return refreshAllDashboards(context, { format: optionalOption(parsed, "format") ?? "html" });
+    }
+    if (target.kind === "global") {
+        return refreshGlobalDashboard(context, { output: optionalOption(parsed, "output"), format: optionalOption(parsed, "format") ?? "html" });
+    }
+    return refreshDashboard(context, {
+        projectRoot: target.project.root,
+        open,
+        format: optionalOption(parsed, "format") ?? (hasOption(parsed, "project") ? "html" : undefined),
+        ...(target.kind === "protocol" ? { protocol: target.protocolId } : {})
+    });
+}
+function withDashboardGuidance(action, target, result, options = {}) {
+    const record = result && typeof result === "object" && !Array.isArray(result) ? result : { ok: true, result };
+    return {
+        ...record,
+        target: dashboardTargetSummary(target),
+        ...(options.compatibilityAlias ? { compatibility_alias: true } : {}),
+        preferred_command: options.preferredCommand ?? preferredDashboardCommand(action, target),
+        related_commands: relatedDashboardCommands(action, target.kind)
+    };
+}
 function dispatchSchema(command, parsed) {
     if (command === "validate") {
         const schemaDir = optionalOption(parsed, "schema-dir");
@@ -628,6 +1000,21 @@ async function dispatchLane(context, command, parsed) {
     if (command === "status") {
         return getLaneStatus(context, { projectRoot: requiredOption(parsed, "project-root"), lane: optionalOption(parsed, "lane") });
     }
+    if (command === "waiters") {
+        return getLaneWaiters(context, { projectRoot: requiredOption(parsed, "project-root"), lane: optionalOption(parsed, "lane") });
+    }
+    if (command === "waiter") {
+        const action = requiredPosition(parsed, 0, "lane waiter action");
+        if (action === "cancel") {
+            return cancelLaneWaiter(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                lane: requiredOption(parsed, "lane"),
+                workerId: requiredOption(parsed, "worker-id"),
+                reason: requiredOption(parsed, "reason")
+            });
+        }
+        throw new AppError("usage", `Unknown lane waiter action: ${action}`, 2);
+    }
     if (command === "workspace") {
         const action = requiredPosition(parsed, 0, "lane workspace action");
         if (action === "set") {
@@ -692,6 +1079,18 @@ async function dispatchLane(context, command, parsed) {
                 pollIntervalSeconds: optionalNumber(parsed, "poll-interval")
             });
         }
+        if (action === "wait-acquire") {
+            return waitAcquireLaneLock(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                lane: requiredOption(parsed, "lane"),
+                workerId: requiredOption(parsed, "worker-id"),
+                workspacePath: workspacePathOption(parsed),
+                timeoutSeconds: optionalNumber(parsed, "timeout"),
+                pollIntervalSeconds: optionalNumber(parsed, "poll-interval"),
+                ttlSeconds: optionalNumber(parsed, "ttl"),
+                reason: requiredOption(parsed, "reason")
+            });
+        }
         throw new AppError("usage", `Unknown lane lock action: ${action}`, 2);
     }
     throw new AppError("usage", `Unknown lane command: ${command ?? "<empty>"}`, 2);
@@ -882,6 +1281,14 @@ function requiredOption(parsed, key) {
     }
     return value;
 }
+function requiredOptionAlias(parsed, keys) {
+    for (const key of keys) {
+        const value = optionalOption(parsed, key);
+        if (value)
+            return value;
+    }
+    throw new AppError("usage", `Missing required option: ${keys.map((key) => `--${key}`).join(" or ")}`, 2);
+}
 function hasOption(parsed, key) {
     return parsed.options.has(key);
 }
@@ -1018,11 +1425,14 @@ function projectRootForLaneMutation(command, parsed) {
     if (command === "workspace" && requiredPosition(parsed, 0, "lane workspace action") === "set") {
         return requiredOption(parsed, "project-root");
     }
+    if (command === "waiter" && requiredPosition(parsed, 0, "lane waiter action") === "cancel") {
+        return requiredOption(parsed, "project-root");
+    }
     if (command !== "lock") {
         return undefined;
     }
     const action = requiredPosition(parsed, 0, "lane lock action");
-    return ["acquire", "heartbeat", "release"].includes(action) ? requiredOption(parsed, "project-root") : undefined;
+    return ["acquire", "heartbeat", "release", "wait-acquire"].includes(action) ? requiredOption(parsed, "project-root") : undefined;
 }
 function projectRootForMergeQueueMutation(context, command, parsed) {
     if (["next", "wait-next"].includes(command ?? "")) {