agent-device 0.20.1 → 0.20.3

package/dist/src/index.d.ts

@@ -1,979 +1,635 @@
-import { C as normalizeAgentDeviceError, D as ScreenshotOverlayRef, F as DeviceKind, I as DeviceTarget, M as SnapshotVisibility, N as centerOfRect, O as SnapshotNode, P as AppleOS, R as PlatformSelector, S as isAgentDeviceError, _ as SessionIsolationMode, a as DaemonLockPolicy, b as NormalizedError, c as DaemonResponseData, g as ResponseLevel, i as DaemonInstallSource, j as SnapshotUnchanged, k as SnapshotQualityVerdict, m as NetworkIncludeMode, n as DaemonArtifactType, o as DaemonRequest, p as LeaseBackend, r as DaemonError, s as DaemonResponse, t as DaemonArtifact, v as SessionRuntimeHints, y as AppError, z as PublicPlatform } from "./sdk-contracts.js";
-import { a as GesturePointerCount, c as SwipePreset, d as AndroidSnapshotHelperInstallReason, f as AndroidSnapshotHelperTransport, l as TransformGestureParams, o as ScrollDirection, s as SwipePattern, u as AndroidSnapshotCaptureMode } from "./sdk-android-adb.js";
+import { A as SnapshotNode, B as DeviceTarget, C as normalizeAgentDeviceError, F as SnapshotVisibility, H as PlatformSelector, I as centerOfRect, L as AppleOS, P as SnapshotUnchanged, S as isAgentDeviceError, U as PublicPlatform, _ as SessionIsolationMode, a as DaemonLockPolicy, b as NormalizedError, c as DaemonResponseData, g as ResponseLevel, i as DaemonInstallSource, m as NetworkIncludeMode, o as DaemonRequest, p as LeaseBackend, r as DaemonError, s as DaemonResponse, t as DaemonArtifact, v as SessionRuntimeHints, y as AppError, z as DeviceKind } from "./sdk-contracts.js";
+import { c as ScrollDirection, d as SwipePreset, f as TransformGestureParams, l as ScrollInputDirection, s as GesturePointerCount, u as SwipePattern } from "./sdk-android-adb.js";
 import { t as AppsFilter } from "./sdk-app-inventory.js";
 import { t as BatchRunResult } from "./sdk-batch-runner.js";
 import { r as FindLocator } from "./sdk-finders.js";
-import { a as LongPressCommandResponseData, i as FindCommandResponseData, o as PressCommandResponseData, r as FillCommandResponseData, s as ClickButton, t as ClickCommandResponseData } from "./interaction.js";
+import { a as RemoteConnectionProfileFields, c as MetroPrepareResult, i as CloudProviderProfileFields, l as MetroReloadOptions, s as MetroPrepareOptions, u as MetroReloadResult } from "./sdk-remote-config.js";
+import { c as RecordingExportQuality, d as PublicSnapshotCaptureAnnotations, i as AgentArtifactsResult, l as ScreenshotResultData, m as JsonObject, n as DeviceRotation, o as CloudProviderSessionResult, p as SessionSurface, r as AlertAction, s as BackMode, t as TvRemoteButton, u as SnapshotDiagnosticsSummary } from "./tv-remote.js";
+import { t as ClickButton } from "./click-button.js";
+import { a as LongPressCommandResponseData, i as FindCommandResponseData, o as PressCommandResponseData, r as FillCommandResponseData, t as ClickCommandResponseData } from "./interaction.js";
 import { p as createLocalArtifactAdapter } from "./sdk-io.js";
