fix(device): hard-fail device_screenshot on explicit-platform raw failure (closes #136 sub-issue 1)

[Lykhoyda]

Summary

Closes the first of three sub-issues in #136 — device_screenshot platform: \"android\" silently capturing the iOS screen when both simulators are booted. PR #142 (the prior fix) shipped a raw-command path that bypasses agent-device's broken --platform routing, but kept a "graceful fallback" that fell through to that same broken path on any raw failure. The fallback was the regression vector.

Root cause

In the user-reported session, the Android emulator was in an OOM-unstable state. adb devices reported it as offline, parseAdbDevicesEmu's ^(emulator-\\d+)\\s+device\\b regex skipped it, the resolver returned null, the raw path returned null, and the fallback to runAgentDeviceFn fired — which then routed via agent-device's --platform flag (the exact broken path #142 was meant to avoid), capturing the iOS screen.

The comment in device-list.ts defended this as graceful degradation preserving single-device behavior. That reasoning was backwards: single-device users don't pass platform: explicitly (it's inferred from CDP target), so they never hit this branch. Only the multi-device case sets platformExplicit=true, and for that case silent fallback defeats the entire purpose of the arg.

Fix

When platformExplicit && raw fails, return a structured failure with the actionable reason instead of falling through.

• device-screenshot-raw.ts: tryRawScreenshot now returns a discriminated union {ok:true,path} | {ok:false,reason: 'no-device' | 'capture-failed'} so callers can distinguish a resolver miss (no device booted / offline) from a capturer failure (transient adb/simctl error).
• device-list.ts: captureAndResizeScreenshot returns failResult(...) with code=SCREENSHOT_FAILED and meta={platform, reason} on explicit-platform failure. Error message names the CLI (xcrun simctl / adb) and the sub-cause so callers can act.
• Implicit-platform calls (platformExplicit=false) still route through runAgentDevice unchanged — backward parity preserved by the existing 'platformExplicit=false → uses runAgentDevice (backward parity)' test.

Test plan

• 1465/1465 cdp-bridge unit tests passing locally
• Inverted the existing 'falls through to runAgentDevice' test to assert hard-fail (the test had been encoding the regression behavior)
• Added a second hard-fail test for the capture-failed surface (distinct from no-device)
• Tightened 3 pre-existing tryRawScreenshot tests from assert.equal(result, null) to assert.deepEqual(result, {ok:false, reason:...}) on the new union shape
• codex-pair reviewed every edit; final state has zero outstanding concerns from this PR
• CI green
• Live multi-device verification (out of scope for this PR — needs the dual-device harness mentioned in the deferral comment)

Out of scope

• Sub-issue 2 (cdp_status dev-client picker auto-tap) — needs an Expo Dev Client test-app to reproduce. Tracked in Multi-device routing + dev-client picker hangs (combined session feedback) #136.
• Sub-issue 3 (launchApp dev-launcher handler) — same prereq.
• Unrelated pre-existing HIGH flagged by codex-pair: deriveScreenshotPath throws PathTraversalScreenshotError for .. paths, but no catch wraps the handler — a bad path becomes an uncaught tool exception instead of a structured failResult. Filed as a follow-up, not addressed in this PR.

Refs

• IX-2950 session feedback: multi-device routing bugs + missing primitives (record/storage/reset) #60 — original multi-device routing issue (CLOSED; this is the re-evidence path)
• Multi-device routing + dev-client picker hangs (combined session feedback) #136 — combined session feedback (3 sub-issues; this PR addresses post-edit-health-check hook fires false positives outside RN project and when app is uninstalled #1)
• PR fix(gh-136): explicit-platform raw screenshot path (PR-A) #142 — the prior raw-path fix this builds on
• PR fix: android capturer exit-code race (Phase 134.0) #143 — the capturer race fix that hardened the Android path

🤖 Generated with Claude Code