macOS: decide the public surface for "do not activate this app" (the --foreground axis collision) #3338

Purpose

Decide the public surface for "do not bring this app forward" on macOS. Two different axes currently
want the same word: --foreground already means "include an initial interactive snapshot in a fresh
open response" (packages/command-registry/src/flag-definitions-action.ts, key foreground:
recorded: false, projectConfig: false, and foreground: req.flags?.foreground === true && openTarget === undefined
in src/daemon/session-lifecycle/internal/session-open-execution.ts:524), while #3254 proposal 1 asks
for "do not activate the app unless --foreground is passed". #3254 says nothing about which
reading wins; #3323 implements a third answer (open -g keyed off the daemon's app backend, no flag);
nothing yet states the contract. This issue is that decision. It does not ask for an implementation to
be guessed ahead of it.

Why a runner-side "skip activation" is not free

Measured on a macOS host against the built runner (System Settings as the app under test):

• A backgrounded macOS app can answer a stale or sparser tree: the same snapshot answered 146
  nodes in the foreground and 143 in the background. A control (foreground → background →
  foreground again) showed 38 name-matched rows with a moved rect for the foreground-vs-background
  pair and 39 for foreground-vs-later-foreground, so the rect drift is time and relayout, not
  foreground state — an earlier "79 of 143" figure in this body was an index-alignment artifact and
  is corrected. Content staleness remains possible (AppKit defers work in the background), and a
  background read carries no foreground disclosure. fix(apple-runner): serve a macOS read of a background app without raising it #3339 ships background reads on this evidence
  with a live check; treat the residual risk as accepted, not unknown.
• An app-targeted screenshot on the XCTest backend is a screen-region grab, so a background
  window comes back with the occluding app's windows in it; activate() first returns the app's own
  content. This is why the window-level capture in RunnerTests+CommandExecution.swift keeps its
  raise (measured, not assumed) and why the helper's SCContentFilter(desktopIndependentWindow:)
  path exists. Note the backend split: on the default XCTest backend the helper's window capture
  never runs (macOsSurfaceBackend in packages/contracts/src/session-surface.ts routes the app
  surface to the helper only under appBackend === 'native'), so --fullscreen is the only
  non-raising capture fix(apple-runner): serve a macOS read of a background app without raising it #3339 adds there.
• What the host can do without the runner is the native backend (AGENT_DEVICE_MACOS_APP_BACKEND=native,
  ADR 0031), which already acts through accessibility actions. So the flag question is mostly about
  open plus how one asks the XCTest backend to stay out of the user's screen, if it ever can.

Options, with their costs

A. Overload --foreground. Recommended against (see the recommendation comment for the full
case). Today open without it means "no initial snapshot"; src/mcp/server-guide.ts:20 and
skills/agent-device/SKILL.md:11 both instruct agents to always pass it, so "the agent's default
spelling" of an overloaded flag would mean "activate" — preserving exactly the behavior #3254 asks
to escape. The flag is recorded: false, so .ad replay cannot carry it, and
parseReplayOpenFlags (packages/ad-script/src/internal/open-script.ts) knows only --surface,
--relaunch, and --test-ime: any other token falls through into positionals, so an overloaded
--foreground in a recorded open would silently become an app-argument on replay. The flag is also
platform-neutral: iOS simctl launch and Android am start have no non-activating form, so the
overload would have to mean "activate only if the platform can", putting two unrelated promises in
one usageDescription. Do not pick this without accepting the replay default flip.

B. A dedicated activation flag (e.g. --no-activate). Costs the full threading
docs/agents/cli-flags.md lists: packages/contracts/src/cli-flags.ts, the
packages/command-registry/src/flag-definitions-*.ts owner plus its flag-groups.ts group, the open
family metadata and input schema (src/commands/management/app.ts, which today declares
foreground: optionField('foreground') and no activation key), the src/commands/cli-grammar/*
reader, src/commands/command-projection.ts, src/client/client-types.ts and
src/client/client-normalizers.ts if Node/MCP expose it, src/daemon/context.ts and
src/core/dispatch-context.ts, the handler/platform modules, the
scripts/integration-progress-model.ts classification, and a pass over
packages/contracts/src/interaction-guarantees.ts if it changes interaction semantics. Also needs a
scoping answer: is it an open option, or does it apply to every command that names the app?

C. No flag: the backend is the switch. #3323 already does this for open alone
(const openOptions = { background: hostMacOsAppBackend() === 'native' }), i.e. native backend ⇒
open -g, XCTest backend ⇒ activating open. Cheapest, and consistent with ADR 0031's opt-in model,
but it gives the operator no way to ask for a foreground open on the native backend, and it says
nothing about the commands that still activate on both backends. Note the side effect #3323 carries:
under the native backend, open <app> --surface frontmost-app stops bringing the app forward (its
ADR 0031 update states this) — an undecided behavior change riding along with the backend switch
that this decision should ratify or reject explicitly.

Required behavior

One of A, B, or C is chosen by a maintainer and written where semantics are owned: the flag definition's
usageDescription/inputDescription (versioned CLI help) for A or B, or the ADR 0031 rule plus
website/docs/docs/commands.md for C. The chosen reading must be one sentence that does not mention
the other axis.

Observable completion

• agent-device help open states the activation contract in one place, and no second prose copy
  restates it in a way that can drift.
• If a flag is added: its decode and daemon projection are tested, projectConfig/recorded are
  chosen deliberately and justified, and scripts/integration-progress-model.ts classifies it (the
  architecture-progress gate fails CI on an unclassified public flag).
• If --foreground is overloaded: an existing .ad replay's behavior change is named in the changelog,
  because a recorded: false flag is absent from every existing recording.
• The macOS docs continue to name which commands can still activate the app or move the real pointer.

Depends on: none for the decision itself. #3254 proposal 1, #3323 rule 7, and #3213 item 13 (which is
what would make non-activating raw-coordinate interaction possible at all) each take this answer as
input.