refactor: split generic host mechanics into @agent-device/host-kit

capture-kit's generic host modules move to a new host-kit package that
sits between kernel and capture-kit, exported behind four deep seams —
exec, fs, values, request — with explicit named re-exports and internals
sealed under src/internal/. capture-kit keeps capture, snapshot, and
recording behavior and now depends on host-kit; tar-stream/yauzl move
with the archive mechanics. The layering model, platform-package policy,
package pins, eager-closure budgets, and the ADR-0019 substrate
amendment now describe this layout, and the remaining alias-source
narration is removed.

Seam merging also surfaced tests whose per-module mocks became
same-seam duplicates (the later factory silently replaced the earlier
one) and mocks that internal relative imports now bypass; those factories
are merged and pinned at the injection points instead.

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

Author: claude

.fallowrc.json

@@ -217,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": {

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

@@ -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:*",

package.json

@@ -6,87 +6,18 @@
   "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/kernel": "workspace:*",
-    "tar-stream": "^3.2.0",
-    "yauzl": "^3.4.0"
+    "@agent-device/host-kit": "workspace:*",
+    "@agent-device/kernel": "workspace:*"
   },
   "exports": {
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
-    "./archive-extraction": {
-      "types": "./src/archive-extraction.ts",
-      "default": "./src/archive-extraction.ts"
-    },
-    "./archive-safety": {
-      "types": "./src/archive-safety.ts",
-      "default": "./src/archive-safety.ts"
-    },
-    "./artifact-limits": {
-      "types": "./src/artifact-limits.ts",
-      "default": "./src/artifact-limits.ts"
-    },
-    "./atomic-file": {
-      "types": "./src/atomic-file.ts",
-      "default": "./src/atomic-file.ts"
-    },
-    "./byte-limit-stream": {
-      "types": "./src/byte-limit-stream.ts",
-      "default": "./src/byte-limit-stream.ts"
-    },
-    "./device-isolation": {
-      "types": "./src/device-isolation.ts",
-      "default": "./src/device-isolation.ts"
-    },
-    "./diagnostics": {
-      "types": "./src/diagnostics.ts",
-      "default": "./src/diagnostics.ts"
-    },
-    "./env-map": {
-      "types": "./src/env-map.ts",
-      "default": "./src/env-map.ts"
-    },
-    "./exec": {
-      "types": "./src/exec.ts",
-      "default": "./src/exec.ts"
-    },
-    "./host-process": {
-      "types": "./src/host-process.ts",
-      "default": "./src/host-process.ts"
-    },
-    "./location-coordinates": {
-      "types": "./src/location-coordinates.ts",
-      "default": "./src/location-coordinates.ts"
-    },
-    "./method-scope": {
-      "types": "./src/method-scope.ts",
-      "default": "./src/method-scope.ts"
-    },
     "./mobile-snapshot-semantics": {
       "types": "./src/mobile-snapshot-semantics.ts",
       "default": "./src/mobile-snapshot-semantics.ts"
     },
-    "./owned-process-reaper": {
-      "types": "./src/owned-process-reaper.ts",
-      "default": "./src/owned-process-reaper.ts"
-    },
-    "./owned-process-record": {
-      "types": "./src/owned-process-record.ts",
-      "default": "./src/owned-process-record.ts"
-    },
-    "./owner-identity": {
-      "types": "./src/owner-identity.ts",
-      "default": "./src/owner-identity.ts"
-    },
-    "./parsing": {
-      "types": "./src/parsing.ts",
-      "default": "./src/parsing.ts"
-    },
-    "./path-resolution": {
-      "types": "./src/path-resolution.ts",
-      "default": "./src/path-resolution.ts"
-    },
     "./png": {
       "types": "./src/png.ts",
       "default": "./src/png.ts"
@@ -107,26 +38,6 @@
       "types": "./src/png-worker-client.ts",
       "default": "./src/png-worker-client.ts"
     },
-    "./process-lock": {
-      "types": "./src/process-lock.ts",
-      "default": "./src/process-lock.ts"
-    },
-    "./request-cancel": {
-      "types": "./src/request-cancel.ts",
-      "default": "./src/request-cancel.ts"
-    },
-    "./request-progress": {
-      "types": "./src/request-progress.ts",
-      "default": "./src/request-progress.ts"
-    },
-    "./retry": {
-      "types": "./src/retry.ts",
-      "default": "./src/retry.ts"
-    },
-    "./scoped-provider": {
-      "types": "./src/scoped-provider.ts",
-      "default": "./src/scoped-provider.ts"
-    },
     "./screenshot-density": {
       "types": "./src/screenshot-density.ts",
       "default": "./src/screenshot-density.ts"
@@ -135,10 +46,6 @@
       "types": "./src/screenshot-diff-pixels.ts",
       "default": "./src/screenshot-diff-pixels.ts"
     },
-    "./shell-quote": {
-      "types": "./src/shell-quote.ts",
-      "default": "./src/shell-quote.ts"
-    },
     "./snapshot-occlusion": {
       "types": "./src/snapshot-occlusion.ts",
       "default": "./src/snapshot-occlusion.ts"
@@ -150,32 +57,10 @@
     "./snapshot-quality-verdict": {
       "types": "./src/snapshot-quality-verdict.ts",
       "default": "./src/snapshot-quality-verdict.ts"
-    },
-    "./source-value": {
-      "types": "./src/source-value.ts",
-      "default": "./src/source-value.ts"
-    },
-    "./success-text": {
-      "types": "./src/success-text.ts",
-      "default": "./src/success-text.ts"
-    },
-    "./timeouts": {
-      "types": "./src/timeouts.ts",
-      "default": "./src/timeouts.ts"
-    },
-    "./ttl-memo": {
-      "types": "./src/ttl-memo.ts",
-      "default": "./src/ttl-memo.ts"
-    },
-    "./version": {
-      "types": "./src/version.ts",
-      "default": "./src/version.ts"
     }
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",
-    "@types/tar-stream": "^3.1.4",
-    "@types/yauzl": "^3.4.0",
     "pngjs": "^7.0.0"
   }
 }

