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)

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"

docs/dependency-graph-findings.md

@@ -22,8 +22,8 @@ const files = listSourceFiles();
 const sources = new Map(files.map((f) => [f, fs.readFileSync(f, 'utf8')]));
 const edges = resolveImportEdges(sources);
 
-// e.g. R6 inversions per zone pair, deduplicated by file pair — reproduces
-// TYPE_INVERSION_BASELINE, so a mismatch means one of the two is stale.
+// e.g. R6 inversions per zone pair, deduplicated by file pair — the same count the gate
+// ratchets against the merge-base with origin/main.
 const seen = new Set<string>();
 const byPair = new Map<string, number>();
 for (const edge of edges) {
@@ -126,8 +126,9 @@ narrow name replaced both.
   from `daemon-command-registry.ts` to key an exhaustive owner-file map; that remaining inversion
   is the commands-zone consumer, not a second source of truth for the union.
 
-All remaining inversions are argued at `TYPE_INVERSION_BASELINE` in `scripts/layering/check.ts`, next
-to the numbers they explain.
+All remaining inversions are argued here. R6 (`scripts/layering/type-inversion-ratchet.ts`) records
+no numbers of its own: its reference is the same count taken at the merge-base with `origin/main`,
+so a zone pair can only shrink.
 
 ## 0b. The biggest structural finding is not an inversion
 
@@ -156,13 +157,13 @@ but it is a comprehension one, and it is the single largest obstacle to reading
 isolation. At the current measured commit it spans `commands` (33), `daemon-server` (30),
 `platforms` (19), `core` (12), root composition (5), `contracts` (2), and `client` (1).
 
-Now ratcheted for growth by **R9** (`TYPE_CYCLE_BASELINE`, derived from the zone ceilings in
-`scripts/layering/daemon-modularity.ts`), so it cannot get worse
+Now ratcheted for growth by **R9** (`scripts/layering/daemon-modularity.ts`), so it cannot get worse
 while nobody is looking — a type-only import that closes a new loop fails the gate, verified by
 adding one type-only import that closes a loop and watching the gate reject it. It was growth-only
-here; #1781 A6 made it an equality pin, so a baseline left above the measured size fails too and a
-shrink is banked by the change that earns it. The refactor itself is still deliberately not
-attempted; it starts at those four hubs.
+here; #1781 A6 made it an equality pin, and the pin is now the merge-base's own measurement
+(`scripts/layering/ratchet-reference.ts`), so a shrink is banked the moment it merges and there is
+no slack left to spend. The refactor itself is still deliberately not attempted; it starts at those
+four hubs.
 
 ### The facade cycle: investigated, no narrower port exists
 
@@ -183,14 +184,15 @@ duplicate the public API shape — a second source of truth for it — or derive
 carry the same dependency.
 
 Those four files are therefore the minimum number of naming sites, not an accident: they are the
-choke point. Accepted as a position, argued at `TYPE_INVERSION_BASELINE`. The option this section
+choke point. Accepted as a position, argued in §0 above. The option this section
 used to hold open — moving `NAVIGATION_COMMAND_PROJECTIONS` out of `commands/` — was answered by
 deleting it: five direct signatures replaced the registry, so there is no longer a projection
 registry whose home is in question.
 
 ## 1. The two remaining type-inversion clusters
 
-`TYPE_INVERSION_BASELINE` in `scripts/layering/check.ts` holds both, with the reasoning inline.
+§0 above holds both, with the reasoning inline; the gate measures them against the merge-base
+rather than recording them.
 
 **28 + 1 edges → `client/client-types.ts`** — *done, mostly.* Now 5 edges. The vocabulary moved into
 the `contracts/client-*.ts` family files — one file per command/domain family, largest 137 LOC —

package.json

@@ -265,14 +265,6 @@
     "maestro",
     "detox"
   ],
-  "dependencies": {
-    "@limrun/api": "^0.24.5",
-    "ipaddr.js": "^2.5.0",
-    "tar-stream": "^3.2.0",
-    "undici": "7.29.0",
-    "yaml": "^2.9.0",
-    "yauzl": "^3.4.0"
-  },
   "peerDependencies": {
     "ai": "^6.0.0 || ^7.0.0"
   },
@@ -303,6 +295,7 @@
     "@agent-device/xml": "workspace:*",
     "@arethetypeswrong/cli": "^0.18.5",
     "@chenglou/freerange": "^0.0.4",
+    "@limrun/api": "^0.24.5",
     "@nkzw/eslint-plugin": "^2.0.0",
     "@nkzw/oxlint-config": "^1.3.0",
     "@stryker-mutator/core": "10.0.0",
@@ -318,14 +311,19 @@
     "eslint-plugin-perfectionist": "^5.10.1",
     "fallow": "^2.104.0",
     "fast-check": "^4.9.0",
+    "ipaddr.js": "^2.5.0",
     "oxc-parser": "^0.146.0",
     "oxfmt": "^0.64.0",
     "oxlint": "^1.79.0",
     "pngjs": "^7.0.0",
     "publint": "^0.3.24",
+    "tar-stream": "^3.2.0",
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",
+    "undici": "7.29.0",
     "vite": "^8.2.1",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "yaml": "^2.9.0",
+    "yauzl": "^3.4.0"
   }
 }

packages/host-kit/package.json

