@deksden-com/dd-flow-cli 0.3.0 → 0.4.0

package/dist/cli/run-cli.js

@@ -5,24 +5,30 @@ import { writeJson } from "../shared/json.js";
 import { archiveProject, getProjectStatus, migrateProjectIds, registerProject, resolveProject } from "../services/projects.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 { cancelMergeQueueJob, claimNextMergeJob, claimMergeBundle, completeMergeBundle, completeMergeJob, failMergeBundle, failMergeJob, getMergeBundleStatus, 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 { getCliVersionReport } from "../services/build-info.js";
-import { autoRefreshDashboards, dashboardData, getCmuxStatus, openDashboard, refreshDashboard, refreshGlobalDashboard, renderDashboard, renderGlobalDashboard } from "../services/dashboard.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 { getProtocolBranchContext } from "../services/branch-context.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,
@@ -51,7 +57,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);
@@ -70,10 +85,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;
@@ -96,7 +135,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: "" },
@@ -164,7 +203,15 @@ function renderHumanResult(args, result) {
     }
     if (family === "version") {
         const cli = recordObject(record.cli);
-        return `dd-flow ${stringValue(cli?.version) ?? "unknown"}\n`;
+        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;
@@ -177,6 +224,18 @@ function renderHumanResult(args, result) {
         const job = record.job;
         lines.push(`job: ${String(job.protocol_id ?? "none")} ${String(job.status ?? "")}`.trim());
     }
+    const branchContext = recordObject(record.branch_context);
+    const mergeBundle = recordObject(branchContext?.merge_bundle);
+    if (branchContext) {
+        lines.push(`branch: ${String(branchContext.feature_branch ?? branchContext.grouping_key ?? "unknown")}`);
+        const protocols = Array.isArray(branchContext.protocols) ? branchContext.protocols.length : 0;
+        lines.push(`branch_protocols: ${protocols}`);
+        if (mergeBundle) {
+            const eligible = Array.isArray(mergeBundle.eligible_protocols) ? mergeBundle.eligible_protocols.length : 0;
+            const notReady = Array.isArray(mergeBundle.not_ready_protocols) ? mergeBundle.not_ready_protocols.length : 0;
+            lines.push(`bundle: ${String(mergeBundle.reason ?? "unknown")} ready=${eligible} not_ready=${notReady}`);
+        }
+    }
     if (record.stopped)
         lines.push(`stopped: ${String(record.reason ?? "true")}`);
     if (record.timed_out)
@@ -230,6 +289,63 @@ function renderStatusHuman(record) {
     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)
@@ -261,6 +377,9 @@ 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, {
@@ -280,6 +399,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") });
     }
@@ -310,6 +435,14 @@ async function dispatch(args, context, io) {
     if (family === "protocol" && command === "status") {
         return getProtocolStatus(context, { protocolId: requiredPosition(parsed, 0, "protocol-id") });
     }
+    if (family === "protocol" && command === "branch-status") {
+        const protocolId = parsed.positional[0];
+        return getProtocolBranchContext(context, {
+            ...(protocolId ? { protocolId } : {}),
+            projectRoot: optionalOption(parsed, "project-root"),
+            workspacePath: optionalOption(parsed, "path")
+        });
+    }
     if (family === "protocol" && command === "ready") {
         return getReadyProtocols(context, { projectRoot: requiredOption(parsed, "project-root") });
     }
@@ -418,6 +551,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);
     }