-import { i as MetroPrepareKind, n as RemoteConnectionProfileFields, r as CloudProviderProfileFields } from "./sdk-remote-config.js";
-import { n as MetroBridgeResult, r as MetroRuntimeHints } from "./metro-types.js";
-//#region src/platforms/android/snapshot-types.d.ts
-type AndroidSnapshotBackendMetadata = {
-  backend: 'android-helper';
-  helperVersion?: string;
-  helperApiVersion?: string;
-  helperTransport?: AndroidSnapshotHelperTransport;
-  helperSessionReused?: boolean;
-  installReason?: AndroidSnapshotHelperInstallReason;
-  waitForIdleTimeoutMs?: number;
-  waitForIdleQuietMs?: number;
-  timeoutMs?: number;
-  maxDepth?: number;
-  maxNodes?: number;
-  rootPresent?: boolean;
-  captureMode?: AndroidSnapshotCaptureMode;
-  systemSurfaceOnly?: boolean;
-  windowCount?: number;
-  nodeCount?: number;
-  helperTruncated?: boolean;
-  elapsedMs?: number;
-};
-//#endregion
-//#region src/contracts/snapshot-capture-annotations.d.ts
-type SnapshotCaptureAnalysis = {
-  rawNodeCount: number;
-  maxDepth: number;
+//#region src/contracts/client-connection.d.ts
+type AgentDeviceDaemonTransport = (req: Omit<DaemonRequest, 'token'>) => Promise<DaemonResponse>;
+type AgentDeviceClientConfig = RemoteConnectionProfileFields & CloudProviderProfileFields & {
+  session?: string;
+  lockPolicy?: DaemonLockPolicy;
+  lockPlatform?: PlatformSelector;
+  requestId?: string;
+  sessionIsolation?: SessionIsolationMode;
+  leaseBackend?: LeaseBackend;
+  leaseTtlMs?: number;
+  runtime?: SessionRuntimeHints;
+  cwd?: string;
+  debug?: boolean;
+  cost?: boolean;
+  responseLevel?: ResponseLevel;
+  iosXctestrunFile?: string;
+  iosXctestDerivedDataPath?: string;
+  iosXctestEnvDir?: string;
 };
-type SnapshotCaptureFreshness = {
-  action: string;
-  retryCount: number;
-  staleAfterRetries: boolean;
-  reason?: 'empty-interactive' | 'sharp-drop' | 'stuck-route';
-};
-type SnapshotCaptureAnnotations = {
-  analysis?: SnapshotCaptureAnalysis;
-  androidSnapshot?: AndroidSnapshotBackendMetadata;
-  freshness?: SnapshotCaptureFreshness;
-  quality?: SnapshotQualityVerdict;
-  warnings?: string[];
+type AgentDeviceRequestOverrides = Pick<AgentDeviceClientConfig, 'session' | 'lockPolicy' | 'lockPlatform' | 'requestId' | 'daemonBaseUrl' | 'daemonAuthToken' | 'daemonTransport' | 'daemonServerMode' | 'tenant' | 'sessionIsolation' | 'runId' | 'leaseId' | 'leaseBackend' | 'leaseProvider' | 'deviceKey' | 'clientId' | 'providerApp' | 'providerOsVersion' | 'providerProject' | 'providerBuild' | 'providerSessionName' | 'awsProjectArn' | 'awsDeviceArn' | 'awsAppArn' | 'awsRegion' | 'awsInteractionMode' | 'leaseTtlMs' | 'cwd' | 'debug' | 'cost' | 'responseLevel' | 'iosXctestrunFile' | 'iosXctestDerivedDataPath' | 'iosXctestEnvDir'>;
+type AgentDeviceIdentifiers = {
+  session?: string;
+  deviceId?: string;
+  deviceName?: string;
+  udid?: string;
+  serial?: string;
+  appId?: string;
+  appBundleId?: string;
+  package?: string;
 };
-type PublicSnapshotCaptureAnnotations = Pick<SnapshotCaptureAnnotations, 'androidSnapshot' | 'warnings'> & {
-  snapshotQuality?: SnapshotQualityVerdict;
+type AgentDeviceSelectionOptions = {
+  platform?: PlatformSelector;
+  target?: DeviceTarget;
+  device?: string;
+  udid?: string;
+  serial?: string;
+  iosSimulatorDeviceSet?: string;
+  androidDeviceAllowlist?: string;
 };
+type DeviceCommandBaseOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions;
 //#endregion
-//#region src/contracts/snapshot-diagnostics.d.ts
-type SnapshotTimingStats = {
-  count: number;
-  p50Ms: number;
-  p95Ms: number;
-  maxMs: number;
-  slowThresholdMs: number;
-  platform?: PublicPlatform;
-  backends?: Record<string, number>;
-};
-type SnapshotDiagnosticsSummary = {
-  stats: SnapshotTimingStats;
-  warning?: string;
+//#region src/contracts/target-shutdown-contract.d.ts
+type TargetShutdownResult = {
+  success: boolean;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  error?: NormalizedError;
 };
 //#endregion
-//#region src/contracts/back-mode.d.ts
-declare const BACK_MODES: readonly ['in-app', 'system'];
-type BackMode = (typeof BACK_MODES)[number];
-//#endregion
-//#region src/contracts/device-rotation.d.ts
-declare const DEVICE_ROTATIONS: readonly ['portrait', 'portrait-upside-down', 'landscape-left', 'landscape-right'];
-type DeviceRotation = (typeof DEVICE_ROTATIONS)[number];
-//#endregion
-//#region src/contracts/tv-remote.d.ts
-declare const TV_REMOTE_BUTTON_DEFINITIONS: {
-  readonly up: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_DPAD_UP';
-    readonly appleRemoteButton: 'up';
-    readonly vegaKey: 'KEY_UP';
-  };
-  readonly down: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_DPAD_DOWN';
-    readonly appleRemoteButton: 'down';
-    readonly vegaKey: 'KEY_DOWN';
-  };
-  readonly left: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_DPAD_LEFT';
-    readonly appleRemoteButton: 'left';
-    readonly vegaKey: 'KEY_LEFT';
+//#region src/contracts/client-device-view.d.ts
+type AgentDeviceDevice = {
+  platform: PublicPlatform;
+  target: DeviceTarget;
+  kind: DeviceKind;
+  id: string;
+  name: string;
+  booted?: boolean;
+  /**
+   * Additive Apple-OS discriminant (iPhone/iPad/tvOS/visionOS/macOS). Present only for
+   * Apple devices; `platform` still carries the leaf (`ios`/`macos`).
+   */
+  appleOs?: AppleOS;
+  identifiers: AgentDeviceIdentifiers;
+  ios?: {
+    udid: string;
   };
-  readonly right: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_DPAD_RIGHT';
-    readonly appleRemoteButton: 'right';
-    readonly vegaKey: 'KEY_RIGHT';
+  android?: {
+    serial: string;
   };
-  readonly select: {
-    readonly aliases: readonly ["ok", "center", "enter"];
-    readonly androidKeyevent: 'KEYCODE_DPAD_CENTER';
-    readonly appleRemoteButton: 'select';
-    readonly vegaKey: 'KEY_ENTER';
+  vega?: {
+    serial: string;
   };
-  readonly menu: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_MENU';
-    readonly appleRemoteButton: 'menu';
-    readonly vegaKey: 'KEY_MENU';
+};
+type AgentDeviceCapabilitiesResult = {
+  device: AgentDeviceDevice;
+  availableCommands: string[];
+};
+type AgentDeviceSessionDevice = {
+  platform: PublicPlatform;
+  target: DeviceTarget;
+  id: string;
+  name: string;
+  /**
+   * Additive Apple-OS discriminant (iPhone/iPad/tvOS/visionOS/macOS). Present only for
+   * Apple devices; `platform` still carries the leaf (`ios`/`macos`).
+   */
+  appleOs?: AppleOS;
+  identifiers: AgentDeviceIdentifiers;
+  ios?: {
+    udid: string;
+    simulatorSetPath?: string | null;
   };
-  readonly home: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_HOME';
-    readonly appleRemoteButton: 'home';
-    readonly vegaKey: 'KEY_HOMEPAGE';
+  android?: {
+    serial: string;
   };
-  readonly back: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_BACK';
-    readonly appleRemoteButton: 'menu';
-    readonly vegaKey: 'KEY_BACK';
+  vega?: {
+    serial: string;
   };
 };
-declare const TV_REMOTE_BUTTONS: (keyof typeof TV_REMOTE_BUTTON_DEFINITIONS)[];
-type TvRemoteButton = (typeof TV_REMOTE_BUTTONS)[number];
-//#endregion
-//#region src/contracts/navigation.d.ts
-/**
- * Closed results of the navigation/global action commands. Each mirrors the
- * dispatch handler's literal return EXACTLY (src/core/dispatch.ts
- * `DISPATCH_HANDLERS`): a fixed `action` discriminant plus the always-present
- * `successText` message (the handlers always pass a non-empty message, so it is
- * required here). The handlers spread nothing else, so the shapes are closed —
- * consistent with the `viewport` contract, the generic-dispatch Android
- * dialog-recovery `warning` annotation is intentionally not part of the contract.
- */
-/** `home` — `{ action: 'home', message: 'Home' }`. */
-type HomeCommandResult = {
-  action: 'home';
-  message: string;
+type AgentDeviceSession = {
+  name: string;
+  createdAt: number;
+  sessionStateDir?: string;
+  runnerLogPath?: string;
+  device: AgentDeviceSessionDevice;
+  identifiers: AgentDeviceIdentifiers;
 };
-/** `back` — `{ action: 'back', mode, message: 'Back' }`; `mode` defaults to `'in-app'`. */
-type BackCommandResult = {
-  action: 'back';
-  mode: BackMode;
-  message: string;
+type StartupPerfSample = {
+  durationMs: number;
+  measuredAt: string;
+  method: string;
+  appTarget?: string;
+  appBundleId?: string;
 };
-/** `orientation` — `{ action: 'orientation', orientation, message: 'Rotated to <orientation>' }`. */
-type OrientationCommandResult = {
-  action: 'orientation';
-  orientation: DeviceRotation;
-  message: string;
+type DeviceBootOptions = DeviceCommandBaseOptions & {
+  headless?: boolean;
 };
-/**
- * @deprecated The `rotate` command was renamed to `orientation`. This is the
- * legacy response contract (`action: 'rotate'`) that shipped in v0.18/v0.19,
- * retained for existing SDK consumers until the next major version. New code
- * should use {@link OrientationCommandResult}.
- */
-type RotateCommandResult = {
-  action: 'rotate';
-  orientation: DeviceRotation;
-  message: string;
+type DeviceShutdownOptions = DeviceCommandBaseOptions;
+//#endregion
+//#region src/contracts/client-app.d.ts
+type AppInstallOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+  app?: string;
+  appPath: string;
 };
-/** `app-switcher` — `{ action: 'app-switcher', message: 'Opened app switcher' }`. */
-type AppSwitcherCommandResult = {
-  action: 'app-switcher';
-  message: string;
+type AppDeployOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+  app: string;
+  appPath: string;
 };
-/** `tv-remote` — `{ action: 'tv-remote', button, durationMs?, message }`. */
-type TvRemoteCommandResult = {
-  action: 'tv-remote';
-  button: TvRemoteButton;
-  durationMs?: number;
-  message: string;
+type AppDeployResult = {
+  app: string;
+  appPath: string;
+  platform: PublicPlatform;
+  appId?: string;
+  bundleId?: string;
+  package?: string;
+  identifiers: AgentDeviceIdentifiers;
 };
-//#endregion
-//#region src/contracts/recording-export-quality.d.ts
-declare const RECORDING_EXPORT_QUALITIES: readonly ['medium', 'high'];
-type RecordingExportQuality = (typeof RECORDING_EXPORT_QUALITIES)[number];
-//#endregion
-//#region src/contracts/recording-scope.d.ts
-declare const RECORDING_SCOPE_VALUES: readonly ['app', 'device', 'system'];
-type RecordingScope = (typeof RECORDING_SCOPE_VALUES)[number];
-//#endregion
-//#region src/contracts/alert-contract.d.ts
-declare const ALERT_ACTIONS: readonly ['get', 'accept', 'dismiss', 'wait'];
-type AlertAction = (typeof ALERT_ACTIONS)[number];
-//#endregion
-//#region src/contracts/json.d.ts
-type JsonPrimitive = string | number | boolean | null;
-type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
-type JsonObject = {
-  [key: string]: JsonValue;
+type AppOpenOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+  app?: string;
+  url?: string;
+  surface?: SessionSurface;
+  activity?: string;
+  launchConsole?: string;
+  launchArgs?: string[];
+  relaunch?: boolean;
+  saveScript?: boolean | string;
+  /** #1258: overwrite an existing --save-script target instead of refusing. Alias: --overwrite. */
+  force?: boolean;
+  deviceHub?: boolean;
+  testIme?: boolean;
+  noRecord?: boolean;
+  runtime?: SessionRuntimeHints;
 };
-//#endregion
-//#region src/commands/command-contract.d.ts
-type JsonSchema = {
-  type?: string | readonly string[];
-  description?: string;
-  properties?: Record<string, JsonSchema>;
-  required?: readonly string[];
-  additionalProperties?: boolean | JsonSchema;
-  items?: JsonSchema;
-  prefixItems?: readonly JsonSchema[];
-  oneOf?: readonly JsonSchema[];
-  enum?: readonly unknown[];
-  const?: unknown;
-  minimum?: number;
-  maximum?: number;
+type AppOpenResult = {
+  session: string;
+  warnings?: string[];
+  sessionStateDir?: string;
+  runnerLogPath?: string;
+  requestLogPath?: string;
+  eventLogPath?: string;
+  appName?: string;
+  appBundleId?: string;
+  appId?: string;
+  startup?: StartupPerfSample;
+  runtime?: SessionRuntimeHints;
+  device?: AgentDeviceSessionDevice;
+  identifiers: AgentDeviceIdentifiers;
 };
-type ExecutableCommandProjection<ClientMethod extends string = string> = {
-  clientMethod: ClientMethod;
-  outputSchema: JsonSchema;
+type AppCloseOptions = AgentDeviceRequestOverrides & {
+  app?: string;
+  shutdown?: boolean;
+  saveScript?: boolean | string;
+  /** #1258: overwrite an existing --save-script target instead of refusing. Alias: --overwrite. */
+  force?: boolean;
 };
-//#endregion
-//#region src/contracts/session-surface.d.ts
-declare const SESSION_SURFACES: readonly ['app', 'frontmost-app', 'desktop', 'menubar'];
-type SessionSurface = (typeof SESSION_SURFACES)[number];
-//#endregion
-//#region src/utils/screenshot-result.d.ts
-type ScreenshotResultData = {
-  path?: string;
-  width?: number;
-  height?: number;
-  logicalWidth?: number;
-  logicalHeight?: number;
-  pixelDensity?: number;
-  overlayRefs?: ScreenshotOverlayRef[];
+type AppCloseResult = {
+  session: string;
+  closedApp?: string;
+  shutdown?: TargetShutdownResult;
+  /**
+   * #1258: absolute path of the committed session/healed script when this close
+   * published one (`close --save-script`, or a repair-armed session's finalize)
+   * — so a client that requested publication learns where the file landed.
+   */
+  savedScript?: string;
+  identifiers: AgentDeviceIdentifiers;
 };
-//#endregion
-//#region src/commands/interaction/runtime/gestures.d.ts
-declare const SCROLL_INPUT_DIRECTIONS: readonly ['up', 'down', 'left', 'right', 'top', 'bottom'];
-type ScrollInputDirection = (typeof SCROLL_INPUT_DIRECTIONS)[number];
-//#endregion
-//#region src/commands/system/navigation-projection.d.ts
-declare const navigationCommandProjectionType: unique symbol;
-type NavigationCommandProjection<Options, Result, Required extends boolean, ClientMethod extends string> = ExecutableCommandProjection<ClientMethod> & {
-  readonly [navigationCommandProjectionType]?: {
-    options: Options;
-    result: Result;
-    required: Required;
-  };
+type AppInstallFromSourceOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+  source: DaemonInstallSource;
+  retainPaths?: boolean;
+  retentionMs?: number;
 };
-declare const NAVIGATION_COMMAND_PROJECTIONS: {
-  readonly back: NavigationCommandProjection<{
-    mode?: BackMode;
-  }, BackCommandResult, false, "back">;
-  readonly home: NavigationCommandProjection<{}, HomeCommandResult, false, "home">;
-  readonly orientation: NavigationCommandProjection<{
-    orientation: DeviceRotation;
-  }, OrientationCommandResult, true, "orientation">;
-  readonly 'app-switcher': NavigationCommandProjection<{}, AppSwitcherCommandResult, false, "appSwitcher">;
-  readonly 'tv-remote': NavigationCommandProjection<{
-    button: TvRemoteButton;
-    durationMs?: number;
-  }, TvRemoteCommandResult, true, "tvRemote">;
+type AppInstallFromSourceResult = {
+  appName?: string;
+  appId?: string;
+  bundleId?: string;
+  packageName?: string;
+  launchTarget: string;
+  installablePath?: string;
+  archivePath?: string;
+  materializationId?: string;
+  materializationExpiresAt?: string;
+  identifiers: AgentDeviceIdentifiers;
 };
-type NavigationCommandName = keyof typeof NAVIGATION_COMMAND_PROJECTIONS;
-type NavigationCommandOptions<Name extends NavigationCommandName> = (typeof NAVIGATION_COMMAND_PROJECTIONS)[Name] extends NavigationCommandProjection<infer Options, unknown, boolean, string> ? Options : never;
-type ProjectedNavigationCommandMethod<BaseOptions, Projection> = Projection extends NavigationCommandProjection<infer Options, infer Result, infer Required, string> ? Required extends true ? (options: BaseOptions & Options) => Promise<Result> : (options?: BaseOptions & Options) => Promise<Result> : never;
-type ProjectedNavigationCommandClient<BaseOptions> = { [Name in NavigationCommandName as (typeof NAVIGATION_COMMAND_PROJECTIONS)[Name]['clientMethod']]: ProjectedNavigationCommandMethod<BaseOptions, (typeof NAVIGATION_COMMAND_PROJECTIONS)[Name]>; };
-//#endregion
-//#region src/contracts/logs.d.ts
-declare const LOG_ACTION_VALUES: readonly ['path', 'start', 'stop', 'doctor', 'mark', 'clear'];
-type LogAction = (typeof LOG_ACTION_VALUES)[number];
-//#endregion
-//#region src/client/client-companion-tunnel-contract.d.ts
-type CompanionTunnelScope = {
-  tenantId: string;
-  runId: string;
-  leaseId: string;
+type AppListOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+  appsFilter?: AppsFilter;
 };
-type MetroBridgeScope = CompanionTunnelScope;
-//#endregion
-//#region src/metro/client-metro.d.ts
-type ResolvedMetroKind = Exclude<MetroPrepareKind, 'auto'>;
-type PrepareMetroRuntimeResult = {
-  projectRoot: string;
-  kind: ResolvedMetroKind;
-  dependenciesInstalled: boolean;
-  packageManager: string | null;
-  started: boolean;
-  reused: boolean;
-  pid: number;
-  logPath: string;
-  statusUrl: string;
-  runtimeFilePath: string | null;
-  iosRuntime: MetroRuntimeHints;
-  androidRuntime: MetroRuntimeHints;
-  bridge: MetroBridgeResult | null;
+type AppPushOptions = DeviceCommandBaseOptions & {
+  app: string;
+  payload: string | JsonObject;
 };
-/**
- * `transport` says which channel delivered the reload: `http` for the classic GET /reload route,
- * `message-socket` for the /message websocket broadcast used when the server has no HTTP reload
- * route (Expo). `status`/`body` always describe the HTTP probe; on the websocket path `reloadUrl`
- * is the ws(s) message-socket URL.
- */
-type ReloadMetroResult = {
-  reloaded: true;
-  reloadUrl: string;
-  status: number;
-  body: string;
-  transport: 'http' | 'message-socket';
+type AppTriggerEventOptions = DeviceCommandBaseOptions & {
+  event: string;
+  payload?: JsonObject;
 };
-//#endregion
-//#region src/contracts/target-shutdown-contract.d.ts
-type TargetShutdownResult = {
-  success: boolean;
-  exitCode: number;
-  stdout: string;
-  stderr: string;
-  error?: NormalizedError;
+type MaterializationReleaseOptions = AgentDeviceRequestOverrides & {
+  materializationId: string;
+};
+type MaterializationReleaseResult = {
+  released: boolean;
+  materializationId: string;
+  identifiers: AgentDeviceIdentifiers;
 };
 //#endregion
-//#region src/contracts/perf.d.ts
-declare const PERF_AREA_VALUES: readonly ['metrics', 'frames', 'memory', 'cpu', 'trace'];
-declare const PERF_ACTION_VALUES: readonly ['sample', 'snapshot', 'start', 'stop', 'report'];
-declare const PERF_SUBJECT_VALUES: readonly ['profile'];
-declare const PERF_KIND_VALUES: readonly ['xctrace', 'simpleperf', 'perfetto', 'android-hprof', 'memgraph'];
-type PerfArea = (typeof PERF_AREA_VALUES)[number];
-type PerfAction = (typeof PERF_ACTION_VALUES)[number];
-type PerfSubject = (typeof PERF_SUBJECT_VALUES)[number];
-type PerfKind = (typeof PERF_KIND_VALUES)[number];
-//#endregion
-//#region src/contracts/debug-symbols.d.ts
-type DebugSymbolsOptions = {
-  action?: 'symbols';
-  artifact: string;
-  dsym?: string;
-  searchPath?: string;
-  out?: string;
-  cwd?: string;
+//#region src/contracts/client-capture.d.ts
+type CaptureSnapshotOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+  interactiveOnly?: boolean;
+  depth?: number;
+  scope?: string;
+  raw?: boolean;
+  forceFull?: boolean;
+  timeoutMs?: number;
+  /**
+   * #1271 stage 2 (ADR 0012 amendment): `snapshot` is observation-only and
+   * excluded from a repair-armed heal by default; `record` forces it
+   * through. Mutually exclusive with `noRecord`.
+   */
+  noRecord?: boolean;
+  record?: boolean;
 };
-type DebugSymbolsImage = {
-  name: string;
-  uuid: string;
-  arch?: string;
-  dsymPath: string;
-  binaryPath: string;
+type CaptureSnapshotResult = {
+  nodes: SnapshotNode[];
+  truncated: boolean;
+  appName?: string;
+  appBundleId?: string;
+  visibility?: SnapshotVisibility;
+  unchanged?: SnapshotUnchanged;
+  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
+  identifiers: AgentDeviceIdentifiers;
+  /**
+   * ADR 0014: the response-level ref-frame epoch the plain node refs were minted
+   * from. A ref-issuing snapshot carries it ONCE (nodes stay plain `@e12` for the
+   * token budget); pair a ref with it (`@e12~s<refsGeneration>`) before a mutation.
+   */
+  refsGeneration?: number;
+  /**
+   * Digest response view only: a capped list of `{ ref, label? }` pairs taken
+   * from the full `nodes` tree so the MCP layer can still pin refs when the
+   * default-level `nodes` payload is intentionally omitted.
+   */
+  refs?: Array<{
+    ref: string;
+    label?: string;
+  }>;
+} & PublicSnapshotCaptureAnnotations;
+type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
+  path?: string;
+  overlayRefs?: boolean;
+  pixelDensity?: number;
+  fullscreen?: boolean;
+  maxSize?: number;
+  stabilize?: boolean;
+  normalizeStatusBar?: boolean;
+  surface?: SessionSurface;
 };
-type DebugSymbolsCrashFrame = {
-  index: number;
-  image: string;
-  address: string;
-  symbol?: string;
+type CaptureScreenshotResult = ScreenshotResultData & {
+  path: string;
+  identifiers: AgentDeviceIdentifiers;
 };
-type DebugSymbolsCrashSummary = {
-  format: 'ips' | 'text';
-  appName?: string;
-  bundleId?: string;
-  version?: string;
-  incident?: string;
-  timestamp?: string;
-  exceptionType?: string;
-  exceptionCodes?: string;
-  terminationReason?: string;
-  crashedThread?: number;
-  topFrames: DebugSymbolsCrashFrame[];
-  findings: string[];
+type CaptureDiffOptions = DeviceCommandBaseOptions & Pick<CaptureSnapshotOptions, 'interactiveOnly' | 'depth' | 'scope' | 'raw'> & {
+  kind: 'snapshot';
+  out?: string;
 };
-type DebugSymbolsResult = {
-  kind: 'debugSymbols';
-  platform: 'apple';
-  artifactPath: string;
-  outPath: string;
-  crash: DebugSymbolsCrashSummary;
-  matchedImages: DebugSymbolsImage[];
-  symbolicatedFrames: number;
-  skippedImages: number;
-  warnings?: string[];
-  message: string;
+type SelectorSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'scope' | 'raw'>;
+type FindSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'raw'>;
+//#endregion
+//#region src/contracts/client-target.d.ts
+type PointTarget = {
+  x: number;
+  y: number;
+  ref?: never;
+  selector?: never;
+  label?: never;
+};
+type RefTarget = {
+  ref: string;
+  label?: string;
+  x?: never;
+  y?: never;
+  selector?: never;
+};
+type SelectorTarget = {
+  selector: string;
+  x?: never;
+  y?: never;
+  ref?: never;
+  label?: never;
 };
+type InteractionTarget = PointTarget | RefTarget | SelectorTarget;
+type ElementTarget = RefTarget | SelectorTarget;
 //#endregion
-//#region src/contracts/device.d.ts
+//#region src/contracts/client-gesture.d.ts
+type RepeatedPressOptions = {
+  count?: number;
+  intervalMs?: number;
+  holdMs?: number;
+  jitterPx?: number;
+  doubleTap?: boolean;
+};
 /**
- * Closed result of the `boot` command. Mirrors the daemon handler's only
- * success return EXACTLY (src/daemon/handlers/session-state.ts) — the fixed
- * object literal `{ platform, target, device, id, kind, booted }` plus the
- * additive `appleOs` discriminant, emitted only for Apple devices.
+ * Opt-in (#1101): after the action, wait for the UI to go quiet and return the
+ * settled diff vs the pre-action tree (`settle` on the result) in the same
+ * response. Best-effort — never fails the action. `settleQuietMs` tunes the
+ * quiet window (default 500ms); `timeoutMs` bounds the settle wait (default
+ * 10s) when `settle` is true. A bare `timeoutMs` without `settle` is ignored
+ * for compatibility; `settleQuietMs` still requires `settle`.
  */
-type BootCommandResult = {
-  platform: PublicPlatform;
-  target: DeviceTarget;
-  /** Human-readable device name (`device.name`). */
-  device: string;
-  /** Stable device id (`device.id`). */
-  id: string;
-  kind: DeviceKind;
-  /** Always `true` on the success path. */
-  booted: true;
+type SettleCommandOptions = {
+  settle?: boolean;
+  settleQuietMs?: number;
+  timeoutMs?: number;
+};
+type ClickOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions & SettleCommandOptions & {
+  button?: ClickButton;
   /**
-   * Additive Apple-OS discriminant (`device.appleOs`): iPhone/iPad/tvOS/visionOS/macOS.
-   * Present only for Apple devices; absent for non-Apple platforms. `platform` stays the
-   * leaf (`ios`/`macos`) — this is an extra field, not a replacement.
+   * Opt-in (#1047): return cheap post-action evidence (AX digest, node counts,
+   * changedFromBefore) in the response instead of requiring a follow-up
+   * snapshot to confirm the action had an effect.
    */
-  appleOs?: AppleOS;
+  verify?: boolean;
 };
-/**
- * Closed result of the `shutdown` command. Mirrors the daemon handler's success
- * return EXACTLY (src/daemon/handlers/session-state.ts) — the fixed object
- * literal `{ platform, target, device, id, kind, shutdown }` plus the additive
- * `appleOs` discriminant (Apple devices only). The `shutdown` field is the raw
- * {@link TargetShutdownResult} from `shutdownDeviceTarget`.
- */
-type ShutdownCommandResult = {
-  platform: PublicPlatform;
-  target: DeviceTarget;
-  /** Human-readable device name (`device.name`). */
-  device: string;
-  /** Stable device id (`device.id`). */
-  id: string;
-  kind: DeviceKind;
-  shutdown: TargetShutdownResult;
-  /**
-   * Additive Apple-OS discriminant (`device.appleOs`): iPhone/iPad/tvOS/visionOS/macOS.
-   * Present only for Apple devices; absent for non-Apple platforms. `platform` stays the
-   * leaf (`ios`/`macos`) — this is an extra field, not a replacement.
-   */
-  appleOs?: AppleOS;
-};
-//#endregion
-//#region src/contracts/viewport.d.ts
-/**
- * Closed result of the `viewport` command. Mirrors the dispatch handler's return
- * EXACTLY (src/core/dispatch.ts `handleViewportCommand`) — `{ width, height }`
- * plus the always-present `successText` message. The generic dispatch path
- * returns this object unchanged (viewport has no Android dialog guard, so no
- * `warning` is ever appended), so the shape is intentionally closed.
- */
-type ViewportCommandResult = {
-  width: number;
-  height: number;
-  message: string;
-};
-//#endregion
-//#region src/contracts/clipboard.d.ts
-/**
- * Closed result of the `clipboard` command. Mirrors the dispatch handler's
- * literal return EXACTLY (src/core/dispatch.ts `handleClipboardCommand`): a
- * discriminated union on `action`. `read` returns the clipboard `text`; `write`
- * reports the written `textLength` plus the `successText` message. The handler
- * spreads nothing else, so each branch is closed.
- */
-type ClipboardCommandResult = {
-  action: 'read';
-  text: string;
-} | {
-  action: 'write';
-  textLength: number;
-  message: string;
-};
-//#endregion
-//#region src/contracts/app-state.d.ts
-/**
- * Closed result of the `appstate` command, grounded in the daemon handler's
- * success returns (src/daemon/handlers/session-state.ts `handleAppStateCommand`).
- * A discriminated union on `platform`:
- *  - Apple (`ios` / `macos`) session state, with iOS-only device locators that
- *    the previous hand-written mirror omitted; and
- *  - Android foreground `package` / `activity`.
- *
- * The handler returns one of these fixed objects (errors take the `ok: false`
- * path), so each branch is closed.
- */
-type AppStateCommandResult = {
-  platform: 'ios' | 'macos';
-  appName: string;
-  appBundleId?: string;
-  source: 'session';
-  surface: SessionSurface;
-  /** iOS only — the session device's UDID. */
-  device_udid?: string;
-  /** iOS only — the simulator set path, or `null` when unknown. */
-  ios_simulator_device_set?: string | null;
-} | {
-  platform: 'android';
-  package: string;
-  activity: string;
-};
-//#endregion
-//#region src/contracts/keyboard.d.ts
-/**
- * Closed result of the `keyboard` command, grounded in the dispatch handlers'
- * literal returns (src/core/dispatch.ts `handleAndroidKeyboardCommand` /
- * `handleIosKeyboardCommand`).
- *
- * `platform` and `action` are always present; the remaining fields appear per
- * branch (Android `status`/`dismiss` carry the keyboard-state fields; `enter`
- * and iOS `dismiss` carry a `message`). It is kept as a flat closed shape rather
- * than a five-way `platform`×`action` union because the per-branch field sets
- * overlap heavily and the underlying Android keyboard-state types live in the
- * platform layer (below the public contract). The `Record` index signature of
- * the previous hand-written mirror is dropped, and the spurious `| null`s are
- * removed (the handler never returns `null` for these).
- */
-type KeyboardCommandResult = {
-  platform: 'android' | 'ios';
-  action: 'status' | 'dismiss' | 'enter';
-  visible?: boolean;
-  wasVisible?: boolean;
-  dismissed?: boolean;
-  attempts?: number;
-  inputType?: string;
-  type?: 'text' | 'number' | 'email' | 'phone' | 'password' | 'datetime' | 'unknown';
-  inputMethodPackage?: string;
-  focusedPackage?: string;
-  focusedResourceId?: string;
-  inputOwner?: 'app' | 'ime' | 'unknown';
-  message?: string;
+type PressOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions & SettleCommandOptions & {
+  verify?: boolean;
 };
-//#endregion
-//#region src/contracts/wait.d.ts
-/**
- * Public daemon result for `wait`. The runtime-local result carries a `kind`
- * discriminant, but `toDaemonWaitData` intentionally projects the normal daemon
- * payload to this compact shape. The direct iOS selector fast path may still
- * include `kind: 'selector'` additively.
- */
-type WaitCommandResult = {
-  waitedMs: number;
-  kind?: 'selector';
-  text?: string;
-  selector?: string;
-  captures?: number;
-  nodeCount?: number;
-  hint?: string;
-  warning?: string;
+type LongPressOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & SettleCommandOptions & {
+  durationMs?: number;
 };
-//#endregion
-//#region src/contracts/prepare.d.ts
-type PrepareIosRunnerCacheKind = 'exact' | 'restore-key' | 'miss' | 'external';
-type PrepareIosRunnerArtifactState = 'valid' | 'rebuilt';
-type PrepareIosRunnerTiming = {
-  totalMs: number;
-  additiveParts: {
-    buildMs?: number;
-    connectAfterBuildMs: number;
-    healthCheckMs: number;
+type SwipeOptions = DeviceCommandBaseOptions & {
+  from: {
+    x: number;
+    y: number;
   };
-  containment: {
-    connectMs?: ['buildMs'];
-    healthCheckMs: [];
+  to: {
+    x: number;
+    y: number;
   };
-  note: string;
+  count?: number;
+  pauseMs?: number;
+  pattern?: SwipePattern;
 };
-/**
- * Public daemon result for `prepare ios-runner`. The runner-local prepare result
- * is projected by `prepareIosRunnerResponseData` with device identity and timing
- * guidance before it reaches the client.
- */
-type PrepareCommandResult = {
-  action: 'ios-runner';
-  platform: PublicPlatform;
-  deviceId: string;
-  deviceName: string;
-  kind: DeviceKind;
-  durationMs: number;
-  runner: JsonObject;
-  cache?: PrepareIosRunnerCacheKind;
-  artifact?: PrepareIosRunnerArtifactState;
-  buildMs?: number;
-  connectMs: number;
-  healthCheckMs: number;
-  xctestrunPath?: string;
-  recoveryReason?: string;
-  failureReason?: string;
-  timing: PrepareIosRunnerTiming;
-  message: string;
+type PanOptions = DeviceCommandBaseOptions & {
+  x: number;
+  y: number;
+  dx: number;
+  dy: number;
+  pointerCount?: GesturePointerCount;
+  durationMs?: number;
 };
-//#endregion
-//#region src/contracts/push.d.ts
-type PushCommandResult = {
-  platform: 'ios';
-  bundleId: string;
-  message: string;
-} | {
-  platform: 'android';
-  package: string;
-  action: string;
-  extrasCount: number;
-  message: string;
+type FlingOptions = DeviceCommandBaseOptions & {
+  direction: ScrollDirection;
+  x: number;
+  y: number;
+  distance?: number;
 };
-//#endregion
-//#region src/contracts/app-events.d.ts
-type TriggerAppEventCommandResult = {
-  event: string;
-  eventUrl: string;
-  transport: 'deep-link';
-  message: string;
+type SwipeGestureOptions = DeviceCommandBaseOptions & {
+  preset: SwipePreset;
 };
-//#endregion
-//#region src/contracts/doctor.d.ts
-type DoctorStatus = 'pass' | 'warn' | 'fail' | 'info';
-type DoctorKind = 'auto' | 'react-native' | 'expo' | 'repack';
-type DoctorCheck = {
-  id: string;
-  status: DoctorStatus;
-  summary: string;
-  hint?: string;
-  command?: string;
-  evidence?: Record<string, unknown>;
+type FocusOptions = DeviceCommandBaseOptions & {
+  x: number;
+  y: number;
 };
-type DoctorCommandResult = {
-  status: DoctorStatus;
-  summary: string;
-  kind: DoctorKind;
-  platform?: PlatformSelector;
-  target?: DeviceTarget;
-  targetApp?: string;
-  metro?: {
-    host: string;
-    port: number;
-  };
-  checks: DoctorCheck[];
+type TypeTextOptions = DeviceCommandBaseOptions & {
+  text: string;
+  delayMs?: number;
 };
-//#endregion
-//#region src/snapshot/snapshot-diff.d.ts
-type SnapshotDiffLine = {
-  kind: 'added' | 'removed' | 'unchanged';
+type FillOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & SettleCommandOptions & {
   text: string;
-  /**
-   * Plain ref body (`e12`) of the CURRENT-tree node behind an added line.
-   * Only populated with `withRefs` (interaction `--settle`, #1101) so the
-   * `diff` command's wire shape stays byte-identical. Removed/unchanged lines
-   * never carry it: a removed line's ref names a node of the replaced tree.
-   */
-  ref?: string;
+  delayMs?: number;
+  /** Publish this fill value as `${VAR}` when script recording is armed. */
+  recordAs?: string;
+  verify?: boolean;
 };
-type SnapshotDiffSummary = {
-  additions: number;
-  removals: number;
-  unchanged: number;
+type PinchOptions = DeviceCommandBaseOptions & {
+  scale: number;
+  x?: number;
+  y?: number;
 };
-//#endregion
-//#region src/contracts/diff.d.ts
-type DiffSnapshotCommandResult = {
-  mode: 'snapshot';
-  baselineInitialized: boolean;
-  summary: SnapshotDiffSummary;
-  lines: SnapshotDiffLine[];
-  warnings?: string[];
+type RotateGestureOptions = DeviceCommandBaseOptions & {
+  degrees: number;
+  x?: number;
+  y?: number;
+};
+type TransformGestureOptions = DeviceCommandBaseOptions & TransformGestureParams;
+type ScrollOptions = DeviceCommandBaseOptions & {
+  direction: ScrollInputDirection;
+  amount?: number;
+  pixels?: number;
+  durationMs?: number;
 };
 //#endregion
-//#region src/contracts/recording.d.ts
-type RecordingAppIdentity = {
-  bundleId: string;
-  name?: string;
+//#region src/contracts/client-lease.d.ts
+type Lease = {
+  leaseId: string;
+  tenantId: string;
+  runId: string;
+  backend: LeaseBackend;
+  leaseProvider?: string;
+  deviceKey?: string;
+  clientId?: string;
+  createdAt?: number;
+  heartbeatAt?: number;
+  expiresAt?: number;
 };
-type RecordingStartCommandResult = {
-  recording: 'started';
-  outPath: string;
-  sessionStateDir: string;
-  recordingBackend?: string;
-  recordingScope?: RecordingScope;
-  recordOnlySession?: boolean;
-  activeSessionApp?: RecordingAppIdentity;
-  showTouches: boolean;
+type LeaseOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+  ttlMs?: number;
 };
-type RecordingStopCommandResult = {
-  recording: 'stopped';
-  outPath: string;
-  telemetryPath?: string;
-  artifacts: DaemonArtifact[];
-  recordingBackend?: string;
-  recordingScope?: RecordingScope;
-  recordOnlySession?: boolean;
-  activeSessionApp?: RecordingAppIdentity;
-  durationMs: number;
-  showTouches: boolean;
-  warning?: string;
-  overlayWarning?: string;
-  chunks?: Array<{
-    index: number;
-    path: string;
-  }>;
+type LeaseAllocateOptions = LeaseOptions & {
+  tenant: string;
+  runId: string;
+  leaseBackend?: LeaseBackend;
+  leaseProvider?: string;
+  provider?: string;
+  deviceKey?: string;
+  clientId?: string;
 };
-type RecordingCommandResult = RecordingStartCommandResult | RecordingStopCommandResult;
-type TraceCommandResult = {
-  trace: 'started';
-  outPath: string;
-} | {
-  trace: 'stopped';
-  outPath: string;
+type LeaseScopedOptions = LeaseOptions & {
+  tenant?: string;
+  runId?: string;
+  leaseId: string;
+  leaseBackend?: LeaseBackend;
+  leaseProvider?: string;
+  provider?: string;
+  deviceKey?: string;
+  clientId?: string;
+};
+type CloudArtifactsOptions = AgentDeviceRequestOverrides & {
+  provider?: string;
+  providerSessionId?: string;
 };
 //#endregion
-//#region src/contracts/replay.d.ts
-type ReplayCommandResult = {
-  replayed: number;
-  healed: number;
-  session: string;
-  /**
-   * True iff `session` still exists in the daemon's session store when the
-   * response is built — i.e. the replayed script had no terminal `close`
-   * (ADR 0016's consumption contract). The client uses this, not script
-   * parsing, to decide whether an owned one-shot daemon must stay alive so
-   * the caller can keep addressing this session.
-   */
-  sessionActive: boolean;
-  artifactPaths: string[];
-  warnings?: string[];
-  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
-  message: string;
+//#region src/contracts/logs.d.ts
+declare const LOG_ACTION_VALUES: readonly ['path', 'start', 'stop', 'doctor', 'mark', 'clear'];
+type LogAction = (typeof LOG_ACTION_VALUES)[number];
+//#endregion
+//#region src/contracts/perf.d.ts
+declare const PERF_AREA_VALUES: readonly ['metrics', 'frames', 'memory', 'cpu', 'trace'];
+declare const PERF_ACTION_VALUES: readonly ['sample', 'snapshot', 'start', 'stop', 'report'];
+declare const PERF_SUBJECT_VALUES: readonly ['profile'];
+declare const PERF_KIND_VALUES: readonly ['xctrace', 'simpleperf', 'perfetto', 'android-hprof', 'memgraph'];
+type PerfArea = (typeof PERF_AREA_VALUES)[number];
+type PerfAction = (typeof PERF_ACTION_VALUES)[number];
+type PerfSubject = (typeof PERF_SUBJECT_VALUES)[number];
+type PerfKind = (typeof PERF_KIND_VALUES)[number];
+//#endregion
+//#region src/contracts/recording-scope.d.ts
+declare const RECORDING_SCOPE_VALUES: readonly ['app', 'device', 'system'];
+type RecordingScope = (typeof RECORDING_SCOPE_VALUES)[number];
+//#endregion
+//#region src/contracts/client-observability.d.ts
+type PerfOptions = DeviceCommandBaseOptions & {
+  area?: PerfArea;
+  subject?: PerfSubject;
+  action?: PerfAction;
+  kind?: PerfKind;
+  template?: string;
+  out?: string;
+  tracePath?: string;
 };
-type ReplaySuiteTestSkipReason = 'skipped-by-filter';
-type ReplaySuiteAttemptFailure = {
-  attempt: number;
-  message: string;
-  durationMs?: number;
+type LogsOptions = AgentDeviceRequestOverrides & {
+  action?: LogAction;
+  message?: string;
+  restart?: boolean;
 };
-type ReplaySuiteTestPassed = {
-  file: string;
-  title?: string;
-  session: string;
-  status: 'passed';
-  durationMs: number;
-  finalAttemptDurationMs?: number;
-  attempts: number;
-  artifactsDir?: string;
-  replayed: number;
-  healed: number;
-  warnings?: string[];
-  attemptFailures?: ReplaySuiteAttemptFailure[];
-  shardIndex?: number;
-  shardCount?: number;
-  deviceId?: string;
-  deviceName?: string;
-  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
+type EventsOptions = AgentDeviceRequestOverrides & {
+  cursor?: string;
+  limit?: number;
 };
-type ReplaySuiteTestFailed = {
-  file: string;
-  title?: string;
-  session: string;
-  status: 'failed';
-  durationMs: number;
-  attempts: number;
-  artifactsDir?: string;
-  error: DaemonError;
-  shardIndex?: number;
-  shardCount?: number;
-  deviceId?: string;
-  deviceName?: string;
-  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
+type NetworkOptions = DeviceCommandBaseOptions & {
+  action?: 'dump' | 'log';
+  limit?: number;
+  include?: NetworkIncludeMode;
 };
-type ReplaySuiteTestSkipped = {
-  file: string;
-  title?: string;
-  status: 'skipped';
-  durationMs: 0;
-  reason: ReplaySuiteTestSkipReason;
-  message: string;
+type AudioOptions = DeviceCommandBaseOptions & {
+  action?: 'probe';
+  probeAction?: 'start' | 'status' | 'stop';
+  durationMs?: number;
+  bucketMs?: number;
 };
-type ReplaySuiteTestResult = ReplaySuiteTestPassed | ReplaySuiteTestFailed | ReplaySuiteTestSkipped;
-type ReplaySuiteResult = {
-  total: number;
-  executed: number;
-  passed: number;
-  failed: number;
-  skipped: number;
-  notRun: number;
-  durationMs: number;
-  failures: ReplaySuiteTestFailed[];
-  tests: ReplaySuiteTestResult[];
-  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
+type RecordOptions = AgentDeviceRequestOverrides & {
+  action: 'start' | 'stop';
+  path?: string;
+  fps?: number;
+  maxSize?: number;
+  quality?: RecordingExportQuality;
+  hideTouches?: boolean;
+  recordingScope?: RecordingScope;
+};
+type TraceOptions = AgentDeviceRequestOverrides & {
+  action: 'start' | 'stop';
+  path?: string;
 };
 //#endregion
-//#region src/core/command-descriptor/command-result.d.ts
-/**
- * The additive typed-result spine (ADR-0008, Phase 1 step 6).
- *
- * Maps a command name to the per-command result type from `src/contracts/*`. It
- * is SEEDED, not exhaustive: a command is listed here only once its accurate,
- * closed result shape lives in the contracts layer. Commands whose daemon
- * handler spreads dynamic/Record data (screenshot overlays, gesture
- * visualization, perf, logs, …) are deliberately omitted rather than given an
- * invented shape.
- *
- * Batches 1-2 wired `boot` / `shutdown` / `viewport` and the navigation/action
- * commands `home` / `back` / `orientation` / `app-switcher` alongside the seed
- * interaction quartet. Batch 3 adds `clipboard` (a closed `read`/`write` union) and
- * `appstate` (a closed `platform` union — Apple session state with the iOS-only
- * device locators, or Android package/activity). Batch 4 adds `keyboard` (a
- * closed flat shape). Batch 5 adds the compact daemon projections for `wait`,
- * `prepare`, `push`, and `trigger-app-event`. Each entry is grounded in a
- * re-read of the handler's literal return; see the per-type docstrings.
- */
-interface CommandResultMap {
-  press: PressCommandResponseData;
-  click: ClickCommandResponseData;
-  fill: FillCommandResponseData;
-  longpress: LongPressCommandResponseData;
-  find: FindCommandResponseData;
-  boot: BootCommandResult;
-  shutdown: ShutdownCommandResult;
-  viewport: ViewportCommandResult;
-  home: HomeCommandResult;
-  back: BackCommandResult;
-  orientation: OrientationCommandResult;
-  'app-switcher': AppSwitcherCommandResult;
-  clipboard: ClipboardCommandResult;
-  appstate: AppStateCommandResult;
-  keyboard: KeyboardCommandResult;
-  'tv-remote': TvRemoteCommandResult;
-  wait: WaitCommandResult;
-  prepare: PrepareCommandResult;
-  push: PushCommandResult;
-  'trigger-app-event': TriggerAppEventCommandResult;
-  doctor: DoctorCommandResult;
-  diff: DiffSnapshotCommandResult;
-  replay: ReplayCommandResult;
-  test: ReplaySuiteResult;
-  record: RecordingCommandResult;
-  trace: TraceCommandResult;
-}
-/**
- * The typed result for a command named `N`. Seeded commands resolve to their
- * contract result type from {@link CommandResultMap}; every other (unmigrated)
- * command falls back to the untyped `Record<string, unknown>` bag. That default
- * branch is what keeps the mapping total over every command name, so consumers
- * can switch to `CommandResult<Name>` without first migrating every command.
- */
-type CommandResult<N extends string> = N extends keyof CommandResultMap ? CommandResultMap[N] : Record<string, unknown>;
-//#endregion
-//#region src/contracts/cloud-artifacts.d.ts
-declare const CLOUD_ARTIFACT_KINDS: readonly ['video', 'appium-log', 'device-log', 'automation-log', 'provider-session', 'raw'];
-type CloudArtifactKind = (typeof CLOUD_ARTIFACT_KINDS)[number];
-type CloudArtifactAvailability = 'ready' | 'pending' | 'unavailable' | 'expired';
-type CloudArtifact = {
-  provider: string;
-  kind: CloudArtifactKind;
-  name: string;
-  url?: string;
-  providerSessionId?: string;
-  providerArtifactId?: string;
-  contentType?: string;
-  extension?: string;
-  availability?: CloudArtifactAvailability;
-  metadata?: Record<string, unknown>;
-};
-type CloudArtifactsStatus = 'ready' | 'pending' | 'unavailable';
-type CloudArtifactsResult = {
-  provider: string;
-  status: CloudArtifactsStatus;
-  cloudArtifacts: CloudArtifact[];
-  providerSessionId?: string;
-  message?: string;
-};
-type DaemonArtifactInventoryEntry = {
-  id: string;
-  artifactType?: DaemonArtifactType;
-  filename: string;
-  mimeType: string;
-  sizeBytes: number;
-  createdAt: string;
-  expiresAt: string;
-};
-type DaemonArtifactsResult = {
-  source: 'daemon';
-  status: 'ready';
-  artifacts: DaemonArtifactInventoryEntry[];
-  message?: string;
+//#region src/contracts/client-replay.d.ts
+type ReplayRunOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+  path: string;
+  runtime?: SessionRuntimeHints;
+  /**
+   * @deprecated ADR 0012 migration step 6: `--update` no longer rewrites
+   * the script. Accepted for backward compatibility; every divergence
+   * already carries ranked selector suggestions regardless of this flag.
+   */
+  update?: boolean;
+  /** @deprecated Use backend: 'maestro'. */
+  maestro?: boolean;
+  backend?: string;
+  env?: string[];
+  timeoutMs?: number;
+  /**
+   * ADR 0012 decision 4 / migration step 5: resume at this 1-based plan
+   * step, skipping `1..resumeFrom-1` without executing them. Requires
+   * `resumePlanDigest` from the divergence report that reported this
+   * step as the failure. `replay` only — `test` has no resume fields.
+   */
+  resumeFrom?: number;
+  /** The `resume.planDigest` from the divergence report `resumeFrom` came from. */
+  resumePlanDigest?: string;
+  /**
+   * ADR 0012 decision 6, R1/R6: arms agent-supervised re-record repair
+   * from this replay attempt onward. Optional string value is the healed
+   * `.ad`'s output path; absent one, it defaults to the `<path>` sibling
+   * `<stem>.healed.ad` when the repair ends with `close --save-script`.
+   */
+  saveScript?: boolean | string;
+  /** #1258: overwrite an existing --save-script target instead of refusing. Alias: --overwrite. */
+  force?: boolean;
 };
-type AgentArtifactsResult = CloudArtifactsResult | DaemonArtifactsResult;
-type CloudProviderSessionResult = {
-  provider?: string;
-  providerSessionId?: string;
-  cloudArtifacts?: CloudArtifactsResult;
-} & Record<string, unknown>;
-//#endregion
-//#region src/client/client-types.d.ts
-type AgentDeviceDaemonTransport = (req: Omit<DaemonRequest, 'token'>) => Promise<DaemonResponse>;
-type AgentDeviceClientConfig = RemoteConnectionProfileFields & CloudProviderProfileFields & {
-  session?: string;
-  lockPolicy?: DaemonLockPolicy;
-  lockPlatform?: PlatformSelector;
-  requestId?: string;
-  sessionIsolation?: SessionIsolationMode;
-  leaseBackend?: LeaseBackend;
-  leaseTtlMs?: number;
+type ReplayTestOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+  paths: string[];
   runtime?: SessionRuntimeHints;
-  cwd?: string;
-  debug?: boolean;
-  cost?: boolean;
-  responseLevel?: ResponseLevel;
-  iosXctestrunFile?: string;
-  iosXctestDerivedDataPath?: string;
-  iosXctestEnvDir?: string;
+  update?: boolean;
+  /** @deprecated Use backend: 'maestro'. */
+  maestro?: boolean;
+  backend?: string;
+  env?: string[];
+  failFast?: boolean;
+  timeoutMs?: number;
+  retries?: number;
+  recordVideo?: boolean;
+  artifactsDir?: string;
+  /** @deprecated Use the CLI --reporter junit:<path> or --report-junit <path>. */
+  reportJunit?: string;
+  shardAll?: number;
+  shardSplit?: number;
 };
-type AgentDeviceRequestOverrides = Pick<AgentDeviceClientConfig, 'session' | 'lockPolicy' | 'lockPlatform' | 'requestId' | 'daemonBaseUrl' | 'daemonAuthToken' | 'daemonTransport' | 'daemonServerMode' | 'tenant' | 'sessionIsolation' | 'runId' | 'leaseId' | 'leaseBackend' | 'leaseProvider' | 'deviceKey' | 'clientId' | 'providerApp' | 'providerOsVersion' | 'providerProject' | 'providerBuild' | 'providerSessionName' | 'awsProjectArn' | 'awsDeviceArn' | 'awsAppArn' | 'awsRegion' | 'awsInteractionMode' | 'leaseTtlMs' | 'cwd' | 'debug' | 'cost' | 'responseLevel' | 'iosXctestrunFile' | 'iosXctestDerivedDataPath' | 'iosXctestEnvDir'>;
-type AgentDeviceIdentifiers = {
-  session?: string;
-  deviceId?: string;
-  deviceName?: string;
-  udid?: string;
-  serial?: string;
-  appId?: string;
-  appBundleId?: string;
-  package?: string;
+type BatchStep = {
+  command: string;
+  input: Record<string, unknown>;
+  runtime?: SessionRuntimeHints;
 };
-type AgentDeviceSelectionOptions = {
-  platform?: PlatformSelector;
-  target?: DeviceTarget;
-  device?: string;
-  udid?: string;
-  serial?: string;
-  iosSimulatorDeviceSet?: string;
-  androidDeviceAllowlist?: string;
+type BatchRunOptions = AgentDeviceRequestOverrides & {
+  steps: BatchStep[];
+  onError?: 'stop';
+  maxSteps?: number;
+  out?: string;
 };
-type AgentDeviceDevice = {
-  platform: PublicPlatform;
-  target: DeviceTarget;
-  kind: DeviceKind;
-  id: string;
-  name: string;
-  booted?: boolean;
-  /**
-   * Additive Apple-OS discriminant (iPhone/iPad/tvOS/visionOS/macOS). Present only for
-   * Apple devices; `platform` still carries the leaf (`ios`/`macos`).
-   */
-  appleOs?: AppleOS;
-  identifiers: AgentDeviceIdentifiers;
-  ios?: {
-    udid: string;
-  };
-  android?: {
-    serial: string;
-  };
-  vega?: {
-    serial: string;
-  };
+//#endregion
+//#region src/contracts/client-request.d.ts
+type CommandRequestResult = DaemonResponseData;
+//#endregion
+//#region src/contracts/client-selector-read.d.ts
+/**
+ * #1271 stage 2 (ADR 0012 amendment): `get`/`is`/`find` are observation-only
+ * and excluded from a repair-armed heal by default. `record` forces this
+ * action through (the corrective-read case); `noRecord` continues to opt the
+ * action out entirely. Mutually exclusive.
+ */
+type RecordControlOptions = {
+  noRecord?: boolean;
+  record?: boolean;
 };
-type AgentDeviceCapabilitiesResult = {
-  device: AgentDeviceDevice;
-  availableCommands: string[];
+type GetOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & ElementTarget & RecordControlOptions & {
+  format: 'text' | 'attrs';
 };
-type AgentDeviceSessionDevice = {
-  platform: PublicPlatform;
-  target: DeviceTarget;
-  id: string;
-  name: string;
-  /**
-   * Additive Apple-OS discriminant (iPhone/iPad/tvOS/visionOS/macOS). Present only for
-   * Apple devices; `platform` still carries the leaf (`ios`/`macos`).
-   */
-  appleOs?: AppleOS;
-  identifiers: AgentDeviceIdentifiers;
-  ios?: {
-    udid: string;
-    simulatorSetPath?: string | null;
-  };
-  android?: {
-    serial: string;
-  };
-  vega?: {
-    serial: string;
-  };
+type IsTextPredicateOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & RecordControlOptions & {
+  predicate: 'text';
+  selector: string;
+  value: string;
 };
-type AgentDeviceSession = {
-  name: string;
-  createdAt: number;
-  sessionStateDir?: string;
-  runnerLogPath?: string;
-  device: AgentDeviceSessionDevice;
-  identifiers: AgentDeviceIdentifiers;
+type IsStatePredicateOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & RecordControlOptions & {
+  predicate: 'visible' | 'hidden' | 'exists' | 'editable' | 'selected' | 'focused';
+  selector: string;
+  value?: never;
 };
-type StartupPerfSample = {
-  durationMs: number;
-  measuredAt: string;
-  method: string;
-  appTarget?: string;
-  appBundleId?: string;
+type IsOptions = IsTextPredicateOptions | IsStatePredicateOptions;
+type FindBaseOptions = DeviceCommandBaseOptions & FindSnapshotCommandOptions & RecordControlOptions & {
+  locator?: FindLocator;
+  query: string;
+  first?: boolean;
+  last?: boolean;
 };
+type FindOptions = (FindBaseOptions & {
+  action?: 'click' | 'focus' | 'exists' | 'getText' | 'getAttrs';
+}) | (FindBaseOptions & {
+  action: 'wait';
+  timeoutMs?: number;
+}) | (FindBaseOptions & {
+  action: 'fill' | 'type';
+  value: string;
+});
+//#endregion
+//#region src/contracts/client-session.d.ts
 type SessionCloseResult = {
   session: string;
   shutdown?: TargetShutdownResult;
@@ -997,222 +653,41 @@ type SessionSaveScriptResult = {
   actionCount: number;
   identifiers: AgentDeviceIdentifiers;
 };
-type CloudArtifactsOptions = AgentDeviceRequestOverrides & {
-  provider?: string;
-  providerSessionId?: string;
-};
-type AppInstallOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
-  app?: string;
-  appPath: string;
-};
-type AppDeployOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
-  app: string;
-  appPath: string;
-};
-type AppDeployResult = {
-  app: string;
-  appPath: string;
-  platform: PublicPlatform;
-  appId?: string;
-  bundleId?: string;
-  package?: string;
-  identifiers: AgentDeviceIdentifiers;
-};
-type AppOpenOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+//#endregion
+//#region src/contracts/client-settings.d.ts
+type PermissionTarget = 'camera' | 'microphone' | 'photos' | 'contacts' | 'contacts-limited' | 'notifications' | 'calendar' | 'location' | 'location-always' | 'media-library' | 'motion' | 'reminders' | 'siri' | 'accessibility' | 'screen-recording' | 'input-monitoring';
+type SettingsUpdateOptions = (DeviceCommandBaseOptions & {
+  setting: 'clear-app-state';
+  state: 'clear';
   app?: string;
-  url?: string;
-  surface?: SessionSurface;
-  activity?: string;
-  launchConsole?: string;
-  launchArgs?: string[];
-  relaunch?: boolean;
-  saveScript?: boolean | string;
-  /** #1258: overwrite an existing --save-script target instead of refusing. Alias: --overwrite. */
-  force?: boolean;
-  deviceHub?: boolean;
-  testIme?: boolean;
-  noRecord?: boolean;
-  runtime?: SessionRuntimeHints;
-};
-type AppOpenResult = {
-  session: string;
-  warnings?: string[];
-  sessionStateDir?: string;
-  runnerLogPath?: string;
-  requestLogPath?: string;
-  eventLogPath?: string;
-  appName?: string;
-  appBundleId?: string;
-  appId?: string;
-  startup?: StartupPerfSample;
-  runtime?: SessionRuntimeHints;
-  device?: AgentDeviceSessionDevice;
-  identifiers: AgentDeviceIdentifiers;
-};
-type AppCloseOptions = AgentDeviceRequestOverrides & {
-  app?: string;
-  shutdown?: boolean;
-  saveScript?: boolean | string;
-  /** #1258: overwrite an existing --save-script target instead of refusing. Alias: --overwrite. */
-  force?: boolean;
-};
-type AppCloseResult = {
-  session: string;
-  closedApp?: string;
-  shutdown?: TargetShutdownResult;
-  /**
-   * #1258: absolute path of the committed session/healed script when this close
-   * published one (`close --save-script`, or a repair-armed session's finalize)
-   * — so a client that requested publication learns where the file landed.
-   */
-  savedScript?: string;
-  identifiers: AgentDeviceIdentifiers;
-};
-type AppInstallFromSourceOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
-  source: DaemonInstallSource;
-  retainPaths?: boolean;
-  retentionMs?: number;
-};
-type AppInstallFromSourceResult = {
-  appName?: string;
-  appId?: string;
-  bundleId?: string;
-  packageName?: string;
-  launchTarget: string;
-  installablePath?: string;
-  archivePath?: string;
-  materializationId?: string;
-  materializationExpiresAt?: string;
-  identifiers: AgentDeviceIdentifiers;
-};
-type AppListOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
-  appsFilter?: AppsFilter;
-};
-type MaterializationReleaseOptions = AgentDeviceRequestOverrides & {
-  materializationId: string;
-};
-type MaterializationReleaseResult = {
-  released: boolean;
-  materializationId: string;
-  identifiers: AgentDeviceIdentifiers;
-};
-type Lease = {
-  leaseId: string;
-  tenantId: string;
-  runId: string;
-  backend: LeaseBackend;
-  leaseProvider?: string;
-  deviceKey?: string;
-  clientId?: string;
-  createdAt?: number;
-  heartbeatAt?: number;
-  expiresAt?: number;
-};
-type LeaseOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
-  ttlMs?: number;
-};
-type LeaseAllocateOptions = LeaseOptions & {
-  tenant: string;
-  runId: string;
-  leaseBackend?: LeaseBackend;
-  leaseProvider?: string;
-  provider?: string;
-  deviceKey?: string;
-  clientId?: string;
-};
-type LeaseScopedOptions = LeaseOptions & {
-  tenant?: string;
-  runId?: string;
-  leaseId: string;
-  leaseBackend?: LeaseBackend;
-  leaseProvider?: string;
-  provider?: string;
-  deviceKey?: string;
-  clientId?: string;
-};
-type MetroPrepareOptions = {
-  projectRoot?: string;
-  kind?: MetroPrepareKind;
-  publicBaseUrl?: string;
-  proxyBaseUrl?: string;
-  bearerToken?: string;
-  bridgeScope?: MetroBridgeScope;
-  launchUrl?: string;
-  companionProfileKey?: string;
-  companionConsumerKey?: string;
-  port?: number;
-  listenHost?: string;
-  statusHost?: string;
-  startupTimeoutMs?: number;
-  probeTimeoutMs?: number;
-  reuseExisting?: boolean;
-  installDependenciesIfNeeded?: boolean;
-  runtimeFilePath?: string;
-  logPath?: string;
-};
-type MetroPrepareResult = PrepareMetroRuntimeResult;
-type MetroReloadOptions = {
-  metroHost?: string;
-  metroPort?: number;
-  bundleUrl?: string;
-  timeoutMs?: number;
-};
-type MetroReloadResult = ReloadMetroResult;
-type CaptureSnapshotOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
-  interactiveOnly?: boolean;
-  depth?: number;
-  scope?: string;
-  raw?: boolean;
-  forceFull?: boolean;
-  timeoutMs?: number;
-  /**
-   * #1271 stage 2 (ADR 0012 amendment): `snapshot` is observation-only and
-   * excluded from a repair-armed heal by default; `record` forces it
-   * through. Mutually exclusive with `noRecord`.
-   */
-  noRecord?: boolean;
-  record?: boolean;
-};
-type CaptureSnapshotResult = {
-  nodes: SnapshotNode[];
-  truncated: boolean;
-  appName?: string;
-  appBundleId?: string;
-  visibility?: SnapshotVisibility;
-  unchanged?: SnapshotUnchanged;
-  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
-  identifiers: AgentDeviceIdentifiers;
-  /**
-   * ADR 0014: the response-level ref-frame epoch the plain node refs were minted
-   * from. A ref-issuing snapshot carries it ONCE (nodes stay plain `@e12` for the
-   * token budget); pair a ref with it (`@e12~s<refsGeneration>`) before a mutation.
-   */
-  refsGeneration?: number;
-  /**
-   * Digest response view only: a capped list of `{ ref, label? }` pairs taken
-   * from the full `nodes` tree so the MCP layer can still pin refs when the
-   * default-level `nodes` payload is intentionally omitted.
-   */
-  refs?: Array<{
-    ref: string;
-    label?: string;
-  }>;
-} & PublicSnapshotCaptureAnnotations;
-type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
-  path?: string;
-  overlayRefs?: boolean;
-  pixelDensity?: number;
-  fullscreen?: boolean;
-  maxSize?: number;
-  stabilize?: boolean;
-  normalizeStatusBar?: boolean;
-  surface?: SessionSurface;
-};
-type CaptureScreenshotResult = ScreenshotResultData & {
-  path: string;
-  identifiers: AgentDeviceIdentifiers;
-};
-type DeviceCommandBaseOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions;
+}) | (DeviceCommandBaseOptions & {
+  setting: 'wifi' | 'airplane' | 'location';
+  state: 'on' | 'off';
+}) | (DeviceCommandBaseOptions & {
+  setting: 'location';
+  state: 'set';
+  latitude: number;
+  longitude: number;
+}) | (DeviceCommandBaseOptions & {
+  setting: 'animations';
+  state: 'on' | 'off';
+}) | (DeviceCommandBaseOptions & {
+  setting: 'appearance';
+  state: 'light' | 'dark' | 'toggle';
+}) | (DeviceCommandBaseOptions & {
+  setting: 'faceid' | 'touchid';
+  state: 'match' | 'nonmatch' | 'enroll' | 'unenroll';
+}) | (DeviceCommandBaseOptions & {
+  setting: 'fingerprint';
+  state: 'match' | 'nonmatch';
+}) | (DeviceCommandBaseOptions & {
+  setting: 'permission';
+  state: 'grant' | 'deny' | 'reset';
+  permission: PermissionTarget;
+  mode?: 'full' | 'limited';
+});
+//#endregion
+//#region src/contracts/client-system.d.ts
 type WaitCommandTarget = {
   durationMs: number;
   text?: never;
@@ -1260,9 +735,6 @@ type AlertCommandOptions = DeviceCommandBaseOptions & {
   timeoutMs?: number;
 };
 type AppStateCommandOptions = DeviceCommandBaseOptions;
-type OrientationCommandOptions = DeviceCommandBaseOptions & NavigationCommandOptions<'orientation'>;
-/** @deprecated Renamed to `OrientationCommandOptions`. Retained until the next major. */
-type RotateCommandOptions = OrientationCommandOptions;
 type KeyboardCommandOptions = DeviceCommandBaseOptions & {
   action?: 'status' | 'dismiss' | 'enter' | 'return';
 };
@@ -1287,343 +759,632 @@ type ViewportCommandOptions = DeviceCommandBaseOptions & {
   width: number;
   height: number;
 };
-type NonNavigationCommandClient = {
-  wait: (options: WaitCommandOptions) => Promise<CommandResult<'wait'>>;
-  alert: (options?: AlertCommandOptions) => Promise<CommandRequestResult>;
-  appState: (options?: AppStateCommandOptions) => Promise<CommandResult<'appstate'>>;
-  keyboard: (options?: KeyboardCommandOptions) => Promise<CommandResult<'keyboard'>>;
-  clipboard: (options: ClipboardCommandOptions) => Promise<CommandResult<'clipboard'>>;
-  reactNative: (options: ReactNativeCommandOptions) => Promise<CommandRequestResult>;
-  doctor: (options?: DoctorCommandOptions) => Promise<CommandResult<'doctor'>>;
-  /**
-   * JSON prepare results include timing.additiveParts for additive wall-clock phases.
-   * Top-level buildMs/connectMs/healthCheckMs are diagnostics and may overlap.
-   */
-  prepare: (options: PrepareCommandOptions) => Promise<CommandResult<'prepare'>>;
-  viewport: (options: ViewportCommandOptions) => Promise<CommandResult<'viewport'>>;
+//#endregion
+//#region src/contracts/navigation.d.ts
+/**
+ * Closed results of the navigation/global action commands. Each mirrors the
+ * dispatch handler's literal return EXACTLY (src/core/dispatch.ts
+ * `DISPATCH_HANDLERS`): a fixed `action` discriminant plus the always-present
+ * `successText` message (the handlers always pass a non-empty message, so it is
+ * required here). The handlers spread nothing else, so the shapes are closed —
+ * consistent with the `viewport` contract, the generic-dispatch Android
+ * dialog-recovery `warning` annotation is intentionally not part of the contract.
+ */
+/** `home` — `{ action: 'home', message: 'Home' }`. */
+type HomeCommandResult = {
+  action: 'home';
+  message: string;
 };
-type AgentDeviceCommandClient = ProjectedNavigationCommandClient<DeviceCommandBaseOptions> & NonNavigationCommandClient & DeprecatedCommandClient;
-/** Renamed command methods retained for existing consumers until the next major. */
-type DeprecatedCommandClient = {
-  /**
-   * @deprecated Renamed to `orientation`. Delegates to it and returns the legacy
-   * `action: 'rotate'` response contract. Retained until the next major version.
-   */
-  rotate: (options: RotateCommandOptions) => Promise<RotateCommandResult>;
+/** `back` — `{ action: 'back', mode, message: 'Back' }`; `mode` defaults to `'in-app'`. */
+type BackCommandResult = {
+  action: 'back';
+  mode: BackMode;
+  message: string;
 };
-type SelectorSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'scope' | 'raw'>;
-type FindSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'raw'>;
-type PointTarget = {
-  x: number;
-  y: number;
-  ref?: never;
-  selector?: never;
-  label?: never;
+/** `orientation` — `{ action: 'orientation', orientation, message: 'Rotated to <orientation>' }`. */
+type OrientationCommandResult = {
+  action: 'orientation';
+  orientation: DeviceRotation;
+  message: string;
 };
-type RefTarget = {
-  ref: string;
-  label?: string;
-  x?: never;
-  y?: never;
-  selector?: never;
+/**
+ * @deprecated The `rotate` command was renamed to `orientation`. This is the
+ * legacy response contract (`action: 'rotate'`) that shipped in v0.18/v0.19,
+ * retained for existing SDK consumers until the next major version. New code
+ * should use {@link OrientationCommandResult}.
+ */
+type RotateCommandResult = {
+  action: 'rotate';
+  orientation: DeviceRotation;
+  message: string;
 };
-type SelectorTarget = {
-  selector: string;
-  x?: never;
-  y?: never;
-  ref?: never;
-  label?: never;
-};
-type InteractionTarget = PointTarget | RefTarget | SelectorTarget;
-type ElementTarget = RefTarget | SelectorTarget;
-type RepeatedPressOptions = {
-  count?: number;
-  intervalMs?: number;
-  holdMs?: number;
-  jitterPx?: number;
-  doubleTap?: boolean;
-};
-type DeviceBootOptions = DeviceCommandBaseOptions & {
-  headless?: boolean;
-};
-type DeviceShutdownOptions = DeviceCommandBaseOptions;
-type AppPushOptions = DeviceCommandBaseOptions & {
-  app: string;
-  payload: string | JsonObject;
-};
-type AppTriggerEventOptions = DeviceCommandBaseOptions & {
-  event: string;
-  payload?: JsonObject;
-};
-type CaptureDiffOptions = DeviceCommandBaseOptions & Pick<CaptureSnapshotOptions, 'interactiveOnly' | 'depth' | 'scope' | 'raw'> & {
-  kind: 'snapshot';
-  out?: string;
-};
-/**
- * Opt-in (#1101): after the action, wait for the UI to go quiet and return the
- * settled diff vs the pre-action tree (`settle` on the result) in the same
- * response. Best-effort — never fails the action. `settleQuietMs` tunes the
- * quiet window (default 500ms); `timeoutMs` bounds the settle wait (default
- * 10s) when `settle` is true. A bare `timeoutMs` without `settle` is ignored
- * for compatibility; `settleQuietMs` still requires `settle`.
- */
-type SettleCommandOptions = {
-  settle?: boolean;
-  settleQuietMs?: number;
-  timeoutMs?: number;
-};
-type ClickOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions & SettleCommandOptions & {
-  button?: ClickButton;
-  /**
-   * Opt-in (#1047): return cheap post-action evidence (AX digest, node counts,
-   * changedFromBefore) in the response instead of requiring a follow-up
-   * snapshot to confirm the action had an effect.
-   */
-  verify?: boolean;
-};
-type PressOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions & SettleCommandOptions & {
-  verify?: boolean;
+/** `app-switcher` — `{ action: 'app-switcher', message: 'Opened app switcher' }`. */
+type AppSwitcherCommandResult = {
+  action: 'app-switcher';
+  message: string;
 };
-type LongPressOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & SettleCommandOptions & {
+/** `tv-remote` — `{ action: 'tv-remote', button, durationMs?, message }`. */
+type TvRemoteCommandResult = {
+  action: 'tv-remote';
+  button: TvRemoteButton;
   durationMs?: number;
+  message: string;
 };
-type SwipeOptions = DeviceCommandBaseOptions & {
-  from: {
-    x: number;
-    y: number;
-  };
-  to: {
-    x: number;
-    y: number;
-  };
-  count?: number;
-  pauseMs?: number;
-  pattern?: SwipePattern;
-};
-type PanOptions = DeviceCommandBaseOptions & {
-  x: number;
-  y: number;
-  dx: number;
-  dy: number;
-  pointerCount?: GesturePointerCount;
-  durationMs?: number;
+//#endregion
+//#region src/commands/command-contract.d.ts
+type JsonSchema = {
+  type?: string | readonly string[];
+  description?: string;
+  properties?: Record<string, JsonSchema>;
+  required?: readonly string[];
+  additionalProperties?: boolean | JsonSchema;
+  items?: JsonSchema;
+  prefixItems?: readonly JsonSchema[];
+  oneOf?: readonly JsonSchema[];
+  enum?: readonly unknown[];
+  const?: unknown;
+  minimum?: number;
+  maximum?: number;
 };
-type FlingOptions = DeviceCommandBaseOptions & {
-  direction: ScrollDirection;
-  x: number;
-  y: number;
-  distance?: number;
+type ExecutableCommandProjection<ClientMethod extends string = string> = {
+  clientMethod: ClientMethod;
+  outputSchema: JsonSchema;
 };
-type SwipeGestureOptions = DeviceCommandBaseOptions & {
-  preset: SwipePreset;
+//#endregion
+//#region src/commands/system/navigation-projection.d.ts
+declare const navigationCommandProjectionType: unique symbol;
+type NavigationCommandProjection<Options, Result, Required extends boolean, ClientMethod extends string> = ExecutableCommandProjection<ClientMethod> & {
+  readonly [navigationCommandProjectionType]?: {
+    options: Options;
+    result: Result;
+    required: Required;
+  };
 };
-type FocusOptions = DeviceCommandBaseOptions & {
-  x: number;
-  y: number;
+declare const NAVIGATION_COMMAND_PROJECTIONS: {
+  readonly back: NavigationCommandProjection<{
+    mode?: BackMode;
+  }, BackCommandResult, false, "back">;
+  readonly home: NavigationCommandProjection<{}, HomeCommandResult, false, "home">;
+  readonly orientation: NavigationCommandProjection<{
+    orientation: DeviceRotation;
+  }, OrientationCommandResult, true, "orientation">;
+  readonly 'app-switcher': NavigationCommandProjection<{}, AppSwitcherCommandResult, false, "appSwitcher">;
+  readonly 'tv-remote': NavigationCommandProjection<{
+    button: TvRemoteButton;
+    durationMs?: number;
+  }, TvRemoteCommandResult, true, "tvRemote">;
 };
-type TypeTextOptions = DeviceCommandBaseOptions & {
-  text: string;
-  delayMs?: number;
+type NavigationCommandName = keyof typeof NAVIGATION_COMMAND_PROJECTIONS;
+type NavigationCommandOptions<Name extends NavigationCommandName> = (typeof NAVIGATION_COMMAND_PROJECTIONS)[Name] extends NavigationCommandProjection<infer Options, unknown, boolean, string> ? Options : never;
+type ProjectedNavigationCommandMethod<BaseOptions, Projection> = Projection extends NavigationCommandProjection<infer Options, infer Result, infer Required, string> ? Required extends true ? (options: BaseOptions & Options) => Promise<Result> : (options?: BaseOptions & Options) => Promise<Result> : never;
+type ProjectedNavigationCommandClient<BaseOptions> = { [Name in NavigationCommandName as (typeof NAVIGATION_COMMAND_PROJECTIONS)[Name]['clientMethod']]: ProjectedNavigationCommandMethod<BaseOptions, (typeof NAVIGATION_COMMAND_PROJECTIONS)[Name]>; };
+//#endregion
+//#region src/contracts/debug-symbols.d.ts
+type DebugSymbolsOptions = {
+  action?: 'symbols';
+  artifact: string;
+  dsym?: string;
+  searchPath?: string;
+  out?: string;
+  cwd?: string;
 };
-type FillOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & SettleCommandOptions & {
-  text: string;
-  delayMs?: number;
-  /** Publish this fill value as `${VAR}` when script recording is armed. */
-  recordAs?: string;
-  verify?: boolean;
+type DebugSymbolsImage = {
+  name: string;
+  uuid: string;
+  arch?: string;
+  dsymPath: string;
+  binaryPath: string;
 };
-type ScrollOptions = DeviceCommandBaseOptions & {
-  direction: ScrollInputDirection;
-  amount?: number;
-  pixels?: number;
-  durationMs?: number;
+type DebugSymbolsCrashFrame = {
+  index: number;
+  image: string;
+  address: string;
+  symbol?: string;
 };
-type PinchOptions = DeviceCommandBaseOptions & {
-  scale: number;
-  x?: number;
-  y?: number;
+type DebugSymbolsCrashSummary = {
+  format: 'ips' | 'text';
+  appName?: string;
+  bundleId?: string;
+  version?: string;
+  incident?: string;
+  timestamp?: string;
+  exceptionType?: string;
+  exceptionCodes?: string;
+  terminationReason?: string;
+  crashedThread?: number;
+  topFrames: DebugSymbolsCrashFrame[];
+  findings: string[];
 };
-type RotateGestureOptions = DeviceCommandBaseOptions & {
-  degrees: number;
-  x?: number;
-  y?: number;
+type DebugSymbolsResult = {
+  kind: 'debugSymbols';
+  platform: 'apple';
+  artifactPath: string;
+  outPath: string;
+  crash: DebugSymbolsCrashSummary;
+  matchedImages: DebugSymbolsImage[];
+  symbolicatedFrames: number;
+  skippedImages: number;
+  warnings?: string[];
+  message: string;
 };
-type TransformGestureOptions = DeviceCommandBaseOptions & TransformGestureParams;
+//#endregion
+//#region src/contracts/device.d.ts
 /**
- * #1271 stage 2 (ADR 0012 amendment): `get`/`is`/`find` are observation-only
- * and excluded from a repair-armed heal by default. `record` forces this
- * action through (the corrective-read case); `noRecord` continues to opt the
- * action out entirely. Mutually exclusive.
+ * Closed result of the `boot` command. Mirrors the daemon handler's only
+ * success return EXACTLY (src/daemon/handlers/session-state.ts) — the fixed
+ * object literal `{ platform, target, device, id, kind, booted }` plus the
+ * additive `appleOs` discriminant, emitted only for Apple devices.
  */
-type RecordControlOptions = {
-  noRecord?: boolean;
-  record?: boolean;
+type BootCommandResult = {
+  platform: PublicPlatform;
+  target: DeviceTarget;
+  /** Human-readable device name (`device.name`). */
+  device: string;
+  /** Stable device id (`device.id`). */
+  id: string;
+  kind: DeviceKind;
+  /** Always `true` on the success path. */
+  booted: true;
+  /**
+   * Additive Apple-OS discriminant (`device.appleOs`): iPhone/iPad/tvOS/visionOS/macOS.
+   * Present only for Apple devices; absent for non-Apple platforms. `platform` stays the
+   * leaf (`ios`/`macos`) — this is an extra field, not a replacement.
+   */
+  appleOs?: AppleOS;
 };
-type GetOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & ElementTarget & RecordControlOptions & {
-  format: 'text' | 'attrs';
+/**
+ * Closed result of the `shutdown` command. Mirrors the daemon handler's success
+ * return EXACTLY (src/daemon/handlers/session-state.ts) — the fixed object
+ * literal `{ platform, target, device, id, kind, shutdown }` plus the additive
+ * `appleOs` discriminant (Apple devices only). The `shutdown` field is the raw
+ * {@link TargetShutdownResult} from `shutdownDeviceTarget`.
+ */
+type ShutdownCommandResult = {
+  platform: PublicPlatform;
+  target: DeviceTarget;
+  /** Human-readable device name (`device.name`). */
+  device: string;
+  /** Stable device id (`device.id`). */
+  id: string;
+  kind: DeviceKind;
+  shutdown: TargetShutdownResult;
+  /**
+   * Additive Apple-OS discriminant (`device.appleOs`): iPhone/iPad/tvOS/visionOS/macOS.
+   * Present only for Apple devices; absent for non-Apple platforms. `platform` stays the
+   * leaf (`ios`/`macos`) — this is an extra field, not a replacement.
+   */
+  appleOs?: AppleOS;
 };
-type IsTextPredicateOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & RecordControlOptions & {
-  predicate: 'text';
-  selector: string;
-  value: string;
+//#endregion
+//#region src/contracts/viewport.d.ts
+/**
+ * Closed result of the `viewport` command. Mirrors the dispatch handler's return
+ * EXACTLY (src/core/dispatch.ts `handleViewportCommand`) — `{ width, height }`
+ * plus the always-present `successText` message. The generic dispatch path
+ * returns this object unchanged (viewport has no Android dialog guard, so no
+ * `warning` is ever appended), so the shape is intentionally closed.
+ */
+type ViewportCommandResult = {
+  width: number;
+  height: number;
+  message: string;
 };
-type IsStatePredicateOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & RecordControlOptions & {
-  predicate: 'visible' | 'hidden' | 'exists' | 'editable' | 'selected' | 'focused';
-  selector: string;
-  value?: never;
+//#endregion
+//#region src/contracts/clipboard.d.ts
+/**
+ * Closed result of the `clipboard` command. Mirrors the dispatch handler's
+ * literal return EXACTLY (src/core/dispatch.ts `handleClipboardCommand`): a
+ * discriminated union on `action`. `read` returns the clipboard `text`; `write`
+ * reports the written `textLength` plus the `successText` message. The handler
+ * spreads nothing else, so each branch is closed.
+ */
+type ClipboardCommandResult = {
+  action: 'read';
+  text: string;
+} | {
+  action: 'write';
+  textLength: number;
+  message: string;
 };
-type IsOptions = IsTextPredicateOptions | IsStatePredicateOptions;
-type FindBaseOptions = DeviceCommandBaseOptions & FindSnapshotCommandOptions & RecordControlOptions & {
-  locator?: FindLocator;
-  query: string;
-  first?: boolean;
-  last?: boolean;
+//#endregion
+//#region src/contracts/app-state.d.ts
+/**
+ * Closed result of the `appstate` command, grounded in the daemon handler's
+ * success returns (src/daemon/handlers/session-state.ts `handleAppStateCommand`).
+ * A discriminated union on `platform`:
+ *  - Apple (`ios` / `macos`) session state, with iOS-only device locators that
+ *    the previous hand-written mirror omitted; and
+ *  - Android foreground `package` / `activity`.
+ *
+ * The handler returns one of these fixed objects (errors take the `ok: false`
+ * path), so each branch is closed.
+ */
+type AppStateCommandResult = {
+  platform: 'ios' | 'macos';
+  appName: string;
+  appBundleId?: string;
+  source: 'session';
+  surface: SessionSurface;
+  /** iOS only — the session device's UDID. */
+  device_udid?: string;
+  /** iOS only — the simulator set path, or `null` when unknown. */
+  ios_simulator_device_set?: string | null;
+} | {
+  platform: 'android';
+  package: string;
+  activity: string;
 };
-type FindOptions = (FindBaseOptions & {
-  action?: 'click' | 'focus' | 'exists' | 'getText' | 'getAttrs';
-}) | (FindBaseOptions & {
-  action: 'wait';
-  timeoutMs?: number;
-}) | (FindBaseOptions & {
-  action: 'fill' | 'type';
-  value: string;
-});
-type ReplayRunOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
-  path: string;
-  runtime?: SessionRuntimeHints;
-  /**
-   * @deprecated ADR 0012 migration step 6: `--update` no longer rewrites
-   * the script. Accepted for backward compatibility; every divergence
-   * already carries ranked selector suggestions regardless of this flag.
-   */
-  update?: boolean;
-  /** @deprecated Use backend: 'maestro'. */
-  maestro?: boolean;
-  backend?: string;
-  env?: string[];
-  timeoutMs?: number;
-  /**
-   * ADR 0012 decision 4 / migration step 5: resume at this 1-based plan
-   * step, skipping `1..resumeFrom-1` without executing them. Requires
-   * `resumePlanDigest` from the divergence report that reported this
-   * step as the failure. `replay` only — `test` has no resume fields.
-   */
-  resumeFrom?: number;
-  /** The `resume.planDigest` from the divergence report `resumeFrom` came from. */
-  resumePlanDigest?: string;
+//#endregion
+//#region src/contracts/keyboard.d.ts
+/**
+ * Closed result of the `keyboard` command, grounded in the dispatch handlers'
+ * literal returns (src/core/dispatch.ts `handleAndroidKeyboardCommand` /
+ * `handleIosKeyboardCommand`).
+ *
+ * `platform` and `action` are always present; the remaining fields appear per
+ * branch (Android `status`/`dismiss` carry the keyboard-state fields; `enter`
+ * and iOS `dismiss` carry a `message`). It is kept as a flat closed shape rather
+ * than a five-way `platform`×`action` union because the per-branch field sets
+ * overlap heavily and the underlying Android keyboard-state types live in the
+ * platform layer (below the public contract). The `Record` index signature of
+ * the previous hand-written mirror is dropped, and the spurious `| null`s are
+ * removed (the handler never returns `null` for these).
+ */
+type KeyboardCommandResult = {
+  platform: 'android' | 'ios';
+  action: 'status' | 'dismiss' | 'enter';
+  visible?: boolean;
+  wasVisible?: boolean;
+  dismissed?: boolean;
+  attempts?: number;
+  inputType?: string;
+  type?: 'text' | 'number' | 'email' | 'phone' | 'password' | 'datetime' | 'unknown';
+  inputMethodPackage?: string;
+  focusedPackage?: string;
+  focusedResourceId?: string;
+  inputOwner?: 'app' | 'ime' | 'unknown';
+  message?: string;
+};
+//#endregion
+//#region src/contracts/wait.d.ts
+/**
+ * Public daemon result for `wait`. The runtime-local result carries a `kind`
+ * discriminant, but `toDaemonWaitData` intentionally projects the normal daemon
+ * payload to this compact shape. The direct iOS selector fast path may still
+ * include `kind: 'selector'` additively.
+ */
+type WaitCommandResult = {
+  waitedMs: number;
+  kind?: 'selector';
+  text?: string;
+  selector?: string;
+  captures?: number;
+  nodeCount?: number;
+  hint?: string;
+  warning?: string;
+};
+//#endregion
+//#region src/contracts/prepare.d.ts
+type PrepareIosRunnerCacheKind = 'exact' | 'restore-key' | 'miss' | 'external';
+type PrepareIosRunnerArtifactState = 'valid' | 'rebuilt';
+type PrepareIosRunnerTiming = {
+  totalMs: number;
+  additiveParts: {
+    buildMs?: number;
+    connectAfterBuildMs: number;
+    healthCheckMs: number;
+  };
+  containment: {
+    connectMs?: ['buildMs'];
+    healthCheckMs: [];
+  };
+  note: string;
+};
+/**
+ * Public daemon result for `prepare ios-runner`. The runner-local prepare result
+ * is projected by `prepareIosRunnerResponseData` with device identity and timing
+ * guidance before it reaches the client.
+ */
+type PrepareCommandResult = {
+  action: 'ios-runner';
+  platform: PublicPlatform;
+  deviceId: string;
+  deviceName: string;
+  kind: DeviceKind;
+  durationMs: number;
+  runner: JsonObject;
+  cache?: PrepareIosRunnerCacheKind;
+  artifact?: PrepareIosRunnerArtifactState;
+  buildMs?: number;
+  connectMs: number;
+  healthCheckMs: number;
+  xctestrunPath?: string;
+  recoveryReason?: string;
+  failureReason?: string;
+  timing: PrepareIosRunnerTiming;
+  message: string;
+};
+//#endregion
+//#region src/contracts/push.d.ts
+type PushCommandResult = {
+  platform: 'ios';
+  bundleId: string;
+  message: string;
+} | {
+  platform: 'android';
+  package: string;
+  action: string;
+  extrasCount: number;
+  message: string;
+};
+//#endregion
+//#region src/contracts/app-events.d.ts
+type TriggerAppEventCommandResult = {
+  event: string;
+  eventUrl: string;
+  transport: 'deep-link';
+  message: string;
+};
+//#endregion
+//#region src/contracts/doctor.d.ts
+type DoctorStatus = 'pass' | 'warn' | 'fail' | 'info';
+type DoctorKind = 'auto' | 'react-native' | 'expo' | 'repack';
+type DoctorCheck = {
+  id: string;
+  status: DoctorStatus;
+  summary: string;
+  hint?: string;
+  command?: string;
+  evidence?: Record<string, unknown>;
+};
+type DoctorCommandResult = {
+  status: DoctorStatus;
+  summary: string;
+  kind: DoctorKind;
+  platform?: PlatformSelector;
+  target?: DeviceTarget;
+  targetApp?: string;
+  metro?: {
+    host: string;
+    port: number;
+  };
+  checks: DoctorCheck[];
+};
+//#endregion
+//#region src/snapshot/snapshot-diff.d.ts
+type SnapshotDiffLine = {
+  kind: 'added' | 'removed' | 'unchanged';
+  text: string;
   /**
-   * ADR 0012 decision 6, R1/R6: arms agent-supervised re-record repair
-   * from this replay attempt onward. Optional string value is the healed
-   * `.ad`'s output path; absent one, it defaults to the `<path>` sibling
-   * `<stem>.healed.ad` when the repair ends with `close --save-script`.
+   * Plain ref body (`e12`) of the CURRENT-tree node behind an added line.
+   * Only populated with `withRefs` (interaction `--settle`, #1101) so the
+   * `diff` command's wire shape stays byte-identical. Removed/unchanged lines
+   * never carry it: a removed line's ref names a node of the replaced tree.
    */
-  saveScript?: boolean | string;
-  /** #1258: overwrite an existing --save-script target instead of refusing. Alias: --overwrite. */
-  force?: boolean;
+  ref?: string;
 };
-type ReplayTestOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
-  paths: string[];
-  runtime?: SessionRuntimeHints;
-  update?: boolean;
-  /** @deprecated Use backend: 'maestro'. */
-  maestro?: boolean;
-  backend?: string;
-  env?: string[];
-  failFast?: boolean;
-  timeoutMs?: number;
-  retries?: number;
-  recordVideo?: boolean;
-  artifactsDir?: string;
-  /** @deprecated Use the CLI --reporter junit:<path> or --report-junit <path>. */
-  reportJunit?: string;
-  shardAll?: number;
-  shardSplit?: number;
+type SnapshotDiffSummary = {
+  additions: number;
+  removals: number;
+  unchanged: number;
+};
+//#endregion
+//#region src/contracts/diff.d.ts
+type DiffSnapshotCommandResult = {
+  mode: 'snapshot';
+  baselineInitialized: boolean;
+  summary: SnapshotDiffSummary;
+  lines: SnapshotDiffLine[];
+  warnings?: string[];
+};
+//#endregion
+//#region src/contracts/recording.d.ts
+type RecordingAppIdentity = {
+  bundleId: string;
+  name?: string;
+};
+type RecordingStartCommandResult = {
+  recording: 'started';
+  outPath: string;
+  sessionStateDir: string;
+  recordingBackend?: string;
+  recordingScope?: RecordingScope;
+  recordOnlySession?: boolean;
+  activeSessionApp?: RecordingAppIdentity;
+  showTouches: boolean;
+};
+type RecordingStopCommandResult = {
+  recording: 'stopped';
+  outPath: string;
+  telemetryPath?: string;
+  artifacts: DaemonArtifact[];
+  recordingBackend?: string;
+  recordingScope?: RecordingScope;
+  recordOnlySession?: boolean;
+  activeSessionApp?: RecordingAppIdentity;
+  durationMs: number;
+  showTouches: boolean;
+  warning?: string;
+  overlayWarning?: string;
+  chunks?: Array<{
+    index: number;
+    path: string;
+  }>;
 };
-type BatchStep = {
-  command: string;
-  input: Record<string, unknown>;
-  runtime?: SessionRuntimeHints;
+type RecordingCommandResult = RecordingStartCommandResult | RecordingStopCommandResult;
+type TraceCommandResult = {
+  trace: 'started';
+  outPath: string;
+} | {
+  trace: 'stopped';
+  outPath: string;
 };
-type BatchRunOptions = AgentDeviceRequestOverrides & {
-  steps: BatchStep[];
-  onError?: 'stop';
-  maxSteps?: number;
-  out?: string;
+//#endregion
+//#region src/contracts/replay.d.ts
+type ReplayCommandResult = {
+  replayed: number;
+  healed: number;
+  session: string;
+  /**
+   * True iff `session` still exists in the daemon's session store when the
+   * response is built — i.e. the replayed script had no terminal `close`
+   * (ADR 0016's consumption contract). The client uses this, not script
+   * parsing, to decide whether an owned one-shot daemon must stay alive so
+   * the caller can keep addressing this session.
+   */
+  sessionActive: boolean;
+  artifactPaths: string[];
+  warnings?: string[];
+  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
+  message: string;
 };
-type PerfOptions = DeviceCommandBaseOptions & {
-  area?: PerfArea;
-  subject?: PerfSubject;
-  action?: PerfAction;
-  kind?: PerfKind;
-  template?: string;
-  out?: string;
-  tracePath?: string;
+type ReplaySuiteTestSkipReason = 'skipped-by-filter';
+type ReplaySuiteAttemptFailure = {
+  attempt: number;
+  message: string;
+  durationMs?: number;
 };
-type LogsOptions = AgentDeviceRequestOverrides & {
-  action?: LogAction;
-  message?: string;
-  restart?: boolean;
+type ReplaySuiteTestPassed = {
+  file: string;
+  title?: string;
+  session: string;
+  status: 'passed';
+  durationMs: number;
+  finalAttemptDurationMs?: number;
+  attempts: number;
+  artifactsDir?: string;
+  replayed: number;
+  healed: number;
+  warnings?: string[];
+  attemptFailures?: ReplaySuiteAttemptFailure[];
+  shardIndex?: number;
+  shardCount?: number;
+  deviceId?: string;
+  deviceName?: string;
+  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
 };
-type EventsOptions = AgentDeviceRequestOverrides & {
-  cursor?: string;
-  limit?: number;
+type ReplaySuiteTestFailed = {
+  file: string;
+  title?: string;
+  session: string;
+  status: 'failed';
+  durationMs: number;
+  attempts: number;
+  artifactsDir?: string;
+  error: DaemonError;
+  shardIndex?: number;
+  shardCount?: number;
+  deviceId?: string;
+  deviceName?: string;
+  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
 };
-type NetworkOptions = AgentDeviceRequestOverrides & {
-  action?: 'dump' | 'log';
-  limit?: number;
-  include?: NetworkIncludeMode;
+type ReplaySuiteTestSkipped = {
+  file: string;
+  title?: string;
+  status: 'skipped';
+  durationMs: 0;
+  reason: ReplaySuiteTestSkipReason;
+  message: string;
 };
-type AudioOptions = AgentDeviceRequestOverrides & {
-  action?: 'probe';
-  probeAction?: 'start' | 'status' | 'stop';
-  durationMs?: number;
-  bucketMs?: number;
+type ReplaySuiteTestResult = ReplaySuiteTestPassed | ReplaySuiteTestFailed | ReplaySuiteTestSkipped;
+type ReplaySuiteResult = {
+  total: number;
+  executed: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  notRun: number;
+  durationMs: number;
+  failures: ReplaySuiteTestFailed[];
+  tests: ReplaySuiteTestResult[];
+  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
 };
-type RecordOptions = AgentDeviceRequestOverrides & {
-  action: 'start' | 'stop';
-  path?: string;
-  fps?: number;
-  maxSize?: number;
-  quality?: RecordingExportQuality;
-  hideTouches?: boolean;
-  recordingScope?: RecordingScope;
+//#endregion
+//#region src/core/command-descriptor/command-result.d.ts
+/**
+ * The additive typed-result spine (ADR-0008, Phase 1 step 6).
+ *
+ * Maps a command name to the per-command result type from `src/contracts/*`. It
+ * is SEEDED, not exhaustive: a command is listed here only once its accurate,
+ * closed result shape lives in the contracts layer. Commands whose daemon
+ * handler spreads dynamic/Record data (screenshot overlays, gesture
+ * visualization, perf, logs, …) are deliberately omitted rather than given an
+ * invented shape.
+ *
+ * Batches 1-2 wired `boot` / `shutdown` / `viewport` and the navigation/action
+ * commands `home` / `back` / `orientation` / `app-switcher` alongside the seed
+ * interaction quartet. Batch 3 adds `clipboard` (a closed `read`/`write` union) and
+ * `appstate` (a closed `platform` union — Apple session state with the iOS-only
+ * device locators, or Android package/activity). Batch 4 adds `keyboard` (a
+ * closed flat shape). Batch 5 adds the compact daemon projections for `wait`,
+ * `prepare`, `push`, and `trigger-app-event`. Each entry is grounded in a
+ * re-read of the handler's literal return; see the per-type docstrings.
+ */
+interface CommandResultMap {
+  press: PressCommandResponseData;
+  click: ClickCommandResponseData;
+  fill: FillCommandResponseData;
+  longpress: LongPressCommandResponseData;
+  find: FindCommandResponseData;
+  boot: BootCommandResult;
+  shutdown: ShutdownCommandResult;
+  viewport: ViewportCommandResult;
+  home: HomeCommandResult;
+  back: BackCommandResult;
+  orientation: OrientationCommandResult;
+  'app-switcher': AppSwitcherCommandResult;
+  clipboard: ClipboardCommandResult;
+  appstate: AppStateCommandResult;
+  keyboard: KeyboardCommandResult;
+  'tv-remote': TvRemoteCommandResult;
+  wait: WaitCommandResult;
+  prepare: PrepareCommandResult;
+  push: PushCommandResult;
+  'trigger-app-event': TriggerAppEventCommandResult;
+  doctor: DoctorCommandResult;
+  diff: DiffSnapshotCommandResult;
+  replay: ReplayCommandResult;
+  test: ReplaySuiteResult;
+  record: RecordingCommandResult;
+  trace: TraceCommandResult;
+}
+/**
+ * The typed result for a command named `N`. Seeded commands resolve to their
+ * contract result type from {@link CommandResultMap}; every other (unmigrated)
+ * command falls back to the untyped `Record<string, unknown>` bag. That default
+ * branch is what keeps the mapping total over every command name, so consumers
+ * can switch to `CommandResult<Name>` without first migrating every command.
+ */
+type CommandResult<N extends string> = N extends keyof CommandResultMap ? CommandResultMap[N] : Record<string, unknown>;
+//#endregion
+//#region src/client/client-types.d.ts
+type OrientationCommandOptions = DeviceCommandBaseOptions & NavigationCommandOptions<'orientation'>;
+/** @deprecated Renamed to `OrientationCommandOptions`. Retained until the next major. */
+type RotateCommandOptions = OrientationCommandOptions;
+type NonNavigationCommandClient = {
+  wait: (options: WaitCommandOptions) => Promise<CommandResult<'wait'>>;
+  alert: (options?: AlertCommandOptions) => Promise<CommandRequestResult>;
+  appState: (options?: AppStateCommandOptions) => Promise<CommandResult<'appstate'>>;
+  keyboard: (options?: KeyboardCommandOptions) => Promise<CommandResult<'keyboard'>>;
+  clipboard: (options: ClipboardCommandOptions) => Promise<CommandResult<'clipboard'>>;
+  reactNative: (options: ReactNativeCommandOptions) => Promise<CommandRequestResult>;
+  doctor: (options?: DoctorCommandOptions) => Promise<CommandResult<'doctor'>>;
+  /**
+   * JSON prepare results include timing.additiveParts for additive wall-clock phases.
+   * Top-level buildMs/connectMs/healthCheckMs are diagnostics and may overlap.
+   */
+  prepare: (options: PrepareCommandOptions) => Promise<CommandResult<'prepare'>>;
+  viewport: (options: ViewportCommandOptions) => Promise<CommandResult<'viewport'>>;
 };
-type TraceOptions = AgentDeviceRequestOverrides & {
-  action: 'start' | 'stop';
-  path?: string;
+type AgentDeviceCommandClient = ProjectedNavigationCommandClient<DeviceCommandBaseOptions> & NonNavigationCommandClient & DeprecatedCommandClient;
+/** Renamed command methods retained for existing consumers until the next major. */
+type DeprecatedCommandClient = {
+  /**
+   * @deprecated Renamed to `orientation`. Delegates to it and returns the legacy
+   * `action: 'rotate'` response contract. Retained until the next major version.
+   */
+  rotate: (options: RotateCommandOptions) => Promise<RotateCommandResult>;
 };
-type PermissionTarget = 'camera' | 'microphone' | 'photos' | 'contacts' | 'contacts-limited' | 'notifications' | 'calendar' | 'location' | 'location-always' | 'media-library' | 'motion' | 'reminders' | 'siri' | 'accessibility' | 'screen-recording' | 'input-monitoring';
-type SettingsUpdateOptions = (DeviceCommandBaseOptions & {
-  setting: 'clear-app-state';
-  state: 'clear';
-  app?: string;
-}) | (DeviceCommandBaseOptions & {
-  setting: 'wifi' | 'airplane' | 'location';
-  state: 'on' | 'off';
-}) | (DeviceCommandBaseOptions & {
-  setting: 'location';
-  state: 'set';
-  latitude: number;
-  longitude: number;
-}) | (DeviceCommandBaseOptions & {
-  setting: 'animations';
-  state: 'on' | 'off';
-}) | (DeviceCommandBaseOptions & {
-  setting: 'appearance';
-  state: 'light' | 'dark' | 'toggle';
-}) | (DeviceCommandBaseOptions & {
-  setting: 'faceid' | 'touchid';
-  state: 'match' | 'nonmatch' | 'enroll' | 'unenroll';
-}) | (DeviceCommandBaseOptions & {
-  setting: 'fingerprint';
-  state: 'match' | 'nonmatch';
-}) | (DeviceCommandBaseOptions & {
-  setting: 'permission';
-  state: 'grant' | 'deny' | 'reset';
-  permission: PermissionTarget;
-  mode?: 'full' | 'limited';
-});
-type CommandRequestResult = DaemonResponseData;
 type AgentDeviceClient = {
   command: AgentDeviceCommandClient;
   devices: {