fix(#265): create screenshot target directory before capture — stop blaming device state

[Lykhoyda]

Summary

device_screenshot with a path under a non-existent directory failed with "The device may be transitioning state (booting, OOM, locked)" — a pure misdiagnosis of a filesystem precondition (GH #265).

Root cause (live-verified on a healthy booted simulator): xcrun simctl io <udid> screenshot docs/proof/<missing>/01.jpg exits 4 with NSCocoaErrorDomain "The folder doesn't exist" (underlying ENOENT). The iOS capturer's bare catch { return false } erased the cause, and rawResultFail mapped every non-no-device failure to the device-state guess. The Android tier had the identical hazard via createWriteStream(path) ENOENT.

Fix

All at the shared funnel captureAndResizeScreenshot (covers device_screenshot, device_batch auto-captures, and proof_step):

• mkdir -p the parent of the derived path before any dispatch tier runs (simctl raw, rn-fast-runner, agent-device daemon/CLI, adb stream). New directories are the expected case — the tool's own EPHEMERAL_PATH advisory steers agents toward fresh docs/proof/<slug>/ paths.
• Honest error when mkdir fails (file blocking an intermediate segment, permissions): short-circuits before any device probing with SCREENSHOT_FAILED / reason: 'target-dir-unavailable' naming the offending path.
• ~/ expansion (codex review finding on the first commit): Node never expands ~, so the mkdir precondition would have turned a loud failure for ~/Desktop/x.jpg into a silent mislanding (literal ./~/Desktop/ under the bridge cwd, success reported). deriveScreenshotPath now expands a leading ~/ to homedir() and refuses unexpandable forms (~user/..., bare ~). The traversal guard runs on raw input before expansion, so ~/../ cannot smuggle a collapsed .. past it.

Verification

• TDD throughout: 6 new tests, each watched fail first (the misdiagnosis test pins doesNotMatch /transitioning/i against the exact production message).
• Full unit suite: 2019/2019 (clean main baseline re-measured at 2013 in a fresh worktree).
• Live gate: the exact issue repro (platform=ios, path under a fresh nested dir) now captures + resizes end-to-end against the booted simulator (1206×2622 → 800×1739, 48% bytes saved).
• Multi-LLM review: Antigravity SHIP; Codex NEEDS-WORK → its one IMPORTANT finding (tilde mislanding) verified real and fixed in the second commit. Codex's pre-existing device_record advisory filed as fast-follow bug: device_record has the same missing-target-directory hazard fixed for device_screenshot in #265 #282.

Closes #265

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.