test: guard daemon routing metadata drift

Author: thymikee

AGENTS.md

@@ -76,6 +76,7 @@ Single-context repo. Read `CONTEXT.md` for domain language and testing/architect
   - CLI/client/runtime output projection: `src/commands/cli-output.ts`, `src/commands/client-output.ts`, `src/commands/runtime-output.ts`
 - Do not reintroduce CLI-shaped command adapters or schemas as a second source of truth. CLI, Node.js, and MCP should project from command contracts.
 - Keep `src/daemon/request-router.ts` as request orchestration: auth, diagnostics scope, request admission, locking, handler chain, and fallback dispatch.
+- New daemon handler-family commands must update the relevant `DAEMON_COMMAND_GROUPS.*Handler` entry and the handler module's exported `*_COMMAND_HANDLERS` coverage table; `src/daemon/__tests__/request-handler-catalog.test.ts` guards drift and overlap.
 - Put request policies in focused request modules:
   - tenant/lease/selector/lock admission: `src/daemon/request-admission.ts`
   - artifact/error finalization: `src/daemon/request-finalization.ts`

src/commands/__tests__/command-surface-metadata.test.ts

@@ -0,0 +1,21 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { listMcpExposedCommandNames } from '../../command-catalog.ts';
+import { listCommandMetadataNames, listMcpCommandMetadata } from '../command-metadata.ts';
+import { listExecutableCommandNames } from '../command-surface.ts';
+
+test('MCP exposed command names have metadata and executable command definitions', () => {
+  const mcpExposedNames = listMcpExposedCommandNames().sort();
+  const mcpMetadataNames = listMcpCommandMetadata()
+    .map((definition) => definition.name)
+    .sort();
+  const metadataNames = new Set<string>(listCommandMetadataNames());
+  const executableNames = new Set<string>(listExecutableCommandNames());
+
+  assert.deepEqual(mcpMetadataNames, mcpExposedNames);
+
+  for (const name of mcpExposedNames) {
+    assert.ok(metadataNames.has(name), `${name} must have command metadata`);
+    assert.ok(executableNames.has(name), `${name} must have an executable command definition`);
+  }
+});

src/commands/command-metadata.ts

@@ -29,6 +29,10 @@ export function listMcpCommandMetadata(): AnyCommandMetadata[] {
   });
 }
 
+export function listCommandMetadataNames(): CommandName[] {
+  return [...commandMetadataMap.keys()].sort();
+}
+
 export function isCommandName(name: string): name is CommandName {
   return commandMetadataMap.has(name as CommandName);
 }

src/commands/command-surface.ts

@@ -35,6 +35,10 @@ export async function runCommand(
   return await getCommandDefinition(name).invoke(client, input);
 }
 
+export function listExecutableCommandNames(): CommandName[] {
+  return [...commandMap.keys()].sort();
+}
+
 function getCommandDefinition(name: CommandName): AnyExecutableCommand {
   return commandMap.get(name)!;
 }

src/daemon/__tests__/request-handler-catalog.test.ts

@@ -0,0 +1,100 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { DAEMON_COMMAND_GROUPS, INTERNAL_COMMANDS } from '../../command-catalog.ts';
+import { FIND_COMMAND_HANDLERS } from '../handlers/find.ts';
+import { INTERACTION_COMMAND_HANDLERS } from '../handlers/interaction.ts';
+import { handleLeaseCommands, LEASE_COMMAND_HANDLERS } from '../handlers/lease.ts';
+import { REACT_NATIVE_COMMAND_HANDLERS } from '../handlers/react-native.ts';
+import { RECORD_TRACE_COMMAND_HANDLERS } from '../handlers/record-trace.ts';
+import { SESSION_COMMAND_HANDLERS } from '../handlers/session.ts';
+import { SNAPSHOT_COMMAND_HANDLERS } from '../handlers/snapshot.ts';
+import { LeaseRegistry } from '../lease-registry.ts';
+
+const handlerFamilies = [
+  {
+    name: 'leaseHandler',
+    commands: DAEMON_COMMAND_GROUPS.leaseHandler,
+    handlers: LEASE_COMMAND_HANDLERS,
+  },
+  {
+    name: 'sessionHandler',
+    commands: DAEMON_COMMAND_GROUPS.sessionHandler,
+    handlers: SESSION_COMMAND_HANDLERS,
+  },
+  {
+    name: 'snapshot',
+    commands: DAEMON_COMMAND_GROUPS.snapshot,
+    handlers: SNAPSHOT_COMMAND_HANDLERS,
+  },
+  {
+    name: 'reactNativeHandler',
+    commands: DAEMON_COMMAND_GROUPS.reactNativeHandler,
+    handlers: REACT_NATIVE_COMMAND_HANDLERS,
+  },
+  {
+    name: 'recordTraceHandler',
+    commands: DAEMON_COMMAND_GROUPS.recordTraceHandler,
+    handlers: RECORD_TRACE_COMMAND_HANDLERS,
+  },
+  {
+    name: 'findHandler',
+    commands: DAEMON_COMMAND_GROUPS.findHandler,
+    handlers: FIND_COMMAND_HANDLERS,
+  },
+  {
+    name: 'interactionHandler',
+    commands: DAEMON_COMMAND_GROUPS.interactionHandler,
+    handlers: INTERACTION_COMMAND_HANDLERS,
+  },
+] as const;
+
+test('daemon handler routing groups match handler coverage', () => {
+  for (const { name, commands, handlers } of handlerFamilies) {
+    assert.deepEqual(
+      Object.keys(handlers).sort(),
+      [...commands].sort(),
+      `${name} catalog must match its handler module`,
+    );
+  }
+});
+
+test('lease handler coverage table points at executable commands', async () => {
+  const leaseRegistry = new LeaseRegistry();
+  const allocated = leaseRegistry.allocateLease({ tenantId: 'tenant-a', runId: 'run-a' });
+
+  for (const command of Object.keys(LEASE_COMMAND_HANDLERS)) {
+    const response = await handleLeaseCommands({
+      req: {
+        command,
+        token: 'test-token',
+        session: 'catalog-test',
+        flags: {
+          tenant: 'tenant-a',
+          runId: 'run-a',
+          ...(command === INTERNAL_COMMANDS.leaseAllocate
+            ? {}
+            : { leaseId: allocated.leaseId }),
+        },
+        positionals: [],
+      },
+      leaseRegistry,
+    });
+
+    assert.notEqual(response, null, `${command} should be handled by lease handler`);
+  }
+});
+
+test('daemon handler routing groups are disjoint', () => {
+  const ownerByCommand = new Map<string, string>();
+  for (const { name, commands } of handlerFamilies) {
+    for (const command of commands) {
+      const previousOwner = ownerByCommand.get(command);
+      assert.equal(
+        previousOwner,
+        undefined,
+        `${command} is routed by both ${previousOwner} and ${name}`,
+      );
+      ownerByCommand.set(command, name);
+    }
+  }
+});

