docs(adr): correct stale facts in the ADR set

docs/adr/0001-provider-first-integration-scenarios.md

@@ -192,13 +192,20 @@ The script is the source of truth for:
 
 These flags stay in their owning unit/CLI suites:
 
-- Config.
-- Remote transport.
-- Metro preparation.
-- Parser/client-only.
-- Report-writing.
-- Boot-fallback.
-
+- Config, output, diagnostics, and transport.
+- Remote connection and session-lock policy.
+- Cloud artifact provider lookup.
+- Metro and React Native runtime preparation.
+- Apple launch and perf artifact options.
+- Parser/client-only command flags.
+- Daemon lifecycle control.
+- Platform boot fallback without a provider seam.
+- Open foreground auto-resolution (RFC prototype).
+- Local device contention waiting.
+- Apple simulator screenshot, private-AX, and observe-only capture options.
+- Daemon screenshot selector crop.
+
+`summarizeProviderScenarioFlagExclusions` in `scripts/integration-progress-model.ts` is the full list.
 The report lists these flags as explicit exclusions, so they are not silently missing from the denominator.
 Provider pressure separates semantic Apple `simctl`/`devicectl`, macOS helper, and macOS host usage from generic Apple host-tool usage.
 It also separates semantic Linux desktop/accessibility/clipboard/screenshot/input usage from generic Linux tool usage.

docs/adr/0002-persistent-platform-helper-sessions.md

@@ -14,7 +14,7 @@ Accepted
 - When startup costs are high and an automation context is reusable, use persistent platform helper sessions.
 - The daemon owns helper lifetime policy. Platform modules own helper-manager mechanics.
 - Unless a separate cache contract has explicit invalidation, a helper must execute each command against fresh platform state.
-- On Android, snapshot capture, gesture viewport resolution, and planned-touch injection share one bundled automation helper.
+- On Android, snapshot capture, gesture viewport resolution, and instrumentation-backed planned-touch injection share one bundled automation helper.
 - On Android, after a failed session command, retry one-shot only for idempotent reads, and only after the failed session has stopped.
 - On Android, return a session gesture failure directly. Do not retry it one-shot.
 - For Android snapshots, if the packaged helper is unavailable or invalid, agent-device must fail closed. It must not substitute the legacy `adb uiautomator dump` snapshot engine.
@@ -87,7 +87,7 @@ If that helper is unavailable or invalid, agent-device must fail closed.
 It must not substitute the legacy `adb uiautomator dump` snapshot engine.
 
 Android permits only one reliable instrumentation-owned `UiAutomation` context per device.
