refactor: address review follow-ups

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

Author: thymikee

skills/agent-device/references/exploration.md

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

src/cli/commands/connection-runtime.ts

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

src/client-metro.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { sleep } from './utils/timeouts.ts';
 import { ensureMetroCompanion } from './client-metro-companion.ts';
 import type { MetroBridgeScope } from './client-metro-companion-contract.ts';
 import type {
@@ -215,7 +216,7 @@ function installDependenciesIfNeeded(
 }
 
 async function wait(ms: number): Promise<void> {
-  await new Promise((resolve) => setTimeout(resolve, ms));
+  await sleep(ms);
 }
 
 async function fetchText(

src/client-types.ts

@@ -11,6 +11,7 @@ import type { DeviceKind, DeviceTarget, Platform, PlatformSelector } from './uti
 import type { FindLocator } from './utils/finders.ts';
 import type { ScreenshotOverlayRef, SnapshotNode, SnapshotVisibility } from './utils/snapshot.ts';
 import type { MetroPrepareKind, PrepareMetroRuntimeResult } from './client-metro.ts';
+import type { MetroBridgeScope } from './client-metro-companion-contract.ts';
 
 export type { FindLocator } from './utils/finders.ts';
 
@@ -270,11 +271,7 @@ export type MetroPrepareOptions = {
   publicBaseUrl: string;
   proxyBaseUrl?: string;
   bearerToken?: string;
-  bridgeScope?: {
-    tenantId: string;
-    runId: string;
-    leaseId: string;
-  };
+  bridgeScope?: MetroBridgeScope;
   launchUrl?: string;
   companionProfileKey?: string;
   companionConsumerKey?: string;

src/core/dispatch.ts

@@ -13,7 +13,7 @@ import { getInteractor, type Interactor, type RunnerContext } from './interactor
 import { runIosRunnerCommand } from '../platforms/ios/runner-client.ts';
 import { runMacOsPressAction, runMacOsReadTextAction } from '../platforms/ios/macos-helper.ts';
 import { pushIosNotification } from '../platforms/ios/index.ts';
-import { snapshotLinux } from '../platforms/linux/index.ts';
+import { snapshotLinux } from '../platforms/linux/snapshot.ts';
 import { rightClickLinux, middleClickLinux } from '../platforms/linux/input-actions.ts';
 import type { SessionSurface } from './session-surface.ts';
 import { isDeepLinkTarget } from './open-target.ts';

src/daemon-client.ts

@@ -3,6 +3,7 @@ import http from 'node:http';
 import https from 'node:https';
 import fs from 'node:fs';
 import path from 'node:path';
+import { sleep } from './utils/timeouts.ts';
 import { AppError, toAppErrorCode } from './utils/errors.ts';
 import type {
   DaemonArtifact,
@@ -483,7 +484,7 @@ async function ensureDaemon(settings: DaemonClientSettings): Promise<DaemonInfo>
 
     // Detached daemon startup can race on busy CI hosts; retry when no metadata exists yet.
     if (!metadataState.hasInfo && !metadataState.hasLock) {
-      await sleepMs(150);
+      await sleep(150);
       continue;
     }
   }
@@ -509,15 +510,11 @@ async function waitForDaemonInfo(
   while (Date.now() - start < timeoutMs) {
     const info = readDaemonInfo(settings.paths.infoPath);
     if (info && (await canConnect(info, settings.transportPreference))) return info;
-    await new Promise((resolve) => setTimeout(resolve, 100));
+    await sleep(100);
   }
   return null;
 }
 
-async function sleepMs(ms: number): Promise<void> {
-  await new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 async function recoverDaemonLockHolder(paths: DaemonPaths): Promise<boolean> {
   const state = getDaemonMetadataState(paths);
   if (!state.hasLock || state.hasInfo) return false;

src/daemon/handlers/find.ts

@@ -1,4 +1,5 @@
 import { dispatchCommand, resolveTargetDevice } from '../../core/dispatch.ts';
+import { sleep } from '../../utils/timeouts.ts';
 import { findBestMatchesByLocator, parseFindArgs, type FindLocator } from '../../utils/finders.ts';
 import { centerOfRect, type SnapshotState } from '../../utils/snapshot.ts';
 import type { DaemonRequest, DaemonResponse } from '../types.ts';
@@ -200,7 +201,7 @@ async function handleFindWait(
       }
       return { ok: true, data: { found: true, waitedMs: Date.now() - start } };
     }
-    await new Promise((resolve) => setTimeout(resolve, 300));
+    await sleep(300);
   }
   return errorResponse('COMMAND_FAILED', 'find wait timed out');
 }

src/daemon/handlers/record-trace-android.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import { emitDiagnostic } from '../../utils/diagnostics.ts';
+import { sleep } from '../../utils/timeouts.ts';
 import type { DaemonResponse, SessionState } from '../types.ts';
 import { formatRecordTraceExecFailure } from '../record-trace-errors.ts';
 import type { RecordTraceDeps } from './record-trace-types.ts';
@@ -67,7 +68,7 @@ async function waitForAndroidProcessExit(
     if (!(await isAndroidProcessRunning(deps, deviceId, pid))) {
       return true;
     }
-    await new Promise((resolve) => setTimeout(resolve, ANDROID_PROCESS_EXIT_POLL_MS));
+    await sleep(ANDROID_PROCESS_EXIT_POLL_MS);
   }
   return !(await isAndroidProcessRunning(deps, deviceId, pid));
 }
@@ -96,7 +97,7 @@ async function waitForAndroidRemoteFileStability(
       stableCount = 0;
     }
     previousSize = currentSize;
-    await new Promise((resolve) => setTimeout(resolve, ANDROID_REMOTE_FILE_POLL_MS));
+    await sleep(ANDROID_REMOTE_FILE_POLL_MS);
   }
 }
 
