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

Author: thymikee

src/utils/__tests__/errors.test.ts

@@ -1,6 +1,6 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
-import { AppError, asAppError, normalizeError } from '../errors.ts';
+import { AppError, asAppError, normalizeError, toAppErrorCode } from '../errors.ts';
 
 test('normalizeError adds default hint and strips diagnostic metadata from details', () => {
   const err = new AppError('COMMAND_FAILED', 'runner failed', {
@@ -91,3 +91,15 @@ test('normalizeError provides app discovery guidance for app-not-installed error
     /Run apps to discover the exact installed package or bundle id/i,
   );
 });
+
+test('toAppErrorCode preserves handler-emitted codes verbatim (including AMBIGUOUS_MATCH)', () => {
+  assert.equal(toAppErrorCode('AMBIGUOUS_MATCH'), 'AMBIGUOUS_MATCH');
+  assert.equal(toAppErrorCode('SOME_FUTURE_CODE'), 'SOME_FUTURE_CODE');
+  assert.equal(toAppErrorCode('DEVICE_IN_USE'), 'DEVICE_IN_USE');
+});
+
+test('toAppErrorCode falls back when code is missing or empty', () => {
+  assert.equal(toAppErrorCode(undefined), 'COMMAND_FAILED');
+  assert.equal(toAppErrorCode(''), 'COMMAND_FAILED');
+  assert.equal(toAppErrorCode(undefined, 'UNAUTHORIZED'), 'UNAUTHORIZED');
+});

src/utils/errors.ts

@@ -1,6 +1,6 @@
 import { redactDiagnosticData } from './redaction.ts';
 
-export type AppErrorCode =
+export type KnownAppErrorCode =
   | 'INVALID_ARGS'
   | 'DEVICE_NOT_FOUND'
   | 'DEVICE_IN_USE'
@@ -12,35 +12,18 @@ export type AppErrorCode =
   | 'COMMAND_FAILED'
   | 'SESSION_NOT_FOUND'
   | 'UNAUTHORIZED'
+  | 'AMBIGUOUS_MATCH'
   | 'UNKNOWN';
 
-const APP_ERROR_CODES: readonly AppErrorCode[] = [
-  'INVALID_ARGS',
-  'DEVICE_NOT_FOUND',
-  'DEVICE_IN_USE',
-  'TOOL_MISSING',
-  'APP_NOT_INSTALLED',
-  'UNSUPPORTED_PLATFORM',
-  'UNSUPPORTED_OPERATION',
-  'NOT_IMPLEMENTED',
-  'COMMAND_FAILED',
-  'SESSION_NOT_FOUND',
-  'UNAUTHORIZED',
-  'UNKNOWN',
-];
-
-/**
- * Narrow a wire-level error code string into a known AppErrorCode.
- * Unrecognised codes are surfaced verbatim by preserving them on details,
- * while the typed channel falls back to the provided default.
- */
+// Accepts any string so wire codes from the daemon are preserved verbatim; the
+// `(string & {})` form keeps IDE autocomplete of the known codes.
+export type AppErrorCode = KnownAppErrorCode | (string & {});
+
 export function toAppErrorCode(
   code: string | undefined,
   fallback: AppErrorCode = 'COMMAND_FAILED',
 ): AppErrorCode {
-  if (typeof code === 'string' && (APP_ERROR_CODES as readonly string[]).includes(code)) {
-    return code as AppErrorCode;
-  }
+  if (typeof code === 'string' && code.length > 0) return code;
   return fallback;
 }