refactor: move errors/redaction/device into src/kernel — Phase 5 slice 3

AGENTS.md

@@ -139,7 +139,7 @@ Command-only flags (like `find --first`) that do not flow to the platform layer
 - Use `keyboard dismiss` for iOS keyboard dismissal; it may tap safe native controls such as `Done` but must not fall back to system back navigation.
 - Do not remove shared snapshot/session model behavior without full migration.
 - Command/device support must come from `src/core/capabilities.ts`.
-- Apple-family target changes must keep `src/utils/device.ts`, `src/core/capabilities.ts`, `src/core/dispatch-resolve.ts`, `src/platforms/ios/devices.ts`, and `src/platforms/ios/runner-xctestrun.ts` in sync.
+- Apple-family target changes must keep `src/kernel/device.ts`, `src/core/capabilities.ts`, `src/core/dispatch-resolve.ts`, `src/platforms/ios/devices.ts`, and `src/platforms/ios/runner-xctestrun.ts` in sync.
 - iOS simulator-set scoping is iOS-specific: do not let `iosSimulatorDeviceSet` hide the host macOS desktop target when `--platform macos` or `--target desktop` is requested.
 - If Swift runner code changes, run `pnpm build:xcuitest`.
 - Use `inferFillText` and `uniqueStrings` from `src/daemon/action-utils.ts`.
@@ -157,7 +157,7 @@ Command-only flags (like `find --first`) that do not flow to the platform layer
 - Request diagnostics belong in `sessions/<effective-session>/requests/<request-id>.ndjson` once the effective session is resolved. The top-level daemon log is for daemon lifecycle/startup and pre-session failures.
 - Session artifact paths are centralized in `src/daemon/session-store.ts`; do not hand-build session log paths in handlers.
 - Do not add ad-hoc stderr/file logging where diagnostics helpers apply.
-- Normalize user-facing failures via `src/utils/errors.ts` (`normalizeError`).
+- Normalize user-facing failures via `src/kernel/errors.ts` (`normalizeError`).
 - Failure payload contract: `code`, `message`, `hint`, `diagnosticId`, `logPath`, `details`.
 - User-facing errors should be short and actionable: say what failed, why when known, and how to recover. Put recovery steps in `hint` when the action is not obvious, for example restart/retry, use plain screenshot when AX state is unavailable, navigate with coordinates, or inspect logs.
 - If an interaction unexpectedly takes 5+ seconds, inspect the relevant daemon log before attributing it to the app. Check the session `--state-dir` `daemon.log` or the failure `logPath` for runner restart, stale session recovery, AX failure, transport retry, or command timeout evidence.

docs/adr/0009-apple-platform-consolidation.md

@@ -9,7 +9,7 @@ Accepted
 Apple support is modeled asymmetrically and is physically smeared across an `ios` directory that is really
 the shared Apple engine. `Platform` carries `ios` and `macos` as separate literals, but tvOS is not a
 platform at all — it is `platform: 'ios' + target: 'tv'`, with the OS name reconstructed late and lossily by
-`resolveApplePlatformName` (`src/utils/device.ts`). Meanwhile ~697 LOC of macOS code lives inside
+`resolveApplePlatformName` (`src/kernel/device.ts`). Meanwhile ~697 LOC of macOS code lives inside
 `src/platforms/ios/`, `src/platforms/macos/devices.ts` is a 19-line stub that the iOS discovery imports (the
 dependency arrow points backwards), and the Apple interactor in `src/core/interactors/apple.ts` reaches into
 `platforms/ios`. A four-investigator survey found that ~85% of `platforms/ios` (the runner stack,

fallow-baselines/health.json

@@ -553,7 +553,7 @@
         "count": 1
       }
     },