packages/capture-kit/package.json

@@ -1,5 +1,5 @@
 import { Worker } from 'node:worker_threads';
-import { emitDiagnostic } from './diagnostics.ts';
+import { emitDiagnostic } from '@agent-device/host-kit/exec';
 import { AppError, toAppErrorCode } from '@agent-device/kernel/errors';
 import { resolveInternalEntryModulePath } from './internal-entry.ts';
 import { decodePng, PNG } from './png.ts';

packages/capture-kit/src/png-worker-client.ts

@@ -0,0 +1,35 @@
+{
+  "name": "@agent-device/host-kit",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Private generic host mechanics behind four deep seams: process execution and supervision (exec), filesystem and archive guards (fs), pure value helpers (values), and request-scoped plumbing (request). Internal workspace package bundled into the published agent-device artifact.",
+  "dependencies": {
+    "@agent-device/contracts": "workspace:*",
+    "@agent-device/kernel": "workspace:*",
+    "tar-stream": "^3.2.0",
+    "yauzl": "^3.4.0"
+  },
+  "devDependencies": {
+    "@types/tar-stream": "^3.1.4",
+    "@types/yauzl": "^3.4.0"
+  },
+  "exports": {
+    "./exec": {
+      "types": "./src/exec.ts",
+      "default": "./src/exec.ts"
+    },
+    "./fs": {
+      "types": "./src/fs.ts",
+      "default": "./src/fs.ts"
+    },
+    "./request": {
+      "types": "./src/request.ts",
+      "default": "./src/request.ts"
+    },
+    "./values": {
+      "types": "./src/values.ts",
+      "default": "./src/values.ts"
+    }
+  }
+}

packages/host-kit/package.json

