fix: close simulator snapshot source ownership gaps

Author: thymikee

.github/workflows/ios.yml

@@ -126,6 +126,24 @@ jobs:
           runtime-version: ${{ env.IOS_RUNTIME_VERSION }}
           preferred-device-name: iPhone 17 Pro
 
+      - name: Verify clean-installed Simulator snapshot bridge preparation
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          git fetch origin "$BASE_SHA" --depth=1
+          if git diff --quiet "$BASE_SHA"...HEAD -- \
+            apple/snapshot-bridge \
+            packages/platform-apple/src/snapshot-source \
+            scripts/check-package.ts \
+            scripts/size-report-install.mjs \
+            scripts/size-report-package.mjs; then
+            echo "Snapshot bridge packaging is unchanged; skipping preparation proof."
+            exit 0
+          fi
+          pnpm build
+          pnpm check:package -- --verify-snapshot-bridge-preparation
+
       - name: Run targeted iOS runner XCTest regressions
         run: |
           XCTESTRUN_PATH="$(find "$AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH/Build/Products" -maxdepth 1 -name '*.xctestrun' -print -quit)"

docs/evidence/ios-simulator-snapshot-source-2026-09-04.md

@@ -59,7 +59,7 @@ lifecycle contract.
 | Retained growth | Scope kept in the facet |
 |---|---|
 | Native runtime | Private AX binding, strict tree materialization, watchdog, and bounded response framing |
-| Host/cache | Toolchain-aware atomic build cache and clean-installed native source validation |
+| Host/cache | Toolchain-aware atomic build cache and clean-installed native source preparation |
 | Lifecycle/wire | Per-simulator generation routing, persistent helper reuse, typed failures, and reap recovery |
 | Proof | Vitest coverage topology, native/TypeScript vocabulary parity, size base/head handling, and live evidence |
 

packages/platform-apple/package.json

@@ -4,6 +4,9 @@
   "private": true,
   "type": "module",
   "description": "Apple-family platform runtime metadata and implementations for agent-device.",
+  "scripts": {
+    "verify-installed-snapshot-bridge": "node --experimental-strip-types scripts/verify-installed-snapshot-bridge.ts"
+  },
   "dependencies": {
     "@agent-device/capture-kit": "workspace:*",
     "@agent-device/contracts": "workspace:*",

packages/platform-apple/scripts/verify-installed-snapshot-bridge.ts

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import { ensureSnapshotBridgeBinary } from '../src/snapshot-source/cache.ts';
+import { createSnapshotSourceDeadline } from '../src/snapshot-source/deadline.ts';
+import { createSnapshotSourceHost } from '../src/snapshot-source/host.ts';
+import { resolveSnapshotSourceLimits } from '../src/snapshot-source/limits.ts';
+
+const [installedRoot, cacheRoot] = process.argv.slice(2);
+if (!installedRoot || !cacheRoot) {
+  throw new Error('Usage: verify-installed-snapshot-bridge <installed-root> <cache-root>');
+}
+
+const host = {
+  ...createSnapshotSourceHost(),
+  projectRoot: () => installedRoot,
+};
+const limits = resolveSnapshotSourceLimits({ maxDurationMs: 120_000 });
+const prepared = await ensureSnapshotBridgeBinary({
+  host,
+  runtime: 'installed-package-verification',
+  limits,
+  deadline: createSnapshotSourceDeadline(limits.maxDurationMs, undefined),
+  cacheRoot,
+});
+if (!prepared.path.startsWith(`${cacheRoot}${path.sep}`) || !host.exists(prepared.path)) {
+  throw new Error('Installed snapshot bridge preparation did not publish its compiled binary.');
+}

packages/platform-apple/src/snapshot-source/adapter.test.ts

@@ -161,6 +161,7 @@ function createAdapterHost(buildDelayMs = 0): AdapterFixture {
     },
     start: () => new AdapterProcess(),
     connect: async () => new AdapterSocket(() => fixture.responsePid),
+    readTargetProcessStartTime: async () => 'target-start',
   };
   fixture.host = host;
   return fixture;

