Merge remote-tracking branch 'origin/main' into HEAD

* origin/main:
  perf: bundle runtime dependencies and report full install size (#2310)
  ci: avoid unrelated Apple runner cache invalidation (#2303)
  fix(web): preserve the backend ref so snapshot refs match actionable refs (#2283)
  test(daemon): session-open-url-prewarm through the request seam (#2304)
  test(daemon): session-devices-batch-runtime through the request seam (#2305)
  chore(gates): layering baselines ratchet against merge-base (#2299)
  test(daemon): one typed conformance helper for the daemon runtime suites (#2298)
  chore(layering): derive the contracts export inventory from package.json (#2297)
  perf: bundle tar-stream to reduce install footprint (#2286)
  docs: simplify agent context and resolve conflicting guidance (#2287)
  refactor(cli): let help resolve command aliases itself and retire R12 (#2293)

Author: thymikee

.github/actions/setup-apple-runner-build/action.yml

@@ -44,7 +44,7 @@ runs:
       id: source-hash
       run: |
         set -euo pipefail
-        echo "value=${{ hashFiles('apple/runner/**', 'apple/snapshot-presentation/**', 'scripts/build-xcuitest-apple.sh', 'scripts/patch-xcuitest-runner-icon.ts', 'scripts/write-xcuitest-cache-metadata.mjs', 'packages/platform-apple/src/runner/apple-runner-platform.ts', 'packages/platform-apple/src/runner/runner-cache-metadata.ts', 'packages/platform-apple/src/runner/runner-icon.ts', 'packages/platform-apple/src/runner/runner-xctestrun.ts', 'packages/platform-apple/src/runner/runner-xctestrun-products.ts', '.github/actions/setup-apple-runner-build/action.yml', 'package.json', 'pnpm-lock.yaml') }}" >> "$GITHUB_OUTPUT"
+        echo "value=${{ hashFiles('apple/runner/**', 'apple/snapshot-presentation/**', 'scripts/build-xcuitest-apple.sh', 'scripts/swift-toolchain-tmpdir.ts', 'scripts/patch-xcuitest-runner-icon.ts', 'scripts/write-xcuitest-cache-metadata.mjs', 'packages/platform-apple/src/runner/apple-runner-platform.ts', 'packages/platform-apple/src/runner/runner-cache-metadata.ts', 'packages/platform-apple/src/runner/runner-icon.ts', 'packages/platform-apple/src/runner/runner-xctestrun.ts', 'packages/platform-apple/src/runner/runner-xctestrun-products.ts', '.github/actions/setup-apple-runner-build/action.yml') }}" >> "$GITHUB_OUTPUT"
       shell: bash
 
     - name: Resolve Apple runner build variant
@@ -55,12 +55,19 @@ runs:
         INPUT_XCUITEST_DESTINATION: ${{ inputs.xcuitest-destination }}
       run: |
         set -euo pipefail
+        BUILD_COMMANDS="$(node -p 'JSON.stringify(Object.entries(require("./package.json").scripts).filter(([name]) => name.startsWith("build:xcuitest:")))')"
         VARIANT="$(
           printf '%s\n' \
             "$INPUT_GATE" \
+            "$BUILD_COMMANDS" \
+            "$(uname -m)" \
             "$INPUT_XCUITEST_PLATFORM" \
             "$INPUT_XCUITEST_DESTINATION" \
             "${AGENT_DEVICE_XCUITEST_INCLUDE_UNIT_TESTS:-0}" \
+            "${AGENT_DEVICE_XCUITEST_ARCHS:-}" \
+            "${AGENT_DEVICE_IOS_BUNDLE_ID:-}" \
+            "${AGENT_DEVICE_IOS_RUNNER_APP_BUNDLE_ID:-}" \
+            "${AGENT_DEVICE_IOS_RUNNER_TEST_BUNDLE_ID:-}" \
             | shasum -a 256 \
             | cut -c1-16
         )"
@@ -89,4 +96,23 @@ runs:
       uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.2.3
       with:
         path: ${{ inputs.derived-path }}
-        key: ${{ inputs.cache-key-prefix }}-${{ steps.xcode.outputs.key }}${{ inputs.cache-key-suffix }}-${{ steps.build-variant.outputs.key }}-${{ steps.source-hash.outputs.value }}
+        key: ${{ steps.restore-runner-build.outputs.cache-primary-key }}
+
+    - name: Report Apple runner build cache
+      env:
+        CACHE_HIT: ${{ steps.restore-runner-build.outputs.cache-hit }}
+        CACHE_KEY: ${{ steps.restore-runner-build.outputs.cache-primary-key }}
+        BUILD_GATE: ${{ inputs.gate }}
+      run: |
+        set -euo pipefail
+        if [ "$CACHE_HIT" = 'true' ]; then
+          RESULT='restored exact prebuilt runner; compilation skipped'
+        else
+          RESULT='cache miss; built runner and attempted cache save'
+        fi
+        {
+          printf '### Apple runner cache (%s)\n\n' "$BUILD_GATE"
+          printf '%s\n\n' "$RESULT"
+          printf 'Key: `%s`\n' "$CACHE_KEY"
+        } >> "$GITHUB_STEP_SUMMARY"
+      shell: bash

.github/workflows/ci.yml

@@ -100,8 +100,12 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
+      # The layering ratchets (R6/R9/R10) measure the merge-base with origin/main, which a
+      # shallow checkout cannot reach.
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
 
       # The layering gate parses production sources with `oxc-parser`, so
       # dependencies are required; keep install-deps enabled.
@@ -117,7 +121,7 @@ jobs:
 
       # Model tests for the dependency-graph report and its blast-radius query. The report
       # reads the gate's model (scripts/layering/model.ts) and applies the gate's own R6
-      # counting rule, so it is not a second measurement of TYPE_INVERSION_BASELINE.
+      # counting rule, so it is not a second measurement of the R6 ratchet.
       - name: Check the depgraph report model
         uses: ./.github/actions/run-gate
         with: { gate: depgraph }

.github/workflows/size.yml

@@ -99,6 +99,15 @@ jobs:
             --startup-runs 7 \
             --json .tmp/size-report.json \
             --markdown .tmp/size-report.md
+          cp /tmp/agent-device-size-base.json .tmp/size-report-base.json
+
+      - name: Upload detailed size reports
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: size-report
+          path: .tmp/size-report*.json
+          include-hidden-files: true
+          if-no-files-found: error
 
       - name: Add job summary
         run: cat .tmp/size-report.md >> "$GITHUB_STEP_SUMMARY"

AGENTS.md

@@ -3,8 +3,9 @@
 `agent-device` is a CLI and daemon for automating Apple, Android, HarmonyOS, Vega, Linux, and web
 targets. A long-lived daemon owns sessions; registry-derived commands route to platform runtimes.
 
-This file contains repository-specific traps and invariants that are expensive to rediscover. Load
-task procedures only when needed:
+## Task routing
+
+Load only the procedures relevant to the task:
 
 | When the task involves | Read |
 | --- | --- |
@@ -14,35 +15,28 @@ task procedures only when needed:
 | Selector capture, polling, or interaction fast paths | `docs/agents/selector-capture.md` |
 | Adding or changing a CLI flag | `docs/agents/cli-flags.md` |
 | Opening or reviewing a PR | `docs/agents/pull-requests.md` |
-| Running against a real device | `docs/agents/device-verification.md` |
+| Apple runner changes or manual device verification | `docs/agents/device-verification.md` |
 | Writing issues or PRDs, and triage labels | `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md` |
 | Web backend setup or diagnostics | `docs/agents/web-backend.md` |
 
-Versioned CLI help is the source of truth for command behavior. Start with `agent-device help
-workflow`, then the relevant topic help.
+Versioned CLI help owns command semantics. Read the relevant topic when behavior is unclear;
+normal app-driving startup follows the skill's routing card.
 
 ## Incident-derived principles
 
-- Guarantees erode at path boundaries. Classify every interaction dispatch path in
-  `packages/contracts/src/interaction-guarantees.ts`; a registry claim is not proof that the native
-  implementation satisfies the guarantee's definition.
+- Classify interaction dispatch paths in `packages/contracts/src/interaction-guarantees.ts` and
+  verify each claim against the native implementation.
 - Delegation on error proves no success-path parity. A fast path may succeed on a candidate the
   shared rules would refuse.
-- Prove that a code path can fire before measuring it. An A/B test with an unreachable arm is two
-  green runs without evidence.
-- A green regression test counts only after it has been observed red against the pre-fix code. Plant
-  a violation for new structural gates and verify the gate names the invariant.
-- Repair recurring failures at their owning interface with types, a registry, or one construction
-  path. A custom guard that reconstructs another source of truth needs redesign, not another
-  exception.
-- Treat explanatory implementation comments as a failed design review. Do not narrate control flow,
-  preserve review history, or justify a workaround in code. Express the invariant through names,
-  types, module boundaries, and tests; put history in the PR or an ADR. Allow only public API docs,
-  tool directives, and a brief citation to an external constraint that cannot be encoded.
-- Key behavior on typed reasons and details, never error text. Existing message sniffs are owned debt
-  and must not be copied.
-- Snapshot output is the token budget: do not add per-node metadata when response-level metadata can
-  be emitted once. Append warnings through the shared response builder; never replace prior warnings.
+- Prove both paths are reachable before measuring a fast path against its baseline.
+- Repair recurring failures at the owning type, registry, or construction path; do not add guards
+  that reconstruct another source of truth.
+- Keep control-flow narration and review history out of implementation comments. Encode invariants
+  in names, types, boundaries, and tests; reserve comments for public API docs, tool directives,
+  and non-obvious constraints that cannot be encoded.
+- Key behavior on typed reasons and details, never error text; do not copy existing message sniffs.
+- Keep metadata at response level when it applies to the whole snapshot. Append warnings through
+  the shared response builder; never replace prior warnings.
 - Before preserving a compatibility shape, run `git tag --contains <commit>`. Unreleased API has no
   external compatibility obligation.
 
@@ -66,10 +60,10 @@ and progress in `@agent-device/capture-kit` (`request-cancel`, `request-progress
 contracts in `@agent-device/contracts`; CLI flags in `src/commands/cli-grammar`; cross-surface schema
 composition in `src/cli-schema`.
 
-The enforced registries are self-declaring. A failing completeness, parity, coverage, timeout,
-layering, or construction gate means the new cell or path is unclassified; do not suppress or
-allowlist it. Interaction responses are built only through `buildInteractionResponseData`, and
-cross-language rules change through golden tables under `contracts/fixtures/`.
+Resolve registry completeness failures at the missing declaration. Diagnose other gate failures
+at their reported invariant; do not suppress them or add an allowlist to get a pass. Build interaction
+responses through `buildInteractionResponseData`; change cross-language rules through golden tables
+under `contracts/fixtures/`.
 
 ## Hard repository rules
 
@@ -78,9 +72,9 @@ cross-language rules change through golden tables under `contracts/fixtures/`.
 - Apple target changes keep the kernel device model, runtime-fact admission, dispatch resolution,
   Apple discovery, and xctestrun preparation in sync.
 - iOS simulator-set scoping must never hide the host macOS desktop target.
-- Skills may carry a minimal start/routing card; command semantics belong in versioned CLI help.
-- Do not add compatibility or fallback behavior without explicit approval. Complete migrations and
-  remove superseded paths.
+- Skills stay minimal routing cards.
+- Add compatibility or fallback behavior only when explicitly requested or approved. Otherwise,
+  complete the migration and remove superseded paths.
 - Keep changes within one command family or module group unless the task explicitly crosses a
   boundary. Platform-neutral work does not license inspecting every platform implementation.
 
@@ -93,7 +87,6 @@ cross-language rules change through golden tables under `contracts/fixtures/`.
 - Tests mirror source topology one-to-one. Split a source module and its test together; do not add to
   the legacy `interaction.test.ts` or platform `index.test.ts` aggregations. Pure moves carry their
   tests unchanged; rename-only hunks owe no new coverage.
-- Shared fixtures are named exports in a sibling fixture module, not repeated inline literals.
 - `src/daemon/handlers/session.ts` is already over budget; extract the relevant platform-specific
   concept before adding behavior.
 
@@ -103,30 +96,14 @@ cross-language rules change through golden tables under `contracts/fixtures/`.
   repository-wide, not path-scoped.
 - A fresh worktree requires `pnpm install --frozen-lockfile && pnpm build`. Until then package and
   optional-peer resolution may point at another checkout and produce false failures.
-- Source-checkout daemon state is worktree-scoped, but devices are not. Use `pnpm daemon:state-dir`
-  to inspect it and different devices for concurrent worktrees.
-- Run one full gate per host at a time. Subprocess-backed tests under concurrent worktrees produce
-  timeout-shaped contention failures.
-- Before pushing, run `pnpm check:affected --run && git push`. Use `pnpm check` for broad refactors.
-  GitHub remains authoritative for native, device, provider, and full-coverage lanes.
+- Parallel work needs disjoint edit ownership and distinct devices. Run one full gate per host;
+  concurrent subprocess-backed suites can produce contention timeouts.
 - The layering scan reads tracked files only. Stage a new module before trusting its result.
 - Fallow baselines are path-keyed. Move the matching baseline entry when renaming a file; never bulk
   regenerate baselines to accept unrelated findings.
-- The first Node process after a newly signed Apple runner launches may block during Gatekeeper
-  verification. Warm it with a throwaway `node -e 0` before measuring.
-- `DEVICE_IN_USE` has two flavors. "already in use by session X" is this daemon — follow its
-  `close --session` hint. "owned by session X in workspace Y" is another worktree's device
-  claim — non-retriable; run the error's `device status`/`device release --stale` recovery,
-  never PID hunting.
-- A changing timeout failure set that passes in isolation is host contention. Reproduce the same
-  test on `origin/main` under the same load before treating it as a regression.
 
 ## Runtime and diagnostics seams
 
-The OS-neutral Apple runner lives under `packages/platform-apple/src/runner/`. For connection errors,
-retry policy, or command typing, start at `runner-contract.ts`; transport stays below session/client
-behavior, and xctestrun build/cache logic stays outside request execution.
-
 Diagnostics use `@agent-device/capture-kit/diagnostics`. Request diagnostics belong in the session request log;
 session artifact paths come from `src/daemon/session-store.ts`. App/device logs remain in `app.log`;
 Apple runner and xcodebuild output remains in `runner.log`.
@@ -150,11 +127,8 @@ translate through the interaction root frame. Prefer selector or ref tests over
 
 ## Documentation ownership
 
-Before adding guidance, decide whether the command surface, CLI grammar/help, MCP projection, daemon
-runtime, ADR, or task procedure owns it. Link to executable registries instead of copying their
-contents. Keep a sentence in this file only when no gate, lint rule, versioned help, ADR, or
-decision-site comment can own it. `CONTEXT.md` is glossary-only: no implementation paths,
-architecture decisions, migration state, or workflows.
+Keep this file to repository traps and routing. Put task procedures in `docs/agents/`, decisions in
+ADRs, and command semantics in versioned help. Link to executable registries instead of duplicating
+their rules. `CONTEXT.md` is glossary-only: no implementation paths, decisions, or migration status.
 
-Behavior changes update their owning help/metadata and user docs. In the final summary,
-state whether docs or skills changed and why.
+Behavior changes update owning help/metadata and user docs. Report docs or skill changes when relevant.

docs/agents/cli-flags.md

@@ -1,16 +1,14 @@
 # Adding a CLI Flag
 
-A new flag touches only the layers that need to understand it. Stop at the layer where it stops
-mattering — threading it further is the common failure, not stopping too early.
+Thread a flag only through the layers that consume it:
 
 1. `packages/contracts/src/cli-flags.ts`: add to `CliFlags`; add the definition to the matching
    `src/commands/cli-grammar/flag-definitions-*.ts` owner and the relevant group in `flag-groups.ts`
    (for example `SNAPSHOT_FLAGS`). Then update the command family metadata/schema that exposes the
    flag; find the owner with
    `rg -n "<command>|supportedFlags|allowedFlags" src/commands src/cli-schema src/cli/parser`. For
-   schema-only CLI commands (`cdp`, `auth`, `connect`, `proxy`, `react-devtools`, `web`) the owner is
-   `SCHEMA_ONLY_CLI_COMMAND_SCHEMAS` in `src/cli-schema/command-overrides.ts`. New flags are
-   operator-only by default. Add a flag to `PROJECT_CONFIG_FLAG_KEYS` in
+   schema-only CLI commands, the owner is `SCHEMA_ONLY_CLI_COMMAND_SCHEMAS` in
+   `src/cli-schema/command-overrides.ts`. New flags are operator-only by default. Add a flag to `PROJECT_CONFIG_FLAG_KEYS` in
    `src/cli-schema/cli-config.ts` only when repository control is safe; this positive allowlist is
    the completeness gate.
 2. `src/commands/cli-grammar/*`: read the CLI flag into command input.