feat: registry-driven exhaustive command dispatch — Phase 1 step 5

[thymikee]

Phase 1 step 5 of the command-descriptor migration (ADR 0008). Stacked on #909.

What

Part A — enabler. In src/core/command-descriptor/registry.ts, the commandDescriptors table is now as const (RAW_COMMAND_DESCRIPTORS … as const satisfies readonly Omit<CommandDescriptor, 'mcpExposed'>[], with the as const flowing through the .map so each entry keeps its literal name). Exports the literal command-name union:

export type Command = (typeof commandDescriptors)[number]['name'];

The closure/function fields (supports, unsupportedHint, allowSessionlessDefaultDevice, …) are fine under as const; tsc stays clean. defineCommandDescriptor is no longer needed in the map (it widened name to string) and is dropped from the registry's usage.

Part B — exhaustive dispatch map. Replaces the dispatchKnownCommand switch (command) { case …: return handle*Command(…); default: throw … } with a const DISPATCH_HANDLERS: Record<DispatchCommand, DispatchHandler> lookup. Every command routes to the identical handler with the identical arguments and return value the switch used; the inline cases (close/back/home/rotate/app-switcher) are preserved verbatim as inline arrows.

How exhaustiveness is enforced

The Record<DispatchCommand, DispatchHandler> type forces every dispatch command to have a handler — a missing entry is now a COMPILE error (verified: deleting the back handler yields TS2741: Property 'back' is missing … but required in type 'Record<DispatchCommand, DispatchHandler>'). This replaces the runtime default: throw as the coverage safety net. A runtime guard remains: Object.hasOwn(DISPATCH_HANDLERS, command) gates the lookup and throws the same INVALID_ARGS Unknown command: ${command} error for unknown commands — and prevents inherited keys (e.g. toString) from resolving to a prototype method.

DispatchCommand is hand-authored to match the switch cases verbatim. It is deliberately NOT derived from the registry's generic daemon route: that set is both narrower (no open/type/read/etc.) and includes gesture (which dispatch never handled), and swipe-preset / read are not registry command names at all. The mismatch is noted in a doc comment on the type.

Behaviorless

Same routing, same handler args, same results, same error for unknown commands. No runtime behavior changed.

Verification

• tsc -p tsconfig.json --noEmit → exit 0; missing-handler probe → compile error (TS2741); Command literal-union probe → invalid name rejected.
• oxfmt --write + oxlint --deny-warnings on changed files → clean.
• vitest run dispatch core/dispatch dispatch-interactions daemon core/command-descriptor → 109 files, 992 tests passed.
• Layering Guard git grep → empty.

iOS e2e smoke pending reviewer.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.4 MB	1.4 MB	+770 B
JS gzip	445.4 kB	445.5 kB	+115 B
npm tarball	584.6 kB	584.7 kB	+116 B
npm unpacked	2.0 MB	2.0 MB	+770 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	24.3 ms	24.2 ms	-0.1 ms
CLI --help	43.1 ms	43.1 ms	+0.1 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/9722.js	+770 B	+115 B

[thymikee]

iOS smoke (booted iPhone 17 Pro, source build of this tip): screenshot — which routes through the new DISPATCH_HANDLERS map — succeeded end-to-end (378 KB PNG), confirming registry-driven dispatch routes correctly. snapshot/scroll hit a runner-lease conflict from a leftover smoke daemon (iOS runner … already owned by another agent-device daemon — environment, not a routing regression; cleaned up afterward). Combined with the full dispatch+interaction+daemon suite (992 tests), compile-time exhaustiveness (deleting a handler → TS2741), and the Object.hasOwn guard preserving the identical unknown-command error, the flip is verified behaviorless.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-27 18:59 UTC