@deksden-com/dd-flow-cli 0.9.0-beta.137 → 0.9.0-beta.138

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.138
+
+- Retain causal native check failures and permit fenced source repair in the same Session. Reject malformed repair proofs and preserve physical execution blockers during reconciliation.
+
 ## 0.9.0-beta.137
 
 - Preserve shared reasoning/mode options in OpenCode v2 and support non-generative doctor before daemon startup.

package/README.md

@@ -36,6 +36,15 @@ Add `DD_TEST_OPENCODE_LONG=1` to prove shell progress beyond the old 120s cutoff
 
 ## Native daemon shutdown
 
+Managed native shells use the launch-bound `DD_FLOW_DAEMON_ID`, `DD_FLOW_HOME`,
+`DD_FLOW_BIN` and resource path. Inherited invocation/control authority is
+cleared; security-only launches do not borrow a previous RUN's identity.
+Compact lifecycle commands resolve private arguments from the issued assignment
+and its native receipt, not from a model-supplied ID or the latest matching row.
+A lost managed binding is a tooling failure, not permission to replay a short
+command. Corrective retries are scoped to the action, Session and Stage attempt;
+exact native event re-delivery returns the retained outcome.
+
 `daemon.stop` fences productive dispatch before awaiting settlement. A successful
 durable stop receipt follows native tree settlement, physical provider exit,
 journal drain and required resource/auth finalization. The endpoint then retires

package/dist/build-info.json

@@ -1,15 +1,15 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.137",
-  "cli_commit": "3a1e4cb4a0a24e388228ebb85591350fa4f5886b",
-  "built_at": "2026-10-14T05:52:24.329Z",
+  "cli_version": "0.9.0-beta.138",
+  "cli_commit": "c1a9786d04e0944daac204e1c767414904d9ced2",
+  "built_at": "2026-10-15T05:27:46.626Z",
   "built_with_canon": {
     "version": "4.1.2",
     "commit": "1ddedf9d3f086e046f8e7b194c739ec386e7c8b9",
     "flow_contract": "dd-flow-canonical-2026-08",
-    "repo_root": "/Users/deksden/Documents/_Projects/dd-memorybank",
-    "memorybank_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank",
-    "flow_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank/dd-flow",
+    "repo_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-memorybank-084-release",
+    "memorybank_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-memorybank-084-release/.memory-bank",
+    "flow_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-memorybank-084-release/.memory-bank/dd-flow",
     "layout": "dot_memory_bank"
   }
 }

package/dist/cli/argument-values.js

@@ -4,15 +4,15 @@ export function optionalOption(parsed, key) {
     const values = parsed.options.get(key);
     const value = values?.[values.length - 1];
     if (value === flagValue)
-        throw new AppError("usage", `--${key} requires a value`, 2);
+        throw new AppError("usage", `--${key} requires a value`, 2, { parameter: key, reason: "missing_option_value" });
     if (value !== undefined && !value.trim())
-        throw new AppError("usage", `--${key} requires a non-empty value`, 2);
+        throw new AppError("usage", `--${key} requires a non-empty value`, 2, { parameter: key, reason: "empty_option_value" });
     return value;
 }
 export function requiredOption(parsed, key) {
     const value = optionalOption(parsed, key);
     if (!value) {
-        throw new AppError("usage", `Missing required option: --${key}`, 2);
+        throw new AppError("usage", `Missing required option: --${key}`, 2, { parameter: key, reason: "missing_required_option" });
     }
     return value;
 }
@@ -23,7 +23,7 @@ export function optionalNumber(parsed, key) {
     }
     const parsedNumber = Number(value);
     if (!Number.isFinite(parsedNumber)) {
-        throw new AppError("validation", `--${key} must be a number`, 2);
+        throw new AppError("validation", `--${key} must be a number`, 2, { parameter: key, reason: "invalid_number" });
     }
     return parsedNumber;
 }
@@ -32,7 +32,7 @@ export function optionalPositiveNumber(parsed, key, integer = false) {
     if (typeof value === "undefined")
         return undefined;
     if (value <= 0 || (integer && !Number.isInteger(value))) {
-        throw new AppError("validation", `--${key} must be a positive${integer ? " integer" : ""} number`, 2);
+        throw new AppError("validation", `--${key} must be a positive${integer ? " integer" : ""} number`, 2, { parameter: key, reason: "invalid_number" });
     }
     return value;
 }

package/dist/cli/command-inputs.js

@@ -1,7 +1,7 @@
 import { AppError } from "../shared/errors.js";
 import { parseCommandArgs } from "../services/lifecycle-command.js";
 import { lifecycleInternalOptions, lifecycleRouteForOperation } from "../services/lifecycle-contract.js";