-Thus, snapshot capture, gesture viewport resolution, and planned-touch injection share one bundled automation helper (amended 2026-07, issue #1275, consistent with ADR 0013).
+Thus, snapshot capture, gesture viewport resolution, and instrumentation-backed planned-touch injection share one bundled automation helper (amended 2026-07, issue #1275, consistent with ADR 0013).
 A live persistent helper session executes touch commands directly over its session socket.
 Without a live persistent session, the same helper runs one-shot.
 Before that amendment, touch synthesis shipped as a separate instrumentation helper.

docs/adr/0003-daemon-command-registry.md

@@ -2,16 +2,19 @@
 
 ## Status
 
-Accepted
+Accepted. Amended 2026-10-16: invariants 3 and 4 now describe the shipped derivation (#906, #907).
 
 ## Rules at a glance
 
 - Keep public command identity in `packages/command-registry/src/catalog.ts` and public input/output contracts in `src/commands/**`.
-- Keep daemon route ownership and request-policy traits in the daemon command registry.
+- Declare daemon route ownership and request-policy traits in the separately typed `daemon` facet of the descriptor registry.
+- Derive the daemon registry from that facet. Expose request-policy predicates only through the daemon registry.
 - Request modules consume named predicates from the registry. They do not recreate command string sets.
 - Handler modules own execution logic only. They do not export duplicate coverage tables to prove route membership.
 - The daemon registry must not define CLI grammar, Node.js client options, MCP schemas, user-facing help, or platform capability support.
-- A derived daemon registry is permitted only if it preserves all four invariants in the 2026-06 update.
+- Preserve all four invariants in the 2026-06 update.
+- Do not derive a public contract from daemon traits. A diagnostic display, such as `command explain`, may read them.
+- A command without a `daemon` facet uses the `generic` route with default request policy.
 
 ## Context
 
@@ -35,7 +38,9 @@ Duplicate command sets required alignment by convention.
 Keep public command identity in `packages/command-registry/src/catalog.ts`.
 Keep public input/output contracts in `src/commands/**`.
 
-Add `packages/daemon/src/core/daemon-command-registry.ts` as the daemon-side source of truth for command route ownership and request-policy traits.
+Declare command route ownership and request-policy traits in the `daemon` facet in `packages/command-registry/src/registry.ts`.
+`DaemonCommandDescriptor` in `packages/command-registry/src/daemon-command-descriptor.ts` types that separate facet.
+`packages/daemon/src/core/daemon-command-registry.ts` derives its table through `deriveDaemonCommandDescriptors(commandDescriptors)`.
 Request modules consume predicate functions from the registry.
 They do not recreate command string sets.
 Handler modules own execution logic only.
@@ -64,7 +69,8 @@ The command contract, projection, help, and capability modules retain these resp
 
 ## Consequences
 
-When a daemon-handled command is added or moved, its route and request-policy traits require updates in the daemon command registry.
+When a daemon-handled command is added or moved, update its `daemon` facet in `packages/command-registry/src/registry.ts`.
+The daemon registry derives its table from those declarations.
 The registry tests pin the trait decisions.
 Provider-backed integration scenarios verify important request-policy behavior through the real daemon request path.
 
@@ -79,7 +85,7 @@ Thus, future changes do not require readers to infer the rationale from agent in
 
 ## Update (2026-06): single-declaration / derivation model
 
-A later proposal, the `CommandDescriptor` direction in [ADR 0008](0008-command-descriptor-registry.md), unifies a command's declarations at one registration site.
+The implemented `CommandDescriptor` direction in [ADR 0008](0008-command-descriptor-registry.md) unifies a command's declarations at one registration site.
 It derives these surfaces from that site:
 
 - Public catalog.
@@ -89,15 +95,16 @@ It derives these surfaces from that site:
 - Daemon registry.
 
 Its purpose is to remove the drift between these tables.
-Convention keeps several of these surfaces aligned against that drift.
+Registry tests pin the derived tables.
 
 **This ADR's decision remains accepted.**
 Its boundary concerns ownership and the predicate interface, not the physical file that contains a trait.
 “Separate source of truth” means separate ownership and exposure through named predicates.
 That property remains true for a projected or derived backing table.
 A derived daemon registry is therefore permitted **only if** it preserves all these invariants:
 
-1. **Daemon-owned declaration.** A daemon-owned facet under `packages/daemon/src/` declares route and request-policy traits.
+1. **Daemon-owned declaration.** The separately typed `daemon` facet in `packages/command-registry/src/registry.ts` declares route and request-policy traits.
+   `DaemonCommandDescriptor` in `packages/command-registry/src/daemon-command-descriptor.ts` owns its type.
    The registration composes that facet.
    The public command contract in `src/commands/**` or `packages/command-registry/src/catalog.ts` must never contain these traits as inline fields.
    A registration call may be co-located with public declarations.
@@ -106,15 +113,20 @@ A derived daemon registry is therefore permitted **only if** it preserves all th
 2. **Predicate interface unchanged.** Consumers continue to use named predicates such as `getDaemonCommandRoute`, `isLeaseAdmissionExempt`, and `shouldLockSessionExecution`.
    Only the daemon registry exposes these predicates.
    Derivation changes table construction, not table access.
-3. **No leakage into public projections.** Types must prevent the catalog/CLI/MCP/help/capability projections from reading daemon-only traits.
-   The daemon registry must still not define CLI grammar, Node.js options, MCP schemas, user-facing help, or capability support.
-4. **One declaration per concern, enforced by types.** At the single registration site, a missing or duplicate daemon trait must cause a compile error.
-   This replaces alignment by convention.
-   This structural improvement justifies derivation instead of a separate hand-authored table.
+3. **No daemon traits in public contracts.** CLI grammar, Node.js client options, MCP schemas, user-facing help, and capability support must not derive from daemon-only traits.
+   A diagnostic display may read the `daemon` facet. `command explain` in `src/cli/command-explain.ts` displays routes and request-policy traits this way.
+4. **One declaration per command.** Each command has at most one `daemon` facet, at its registration in the descriptor registry.
+   No second table declares the same traits. This replaces alignment by convention, and it justifies derivation instead of a separate hand-authored table.
+   A command without a `daemon` facet uses the `generic` route with default request policy. The daemon registry tests pin the derived table.
 
 A single flat public descriptor that exposes daemon fields in public views is **not** permitted.
 This would combine daemon policy with a public command registry, which this ADR rejects.
 Compose facets owned by their domains.
 Derive the registry from those facets.
-Until that derivation is implemented and the registry tests pin it, the hand-authored `packages/daemon/src/core/daemon-command-registry.ts` remains the source of truth.
-Until then, the operating rule in `AGENTS.md` does not change.
+PR #906 introduced the descriptor and proved parity.
+PR #907 made the derivation live and deleted the hand-authored table.
+The daemon registry tests pin route and request-policy decisions.
+
+**Amendment 2026-10-16.** The 2026-06 text required types to stop every public projection from reading daemon traits, and required a compile error for a missing daemon trait.
+The shipped derivation does neither: `CommandDescriptorBase.daemon` is optional (`packages/command-registry/src/types.ts`), and a command without a facet gets the `generic` route.
+Invariants 3 and 4 now state the property that matters and that the code holds: no public contract derives from daemon traits, and no second table declares them.

docs/adr/0004-ios-snapshot-backend-strategy.md

@@ -17,7 +17,8 @@ Structured snapshot quality verdicts and fallback warnings make degraded or reco
 
 - Route eligible local iOS Simulator snapshots through the host AX bridge. Present them once through the shared TypeScript engine.
 - If bridge acquisition or presentation fails, use one typed XCTest fallback.
-- After fallback, disable the bridge for that app generation, except for capture-scoped failures. A new app generation enables it again.
+- After fallback, disable the bridge for that app generation, except for `preparing` failures and capture-scoped failures.
+  A new app generation enables it again.
 - A refusal that provides evidence about the screen, not the app, has capture scope.
 - Keep the regular visible strategy and the raw diagnostic strategy explicit as the two public snapshot strategies.
 - The regular visible strategy must not use an arbitrary node-count cutoff.
@@ -52,7 +53,9 @@ Keep XCTest as the iOS automation runner.
 Route eligible local iOS Simulator snapshots through the host AX bridge.
 Present them once through the shared TypeScript engine.
 If bridge acquisition or presentation fails, use one typed XCTest fallback.
-After fallback, disable the bridge for that app generation, subject to the capture-scoped exception below.
+After fallback, disable the bridge for that app generation, except for `preparing` failures and the capture-scoped exception below.
+A `preparing` failure describes a bridge preparation that is still running, not the app.
+It sends only that capture to XCTest.
 A new app generation enables it again.
 Physical devices, providers, custom-action captures, and interactions remain on their existing owners.
 

docs/adr/0005-ios-runner-interaction-lifecycle.md

@@ -7,7 +7,7 @@ Accepted
 ## Rules at a glance
 
 - For iOS/macOS selector taps on an element with a frame, use coordinate-first resolved element activation. tvOS remains focus/remote-driven.
-- Before a command to a ready session, send an `uptime` preflight, except for the stated startup, readiness, and recent-mutation cases.
+- Before a command to a ready session, send an `uptime` preflight, except for the stated startup, readiness, exempt-command, and recent-mutation cases.
 - Keep recent-mutation health only on the `RunnerSession` and only for the stated app, commands, response checks, and 5-second window.
 - Never count snapshots or other read-only responses as health signals.
 - Future optimization work should reduce the `uptime` preflights only after runner status survives command-induced XCTest teardown and can prove that the session still serves new requests.
@@ -45,6 +45,7 @@ tvOS remains focus/remote-driven because tvOS does not support normal coordinate
 Before command send, ready runner sessions receive a short `uptime` preflight.
 Read-only startup commands still skip that preflight because, for a newly launched runner, the first successful command is the readiness proof.
 Readiness probe commands skip preflight to avoid recursion.
+A ready session also skips the preflight for the preflight-exempt commands `activate`, `terminate`, and `targetReset` (`readinessPreflightExempt` in `RUNNER_COMMAND_TRAITS`).
 
 The daemon may also skip the ready-session `uptime` preflight for an explicit allowlist of mutating interactions:
 
@@ -53,6 +54,8 @@ The daemon may also skip the ready-session `uptime` preflight for an explicit al
 - `drag`.
 - `swipe`.
 - `scroll`.
+- `desktopScroll`.
+- `gesture`.
 - `sequence`.
 
 The skip requires that the same session produced a healthy mutating response for the same `appBundleId` within 5 seconds.

docs/adr/0006-daemon-rpc-protocol-version.md

@@ -91,7 +91,9 @@ Checks enforce the increment rules above, so nobody has to remember them (#1432)
 `test/wire-compat/ledger.json` records the hash of each declaration and the protocol version of that hash.
 The unit lane fails if the shape of a declaration changes and the ledger does not change with it.
 `pnpm check:daemon-wire-compat` compares the ledger with the last released tag.
-Drift since that release must carry either a protocol increment or a `compatibleChanges` acknowledgment that invokes the additive list above.
+A declaration removed since that release needs a protocol increment; an acknowledgment cannot cover a removal.
+A declaration changed since that release needs a protocol increment or a `compatibleChanges` acknowledgment that invokes the additive list above.
+Declarations added since that release need neither.
 One bullet is only partly digestible: the `/health` and `/rpc` path literals inside `http-server.ts`.
 For that gap, the manifest records the gap and its reason instead of implying coverage.
 See `test/wire-compat/README.md`.

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

@@ -41,7 +41,7 @@ It stays below daemon device leases and should not be weakened or replaced by th
 
 `open` is the natural point to acquire a device lease because target resolution and session creation meet there.
 Commands after `open` must refresh the lease.
-After five minutes without activity, the device should become available again.
+After the default 60 seconds without activity, the device should become available again.
 
 These operations must run under the same daemon request lock: