@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.151

package/README.md

@@ -1,5 +1,71 @@
 # dd-flow-cli
 
+See [dd-zcode integration](src/harness-runtime/DD-ZCODE.md) for native transport,
+adapter ownership and the versioned bridge contract.
+
+## OpenCode v2
+
+`dd-opencode` supports OpenCode v2 only; the final v1 source is tagged
+`archive/opencode-v1-final-beta134`. Client/plugin build inputs are pinned to
+2.0.28; build copies the unmodified self-contained upstream Promise assets.
+Optional AI/Effect/TUI dependency graphs are not production engine dependencies.
+Select the native executable with `--opencode-bin`, portable JSON/JSONC provider
+config with `--config-path` and selected credentials with `--auth-path` (legacy
+provider auth map or native v2 credential-list JSON). Credentials are loaded and
+verified in the owned private DB, never copied from the user's Session DB.
+
+The adapter owns an unregistered loopback `serve` instance, private XDG paths,
+DB and launch-bound dd-flow plugin. It does not install a global user plugin or
+load third-party plugins. `doctor` checks the native instance and productive
+plugin separately from model qualification. No-flow probes load only the owned
+secret-stripping security definition, without lifecycle admission. V1 states/archives are rejected
+without migration; use a fresh v2 state directory.
+
+Prompt acknowledgement means inbox admission, not success. Lost replies are
+reconciled read-only against the same message ID; `session resume` never wakes
+execution. Native projected user/idle records prove delivery/outcome because
+CLI v2 does not persist full event payloads by default. Model/tool deltas and
+new owned shell output sustain the shared sliding observer. Proven terminal
+overload uses the shared continuation policy; quota/auth and unknown effects
+do not authorize a prompt replay. `session fork --message-id` means **before**
+that message, recorded in the native boundary receipt.
+
+Technical native probes use a local stub, not scored EVALs:
+`DD_TEST_OPENCODE_V2=<absolute-v2-binary> node --test test/fixtures/opencode-v2-native.mjs test/fixtures/opencode-v2-plugin-native.mjs`.
+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
+before ACK; clients also verify the retained daemon PID has exited. A missing
+socket alone is not physical shutdown proof.
+
+Partial cleanup preserves the same incarnation's completed phases in
+`daemon.json` (`dd-flow/daemon-shutdown@1`). A fresh control operation can finish
+remaining cleanup without replaying agent work or inspecting a closed pipe.
+Failed operation IDs remain immutable. Unknown ownership and persistent EPERM
+remain failures; never remove sockets or repair runtime databases manually to
+make an outcome look clean.
+
+Shutdown proof records `required_phases`; every recorded phase must be complete,
+including native tree and daemon resource settlement. A `clean` label without
+this proof cannot authorize retained restart. `stopping`, `cleanup_failed` and
+`unclean` cannot start a replacement native bridge. Forced AGY termination
+without a current native terminal receipt is unclean, even after a previous
+successful Turn. Mandatory stream-journal failures remain failures after
+physical cleanup. Listener retirement must not unlink a replacement endpoint.
+
 ## Managed temporary HTTP services
 
 For an interactive scenario, `runtime process start --run <RUN-ID>
@@ -17,6 +83,36 @@ Never use a broad `pkill`/`killall`. A failed owned stop retains resources.
 
 It does not replace Memory Bank prompts and does not make product, design, merge, or verification judgments. Prompts own intent, route selection, planning depth, evidence meaning, and semantic readiness. The CLI owns explicit local state: projects, protocols, Codex session bindings, transitions, worktree records, lanes, locks, merge queue jobs, hook records, and audit events.
 
+## Factory Droid harness
+
+Configure `droid-cli` in `~/.dd-flow/harnesses.json` with absolute
+`adapter_command` (`dd-droid`) and `runtime_command` (`droid`) paths. Agent
+profiles use the `droid` alias; the adapter receives `--droid-bin`.
+
+The controlled adapter sends `dd-flow/droid-tool-event@1` JSON to
+`dd-flow droid event handle --project-root <root> --json`. Events include a
+stable `event_id`, `daemon_id`, `phase` (`before` or `after`), native Session
+identity and parent, absolute Session directory, `Execute` input, observed
+profile and transcript path. Before a lifecycle invocation, the returned
+`hookSpecificOutput.updatedInput` adds its one-use `--hook-event-id` receipt.
+The event ID belongs to the native hook invocation and is reused only for
+transport retries. Session success is established by the Work contract.
+
+`dd-flow droid usage ingest --project-root <root> --json` accepts cumulative
+per-Session counters with explicit `usage_scope: physical_session` and
+`completeness: complete|partial`. Inclusive root counters are rejected;
+partial windows remain unavailable in RUN totals until complete evidence
+arrives. Keep inclusive provider totals in adapter evidence for reconciliation.
+
+## Check evidence
+
+Checks write evidence into their invocation's `DD_FLOW_EVIDENCE_DIR`. Receipts
+retain and hash every regular file in that directory, including nested files.
+`required_artifacts` specifies the minimum files needed to pass, so an empty
+list still permits supplemental screenshots or reports. Missing required files
+fail the check. Symlinks are not followed or registered. The same collection
+rules apply when recovering a detached check from its completion marker.
+
 ## Runtime Model
 
 Root local database:
@@ -65,6 +161,8 @@ dd-flow canon status --json
 
 `canon resolve` checks explicit `--root`, then `DD_MEMORYBANK`, then the globally registered value in `DD_FLOW_HOME`, then known nearby `dd-memorybank` checkouts from the current working directory. If two different valid canonical roots are discovered, it fails closed with structured blockers and bootstrap hints. Use `DD_MEMORYBANK` for the local canonical `dd-memorybank` checkout.
 
+With no explicit, environment or registered source, the release installed by `setup` in `DD_FLOW_HOME` takes precedence over nearby checkouts. Archive provenance comes from its retained release manifest. A degraded installation does not silently fall back to a local checkout. Discovery remains read-only and does not open SQLite before runtime context admission.
+
 Register a project:
 
 ```bash