packages/platform-apple/src/snapshot-source/host.test.ts

@@ -4,10 +4,13 @@ import { createSnapshotSourceHost, snapshotSourceSocketPath } from './host.ts';
 
 test('snapshot bridge socket paths stay within the AF_UNIX limit and are target-specific', () => {
   const host = createSnapshotSourceHost();
-  const first = snapshotSourceSocketPath(host, 'simulator-1');
-  const second = snapshotSourceSocketPath(host, 'simulator-2');
+  const first = snapshotSourceSocketPath(host, 'simulator-1', 'owner-1');
+  const second = snapshotSourceSocketPath(host, 'simulator-2', 'owner-1');
+  const otherOwner = snapshotSourceSocketPath(host, 'simulator-1', 'owner-2');
 
   assert.equal(first.length < 104, true);
   assert.equal(second.length < 104, true);
+  assert.equal(otherOwner.length < 104, true);
   assert.notEqual(first, second);
+  assert.notEqual(first, otherOwner);
 });

packages/platform-apple/src/snapshot-source/host.ts

@@ -48,9 +48,23 @@ export function createSnapshotSourceHost(): SnapshotSourceHost {
     emitDiagnostic,
     withDiagnosticTimer,
     processId: hostProcessId,
+    readTargetProcessStartTime,
   };
 }
 
