fix: improve rn agent-device stability guidance (#519)

Author: thymikee

README.md

@@ -54,7 +54,7 @@ If you install skills separately, keep the CLI on `agent-device >= 0.14.0`. Olde
 ### AI Agent Entry Points
 
 - **Agent + terminal**: in Cursor, Codex, Claude Code, Windsurf, and similar clients, run `agent-device` in the integrated terminal. Start planning with `agent-device help workflow`; CLI help is authoritative.
-- **Skills or rules**: install the skill with `npx skills add callstackincubator/agent-device`, use the bundled [agent-device skill](skills/agent-device/SKILL.md), or mirror it as a thin project rule, so the agent checks the installed version and reads `agent-device help workflow` before acting.
+- **Skills or rules**: install the skill with `npx skills add callstackincubator/agent-device`, use the bundled [agent-device skill](skills/agent-device/SKILL.md), or mirror it as a thin project rule, so the agent checks the installed version and reads `agent-device help workflow` before acting. Use `agent-device help react-native` for React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence.
 - **MCP router**: use `agent-device mcp` when an MCP-aware client needs install, status, and version-matched help discovery. MCP is intentionally a thin router; device automation still runs through CLI commands.
 
 For client-specific setup, see [AI Agent Setup](https://incubator.callstack.com/agent-device/docs/agent-setup). For agent-readable docs, use [llms-full.txt](https://incubator.callstack.com/agent-device/llms-full.txt).

skills/agent-device/SKILL.md

@@ -25,6 +25,7 @@ Escalate only when relevant:
 
 ```bash
 agent-device help debugging
+agent-device help react-native
 agent-device help react-devtools
 agent-device help remote
 agent-device help macos

src/__tests__/client.test.ts

@@ -506,7 +506,7 @@ test('client capture.snapshot preserves visibility metadata from daemon response
     data: {
       nodes: [],
       truncated: false,
-      appBundleId: 'com.expensify.chat.dev',
+      appBundleId: 'com.agentdevice.tester',
       visibility: {
         partial: true,
         visibleNodeCount: 64,

src/__tests__/runtime-snapshot.test.ts

@@ -86,22 +86,14 @@ test('runtime diff snapshot initializes baseline when no previous snapshot exist
 });
 
 test('runtime snapshot emits filtered Android guidance from backend analysis', async () => {
-  const device = createAgentDevice({
-    backend: createSnapshotBackend(() => ({
-      nodes: [],
-      truncated: false,
-      backend: 'android',
-      analysis: {
-        rawNodeCount: 42,
-        maxDepth: 6,
-      },
-    })),
-    artifacts: createLocalArtifactAdapter(),
-    sessions: {
-      get: () => undefined,
-      set: () => {},
+  const device = createSnapshotOnlyDevice({
+    nodes: [],
+    truncated: false,
+    backend: 'android',
+    analysis: {
+      rawNodeCount: 42,
+      maxDepth: 6,
     },
-    policy: localCommandPolicy(),
   });
 
   const result = await device.capture.snapshot({
@@ -116,6 +108,99 @@ test('runtime snapshot emits filtered Android guidance from backend analysis', a
   ]);
 });
 
+test('runtime snapshot warns when Android hierarchy looks like a React Native overlay', async () => {
+  const device = createSnapshotOnlyDevice({
+    nodes: [
+      { ref: 'e1', index: 0, depth: 0, type: 'Text', label: 'LogBox' },
+      { ref: 'e2', index: 1, depth: 1, type: 'Text', label: 'Warnings' },
+      { ref: 'e3', index: 2, depth: 1, type: 'Button', label: 'Dismiss' },
+    ],
+    truncated: false,
+    backend: 'android',
+  });
+
+  const result = await device.capture.snapshot({ session: 'default', interactiveOnly: true });
+
+  assertReactNativeOverlayWarning(result.warnings);
+});
+
+test('runtime snapshot warns on collapsed Android React Native warning banners', async () => {
+  const device = createSnapshotOnlyDevice({
+    nodes: [
+      {
+        ref: 'e1',
+        index: 0,
+        depth: 0,
+        type: 'android.view.ViewGroup',
+        label: '!, Open debugger to view warnings.',
+      },
+      {
+        ref: 'e2',
+        index: 1,
+        depth: 1,
+        type: 'android.widget.TextView',
+        label: 'Open debugger to view warnings.',
+      },
+    ],
+    truncated: false,
+    backend: 'android',
+  });
+
+  const result = await device.capture.snapshot({ session: 'default', interactiveOnly: true });
+
+  assertReactNativeOverlayWarning(result.warnings);
+});
+
+test('runtime snapshot warns when iOS hierarchy looks like a React Native overlay', async () => {
+  const device = createSnapshotOnlyDevice({
+    nodes: [
+      {
+        ref: 'e1',
+        index: 0,
+        depth: 0,
+        type: 'XCUIElementTypeOther',
+        label: 'React Native RedBox',
+      },
+      {
+        ref: 'e2',
+        index: 1,
+        depth: 1,
+        type: 'XCUIElementTypeStaticText',
+        value: 'Runtime Error',
+      },
+      {
+        ref: 'e3',
+        index: 2,
+        depth: 1,
+        type: 'XCUIElementTypeButton',
+        identifier: 'Reload JS',
+      },
+    ],
+    truncated: false,
+    backend: 'xctest',
+  });
+
+  const result = await device.capture.snapshot({ session: 'default', interactiveOnly: true });
+
+  assertReactNativeOverlayWarning(result.warnings);
+});
+
+test('runtime snapshot does not warn for ordinary Android validation errors', async () => {
+  const device = createSnapshotOnlyDevice({
+    nodes: [
+      { ref: 'e1', index: 0, depth: 0, type: 'Text', label: 'Validation errors' },
+      { ref: 'e2', index: 1, depth: 1, type: 'Text', label: 'Required' },
+      { ref: 'e3', index: 2, depth: 1, type: 'Button', label: 'Submit order' },
+    ],
+    truncated: false,
+    backend: 'android',
+  });
+
+  const result = await device.capture.snapshot({ session: 'default', interactiveOnly: true });
+
+  assert.equal(result.warnings, undefined);
+});
+
 test('runtime snapshot stale-drop warning uses the runtime clock', async () => {
   const session = {
     name: 'default',
@@ -257,3 +342,20 @@ function createSnapshotBackend(
     captureSnapshot: async () => await captureSnapshot(),
   };
 }
+
+function createSnapshotOnlyDevice(result: BackendSnapshotResult) {
+  return createAgentDevice({
+    backend: createSnapshotBackend(() => result),
+    artifacts: createLocalArtifactAdapter(),
+    sessions: {
+      get: () => undefined,
+      set: () => {},
+    },
+    policy: localCommandPolicy(),
+  });
+}
+
+function assertReactNativeOverlayWarning(warnings: string[] | undefined) {
+  assert.equal(warnings?.length, 1);
+  assert.match(warnings[0] ?? '', /Possible React Native warning\/error overlay/);
+}

src/commands/capture-snapshot.ts

@@ -216,6 +216,12 @@ function buildSnapshotWarnings(params: {
     }
   }
 
+  if (hasReactNativeOverlay(params.snapshot.nodes)) {
+    warnings.push(
+      'Possible React Native warning/error overlay detected. Capture screenshot --overlay-refs, check react-devtools errors if connected, dismiss Dismiss/Close only if unrelated, re-snapshot, and report it.',
+    );
+  }
+
   const previousSnapshot = params.session?.snapshot;
   const isRecentSnapshot = previousSnapshot
     ? [params.capturedAt, params.runtimeNow].some((timestamp) => {
@@ -254,3 +260,16 @@ function isLikelyStaleSnapshotDrop(previousCount: number, currentCount: number):
   if (previousCount < 12) return false;
   return currentCount <= Math.floor(previousCount * 0.2);
 }
+
+function hasReactNativeOverlay(nodes: SnapshotNode[]): boolean {
+  const text = nodes
+    .map((node) =>
+      [node.label, node.value, node.identifier, node.type, node.role].filter(Boolean).join(' '),
+    )
+    .join('\n')
+    .toLowerCase();
+
+  return /\b(logbox|redbox|reload js|copy stack|component stack|call stack|runtime error|open debugger to view warnings)\b/.test(
+    text,
+  );
+}

src/core/__tests__/dispatch-type.test.ts

@@ -6,7 +6,7 @@ import { ANDROID_EMULATOR } from '../../__tests__/test-utils/device-fixtures.ts'
 
 test('dispatch type rejects ref-shaped first positional with a repair hint', async () => {
   await assert.rejects(
-    () => dispatchCommand(ANDROID_EMULATOR, 'type', ['@ref42', 'filed', 'the', 'expense']),
+    () => dispatchCommand(ANDROID_EMULATOR, 'type', ['@ref42', 'sent', 'the', 'update']),
     (error: unknown) =>
       error instanceof AppError &&
       error.code === 'INVALID_ARGS' &&

src/daemon/__tests__/network-log.test.ts

@@ -48,7 +48,7 @@ test('readRecentNetworkTraffic enriches Android GIBSDK URL lines with timing met
     [
       '03-31 17:43:32.564 V/GIBSDK  (17434): [NetworkAgent]: packet id 23911610 added, queue size: 1',
       '03-31 17:43:33.031 D/GIBSDK  (17434): [NetworkAgent] packet id 23911610 total elapsed request/response time, ms: 377; response code: 200;',
-      '03-31 17:43:33.031 D/GIBSDK  (17434): URL: https://www.expensify.com/api/fl?as=2.0.2816300925',
+      '03-31 17:43:33.031 D/GIBSDK  (17434): URL: https://api.example.com/v1/fixture?as=2.0.2816300925',
       '03-31 17:43:33.032 V/GIBSDK  (17434): [NetworkAgent]: packet id 23911610 sent successfully, 0 left in queue',
     ].join('\n'),
     'utf8',
@@ -64,7 +64,7 @@ test('readRecentNetworkTraffic enriches Android GIBSDK URL lines with timing met
 
   assert.equal(dump.exists, true);
   assert.equal(dump.entries.length, 1);
-  assert.equal(dump.entries[0]?.url, 'https://www.expensify.com/api/fl?as=2.0.2816300925');
+  assert.equal(dump.entries[0]?.url, 'https://api.example.com/v1/fixture?as=2.0.2816300925');
   assert.equal(dump.entries[0]?.timestamp, '03-31 17:43:33.031');
   assert.equal(dump.entries[0]?.status, 200);
   assert.equal(dump.entries[0]?.durationMs, 377);
@@ -83,7 +83,7 @@ test('readRecentNetworkTraffic tolerates interleaved Android lines within the pa
       '03-31 17:43:32.900 V/OtherTag (17434): unrelated line 3',
       '03-31 17:43:33.000 V/OtherTag (17434): unrelated line 4',
       '03-31 17:43:33.031 D/GIBSDK  (17434): [NetworkAgent] packet id 23911610 total elapsed request/response time, ms: 377; response code: 200;',
-      '03-31 17:43:33.032 D/GIBSDK  (17434): URL: https://www.expensify.com/api/fl?as=2.0.2816300925',
+      '03-31 17:43:33.032 D/GIBSDK  (17434): URL: https://api.example.com/v1/fixture?as=2.0.2816300925',
     ].join('\n'),
     'utf8',
   );
@@ -109,7 +109,7 @@ test('readRecentNetworkTraffic keeps Android packet enrichment disabled for Appl
     logPath,
     [
       '2026-03-31 17:43:33.031 response code: 200',
-      '2026-03-31 17:43:33.032 URL: https://www.expensify.com/api/fl?as=2.0.2816300925',
+      '2026-03-31 17:43:33.032 URL: https://api.example.com/v1/fixture?as=2.0.2816300925',
     ].join('\n'),
     'utf8',
   );
@@ -123,7 +123,7 @@ test('readRecentNetworkTraffic keeps Android packet enrichment disabled for Appl
   });
 
   assert.equal(dump.entries.length, 1);
-  assert.equal(dump.entries[0]?.url, 'https://www.expensify.com/api/fl?as=2.0.2816300925');
+  assert.equal(dump.entries[0]?.url, 'https://api.example.com/v1/fixture?as=2.0.2816300925');
   assert.equal(dump.entries[0]?.timestamp, '2026-03-31 17:43:33.032');
   assert.equal(dump.entries[0]?.status, undefined);
   assert.equal(dump.entries[0]?.durationMs, undefined);
@@ -134,7 +134,7 @@ test('readRecentNetworkTraffic ignores plain documentation URLs in non-network l
   const logPath = path.join(tempDir, 'app.log');
   fs.writeFileSync(
     logPath,
-    '2026-04-02 08:14:44.371 E New Expensify Dev[32193:8c7e18d] Airship config warning. See https://docs.airship.com/platform/mobile/setup/sdk/ios/#url-allow-list for more information.\n',
+    '2026-04-02 08:14:44.371 E Agent Device Tester[32193:8c7e18d] Airship config warning. See https://docs.airship.com/platform/mobile/setup/sdk/ios/#url-allow-list for more information.\n',
     'utf8',
   );
 

src/daemon/handlers/__tests__/find.test.ts

@@ -315,7 +315,7 @@ test('handleFindCommands wait bypasses snapshot cache while Android freshness re
     })
     .mockResolvedValueOnce({
       nodes: [
-        { index: 0, depth: 0, type: 'android.widget.TextView', label: 'Create expense' },
+        { index: 0, depth: 0, type: 'android.widget.TextView', label: 'Create document' },
         { index: 1, depth: 0, type: 'android.widget.Button', label: 'Submit', hittable: true },
       ],
       truncated: false,
@@ -324,7 +324,7 @@ test('handleFindCommands wait bypasses snapshot cache while Android freshness re
     });
 
   const { response } = await runFindClickScenario({
-    positionals: ['text', 'Create expense', 'wait', '700'],
+    positionals: ['text', 'Create document', 'wait', '700'],
     session,
   });
 

src/daemon/handlers/__tests__/interaction.test.ts

@@ -1024,7 +1024,7 @@ test('press @ref fails when Android tap escapes to Settings', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'android-settings-escape';
   const session = makeAndroidSession(sessionName);
-  session.appBundleId = 'com.expensify.chat.dev';
+  session.appBundleId = 'com.agentdevice.tester';
   session.snapshot = {
     nodes: attachRefs([
       {

src/daemon/handlers/__tests__/session.test.ts

@@ -3743,6 +3743,8 @@ test('open on in-use device returns DEVICE_IN_USE before readiness checks', asyn
   expect(response?.ok).toBe(false);
   if (response && !response.ok) {
     expect(response.error.code).toBe('DEVICE_IN_USE');
+    expect(response.error.details?.hint).toContain('agent-device session list');
+    expect(response.error.details?.hint).toContain('--session busy-session');
   }
   expect(mockEnsureDeviceReady).not.toHaveBeenCalled();
 });
@@ -4733,7 +4735,7 @@ test('network dump recovers Android entries from adb logcat when the session str
       return {
         stdout:
           '04-01 10:00:14.500 I/ActivityManager( 9999): Start proc 4321:com.example.app/u0a123 for top-activity\n' +
-          '04-01 10:00:15.000 D/GIBSDK  (4321): POST https://api.example.com/v1/expenses status=200 duration=15032\n',
+          '04-01 10:00:15.000 D/GIBSDK  (4321): POST https://api.example.com/v1/documents status=200 duration=15032\n',
         stderr: '',
         exitCode: 0,
       };
@@ -4763,7 +4765,7 @@ test('network dump recovers Android entries from adb logcat when the session str
     expect(entries.length).toBe(1);
     const latest = entries[0] as Record<string, unknown>;
     expect(latest.method).toBe('POST');
-    expect(latest.url).toBe('https://api.example.com/v1/expenses');
+    expect(latest.url).toBe('https://api.example.com/v1/documents');
     expect(latest.status).toBe(200);
     expect(response.data?.notes).toContain(
       'Session app log stream was inactive. Recovered recent Android HTTP entries from adb logcat for PID set 4321.',
@@ -4996,7 +4998,7 @@ test('network dump recovers iOS simulator entries from simctl log show when the
   fs.mkdirSync(path.dirname(appLogPath), { recursive: true });
   fs.writeFileSync(
     appLogPath,
-    'Filtering the log data using "subsystem == \\"com.expensify.chat.dev\\""\n',
+    'Filtering the log data using "subsystem == \\"com.agentdevice.tester\\""\n',
     'utf8',
   );
   sessionStore.set(sessionName, {
@@ -5007,7 +5009,7 @@ test('network dump recovers iOS simulator entries from simctl log show when the
       kind: 'simulator',
       booted: true,
     }),
-    appBundleId: 'com.expensify.chat.dev',
+    appBundleId: 'com.agentdevice.tester',
     appLog: {
       platform: 'ios',
       backend: 'ios-simulator',
@@ -5030,7 +5032,7 @@ test('network dump recovers iOS simulator entries from simctl log show when the
       return {
         stdout:
           'Timestamp               Ty Process[PID:TID]\n' +
-          '2026-04-02 08:08:50.665 I New Expensify Dev[32193:8c7411e] POST https://api.example.com/v1/search statusCode=200 duration=42\n',
+          '2026-04-02 08:08:50.665 I Agent Device Tester[32193:8c7411e] POST https://api.example.com/v1/search statusCode=200 duration=42\n',
         stderr: '',
         exitCode: 0,
       };
@@ -5073,7 +5075,7 @@ test('network dump explains when iOS simulator recovery found app logs but no HT
   fs.mkdirSync(path.dirname(appLogPath), { recursive: true });
   fs.writeFileSync(
     appLogPath,
-    'Filtering the log data using "subsystem == \\"com.expensify.chat.dev\\""\n',
+    'Filtering the log data using "subsystem == \\"com.agentdevice.tester\\""\n',
     'utf8',
   );
   sessionStore.set(sessionName, {
@@ -5084,7 +5086,7 @@ test('network dump explains when iOS simulator recovery found app logs but no HT
       kind: 'simulator',
       booted: true,
     }),
-    appBundleId: 'com.expensify.chat.dev',
+    appBundleId: 'com.agentdevice.tester',
     appLog: {
       platform: 'ios',
       backend: 'ios-simulator',
@@ -5107,7 +5109,7 @@ test('network dump explains when iOS simulator recovery found app logs but no HT
       return {
         stdout:
           'Timestamp               Ty Process[PID:TID]\n' +
-          '2026-04-02 08:08:50.665 E New Expensify Dev[32193:8c7411e] Airship config warning\n',
+          '2026-04-02 08:08:50.665 E Agent Device Tester[32193:8c7411e] Airship config warning\n',
         stderr: '',
         exitCode: 0,
       };