src/daemon/handlers/find.ts

@@ -17,9 +17,14 @@ import { setSessionSnapshot } from '../session-snapshot.ts';
 import { errorResponse } from './response.ts';
 import { getActiveAndroidSnapshotFreshness } from '../android-snapshot-freshness.ts';
 import { dispatchFindReadOnlyViaRuntime } from '../selector-runtime.ts';
+import { PUBLIC_COMMANDS } from '../../command-catalog.ts';
 
 export { parseFindArgs } from '../../utils/finders.ts';
 
+export const FIND_COMMAND_HANDLERS = {
+  [PUBLIC_COMMANDS.find]: true,
+} as const satisfies Record<string, true>;
+
 type FindContext = {
   req: DaemonRequest;
   sessionName: string;

src/daemon/handlers/interaction.ts

@@ -16,6 +16,16 @@ import {
   recoverAndroidBlockingSystemDialog,
 } from '../android-system-dialog.ts';
 
+export const INTERACTION_COMMAND_HANDLERS = {
+  [PUBLIC_COMMANDS.click]: true,
+  [PUBLIC_COMMANDS.fill]: true,
+  [PUBLIC_COMMANDS.get]: true,
+  [PUBLIC_COMMANDS.is]: true,
+  [PUBLIC_COMMANDS.longPress]: true,
+  [PUBLIC_COMMANDS.press]: true,
+  [PUBLIC_COMMANDS.type]: true,
+} as const satisfies Record<string, true>;
+
 export async function handleInteractionCommands(
   params: InteractionHandlerParams,
 ): Promise<DaemonResponse | null> {

src/daemon/handlers/lease.ts

@@ -1,12 +1,19 @@
 import type { DaemonRequest, DaemonResponse } from '../types.ts';
 import type { LeaseRegistry } from '../lease-registry.ts';
 import { resolveLeaseScope } from '../lease-context.ts';
+import { INTERNAL_COMMANDS } from '../../command-catalog.ts';
 
 type LeaseHandlerArgs = {
   req: DaemonRequest;
   leaseRegistry: LeaseRegistry;
 };
 
+export const LEASE_COMMAND_HANDLERS = {
+  [INTERNAL_COMMANDS.leaseAllocate]: true,
+  [INTERNAL_COMMANDS.leaseHeartbeat]: true,
+  [INTERNAL_COMMANDS.leaseRelease]: true,
+} as const satisfies Record<string, true>;
+
 export async function handleLeaseCommands(args: LeaseHandlerArgs): Promise<DaemonResponse | null> {
   const { req, leaseRegistry } = args;
   const leaseScope = resolveLeaseScope(req);

src/daemon/handlers/react-native.ts

@@ -15,6 +15,10 @@ import { captureSnapshotForSession } from './interaction-snapshot.ts';
 import { finalizeTouchInteraction, type InteractionHandlerParams } from './interaction-common.ts';
 import { readSnapshotNodesReferenceFrame } from './interaction-touch-reference-frame.ts';
 
+export const REACT_NATIVE_COMMAND_HANDLERS = {
+  [PUBLIC_COMMANDS.reactNative]: true,
+} as const satisfies Record<string, true>;
+
 export async function handleReactNativeCommands(
   params: InteractionHandlerParams,
 ): Promise<DaemonResponse | null> {

src/daemon/handlers/record-trace.ts

@@ -5,6 +5,12 @@ import type { DaemonRequest, DaemonResponse } from '../types.ts';
 import { SessionStore } from '../session-store.ts';
 import { handleRecordCommand } from './record-trace-recording.ts';
 import { errorResponse } from './response.ts';
+import { PUBLIC_COMMANDS } from '../../command-catalog.ts';
+
+export const RECORD_TRACE_COMMAND_HANDLERS = {
+  [PUBLIC_COMMANDS.record]: true,
+  [PUBLIC_COMMANDS.trace]: true,
+} as const satisfies Record<string, true>;
 
 export async function handleRecordTraceCommands(params: {
   req: DaemonRequest;