refactor: split generic host mechanics into @agent-device/host-kit (#2082 W1)

The shared src/utils closure that blocked the platform-family moves lands
on declared owners: generic host mechanics form a new private
@agent-device/host-kit package between kernel and capture-kit, and
capture-kit keeps capture, snapshot, and recording behavior, depending on
host-kit for the mechanics it needs. tar-stream and yauzl move with the
archive code.

Every seam's exported subpaths are pinned in package-boundaries.test.ts,
the layering model ranks the new zone, R13's allow-list names it, and each
seam carries an exact eager-closure row. ADR-0019's substrate amendment
describes the layout.

Tests that mocked two of the moved modules separately became duplicate
same-seam vi.mock factories, where the second silently replaced the first;
those are merged, and the mocks that production code reaches past are
pinned at their injection points instead.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018VngeKZH6zBuJzNBk5YzUH

Author: claude

.fallowrc.json

@@ -65,6 +65,11 @@
       "file": "src/platforms/android/perf.ts",
       "exports": ["sampleAndroidMemoryPerf"]
     },
+    {
+      "comment": "Apple perf sampling metadata is selected through the same lazy platform host; Fallow cannot follow the dynamic property read in src/platform-runtime-perf-host.ts.",
+      "file": "src/platforms/apple/core/perf.ts",
+      "exports": ["buildAppleFrameSamplingMetadata", "buildAppleMemorySamplingMetadata"]
+    },
     {
       "comment": "Daemon route handlers are reached only through the dynamic `import()` table in request-handler-chain.ts, which --production analysis cannot follow to a consumer.",
       "file": "src/daemon/handlers/{lease,session,snapshot,react-native,record-trace,find,interaction}.ts",
@@ -212,6 +217,13 @@
       "rules": {
         "unused-types": "off"
       }
+    },
+    {
+      "comment": "Host-kit seam façades: same false-positive shape as the contracts façades above — each seam names every type its re-exported functions put in a public signature, and callers use those types structurally without importing the name. unused-exports (the VALUE check) stays on.",
+      "files": ["packages/host-kit/src/*.ts"],
+      "rules": {
+        "unused-types": "off"
+      }
     }
   ],
   "production": {

.oxlintrc.json

@@ -37,23 +37,28 @@
   },
   "overrides": [
     {
-      "files": ["src/**/*.ts"],
+      "files": ["src/**/*.ts", "packages/capture-kit/src/**/*.ts"],
       "rules": {
         "eslint/no-restricted-imports": [
           "error",
           {
             "paths": [
               {
                 "name": "node:child_process",
-                "message": "Use process helpers from src/utils/exec.ts instead of importing node:child_process directly."
+                "message": "Use process helpers from @agent-device/capture-kit/exec instead of importing node:child_process directly."
               }
             ]
           }
         ]
       }
     },
     {
-      "files": ["src/utils/exec.ts", "src/**/*.test.ts", "src/**/__tests__/**/*.ts"],
+      "files": [
+        "packages/capture-kit/src/exec.ts",
+        "packages/capture-kit/src/*.test.ts",
+        "src/**/*.test.ts",
+        "src/**/__tests__/**/*.ts"
+      ],
       "rules": {
         "eslint/no-restricted-imports": ["error", { "paths": [] }]
       }

AGENTS.md

@@ -61,9 +61,10 @@ Read the declaration rather than maintaining a prose copy:
 - common command input fields, and which surface may write an input key (model, operator, retired):
   `src/commands/common-input-fields.ts` and `src/commands/input-audience.ts`
 
-Shared selector parsing and matching belongs in `@agent-device/selectors`; request cancellation and
-progress in `src/request`; cross-layer contracts in `src/contracts`; CLI flags in
-`src/commands/cli-grammar`; cross-surface schema composition in `src/cli-schema`.
+Shared selector parsing and matching belongs in `@agent-device/selectors`; request cancellation
+and progress in `@agent-device/capture-kit` (`request-cancel`, `request-progress`); cross-layer
+contracts in `src/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
@@ -123,7 +124,7 @@ The OS-neutral Apple runner lives under `packages/platform-apple/src/runner/`. F
 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 `src/utils/diagnostics.ts`. Request diagnostics belong in the session request log;
+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`.
 

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTapPointPolicy.swift

@@ -11,7 +11,7 @@ import XCTest
 // This is pure geometry on purpose — no XCUIElement — so the exact decision
 // can be proven against the golden fixture table shared with the TS twin:
 //   table:   contracts/fixtures/tap-point-policy.json
-//   TS twin: src/snapshot/mobile-snapshot-semantics.ts#isTapPointInsideViewport
+//   TS twin: packages/contracts/src/mobile-snapshot-semantics.ts#isTapPointInsideViewport
 //   TS test: src/snapshot/__tests__/tap-point-policy-parity.test.ts
 // Drift on either side turns CI red without needing a simulator.
 enum TapPointPolicy {

docs/adr/0019-request-bound-platform-runtime.md

@@ -132,6 +132,34 @@ platform-common package, and it preserves the package façades' implementation-l
 Its introduction carries the normal workspace-package compliance surface: `check:affected`
 selection, R11/R13 package enumeration, and the composite typecheck project list.
 
+> **Amendment (#2082): the substrate below the platform families.** Retiring the shared
+> `src/utils` and `src/platforms` root surfaces (so the family trees can move behind their
+> exports maps) forces every shared file onto a declared domain owner, and the paragraph above
+> is amended to name that layout rather than let capture-kit absorb it:
+>
+> - `@agent-device/host-kit` owns generic host mechanics — process execution, supervision, and
+>   diagnostics; archives, streams, atomic files, locks, and path/device isolation; small host
+>   value helpers; request-scoped plumbing — behind a small deep surface of exactly four seams:
+>   `exec`, `fs`, `values`, `request`. Modules under `src/internal/` are reachable only through
+>   those seams; consumers import a seam, never an internal module.
+> - `@agent-device/capture-kit` owns capture, snapshot, and recording behavior — PNG tooling,
+>   screenshot density and pixel diffing, snapshot occlusion, mobile snapshot semantics,
+>   quality verdicts and backend capability tables. Snapshot *behavior* is capture domain, not
+>   contracts vocabulary, and host mechanics are host-kit's, not capture-kit's.
+> - `@agent-device/provision-kit` owns provisioning mechanics — install-artifact acquisition
+>   (local paths, archives, guarded network downloads) and host toolchain probing.
+> - The enforced direction is `kernel < contracts < host-kit < capture-kit < provision-kit <
+>   platform/provider/daemon`.
+> - Contracts stays vocabulary, plan models, and pure classification with no process,
+>   filesystem, or timer mechanics (the existing planted-red gate); platform-specific parsing
+>   stays with its family package and reaches legacy callers through composition, never by a
+>   family importing another owner's internals.
+>
+> Enforcement: each substrate package's exported subpaths are pinned in
+> `package-boundaries.test.ts` (widening fails the gate), the contracts mechanics gate stays
+> planted red, and the `platforms-root-shape` rule rejects any new shared file or directory
+> appearing directly under `src/platforms`.
+
 The Apple XCUITest runner client is a durable platform-owned implementation facet colocated
 inside `packages/platform-apple` as the `src/runner/` subtree (#2040) — Apple mechanics belong to
 the Apple package. R13 models the facet by enumeration rather than by exception sprawl: the family

docs/agents/testing.md

@@ -129,7 +129,7 @@ whether tests distinguish changed decision logic. Do not infer redundancy from l
 Run `pnpm depgraph affected` before touching a high-fan-in module:
 
 ```sh
-pnpm depgraph affected src/utils/exec.ts
+pnpm depgraph affected packages/capture-kit/src/exec.ts
 pnpm depgraph affected src/daemon/ref-frame.ts --json --limit 25
 ```
 

package.json

@@ -161,7 +161,7 @@
     "check:unit": "pnpm test:unit && pnpm check:tmpdir-leaks && pnpm test:smoke",
     "check": "pnpm check:tooling && pnpm check:fallow && pnpm check:unit",
     "prepack": "pnpm check:mcp-metadata && pnpm package:npm",
-    "typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/capture-kit packages/platform-apple packages/platform-android packages/platform-harmonyos packages/platform-vega packages/platform-linux packages/platform-web packages/ad-script packages/selectors packages/ad-replay packages/maestro packages/replay-test packages/provider-webdriver packages/provider-limrun && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
+    "typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/host-kit packages/capture-kit packages/platform-apple packages/platform-android packages/platform-harmonyos packages/platform-vega packages/platform-linux packages/platform-web packages/ad-script packages/selectors packages/ad-replay packages/maestro packages/replay-test packages/provider-webdriver packages/provider-limrun && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
     "test-app:install": "pnpm install --dir examples/test-app",
     "test-app:start": "pnpm --dir examples/test-app start",
     "test-app:ios": "pnpm --dir examples/test-app ios",
@@ -278,6 +278,7 @@
     "@agent-device/ad-script": "workspace:*",
     "@agent-device/capture-kit": "workspace:*",
     "@agent-device/contracts": "workspace:*",
+    "@agent-device/host-kit": "workspace:*",
     "@agent-device/kernel": "workspace:*",
     "@agent-device/maestro": "workspace:*",
     "@agent-device/platform-android": "workspace:*",

packages/ad-replay/src/internal/canonical-json.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import type { SessionAction } from '@agent-device/contracts/session';
-import { canonicalJson } from './canonical-json.ts';
+import { canonicalJson } from '@agent-device/kernel/collections';
 
 /**
  * ADR 0012 decision 4 / migration step 5: `planDigest` is SHA-256 over the

packages/ad-replay/src/internal/plan-digest.ts

@@ -3,15 +3,64 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
-  "description": "Private durable-capture mechanics shared by platform runtimes, providers, and daemon orchestration.",
+  "description": "Private host and durable-capture mechanics shared by platform runtimes, providers, and daemon orchestration: process execution, diagnostics, archives, PNG tooling, and request-scoped plumbing.",
   "dependencies": {
     "@agent-device/contracts": "workspace:*",
+    "@agent-device/host-kit": "workspace:*",
     "@agent-device/kernel": "workspace:*"
   },
   "exports": {
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
+    },
+    "./mobile-snapshot-semantics": {
+      "types": "./src/mobile-snapshot-semantics.ts",
+      "default": "./src/mobile-snapshot-semantics.ts"
+    },
+    "./png": {
+      "types": "./src/png.ts",
+      "default": "./src/png.ts"
+    },
+    "./png-resize": {
+      "types": "./src/png-resize.ts",
+      "default": "./src/png-resize.ts"
+    },
+    "./png-rgb-difference": {
+      "types": "./src/png-rgb-difference.ts",
+      "default": "./src/png-rgb-difference.ts"
+    },
+    "./png-size": {
+      "types": "./src/png-size.ts",
+      "default": "./src/png-size.ts"
+    },
+    "./png-worker-client": {
+      "types": "./src/png-worker-client.ts",
+      "default": "./src/png-worker-client.ts"
+    },
+    "./screenshot-density": {
+      "types": "./src/screenshot-density.ts",
+      "default": "./src/screenshot-density.ts"
+    },
+    "./screenshot-diff-pixels": {
+      "types": "./src/screenshot-diff-pixels.ts",
+      "default": "./src/screenshot-diff-pixels.ts"
+    },
+    "./snapshot-occlusion": {
+      "types": "./src/snapshot-occlusion.ts",
+      "default": "./src/snapshot-occlusion.ts"
+    },
+    "./snapshot-quality-backend-capabilities": {
+      "types": "./src/snapshot-quality-backend-capabilities.ts",
+      "default": "./src/snapshot-quality-backend-capabilities.ts"
+    },
+    "./snapshot-quality-verdict": {
+      "types": "./src/snapshot-quality-verdict.ts",
+      "default": "./src/snapshot-quality-verdict.ts"
     }
+  },
+  "devDependencies": {
+    "@types/pngjs": "^6.0.5",
+    "pngjs": "^7.0.0"
   }
 }