+async function readTargetProcessStartTime(
+  pid: number,
+  options: { signal?: AbortSignal; timeoutMs: number },
+): Promise<string | null> {
+  const result = await runCmd('ps', ['-p', String(pid), '-o', 'lstart='], {
+    allowFailure: true,
+    signal: options.signal,
+    timeoutMs: options.timeoutMs,
+  });
+  if (result.exitCode !== 0) return null;
+  return result.stdout.trim() || null;
+}
+
 function startSnapshotBridge(
   udid: string,
   bridgePath: string,
@@ -217,11 +231,16 @@ function appendBoundedLog(current: string, addition: string): string {
     : combined.slice(combined.length - MAX_PROCESS_LOG_BYTES);
 }
 
-export function snapshotSourceSocketPath(host: SnapshotSourceHost, udid: string): string {
+export function snapshotSourceSocketPath(
+  host: SnapshotSourceHost,
+  udid: string,
+  ownerId: string,
+): string {
   const targetKey = createHash('sha256').update(udid).digest('hex').slice(0, 12);
+  const ownerKey = createHash('sha256').update(ownerId).digest('hex').slice(0, 12);
   return path.join(
     SNAPSHOT_SOCKET_ROOT,
-    `agent-device-ax-${targetKey}-${host.processId()}`,
+    `agent-device-ax-${targetKey}-${host.processId()}-${ownerKey}`,
     'snapshot.sock',
   );
 }

packages/platform-apple/src/snapshot-source/lifecycle.test.ts

@@ -106,6 +106,62 @@ test('cancellation while queued prevents a later dispatch', async () => {
   await manager.close();
 });
 
+test('cancelling a middle waiter does not release the following request early', async () => {
+  const fixture = createLifecycleFixture({ responseDelayMs: 120 });
+  const manager = new SnapshotBridgeManager(fixture.host);
+  const first = manager.request({
+    target,
+    bridge,
+    limits,
+    maxDepth: 10,
+    deadline: deadline(undefined, 1000),
+  });
+  await waitForDispatch(fixture);
+
+  const controller = new AbortController();
+  const middle = manager.request({
+    target,
+    bridge,
+    limits,
+    maxDepth: 10,
+    deadline: deadline(controller.signal, 1000),
+  });
+  const last = manager.request({
+    target,
+    bridge,
+    limits,
+    maxDepth: 10,
+    deadline: deadline(undefined, 1000),
+  });
+  controller.abort();
+
+  await assert.rejects(
+    middle,
+    (error: unknown) => error instanceof SnapshotSourceError && error.failureKind === 'cancelled',
+  );
+  assert.equal(fixture.sockets[0]?.writes, 1);
+  await first;
+  await last;
+  assert.equal(fixture.sockets[0]?.writes, 2);
+  await manager.close();
+});
+
+test('independent managers own distinct sockets for the same Simulator', async () => {
+  const fixture = createLifecycleFixture();
+  const first = new SnapshotBridgeManager(fixture.host);
+  const second = new SnapshotBridgeManager(fixture.host);
+
+  await first.request({ target, bridge, limits, maxDepth: 10, deadline: deadline() });
+  await second.request({ target, bridge, limits, maxDepth: 10, deadline: deadline() });
+
+  assert.equal(fixture.socketPaths.length, 2);
+  assert.notEqual(fixture.socketPaths[0], fixture.socketPaths[1]);
+  await first.close();
+  assert.equal(fixture.processes[1]?.isAlive(), true);
+  await second.request({ target, bridge, limits, maxDepth: 10, deadline: deadline() });
+  await second.close();
+});
+
 test('request cancellation after dispatch reaps the exact helper before recovery', async () => {
   const fixture = createLifecycleFixture({ responseDelayMs: 80 });
   const manager = new SnapshotBridgeManager(fixture.host);
@@ -258,6 +314,20 @@ test('the manager rejects a response carrying a previous target generation as st
   await manager.close();
 });
 
+test('the manager rejects a tree when the target process changes during acquisition', async () => {
+  const fixture = createLifecycleFixture({ targetStartTimes: ['start-1', 'start-2'] });
+  const manager = new SnapshotBridgeManager(fixture.host);
+
+  await assert.rejects(
+    manager.request({ target, bridge, limits, maxDepth: 10, deadline: deadline() }),
+    (error: unknown) =>
+      error instanceof SnapshotSourceError &&
+      error.failureKind === 'stale-target' &&
+      error.failureCode === 'target-process-changed',
+  );
+  await manager.close();
+});
+
 test('typed guest failures retain their kind after target validation', async () => {
   const fixture = createLifecycleFixture({ responseErrorKind: 'application_not_responding' });
   const manager = new SnapshotBridgeManager(fixture.host);
@@ -274,6 +344,7 @@ type LifecycleFixture = {
   processes: FakeProcess[];
   sockets: FakeSocket[];
   diagnostics: Array<Parameters<SnapshotSourceHost['emitDiagnostic']>[0]>;
+  socketPaths: string[];
 };
 
 function deadline(signal?: AbortSignal, timeoutMs = limits.maxDurationMs) {
@@ -295,16 +366,20 @@ function createLifecycleFixture(
     responsePid?: number;
     responseGeneration?: string;
     responseErrorKind?: string;
+    targetStartTimes?: Array<string | null>;
   } = {},
 ): LifecycleFixture {
   const processes: FakeProcess[] = [];
   const sockets: FakeSocket[] = [];
   const diagnostics: LifecycleFixture['diagnostics'] = [];
+  const socketPaths: string[] = [];
   const realHost = createSnapshotSourceHost();
   const host: SnapshotSourceHost = {
     ...realHost,
     emitDiagnostic: (event) => diagnostics.push(event),
-    start: () => {
+    readTargetProcessStartTime: async () => options.targetStartTimes?.shift() ?? 'target-start',
+    start: (_udid, _bridgePath, socketPath) => {
+      socketPaths.push(socketPath);
       const process = new FakeProcess(700 + processes.length);
       processes.push(process);
       return process;
@@ -336,7 +411,7 @@ function createLifecycleFixture(
       return socket;
     },
   };
-  return { host, processes, sockets, diagnostics };
+  return { host, processes, sockets, diagnostics, socketPaths };
 }
 
 class FakeProcess implements SnapshotSourceProcess {

packages/platform-apple/src/snapshot-source/lifecycle.ts

@@ -44,6 +44,7 @@ type SnapshotBridgeRequest = Readonly<{
 export class SnapshotBridgeManager {
   private readonly sessions = new Map<string, BridgeSession>();
   private readonly requestQueues = new Map<string, Promise<void>>();
+  private readonly ownerId = randomUUID();
   private closed = false;
   private readonly host: SnapshotSourceHost;
 
@@ -65,7 +66,10 @@ export class SnapshotBridgeManager {
     const previousSession = this.sessions.get(input.target.udid);
     const session = await this.ensureSession(input, deadline);
     try {
-      return await this.exchange(session, input, deadline);
+      const targetStartTime = await this.readTargetStartTime(input.target, deadline);
+      const envelope = await this.exchange(session, input, deadline);
+      await this.assertTargetStillCurrent(input.target, targetStartTime, deadline);
+      return envelope;
     } catch (error) {
       const normalized = await this.handleRequestFailure(error, session, previousSession);
       throw normalized;
@@ -94,15 +98,15 @@ export class SnapshotBridgeManager {
     deadline: SnapshotSourceDeadline,
     action: () => Promise<T>,
   ): Promise<T> {
-    const previous = this.requestQueues.get(udid);
+    const previous = this.requestQueues.get(udid) ?? Promise.resolve();
     let release!: () => void;
-    const current = new Promise<void>((resolve) => {
+    const turnFinished = new Promise<void>((resolve) => {
       release = resolve;
     });
+    const current = previous.then(() => turnFinished);
     this.requestQueues.set(udid, current);
     try {
-      if (previous) await waitForSimulatorTurn(previous, deadline);
-      else remainingSnapshotSourceMs(deadline, 'bridge-request-deadline');
+      await waitForSimulatorTurn(previous, deadline);
       return await action();
     } finally {
       release();
@@ -132,7 +136,7 @@ export class SnapshotBridgeManager {
     }
     if (existing) await this.removeSession(existing, true);
 
-    const socketPath = snapshotSourceSocketPath(this.host, input.target.udid);
+    const socketPath = snapshotSourceSocketPath(this.host, input.target.udid, this.ownerId);
     await this.host.ensureDirectory(path.dirname(socketPath));
     await this.host.remove(socketPath);
     const bridgeProcess = this.host.start(input.target.udid, input.bridge.path, socketPath, {
@@ -222,6 +226,42 @@ export class SnapshotBridgeManager {
     });
   }
 
+  private async readTargetStartTime(
+    target: SnapshotSourceTarget,
+    deadline: SnapshotSourceDeadline,
+  ): Promise<string> {
+    const startTime = await this.host.readTargetProcessStartTime(target.pid, {
+      signal: deadline.signal,
+      timeoutMs: remainingSnapshotSourceMs(deadline, 'target-identity-deadline'),
+    });
+    if (!startTime) {
+      throw snapshotSourceError('stale-target', 'target-process-unavailable', {
+        pid: target.pid,
+        generation: target.generation,
+      });
+    }
+    return startTime;
+  }
+
+  private async assertTargetStillCurrent(
+    target: SnapshotSourceTarget,
+    expectedStartTime: string,
+    deadline: SnapshotSourceDeadline,
+  ): Promise<void> {
+    const observedStartTime = await this.host.readTargetProcessStartTime(target.pid, {
+      signal: deadline.signal,
+      timeoutMs: remainingSnapshotSourceMs(deadline, 'target-identity-deadline'),
+    });
+    if (observedStartTime !== expectedStartTime) {
+      throw snapshotSourceError('stale-target', 'target-process-changed', {
+        pid: target.pid,
+        generation: target.generation,
+        expectedStartTime,
+        observedStartTime,
+      });
+    }
+  }
+
   private async removeSession(session: BridgeSession, stopProcess: boolean): Promise<void> {
     if (this.sessions.get(session.udid) === session) this.sessions.delete(session.udid);
     await this.dispose(session, stopProcess);

packages/platform-apple/src/snapshot-source/types.ts

@@ -112,6 +112,10 @@ export type SnapshotSourceHost = Readonly<{
     data?: Record<string, unknown>,
   ): Promise<T>;
   processId(): number;
+  readTargetProcessStartTime(
+    pid: number,
+    options: { signal?: AbortSignal; timeoutMs: number },
+  ): Promise<string | null>;
 }>;
 
 export type SnapshotSourceBridgeBinary = Readonly<{