Noticed while working on #620.
An Android device whose screen is off produces a describe tree with no content and no hint, so every tool built on it stalls without saying why.
Reproduced on a Pixel_9 emulator that had gone to sleep:
dumpsys power → mWakefulness=Asleep
dumpsys window → mCurrentFocus=null
describe → "ROOT Screen (0.000, 0.000, 1.000, 1.000)" ← no children, no hint
await-screen-idle → { settled: false, waitedMs: 20000, polls: 4 } ← burns the whole budget
The await-screen-idle result is correct behaviour — the screen genuinely has no content — and after #620 it at least now says "the screen reported no content". But it still cannot say the useful thing, because nothing upstream knows: describeAndroid attaches no hint for this state.
The cause is trivially detectable. dumpsys power | grep mWakefulness is one adb call, and argent already shells out to dumpsys elsewhere. A hint like "the device screen is off — wake it with button {button:"power"} and retry" would turn a silent 20s stall into a one-step fix.
Worth deciding as part of this: whether describe should merely report it or optionally wake the device. Reporting is clearly right; waking is a side effect a read-only discovery tool arguably should not perform, so my inclination is hint-only.
Note the MCP auto-screenshot path makes this more expensive than it looks — it waits on await-screen-idle before capturing, so a sleeping device costs the full per-tool budget (up to 15s for run-sequence) on every call.
Noticed while working on #620.
An Android device whose screen is off produces a describe tree with no content and no hint, so every tool built on it stalls without saying why.
Reproduced on a Pixel_9 emulator that had gone to sleep:
The
await-screen-idleresult is correct behaviour — the screen genuinely has no content — and after #620 it at least now says "the screen reported no content". But it still cannot say the useful thing, because nothing upstream knows:describeAndroidattaches no hint for this state.The cause is trivially detectable.
dumpsys power | grep mWakefulnessis one adb call, and argent already shells out todumpsyselsewhere. A hint like "the device screen is off — wake it withbutton {button:"power"}and retry" would turn a silent 20s stall into a one-step fix.Worth deciding as part of this: whether
describeshould merely report it or optionally wake the device. Reporting is clearly right; waking is a side effect a read-only discovery tool arguably should not perform, so my inclination is hint-only.Note the MCP auto-screenshot path makes this more expensive than it looks — it waits on
await-screen-idlebefore capturing, so a sleeping device costs the full per-tool budget (up to 15s forrun-sequence) on every call.