@@ -6,13 +6,13 @@
   "description": "Private host-mechanics package: each export is one narrow capability port over the host machine \u2014 running commands, observing and owning processes, diagnostics, retry/deadline, archive extraction, durable files and locks, request-scoped plumbing, and the installed version.",
   "dependencies": {
     "@agent-device/contracts": "workspace:*",
-    "@agent-device/kernel": "workspace:*",
-    "tar-stream": "^3.2.0",
-    "yauzl": "^3.4.0"
+    "@agent-device/kernel": "workspace:*"
   },
   "devDependencies": {
     "@types/tar-stream": "^3.1.4",
-    "@types/yauzl": "^3.4.0"
+    "@types/yauzl": "^3.4.0",
+    "tar-stream": "^3.2.0",
+    "yauzl": "^3.4.0"
   },
   "exports": {
     "./archive": {

packages/kernel/src/snapshot-attach-refs.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'vitest';
+import { attachRefs, type RawSnapshotNode } from './snapshot.ts';
+
+const node = (index: number, extra: Partial<RawSnapshotNode> = {}): RawSnapshotNode => ({
+  index,
+  ...extra,
+});
+
+describe('attachRefs', () => {
+  test('preserves a backend-minted ref instead of re-minting a dense positional one', () => {
+    // The web/agent-browser backend mints refs in tree order (non-dense — non-interactive
+    // nodes are skipped). The first node's backend ref is e2 because e1 went to a node
+    // that did not appear in the projected tree. Preserving it keeps the ref the agent
+    // reads off the snapshot identical to the ref the backend resolves on the next action.
+    const attached = attachRefs([node(0, { ref: 'e2' }), node(1, { ref: 'e3' })]);
+    expect(attached.map((n) => n.ref)).toEqual(['e2', 'e3']);
+    // index is preserved untouched — the positional identity is orthogonal to the ref.
+    expect(attached.map((n) => n.index)).toEqual([0, 1]);
+  });
+
+  test('re-mints dense positional refs for nodes without a backend ref', () => {
+    const attached = attachRefs([node(0), node(1, { ref: 'e7' }), node(2)]);
+    expect(attached.map((n) => n.ref)).toEqual(['e1', 'e7', 'e3']);
+  });
+});

packages/kernel/src/snapshot.ts

@@ -120,6 +120,15 @@ export type RawSnapshotNode = {
   hiddenContentBelow?: boolean;
   interactionBlocked?: 'covered';
   presentationHints?: string[];
+  /**
+   * Backend-minted ref for this node, when the capture backend already assigns a
+   * stable, actionable ref (e.g. the web/agent-browser backend resolves actions
+   * against its own `@eN` refs). `attachRefs` preserves this instead of re-minting
+   * a dense positional ref, so the ref an agent sees in the snapshot is the same
+   * ref the backend can resolve on the next action. Absent for backends that do
+   * not mint refs — those fall back to dense `e${index}` numbering.
+   */
+  ref?: string;
   /**
    * Accessibility custom actions the element exposes (iOS
    * `UIAccessibilityCustomAction`, React Native `accessibilityActions`). Merged
@@ -273,8 +282,15 @@ export type ScreenshotOverlayRef = {
   center: Point;
 };
 
+/**
+ * Assign a display ref to every node. A node that already carries a backend-minted
+ * `ref` keeps it (see `RawSnapshotNode.ref`) — the web/agent-browser backend resolves
+ * actions against its own refs, so re-minting a dense positional ref here would make
+ * the snapshot show one ref while actions act on a different element. Backends that do
+ * not mint refs get dense `e${index}` numbering, matching the historical behavior.
+ */
 export function attachRefs(nodes: RawSnapshotNode[]): SnapshotNode[] {
-  return nodes.map((node, idx) => ({ ...node, ref: `e${idx + 1}` }));
+  return nodes.map((node, idx) => ({ ...node, ref: node.ref ?? `e${idx + 1}` }));
 }
 
 /**

packages/maestro/package.json

@@ -8,13 +8,15 @@
   "dependencies": {
     "@agent-device/contracts": "workspace:*",
     "@agent-device/kernel": "workspace:*",
-    "@agent-device/selectors": "workspace:*",
-    "yaml": "^2.9.0"
+    "@agent-device/selectors": "workspace:*"
   },
   "exports": {
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     }
+  },
+  "devDependencies": {
+    "yaml": "^2.9.0"
   }
 }

packages/platform-web/src/__tests__/agent-browser-snapshot.test.ts

@@ -59,4 +59,34 @@ describe('normalizeAgentBrowserSnapshot', () => {
 
     expect(result.nodes[0]?.enabled).toBe(true);
   });
+
+  test('preserves the backend ref so the displayed ref is the actionable one', async () => {
+    // agent-browser mints refs in tree order and skips non-interactive nodes
+    // (the leading `generic` container never gets a ref), so the refs are NOT dense:
+    //   e1 = generic  (skipped here, no ref on it)
+    //   e2 = username textbox
+    //   e3 = passcode textbox   <-- agent presses @e3 expecting username
+    //   e4 = sign-in button
+    // The username textbox is the 2nd NODE in the snapshot but its backend ref is e2.
+    // If agent-device re-mints dense positional refs, the snapshot would show the
+    // username as @e2 while the passcode (node 3) shows @e3 — and an agent that
+    // reads "@e3 = passcode" would land in the passcode field when it meant the
+    // username, because the backend's own e3 resolves to a different element.
+    // Preserving the backend ref keeps display ref == actionable ref.
+    const result = await normalizeAgentBrowserSnapshot({
+      snapshot: [
+        '- textbox "Username" [ref=e2]',
+        '- textbox "Passcode" [ref=e3]',
+        '- button "Sign in" [ref=e4]',
+      ].join('\n'),
+      refs: {
+        e2: { role: 'textbox', name: 'Username' },
+        e3: { role: 'textbox', name: 'Passcode' },
+        e4: { role: 'button', name: 'Sign in' },
+      },
+    });
+
+    expect(result.nodes.map((node) => node.label)).toEqual(['Username', 'Passcode', 'Sign in']);
+    expect(result.nodes.map((node) => node.ref)).toEqual(['e2', 'e3', 'e4']);
+  });
 });