-import { isUpgradeAllowlisted } from "../services/cli-operation-classifier.js";
+import { isUpgradeAllowlisted } from "../services/cli-upgrade-allowlist.js";
 const words = (value) => value.split(" ").filter(Boolean);
 const route = (positions, required = "", values = "", switches = "", repeatable = "", enums = {}) => ({
     positions: typeof positions === "number" ? [positions, positions] : positions,
@@ -12,12 +12,50 @@ const scoped = "project-root"; // Optional when the router resolves a unique ret
 const lifecycle = lifecycleInternalOptions.join(" ");
 const worker = "worker-id";
 const control = "project-root run";
+const protocolTransitionInput = route(1, "to", `${scoped} payload-file json-file reason`, "force");
+const setupInput = route(0, "request-id trust-file", "canon-source canon-version release-registry channel profile profile-file save-profile-intent", "non-interactive skip-agent-setup", "", { channel: ["stable", "preview", "development"] });
+const memoryInitInput = route(0, "project-root workspace-root request-id", "intake-file intake-sha256 profile profile-file stage-profile work-profile max-parallel delegation native-config-home git-route integration-branch", "detach non-interactive prepare-only allow-live-probe", "stage-profile work-profile", { "git-route": ["integration_branch_direct", "feature_worktree"], delegation: ["external", "native"] });
+export const commandAliases = { transition: "protocol transition", init: "flow mb-init" };
 /** Path-shaped arguments default to physical paths unless the route explicitly
  * opts into contextualPaths. This inventory does not expand arbitrary strings. */
-export const physicalPathOptions = new Set(words("root project-root workspace-root workspace-path path dir file schema-dir output result-file semantic-file data decision-file verification-file reason-file task-file intake-file context-file observations-file observation-file summary-file question-file answer-file payload-file json-file task-profile-file execution-routing-file protocol-override-file manifest-file routing-file config-file input-file report-file snapshot-file output-dir state-dir capture-root capture-path destination source archive snapshot plan-file backup-path database backup source-home target-home stdout stderr adapter-executable memory-bank flow stage-report dashboard report"));
+export const physicalPathOptions = new Set(words("canon-source trust-file root project-root workspace-root workspace-path workspace-path path dir file schema-dir output result-file semantic-file data decision-file verification-file reason-file task-file intake-file context-file observations-file observation-file summary-file question-file answer-file payload-file json-file task-profile-file execution-routing-file protocol-override-file manifest-file routing-file config-file input-file report-file snapshot-file output-dir state-dir capture-root capture-path destination source archive snapshot plan-file backup-path database backup source-home target-home stdout stderr adapter-executable memory-bank flow stage-report dashboard report"));
+physicalPathOptions.add("profile-file");
+physicalPathOptions.add("save-profile-intent");
+physicalPathOptions.add("model-observation-file");
+physicalPathOptions.add("release-registry");
+physicalPathOptions.add("seed-file");
+physicalPathOptions.add("native-executable");
+physicalPathOptions.add("native-config-home");
 physicalPathOptions.add("operational-decision-file");
 export const commandInputs = {
     "version": route(0),
+    "flow list": route(0),
+    "flow show": route(1),
+    "flow mb-init": memoryInitInput,
+    "init": memoryInitInput,
+    "runtime storage admit": route(0, "operation", "", "", "", { operation: ["memory-init"] }),
+    "runtime flow admit": route(0, "operation", "", "", "", { operation: ["memory-init"] }),
+    "completion bash": route(0),
+    "completion zsh": route(0),
+    "completion fish": route(0),
+    "completion candidates": route([0, 1000]),
+    "harnesses list": route(0),
+    "models list": route(0, "", "harness provider account-sha256 seed-file observation-file", "", "", { harness: ["codex", "zcode", "agy", "opencode", "grok", "droid"] }),
+    "models show": route(1, "", "harness provider account-sha256 seed-file observation-file", "", "", { harness: ["codex", "zcode", "agy", "opencode", "grok", "droid"] }),
+    "harnesses show": route(1),
+    "harnesses discover": route(0, "", "harness executable", "", "", { harness: ["codex", "zcode", "agy", "opencode", "grok", "droid"] }),
+    "harnesses probe-version": route(0, "harness", "executable timeout-ms", "allow-processes allow-credentials allow-writes", "", { harness: ["codex", "zcode", "agy", "opencode", "grok", "droid"] }),
+    "harnesses doctor": route(0, "harness", "executable native-executable state-dir timeout-ms provider account-sha256 model-observation-file", "allow-processes allow-services allow-credentials allow-writes", "", { harness: ["codex", "zcode", "agy", "opencode", "grok", "droid"] }),
+    "setup": setupInput,
+    "setup update": setupInput,
+    "setup status": route(0),
+    "profiles list": route(0),
+    "profiles show": route(1),
+    "profiles create": route(0, "file expected-revision", "", "set-default"),
+    "profiles edit": route(0, "file expected-revision"),
+    "profiles remove": route(1, "expected-revision"),
+    "profiles alias": route(1, "expected-revision", "target", "remove"),
+    "profiles set-default": route([0, 1], "expected-revision", "", "clear"),
     "status": route(0, "", "root project-root", "check-registry"),
     "project register": route(0, "root"),
     "project status": route(0, "root"),
@@ -34,8 +72,8 @@ export const commandInputs = {
     "protocol blockers": route(1, project),
     "protocol implement": route(1, "", `${scoped} reason`, "force"),
     "protocol ready-for-merge": route(1, "", scoped),
-    "protocol transition": route(1, "to", `${scoped} payload-file json-file reason`, "force"),
-    "transition": route(1, "to", `${scoped} payload-file json-file reason`, "force"),
+    "protocol transition": protocolTransitionInput,
+    "transition": protocolTransitionInput,
     "protocol sync-from-run": route(1, "run", `${scoped} target`),
     "protocol cancel": route(1, "reason", `${scoped} close-sessions cancel-queue release-locks worktree`, "force"),
     "plan status": route(1, "", scoped),
@@ -57,7 +95,7 @@ export const commandInputs = {
     "stage fanout reconcile": { ...route(1, "stage observations-file", scoped), contextualPaths: words("project-root observations-file") },
     "stage native observe": { ...route(1, "stage observations-file", scoped), contextualPaths: words("project-root observations-file") },
     "work status": route(1, project),
-    "work add-batch": { ...route(0, "parent file", scoped), contextualPaths: words("project-root file") },
+    "work add-batch": { ...route(0, "parent file", `${scoped} stage request-key`), contextualPaths: words("project-root file") },
     "work ls": route(0, "", `${scoped} run parent status limit`, "ready include-results", "", { status: ["created", "running", "paused", "completed", "failed", "cancelled"] }),
     "work show": route(1, "", scoped),
     "work repair add": { ...route(0, "run", `${scoped} origin-work from-check from-finding from-unresolved check-ref verification-file task-file`, "task-stdin", "origin-work from-finding from-unresolved check-ref"), contextualPaths: words("project-root verification-file task-file") },
@@ -101,7 +139,7 @@ export const commandInputs = {
     "run recovery capture": route(1, `${project} recovery-id capture-path`),
     "run recovery resume": route(1, `${project} recovery-id daemon-id harness native-session-id`),
     "run recovery accept": { ...route(1, `${project} recovery-id`, lifecycle), contextualPaths: ["project-root"] },
-    "run snapshot bootstrap create": route(0, `${project} output`),
+    "run snapshot bootstrap create": route(0, `${project} output flow`),
     "run snapshot bootstrap restore": route(0, `${project} snapshot`),
     "run snapshot create": route(1, `${project} output`, "recovery-id stage-entry", "candidate incomplete"),
     "run snapshot restore": route(0, `${project} snapshot`, "execution-routing-file operational-decision-file recovery-id"),
@@ -225,14 +263,33 @@ export const commandInputs = {
     "dashboard refresh": route(0, "", "project project-root protocol open format output", "all"),
     "dashboard refresh-global": route(0, "", "output format"),
     "schema validate": { ...route(0, "schema file", "schema-dir project-root run"), contextualPaths: words("project-root file") },
-    "memory permissions preflight": route(0, "root memory-bank flow mode", "tasks")
+    "memory permissions preflight": route(0, "root memory-bank flow mode", "tasks"),
+    "memory compose register": route(0, "project-root run request-key result-file"),
+    "memory verify checks": route(0, "project-root run"),
+    "memory review register": route(0, "project-root run"),
+    "memory review collect": route(0, "project-root run"),
+    "memory finish evidence": route(0, "project-root run"),
+    "memory finish integrate": route(0, "project-root run"),
+    "memory corrections register": route(0, "project-root run wave result-file", "", "", "", { wave: ["1", "2"] }),
+    "memory corrections checks": route(0, "project-root run wave", "", "", "", { wave: ["1", "2"] }),
+    "memory review selective-register": route(0, "project-root run wave", "", "", "", { wave: ["1", "2"] }),
+    "memory review selective-collect": route(0, "project-root run wave", "", "", "", { wave: ["1", "2"] }),
+    "memory repair baseline": route(0, "project-root run wave work", "", "", "", { wave: ["1", "2"] }),
+    "memory repair copy-reserve": route(0, "project-root run wave work", "", "", "", { wave: ["1", "2"] }),
+    "memory repair copy-materialize": route(0, "project-root run wave work", "", "", "", { wave: ["1", "2"] }),
+    "memory repair copy-dispatch": route(0, "project-root run wave work", "", "", "", { wave: ["1", "2"] }),
+    "memory repair current-view": route(0, "project-root run wave work workspace-root", "", "", "", { wave: ["1", "2"] }),
+    "memory repair publication-source": route(0, "project-root run wave work workspace-root work-session", "", "", "", { wave: ["1"] }),
+    "memory repair publication-reserve": route(0, "project-root run wave work workspace-root work-session result-file", "", "", "", { wave: ["1", "2"] }),
+    "memory repair publication-apply": route(0, "project-root run wave work workspace-root work-session", "", "", "", { wave: ["1", "2"] }),
+    "memory repair publication-finish": route(0, "project-root run wave work workspace-root work-session", "", "", "", { wave: ["1", "2"] })
 };
 export function contextualPathOptionsForLifecycle(operation) {
     const key = lifecycleRouteForOperation(operation);
     return new Set(commandInputs[key]?.contextualPaths ?? []);
 }
 const flag = "__dd_flow_flag__";
-const positiveInteger = new Set(words("limit lease-ms pid owner-pid process-group-id ready-timeout-ms max-parallel-projects expected-revision"));
+const positiveInteger = new Set(words("limit lease-ms pid owner-pid process-group-id ready-timeout-ms max-parallel max-parallel-projects expected-revision"));
 const nonnegativeInteger = new Set(words("after generation wait-ms grace-ms available-slots"));
 const positiveNumber = new Set(words("ttl poll-interval poll-seconds"));
 const booleans = new Set(words("write close-sessions cancel-queue release-locks user-required requeue acquire-lock"));
@@ -240,7 +297,7 @@ export function prepareCommandRoute(args) {
     const parsed = parseCommandArgs(args);
     const key = Object.keys(commandInputs).filter(key => key.split(" ").every((part, index) => parsed.positional[index] === part))
         .sort((a, b) => b.split(" ").length - a.split(" ").length)[0];
-    const reject = (message, parameter) => { throw new AppError("usage", message, 2, { phase: "prepare", effect: "no_effect", recoverable: true, ...(parameter ? { parameter } : {}) }); };
+    const reject = (message, parameter, reason = "invalid_argument") => { throw new AppError("usage", message, 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason, ...(parameter ? { parameter } : {}) }); };
     if (!key)
         return reject("Unknown command; use dd-flow --help");
     const contract = commandInputs[key];
@@ -259,7 +316,7 @@ export function prepareCommandRoute(args) {
         if (!upgrade && !contract.values.includes(name) && !contract.switches.includes(name))
             reject(`${key} does not accept --${name}`, name);
         if (values.length > 1 && !contract.repeatable.includes(name))
-            reject(`--${name} must occur once`, name);
+            reject(`--${name} must occur once`, name, "duplicate_option");
         for (const value of values) {
             if (contract.switches.includes(name) || name === "mb-upgrade-mode") {
                 if (value !== flag)
@@ -267,26 +324,38 @@ export function prepareCommandRoute(args) {
                 continue;
             }
             if (value === flag || !value.trim())
-                reject(`--${name} requires a non-empty value`, name);
+                reject(`--${name} requires a non-empty value`, name, value === flag ? "missing_option_value" : "empty_option_value");
             if (name === "compatibility-mode" && value !== "mb-upgrade")
-                reject("--compatibility-mode must be mb-upgrade", name);
+                reject("--compatibility-mode must be mb-upgrade", name, "invalid_choice");
             const choices = contract.enums[name];
             if (choices && !choices.includes(key === "id next" && name === "type" ? value.toLowerCase() : value))
-                reject(`--${name} must be ${choices.join(" or ")}`, name);
+                reject(`--${name} must be ${choices.join(" or ")}`, name, "invalid_choice");
             if (booleans.has(name) && !["true", "false"].includes(value))
-                reject(`--${name} must be true or false`, name);
+                reject(`--${name} must be true or false`, name, "invalid_choice");
             const number = Number(value);
-            if (positiveInteger.has(name) && (!/^[0-9]+$/.test(value) || !Number.isSafeInteger(number) || number <= 0)
+            const profileRevision = key.startsWith("profiles ") && name === "expected-revision";
+            if (profileRevision && !/^[a-f0-9]{64}$/.test(value))
+                reject("--expected-revision requires the SHA-256 returned by profiles list", name);
+            if (!profileRevision && positiveInteger.has(name) && (!/^[0-9]+$/.test(value) || !Number.isSafeInteger(number) || number <= 0)
                 || nonnegativeInteger.has(name) && (!/^[0-9]+$/.test(value) || !Number.isSafeInteger(number) || number < 0)
                 || positiveNumber.has(name) && (!Number.isFinite(number) || number <= 0)
                 || name === "timeout" && (!Number.isFinite(number) || number < 0)
-                || name === "available-slots" && number > 15)
-                reject(`Invalid numeric value for --${name}`, name);
+                || name === "available-slots" && number > 15
+                || name === "max-parallel" && number > 256)
+                reject(`Invalid numeric value for --${name}`, name, "invalid_number");
         }
     }
     for (const name of contract.required)
         if (!parsed.options.has(name))
-            reject(`Missing required option: --${name}`, name);
+            reject(`Missing required option: --${name}`, name, "missing_required_option");
+    if (key === "work add-batch" && parsed.options.has("request-key")) {
+        const requestKey = parsed.options.get("request-key")[0];
+        const stage = parsed.options.get("stage")?.[0];
+        if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestKey))
+            reject("--request-key requires a bounded identifier (1..96 characters)", "request-key");
+        if (!stage || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(stage))
+            reject("--request-key requires an explicit bounded --stage", "stage");
+    }
     for (const aliases of [
         ["root", "project-root"], ["payload-file", "json-file"],
         ["payload-file", "payload-json", "payload-base64"], ["semantic-file", "data", "result-file", "result-stdin"],
@@ -296,12 +365,12 @@ export function prepareCommandRoute(args) {
     ]) {
         const present = aliases.filter(name => parsed.options.has(name));
         if (present.length > 1)
-            reject(`Use only one of ${present.map(name => `--${name}`).join(", ")}`);
+            reject(`Use only one of ${present.map(name => `--${name}`).join(", ")}`, [...present].sort(), "duplicate_option");
     }
     if (contract.values.includes("retry-check") && parsed.options.has("retry-check") !== (parsed.options.has("reason") || parsed.options.has("reason-file")))
         reject("--retry-check requires exactly one of --reason or --reason-file");
     // Retain the dispatcher's historic offsets for nested action positions.
     const family = parsed.positional[0];
-    const singleWord = ["status", "version", "transition"].includes(family);
+    const singleWord = ["status", "version", "transition", "init"].includes(family);
     return { key, family, command: singleWord ? undefined : parsed.positional[1], parsed: { options: parsed.options, positional: parsed.positional.slice(singleWord ? 1 : 2) } };
 }

package/dist/cli/command-metadata.js

@@ -0,0 +1,197 @@
+import { commandInputs, physicalPathOptions } from "./command-inputs.js";
+import { runtimeOptionDescriptions } from "./command-option-descriptions.js";
+const optionDescriptions = {
+    "intake-sha256": "SHA-256 of the exact original intake file bytes. Fresh execution verifies the bytes; replay compares the retained hash without reopening the original file.",
+    "stage-profile": "Repeatable stage=profile assignment for the six mb-init stages. Each stage may occur once; the selected profile ID or alias is frozen before dispatch.",
+    "work-profile": "Repeatable approved Work executor profile ID or alias. Explicit order is retained; duplicate profiles refuse.",
+    "git-route": "Explicit project Git integration route. Direct integration uses the integration branch checkout; feature_worktree uses an already assigned separate checkout.",
+    "integration-branch": "Explicit project integration branch, validated with Git before project publication. No branch is inferred from the current checkout.",
+    "detach": "Return the accepted managed-controller receipt without observing until completion. Disconnecting the observer never stops the controller.",
+    "harness": "Select one supported harness family. Static discovery checks executable presence, not authentication or model access; diagnostics require separate effect consent.",
+    "provider": "Exact provider namespace for model filtering or doctor observation binding, including namespaced IDs such as builtin:zai-coding-plan. An account binding requires --account-sha256; this selector does not authenticate credentials.",
+    "executable": "Explicit installed harness executable path, including paths with spaces. Resolves ambiguous installations without choosing an arbitrary PATH candidate. Discovery never executes it; probes require explicit effect flags.",
+    "state-dir": "Existing OpenCode server state directory for the selected doctor. Its daemon configuration must bind the selected executable; doctor does not start or stop an unrelated daemon. Not an executor profile or project directory.",
+    "model-observation-file": "Optional destination for a standalone model listing snapshot from the admitted doctor. Requires --provider and --account-sha256; operator scope is unverified. Artifact publication is explicit, separate from provider writes, and never proves account access. Must differ from --response-file.",
+    "save-profile-intent": "Explicit frozen dd-flow/profile-creation-intent@1 JSON file containing before/after settings, profile and default consent. Setup binds it to request identity, saves under revision CAS and reconciles exact replay. Conflicts with --skip-agent-setup; an additional selected profile must match. This file is not provider authorization.",
+    "set-default": "Explicitly select the newly created profile as global default in the same atomic settings write. Omission preserves the existing default. Does not change frozen RUN settings.",
+    "remove": "Remove the positional operator alias binding, not its target profile; conflicts with --target.",
+    "clear": "Clear the operator global default without removing profiles or changing project routing and frozen RUN snapshots.",
+    "allow-processes": "Explicit permission to execute installed diagnostic code. Version/doctor probes are opt-in; static discovery never requires this flag.",
+    "allow-services": "Permit the selected adapter doctor's possible service process effects. Does not authorize model Turns, a flow, or reuse of an unrelated service.",
+    "allow-credentials": "Permit possible credential reads by the installed diagnostic; no credentials or raw adapter output enter this command's result.",
+    "allow-writes": "Permit possible diagnostic temporary/runtime writes by installed code; not permission to modify project packs or RUN settings.",
+    "native-executable": "Absolute native ZCode executable for the selected ZCode ACP doctor; no ambient ZCODE_BIN fallback. Invalid for other families.",
+    "timeout-ms": "Timeout in milliseconds for the selected operation. Harness diagnostics accept 1..60000: version defaults to 3000 and doctor to 30000. Other commands retain their own operation timeout policy; this option is not a productive RUN inactivity policy.",
+    "seed-file": "Optional reviewed dd-flow/model-catalog@1 JSON input; default is the bundled seed. Seed-only entries cannot establish account access or runtime qualification.",
+    "observation-file": "Explicit regular-file model listing snapshot; requires --harness, --provider and --account-sha256. Foreign scopes are ignored; malformed or secret-bearing fields refuse. No live listing is started.",
+    "account-sha256": "Opaque 64-character lowercase SHA-256 account binding, never an account name, token or credential path. Requires --harness and --provider; does not authenticate the account.",
+    "canon-source": "Explicit local signed release bundle or HTTPS envelope URL. Remote archives must use the same origin; trust comes only from --trust-file. Exclusive with --canon-version.",
+    "canon-version": "Exact canon release version in the selected channel of the operator release registry; exclusive with --canon-source. Omission selects the registry's explicit channel default.",
+    "release-registry": "Operator dd-flow/release-registry@1 JSON selector; default is DD_FLOW_RELEASE_REGISTRY or release-registry.json in DD_FLOW_HOME. Registry entries never enroll signing keys.",
+    "trust-file": "Explicit operator dd-flow/release-trust@1 file; release bytes cannot enroll their own signing key.",
+    "channel": "Selected release channel; preview and development must be requested explicitly.",
+    "skip-agent-setup": "Install without selecting or configuring an executor; conflicts with --profile.",
+    "non-interactive": "Never request interactive input; a missing executor selection fails unless agent setup is explicitly skipped.",
+    "project-root": "Stable repository identity; not the assigned feature workspace.",
+    "workspace-root": "Concrete assigned checkout used for this operation.",
+    "workspace-path": "Concrete assigned checkout; does not change project identity.",
+    "root": "Explicit root for the selected command; prevents implicit root discovery.",
+    "run": "Exact retained RUN identity; its frozen execution settings remain authoritative.",
+    "reason": "Operator explanation retained with the requested change.",
+    "request-id": "Stable request identity for reconciliation and idempotent retry.",
+    "request-key": "Stable exact-request replay identity; changed inputs or missing independent custody refuse rather than allocate again. The owning command defines scope and syntax.",
+    "expected-revision": "Required current revision; stale changes are rejected instead of overwriting concurrent edits.",
+    "profile": "Explicit configured profile identifier; credentials are not stored in profiles.",
+    "profile-file": "Complete validated executor profile; exclusive with --profile and --skip-agent-setup. Does not change operator defaults.",
+    "agent-profile": "Explicit configured executor profile; no automatic model selection.",
+    "force": "Explicit force request; does not bypass ownership, compatibility or authorization gates.",
+    "offline": "Explicit drained/offline operation; does not establish physical settlement by itself."
+};
+/** Option names alone are insufficient when different commands own different inputs. */
+const memoryRepairOptions = {
+    run: "Active registered mb-init review RUN; retained correction graph and frozen execution own every repair operation.",
+    wave: "Exact causal correction wave 1 or 2; never falls back to another wave or permits a third wave.",
+    work: "Exact registered repair Work in the selected correction wave; foreign Work and generation custody refuse.",
+    "workspace-root": "Shared frozen RUN workspace, not the private repair copy; independent source and scope custody remain required.",
+    "work-session": "Exact independently started repair WorkSession; this command never creates or claims a provider Session."
+};
+const memoryInitOptions = {
+    "prepare-only": "Prepare or replay the frozen Memory RUN and project bootstrap without launching a controller or provider Session. This publishes project/runtime state; it is not a dry run. Use run drive launch with the returned RUN to select bounded observation/capture. Exclusive with --detach; replay never stops an existing controller.",
+    "profile-file": "Absolute regular JSON file with one complete validated operation-only executor profile. Exclusive with --profile; never saves settings or changes defaults. Omit on replay to reuse frozen bytes; supplied profile content must match the original selection.",
+    "non-interactive": "Never open the first-flow executor dialog, even on a terminal. Without an explicit profile/file or configured default, refuse before project effects; init cannot skip its executor."
+};
+const commandOptionDescriptions = {
+    "flow mb-init": memoryInitOptions,
+    init: memoryInitOptions,
+    "runtime storage admit": { operation: "Operation-specific writable-connection admission: memory-init only. Requires explicit canonical DD_FLOW_HOME and an existing compatible resource registry. Never initializes, migrates, repairs or starts agents." },
+    "runtime flow admit": { operation: "Memory-init handler admission in the executing engine. Reads bounded UTF-8 JSON stdin with source and source_sha256; optional startup_input_schema additionally requires support by this engine's startup reader. Validates the exact six-stage descriptor using actual registered handlers. Does not establish release trust, storage/provider readiness or semantic completion, and never creates Home, RUN or agents." },
+    "profiles create": { file: "Regular UTF-8 JSON file containing one complete validated agent profile. The ID must be unused. Credentials and unknown fields are refused; creation uses --expected-revision and never starts a model Turn." },
+    "profiles edit": { file: "Regular UTF-8 JSON file containing the complete replacement agent profile, not a patch. Its ID must already exist. Revision conflicts refuse the edit; retained RUN snapshots are unchanged." },
+    "profiles alias": {
+        target: "Existing canonical profile ID for the positional alias. Aliases cannot chain or collide with profile IDs. Supply exactly one of --target or --remove, plus --expected-revision.",
+        remove: "Remove the positional alias, not its target profile. Exclusive with --target. The revision-checked change does not rewrite retained RUN settings."
+    },
+    "profiles set-default": { clear: "Clear only the operator global default. Exclusive with a positional profile ID or alias; existing profiles, project routing and frozen RUN settings remain unchanged." },
+    "work add-batch": {
+        file: "Validated Work batch JSON file declaring children of --parent, including their task and dependency inputs. Adding logical Work does not launch physical Sessions.",
+        stage: "Explicit owner stage. With --request-key it must be the active running coordinator stage; attempt and cycle are resolved from retained RUN authority.",
+        "request-key": "Stable registration ID (1..96 letters, digits, dots, underscores or hyphens, starting with a letter or digit). Requires --stage. Identical replay returns the retained Work IDs; changed input or missing custody refuses allocation. Without this option the historical non-replayable batch behavior is retained."
+    },
+    "schema validate": { file: "JSON document to validate against --schema in the selected schema directory. Validation does not execute a flow or accept semantic completion." },
+    "migration verify": { file: "Existing dd-flow/mb-upgrade-migration-report@1 JSON report to verify against migration evidence; verification does not apply a storage migration." },
+    "migration apply": { file: "Explicit migration report JSON file used for admission to the requested apply operation; backup and ownership gates remain mandatory." },
+    "prompt render": { profile: "Prompt profile name required by the assigned Work execution context; not an operator executor profile ID or a Codex home profile." },
+    "runtime process register": { harness: "Harness family associated with the registered process/budget; registration is not a discovery or doctor probe.", "state-dir": "Adapter runtime state directory retained with the physical process for later ownership/admission checks." },
+    "runtime process admission": { "state-dir": "Exact adapter runtime state directory matching the confirmed process record; mismatched ownership refuses provider admission." },
+    "runtime process release-turn": { "observation-file": "Provider turn release observation file for the selected daemon/operation budget. This is not a model inventory snapshot or account listing." },
+    "runtime scope control": { mode: "Recoverable scope control intent: pause or stop. Drain/settlement remains pending until owned physical evidence is confirmed." },
+    "merge request route": { mode: "Route this MERGE request through same_session or server; selected execution policy and workspace admission still apply." },
+    "worktree close": { mode: "keep retains the feature checkout; remove requests its guarded removal. Dirty or foreign worktrees must not be silently discarded." },
+    "codex home remove": { mode: "keep-shared preserves shared state; remove-owned removes only the verified project-owned home entries.", profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
+    "codex home plan": { profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
+    "codex home init": { profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
+    "codex home status": { profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
+    "codex home print-env": { profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
+    "codex hooks print": { target: "Hook installation target: isolated (default) or default Codex home. Printing does not install hooks.", profile: "Project Codex home profile used to locate isolated hooks; not an executor profile." },
+    "codex hooks status": { target: "Hook installation target: isolated (default) or default Codex home. Status does not install hooks.", profile: "Project Codex home profile used to locate isolated hooks; not an executor profile." },
+    "codex hooks install": { target: "Hook installation target: isolated (default) or default Codex home; mutation also requires explicit confirmation.", profile: "Project Codex home profile used to locate isolated hooks; not an executor profile." },
+    "codex hooks remove": { target: "Hook installation target: isolated (default) or default Codex home; removal also requires explicit confirmation.", profile: "Project Codex home profile used to locate isolated hooks; not an executor profile." },
+    "protocol sync-from-run": { target: "Protocol state target derived from the selected RUN; auto uses the command's supported state mapping." },
+    "run reconcile": {
+        apply: "Persist the observed RUN health under its current ownership and revision fences. Without this switch, report only; never launch, resume or stop a provider.",
+        "no-progress-ms": "Override the health-assessment progress-age threshold in milliseconds; integer at least 1000. Defaults are 120000 for starting, 300000 for capturing and 1800000 otherwise. This is not a productive command timeout or permission to stop a live owner."
+    },
+    "run fork": { from: "Existing retained snapshot path to fork into a new RUN with the explicitly selected engine; not a control request identity." },
+    "run control resume": { from: "Exact retained pause/stop control ID whose captured state authorizes this resume request; not a snapshot path." },
+    "stage block": { kind: "Blocker category: engine, harness or environment; code and summary identify the actionable cause." },
+    "migration impact": { mode: "Optional full_migration request forces the strict full-migration assessment; otherwise impact evidence determines patch, targeted_minor or full_migration." },
+    "memory permissions preflight": { mode: "Permission contour to check: read, write, repair or report_only; write checks may create temporary permission probes.", flow: "Workflow permission contour: mb-init, mb-upgrade, mb-audit, mb-fix, mb-upgrade-review or custom. Not a filesystem path." },
+    "memory compose register": { "run": "Active registered mb-init RUN whose accepted discovery and immutable execution bind the composition graph.", "request-key": "Stable composition registration identity; exact replay retains the original Work graph.", "result-file": "Bounded proposed composition JSON. Bytes are prepared before registration; agent fields do not grant Work or write authority." },
+    "memory verify checks": { "run": "Active registered mb-init RUN. Execute only its independently selected declared verification checks." },
+    "memory review register": { "run": "Active registered mb-init RUN with accepted verification. Register initial independent reviewers; this does not launch providers." },
+    "memory review collect": { "run": "Active registered mb-init RUN. Collect genuine registered initial-wave results without accepting the Stage or granting correction authority." },
+    "memory finish evidence": { "run": "Active registered mb-init finish RUN. Publish independently prepared coverage, integration and readiness evidence; publication does not complete Stage or RUN." },
+    "memory finish integrate": { "run": "Active mb-init finish RUN. Commit only accepted Memory Bank and owned lint files under retained Git policy, then integrate the admitted workspace locally. Preserve unrelated staged/dirty files; never push. Lost-response replay observes the original effects without another commit." },
+    "memory corrections register": { run: "Active registered mb-init review RUN. Register only the correction plan bound to the independently retained preceding review.", wave: "Correction wave 1 follows initial review; wave 2 requires settled first selective review. A third wave is unsupported.", "result-file": "Bounded correction-plan JSON prepared before graph registration; exact retained replay cannot substitute another plan." },
+    "memory corrections checks": { run: "Active registered mb-init review RUN with a genuinely settled correction view.", wave: "Run only the independently selected finite check profile for correction wave 1 or 2; this does not accept semantic quality." },
+    "memory review selective-register": { run: "Active registered mb-init review RUN. Allocate selective reviewers only after their wave's committed checks.", wave: "Select correction wave 1 or 2. Unaffected accepted units remain retained; registration does not launch providers." },
+    "memory review selective-collect": { run: "Active registered mb-init review RUN. Return genuine selective reviewer references, not Stage or RUN acceptance.", wave: "Select independently registered review of correction wave 1 or 2; missing wave custody never falls back to initial review." },
+    "memory repair baseline": { ...memoryRepairOptions, work: "Register the immutable prelaunch baseline for this repair Work; dependent/peer changes require explicit current-view registration first. Does not launch providers." },
+    "memory repair copy-reserve": { ...memoryRepairOptions, work: "Reserve the owned private copy for this repair Work after its committed baseline; reservation does not create the copy or launch providers." },
+    "memory repair copy-materialize": { ...memoryRepairOptions, work: "Materialize the reserved private copy for this repair Work with retained build/ready receipts; no provider launch or shared document publication." },
+    "memory repair copy-dispatch": { ...memoryRepairOptions, work: "Prepare the frozen profile and verified ready-copy root for this repair Work. Read-only packet output does not launch a provider, claim a Session or replace fresh launcher custody checks." },
+    "memory repair current-view": { ...memoryRepairOptions, work: "Retain the explained settled-peer input view for this repair Work; does not replace an existing immutable baseline or grant launch authority." },
+    "memory repair publication-source": { ...memoryRepairOptions, wave: "Wave 1 only: retain independently explained shared publication source before reserving output. Wave 2 uses its separate retained launch owner." },
+    "memory repair publication-reserve": { ...memoryRepairOptions, "result-file": "Bounded exact private repair result bytes prepared before dispatch. Reserve the independently validated delta only; wave 1 requires a previously registered publication-source." },
+    "memory repair publication-apply": { ...memoryRepairOptions, work: "Apply or reconcile one retained publication action for this repair Work; repeat until physical publication completes. Unknown effect never authorizes blind retry." },
+    "memory repair publication-finish": { ...memoryRepairOptions, work: "Settle this repair Work only after independently proven physical publication completion; does not accept semantic review or finish Stage/RUN." }
+};
+export const globalOptionDocumentation = [
+    { name: "help", description: "Show help before command preparation or resource access; -h is equivalent.", kind: "switch", required: false, repeatable: false, choices: [], physical_path: false },
+    { name: "option", description: "Help-only selector for one option; accepts name or --name.", kind: "value", required: false, repeatable: false, choices: [], physical_path: false },
+    { name: "json", description: "Emit structured JSON rather than human text.", kind: "switch", required: false, repeatable: false, choices: [], physical_path: false },
+    { name: "progress-jsonl", description: "Emit machine-readable progress events during command execution.", kind: "switch", required: false, repeatable: false, choices: [], physical_path: false },
+    { name: "response-file", description: "Execution-only response destination; help never opens or writes it.", kind: "value", required: false, repeatable: false, choices: [], physical_path: true }
+];
+export function optionsForCommand(input, command) {
+    return [...new Set([...input.values, ...input.switches])].map(name => ({
+        name,
+        description: optionDescription(name, command),
+        kind: input.switches.includes(name) ? "switch" : "value",
+        required: input.required.includes(name), repeatable: input.repeatable.includes(name),
+        choices: input.enums[name] ?? [], physical_path: physicalPathOptions.has(name) && name !== "flow" && name !== "stage"
+    }));
+}
+function optionDescription(name, command) {
+    const description = (command ? commandOptionDescriptions[command]?.[name] : undefined) ?? optionDescriptions[name] ?? runtimeOptionDescriptions[name];
+    if (!description)
+        throw new Error(`Missing CLI option documentation: ${command ?? "inventory"} --${name}`);
+    return description;
+}
+/** Shared help/completion option set for a route, family or root catalog. */
+export function optionsForCommandTree(command) {
+    const options = new Map(globalOptionDocumentation.map(option => [option.name, option]));
+    for (const [key, input] of Object.entries(commandInputs)) {
+        if (!command || key === command || key.startsWith(`${command} `)) {
+            for (const option of optionsForCommand(input, key))
+                options.set(option.name, option);
+        }
+    }
+    return [...options.values()].sort((left, right) => left.name.localeCompare(right.name, "en"));
+}
+/** One exact native routing classification shared by router and compatibility admission. */
+export function routerNativeRoute(key) {
+    return key === "version" || key.startsWith("engine ") || key === "schema validate"
+        || key === "flow list" || key === "flow show" || key === "flow mb-init" || key === "init"
+        || key === "run reconcile" || key === "runtime storage admit"
+        || key === "runtime flow admit"
+        || key.startsWith("profiles ") || key.startsWith("models ") || key.startsWith("harnesses ") || key.startsWith("completion ") || key === "setup" || key.startsWith("setup ")
+        || key === "storage migrate-writer" || key === "codex hook handle"
+        || key === "zcode hook handle" || key === "zcode invocation prepare"
+        || /^(zcode|grok|droid|opencode|agy) (event handle|usage ingest)$/.test(key);
+}
+export function commandKeyForPositions(positions) {
+    return Object.keys(commandInputs).filter(key => key.split(" ").every((part, index) => positions[index] === part))
+        .sort((a, b) => b.split(" ").length - a.split(" ").length)[0];
+}
+/** Best matching help topic for rejected argv; never validates or executes it.
+ * Option values and literal passthrough cannot impersonate a command path.
+ */
+export function commandHelpTopic(args, fallback) {
+    const switches = new Set([...globalOptionDocumentation.filter(option => option.kind === "switch").map(option => option.name),
+        ...Object.values(commandInputs).flatMap(input => input.switches)]);
+    const positions = [];
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--")
+            break;
+        if (arg.startsWith("--")) {
+            const name = arg.slice(2).split("=", 1)[0];
+            if (!arg.includes("=") && !switches.has(name) && args[index + 1] && !args[index + 1].startsWith("-"))
+                index++;
+        }
+        else if (!arg.startsWith("-"))
+            positions.push(arg);
+    }
+    return commandKeyForPositions(positions) ?? fallback;
+}