@@ -128,7 +129,7 @@ async function waitForAndroidRecordingReady(
       return true;
     }
 
-    await new Promise((resolve) => setTimeout(resolve, ANDROID_REMOTE_FILE_POLL_MS));
+    await sleep(ANDROID_REMOTE_FILE_POLL_MS);
   }
 
   return false;
@@ -196,7 +197,7 @@ async function copyAndroidRecordingWithValidation(params: {
     }
 
     if (attempt < ANDROID_LOCAL_VIDEO_ATTEMPTS - 1) {
-      await new Promise((resolve) => setTimeout(resolve, ANDROID_LOCAL_VIDEO_RETRY_DELAY_MS));
+      await sleep(ANDROID_LOCAL_VIDEO_RETRY_DELAY_MS);
     }
   }
 

src/daemon/handlers/record-trace-recording.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { sleep } from '../../utils/timeouts.ts';
 import { resolveTargetDevice, type CommandFlags } from '../../core/dispatch.ts';
 import { isCommandSupportedOnDevice } from '../../core/capabilities.ts';
 import { ensureDeviceReady } from '../device-ready.ts';
@@ -81,7 +82,7 @@ async function waitForLocalRecordingSettleWindow(outPath: string): Promise<numbe
       return Date.now();
     }
 
-    await new Promise((resolve) => setTimeout(resolve, LOCAL_RECORDING_READY_POLL_MS));
+    await sleep(LOCAL_RECORDING_READY_POLL_MS);
   }
 
   return Date.now();

src/daemon/handlers/snapshot-alert.ts

@@ -1,4 +1,5 @@
 import { isCommandSupportedOnDevice } from '../../core/capabilities.ts';
+import { sleep } from '../../utils/timeouts.ts';
 import { runIosRunnerCommand } from '../../platforms/ios/runner-client.ts';
 import { runMacOsAlertAction } from '../../platforms/ios/macos-helper.ts';
 import { AppError } from '../../utils/errors.ts';
@@ -54,7 +55,7 @@ export async function handleAlertCommand(
         } catch {
           // keep waiting
         }
-        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+        await sleep(POLL_INTERVAL_MS);
       }
       return errorResponse('COMMAND_FAILED', 'alert wait timed out');
     }
@@ -73,7 +74,7 @@ export async function handleAlertCommand(
           const msg = String((err as { message?: unknown })?.message ?? '').toLowerCase();
           if (!msg.includes('alert not found') && !msg.includes('no alert')) break;
         }
-        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+        await sleep(POLL_INTERVAL_MS);
       }
       throw withAlertFallbackHint(lastError);
     }
@@ -101,7 +102,7 @@ export async function handleAlertCommand(
       } catch {
         // keep waiting
       }
-      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+      await sleep(POLL_INTERVAL_MS);
     }
     return errorResponse('COMMAND_FAILED', 'alert wait timed out');
   }
@@ -132,7 +133,7 @@ export async function handleAlertCommand(
         const msg = String((err as { message?: unknown })?.message ?? '').toLowerCase();
         if (!msg.includes('alert not found') && !msg.includes('no alert')) break;
       }
-      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+      await sleep(POLL_INTERVAL_MS);
     }
     // lastError is always set because ALERT_ACTION_RETRY_MS > 0
     throw withAlertFallbackHint(lastError);