Summary
Add an agent-friendly doctor command that quickly separates environment/setup failures from product or agent-device failures before a QA or dogfood run starts.
Motivation
QA onboarding feedback shows many red runs are caused by plumbing issues rather than the scenario itself: wrong or stale Metro on port 8081, device not fully booted, stale agent-device sessions, app/package mismatch, missing Android port reverse for package launches, React Native LogBox/RedBox overlays, permission dialogs, and under-provisioned emulators. Today users manually run a short checklist with adb, curl, and agent-device commands.
Proposed shape
agent-device doctor --platform android --target-app com.example.app --metro-port 8081 --react-native
agent-device doctor --platform ios --target-app com.example.app --metro-port 8081 --expo
The command should be safe/read-only by default and return compact text plus JSON for agents.
First-pass checks
- CLI version and resolved state dir.
- Device/simulator/emulator presence and boot readiness.
- Active/stale agent-device sessions or locks for the selected target.
- App installed/discoverable and foreground package/bundle when relevant.
- Metro reachability from the host context, with a warning when sandboxed probes may be non-authoritative.
- Android RN/Expo reachability hints: direct URL opens can auto-configure localhost, while package launches may still need adb reverse.
- Common RN blockers visible on current snapshot/screenshot: LogBox/RedBox overlay, permission dialog, app on launcher, wrong app in foreground.
- Android animation settings and permission state hints where supported.
- Optional emulator resource warning if available from host/device metadata.
Output requirements
- Keep default output short: status, top blockers first, exact recovery command when safe.
- Preserve detailed diagnostics in JSON fields for agents and CI artifacts.
- Avoid mutating app/device state unless explicit flags request fixes such as --fix-animations or --grant-permission.
Notes
Some React Native-specific findings may belong in the doctor command directly, while deeper runtime evidence should continue to route to help react-native, help debugging, and react-native dismiss-overlay.
Summary
Add an agent-friendly doctor command that quickly separates environment/setup failures from product or agent-device failures before a QA or dogfood run starts.
Motivation
QA onboarding feedback shows many red runs are caused by plumbing issues rather than the scenario itself: wrong or stale Metro on port 8081, device not fully booted, stale agent-device sessions, app/package mismatch, missing Android port reverse for package launches, React Native LogBox/RedBox overlays, permission dialogs, and under-provisioned emulators. Today users manually run a short checklist with adb, curl, and agent-device commands.
Proposed shape
The command should be safe/read-only by default and return compact text plus JSON for agents.
First-pass checks
Output requirements
Notes
Some React Native-specific findings may belong in the doctor command directly, while deeper runtime evidence should continue to route to help react-native, help debugging, and react-native dismiss-overlay.