@@ -432,6 +568,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") });
@@ -505,7 +676,38 @@ function dispatchMergeQueue(context, command, parsed) {
 }
 function dispatchMerge(context, command, parsed) {
     if (command === "status") {
-        return getMergeWorkerStatus(context, { projectRoot: requiredOption(parsed, "project-root") });
+        return getMergeWorkerStatus(context, { projectRoot: requiredOption(parsed, "project-root"), workspacePath: optionalOption(parsed, "path") });
+    }
+    if (command === "bundle") {
+        const action = requiredPosition(parsed, 0, "bundle action");
+        if (action === "status") {
+            return getMergeBundleStatus(context, { projectRoot: requiredOption(parsed, "project-root"), workspacePath: workspacePathOption(parsed) });
+        }
+        if (action === "claim") {
+            return claimMergeBundle(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                workerId: requiredWorkerId(parsed),
+                workspacePath: workspacePathOption(parsed)
+            });
+        }
+        if (action === "complete") {
+            return completeMergeBundle(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                workerId: requiredWorkerId(parsed),
+                workspacePath: workspacePathOption(parsed),
+                summary: requiredOption(parsed, "summary")
+            });
+        }
+        if (action === "fail") {
+            return failMergeBundle(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                workerId: requiredWorkerId(parsed),
+                workspacePath: workspacePathOption(parsed),
+                reason: requiredOption(parsed, "reason"),
+                requeue: parseBoolean(requiredOption(parsed, "requeue"), "requeue")
+            });
+        }
+        throw new AppError("usage", `Unknown merge bundle action: ${action}`, 2);
     }
     if (command === "one-shot") {
         return oneShotMergeClaim(context, {
@@ -690,49 +892,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 global = hasOption(parsed, "global");
-        return dashboardData(context, {
-            global,
-            projectRoot: global ? undefined : requiredOption(parsed, "project-root"),
-            protocol: optionalOption(parsed, "protocol")
+        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"),
-            format: optionalOption(parsed, "format"),
+        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"), format: optionalOption(parsed, "format") });
+        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"),
-            format: optionalOption(parsed, "format")
+        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,
-            format: optionalOption(parsed, "format"),
-            protocol: optionalOption(parsed, "protocol")
+        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"), format: optionalOption(parsed, "format") });
+        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");
@@ -750,6 +1052,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") {
@@ -814,6 +1131,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);
@@ -1148,11 +1477,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 ?? "")) {

package/dist/schemas/compatibility.schema.json

@@ -2,10 +2,10 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "dd-flow/compatibility@1",
   "title": "dd-flow compatibility manifest",
-  "description": "Canonical compatibility map between a Memory Bank release and the dd-flow CLI package required by that release.",
+  "description": "Canonical compatibility map between a Memory Bank release, tool packages, routed CLI engine expectations and machine data contracts required or recommended by that release.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schema_id", "memory_bank_version", "dd_flow_cli"],
+  "required": ["schema_id", "memory_bank_version", "dd_flow_cli", "router", "engine", "contracts", "migrations", "mb_lint"],
   "properties": {
     "schema_id": { "const": "dd-flow/compatibility@1" },
     "memory_bank_version": { "type": "string", "minLength": 1 },
@@ -21,6 +21,85 @@
         "version_contract": { "type": "string", "minLength": 1 },
         "flow_contract": { "type": "string", "minLength": 1 }
       }
+    },
+    "router": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["package_name", "min_version", "recommended_version", "routing_model", "engine_store"],
+      "properties": {
+        "package_name": { "type": "string", "minLength": 1 },
+        "min_version": { "type": "string", "minLength": 1 },
+        "recommended_version": { "type": "string", "minLength": 1 },
+        "routing_model": { "type": "string", "minLength": 1 },
+        "engine_store": { "type": "string", "minLength": 1 },
+        "notes": { "type": "string" }
+      }
+    },
+    "engine": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["package_name", "version_range", "recommended_version", "install_hint", "old_engine_install_hint", "first_engine_installable_version", "legacy_direct_cli_before", "manifest_contract", "status"],
+      "properties": {
+        "package_name": { "type": "string", "minLength": 1 },
+        "version_range": { "type": "string", "minLength": 1 },
+        "recommended_version": { "type": "string", "minLength": 1 },
+        "install_hint": { "type": "string", "minLength": 1 },
+        "old_engine_install_hint": { "type": "string", "minLength": 1 },
+        "first_engine_installable_version": { "type": "string", "minLength": 1 },
+        "legacy_direct_cli_before": { "type": "string", "minLength": 1 },
+        "manifest_contract": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "minLength": 1 }
+      }
+    },
+    "contracts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["storage_contract_set", "project_summary_contract", "project_dashboard_contract", "global_dashboard_contract", "status_contract", "version_contract"],
+      "properties": {
+        "storage_contract_set": { "type": "string", "minLength": 1 },
+        "project_summary_contract": { "type": "string", "minLength": 1 },
+        "project_dashboard_contract": { "type": "string", "minLength": 1 },
+        "global_dashboard_contract": { "type": "string", "minLength": 1 },
+        "status_contract": { "type": "string", "minLength": 1 },
+        "version_contract": { "type": "string", "minLength": 1 }
+      }
+    },
+    "global_dashboard": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["supported_project_summary_contracts", "unsupported_project_visibility", "summary_version_groups"],
+      "properties": {
+        "supported_project_summary_contracts": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "unsupported_project_visibility": { "type": "boolean" },
+        "summary_version_groups": { "type": "boolean" }
+      }
+    },
+    "migrations": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "from_previous", "to_this", "adjacent_only", "normal_commands_may_migrate"],
+      "properties": {
+        "mode": { "const": "mb-upgrade-only" },
+        "from_previous": { "type": ["string", "null"] },
+        "to_this": { "type": "string", "minLength": 1 },
+        "adjacent_only": { "type": "boolean" },
+        "normal_commands_may_migrate": { "const": false }
+      }
+    },
+    "mb_lint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["package_name", "min_version", "recommended_version", "command_contract"],
+      "properties": {
+        "package_name": { "type": "string", "minLength": 1 },
+        "min_version": { "type": "string", "minLength": 1 },
+        "recommended_version": { "type": "string", "minLength": 1 },
+        "command_contract": { "type": "string", "minLength": 1 }
+      }
     }
   }
 }