fix: keep iOS runner hot across app closes

Author: thymikee

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -48,6 +48,7 @@ final class RunnerTests: XCTestCase {
   let firstInteractionAfterActivateDelay: TimeInterval = 0.25
   let scrollInteractionIdleTimeoutDefault: TimeInterval = 1.0
   let tvRemoteDoublePressDelayDefault: TimeInterval = 0.0
+  let xctestIdleKeepaliveInterval: TimeInterval = 5.0
   let minRecordingFps = 1
   let maxRecordingFps = 120
   let minRecordingQuality = 5
@@ -119,6 +120,18 @@ final class RunnerTests: XCTestCase {
       self.handle(connection: conn)
     }
     listener?.start(queue: transportQueue)
+    let idleKeepaliveTimer = DispatchSource.makeTimerSource(queue: transportQueue)
+    idleKeepaliveTimer.schedule(
+      deadline: .now() + xctestIdleKeepaliveInterval,
+      repeating: xctestIdleKeepaliveInterval
+    )
+    idleKeepaliveTimer.setEventHandler {
+      NSLog("AGENT_DEVICE_RUNNER_IDLE_KEEPALIVE")
+    }
+    idleKeepaliveTimer.resume()
+    defer {
+      idleKeepaliveTimer.cancel()
+    }
 
     guard let expectation = doneExpectation else {
       XCTFail("runner expectation was not initialized")

src/daemon/handlers/__tests__/session.test.ts

@@ -3013,6 +3013,48 @@ test('close <app> on iOS stops runner before app close dispatch and performs fin
   expect(calls).toEqual(['stop-runner', 'close:com.example.app', 'stop-runner']);
 });
 
+test('close <app> on iOS simulator retains runner while terminating app', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-simulator-close-session';
+  sessionStore.set(sessionName, {
+    ...makeSession(sessionName, {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'iPhone 17 Pro',
+      kind: 'simulator',
+      booted: true,
+    }),
+    appName: 'com.example.app',
+  });
+
+  const calls: string[] = [];
+  mockStopIosRunner.mockImplementation(async () => {
+    calls.push('stop-runner');
+  });
+  mockDispatch.mockImplementation(async (_device, command, positionals) => {
+    calls.push(`${command}:${positionals.join(' ')}`);
+    return {};
+  });
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'close',
+      positionals: ['com.example.app'],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  expect(response).toBeTruthy();
+  expect(response?.ok).toBe(true);
+  expect(calls).toEqual(['close:com.example.app']);
+});
+
 test('close <app> on macOS stops runner before app close dispatch and dismisses automation alert', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'macos-close-session';

src/daemon/handlers/session-close.ts

@@ -96,10 +96,11 @@ async function stopAppleRunnerForClose(session: SessionState): Promise<void> {
 }
 
 function shouldRetainAppleRunnerAfterClose(req: DaemonRequest, session: SessionState): boolean {
-  const hasCloseTarget = (req.positionals?.length ?? 0) > 0;
-  return (
-    isIosSimulator(session.device) && !hasCloseTarget && !req.flags?.shutdown && !session.recording
-  );
+  return isIosSimulator(session.device) && !req.flags?.shutdown && !session.recording;
+}
+
+function shouldStopAppleRunnerBeforeTargetedClose(session: SessionState): boolean {
+  return isApplePlatform(session.device.platform) && !isIosSimulator(session.device);
 }
 
 export async function teardownSessionResources(
@@ -130,7 +131,7 @@ export async function handleCloseCommand(params: {
     await stopAppLog(session.appLog);
   }
   if (req.positionals && req.positionals.length > 0) {
-    if (isApplePlatform(session.device.platform)) {
+    if (shouldStopAppleRunnerBeforeTargetedClose(session)) {
       await stopAppleRunnerForClose(session);
     }
     await dispatchCommand(session.device, 'close', req.positionals, req.flags?.out, {

src/platforms/ios/__tests__/runner-transport.test.ts

@@ -2,7 +2,9 @@ import fs from 'node:fs';
 import { afterEach, beforeEach, test, vi } from 'vitest';
 import assert from 'node:assert/strict';
 import type { DeviceInfo } from '../../../utils/device.ts';
+import type { ExecBackgroundResult } from '../../../utils/exec.ts';
 import { AppError } from '../../../utils/errors.ts';
+import type { RunnerSession } from '../runner-session-types.ts';
 
 const { mockRunCmd } = vi.hoisted(() => ({
   mockRunCmd: vi.fn(),
@@ -106,6 +108,37 @@ test('waitForRunner keeps tunnel IP lookup request-local when no tunnel IP is av
   assert.equal(vi.mocked(fetch).mock.calls[0]?.[0], 'http://127.0.0.1:8100/command');
 });
 
+test('waitForRunner uses simulator fallback within the attempt for ready sessions', async () => {
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async () => {
+      throw new Error('ECONNREFUSED');
+    }),
+  );
+  mockRunCmd.mockResolvedValue({ exitCode: 0, stdout: '{"ok":true}', stderr: '' });
+
+  const response = await waitForRunner(
+    iosSimulator,
+    8100,
+    { command: 'uptime' },
+    undefined,
+    5_000,
+    makeReadyRunnerSession(),
+  );
+
+  assert.equal(await response.text(), '{"ok":true}');
+  assert.equal(vi.mocked(fetch).mock.calls.length, 1);
+  assert.equal(mockRunCmd.mock.calls.length, 1);
+  assert.equal(mockRunCmd.mock.calls[0]?.[0], 'xcrun');
+  assert.deepEqual(mockRunCmd.mock.calls[0]?.[1]?.slice(0, 5), [
+    'simctl',
+    'spawn',
+    'sim-1',
+    '/usr/bin/curl',
+    '-s',
+  ]);
+});
+
 test('waitForRunner invalidates cached tunnel IP when localhost fallback succeeds', async () => {
   const tunnelIps = ['fd00::123', 'fd00::456'];
   mockRunCmd.mockImplementation(async (_cmd: string, args: string[]) => {
@@ -170,3 +203,17 @@ function stubSuccessfulFetch(): void {
     vi.fn(async () => new Response('{}')),
   );
 }
+
+function makeReadyRunnerSession(): RunnerSession {
+  return {
+    sessionId: 'ready-session',
+    device: iosSimulator,
+    deviceId: iosSimulator.id,
+    port: 8100,
+    xctestrunPath: '/tmp/runner.xctestrun',
+    jsonPath: '/tmp/runner.json',
+    testPromise: Promise.resolve({ exitCode: 0, stdout: '', stderr: '' }),
+    child: { pid: 1234, exitCode: null } as ExecBackgroundResult['child'],
+    ready: true,
+  };
+}

src/platforms/ios/runner-transport.ts

@@ -81,6 +81,16 @@ export async function waitForRunner(
           },
         });
         if (response) return response;
+        if (device.kind === 'simulator' && session?.ready) {
+          const simulatorResponse = await tryRunnerSimulatorEndpoint(device, port, command, {
+            signal,
+            attemptDeadline,
+            onError: (err) => {
+              lastError = err;
+            },
+          });
+          if (simulatorResponse) return simulatorResponse;
+        }
         if (device.kind === 'device' && usedCachedTunnelIp) {
           invalidateDeviceTunnelIpCache(device.id);
           const refreshed = await getEndpoints(attemptDeadline?.remainingMs(), true);
@@ -238,6 +248,31 @@ async function tryRunnerEndpoints(
   return null;
 }
 
+async function tryRunnerSimulatorEndpoint(
+  device: DeviceInfo,
+  port: number,
+  command: RunnerCommand,
+  params: {
+    signal?: AbortSignal;
+    attemptDeadline?: Deadline;
+    onError: (error: unknown) => void;
+  },
+): Promise<Response | null> {
+  const { signal, attemptDeadline, onError } = params;
+  const remainingMs = attemptDeadline?.remainingMs() ?? RUNNER_COMMAND_TIMEOUT_MS;
+  if (remainingMs <= 0) return null;
+  try {
+    const simResponse = await postCommandViaSimulator(device, port, command, remainingMs, signal);
+    return new Response(simResponse.body, { status: simResponse.status });
+  } catch (err) {
+    if (signal?.aborted || isRequestCanceledError(err)) {
+      throw createRequestCanceledError();
+    }
+    onError(err);
+    return null;
+  }
+}
+
 async function getDeviceTunnelIpForRequest(params: {
   device: DeviceInfo;
   timeoutBudgetMs?: number;