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

package/dist/services/cleanup.js

@@ -2,13 +2,13 @@ import fs from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-import { parseJsonObject } from "../shared/json.js";
-import { ensureReadableFile } from "../storage/database.js";
-import { projectCheckoutRoot, resolveProjectRoot } from "../storage/paths.js";
+import { prepareJsonFile } from "../cli/input-preparation.js";
+import { projectCheckoutRoot, resolveProjectRoot, runtimeStateJsonPath } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
-import { protocolRunDiagnostics, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
+import { persistProtocolState, prepareProtocolRuntimeRepair, protocolRunDiagnostics, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { publicSessionIdentity } from "./session-identity.js";
+import { publishRunProjections } from "./runs.js";
 const actionKinds = new Set([
     "repair_protocol_state",
     "cancel_queue_job",
@@ -25,7 +25,8 @@ export function cleanupScan(context, input) {
     const protocols = context.db.all("SELECT id, status, stage, state_path FROM protocols WHERE project_id = ? ORDER BY id ASC", [project.id]);
     for (const protocol of protocols) {
         const terminal = ["closed", "cancelled"].includes(protocol.status) || ["closed", "cancelled"].includes(protocol.stage);
-        if (!fs.existsSync(protocol.state_path)) {
+        const requiresMigration = protocol.state_path !== runtimeStateJsonPath(context.ddFlowHome, project.id, protocol.id);
+        if (!fs.existsSync(protocol.state_path) || requiresMigration) {
             pushFinding(findings, actions, "missing_protocol_runtime_state", "warning", {
                 protocol_id: protocol.id,
                 path: protocol.state_path,
@@ -43,6 +44,8 @@ export function cleanupScan(context, input) {
             }
         }
         const fullProtocol = requireProtocol(context, protocol.id, project.id);
+        if (requiresMigration)
+            continue;
         const state = readProtocolRuntimeState(context, fullProtocol).state;
         const diagnostics = protocolRunDiagnostics(context, fullProtocol, state).diagnostics;
         for (const diagnostic of diagnostics.filter((entry) => entry.code === "protocol_run_stage_mismatch")) {
@@ -170,36 +173,55 @@ export function cleanupScan(context, input) {
         plan: { project_root: project.root, project_id: project.id, actions }
     };
 }
-export function cleanupApply(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+export function prepareCleanupApply(context, input) {
     const reason = input.reason.trim();
     if (!reason) {
         throw new AppError("validation", "cleanup apply requires --reason", 2);
     }
-    ensureReadableFile(input.planFile);
-    const plan = validateCleanupPlan(parseJsonObject(fs.readFileSync(input.planFile, "utf8"), input.planFile), project);
+    const value = prepareJsonFile(input.planFile, "cleanup plan").value;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new AppError("validation", "cleanup plan must be an object", 2);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const plan = validateCleanupPlan(value, project);
     validateNoDestructiveSurprises(context, plan, input.force);
+    return { project, reason, plan };
+}
+export function cleanupApply(context, input) {
+    const { project, reason, plan } = input.prepared ?? prepareCleanupApply(context, input);
+    // A supplied plan can outlive its initial inspection. Refresh external
+    // workspace evidence before reserving the writer, then recheck SQL below.
+    if (input.prepared)
+        validateNoDestructiveSurprises(context, plan, input.force);
+    const prepared = prepareCleanupEffects(context, plan);
     const now = context.now();
     const results = [];
-    context.db.exec("BEGIN IMMEDIATE");
+    let executing = false, committed = false;
     try {
-        for (const action of plan.actions) {
-            results.push(applyAction(context, action, reason, input.force, now));
-        }
-        const changed = results.filter((result) => result.changed).length;
-        if (changed > 0) {
-            appendAudit(context, {
-                projectId: project.id,
-                eventType: "cleanup.applied",
-                reason,
-                forced: input.force,
-                payload: { project_id: project.id, action_count: plan.actions.length, changed, results }
-            });
-        }
-        context.db.exec("COMMIT");
+        context.db.writeTransaction(() => {
+            context.db.afterCommit(() => { committed = true; });
+            validateNoDestructiveSurprises(context, plan, input.force, false);
+            prepared.assertUnchanged();
+            for (const action of plan.actions) {
+                executing = true;
+                results.push(applyAction(context, action, reason, input.force, now, prepared));
+            }
+            const changed = results.filter((result) => result.changed).length;
+            if (changed > 0) {
+                appendAudit(context, {
+                    projectId: project.id,
+                    eventType: "cleanup.applied",
+                    reason,
+                    forced: input.force,
+                    payload: { project_id: project.id, action_count: plan.actions.length, changed, results }
+                });
+            }
+        });
     }
     catch (error) {
-        context.db.exec("ROLLBACK");
+        if (committed || error instanceof AppError && error.details.effect === "committed")
+            throw new AppError(error instanceof AppError ? error.code : "cleanup_publication_failed", error instanceof Error ? error.message : "Committed cleanup publication failed", error instanceof AppError ? error.exitCode : 1, { ...(error instanceof AppError ? error.details : {}), effect: "committed", publication_pending: true, attempted_results: results, cause: String(error) });
+        if (executing)
+            throw new AppError("cleanup_apply_failed", "Cleanup failed after execution began; inspect retained artifacts before retrying", 1, { effect: "unknown", database_rolled_back: true, attempted_results: results, cause: error instanceof Error ? error.message : String(error), ...(error instanceof AppError ? { cause_code: error.code } : {}) });
         throw error;
     }
     return {
@@ -248,18 +270,36 @@ function validateCleanupPlan(value, project) {
                 throw new AppError("validation", "close_flow_session requires a native session identity", 2);
             }
         }
+        const requiredField = action.kind === "discard_stale_run" ? "run_id"
+            : ["repair_protocol_state", "cancel_queue_job", "close_worktree_record"].includes(String(action.kind)) ? "protocol_id" : undefined;
+        if (requiredField && (typeof action[requiredField] !== "string" || !action[requiredField].trim()))
+            throw new AppError("validation", `cleanup ${String(action.kind)} requires ${requiredField}`, 2);
+        const numericField = action.kind === "expire_lane_lock" ? "lock_id" : action.kind === "expire_lane_waiter" ? "waiter_id" : undefined;
+        if (numericField && (!Number.isSafeInteger(action[numericField]) || action[numericField] < 1))
+            throw new AppError("validation", `cleanup ${String(action.kind)} requires a positive integer ${numericField}`, 2);
+        if (action.worktree_path !== undefined && (typeof action.worktree_path !== "string" || !path.isAbsolute(action.worktree_path)))
+            throw new AppError("validation", "cleanup worktree_path must be an absolute path", 2);
         return action;
     });
     return { project_root: project.root, project_id: project.id, actions };
 }
-function validateNoDestructiveSurprises(context, plan, force) {
-    const destructive = plan.actions.find((action) => action.kind === "close_worktree_record" && action.worktree_path && dirtyGit(action.worktree_path));
+function validateNoDestructiveSurprises(context, plan, force, inspectFiles = true) {
+    for (const action of plan.actions) {
+        if (action.kind === "repair_protocol_state")
+            requireProtocol(context, action.protocol_id, action.project_id);
+        if (action.kind === "discard_stale_run") {
+            const run = context.db.get("SELECT index_json, status FROM runs WHERE project_id = ? AND id = ?", [action.project_id, action.run_id]);
+            if (run && ["running", "discarded"].includes(run.status))
+                cleanupRunIndex(run.index_json);
+        }
+    }
+    const destructive = inspectFiles && plan.actions.find((action) => action.kind === "close_worktree_record" && action.worktree_path && dirtyGit(action.worktree_path));
     if (destructive && !force) {
         throw new AppError("worktree_dirty", "cleanup apply refuses dirty worktree actions without --force --reason", 1, {
             path: destructive.worktree_path
         });
     }
-    const unsafeWorktree = plan.actions.find((action) => action.kind === "close_worktree_record" && action.worktree_path && !safeCleanupWorktreePath(context, action.project_id, action.worktree_path));
+    const unsafeWorktree = inspectFiles && plan.actions.find((action) => action.kind === "close_worktree_record" && action.worktree_path && !safeCleanupWorktreePath(context, action.project_id, action.worktree_path));
     if (unsafeWorktree) {
         throw new AppError("worktree_cleanup_unsafe", "cleanup apply refuses unsafe worktree path", 1, {
             path: unsafeWorktree.worktree_path
@@ -278,12 +318,53 @@ function validateNoDestructiveSurprises(context, plan, force) {
         });
     }
 }
-function applyAction(context, action, reason, force, now) {
+function prepareCleanupEffects(context, plan) {
+    const checks = [], files = new Map();
+    const repairs = new Map();
+    const read = (sql, params) => {
+        const value = context.db.get(sql, params), encoded = JSON.stringify(value);
+        checks.push(() => { if (JSON.stringify(context.db.get(sql, params)) !== encoded)
+            throw new AppError("cleanup_plan_changed", "Cleanup target changed during preparation", 1, { effect: "no_effect" }); });
+        return value;
+    };
+    const remember = (file) => { if (file !== undefined)
+        files.set(file, fs.existsSync(file)); };
+    for (const action of plan.actions) {
+        if (action.kind === "repair_protocol_state") {
+            read("SELECT * FROM protocols WHERE project_id = ? AND id = ?", [action.project_id, action.protocol_id]);
+            const protocol = requireProtocol(context, action.protocol_id, action.project_id);
+            remember(protocol.state_path);
+            repairs.set(action, prepareProtocolRuntimeRepair(context, protocol));
+        }
+        if (action.kind === "discard_stale_run") {
+            const run = read("SELECT * FROM runs WHERE project_id = ? AND id = ?", [action.project_id, action.run_id]);
+            if (run) {
+                remember(run.runtime_path);
+                remember(run.run_dir);
+                remember(run.workspace_root);
+            }
+        }
+        if (action.kind === "close_worktree_record") {
+            const record = read("SELECT * FROM worktree_records WHERE project_id = ? AND protocol_id = ?", [action.project_id, action.protocol_id]);
+            remember(action.worktree_path ?? record?.worktree_path);
+        }
+    }
+    return { repairs, assertUnchanged: () => { for (const check of checks)
+            check(); }, exists: (file) => {
+            if (!files.has(file))
+                throw new AppError("cleanup_plan_changed", "Cleanup target has no prepared filesystem observation", 1, { path: file, effect: "no_effect" });
+            return files.get(file);
+        } };
+}
+function applyAction(context, action, reason, force, now, prepared) {
     if (action.kind === "repair_protocol_state" && action.protocol_id) {
         const protocol = requireProtocol(context, action.protocol_id, action.project_id);
         const beforePath = protocol.state_path;
-        const existed = fs.existsSync(beforePath);
-        readProtocolRuntimeState(context, protocol);
+        const existed = prepared.exists(beforePath), repair = prepared.repairs.get(action);
+        context.db.run("UPDATE protocols SET state_path = ?, plan_path = ? WHERE project_id = ? AND id = ?", [repair.statePath, repair.planPath, action.project_id, action.protocol_id]);
+        persistProtocolState(context, { ...protocol, state_path: repair.statePath, plan_path: repair.planPath }, repair.state);
+        protocol.state_path = repair.statePath;
+        appendAudit(context, { protocolId: protocol.id, projectId: protocol.project_id, eventType: "protocol.runtime_state_repaired", payload: { protocol_id: protocol.id, path: repair.statePath, repaired_from: repair.previousStatePath, source: "sqlite" } });
         return {
             kind: action.kind,
             changed: !existed || beforePath !== protocol.state_path,
@@ -338,21 +419,19 @@ function applyAction(context, action, reason, force, now) {
         if (run.status === "discarded") {
             const index = discardedRunIndex(run.index_json, reason, now);
             context.db.run("UPDATE runs SET verdict = 'discarded', next_action = ?, index_json = ?, updated_at = ?, completed_at = COALESCE(completed_at, ?) WHERE project_id = ? AND id = ?", [reason, JSON.stringify(index), now, now, action.project_id, action.run_id]);
-            if (fs.existsSync(run.runtime_path))
-                fs.writeFileSync(run.runtime_path, `${JSON.stringify(index, null, 2)}\n`);
+            context.db.afterCommit(() => publishRunProjections(context, action.project_id, action.run_id));
             return { kind: action.kind, changed: true, run_id: action.run_id };
         }
         if (run.status !== "running") {
             return { kind: action.kind, changed: false, skipped: true, reason: `already_${run.status}`, run_id: action.run_id };
         }
-        if (fs.existsSync(run.runtime_path) || fs.existsSync(run.run_dir) || fs.existsSync(run.workspace_root)) {
+        if (prepared.exists(run.runtime_path) || prepared.exists(run.run_dir) || prepared.exists(run.workspace_root)) {
             return { kind: action.kind, changed: false, skipped: true, reason: "runtime_or_workspace_reappeared", run_id: action.run_id };
         }
         const index = discardedRunIndex(run.index_json, reason, now);
         context.db.run(`UPDATE runs SET status = 'discarded', verdict = 'discarded', next_action = ?, index_json = ?, updated_at = ?, completed_at = ?
        WHERE project_id = ? AND id = ? AND status = 'running'`, [reason, JSON.stringify(index), now, now, action.project_id, action.run_id]);
-        fs.mkdirSync(run.run_dir, { recursive: true });
-        fs.writeFileSync(run.runtime_path, `${JSON.stringify(index, null, 2)}\n`);
+        context.db.afterCommit(() => publishRunProjections(context, action.project_id, action.run_id));
         context.db.run(`UPDATE sessions SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
        WHERE project_id = ? AND run_id = ? AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [reason, now, now, action.project_id, action.run_id]);
         context.db.run("UPDATE flow_session_segments SET ended_at = ? WHERE project_id = ? AND run_id = ? AND ended_at IS NULL", [now, action.project_id, action.run_id]);
@@ -394,7 +473,7 @@ function applyAction(context, action, reason, force, now) {
     }
     if (action.kind === "close_worktree_record" && action.protocol_id) {
         const worktreePath = action.worktree_path ?? context.db.get("SELECT worktree_path FROM worktree_records WHERE project_id = ? AND protocol_id = ?", [action.project_id, action.protocol_id])?.worktree_path;
-        const status = worktreePath && fs.existsSync(worktreePath) ? "kept" : "removed";
+        const status = worktreePath && prepared.exists(worktreePath) ? "kept" : "removed";
         const result = context.db.run(`UPDATE worktree_records SET status = ?, updated_at = ?, closed_at = ?
        WHERE project_id = ? AND protocol_id = ? AND status = 'active'`, [status, now, now, action.project_id, action.protocol_id]);
         return {
@@ -407,22 +486,36 @@ function applyAction(context, action, reason, force, now) {
     return { kind: action.kind, changed: false, skipped: true, reason: "invalid_action" };
 }
 function discardedRunIndex(indexJson, reason, now) {
-    const index = JSON.parse(indexJson);
+    const index = cleanupRunIndex(indexJson);
     index.schema_id = "dd-flow/flow-run@3";
     index.status = "discarded";
     index.verdict = "discarded";
     index.next_action = reason;
     index.updated_at = now;
+    index.runtime_revision = (typeof index.runtime_revision === "number" ? index.runtime_revision : 0) + 1;
     index.completed_at ??= now;
     index.finished_at ??= now;
     return index;
 }
+function cleanupRunIndex(indexJson) {
+    try {
+        const index = JSON.parse(indexJson);
+        if (!index || typeof index !== "object" || Array.isArray(index))
+            throw new Error("RUN index must be an object");
+        return index;
+    }
+    catch (error) {
+        throw new AppError("runtime_state_invalid", "Cleanup cannot read retained RUN state", 1, { cause: String(error) });
+    }
+}
 function dirtyGit(worktreePath) {
     if (!fs.existsSync(worktreePath)) {
         return false;
     }
-    const result = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { encoding: "utf8" });
-    return result.status === 0 && result.stdout.trim().length > 0;
+    const result = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { encoding: "utf8", timeout: 5000 });
+    if (result.error || result.status !== 0)
+        throw new AppError("workspace_status_failed", "Cannot establish worktree status before cleanup", 1, { path: worktreePath, cause: result.error?.message ?? result.stderr });
+    return result.stdout.trim().length > 0;
 }
 function safeCleanupWorktreePath(context, projectId, worktreePath) {
     if (!fs.existsSync(worktreePath)) {

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

@@ -1,3 +1,8 @@
+import { parseCommandArgs } from "./lifecycle-command.js";
+import { commandKeyForPositions, routerNativeRoute } from "../cli/command-metadata.js";
+import { hasHelpIntent } from "../cli/help.js";
+import { isUpgradeAllowlisted } from "./cli-upgrade-allowlist.js";
+export { isUpgradeAllowlisted } from "./cli-upgrade-allowlist.js";
 export function classifyCliOperation(args, env = process.env) {
     const positional = positionalArgs(args);
     const [family = null, command = null, action = null] = positional;
@@ -5,6 +10,8 @@ export function classifyCliOperation(args, env = process.env) {
     if (isMbUpgradeMode(args, env)) {
         return { mode: "mb_upgrade", operation, family, command, action };
     }
+    if (family === "run" && command === "reconcile" && !args.includes("--apply"))
+        return { mode: "read_only_diagnostics", operation, family, command, action };
     if (isRouterNative(args)) {
         return { mode: "router_native", operation, family, command, action };
     }
@@ -14,19 +21,7 @@ export function classifyCliOperation(args, env = process.env) {
     return { mode: "normal_write", operation, family, command, action };
 }
 function positionalArgs(args) {
-    const positional = [];
-    for (let index = 0; index < args.length; index += 1) {
-        const value = args[index];
-        if (!value)
-            continue;
-        if (value.startsWith("--")) {
-            if (!value.includes("=") && args[index + 1] && !args[index + 1]?.startsWith("--"))
-                index += 1;
-            continue;
-        }
-        positional.push(value);
-    }
-    return positional;
+    return parseCommandArgs(args).positional;
 }
 export function isReadOnlyCliOperation(args, env = process.env) {
     return classifyCliOperation(args, env).mode === "read_only_diagnostics";
@@ -37,7 +32,7 @@ export function isMbUpgradeCliOperation(args, env = process.env) {
 export function requiresExplicitUpgradeAuthorization(args) {
     const positional = positionalArgs(args);
     const [family, command] = positional;
-    if (family === "migration" && command === "apply")
+    if (family === "migration" && ["apply", "readiness"].includes(command ?? ""))
         return true;
     if (family === "run" && command === "start" && optionValue(args, "flow-kind") === "mb-upgrade")
         return true;
@@ -57,59 +52,19 @@ function isMbUpgradeMode(args, env) {
     }
     return marked && isUpgradeAllowlisted(args);
 }
-function isUpgradeAllowlisted(args) {
-    const positional = positionalArgs(args);
-    const [family, command] = positional;
-    if (family === "status")
-        return true;
-    if (family === "engine" && command === "resolve")
-        return true;
-    if (family === "migration" && ["impact", "plan", "report", "verify", "apply"].includes(command ?? ""))
-        return true;
-    if (family === "memory" && command === "permissions" && positional[2] === "preflight")
-        return true;
-    if (family === "run" && command === "start")
-        return optionValue(args, "flow-kind") === "mb-upgrade";
-    if (family === "stage" && ["start", "pause", "resume", "finish"].includes(command ?? ""))
-        return hasRunBinding(args);
-    if (family === "session" && ["status", "register", "stop", "usage"].includes(command ?? ""))
-        return hasRunBinding(args);
-    if (family === "dashboard" && ["data", "render", "refresh", "open"].includes(command ?? ""))
-        return true;
-    return false;
-}
-function hasRunBinding(args) {
-    return Boolean(optionValue(args, "run") || positionalArgs(args).some((value) => value.startsWith("RUN-")));
-}
 function optionValue(args, name) {
-    for (let index = args.length - 1; index >= 0; index -= 1) {
-        const arg = args[index];
-        if (arg === `--${name}`)
-            return args[index + 1] ?? null;
-        if (arg?.startsWith(`--${name}=`))
-            return arg.slice(name.length + 3);
-    }
-    return null;
+    const values = parseCommandArgs(args).options.get(name);
+    const value = values?.[values.length - 1];
+    return value && value !== "__dd_flow_flag__" ? value : null;
 }
-function isRouterNative(args) {
+export function isRouterNative(args) {
     const first = args[0];
     if (!first || first === "--version")
         return true;
-    if (first === "--help" || first === "-h")
+    if (hasHelpIntent(args))
         return true;
-    if (args.includes("--help") || args.includes("-h"))
-        return true;
-    if (["engine", "version", "schema"].includes(first))
-        return true;
-    return (first === "codex" && args[1] === "hook" && args[2] === "handle")
-        || (first === "zcode" && args[1] === "event" && args[2] === "handle")
-        || (first === "zcode" && args[1] === "usage" && args[2] === "ingest")
-        || (first === "grok" && args[1] === "event" && args[2] === "handle")
-        || (first === "grok" && args[1] === "usage" && args[2] === "ingest")
-        || (first === "opencode" && args[1] === "event" && args[2] === "handle")
-        || (first === "opencode" && args[1] === "usage" && args[2] === "ingest")
-        || (first === "agy" && args[1] === "event" && args[2] === "handle")
-        || (first === "agy" && args[1] === "usage" && args[2] === "ingest");
+    const key = commandKeyForPositions(positionalArgs(args));
+    return key !== undefined && routerNativeRoute(key);
 }
 function isReadOnlyDiagnostic(family, command, action) {
     if (!family)
@@ -119,13 +74,25 @@ function isReadOnlyDiagnostic(family, command, action) {
     if (family === "canon")
         return command === "status" || command === "resolve";
     if (family === "project")
-        return command === "status" || command === "resolve";
+        return command === "status" || command === "resolve" || (command === "config" && action === "status");
     if (family === "protocol")
         return ["status", "branch-status", "ready", "blockers", "implement"].includes(command ?? "");
     if (family === "plan")
         return command === "status";
     if (family === "run")
-        return command === "status" || command === "list";
+        return ["status", "list", "timeline"].includes(command ?? "") || (["config", "flags", "drive", "control"].includes(command ?? "") && action === "status") || (command === "vars" && ["ls", "get"].includes(action ?? "")) || (command === "recovery" && action === "inspect");
+    if (family === "runtime" && command === "process" && ["status", "check-admission"].includes(action ?? ""))
+        return true;
+    if (family === "runtime" && command === "scope" && action === "status")
+        return true;
+    if (family === "work")
+        return ["status", "ls", "show"].includes(command ?? "");
+    if (family === "stage")
+        return command === "fanout" && action === "status";
+    if (family === "interactive")
+        return command === "inputs" || command === "git-inputs";
+    if (family === "delivery")
+        return command === "inputs";
     if (family === "lane") {
         return (command === "status" ||
             command === "waiters" ||
@@ -145,7 +112,8 @@ function isReadOnlyDiagnostic(family, command, action) {
     if (family === "dashboard")
         return command === "data" || command === "open";
     if (family === "memory")
-        return command === "permissions" && action === "preflight";
+        return command === "permissions" && action === "preflight" || command === "distill" && action === "inputs"
+            || command === "fix" && ["context", "scope"].includes(action ?? "");
     if (family === "codex" && command === "hooks")
         return action === "print" || action === "status";
     if (family === "codex" && command === "home")

package/dist/services/cli-upgrade-allowlist.js

@@ -0,0 +1,27 @@
+import { parseCommandArgs } from "./lifecycle-command.js";
+/** Syntax eligibility only. Storage/project/RUN authority is checked separately. */
+export function isUpgradeAllowlisted(args) {
+    const parsed = parseCommandArgs(args), [family, command] = parsed.positional;
+    const option = (name) => {
+        const value = parsed.options.get(name)?.at(-1);
+        return value && value !== "__dd_flow_flag__" ? value : null;
+    };
+    if (family === "status")
+        return true;
+    if (family === "engine" && command === "resolve")
+        return true;
+    if (family === "migration" && ["impact", "readiness", "plan", "report", "verify", "apply"].includes(command ?? ""))
+        return true;
+    if (family === "memory" && command === "permissions" && parsed.positional[2] === "preflight")
+        return true;
+    if (family === "run" && command === "start")
+        return option("flow-kind") === "mb-upgrade";
+    const bound = Boolean(option("run") || parsed.positional.some(value => value.startsWith("RUN-")));
+    if (family === "stage" && ["start", "pause", "resume", "finish"].includes(command ?? ""))
+        return bound;
+    if (family === "session" && ["status", "register", "stop", "usage"].includes(command ?? ""))
+        return bound;
+    if (family === "dashboard" && ["data", "render", "refresh", "open"].includes(command ?? ""))
+        return true;
+    return false;
+}