fix(describe): flag an Android read that saw only system chrome

[filip131311]

Fixes #627.

The false pass, measured

With the display off, describe returns a bare ROOT Screen (0,0,1,1) — no error, no hint. The same element, never moved:

screen	call	result
on	await-ui-element visible "Go to home screen"	{"success": true, "elapsed": 5}
off	await-ui-element hidden "Go to home screen"	{"success": true, "elapsed": 5}

An agent gating an action on "the dialog is gone" gets a green light against a screen nobody can read. await-ui-element's isBlindRead has no flag to key on here — its only Android guard is everMatched, which is false when the wait starts after the screen is already dark. The code comment said as much: "Android / Chromium never set these flags."

The signal was already on the wire

getHierarchy() returns nodeCount alongside xml, and describe destructured only xml. nodeCount > 0 with zero rendered children means every node on screen belonged to com.android.systemui and pruned away — which is exactly what a powered-off display and a lock screen look like.

Measured across four states on a Pixel_9 / API 36:

state	nodeCount	rendered children	blind?
app visible	62	2	no
home screen (launcher)	64	7	no
screen off	28	0	yes
keyguard, display on	73	0	yes

So: no adb probe, no new module, no extra round trip, no dumpsys parsing to go stale across OEMs, and nothing added to the hot path.

windowCount is deliberately not the signal. The obvious guess is "no windows ⇒ blind", but it stays 1 with the display off, because the keyguard window is still there — it would never fire. Worth measuring rather than assuming.

I verified the keyguard case separately (set a PIN and disabled the screen timeout so the device couldn't sleep mid-test, since an earlier attempt was unattributable): mWakefulness=Awake, SCREEN_STATE_ON, mIsShowing=true, lock screen visibly on the display — and the tree still comes back empty. A display-power-only check would have missed it entirely.

Fails open

Unknown or zero nodeCount ⇒ no hint. An older device helper that reports no count must not turn every sparse screen into a blind read — that is worse than the bug. This is not hypothetical: the existing hidden succeeds when the node is gone test uses a stub with no nodeCount, and my first draft flagged it, because undefined <= 0 is false. It now passes unmodified.

hint, not a throw

hint already flows into both isBlindRead (so hidden can no longer resolve) and the timeout note — so the false pass closes with zero consumer changes, and the six callers of describeAndroid keep working. On a sleeping device an empty tree plus "wake it" is more useful than a hard error.

Live, after the fix:

describe (screen off) → hint: "This read is BLIND, not empty: every node on screen belonged to the
system UI… An element missing from this tree is NOT evidence that it is hidden or gone… Wake the
device (`button` with button `power`) and dismiss the lock screen, then read again."

await-ui-element hidden → success: false
   note: "could not confirm the element is hidden — the UI tree was empty or unreadable at timeout
          (This read is BLIND, not empty: …)"

Screen on: no hint, full tree, unchanged.

Behaviour change to know about

A hidden wait that previously returned instantly now runs to its timeout and fails, and an unmet wait halts a run-sequence. That is the intent, but it will change any recorded sequence that (wrongly) depended on the instant pass.

Interaction with #591

#591 (draft) touches the same two files. No textual collision: its android/index.ts hunk is @@ -52,7 +52,34 @@ and mine is the destructure at :54 plus a new helper above the TV hint — the one adjacent line resolves trivially either merge order. In await-ui-element/index.ts its hunks are at 187-195 / 217-223 / 354-360; my only edit is the now-false comment at :151-165, which had to be corrected since it documented precisely the gap this closes. The new await-ui-element test is a separate file because #591 also extends test/await-ui-element.test.ts.

#519 is the iOS half of this class; it throws inside flow-ios-tree.ts, whose contract is "helpers throw". The true Android mirror is flows/flow-android-tree.ts, which does not route through describeAndroid — so flow assert hidden still false-passes there. Left as a follow-up so it can be reviewed next to #519.

Checks

• 3094 tests pass; 8 new, of which 5 fail against the pre-fix source (the 3 that pass on both are the fail-open invariance checks).
• All pre-existing await-ui-element / describe-tv / await-screen-idle tests pass unmodified.
• extract-tools 46/46; prettier, eslint, both typechecks clean; lock untouched.