@deksden-com/dd-flow-cli 0.9.0-beta.13 → 0.9.0-beta.134

package/README.md

@@ -1,9 +1,78 @@
 # dd-flow-cli
 
+See [dd-zcode integration](src/harness-runtime/DD-ZCODE.md) for native transport,
+adapter ownership and the versioned bridge contract.
+
+## Native daemon shutdown
+
+`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>
+--project-root <absolute-project> --command '<project command>' --ports api
+--ready-port api --ready-path /health --json --progress-jsonl` runs a foreground
+supervisor. The command receives `DD_FLOW_PORT_API`; use it instead of a fixed
+port. Additional comma-separated names receive equivalent environment variables.
+The ready event points to a receipt and logs under the RUN's `runtime/` folder.
+Keep the tool invocation alive, run the scenario using the allocated ports,
+then execute the exact `stop_command` in that receipt and await the supervisor.
+Readiness is not a scenario pass. Keep semantic/scenario evidence separately.
+Never use a broad `pkill`/`killall`. A failed owned stop retains resources.
+
 `dd-flow-cli` is the mechanical control layer for `dd-flow` workflows.
 
 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:
@@ -402,10 +471,41 @@ remain invalid and receive a standalone retry.
 Local verification for this repository:
 
 ```bash
-pnpm test
 pnpm typecheck
 pnpm lint
 pnpm build
+pnpm test
 ```
 
+Build once before testing: release contracts and native fixtures verify the
+copied `dist` bytes. `pnpm test` remains release → integration → runtime-sensitive.
+For development use `pnpm test:fast`, `pnpm test:core` or `pnpm test:flow` plus
+the affected native contracts; these subsets are not full acceptance.
+New files default to serial core execution. A forced serial fallback is
+`pnpm test:integration --no-file-parallelism --maxWorkers=1`.
+The [test-suite verification runbook](https://github.com/deksden-com/dd-eval/blob/docs/066-test-suite-optimization/runbooks/flow-test-suite-verification.md)
+owns group qualification, complete reports and cross-repository commands.
+
 Manual smoke checks should use a temporary `DD_FLOW_HOME` when they do not intentionally inspect the operator's real local state.
+
+### 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.

package/dist/build-info.json

@@ -1,15 +1,15 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.13",
-  "cli_commit": "020ada108a59291f4462f7d52d3ea64bccd77b56",
-  "built_at": "2026-09-05T08:17:23.882Z",
+  "cli_version": "0.9.0-beta.134",
+  "cli_commit": "b243f4dac38629b7f0398b3e0b1613904f4aebff",
+  "built_at": "2026-10-13T11:24:52.803Z",
   "built_with_canon": {
-    "version": null,
-    "commit": null,
-    "flow_contract": null,
-    "repo_root": null,
-    "memorybank_root": null,
-    "flow_root": null,
-    "layout": null
+    "version": "4.1.2",
+    "commit": "2ba0b9ceedf8e4544ad9566c240ef37ea5e8d099",
+    "flow_contract": "dd-flow-canonical-2026-08",
+    "repo_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-memorybank-081-canon",
+    "memorybank_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-memorybank-081-canon/.memory-bank",
+    "flow_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-memorybank-081-canon/.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);
+    if (value !== undefined && !value.trim())
+        throw new AppError("usage", `--${key} requires a non-empty value`, 2);
+    return value;
+}
+export function requiredOption(parsed, key) {
+    const value = optionalOption(parsed, key);
+    if (!value) {
+        throw new AppError("usage", `Missing required option: --${key}`, 2);
+    }
+    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);
+    }
+    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);
+    }
+    return value;
+}

package/dist/cli/command-inputs.js

@@ -0,0 +1,306 @@
+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";
+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";
+/** 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"));
+physicalPathOptions.add("operational-decision-file");
+export const commandInputs = {
+    "version": route(0),
+    "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": route(1, "to", `${scoped} payload-file json-file reason`, "force"),
+    "transition": route(1, "to", `${scoped} payload-file json-file reason`, "force"),
+    "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), 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 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`),
+    "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"),
+    "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 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")
+};
+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 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) => { throw new AppError("usage", message, 2, { phase: "prepare", effect: "no_effect", recoverable: true, ...(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);
+        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);
+            if (name === "compatibility-mode" && value !== "mb-upgrade")
+                reject("--compatibility-mode must be mb-upgrade", name);
+            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);
+            if (booleans.has(name) && !["true", "false"].includes(value))
+                reject(`--${name} must be true or false`, name);
+            const number = Number(value);
+            if (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);
+        }
+    }
+    for (const name of contract.required)
+        if (!parsed.options.has(name))
+            reject(`Missing required option: --${name}`, name);
+    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(", ")}`);
+    }
+    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);
+    return { key, family, command: singleWord ? undefined : parsed.positional[1], parsed: { options: parsed.options, positional: parsed.positional.slice(singleWord ? 1 : 2) } };
+}