@@ -412,13 +510,44 @@ remain invalid and receive a standalone retry.
 
 ## Verification
 
-Local verification for this repository:
-
-```bash
-pnpm test
-pnpm typecheck
-pnpm lint
-pnpm build
-```
-
-Manual smoke checks should use a temporary `DD_FLOW_HOME` when they do not intentionally inspect the operator's real local state.
+Checks follow changed contracts, not a merge/release/EVAL event. Inspect
+`pnpm verify:plan`, then run `pnpm test` (or `pnpm gate:merge`) for only missing
+affected contracts. `scripts/verification-policy.mjs` owns impact selection;
+existing Node/Vitest runners retain complete selected-file/case evidence.
+Unknown impact requires an explicit policy mapping, never a full-suite fallback.
+
+There is no mandatory full release gate. Freeze source/canon, build and pack the
+exact artifact, then accept with `DD_FLOW_VERIFICATION_RECEIPT` pointing to the
+scoped verification receipt. Preserve receipts outside the checkout. Unchanged
+contract inputs reuse intact reports; commit/version/build time alone do not
+invalidate behavior evidence. Failed/unknown attempts require investigation,
+not automatic retries. Package identity and registry readback remain mandatory.
+GitHub CI is disabled. Publication does not repeat the accepted package's smoke
+after identical registry tar readback. EVAL preparation is resource readiness,
+not another engine or product test suite.
+The [verification runbook](https://github.com/deksden-com/dd-eval/blob/main/runbooks/flow-test-suite-verification.md)
+owns the local procedure. A scoped PASS is not a claim that every test ran.
+
+### RUN status during recovery
+
+A controller failure pauses the logical RUN without rewriting its Stage/Work
+outcomes. Accepted pause/stop or recovery intent immediately persists `paused` in the RUN row,
+`index_json`, and `run.json`. A trusted recovery acknowledgement restores the
+operational status; an existing Stage/Work pause remains paused. Terminal RUNs
+are never reopened. Physical tree settlement remains a separate control receipt.
+
+Legacy stores with a fenced recovery may still contain `running`. After building,
+inspect one exact RUN with:
+
+```sh
+node tools/repair-paused-run-status.mjs --home /path/to/dd-flow-home --project PRJ-001-project --run RUN-001-eval-subject
+```
+
+Add `--apply` to repair it. This requires the latest recovery to be draining, sealed or resuming, saves the original row and runtime JSON
+beside `run.json`, and changes no schema, engine binding or recovery capture.
+It does not claim physical settlement or alter its receipts. `--cancel-abandoned`
+explicitly cancels an abandoned fixture only when the project directory is absent
+and it has no Work, Session, controller or recovery history. Historical experiment
+engine snapshots remain pinned; rebuild/release the engine for future executions.
+
+`dd-flow run reconcile [RUN] --json` проверяет сохранённые статусы без dispatch; `--apply` сохраняет согласованную health-проекцию. Возраст записи даёт предупреждение, а не доказательство ошибки. Ожидания и потеря владельца различаются; обслуживание не сигналит процессам и не перехватывает leases.

package/dist/build-info.json

@@ -1,15 +1,15 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.15",
-  "cli_commit": "e11a611fe87370d6203792e5c6a54d7205235a26",
-  "built_at": "2026-09-05T09:50:59.828Z",
+  "cli_version": "0.9.0-beta.151",
+  "cli_commit": "89cad0d654601de59b12929240eee4e958b74207",
+  "built_at": "2026-10-25T10:59:05.638Z",
   "built_with_canon": {
-    "version": "4.0.4",
-    "commit": "c8cae271f844fd3b3c7492f164e13a60eaba4839",
+    "version": "4.1.2",
+    "commit": "925ef10ecc0b683f7feba6f74913e15560842500",
     "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-cp253",
+    "memorybank_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-memorybank-cp253/.memory-bank",
+    "flow_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-memorybank-cp253/.memory-bank/dd-flow",
     "layout": "dot_memory_bank"
   }
 }

