chore: codebase cleanup pass (dedup, types, dead code, cycles) (#420)

* refactor: remove dead code and unused exports

- Delete interaction-get.ts, interaction-is.ts, interaction-selector.ts (superseded by selector-runtime dispatchers)
- Remove handleWaitCommand and its private helpers from snapshot-wait.ts (replaced by dispatchWaitViaRuntime)
- Remove unused distanceFromSafeViewportBand/isRectWithinSafeViewportBand from rect-visibility
- Trim Linux platform barrel to only the re-export still in use (snapshotLinux)

* refactor: consolidate duplicated helpers

- Move sleep() to utils/timeouts.ts; remove 6 duplicate implementations
- Use existing isApplePlatform() helper for ios||macos checks (5 sites)
- Export trimRuntimeValue from runtime-hints; drop duplicate trimRuntimeString
- Merge normalizeTextSurfaceType/normalizeType into single text-surface helper
- Remove pointless isScrollableContainerType wrapper

* refactor: consolidate accidentally-duplicated type definitions

- SnapshotDiffLine/Summary: single definition in utils/snapshot-diff, re-exported from capture-snapshot
- FindLocator: single definition in utils/finders, re-exported from client-types
- JsonRpc envelope in http-server now uses JsonRpcRequestEnvelope/JsonRpcId from contracts
- Inline 'primary'|'secondary'|'middle' literals replaced with ClickButton (internal sites only)

* refactor: strengthen weak types and fix DEVICE_IN_USE downgrade bug

- Add toAppErrorCode() validator and DEVICE_IN_USE to AppErrorCode union
- Replace 'as any' casts on wire error codes with the validator (daemon-error, daemon-client, request-router, http-server)
- Type Metro worker payload as MetroTunnelResponseMessage
- Type xctestrun plist parsing with explicit partial schema
- Narrow 'details.stderr' via typeof checks on Android error paths
- Type runner-session parseRunnerResponse with RunnerResponsePayload

Bug fix: handler emitted 'DEVICE_IN_USE' but router cast silently downgraded to
'COMMAND_FAILED' because the code was missing from AppErrorCode. Clients can now
react to same-device contention.

* refactor: collapse redundant 'ignore' comments in empty catch blocks

- Replace 16 instances of 3-line catch { // ignore } with 1-line catch {}
- Remove one self-describing 'Re-export public API' comment

Specific 'ignore shutdown races' / 'ignore malformed pid files' style comments
that name concrete failure modes are kept.

* refactor: eliminate circular dependencies by extracting shared types to leaves

Resolves all 44 cycles reported by madge. Pattern throughout: extract shared
type into a leaf module; both producer and consumer import from the leaf;
original module re-exports for API stability.

New leaf type modules:
- src/runtime-contract.ts (AgentDeviceRuntime, CommandContext, ...)
- src/metro-types.ts (MetroRuntimeHints, MetroBridgeResult, ...)
- src/commands/runtime-types.ts (CommandResult, RuntimeCommand, ...)
- src/commands/diagnostics-types.ts
- src/cli/commands/router-types.ts (ClientCommandParams, ...)
- src/core/interactor-types.ts (Interactor, BackMode, ...)
- src/platforms/ios/runner-session-types.ts (RunnerSession)
- src/utils/screenshot-diff-region-types.ts (MutableDiffRegion)
- src/daemon/handlers/record-trace-types.ts

madge --circular now reports 0 cycles (was 44). No runtime behavior changes.

* fix: preserve wire error codes verbatim (addresses codex review)

The initial weak-types pass validated wire error codes against a closed
union, silently downgrading any unknown code to COMMAND_FAILED. This
dropped signals like AMBIGUOUS_MATCH that handlers emit and clients are
documented to handle (skills/agent-device/references/exploration.md).

- Widen AppErrorCode to 'KnownAppErrorCode | (string & {})' so autocomplete
  of known codes is preserved while any wire code flows through
- toAppErrorCode now preserves any non-empty code; fallback only when
  undefined or empty
- Add AMBIGUOUS_MATCH to KnownAppErrorCode (documented public code)
- Add test coverage for preservation and fallback behavior

* refactor: address review follow-ups

- Add DEVICE_IN_USE to the batch error taxonomy in exploration.md (now
  observable by clients after earlier fix, needs agent-facing guidance)
- Delete one-line src/platforms/linux/index.ts barrel; both consumers
  (core/dispatch, daemon/handlers/snapshot-capture) now import from
  platforms/linux/snapshot directly
- Replace inline { tenantId; runId; leaseId } shapes with MetroBridgeScope
  alias at client-types, metro, and cli/commands/connection-runtime
- Consolidate remaining inline setTimeout wrappers onto utils/timeouts.ts#sleep
  (12 files, ~18 sites). Left test files and the runtime-clock aware helper
  in commands/selector-read-utils alone. Also removes the local sleepMs
  helper from daemon-client.ts.

* refactor: address low-priority review follow-ups

- daemon-client RPC error path: stringify any non-null data.code instead
  of only forwarding strings. Preserves numeric codes from hypothetical
  future proxies/servers; for first-party daemon today this is a no-op
  since handlers already emit strings.
- errors.ts: expand AppErrorCode comment to call out the exhaustiveness
  tradeoff of the '(string & {})' widening for SDK consumers.

Author: thymikee

skills/agent-device/references/exploration.md

@@ -338,6 +338,7 @@ Common batch error categories:
 - `SESSION_NOT_FOUND`: open or select the correct session, then retry.
 - `UNSUPPORTED_OPERATION`: switch to a supported command or surface.
 - `AMBIGUOUS_MATCH`: refine the selector or locator, then retry the failed step.
+- `DEVICE_IN_USE`: the device is held by another session — close or reuse the existing session before retrying.
 - `COMMAND_FAILED`: add sync guards and retry from the failing step.
 
 ## Stop conditions

src/cli.ts

@@ -336,9 +336,7 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
                   process.stderr.write(`\n[daemon log]\n${tail}\n`);
                 }
               }
