fix: preserve lazy simulator readiness through scoped authority

Author: thymikee

packages/platform-apple/src/core/simulator.ts

@@ -5,7 +5,7 @@ import { Deadline, retryWithPolicy } from '@agent-device/host-kit/retry';
 
 import { createTtlMemo } from '@agent-device/kernel/ttl-memo';
 import { bootFailureHint, classifyBootFailure } from '@agent-device/provision-kit/boot-diagnostics';
-import { delegateManagedDeviceReadiness } from '@agent-device/provision-kit/managed-device-scope';
+import { createScopedProvider } from '@agent-device/kernel/scoped-provider';
 
 import {
   IOS_BOOT_TIMEOUT_MS,
@@ -18,6 +18,17 @@ import { runAppleToolCommand, runXcrun } from './tool-provider.ts';
 const IOS_SIMULATOR_HOST_APPS = ['Simulator'] as const;
 const IOS_DEVICE_HUB_HOST_APPS = ['Device Hub', 'Simulator'] as const;
 
+const simulatorReadiness = createScopedProvider<
+  ((device: DeviceInfo) => Promise<void>) | undefined
+>(undefined);
+
+export async function withSimulatorReadiness<T>(
+  ensureReady: (device: DeviceInfo) => Promise<void>,
+  task: () => Promise<T>,
+): Promise<T> {
+  return await simulatorReadiness.run(ensureReady, task);
+}
+
 type OpenIosSimulatorAppOptions = {
   background?: boolean;
   deviceHub?: boolean;
@@ -86,7 +97,12 @@ export async function ensureBootedSimulator(
 ): Promise<void> {
   if (device.kind !== 'simulator') return;
   options.signal?.throwIfAborted();
-  if (await delegateManagedDeviceReadiness(device)) return;
+  const ensureReady = simulatorReadiness.resolve();
+  if (ensureReady) {
+    await ensureReady(device);
+    options.signal?.throwIfAborted();
+    return;
+  }
 
   const state = wasSimulatorRecentlyObservedBooted(device)
     ? 'Booted'

packages/platform-apple/src/runtime-simulator-readiness.test.ts

@@ -0,0 +1,51 @@
+import { expect, test, vi } from 'vitest';
+import { managedLocalRuntimeOwner } from '@agent-device/contracts/platform-runtime';
+import { withManagedDeviceScope } from '@agent-device/provision-kit/managed-device-scope';
+import { IOS_SIMULATOR } from './__tests__/device-fixtures.ts';
+import { ensureBootedSimulator } from './core/simulator.ts';
+import { createLocalAppleToolProvider, withAppleToolProvider } from './core/tool-provider.ts';
+import { bindSimulatorReadiness } from './runtime-simulator-readiness.ts';
+
+test('ordinary simulator operations preserve their binding without a readiness override', () => {
+  const operations = { ensureBootedSimulator };
+  expect(bindSimulatorReadiness(operations)).toBe(operations);
+});
+
+test('bound simulator readiness captures authority and refuses mismatches or failures before local boot', async () => {
+  await withAppleToolProvider(
+    createLocalAppleToolProvider({
+      runCommand: async () => {
+        throw new Error('Unexpected local readiness');
+      },
+    }),
+    async () => {
+      const device = { ...IOS_SIMULATOR, simulatorSetPath: '/managed/set' };
+      const ensureReady = vi.fn(async () => {});
+      const operations = await withManagedDeviceScope(
+        {
+          device,
+          owner: managedLocalRuntimeOwner('allocator'),
+          fence: { token: 'fence', generation: 1 },
+          ensureReady,
+          run: async <T>(task: () => Promise<T>) => await task(),
+        },
+        async () => bindSimulatorReadiness(Object.freeze({ ensureBootedSimulator })),
+      );
+      await operations.ensureBootedSimulator(device);
+      expect(ensureReady).toHaveBeenCalledOnce();
+      await expect(
+        operations.ensureBootedSimulator({ ...device, simulatorSetPath: undefined }),
+      ).rejects.toMatchObject({ details: { reason: 'managed-device-transport-mismatch' } });
+      expect(ensureReady).toHaveBeenCalledOnce();
+      const abort = new AbortController();
+      abort.abort(new Error('cancelled'));
+      await expect(
+        operations.ensureBootedSimulator(device, { signal: abort.signal }),
+      ).rejects.toThrow('cancelled');
+      expect(ensureReady).toHaveBeenCalledOnce();
+      ensureReady.mockRejectedValueOnce(new Error('lease fenced'));
+      await expect(operations.ensureBootedSimulator(device)).rejects.toThrow('lease fenced');
+      expect(ensureReady).toHaveBeenCalledTimes(2);
+    },
+  );
+});

packages/platform-apple/src/runtime-simulator-readiness.ts

@@ -0,0 +1,11 @@
+import { withMethodScope } from '@agent-device/kernel/scoped-provider';
+import { resolveManagedDeviceReadiness } from '@agent-device/provision-kit/managed-device-scope';
+import { withSimulatorReadiness } from './core/simulator.ts';
+
+export function bindSimulatorReadiness<T extends object>(operations: T): Readonly<T> {
+  const ensureReady = resolveManagedDeviceReadiness();
+  if (!ensureReady) return Object.freeze(operations);
+  return Object.freeze({
+    ...withMethodScope({ ...operations }, (task) => withSimulatorReadiness(ensureReady, task)),
+  });
+}

packages/platform-apple/src/runtime.ts

@@ -4,6 +4,7 @@ import {
   localRuntimeOwner,
   whenAdmitted,
 } from '@agent-device/contracts/platform-runtime';
+import { bindSimulatorReadiness } from './runtime-simulator-readiness.ts';
 import type { NetworkDumpInput } from '@agent-device/contracts/network-runtime';
 import type {
   PlatformRuntimeHost,
@@ -494,7 +495,7 @@ export function createApplePlatformRuntime(host: PlatformRuntimeHost): PlatformR
         device: logs.device,
         owner,
         facts,
-        operations: Object.freeze(operations),
+        operations: bindSimulatorReadiness(operations),
         [Symbol.asyncDispose]: async () => await logs[Symbol.asyncDispose](),
       }) satisfies DeviceBinding<PlatformRuntimeOperations>;
     },

packages/provision-kit/src/managed-device-scope.ts

@@ -28,10 +28,20 @@ export function assertManagedDeviceIdentity(managed: ManagedDeviceScope, device:
   }
 }
 
-export async function delegateManagedDeviceReadiness(device: DeviceInfo): Promise<boolean> {
+export function resolveManagedDeviceReadiness():
+  | ((device: DeviceInfo) => Promise<void>)
+  | undefined {
   const managed = currentManagedDeviceScope();
-  if (!managed) return false;
-  assertManagedDeviceIdentity(managed, device);
-  await managed.ensureReady();
+  if (!managed) return undefined;
+  return async (device) => {
+    assertManagedDeviceIdentity(managed, device);
+    await managed.ensureReady();
+  };
+}
+
+export async function delegateManagedDeviceReadiness(device: DeviceInfo): Promise<boolean> {
+  const ensureReady = resolveManagedDeviceReadiness();
+  if (!ensureReady) return false;
+  await ensureReady(device);
   return true;
 }