package/dist/cli/argument-values.js

@@ -0,0 +1,38 @@
+import { AppError } from "../shared/errors.js";
+const flagValue = "__dd_flow_flag__";
+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, { parameter: key, reason: "missing_option_value" });
+    if (value !== undefined && !value.trim())
+        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, { parameter: key, reason: "missing_required_option" });
+    }
+    return value;
+}
+export function optionalNumber(parsed, key) {
+    const value = optionalOption(parsed, key);
+    if (typeof value === "undefined") {
+        return undefined;
+    }
+    const parsedNumber = Number(value);
+    if (!Number.isFinite(parsedNumber)) {
+        throw new AppError("validation", `--${key} must be a number`, 2, { parameter: key, reason: "invalid_number" });
+    }
+    return parsedNumber;
+}
+export function optionalPositiveNumber(parsed, key, integer = false) {
+    const value = optionalNumber(parsed, key);
+    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, { parameter: key, reason: "invalid_number" });
+    }
+    return value;
+}

package/dist/cli/command-inputs.js

@@ -0,0 +1,386 @@
+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-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,
+    required: words(required), values: words(`${required} ${values}`), switches: words(switches), repeatable: words(repeatable), enums
+});
+const project = "project-root";
+const scoped = "project-root"; // Optional when the router resolves a unique retained scope.
+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"] });
+const diagnosticInput = route(0, "project-root request-id", "intake-file profile profile-file stage-profile work-profile max-parallel", "detach non-interactive prepare-only", "stage-profile work-profile");
+export const commandAliases = { transition: "protocol transition", init: "flow mb-init", upgrade: "flow mb-upgrade", review: "flow project-review" };
+/** 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("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,
+    "flow mb-upgrade": memoryInitInput,
+    "upgrade": memoryInitInput,
+    "flow mb-audit": diagnosticInput,
+    "flow project-review": diagnosticInput,
+    "review": diagnosticInput,
+    "runtime storage admit": route(0, "operation", "", "", "", { operation: ["memory-init", "memory-upgrade"] }),
+    "runtime storage qualify": route(0, "operation", "", "", "", { operation: ["memory-upgrade"] }),
+    "runtime storage transition": route(0, "action project-root workspace-root request-id selection-sha256", "expected-sha256 recovery-id", "offline", "", { action: ["plan", "apply", "status", "recovery-plan", "recover", "recovery-status"] }),
+    "runtime flow admit": route(0, "operation", "", "", "", { operation: ["memory-init", "memory-upgrade", "mb-audit", "project-review"] }),
+    "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"),
+    "project summary": route(0, project, "write"),
+    "project resolve": route(1),
+    "project archive": route([0, 1], "reason", "root"),
+    "project migrate-ids": route(0, "root", "", "apply"),
+    "project config status": route(0, project),
+    "project config set": route(0, `${project} key value`),
+    "protocol register": route(1, project, "workspace-path"),
+    "protocol status": route(1, "", scoped),
+    "protocol branch-status": route([0, 1], "", `${scoped} path`),
+    "protocol ready": route(0, project),
+    "protocol blockers": route(1, project),
+    "protocol implement": route(1, "", `${scoped} reason`, "force"),
+    "protocol ready-for-merge": route(1, "", scoped),
+    "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),
+    "plan reviews": { ...route(0), retired: "PLAN review dispatch moved to: dd-flow plan-review dispatch <RUN>" },
+    "plan item start": route(2, "", scoped),
+    "plan item done": route(2, "summary", `${scoped} evidence`, "", "evidence"),
+    "plan item block": route(2, "reason user-required", scoped),
+    "plan item skip": route(2, "reason", scoped),
+    "plan-review dispatch": route(1, "", scoped),
+    "prompt render": { ...route(0, `${project} run stage profile`, "workspace-root task-file plan-item"), contextualPaths: words("project-root workspace-root task-file") },
+    "stage start": { ...route([0, 1], `${project} stage`, `${lifecycle} dir subject intake-file context-file context-sha256`, "bootstrap intake-stdin require-session-binding"), contextualPaths: words("project-root intake-file context-file") },
+    "stage finish": { ...route(1, `${project} stage`, `${lifecycle} dir semantic-file data result-file outcome decision-file verification-file retry-check reason reason-file request work`, "result-stdin"), contextualPaths: words("project-root semantic-file result-file decision-file verification-file reason-file") },
+    "stage pause": { ...route(1, `${project} stage work`, `${lifecycle} question-file`, "question-stdin"), contextualPaths: words("project-root question-file") },
+    "stage resume": { ...route(1, `${project} stage work`, `${lifecycle} answer-file`, "answer-stdin"), contextualPaths: words("project-root answer-file") },
+    "stage block": { ...route(1, `${project} stage work kind code`, "summary-file", "summary-stdin retryable", "", { kind: ["engine", "harness", "environment"] }), contextualPaths: words("project-root summary-file") },
+    "stage unblock": route(1, `${project} stage work`),
+    "stage fanout status": route(1, "stage", scoped),
+    "stage fanout dispatch": route(1, "stage", scoped),
+    "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} 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") },
+    "work deps add": route(1, "on", scoped, "", "on"),
+    "work deps remove": route(1, "on", scoped, "", "on"),
+    "work deps list": route(1, "", scoped),
+    "work deps clear": route(1, "", scoped),
+    "work delete": route(1, "", scoped),
+    "work launch": route(1, "", `${scoped} stage`),
+    "work start": { ...route(1, "", `${scoped} ${lifecycle} recovery-id`), contextualPaths: ["project-root"] },
+    "work finish": { ...route(1, "", `${scoped} ${lifecycle} result-file retry-check reason reason-file`, "result-stdin"), contextualPaths: words("project-root result-file reason-file") },
+    "work fail": { ...route(1, "reason", `${scoped} ${lifecycle}`), contextualPaths: ["project-root"] },
+    "work cancel": route(1, "reason", scoped),
+    "work retry": route(1, "reason", scoped),
+    "session register": { ...route(0, "", `${scoped} ${lifecycle} payload-base64 payload-json payload-file session-id`), contextualPaths: words("project-root payload-file") },
+    "session status": route(0, project, "session-id worker-id"),
+    "session stop": route(0, `${project} session-id reason`),
+    "session stop-worker": route(0, `${project} worker-id reason`),
+    "session usage sync": route(0, project, "session-id"),
+    "run start": route(0, `${project} flow-kind subject-type subject-id slug`, "workspace-root next-action preset task-profile-file execution-routing-file protocol-override-file flag", "", "flag"),
+    "run prepare-vnext-specify": route(0, `${project} slug`, "execution-routing-file"),
+    "run status": route(1, project),
+    "run reconcile": route([0, 1], "", "project-root no-progress-ms", "apply"),
+    "run list": route(0, project),
+    "run timeline": route(1, project, "hide", "", "hide"),
+    "run config status": route(1, project),
+    "run config set": route(1, `${project} key value reason`),
+    "run vars ls": route(1, project),
+    "run vars get": route(1, `${project} key`),
+    "run vars set": route(1, `${project} key value`),
+    "run flags status": route(1, project),
+    "run flags revise": route(1, `${project} expected-revision idempotency-key`, "flag preset reason", "allow-downgrade", "flag"),
+    "run attach-stage": route(1, `${project} stage dir status`, "data-schema-id"),
+    "run complete-stage": route(1, `${project} stage status`, "stage-report dashboard data data-schema-id report alias", "", "alias"),
+    "run complete": { ...route(0), retired: "run complete is retired; only an operator may use run override" },
+    "run override": route(1, `${project} status reason`, "verdict next-action", "", "", { status: ["cancelled", "failed"] }),
+    "run capacity record": route(1, `${project} available-slots`),
+    "run recovery inspect": route(1, project),
+    "run recovery begin": route(1, `${project} interruption-json`),
+    "run recovery seal": route(1, `${project} recovery-id settlement-json`),
+    "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 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"),
+    "run fork": route(0, "from output engine-version request-id", "integrity-checksum operational-decision-file"),
+    "run drive status": route(0, control, "after"),
+    "run drive launch": route(0, `${control} request-id context-file context-sha256`, "stop-after capture-root"),
+    "run drive serve": route(0, `${control} controller-id`),
+    "run drive answer": route(0, `${control} request-id pause-id answer-file`),
+    "run drive context": route(0, `${control} controller-id request-id stage context-file context-sha256`),
+    "run control status": route(0, control),
+    "run control reconcile": route(0, `${control} control-id request-id`),
+    "run control resume": route(0, `${control} request-id from`, "wait-ms"),
+    "run control serve": route(0, `${control} control-id`),
+    "run control pause": route(0, `${control} request-id`, "grace-ms wait-ms escalate", "force"),
+    "run control stop": route(0, `${control} request-id`, "grace-ms wait-ms escalate", "force"),
+    "runtime scope fence": route(0, "scope-id request-id"),
+    "runtime scope status": route(0, "", "scope-id scope-ids-json"),
+    "runtime scope stop": route(0, "scope-id request-id"),
+    "runtime scope control": route(0, "scope-id request-id mode", "manifest-json", "", "", { mode: ["pause", "stop"] }),
+    "runtime scope serve": route(0, "scope-id generation"),
+    "runtime scope resume": route(0, "scope-id request-id generation capture-key"),
+    "runtime scope reconcile": route(0, "scope-id generation request-id"),
+    "runtime process check-admission": route(0, "id lease-token"),
+    "runtime process start": route(0, `${control} command ports ready-port`, "ready-path ready-timeout-ms"),
+    "runtime process stop": route(0, "id lease-token", "grace-ms"),
+    "runtime process register": route(0, "kind owner", "id lease-ms budget-json project-id run pid process-group-id owner-pid work check operation stdout stderr harness dispatch-barrier role state-dir adapter-executable"),
+    "runtime process confirm": route(0, "id lease-token pid", "owner-pid lease-ms process-group-id"),
+    "runtime process heartbeat": route(0, "id lease-token", "lease-ms registration-sha256"),
+    "runtime process admission": route(0, "id lease-token owner state-dir", "daemon-id operation-id operation native-session-id prompt-sha256"),
+    "runtime process release-turn": route(0, "id lease-token owner daemon-id", "operation-id observation-file"),
+    "runtime process finish": route(0, "id lease-token state", "reason", "", "", { state: ["stopped", "failed"] }),
+    "runtime process status": route(0, "", "id lease-token registration-sha256"),
+    "runtime process reconcile": route(0, "owner", "grace-ms"),
+    "lane status": route(0, project, "lane"),
+    "lane waiters": route(0, project, "lane"),
+    "lane waiter cancel": route(0, `${project} lane ${worker} reason`),
+    "lane workspace set": route(0, `${project} lane path`, "branch"),
+    "lane workspace check": route(0, `${project} lane path`),
+    "lane lock acquire": route(0, `${project} lane ${worker} reason`, "path ttl"),
+    "lane lock heartbeat": route(0, `${project} lane ${worker}`, "path lease-token ttl"),
+    "lane lock release": route(0, `${project} lane ${worker} reason`, "path lease-token"),
+    "lane lock status": route(0, `${project} lane`),
+    "lane lock wait": route(0, `${project} lane ${worker}`, "path timeout poll-interval"),
+    "lane lock wait-acquire": route(0, `${project} lane ${worker} reason`, "path timeout poll-interval ttl"),
+    "merge-queue status": route(0, "", scoped),
+    "merge-queue next": route(0, worker, `${scoped} path`),
+    "merge-queue claim": route(1, worker, `${scoped} path`),
+    "merge-queue wait-next": route(0, worker, `${scoped} path timeout poll-interval acquire-lock`),
+    "merge-queue complete": route(1, `${worker} summary`, `${scoped} path`),
+    "merge-queue fail": route(1, `${worker} reason requeue`, `${scoped} path`),
+    "merge-queue note": route(1, `${worker} summary`, scoped),
+    "merge-queue cancel": route(1, "reason", `${scoped} worker-id path`, "force"),
+    "merge serve": route(0, "agent-profile", "poll-seconds max-parallel-projects", "once"),
+    "merge server status": route(0),
+    "merge server stop": route(1),
+    "merge apply": route(1, `${project} work`, lifecycle),
+    "merge repair": route(1, project, lifecycle),
+    "merge request status": route(1, project),
+    "merge request route": route(1, `${project} mode reason`, "", "", "", { mode: ["same_session", "server"] }),
+    "merge status": route(0, project, "path"),
+    "merge bundle status": route(0, project, "path"),
+    "merge bundle claim": route(0, `${project} ${worker}`, "path"),
+    "merge bundle complete": route(0, `${project} ${worker} summary`, "path"),
+    "merge bundle fail": route(0, `${project} ${worker} reason requeue`, "path"),
+    "merge one-shot": route(0, `${project} ${worker}`, "path"),
+    "merge-worker status": route(0, project),
+    "merge-worker start": route(0, `${project} ${worker}`, "path branch"),
+    "merge-worker stop": route(0, `${project} reason`, worker),
+    "engine install": route(0, "", "", "force"),
+    "engine list": route(0),
+    "engine info": route(0, "", "package version"),
+    "engine resolve": route(0, "", "root project-root"),
+    "engine doctor": route(0, "", "root project-root"),
+    "engine bind-run": route(1, `${project} engine-version reason`, "package integrity-checksum"),
+    "canon register": route(0, "root"),
+    "canon status": route(0, "", "root"),
+    "canon resolve": route(0, "", "root"),
+    "migration impact": route(0, project, "target-version mode"),
+    "migration readiness": route(0, `${project} workspace-root request-id`),
+    "migration plan": route(0, project, "source-version target-version run backup-path backup-created-at"),
+    "migration report": route(0, project, "source-version target-version run backup-path backup-created-at"),
+    "migration verify": route(0, "file"),
+    "migration apply": route(0, project, "source-version target-version run backup-path backup-created-at file"),
+    "storage migrate-writer": route(0, "database backup", "", "offline"),
+    "cleanup scan": route(0, project),
+    "cleanup apply": route(0, `${project} plan-file reason`, "", "force"),
+    "worktree plan": route(0, "protocol-id", scoped),
+    "worktree create": route(0, "protocol-id branch base path", scoped),
+    "worktree status": route(0, "protocol-id", scoped),
+    "worktree bootstrap": route(0, "protocol-id", scoped),
+    "worktree close": route(0, "protocol-id mode", scoped, "", "", { mode: ["keep", "remove"] }),
+    "codex home plan": route(0, project, "profile source-home target-home"),
+    "codex home init": route(0, project, "profile source-home target-home"),
+    "codex home status": route(0, project, "profile"),
+    "codex home print-env": route(0, project, "profile"),
+    "codex home remove": route(0, `${project} mode`, "profile"),
+    "codex hooks print": route(0, project, "target profile"),
+    "codex hooks status": route(0, project, "target profile"),
+    "codex hooks install": route(0, project, "target profile", "yes"),
+    "codex hooks remove": route(0, project, "target profile", "yes"),
+    "codex hook handle": route(0, "event", scoped),
+    "zcode hook handle": route(0, project),
+    "zcode invocation prepare": route(0),
+    "zcode event handle": route(0, project),
+    "zcode usage ingest": route(0, project),
+    "grok event handle": route(0, project),
+    "grok usage ingest": route(0, project),
+    "opencode event handle": route(0, project),
+    "opencode usage ingest": route(0, project),
+    "droid event handle": route(0, project),
+    "droid usage ingest": route(0, project),
+    "agy event handle": route(0, project),
+    "agy usage ingest": route(0, project),
+    "stat usage": route(0, `${project} run`, "group-by session stage"),
+    "stat run sessions ls": route(0, `${project} run`),
+    "id next": route(0, `${project} type slug`, "", "", "", { type: ["protocol", "prt", "run", "work", "wrk"] }),
+    "integration cmux status": route(0, project),
+    "dashboard data": route(0, "", "project project-root protocol", "global"),
+    "dashboard render": route(0, "", "project project-root protocol output format"),
+    "dashboard render-global": route(0, "", "output format"),
+    "dashboard open": route(0, "", "project project-root protocol viewer format"),
+    "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 compose register": route(0, "project-root run request-key result-file"),
+    "memory upgrade publish": route(0, "project-root run"),
+    "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 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"));
+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, 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];
+    if (contract.retired)
+        reject(contract.retired);
+    const prefixLength = key.split(" ").length;
+    const positionCount = parsed.positional.length - prefixLength;
+    if (positionCount < contract.positions[0] || positionCount > contract.positions[1])
+        reject(`${key} expects ${contract.positions[0] === contract.positions[1] ? contract.positions[0] : `${contract.positions[0]}..${contract.positions[1]}`} positional argument(s)`);
+    for (const [name, values] of parsed.options) {
+        if (key.startsWith("merge-queue ") && name === "session-id")
+            reject("--session-id is no longer accepted on merge-queue commands; use --worker-id", name);
+        const upgrade = ["compatibility-mode", "mb-upgrade-mode"].includes(name);
+        if (upgrade && !isUpgradeAllowlisted(args))
+            reject(`${key} does not support explicit upgrade mode`, name);
+        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, "duplicate_option");
+        for (const value of values) {
+            if (contract.switches.includes(name) || name === "mb-upgrade-mode") {
+                if (value !== flag)
+                    reject(`--${name} is a switch and does not take a value`, name);
+                continue;
+            }
+            if (value === flag || !value.trim())
+                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, "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, "invalid_choice");
+            if (booleans.has(name) && !["true", "false"].includes(value))
+                reject(`--${name} must be true or false`, name, "invalid_choice");
+            const number = Number(value);
+            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
+                || 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, "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"],
+        ["stage-report", "dashboard"], ["task-file", "plan-item"], ["project", "project-root"],
+        ["intake-file", "intake-stdin", "context-file"], ["question-file", "question-stdin"], ["answer-file", "answer-stdin"],
+        ["summary-file", "summary-stdin"], ["task-file", "task-stdin"], ["reason", "reason-file"]
+    ]) {
+        const present = aliases.filter(name => parsed.options.has(name));
+        if (present.length > 1)
+            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", "init"].includes(family);
+    return { key, family, command: singleWord ? undefined : parsed.positional[1], parsed: { options: parsed.options, positional: parsed.positional.slice(singleWord ? 1 : 2) } };
+}