@@ -0,0 +1,77 @@
+export {
+  coerceExecResult,
+  execFailureDetails,
+  isExecutablePath,
+  requireExecSuccess,
+  resolveExecutableOverridePath,
+  resolveFileOverridePath,
+  runCmd,
+  runCmdBackground,
+  runCmdDetached,
+  runCmdDetachedMonitored,
+  runCmdStreaming,
+  runCmdSync,
+  whichCmd,
+  withCommandExecutorOverride,
+  withoutCommandExecutorOverride,
+  type CommandExecutorOverride,
+  type ExecBackgroundOptions,
+  type ExecBackgroundResult,
+  type ExecDetachedExit,
+  type ExecDetachedProcess,
+  type ExecOptions,
+  type ExecResult,
+} from './internal/exec.ts';
+export {
+  countDiagnosticEventsByPhase,
+  createRequestId,
+  emitDiagnostic,
+  flushDiagnosticsToSessionFile,
+  getDiagnosticsMeta,
+  registerDiagnosticSensitiveValue,
+  updateDiagnosticsScope,
+  withDiagnosticTimer,
+  withDiagnosticsScope,
+  type FlushedDiagnosticsRecord,
+} from './internal/diagnostics.ts';
+export {
+  expandProcessTree,
+  isProcessAlive,
+  isProcessGroupAlive,
+  isProcessZombie,
+  listHostProcesses,
+  readHostProcessIdentityObservations,
+  readProcessCommand,
+  readProcessStartTime,
+  signalPidsBestEffort,
+  signalProcessGroupBestEffort,
+  stopPidsWithEscalation,
+  uniquePositivePids,
+  waitForProcessExit,
+  type HostProcessIdentityObservation,
+  type HostProcessInfo,
+  type ListHostProcessesOptions,
+  type StopPidsWithEscalationOptions,
+} from './internal/host-process.ts';
+export {
+  reapOwnedProcessRecordsAtStartup,
+  type OwnedProcessReapSummary,
+} from './internal/owned-process-reaper.ts';
+export {
+  createOwnedProcessRecordStore,
+  readOwnedProcessRecordFile,
+  type OwnedProcessRecordRead,
+  type OwnedProcessRecordStore,
+} from './internal/owned-process-record.ts';
+export {
+  classifyOwnerLiveness,
+  classifyOwnerLivenessFromObservation,
+  ownerIdentityDiffers,
+  ownerIdentityMatches,
+  readCurrentOwnerIdentity,
+  type OwnerIdentity,
+  type OwnerLiveness,
+} from './internal/owner-identity.ts';
+export { shellQuote, shellQuoteIfNeeded } from './internal/shell-quote.ts';
+export { sleep } from './internal/timeouts.ts';
+export { Deadline, isEnvTruthy, retryWithPolicy } from './internal/retry.ts';

packages/host-kit/src/exec.ts

@@ -0,0 +1,22 @@
+export {
+  archiveTypeFromPath,
+  extractArchiveSafely,
+  type ExtractArchiveOptions,
+  type SupportedArchiveType,
+} from './internal/archive-extraction.ts';
+export { ArchiveBudget, type ArchiveManifestEntry } from './internal/archive-safety.ts';
+export { MAX_ARTIFACT_COMPRESSED_BYTES } from './internal/artifact-limits.ts';
+export {
+  isAtomicPublishTemporaryPath,
+  publishFileSync,
+  withAtomicPublishTempPathSync,
+  type AtomicPublishMode,
+} from './internal/atomic-file.ts';
+export { createByteLimitStream, type ByteLimitStream } from './internal/byte-limit-stream.ts';
+export {
+  parseSerialAllowlist,
+  resolveAndroidSerialAllowlist,
+  resolveIosSimulatorDeviceSetPath,
+} from './internal/device-isolation.ts';
+export { expandUserHomePath, resolveUserPath } from './internal/path-resolution.ts';
+export { acquireProcessLock, type ProcessLockOwner } from './internal/process-lock.ts';