Skip to content

Commit 88b9ead

Browse files
docs(adr): describe the one session conflict predicate for macOS app claims
ADR 0034 rules 5 and 7 state the predicate shared by the new-session check and open --wait, and the background open now follows the session's scope. ADR 0007 and ADR 0031 and the macOS command notes match.
1 parent 1f09f25 commit 88b9ead

4 files changed

Lines changed: 21 additions & 14 deletions

File tree

‎docs/adr/0007-remote-device-leases.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -189,8 +189,9 @@ app for every request but `open` and the `batch` envelope, so a
189189
request naming no session cannot fall back to the host Mac. `open` requires the native app backend (ADR 0031), because XCTest
190190
posts screen events that can land outside the app's window. A pid-pinned lease is checked against the
191191
running process before each admitted request. A session opened under the lease holds its app, not
192-
the Mac: it takes no host device claim, and other app-leased sessions on the same Mac do not conflict
193-
with it, so one daemon serves several leased apps beside the host's own sessions.
192+
the Mac: it takes no host device claim, and sessions on other apps of the same Mac, leased or
193+
holding an app claim (ADR 0034), do not conflict with it, so one daemon serves several leased apps
194+
beside the host's own sessions. A session on the same app does.
194195

195196
These rules bind a request that names the lease or runs in its session. A daemon policy
196197
`leases.require` (ADR 0029) refuses requests that name no lease. The proxy token is one credential

‎docs/adr/0031-macos-native-app-backend.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,8 @@ window fields are unmeasured.
3636
assistive client. The app surface walks up to 48 levels deep and reports a deeper tree as
3737
truncated; other helper surfaces keep 12.
3838
6. Screenshots capture the session app's front window by itself through ScreenCaptureKit.
39-
7. `open` launches or reopens the app with `open -g`, leaving the frontmost app in front, and an
40-
app session claims only its app ([ADR 0034](0034-macos-per-app-claims.md)).
39+
7. An app session claims only its app, and `open` launches or reopens that app with `open -g`,
40+
leaving the frontmost app in front ([ADR 0034](0034-macos-per-app-claims.md)).
4141

4242
## Context
4343

‎docs/adr/0034-macos-per-app-claims.md‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,20 @@ because 0032 and 0033 exist on main.
2121
is a conflict. A whole-device acquisition on a macOS device scans the per-app claims of that
2222
device: dead or superseded owners are reconciled and removed, other foreign claims conflict,
2323
and this daemon's own are left to its session store.
24-
5. In one daemon, a per-app open conflicts only with sessions on the whole device or on the same
25-
app. A per-app session may reopen only its app on the `app` surface; a link opens as
26-
`open <app> <url>`, because a bare URL's handler is not known before launch.
24+
5. In one daemon, a session holds either one app (an app claim, or a `macos-app` lease, which
25+
takes no claim) or the whole device. Two sessions on the device conflict unless each holds one
26+
app and the apps differ. The new-session conflict check and the `open --wait` that queues on it
27+
decide with this one predicate, so a whole-device opener and a same-app opener wait for an app
28+
session and a different-app opener runs beside it. A per-app session may reopen only its app on
29+
the `app` surface; a link opens as `open <app> <url>`, because a bare URL's handler is not known
30+
before launch.
2731
6. Helper screenshots take a host-wide lock (`macos-screen-capture.lock` in the device claims
2832
directory) for the length of one capture. It is the only action sessions on different apps
2933
serialize on.
30-
7. App keys are lowercase, because LaunchServices matches bundle ids without regard to case.
31-
An `open --wait` does not wait for a session that holds another app.
34+
7. App keys are lowercase, and the predicate of rule 5 compares bundle ids without regard to case,
35+
because LaunchServices matches them that way. An `open --wait` resolves the claim it would take
36+
under the device lock; until then it waits only for a whole-device session, and when the open
37+
then finds a conflicting app session it releases the lock and waits for that session too.
3238

3339
## Context
3440

