You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 903b0f4
Browse filesBrowse the repository at this point in the historyBrowse files
fix(apple-runner): serve a macOS read of a background app without raising it (#3339)
* fix(apple-runner): serve a macOS read of a background app without raising it
On a desktop, the XCTest foreground repair is not a no-op for the user: a read that
names a session app sitting behind other windows took their frontmost app away for a
command that only asked to look (#3254). The activation axis already routes by
`launchPolicy`, so the fix goes on the existing `.existingApp` arm of
`prepareActiveCommandContext`: on macOS, a read whose app answers
`.runningBackground` is served in place through `resolveAppWithoutActivation`, and
no activation fact is booked for it. Scoping is exact:
- a stopped app keeps the launch the activating route performs for it today: `state`
answers `.notRunning` and the arm declines, so `open`-then-read still works and no
macOS refusal is invented (`notRunningRefusal` stays iOS-only);
- interactions keep activating: the macOS XCTest path drives events through the
foreground window, and a background click would land on whatever window is on top;
- a window-level screenshot keeps its raise (measured: a backgrounded
`screenshotRoot(app:).screenshot()` returns the occluding window's content inside
the session window's rect), but a `--fullscreen` capture of a running app no longer
raises — `XCUIScreen.main` answers from any foreground, and the 0.5 s settle waits
belong to the raise and are skipped with it. A stopped app keeps launching either way.
The two conditions are functions the call sites read (`macReadMayBeServedInBackground`,
`macAppCaptureNeedsRaise`) so the host lane pins every state they branch on. Four
host-lane tests: the background read served without a raise or a fact across its three
shapes, the interaction on the same app still activating, a stopped read still
launching, and the raise-condition table. The canary is the arm's removal: the read
test goes red with the app left foreground and a `bundle_changed` fact booked. A live
run on the default backend confirms it: with Finder frontmost, `snapshot` and `get`
answered from the background app, Finder stayed frontmost, and runner.log booked zero
activation facts; the click after them activated with priorState=3 as it must.
`help macos` states the new read behavior.
Also records at the `.presentedSurface` arm why its macOS route is unreachable from
the host (`alert` answers through the helper; `action-button` is refused by its owner
fact before dispatch), so no second activation axis is proposed against it.
Partial #3254
* test(apple-runner): own the background-serve state split and its silence
Turns two accidents into rules, both asked for in coordinator review of #3339:
- `macReadMayBeServedInBackground` splits its state probe from the `state` call so the
host lane can pin every state the answer branches on. The pin records why only
`.runningBackground` is served in place: on the macOS SDK the suspended case does not
exist (the split is pinned by RunnerTests+ApplicationStateRawValueTests), and every
other state keeps the activating route so an app that cannot promise an answerable
tree pays the repair rather than trading a focus steal for an empty read — the same
set `targetNeedsActivation` uses on macOS, so read and capture cannot disagree.
- The disclosure decision is made with the reviewer rather than by omission, and pinned:
a background-served read books no activation fact and no substitute marker. The
existing channels cannot say it honestly — the activation fact records only a repair
performed, and the observation payload belongs to the iOS observe-only contract, which
refuses exactly this situation. A background tree is live, not degraded (measured
rect drift is time, not foreground state), and interactions still activate, so no
action path consumes a background tree. `XCTAssertNil(prepared.observation)` makes the
absence owned: a future disclosure must edit the assertion on purpose.
No behavior change; both live-state tests and the new table pass on the host lane.
* test(apple-runner): pin the capture raise condition on .unknown too
The raise table claimed to pin every state `macAppCaptureNeedsRaise` branches on but
omitted `.unknown`, while the read table in the same test pinned it — the state worth
pinning on one side could not be unpinnable on the other. The rows convert the silent
drift path into a red row: `.unknown` raises for a window-level capture, where the
activation is the standing route's attempt to settle an app whose state the SDK cannot
report, and stays false for `--fullscreen`, whose pixels answer from any foreground.
Expectations verified against the implemented condition, not pasted. No behavior
change.
Partial #3254
* fix(apple-runner): refresh a served macOS read against a relaunched pid
A read served in place resolved through `resolveAppWithoutActivation`, which returns the
cached handle when the cache names the app — and a cached handle can record a pid an
outside relaunch replaced. The activating route never answers from that residue because
it runs `refreshCachedTargetIfProcessChanged` before its `targetNeedsActivation` read;
the new arm bypassed the shared identity rule, so between an outside relaunch and the
next read, a served read could address the dead process while claiming to observe the
live one. Reachability: an `open`-bound session whose app is quit and reopened by the
user leaves exactly this residue, and macOS `notRunningRefusal` never intercepts it.
The fix runs the shared rule on the arm before resolution, so identity is settled once
and both routes read the same live pid.
Pinned by a host-lane test that plants the residue (live app, bogus cached pid) and
asserts the served preparation refreshes without activating; canary: deleting the
refresh call fails the test with the bogus pid still in place. Also drops the probe
wrapper the arm no longer needs: a served read is one `state` query, and the
activating route's second read cannot reuse the first because the refresh between them
may have replaced the process the first answered for. The arm's and the predicate's
comments are cut to the invariant they protect, per AGENTS.md; the decision record
lives in #3338.
Partial #3254
* docs(apple-runner): cut review history from the background-serve comments
AGENTS.md keeps decision and review narration out of implementation comments: the
screenshot raise site, `macAppCaptureNeedsRaise`, and the `.existingApp` policy case
each keep the one constraint they encode (region-grab pixels, the state rule, the
served-read scope) and point at #3338 for the measured record. No behavior change;
host-lane evidence for the pinned conditions is unchanged.
Partial #3254
Copy file name to clipboardExpand all lines: src/commands/schema/cli-help.ts
+2-1Lines changed: 2 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -739,7 +739,8 @@ Rules:
739
739
Context menus are not ambient UI: secondary-click a visible target, then re-snapshot and use the new menu-item refs.
740
740
Do not let iOS simulator-set scoping hide macOS desktop targets.
741
741
Prefer refs/selectors over raw coordinates.
742
-
macOS snapshot rects are window-space; use current refs or overlay refs instead of guessing coordinates.`,
742
+
macOS snapshot rects are window-space; use current refs or overlay refs instead of guessing coordinates.
743
+
On the default XCTest backend a read (snapshot, get, find) of a session app that sits behind other windows is answered from where it sits, without raising the app; interactions and a window-level screenshot of that app still bring it forward.`,
743
744
},
744
745
web: {
745
746
summary: 'Minimal browser workflow with the managed web backend',
0 commit comments