-    "src/utils/device.ts": {
+    "src/kernel/device.ts": {
       "complexity_moderate": {
         "count": 1
       }
@@ -723,7 +723,7 @@
     "src/utils/text-surface.ts:high impact",
     "src/utils/selector-build.ts:high impact",
     "src/core/batch.ts:complexity",
-    "src/utils/device.ts:high impact",
+    "src/kernel/device.ts:high impact",
     "src/daemon/network-log.ts:high impact",
     "src/commands/cli-grammar/selectors.ts:untested risk",
     "src/platforms/ios/xml.ts:high impact",

plans/apple-platform-consolidation.md

@@ -28,7 +28,7 @@ each OS to its own `Platform` literal. Reasons from the code:
 BEFORE — Apple support is smeared across an "iOS" folder that is really the Apple engine
 ─────────────────────────────────────────────────────────────────────────────────────────
 
-DeviceInfo (src/utils/device.ts)
+DeviceInfo (src/kernel/device.ts)
   platform: ios | macos | android | linux | web     ← macOS is its OWN literal …
   kind:     simulator | emulator | device
   target?:  mobile | tv | desktop                   ← … but tvOS = ios + target:'tv'  (asymmetric!)

src/__tests__/cli-client-commands.test.ts

@@ -14,7 +14,7 @@ import type {
   MetroReloadOptions,
 } from '../client.ts';
 import type { SettingsUpdateOptions } from '../client-types.ts';
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 import { resolveCliOptions } from '../utils/cli-options.ts';
 
 test('install-from-source forwards URL and repeated headers to client.apps.installFromSource', async () => {

src/__tests__/cli-close.test.ts

@@ -1,6 +1,6 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 import { runCliCapture, type CapturedCliRun } from './cli-capture.ts';
 
 function runCliWithDaemonStartupFailure(argv: string[]): Promise<CapturedCliRun> {

src/__tests__/client-metro.test.ts

@@ -9,7 +9,7 @@ import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import { prepareMetroRuntime, reloadMetro } from '../client-metro.ts';
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 import { isProcessAlive, waitForProcessExit } from '../utils/process-identity.ts';
 
 const TEST_TOKEN = 'agent-device-proxy-test-token';

src/__tests__/client-normalizers.test.ts

@@ -1,7 +1,7 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import { normalizeOpenDevice } from '../client-normalizers.ts';
-import { PLATFORMS } from '../utils/device.ts';
+import { PLATFORMS } from '../kernel/device.ts';
 
 test('normalizeOpenDevice accepts exactly the canonical leaf platforms', () => {
   for (const platform of PLATFORMS) {

src/__tests__/client.test.ts

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import { createAgentDeviceClient, type AgentDeviceClientConfig } from '../client.ts';
 import { runCommand } from '../commands/command-surface.ts';
 import type { DaemonRequest, DaemonResponse } from '../contracts.ts';
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 
 function createTransport(
   handler: (req: Omit<DaemonRequest, 'token'>) => Promise<DaemonResponse> | DaemonResponse,

src/__tests__/contracts-schema-public.test.ts

@@ -40,7 +40,7 @@ const node = {
 
 test('public contracts error helpers do not load diagnostics module', () => {
   const errorsSource = fs.readFileSync(
-    path.join(import.meta.dirname, '..', 'utils', 'errors.ts'),
+    path.join(import.meta.dirname, '..', 'kernel', 'errors.ts'),
     'utf8',
   );
 

src/__tests__/daemon-client-progress.test.ts

@@ -4,7 +4,7 @@ import type { Socket } from 'node:net';
 import { test } from 'vitest';
 import type { DaemonRequest, DaemonResponse } from '../daemon/types.ts';
 import { readDaemonSocketProgressResponse } from '../daemon-client-progress.ts';
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 
 type MockSocket = EventEmitter & {
   ended: boolean;

src/__tests__/provider-device-runtime.test.ts

@@ -11,7 +11,7 @@ import {
 } from '../provider-device-runtime.ts';
 import type { Interactor } from '../core/interactor-types.ts';
 import type { SimulatorLease } from '../daemon/lease-registry.ts';
-import type { DeviceInfo } from '../utils/device.ts';
+import type { DeviceInfo } from '../kernel/device.ts';
 
 afterEach(() => {
   setActiveProviderDeviceRuntimes([]);

src/__tests__/remote-connection.test.ts

@@ -24,7 +24,7 @@ import {
   PROXY_REMOTE_LEASE_TTL_MS,
 } from '../cli/commands/connection-runtime.ts';
 import { stopMetroCompanion } from '../client-metro-companion.ts';
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 import {
   hashRemoteConfigFile,
   readActiveConnectionState,

src/__tests__/test-utils/device-fixtures.ts

@@ -1,4 +1,4 @@
-import type { DeviceInfo } from '../../utils/device.ts';
+import type { DeviceInfo } from '../../kernel/device.ts';
 
 export const ANDROID_EMULATOR: DeviceInfo = {
   platform: 'android',

src/backend.ts

@@ -2,7 +2,7 @@ import type { AlertAction, AlertInfo } from './alert-contract.ts';
 import type { AppsFilter } from './contracts/app-inventory.ts';
 import type { Point, SnapshotNode, SnapshotOptions, SnapshotState } from './kernel/snapshot.ts';
 import type { NetworkIncludeMode } from './contracts.ts';
-import type { DeviceTarget, Platform, PlatformSelector } from './utils/device.ts';
+import type { DeviceTarget, Platform, PlatformSelector } from './kernel/device.ts';
 import type { BackMode } from './core/back-mode.ts';
 import type { RepeatedInput } from './commands/command-input.ts';
 import type { ClickButton } from './core/click-button.ts';

src/batch-contract.ts

@@ -1,5 +1,5 @@
 import { daemonRuntimeSchema, type SessionRuntimeHints } from './contracts.ts';
-import { AppError } from './utils/errors.ts';
+import { AppError } from './kernel/errors.ts';
 import { isRecord } from './utils/parsing.ts';
 
 export const DEFAULT_BATCH_MAX_STEPS = 100;

src/batch-policy.ts

@@ -1,6 +1,6 @@
 import { deriveStructuredBatchCommandNames } from './core/command-descriptor/derive.ts';
 import { commandDescriptors } from './core/command-descriptor/registry.ts';
-import { AppError } from './utils/errors.ts';
+import { AppError } from './kernel/errors.ts';
 
 /**
  * The exact set of command names exposed through `batch`, as a narrow union.

src/cli-test-reporters/custom.ts

@@ -1,7 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 import type { ReplayTestReporter, ReplayTestReporterFactory } from './types.ts';
 import type { ReplayTestReporterSpec } from './spec.ts';
 

src/cli-test-reporters/junit.ts

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import type { ReplaySuiteResult, ReplaySuiteTestResult } from '../daemon/types.ts';
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 import type { ReplayTestReporter, ReplayTestReporterContext } from './types.ts';
 import {
   appendOptionalLine,

src/cli-test-reporters/spec.ts

@@ -1,4 +1,4 @@
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 
 export type ReplayTestReporterSpec =
   | {

src/cli.ts

@@ -1,5 +1,5 @@
 import { parseRawArgs, usage, usageForCommand } from './utils/args.ts';
-import { asAppError, AppError, normalizeError } from './utils/errors.ts';
+import { asAppError, AppError, normalizeError } from './kernel/errors.ts';
 import { printHumanError, printJson } from './utils/output.ts';
 import { readVersion } from './utils/version.ts';
 import { pathToFileURL } from 'node:url';

src/cli/__tests__/auth-session.test.ts

@@ -12,7 +12,7 @@ import {
   summarizeCliSession,
   writeCliSession,
 } from '../auth-session.ts';
-import { normalizeError } from '../../utils/errors.ts';
+import { normalizeError } from '../../kernel/errors.ts';
 
 const baseFlags = {
   json: false,

src/cli/auth-session.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { runCmd } from '../utils/exec.ts';
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 import type { CliFlags } from '../utils/cli-flags.ts';
 import type { EnvMap } from '../utils/env-map.ts';
 import { readCloudJsonResponse } from './cloud-response.ts';

src/cli/batch-steps.ts

@@ -4,7 +4,7 @@ import { parseBatchStepRuntime } from '../batch-contract.ts';
 import { readInputFromCli } from '../commands/cli-grammar.ts';
 import { isCommandName, type CommandName } from '../commands/command-metadata.ts';
 import type { CliFlags } from '../utils/cli-flags.ts';
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 import { isRecord } from '../utils/parsing.ts';
 
 type LegacyCliBatchStep = {

src/cli/cloud-connection-profile.ts

@@ -1,6 +1,6 @@
 import crypto from 'node:crypto';
 import type { RemoteConfigProfile } from '../remote-config-schema.ts';
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 import type { CliFlags } from '../utils/cli-flags.ts';
 import type { EnvMap } from '../utils/env-map.ts';
 import { resolveCloudAccessForConnect } from './auth-session.ts';

src/cli/cloud-response.ts

@@ -1,4 +1,4 @@
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 
 export async function readCloudJsonResponse<T>(
   response: Response,

src/cli/commands/agent-cdp.ts

@@ -1,5 +1,5 @@
 import { runCmdStreaming } from '../../utils/exec.ts';
-import { AppError } from '../../utils/errors.ts';
+import { AppError } from '../../kernel/errors.ts';
 import { isRemoteBridgeBackend } from './remote-bridge.ts';
 import type { SessionRuntimeHints } from '../../contracts.ts';
 import type { CliFlags } from '../../utils/cli-flags.ts';

src/cli/commands/auth.ts

@@ -1,5 +1,5 @@
 import { resolveDaemonPaths } from '../../daemon/config.ts';
-import { AppError } from '../../utils/errors.ts';
+import { AppError } from '../../kernel/errors.ts';
 import { loginWithDeviceAuth, removeCliSession, summarizeCliSession } from '../auth-session.ts';
 import { writeCommandOutput } from './shared.ts';
 import type { ClientCommandHandler } from './router-types.ts';

src/cli/commands/connection-runtime.ts

@@ -2,7 +2,7 @@ import { resolveDaemonPaths } from '../../daemon/config.ts';
 import { stopReactDevtoolsCompanion } from '../../client-react-devtools-companion.ts';
 import { stopMetroTunnel } from '../../metro.ts';
 import { resolveRemoteConfigProfile } from '../../remote-config.ts';
-import { resolveDevice, type DeviceInfo } from '../../utils/device.ts';
+import { resolveDevice, type DeviceInfo } from '../../kernel/device.ts';
 import { shouldAgentCdpUseRemoteBridgeUrl } from './agent-cdp.ts';
 import type { MetroBridgeScope } from '../../client-companion-tunnel-contract.ts';
 import {
@@ -16,7 +16,7 @@ import {
 } from '../../remote-connection-state.ts';
 import { profileToCliFlags } from '../../utils/remote-config.ts';
 import type { BatchStep } from '../../client-types.ts';
-import { AppError } from '../../utils/errors.ts';
+import { AppError } from '../../kernel/errors.ts';
 import type { LeaseBackend, SessionRuntimeHints } from '../../contracts.ts';
 import type { CliFlags } from '../../utils/cli-flags.ts';
 import type { AgentDeviceClient, Lease } from '../../client.ts';

src/cli/commands/connection.ts

@@ -12,7 +12,7 @@ import {
   type RemoteConnectionState,
   type RemoteConnectionRequestMetadata,
 } from '../../remote-connection-state.ts';
-import { AppError } from '../../utils/errors.ts';
+import { AppError } from '../../kernel/errors.ts';
 import { resolveCloudConnectProfile } from '../cloud-connection-profile.ts';
 import { resolveProxyConnectProfile } from '../proxy-connection-profile.ts';
 import {

src/cli/commands/proxy.ts

@@ -2,7 +2,7 @@ import { randomBytes } from 'node:crypto';
 import { createDaemonProxyServer } from '../../daemon-proxy.ts';
 import { buildDaemonHttpBaseUrl } from '../../daemon/http-contract.ts';
 import { ensureDaemon, resolveClientSettings } from '../../daemon-client-lifecycle.ts';
-import { AppError } from '../../utils/errors.ts';
+import { AppError } from '../../kernel/errors.ts';
 import { colorize, supportsColor } from '../../utils/output.ts';
 import type { CliFlags } from '../../utils/cli-flags.ts';
 import { writeCommandOutput } from './shared.ts';

src/cli/commands/react-devtools.ts

@@ -3,7 +3,7 @@ import {
   ensureReactDevtoolsCompanion,
   stopReactDevtoolsCompanion,
 } from '../../client-react-devtools-companion.ts';
-import { AppError } from '../../utils/errors.ts';
+import { AppError } from '../../kernel/errors.ts';
 import { isRemoteBridgeBackend } from './remote-bridge.ts';
 import type { CliFlags } from '../../utils/cli-flags.ts';
 

src/cli/commands/replay.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { exportReplayScriptToMaestro } from '../../compat/maestro/export-flow.ts';
-import { AppError } from '../../utils/errors.ts';
+import { AppError } from '../../kernel/errors.ts';
 import { resolveUserPath } from '../../utils/path-resolution.ts';
 import { writeCommandOutput } from './shared.ts';
 import type { ClientCommandHandler } from './router-types.ts';

src/cli/commands/screenshot.ts

@@ -1,5 +1,5 @@
 import { formatScreenshotDiffText, formatSnapshotDiffText } from '../../utils/output.ts';
-import { AppError } from '../../utils/errors.ts';
+import { AppError } from '../../kernel/errors.ts';
 import { resolveUserPath } from '../../utils/path-resolution.ts';
 import type { AgentDeviceBackend } from '../../backend.ts';
 import type { AgentDeviceClient, CaptureScreenshotResult } from '../../client.ts';

src/cli/commands/web.ts

@@ -3,7 +3,7 @@ import {
   setupManagedAgentBrowser,
   type AgentBrowserToolStatus,
 } from '../../platforms/web/agent-browser-tool.ts';
-import { AppError } from '../../utils/errors.ts';
+import { AppError } from '../../kernel/errors.ts';
 import type { CliFlags } from '../../utils/cli-flags.ts';
 import { printJson } from '../../utils/output.ts';
 

src/cli/generated-remote-config.ts

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { resolveRemoteConfigProfile } from '../remote-config.ts';
 import type { RemoteConfigProfile, ResolvedRemoteConfigProfile } from '../remote-config-schema.ts';
-import { AppError, asAppError } from '../utils/errors.ts';
+import { AppError, asAppError } from '../kernel/errors.ts';
 import type { EnvMap } from '../utils/env-map.ts';
 import type { CliFlags } from '../utils/cli-flags.ts';
 import { profileToCliFlags } from '../utils/remote-config.ts';

src/cli/proxy-connection-profile.ts

@@ -1,6 +1,6 @@
 import crypto from 'node:crypto';
 import type { RemoteConfigProfile } from '../remote-config-schema.ts';
-import { AppError } from '../utils/errors.ts';
+import { AppError } from '../kernel/errors.ts';
 import type { CliFlags } from '../utils/cli-flags.ts';
 import type { EnvMap } from '../utils/env-map.ts';
 import { persistAndResolveGeneratedProfile } from './generated-remote-config.ts';

src/client-metro.ts

@@ -9,7 +9,7 @@ import type {
   MetroBridgeRuntimePayload,
   MetroRuntimeHints,
 } from './metro-types.ts';
-import { AppError } from './utils/errors.ts';
+import { AppError } from './kernel/errors.ts';
 import { runCmdSync, runCmdDetached } from './utils/exec.ts';
 import { resolveUserPath } from './utils/path-resolution.ts';
 import { waitForProcessExit } from './utils/process-identity.ts';

src/client-normalizers.ts

@@ -1,10 +1,10 @@
 import type { CommandFlags } from './core/dispatch.ts';
 import { screenshotFlagsFromOptions } from './contracts/screenshot.ts';
 import type { DaemonRequest, SessionRuntimeHints } from './daemon/types.ts';
-import { AppError, type NormalizedError } from './utils/errors.ts';
+import { AppError, type NormalizedError } from './kernel/errors.ts';
 import type { SnapshotNode } from './kernel/snapshot.ts';
 import { buildAppIdentifiers, buildDeviceIdentifiers } from './client-shared.ts';
-import { isPlatform } from './utils/device.ts';
+import { isPlatform } from './kernel/device.ts';
 import {
   leaseScopeFromOptions,
   leaseScopeToCommandFlags,

src/client-shared.ts

@@ -14,7 +14,7 @@ import {
   publicSnapshotCaptureAnnotations,
   type SnapshotCaptureAnnotations,
 } from './snapshot-capture-annotations.ts';
-import type { Platform } from './utils/device.ts';
+import type { Platform } from './kernel/device.ts';
 import { successText, withSuccessText } from './utils/success-text.ts';
 
 export function buildAppIdentifiers(params: {

src/client-types.ts

@@ -11,7 +11,7 @@ import type {
   SessionIsolationMode,
   SessionRuntimeHints,
 } from './contracts.ts';
-import type { DeviceKind, DeviceTarget, Platform, PlatformSelector } from './utils/device.ts';
+import type { DeviceKind, DeviceTarget, Platform, PlatformSelector } from './kernel/device.ts';
 import type { BackMode } from './core/back-mode.ts';
 import type { ClickButton } from './core/click-button.ts';
 import type { RecordingExportQuality } from './core/recording-export-quality.ts';

src/commands/batch/projection.ts

@@ -9,7 +9,7 @@ import {
   readBatchStepRecord,
 } from '../../batch-contract.ts';
 import type { DaemonBatchStep } from '../../core/batch.ts';
-import { AppError } from '../../utils/errors.ts';
+import { AppError } from '../../kernel/errors.ts';
 import { request } from '../cli-grammar/common.ts';
 import type { CommandInput, DaemonCommandRequest, DaemonWriter } from '../cli-grammar/types.ts';
 import { buildRequestFlags } from '../command-flags.ts';