@@ -57,10 +63,10 @@ Some commands still reach past the session app, as they did before this ADR: the
5763
appearance settings (host-global state), `close <other app>` (quits any app, including one another
5864
daemon's session holds), and `settings permission` (opens System Settings in front).
5965

60-
**Background open applies to every native surface.** `open` cannot see the session surface, so
61-
under the native backend an `open <app> --surface frontmost-app` no longer brings the app forward
62-
and the session drives whatever is in front. Use `open --surface frontmost-app` without an app, or
63-
the `app` surface.
66+
**Background open follows the session's scope.** A session that holds one app opens it with
67+
`open -g`, because bringing it forward would move the frontmost app under every other session.
68+
A session that holds the whole Mac, including `open <app> --surface frontmost-app`, opens the app in
69+
front as before.
6470

6571
## Rejected alternatives
6672

‎website/docs/docs/commands.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -348,7 +348,7 @@ agent-device snapshot -i --platform apple --target desktop
348348
- Use `click --button secondary` for context menus on macOS, then run `snapshot -i` again.
349349
- On `frontmost-app` and `menubar` surfaces, `press` and `click` post synthetic mouse events through the macOS helper (the `desktop` surface inspects only): `--hold-ms` is how long the button stays down (at least 40 ms, 60 ms by default, because AppKit drops a release posted in the same tick as its press), `--count` is that many independent clicks (apps that detect a double-click by timing, such as Finder, still read two clicks at the default interval as one; pass an `--interval-ms` longer than the system double-click time to keep them apart), and `--double-tap` posts each click as a double-click pair. A long schedule such as `--hold-ms 10000 --count 4` is given the time it needs, and a helper stopped mid-hold — by a cancelled request, a dropped client, or its deadline — releases the button before it exits. `--jitter-px` is not applied on these surfaces.
350350
- With `AGENT_DEVICE_MACOS_APP_BACKEND=native`, macOS app sessions run without XCTest: no Automation Mode overlay, the app can stay behind other windows, and the real pointer stays with you while a drawn pointer shows each action. `click`, `press`, and `fill` use accessibility actions on the element at their target point, which must lie inside one of the app's own on-screen windows and not on its menu bar; `type` inserts at the focused control and falls back to key events sent to the app; `scroll` moves the accessibility scroll bar under the front window's center. Chromium-based apps expose their full tree. The daemon then never starts the Apple runner on macOS: `record`, `prepare`, `back`, `longpress` and `--hold-ms`, `--double-tap`, `--button secondary`, and gestures are refused with `UNSUPPORTED_OPERATION` (`reason: unsupported-device-backend`), as is a click on an element with no accessibility action. Use the default XCTest backend for those. `screenshot` captures only the app's front window, even when other windows cover it.
351-
- With the native backend, `open <app>` launches or reopens the app without bringing it to the front, and an app session claims only its app, not the whole Mac: sessions in other daemons (separate `AGENT_DEVICE_STATE_DIR`s) or other sessions of the same daemon can drive other apps at the same time, while a second session on the same app gets `DEVICE_IN_USE`. Desktop, `menubar` and `frontmost-app` sessions, XCTest sessions, and opens of a URL alone still claim the whole Mac, which excludes every app claim. An app session cannot reopen another app or surface; close it or use another `--session`. Two copies of one app need distinct bundle ids. Screenshots from all sessions on the Mac are taken one at a time.
351+
- With the native backend, an app session claims only its app, not the whole Mac, and `open <app>` launches or reopens that app without bringing it to the front: sessions in other daemons (separate `AGENT_DEVICE_STATE_DIR`s) or other sessions of the same daemon can drive other apps at the same time, while a second session on the same app, including a `macos-app` lease session, gets `DEVICE_IN_USE`, or waits for it under `open --wait`. Desktop, `menubar` and `frontmost-app` sessions, XCTest sessions, and opens of a URL alone still claim the whole Mac, which excludes every app claim. An app session cannot reopen another app or surface; close it or use another `--session`. Two copies of one app need distinct bundle ids. Screenshots from all sessions on the Mac are taken one at a time.
352352
- Mobile-only helpers are unsupported on macOS: `boot`, `shutdown`, `home`, `orientation`, `app-switcher`, `action-button`, `fold`, `install`, `reinstall`, `install-from-source`, and `push`.
353353
354354
Recommended loops:

0 commit comments

Comments
 (0)