fix(428): harden Android raw screenshot capture (#467)

The Android raw path in device-screenshot-raw.ts was fallback-only and
unchanged when #427 hardened iOS, carrying three pre-existing bugs:

1. Truncate-before-success: createWriteStream opened the caller's FINAL
   path (truncating it) before capture succeeded, and unlinkSync'd it on
   failure — destroying a file the tool never created. Now stage bytes in
   a unique sibling temp file and renameSync onto the final path only
   after BOTH the write stream drained AND adb exited 0. Same-dir temp
   keeps the rename an atomic same-filesystem move.

2. Multi-emulator first-pick: the resolver grabbed the first emulator
   line, so with several booted and no session binding a raw screenshot
   could hit the wrong device. Now exactly-one-or-refuse via
   resolveAndroidEmu (null on ambiguity), mirroring iOS resolveIosUdid;
   the first-pick parseAdbDevicesEmu is removed. Sessions still bind via
   tryRawScreenshot's preferredDeviceId.

3. adb child leak on write-stream error: on out.on('error') the adb child
   kept running blocked on stdout. Now unpipe + kill it before settling.

Adds gh-428-android-raw-screenshot.test.ts (fake-adb spawn seam drives
the real capturer: temp/rename, two-track settle, stream-error kill) and
updates the two prose references to the removed parser. Full unit suite
green (2924).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Lykhoyda

.changeset/gh-428-android-raw-screenshot-hardening.md

@@ -0,0 +1,20 @@
+---
+'rn-dev-agent-cdp': patch
+'rn-dev-agent-plugin': patch
+---
+
+Harden the Android **raw** screenshot capture path (`device_screenshot`, GH #428),
+mirroring the iOS hardening from #427:
+
+- **Truncate-before-success**: raw capture now stages `adb exec-out screencap`
+  bytes in a unique sibling temp file and `renameSync`s onto the caller's path
+  only after both the write stream drains and adb exits 0. A failed or timed-out
+  capture can no longer truncate-then-delete an existing file the tool never
+  created.
+- **Multi-emulator first-pick**: with several emulators booted and no session
+  binding, resolution now refuses (exactly-one-or-null via `resolveAndroidEmu`)
+  instead of silently grabbing the first emulator — matching iOS
+  exactly-one-or-refuse. Sessions still bind to their device id.
+- **adb child leak on stream error**: a write-stream error (ENOSPC/EACCES) now
+  unpipes and kills the `adb` child before settling, instead of leaving it
+  running blocked on stdout.

scripts/cdp-bridge/dist/tools/device-list.js

@@ -277,7 +277,7 @@ export async function captureAndResizeScreenshot(args) {
     // capturing the other platform via agent-device's broken `--platform`
     // routing defeats the entire purpose of passing the arg. Re-evidence on
     // the user-reported regression: an OOM-unstable emulator leaves
-    // `adb devices` returning the emulator as `offline`, parseAdbDevicesEmu
+    // `adb devices` returning the emulator as `offline`, parseAdbDevicesEmuAll
     // skips it, the fallback fires, iOS screen is returned.
     const rawResultOk = (path, platform) => ({
         content: [

scripts/cdp-bridge/dist/tools/device-screenshot-raw.js

@@ -19,7 +19,8 @@
  * spawning real `xcrun`/`adb` subprocesses.
  */
 import { execFile, spawn } from 'node:child_process';
-import { createWriteStream, unlinkSync } from 'node:fs';
+import { createWriteStream, renameSync, unlinkSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
 // GH #422: the single-pick parseSimctlBootedUDID was removed — first-booted
@@ -75,19 +76,44 @@ export async function resolveIosUdid(explicit, probe = defaultSimctlBootedJson)
     }
 }
 const EMU_LINE = /^(emulator-\d+)\s+device\b/;
-export function parseAdbDevicesEmu(stdout) {
-    const lines = stdout.split('\n');
-    for (const line of lines) {
+// GH #428: the single-pick parseAdbDevicesEmu was removed — first-booted
+// selection was a silent wrong-device capture with several emulators booted and
+// no session binding. All resolution goes through parseAdbDevicesEmuAll +
+// exactly-one, mirroring the iOS parseSimctlBootedAll hardening from GH #422/#427.
+export function parseAdbDevicesEmuAll(stdout) {
+    const ids = [];
+    for (const line of stdout.split('\n')) {
         const trimmed = line.trim();
-        if (!trimmed)
-            continue;
-        if (trimmed.startsWith('List of devices'))
+        if (!trimmed || trimmed.startsWith('List of devices'))
             continue;
         const match = trimmed.match(EMU_LINE);
         if (match)
-            return match[1];
+            ids.push(match[1]);
+    }
+    return ids;
+}
+async function defaultAdbDevicesStdout() {
+    const { stdout } = await execFileAsync('adb', ['devices'], {
+        timeout: 5000,
+        maxBuffer: 1024 * 1024,
+    });
+    return stdout;
+}
+/**
+ * GH #428: exactly-one-or-refuse Android emulator resolution, mirroring the iOS
+ * resolveIosUdid contract. With several emulators booted and no session UDID,
+ * first-pick could silently capture the wrong device — refuse (return null) so
+ * the caller hard-fails with an actionable message instead. Callers with a
+ * session pass its device id through tryRawScreenshot's preferredDeviceId.
+ */
+export async function resolveAndroidEmu(probe = defaultAdbDevicesStdout) {
+    try {
+        const all = parseAdbDevicesEmuAll(await probe());
+        return all.length === 1 ? all[0] : null;
+    }
+    catch {
+        return null;
     }
-    return null;
 }
 const defaultIosResolver = async () => {
     try {
@@ -109,18 +135,7 @@ const defaultIosResolver = async () => {
 export async function resolveBootedIosUdid() {
     return defaultIosResolver();
 }
-const defaultAndroidResolver = async () => {
-    try {
-        const { stdout } = await execFileAsync('adb', ['devices'], {
-            timeout: 5000,
-            maxBuffer: 1024 * 1024,
-        });
-        return parseAdbDevicesEmu(stdout);
-    }
-    catch {
-        return null;
-    }
-};
+const defaultAndroidResolver = () => resolveAndroidEmu();
 // Honor the requested format via the path extension, matching how the
 // agent-device path infers format. Writing JPEG bytes into a `.png` file
 // (the prior hardcoded `--type=jpeg`) produced a mislabeled image because
@@ -147,6 +162,28 @@ export function resolveCaptureOutcome(streamFinished, procCode) {
         return 'pending';
     return procCode === 0 ? 'success' : 'failure';
 }
+/**
+ * GH #428 finding 1: the caller's FINAL path must never be opened until capture
+ * succeeds. Staging bytes in a unique sibling temp file (same directory → the
+ * rename is an atomic same-filesystem move, never a cross-device EXDEV copy)
+ * means a failed/timed-out `adb screencap` can't truncate-then-unlink a file
+ * the tool didn't create. The name is dotfile-prefixed and `.rawtmp`-suffixed
+ * so a crash leaves an obviously-transient artifact, not a plausible screenshot.
+ */
+export function rawTempPath(finalPath, uniq) {
+    return join(dirname(finalPath), `.${basename(finalPath)}.${uniq}.rawtmp`);
+}
+// Per-process monotonic suffix — collision-free across rapid successive captures
+// without Date.now()/Math.random(), which keeps temp names deterministic in tests.
+let captureCounter = 0;
+function nextCaptureSuffix() {
+    captureCounter += 1;
+    return `${process.pid}.${captureCounter}`;
+}
+const defaultAndroidSpawn = (emuId) => spawn('adb', ['-s', emuId, 'exec-out', 'screencap', '-p'], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+});
+let androidSpawn = defaultAndroidSpawn;
 // Android needs the binary screen bytes piped to a file. execFile can't redirect
 // stdout, so spawn directly and pipe to a write stream — no shell, so the path
 // is safely passed as a literal filename, not interpolated into a command string.
@@ -156,30 +193,30 @@ export function resolveCaptureOutcome(streamFinished, procCode) {
 // alone is insufficient: 'finish' before non-zero close = truncated/partial
 // file reported as success (deepsec 2026-05-12 finding); 'close' before
 // 'finish' = success reported before bytes hit disk (earlier multi-LLM
-// review finding). On any failure path, the partial file is unlinked so
-// `resizeWithSips` never sees a corrupt artifact.
-const defaultAndroidCapturer = async (emuId, path) => new Promise((resolve) => {
+// review finding). Bytes are staged in a temp file (GH #428 finding 1) and
+// promoted onto `path` via renameSync only once the outcome is success; every
+// failure path unlinks the temp and leaves the caller's path untouched.
+export const defaultAndroidCapturer = async (emuId, path) => new Promise((resolve) => {
     let settled = false;
     let streamFinished = false;
     let procCode = null;
-    const proc = spawn('adb', ['-s', emuId, 'exec-out', 'screencap', '-p'], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    const out = createWriteStream(path);
-    const cleanupPartial = () => {
+    const proc = androidSpawn(emuId);
+    const tmp = rawTempPath(path, nextCaptureSuffix());
+    const out = createWriteStream(tmp);
+    const cleanupTemp = () => {
         try {
-            unlinkSync(path);
+            unlinkSync(tmp);
         }
         catch {
-            /* file may not exist yet — ignore */
+            /* temp may not exist yet — ignore */
         }
     };
     const timer = setTimeout(() => {
         if (settled)
             return;
         proc.kill();
         out.destroy();
-        cleanupPartial();
+        cleanupTemp();
         settle(false);
     }, 15_000);
     const settle = (ok) => {
@@ -195,22 +232,38 @@ const defaultAndroidCapturer = async (emuId, path) => new Promise((resolve) => {
             return;
         if (outcome === 'failure') {
             out.destroy();
-            cleanupPartial();
+            cleanupTemp();
+            settle(false);
+            return;
+        }
+        // success: promote the staged temp onto the caller's path only now that
+        // both the stream drained AND adb exited 0. A rename failure (e.g. cross
+        // volume, vanished dir) degrades to capture-failed rather than a partial.
+        try {
+            renameSync(tmp, path);
+            settle(true);
+        }
+        catch {
+            cleanupTemp();
+            settle(false);
         }
-        settle(outcome === 'success');
     };
     proc.stdout.pipe(out);
     out.on('finish', () => {
         streamFinished = true;
         maybeSettle();
     });
     out.on('error', () => {
-        cleanupPartial();
+        // GH #428 finding 3: unpipe + kill the adb child before settling — else it
+        // keeps running, blocked writing to a stdout no one is draining.
+        proc.stdout.unpipe(out);
+        proc.kill();
+        cleanupTemp();
         settle(false);
     });
     proc.on('error', () => {
         out.destroy();
-        cleanupPartial();
+        cleanupTemp();
         settle(false);
     });
     proc.on('close', (code) => {
@@ -231,12 +284,15 @@ export function _setForTest(overrides) {
         iosCapturer = overrides.iosCapturer;
     if (overrides.androidCapturer)
         androidCapturer = overrides.androidCapturer;
+    if (overrides.androidSpawn)
+        androidSpawn = overrides.androidSpawn;
 }
 export function _resetForTest() {
     iosResolver = defaultIosResolver;
     androidResolver = defaultAndroidResolver;
     iosCapturer = defaultIosCapturer;
     androidCapturer = defaultAndroidCapturer;
+    androidSpawn = defaultAndroidSpawn;
 }
 export async function tryRawScreenshot(platform, path, preferredDeviceId) {
     const resolver = platform === 'ios' ? iosResolver : androidResolver;

scripts/cdp-bridge/src/tools/device-list.ts

@@ -367,7 +367,7 @@ export async function captureAndResizeScreenshot(args: ScreenshotArgs): Promise<
   // capturing the other platform via agent-device's broken `--platform`
   // routing defeats the entire purpose of passing the arg. Re-evidence on
   // the user-reported regression: an OOM-unstable emulator leaves
-  // `adb devices` returning the emulator as `offline`, parseAdbDevicesEmu
+  // `adb devices` returning the emulator as `offline`, parseAdbDevicesEmuAll
   // skips it, the fallback fires, iOS screen is returned.
   const rawResultOk = (path: string, platform: 'ios' | 'android'): ToolResult => ({
     content: [