Remote lease backend that confines a proxy client to one macOS app

[janicduplessis]

Problem

A remote agent cannot be handed one macOS app on a proxy host. Through agent-device proxy plus connect proxy, devices --platform macos lists the host Mac, but open is refused: LEASE_BACKEND_BY_PLATFORM in packages/kernel/src/contracts.ts has entries only for ios, android and harmonyos, and its comment says the macOS desktop host maps to no backend on purpose. Observed on 0.21.12 (and reported on 0.21.20), and the same mapping is on main (2f933e5). #2989 (platform axis) does not change this.

The refusal is correct for a whole desktop: a macOS device is the host Mac, and a lease on it would give the client desktop, frontmost-app and menubar surfaces, any other app's windows, install and launch of arbitrary apps, and full-screen capture. Nothing in the current lease model can say "this client may drive this one app and nothing else".

Use case: a host Mac runs an app under test for a developer on another Mac, and the developer's coding agent should snapshot, click, type and screenshot that app through the host's proxy, without being able to touch the host's other apps or windows. This is what Stim (appandflow/stim#2477) needs to let agents drive an app it runs on another Mac.

What exists and why it is not enough

• Leases (ADR 0007) rent one device by backend + provider + deviceKey. For macOS the device is the whole host.
• Daemon policy (feat: add daemon policy to confine devices, commands, and device shutdown #3064, ADR 0029) confines a daemon to allowed devices and commands. It is per daemon, not per lease, and its device scope is the host Mac, so it cannot name a bundle id. A policy alone cannot express "this client, this app".
• macOS native app backend (ADR 0031, AGENT_DEVICE_MACOS_APP_BACKEND=native) drives one session app through accessibility actions without Automation Mode and captures that app's front window. It is the right engine for this, but the session app is chosen by the client's open, and nothing restricts which app.
• Human-control holds (feat: add human takeover controls #2078) already use a host-only loopback admin route that supplies an exact lease device scope with the local daemon token. That is the pattern for a host administrator pinning a scope.
• retainOnClose (feat(daemon): keep a caller-owned lease through session close with retainOnClose #3208) already gives a caller-owned lease lifecycle.
• Explicit macOS surface is lost from recorded actions and replay scripts #3216 / fix(recording): preserve explicit macOS session surfaces #3217 (explicit macOS surface lost from recorded actions) are related: a scoped lease needs the explicit surface visible in admission and the journal, so the two should agree on how an explicit --surface is carried.

Proposal

Add one lease backend, macos-app, whose device key is exactly one app: a bundle id, optionally with a pid (<bundleId> or <bundleId>@<pid>). It follows the shape of the harmonyos-instance backend (#2266: about 300 added lines across 17 files, most of them tests and wire-compat ledger entries).

Admission rules for a macos-app lease

All refusals use the existing typed error with a do-not-retry hint, and apply inside the daemon so batch and replay steps are covered the way #3064 covers them.

1. open accepts only the leased bundle id (and, if the key has a pid, only that process). Any other app is refused. open with an explicit --surface other than app is refused.
2. desktop, frontmost-app and menubar surfaces are refused for the lease's lifetime, including on commands that carry a surface after open.
3. install, install-from-source and launching any app other than the leased one are refused.
4. Screenshots are limited to the leased app's window. Whole-screen capture and screen recording are refused (ADR 0031 item 6 already makes the app-surface screenshot a single window; this makes it an enforced guarantee).
5. Commands that act outside the app are refused: system alerts, clipboard, settings, and anything else not on an allow list the backend declares. An allow list fails closed for commands added later, as in ADR 0029.
6. If the leased process exits, or a pid-pinned key no longer matches the running process, the lease is no longer usable and requests fail with a typed error. A bundle-only key follows the next process of that bundle.
7. snapshot and refs only ever describe the leased app's windows.

Who allocates it

A tenant cannot allocate a macos-app lease for an arbitrary bundle, or the scope would be self-chosen. A host administrator allocates it over the existing loopback-only, daemon-token route used by human-control holds, and the proxy does not forward it:

PUT /admin/leases/<leaseId>
{ "tenantId": "...", "runId": "...", "clientId": "...",
  "leaseBackend": "macos-app", "leaseProvider": "proxy",
  "deviceKey": "com.example.app@12345", "ttlMs": 300000, "retainOnClose": true }
DELETE /admin/leases/<leaseId>

The client then connects with the usual --remote-config fields it already accepts (daemonBaseUrl, daemonAuthToken, leaseId, leaseBackend: "macos-app", platform: "macos") and runs open <bundleId> --platform macos. Tenant-side lease_allocate for macos-app is refused. Heartbeat and release behave as for other leases, and an admin DELETE revokes access at once. Like other proxy leases (ADR 0007), it does not survive a daemon restart; the host administrator re-allocates it, and the client sees the typed inactive-lease error until then.

If a loopback admin route for leases is too large a surface, an acceptable smaller variant is to let the host start the daemon with a policy entry that declares which macos-app keys tenants may allocate ("leases": { "macos-app": { "allow": [{ "bundleId": "..." }] } }), reusing the ADR 0029 file and fail-closed loading. A host that runs one app per client would start one policy per allowed bundle, and the admin route would not be needed.

What a host integrator needs to detect support

A way to learn that the daemon supports the backend before it hands a client access, for example leaseBackends in /health (or the daemon-policy digest work #3064 mentions as a follow-up). Without it, the integrator can only compare versions.

Alternatives considered

• One daemon per app, confined by daemon policy. Works today for commands, but policy cannot name a bundle id, so the daemon still reaches the whole desktop. Adding apps.allow to the policy would work and is a smaller change, at the cost of one daemon, state directory and port per hosted app. Acceptable fallback; a lease backend lets one daemon serve many apps.
• Leasing the whole host Mac. Rejected: gives the client the desktop.
• A client-side restriction. Rejected: the client is the untrusted party.

Non-goals

Other platforms, tenant self-service allocation, driving more than one app per lease, XCTest-backend specifics beyond refusing what leaks outside the app, and changes to ADR 0031's default backend.

Acceptance

• A proxy client holding a macos-app lease can open, snapshot, click, fill, screenshot and close the leased app, and every rule above is refused with a typed error, including through batch.
• A second app running on the host is invisible to snapshot and unreachable by open and by coordinates.
• A tenant cannot allocate or widen the lease; releasing it from the admin route stops the client at its next request.
• Tests mutation-check each rule, as feat: add daemon policy to confine devices, commands, and device shutdown #3064 did.