-            } catch {
-              // ignore
-            }
+            } catch {}
           }
         }
         if (logTailStopper) logTailStopper();

src/cli/commands/apps.ts

@@ -1,5 +1,5 @@
 import { buildSelectionOptions, writeCommandOutput } from './shared.ts';
-import type { ClientCommandHandler } from './router.ts';
+import type { ClientCommandHandler } from './router-types.ts';
 
 export const appsCommand: ClientCommandHandler = async ({ flags, client }) => {
   const apps = await client.apps.list({

src/cli/commands/client-command.ts

@@ -13,7 +13,7 @@ import { AppError } from '../../utils/errors.ts';
 import { parseWaitArgs } from '../../daemon/handlers/snapshot.ts';
 import { parseDeviceRotation } from '../../core/device-rotation.ts';
 import { buildSelectionOptions, writeCommandMessage, writeCommandOutput } from './shared.ts';
-import type { ClientCommandHandlerMap } from './router.ts';
+import type { ClientCommandHandlerMap } from './router-types.ts';
 
 export const clientCommandMethodHandlers = {
   [CLIENT_COMMANDS.wait]: async ({ positionals, flags, client }) => {

src/cli/commands/connection-runtime.ts

@@ -1,6 +1,7 @@
 import { resolveDaemonPaths } from '../../daemon/config.ts';
 import { stopMetroTunnel } from '../../metro.ts';
 import { resolveRemoteConfigProfile } from '../../remote-config.ts';
+import type { MetroBridgeScope } from '../../client-metro-companion-contract.ts';
 import {
   buildRemoteConnectionDaemonState,
   hashRemoteConfigFile,
@@ -173,11 +174,7 @@ export async function prepareConnectedMetro(
   client: AgentDeviceClient,
   remoteConfigPath: string,
   session: string,
-  bridgeScope: {
-    tenantId: string;
-    runId: string;
-    leaseId: string;
-  },
+  bridgeScope: MetroBridgeScope,
 ): Promise<{
   runtime?: SessionRuntimeHints;
   cleanup?: NonNullable<RemoteConnectionState['metro']>;

src/cli/commands/connection.ts

@@ -21,7 +21,7 @@ import {
 import { writeCommandOutput } from './shared.ts';
 import type { LeaseBackend } from '../../contracts.ts';
 import type { CliFlags } from '../../utils/command-schema.ts';
-import type { ClientCommandHandler } from './router.ts';
+import type { ClientCommandHandler } from './router-types.ts';
 
 export const connectCommand: ClientCommandHandler = async ({ flags, client }) => {
   if (!flags.remoteConfig) {

src/cli/commands/devices.ts

@@ -1,7 +1,7 @@
 import { serializeDevice } from '../../client-shared.ts';
 import type { AgentDeviceDevice } from '../../client.ts';
 import { buildSelectionOptions, writeCommandOutput } from './shared.ts';
-import type { ClientCommandHandler } from './router.ts';
+import type { ClientCommandHandler } from './router-types.ts';
 
 export const devicesCommand: ClientCommandHandler = async ({ flags, client }) => {
   const devices = await client.devices.list(buildSelectionOptions(flags));

src/cli/commands/ensure-simulator.ts

@@ -1,7 +1,7 @@
 import { AppError } from '../../utils/errors.ts';
 import { serializeEnsureSimulatorResult } from '../../client-shared.ts';
 import { writeCommandOutput } from './shared.ts';
-import type { ClientCommandHandler } from './router.ts';
+import type { ClientCommandHandler } from './router-types.ts';
 
 export const ensureSimulatorCommand: ClientCommandHandler = async ({ flags, client }) => {
   if (!flags.device) {

src/cli/commands/generic.ts

@@ -14,7 +14,7 @@ import { AppError } from '../../utils/errors.ts';
 import type { CliFlags } from '../../utils/command-schema.ts';
 import { buildSelectionOptions } from './shared.ts';
 import { writeCommandCliOutput } from './output.ts';
-import type { ClientCommandHandler, ClientCommandHandlerMap } from './router.ts';
+import type { ClientCommandHandler, ClientCommandHandlerMap } from './router-types.ts';
 
 type GenericClientCommandRunner = (params: {
   client: AgentDeviceClient;

src/cli/commands/install.ts

@@ -3,7 +3,7 @@ import { serializeDeployResult, serializeInstallFromSourceResult } from '../../c
 import type { CliFlags } from '../../utils/command-schema.ts';
 import type { AgentDeviceClient, AppDeployResult } from '../../client.ts';
 import { buildSelectionOptions, writeCommandMessage } from './shared.ts';
-import type { ClientCommandHandler } from './router.ts';
+import type { ClientCommandHandler } from './router-types.ts';
 
 export const installCommand: ClientCommandHandler = async ({ positionals, flags, client }) => {
   const result = await runDeployCommand('install', positionals, flags, client);