agent-device 0.4.0 → 0.4.2

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -216,14 +216,20 @@ final class RunnerTests: XCTestCase {
   }
 
   private func executeOnMain(command: Command) throws -> Response {
-    let bundleId = command.appBundleId ?? currentBundleId ?? "com.apple.Preferences"
-    if currentBundleId != bundleId {
+    let normalizedBundleId = command.appBundleId?
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+    let requestedBundleId = (normalizedBundleId?.isEmpty == true) ? nil : normalizedBundleId
+    if let bundleId = requestedBundleId, currentBundleId != bundleId {
       let target = XCUIApplication(bundleIdentifier: bundleId)
       NSLog("AGENT_DEVICE_RUNNER_ACTIVATE bundle=%@ state=%d", bundleId, target.state.rawValue)
       // activate avoids terminating and relaunching the target app
       target.activate()
       currentApp = target
       currentBundleId = bundleId
+    } else if requestedBundleId == nil {
+      // Do not reuse stale bundle targets when the caller does not explicitly request one.
+      currentApp = nil
+      currentBundleId = nil
     }
     let activeApp = currentApp ?? app
     _ = activeApp.waitForExistence(timeout: 5)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
   "license": "MIT",
   "author": "Callstack",
@@ -26,7 +26,7 @@
     "prepack": "pnpm build:node && pnpm build:axsnapshot",
     "typecheck": "tsc -p tsconfig.json",
     "test": "node --test",
-    "test:unit": "node --test src/core/__tests__/*.test.ts src/daemon/__tests__/*.test.ts src/daemon/handlers/__tests__/*.test.ts src/platforms/**/__tests__/*.test.ts src/utils/**/__tests__/*.test.ts",
+    "test:unit": "node --test src/__tests__/*.test.ts src/core/__tests__/*.test.ts src/daemon/__tests__/*.test.ts src/daemon/handlers/__tests__/*.test.ts src/platforms/**/__tests__/*.test.ts src/utils/**/__tests__/*.test.ts",
     "test:smoke": "node --test test/integration/smoke-*.test.ts",
     "test:integration": "node --test test/integration/*.test.ts"
   },

package/skills/agent-device/SKILL.md

@@ -27,7 +27,7 @@ npx -y agent-device
 
 ## Core workflow
 
-1. Open app or deep link: `open [app|url]` (`open` handles target selection + boot/activation in the normal flow)
+1. Open app or deep link: `open [app|url] [url]` (`open` handles target selection + boot/activation in the normal flow)
 2. Snapshot: `snapshot` to get refs from accessibility tree
 3. Interact using refs (`click @ref`, `fill @ref "text"`)
 4. Re-snapshot after navigation/UI changes
@@ -39,13 +39,14 @@ npx -y agent-device
 
 ```bash
 agent-device boot                 # Ensure target is booted/ready without opening app
-agent-device boot --platform ios  # Boot iOS simulator/device target
+agent-device boot --platform ios  # Boot iOS target
 agent-device boot --platform android # Boot Android emulator/device target
-agent-device open [app|url]       # Boot device/simulator; optionally launch app or deep link URL
+agent-device open [app|url] [url] # Boot device/simulator; optionally launch app or deep link URL
 agent-device open [app] --relaunch # Terminate app process first, then launch (fresh runtime)
 agent-device open [app] --activity com.example/.MainActivity # Android: open specific activity (app targets only)
 agent-device open "myapp://home" --platform android          # Android deep link
-agent-device open "https://example.com" --platform ios       # iOS simulator deep link (device unsupported)
+agent-device open "https://example.com" --platform ios       # iOS deep link (opens in browser)
+agent-device open MyApp "myapp://screen/to" --platform ios   # iOS deep link in app context
 agent-device close [app]          # Close app or just end session
 agent-device reinstall <app> <path> # Uninstall + install app in one command
 agent-device session list         # List active sessions
@@ -101,10 +102,12 @@ iOS settings helpers are simulator-only.
 
 ```bash
 agent-device appstate
-agent-device apps --metadata --platform ios
-agent-device apps --metadata --platform android
 ```
 
+- Android: `appstate` reports live foreground package/activity.
+- iOS: `appstate` is session-scoped and reports the app tracked by the active session on the target device.
+- For iOS `appstate`, ensure a matching session exists (for example `open --session <name> --platform ios --device "<name>" <app>`).
+
 ### Interactions (use @refs from snapshot)
 
 ```bash
@@ -143,13 +146,16 @@ agent-device screenshot out.png
 
 ```bash
 agent-device open App --relaunch      # Fresh app process restart in the current session
-agent-device open App --save-script   # Save session script (.ad) on close
+agent-device open App --save-script   # Save session script (.ad) on close (default path)
+agent-device open App --save-script ./workflows/app-flow.ad  # Save to custom file path
 agent-device replay ./session.ad      # Run deterministic replay from .ad script
 agent-device replay -u ./session.ad   # Update selector drift and rewrite .ad script in place
 ```
 
 `replay` reads `.ad` recordings.
 `--relaunch` controls launch semantics; `--save-script` controls recording. Combine only when both are needed.
+`--save-script` path is a file path; parent directories are created automatically.
+For ambiguous bare values, use `--save-script=workflow.ad` or `./workflow.ad`.
 
 ### Trace logs (AX/XCTest)
 
@@ -164,9 +170,11 @@ agent-device trace stop ./trace.log    # Stop and move trace log
 
 ```bash
 agent-device devices
-agent-device apps --platform ios
-agent-device apps --platform android          # default: launchable only
-agent-device apps --platform android --all
+agent-device apps --platform ios              # iOS simulator + iOS device, includes default/system apps
+agent-device apps --platform ios --all        # explicit include-all (same as default)
+agent-device apps --platform ios --user-installed
+agent-device apps --platform android          # includes default/system apps
+agent-device apps --platform android --all    # explicit include-all (same as default)
 agent-device apps --platform android --user-installed
 ```
 
@@ -181,15 +189,16 @@ agent-device apps --platform android --user-installed
 - Prefer `snapshot -i` to reduce output size.
 - On iOS, `xctest` is the default and does not require Accessibility permission.
 - If XCTest returns 0 nodes (foreground app changed), treat it as an explicit failure and retry the flow/app state.
-- `open <app|url>` can be used within an existing session to switch apps or open deep links.
-- `open <app>` updates session app bundle context; URL opens do not set an app bundle id.
+- `open <app|url> [url]` can be used within an existing session to switch apps or open deep links.
+- `open <app>` updates session app bundle context; `open <app> <url>` opens a deep link on iOS.
 - Use `open <app> --relaunch` during React Native/Fast Refresh debugging when you need a fresh app process without ending the session.
 - If AX returns the Simulator window or empty tree, restart Simulator or use `--backend xctest`.
 - Use `--session <name>` for parallel sessions; avoid device contention.
 - Use `--activity <component>` on Android to launch a specific activity (e.g. TV apps with LEANBACK); do not combine with URL opens.
-- iOS deep-link opens are simulator-only.
+- On iOS devices, `http(s)://` URLs fall back to Safari automatically; custom scheme URLs require an active app in the session.
 - iOS physical-device runner requires Xcode signing/provisioning; optional overrides: `AGENT_DEVICE_IOS_TEAM_ID`, `AGENT_DEVICE_IOS_SIGNING_IDENTITY`, `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`.
-- For long first-run physical-device setup/build, increase daemon timeout: `AGENT_DEVICE_DAEMON_TIMEOUT_MS=180000` (or higher).
+- Default daemon request timeout is `45000`ms. For slow physical-device setup/build, increase `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (for example `120000`).
+- For daemon startup troubleshooting, follow stale metadata hints for `~/.agent-device/daemon.json` / `~/.agent-device/daemon.lock`.
 - Use `fill` when you want clear-then-type semantics.
 - Use `type` when you want to append/enter text without clearing.
 - On Android, prefer `fill` for important fields; it verifies entered text and retries once when IME reorders characters.

package/skills/agent-device/references/permissions.md

@@ -24,9 +24,14 @@ Use Automatic Signing in Xcode, or provide optional overrides:
 - `AGENT_DEVICE_IOS_SIGNING_IDENTITY`
 - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
 
-If first-run setup/build takes long, increase:
+If setup/build takes long, increase:
 
-- `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (for example `180000`)
+- `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (default `45000`, for example `120000`)
+
+If daemon startup fails with stale metadata hints, clean stale files and retry:
+
+- `~/.agent-device/daemon.json`
+- `~/.agent-device/daemon.lock`
 
 ## Simulator troubleshooting
 

package/skills/agent-device/references/session-management.md

@@ -14,8 +14,12 @@ Sessions isolate device context. A device can only be held by one session at a t
 - Name sessions semantically.
 - Close sessions when done.
 - Use separate sessions for parallel work.
-- In iOS sessions, use `open <app>` for simulator/device. `open <url>` is simulator-only.
+- In iOS sessions, use `open <app>`. `open <url>` opens deep links; on devices `http(s)://` opens Safari when no app is active, and custom schemes require an active app in the session.
+- In iOS sessions, `open <app> <url>` opens a deep link.
+- On iOS, `appstate` is session-scoped and requires a matching active session on the target device.
 - For dev loops where runtime state can persist (for example React Native Fast Refresh), use `open <app> --relaunch` to restart the app process in the same session.
+- Use `--save-script [path]` to record replay scripts on `close`; path is a file path and parent directories are created automatically.
+- For ambiguous bare `--save-script` values, prefer `--save-script=workflow.ad` or `./workflow.ad`.
 - For deterministic replay scripts, prefer selector-based actions and assertions.
 - Use `replay -u` to update selector drift during maintenance.
 

package/src/__tests__/cli-close.test.ts

@@ -0,0 +1,155 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runCli } from '../cli.ts';
+import { AppError } from '../utils/errors.ts';
+import type { DaemonResponse } from '../daemon-client.ts';
+
+class ExitSignal extends Error {
+  public readonly code: number;
+
+  constructor(code: number) {
+    super(`EXIT_${code}`);
+    this.code = code;
+  }
+}
+
+type RunResult = {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  daemonCalls: number;
+};
+
+async function runCliCapture(argv: string[]): Promise<RunResult> {
+  let daemonCalls = 0;
+  let stdout = '';
+  let stderr = '';
+  let code: number | null = null;
+
+  const originalExit = process.exit;
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+  (process as any).exit = ((nextCode?: number) => {
+    throw new ExitSignal(nextCode ?? 0);
+  }) as typeof process.exit;
+  (process.stdout as any).write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+  (process.stderr as any).write = ((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+
+  const sendToDaemon = async (): Promise<DaemonResponse> => {
+    daemonCalls += 1;
+    throw new AppError('COMMAND_FAILED', 'Failed to start daemon', {
+      infoPath: '/tmp/daemon.json',
+      hint: 'stale daemon info',
+    });
+  };
+
+  try {
+    await runCli(argv, { sendToDaemon });
+  } catch (error) {
+    if (error instanceof ExitSignal) code = error.code;
+    else throw error;
+  } finally {
+    process.exit = originalExit;
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+
+  return { code, stdout, stderr, daemonCalls };
+}
+
+async function runCliCaptureWithErrorDetails(
+  argv: string[],
+  details: Record<string, unknown>,
+  message = 'Failed to start daemon',
+): Promise<RunResult> {
+  let daemonCalls = 0;
+  let stdout = '';
+  let stderr = '';
+  let code: number | null = null;
+
+  const originalExit = process.exit;
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+  (process as any).exit = ((nextCode?: number) => {
+    throw new ExitSignal(nextCode ?? 0);
+  }) as typeof process.exit;
+  (process.stdout as any).write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+  (process.stderr as any).write = ((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+
+  const sendToDaemon = async (): Promise<DaemonResponse> => {
+    daemonCalls += 1;
+    throw new AppError('COMMAND_FAILED', message, details);
+  };
+
+  try {
+    await runCli(argv, { sendToDaemon });
+  } catch (error) {
+    if (error instanceof ExitSignal) code = error.code;
+    else throw error;
+  } finally {
+    process.exit = originalExit;
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+
+  return { code, stdout, stderr, daemonCalls };
+}
+
+test('close treats daemon startup failure as no-op', async () => {
+  const result = await runCliCapture(['close']);
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  assert.equal(result.stdout, '');
+  assert.equal(result.stderr, '');
+});
+
+test('close --json treats daemon startup failure as no-op success', async () => {
+  const result = await runCliCapture(['close', '--json']);
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  const payload = JSON.parse(result.stdout);
+  assert.equal(payload.success, true);
+  assert.equal(payload.data.closed, 'session');
+  assert.equal(payload.data.source, 'no-daemon');
+  assert.equal(result.stderr, '');
+});
+
+test('close treats lock-only daemon startup failure as no-op', async () => {
+  const result = await runCliCaptureWithErrorDetails(['close'], {
+    lockPath: '/tmp/daemon.lock',
+    hint: 'stale daemon lock',
+  });
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  assert.equal(result.stdout, '');
+  assert.equal(result.stderr, '');
+});
+
+test('close treats structured daemon startup failure as no-op without relying on message text', async () => {
+  const result = await runCliCaptureWithErrorDetails(
+    ['close'],
+    {
+      kind: 'daemon_startup_failed',
+      lockPath: '/tmp/daemon.lock',
+    },
+    'daemon bootstrap failed',
+  );
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  assert.equal(result.stdout, '');
+  assert.equal(result.stderr, '');
+});

package/src/__tests__/cli-help.test.ts

@@ -0,0 +1,102 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runCli } from '../cli.ts';
+import type { DaemonResponse } from '../daemon-client.ts';
+
+class ExitSignal extends Error {
+  public readonly code: number;
+
+  constructor(code: number) {
+    super(`EXIT_${code}`);
+    this.code = code;
+  }
+}
+
+type RunResult = {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  daemonCalls: number;
+};
+
+async function runCliCapture(argv: string[]): Promise<RunResult> {
+  let daemonCalls = 0;
+  let stdout = '';
+  let stderr = '';
+  let code: number | null = null;
+
+  const originalExit = process.exit;
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+  (process as any).exit = ((nextCode?: number) => {
+    throw new ExitSignal(nextCode ?? 0);
+  }) as typeof process.exit;
+  (process.stdout as any).write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+  (process.stderr as any).write = ((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+
+  const sendToDaemon = async (): Promise<DaemonResponse> => {
+    daemonCalls += 1;
+    return { ok: true, data: {} };
+  };
+
+  try {
+    await runCli(argv, { sendToDaemon });
+  } catch (error) {
+    if (error instanceof ExitSignal) code = error.code;
+    else throw error;
+  } finally {
+    process.exit = originalExit;
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+
+  return { code, stdout, stderr, daemonCalls };
+}
+
+test('help appstate prints command help and skips daemon dispatch', async () => {
+  const result = await runCliCapture(['help', 'appstate']);
+  assert.equal(result.code, 0);
+  assert.equal(result.daemonCalls, 0);
+  assert.match(result.stdout, /Show foreground app\/activity/);
+  assert.doesNotMatch(result.stdout, /Command flags:/);
+  assert.match(result.stdout, /Global flags:/);
+});
+
+test('appstate --help prints command help and skips daemon dispatch', async () => {
+  const result = await runCliCapture(['appstate', '--help']);
+  assert.equal(result.code, 0);
+  assert.equal(result.daemonCalls, 0);
+  assert.match(result.stdout, /Usage:\n  agent-device appstate/);
+  assert.match(result.stdout, /Global flags:/);
+});
+
+test('help unknown command prints error plus global usage and skips daemon dispatch', async () => {
+  const result = await runCliCapture(['help', 'not-a-command']);
+  assert.equal(result.code, 1);
+  assert.equal(result.daemonCalls, 0);
+  assert.match(result.stderr, /Error \(INVALID_ARGS\): Unknown command: not-a-command/);
+  assert.match(result.stdout, /Commands:/);
+  assert.match(result.stdout, /Flags:/);
+});
+
+test('unknown command --help prints error plus global usage and skips daemon dispatch', async () => {
+  const result = await runCliCapture(['not-a-command', '--help']);
+  assert.equal(result.code, 1);
+  assert.equal(result.daemonCalls, 0);
+  assert.match(result.stderr, /Error \(INVALID_ARGS\): Unknown command: not-a-command/);
+  assert.match(result.stdout, /Commands:/);
+});
+
+test('help rejects multiple positional commands and skips daemon dispatch', async () => {
+  const result = await runCliCapture(['help', 'appstate', 'extra']);
+  assert.equal(result.code, 1);
+  assert.equal(result.daemonCalls, 0);
+  assert.match(result.stderr, /Error \(INVALID_ARGS\): help accepts at most one command/);
+});

package/src/cli.ts

@@ -1,4 +1,4 @@
-import { parseArgs, toDaemonFlags, usage } from './utils/args.ts';
+import { parseArgs, toDaemonFlags, usage, usageForCommand } from './utils/args.ts';
 import { asAppError, AppError } from './utils/errors.ts';
 import { formatSnapshotText, printHumanError, printJson } from './utils/output.ts';
 import { readVersion } from './utils/version.ts';
@@ -8,7 +8,15 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-export async function runCli(argv: string[]): Promise<void> {
+type CliDeps = {
+  sendToDaemon: typeof sendToDaemon;
+};
+
+const DEFAULT_CLI_DEPS: CliDeps = {
+  sendToDaemon,
+};
+
+export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS): Promise<void> {
   const parsed = parseArgs(argv);
   for (const warning of parsed.warnings) {
     process.stderr.write(`Warning: ${warning}\n`);
@@ -19,9 +27,31 @@ export async function runCli(argv: string[]): Promise<void> {
     process.exit(0);
   }
 
-  if (parsed.flags.help || !parsed.command) {
+  const isHelpAlias = parsed.command === 'help';
+  const isHelpFlag = parsed.flags.help;
+  if (isHelpAlias || isHelpFlag) {
+    if (isHelpAlias && parsed.positionals.length > 1) {
+      printHumanError(new AppError('INVALID_ARGS', 'help accepts at most one command.'));
+      process.exit(1);
+    }
+    const helpTarget = isHelpAlias ? parsed.positionals[0] : parsed.command;
+    if (!helpTarget) {
+      process.stdout.write(`${usage()}\n`);
+      process.exit(0);
+    }
+    const commandHelp = usageForCommand(helpTarget);
+    if (commandHelp) {
+      process.stdout.write(commandHelp);
+      process.exit(0);
+    }
+    printHumanError(new AppError('INVALID_ARGS', `Unknown command: ${helpTarget}`));
+    process.stdout.write(`${usage()}\n`);
+    process.exit(1);
+  }
+
+  if (!parsed.command) {
     process.stdout.write(`${usage()}\n`);
-    process.exit(parsed.flags.help ? 0 : 1);
+    process.exit(1);
   }
 
   const { command, positionals, flags } = parsed;
@@ -34,7 +64,7 @@ export async function runCli(argv: string[]): Promise<void> {
       if (sub !== 'list') {
         throw new AppError('INVALID_ARGS', 'session only supports list');
       }
-      const response = await sendToDaemon({
+      const response = await deps.sendToDaemon({
         session: sessionName,
         command: 'session_list',
         positionals: [],
@@ -47,7 +77,7 @@ export async function runCli(argv: string[]): Promise<void> {
       return;
     }
 
-    const response = await sendToDaemon({
+    const response = await deps.sendToDaemon({
       session: sessionName,
       command: command!,
       positionals,
@@ -149,9 +179,6 @@ export async function runCli(argv: string[]): Promise<void> {
               const bundleId = app.bundleId ?? app.package;
               const name = app.name ?? app.label;
               if (name && bundleId) return `${name} (${bundleId})`;
-              if (bundleId && typeof app.launchable === 'boolean') {
-                return `${bundleId} (launchable=${app.launchable})`;
-              }
               if (bundleId) return String(bundleId);
               return JSON.stringify(app);
             }
@@ -169,7 +196,7 @@ export async function runCli(argv: string[]): Promise<void> {
           const pkg = (data as any)?.package;
           const activity = (data as any)?.activity;
           if (platform === 'ios') {
-            process.stdout.write(`Foreground app: ${appName ?? appBundleId}\n`);
+            process.stdout.write(`Foreground app: ${appName ?? appBundleId ?? 'unknown'}\n`);
             if (appBundleId) process.stdout.write(`Bundle: ${appBundleId}\n`);
             if (source) process.stdout.write(`Source: ${source}\n`);
             if (logTailStopper) logTailStopper();
@@ -190,6 +217,13 @@ export async function runCli(argv: string[]): Promise<void> {
     throw new AppError(response.error.code as any, response.error.message, response.error.details);
   } catch (err) {
     const appErr = asAppError(err);
+    if (command === 'close' && isDaemonStartupFailure(appErr)) {
+      if (flags.json) {
+        printJson({ success: true, data: { closed: 'session', source: 'no-daemon' } });
+      }
+      if (logTailStopper) logTailStopper();
+      return;
+    }
     if (flags.json) {
       printJson({
         success: false,
@@ -199,9 +233,6 @@ export async function runCli(argv: string[]): Promise<void> {
       printHumanError(appErr);
       if (flags.verbose) {
         try {
-          const fs = await import('node:fs');
-          const os = await import('node:os');
-          const path = await import('node:path');
           const logPath = path.join(os.homedir(), '.agent-device', 'daemon.log');
           if (fs.existsSync(logPath)) {
             const content = fs.readFileSync(logPath, 'utf8');
@@ -221,6 +252,13 @@ export async function runCli(argv: string[]): Promise<void> {
   }
 }
 
+function isDaemonStartupFailure(error: AppError): boolean {
+  if (error.code !== 'COMMAND_FAILED') return false;
+  if (error.details?.kind === 'daemon_startup_failed') return true;
+  if (!error.message.toLowerCase().includes('failed to start daemon')) return false;
+  return typeof error.details?.infoPath === 'string' || typeof error.details?.lockPath === 'string';
+}
+
 const isDirectRun = pathToFileURL(process.argv[1] ?? '').href === import.meta.url;
 if (isDirectRun) {
   runCli(process.argv.slice(2)).catch((err) => {
@@ -238,15 +276,23 @@ function startDaemonLogTail(): (() => void) | null {
     const interval = setInterval(() => {
       if (stopped) return;
       if (!fs.existsSync(logPath)) return;
-      const stats = fs.statSync(logPath);
-      if (stats.size <= offset) return;
-      const fd = fs.openSync(logPath, 'r');
-      const buffer = Buffer.alloc(stats.size - offset);
-      fs.readSync(fd, buffer, 0, buffer.length, offset);
-      fs.closeSync(fd);
-      offset = stats.size;
-      if (buffer.length > 0) {
-        process.stdout.write(buffer.toString('utf8'));
+      try {
+        const stats = fs.statSync(logPath);
+        if (stats.size < offset) offset = 0;
+        if (stats.size <= offset) return;
+        const fd = fs.openSync(logPath, 'r');
+        try {
+          const buffer = Buffer.alloc(stats.size - offset);
+          fs.readSync(fd, buffer, 0, buffer.length, offset);
+          offset = stats.size;
+          if (buffer.length > 0) {
+            process.stdout.write(buffer.toString('utf8'));
+          }
+        } finally {
+          fs.closeSync(fd);
+        }
+      } catch {
+        // Best-effort tailing should not crash CLI flow.
       }
     }, 200);
     return () => {

package/src/core/__tests__/capabilities.test.ts

@@ -33,7 +33,7 @@ test('iOS simulator-only commands reject iOS devices and Android', () => {
 });
 
 test('simulator-only iOS commands with Android support reject iOS devices', () => {
-  for (const cmd of ['apps', 'reinstall', 'record', 'settings', 'swipe']) {
+  for (const cmd of ['reinstall', 'record', 'settings', 'swipe']) {
     assert.equal(isCommandSupportedOnDevice(cmd, iosSimulator), true, `${cmd} on iOS sim`);
     assert.equal(isCommandSupportedOnDevice(cmd, iosDevice), false, `${cmd} on iOS device`);
     assert.equal(isCommandSupportedOnDevice(cmd, androidDevice), true, `${cmd} on Android`);
@@ -43,6 +43,7 @@ test('simulator-only iOS commands with Android support reject iOS devices', () =
 test('core commands support iOS simulator, iOS device, and Android', () => {
   for (const cmd of [
     'app-switcher',
+    'apps',
     'back',
     'boot',
     'click',

package/src/core/__tests__/dispatch-open.test.ts

@@ -0,0 +1,25 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { dispatchCommand } from '../dispatch.ts';
+import { AppError } from '../../utils/errors.ts';
+import type { DeviceInfo } from '../../utils/device.ts';
+
+test('dispatch open rejects URL as first argument when second URL is provided', async () => {
+  const device: DeviceInfo = {
+    platform: 'ios',
+    id: 'sim-1',
+    name: 'iPhone 15',
+    kind: 'simulator',
+    booted: true,
+  };
+
+  await assert.rejects(
+    () => dispatchCommand(device, 'open', ['myapp://first', 'myapp://second']),
+    (error: unknown) => {
+      assert.equal(error instanceof AppError, true);
+      assert.equal((error as AppError).code, 'INVALID_ARGS');
+      assert.match((error as AppError).message, /requires an app target as the first argument/i);
+      return true;
+    },
+  );
+});