iOS: selector commands displace the app under test and return false negatives when no app session is tracked

[thymikee]

Summary

On iOS, a selector command run against a session with no tracked appBundleId does not merely
fail to observe the screen — it displaces the app under test and then returns a confident
negative. find reports success: true, matches: [] for an element that is unambiguously on
screen, and the app that was in the foreground is gone.

This is a silent false negative that also corrupts device state, which makes it worse than a
failure: an agent gets a definitive-looking answer and a changed device.

Reproduction (iOS Simulator, iPhone 17, iOS 26.2)

Three A/B runs on the same simulator, seconds apart, against main:

Setup	Command	Result	Device afterwards
Settings foregrounded	sessionless find "General" list	success: true, matches: []	Settings displaced by AgentDeviceRunner
Home screen, "Settings" icon visible	find "Settings" list on a session with no app	success: true, matches: []	home screen displaced
Settings foregrounded	sessionless snapshot	refuses in 2.4s, SESSION_NOT_FOUND	Settings untouched

"General" and the Settings icon were unambiguously visible in the first two cases.

Mechanism

appBundleId is the XCUITest attach target.

• With a target: the runner attaches to (and relaunches) that app. Verified by killing Settings with
  simctl terminate mid-session — snapshot still returned 18 real Settings nodes.
• With no target: the runner has nothing to attach to, ensureRunnerHostAppActive brings
  AgentDeviceRunner itself to the foreground, and the capture observes its own ~3-node blank
  screen. The runner app has real UI, so the nodes.length === 0 tripwire never fires and the
  result looks plausible.

snapshot and diff are protected because they refuse this state up front (introduced in #681 to
stop exactly this class of wrong answer). find, get, is, and wait never ask, so they run the
capture and report on the runner.

Same state on Android is fine: snapshot returns the real launcher (16 nodes), find "Chrome" exists → true, wait text "Gmail" → success in 385 ms. The platform facts already encode the
asymmetry — platform-apple marks withoutActiveApp app-required for iOS,
platform-android allows it — so this is an iOS-only defect.

Related but separate: unhelpful refusal wording

Sessionless get and is refuse with a generic SESSION_NOT_FOUND / "No active session", rather
than the actionable iOS app-session message with the open hint that snapshot emits
(ios_app_session_required + buildIosOpenCommandHint). Unifying the wording across the selector
family is cheap and removes a second class of confusing output.

Fix direction

The Wave 4 selector migrations (#1739) close this as a side effect: wait (#1875), get (#1877),
and is route their captures through fact-derived admission, which refuses on iOS-with-no-app and
proceeds on Android automatically. find's own cutover is deferred behind Wave 5 focus/type
(#1876), so find keeps this defect the longest and is the reason this is filed separately
rather than folded into the wave.

Worth reconsidering while fixing

The rationale currently in the code — that an iOS capture without an app session "cannot succeed" —
is too strong. #1296 live-validated that capture works fine when SpringBoard is named as the session
app; the real constraint is that XCUITest needs some bundle id to attach to, not the user's app.
So refusing is correct only relative to today's implementation. A no-app iOS session could attach to
SpringBoard and return the real screen, which is what #1296 wants and what would remove the agent
friction #1662 measured (27 of 30 benchmark tasks hitting this refusal, costing 2-3 turns and ~20 s
each). That is a larger change than this bug fix and is noted here so the two are not solved twice.

[thymikee]

Two refinements from the units that produced the evidence above.

Scope correction on the device evidence. The A/B runs tested the no bundle id at all case, where XCUITest has no attach target and the runner foregrounds itself. They do not support the stronger claim that iOS capture without an app session is impossible in principle — #1296 falsifies that by capturing SpringBoard successfully when it is named as the session app. The accurate reading is the narrower one: without a target bundle id, the capture observes the runner and displaces the foreground. That is consistent with the real constraint being "XCUITest needs some bundle id, not the user's app," and it is why the fix direction is fact-derived admission rather than a blanket refusal.

The findings that stand independent of that rationale are the ones in the report above: find returning success: true, matches: [] while destroying the foreground, and the Android contrast where the identical state captures the real launcher and find/wait/is all answer correctly.

The category error propagates through one owner, which is good news for fixing it. reason: 'owner-capability-missing' classifies "the user has not run open yet" as a missing platform owner capability, when it is session state. That misclassification is the mechanism by which the refusal reaches every command that adopts the snapshot plan, without anyone deciding it should.

The Wave 4 selector seam (#1877) inherits that classification rather than copying it: resolveSelectorCaptureRuntimePlan keys the plan on session?.appBundleId !== undefined and lets the platform fact supply the answer. So find, get, is, and wait are all consumers of the single classification, not independent reimplementations of it. If the session-state-vs-owner-capability distinction is corrected at the fact model, every selector command follows automatically — no per-command migration needed.

That also means the cheapest version of the deeper fix outlined above (attach to SpringBoard rather than refuse) is a change at the fact/plan boundary, not a change in five command handlers.

A concrete behavior the fix must preserve, measured on device: the two wait verdicts are genuinely distinct — a sessionless wait yields wait_capture_stalled with readableCaptures: 0, while a session-with-no-app wait yields wait_deadline_exceeded with readableCaptures: 2. They report different underlying situations and should not be collapsed.

[thymikee]

Closing: fixed on `main`.

All four selector commands now share one admit-then-bind seam — `SelectorCaptureCommand = 'find' | 'get' | 'is' | 'wait'` in `src/daemon/selector-capture-binding.ts`. It resolves the plan through `resolveSelectorCaptureRuntimePlan({ hasActiveApp })`, so a session with no tracked `appBundleId` asks for `captureSnapshotWithoutActiveApp`, hits iOS's `snapshotActiveAppRequired` fact (`packages/platform-apple/src/runtime.ts:403`), and is refused before any bind or capture — nothing reaches the runner, so nothing can be displaced.

The issue predicted `find` would keep the defect longest. It does not: read-only `find` actions (`exists`/`wait`/`list`/`get text`/`get attrs` — exactly the reproduction's `find "General" list`) always return from `dispatchFindReadOnlyViaRuntime` (`src/daemon/handlers/find.ts:84`), and only mutating actions fall through, where an active session was already required.

The "related but separate" wording item is closed by the same seam: the refusal is built once in `admitAndBindSnapshotCapture` and carries `ios_app_session_required` plus `buildIosOpenCommandHint` (`src/daemon/snapshot-runtime-binding.ts:311`), so `get`/`is`/`wait`/`find` all emit the actionable message with the `open` hint instead of a bare `SESSION_NOT_FOUND`.

Regression coverage names the defect verbatim: \an iOS session with no tracked app is refused with the open hint, not answered from a displaced capture' (\src/daemon/tests/is-runtime.test.ts:106`), with the Android counterpart asserting the platform asymmetry still proceeds.

Landed across #1875, #1876 and #1877.

Not closed here, by design: attaching a no-app iOS session to SpringBoard so the real screen can be returned (the #1296 / #1662 direction). That remains the larger change this issue flagged so the two would not be solved twice.