perf: adapt ios runner uptime preflight

Author: thymikee

src/platforms/ios/__tests__/runner-command-retry.test.ts

@@ -1,7 +1,11 @@
 import { beforeEach, test, vi } from 'vitest';
 import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { IOS_SIMULATOR } from '../../../__tests__/test-utils/index.ts';
 import { AppError } from '../../../utils/errors.ts';
+import { flushDiagnosticsToSessionFile, withDiagnosticsScope } from '../../../utils/diagnostics.ts';
 import type { RunnerSession } from '../runner-session-types.ts';
 
 const {
@@ -131,6 +135,28 @@ test('mutating commands restart stale sessions when readiness preflight times ou
   assert.equal(mockExecuteRunnerCommandWithSession.mock.calls[1]?.[1], freshSession);
 });
 
+test('mutating commands emit readiness recovery diagnostics after failed preflight restart succeeds', async () => {
+  const staleSession = makeRunnerSession({ port: 8100, ready: true });
+  const freshSession = makeRunnerSession({ port: 8101, ready: false });
+
+  mockEnsureRunnerSession.mockResolvedValueOnce(staleSession).mockResolvedValueOnce(freshSession);
+  mockExecuteRunnerCommandWithSession
+    .mockRejectedValueOnce(
+      new AppError('COMMAND_FAILED', 'fetch failed', {
+        runnerReadinessPreflightFailed: true,
+      }),
+    )
+    .mockResolvedValueOnce({ message: 'tapped' });
+
+  const diagnostics = await captureDiagnostics(async () => {
+    const result = await runIosRunnerCommand(IOS_SIMULATOR, { command: 'tap', x: 120, y: 240 });
+    assert.deepEqual(result, { message: 'tapped' });
+  });
+
+  assert.match(diagnostics, /ios_runner_readiness_preflight_recovered/);
+  assert.match(diagnostics, /"recovery":"session_restarted"/);
+});
+
 test('mutating commands do not restart or replay after command send failure', async () => {
   const session = makeRunnerSession({ port: 8100, ready: true });
 
@@ -175,6 +201,35 @@ test('mutating commands recover cached responses before invalidating after comma
   assert.equal(statusCommand.statusCommandId, sentCommand.commandId);
 });
 
+test('mutating commands run status recovery after transport failure when readiness preflight was skipped', async () => {
+  const session = makeRunnerSession({ port: 8100, ready: true });
+
+  mockEnsureRunnerSession.mockResolvedValueOnce(session);
+  mockExecuteRunnerCommandWithSession
+    .mockRejectedValueOnce(
+      new AppError('COMMAND_FAILED', 'fetch failed', {
+        runnerReadinessPreflightSkipped: true,
+        runnerReadinessPreflightSkipReason: 'recent_successful_response',
+      }),
+    )
+    .mockResolvedValueOnce({
+      lifecycleState: 'completed',
+      lifecycleResponseJson: JSON.stringify({ ok: true, data: { message: 'tapped' } }),
+    });
+
+  const diagnostics = await captureDiagnostics(async () => {
+    const result = await runIosRunnerCommand(IOS_SIMULATOR, { command: 'tap', x: 120, y: 240 });
+    assert.deepEqual(result, { message: 'tapped' });
+  });
+
+  assert.equal(mockInvalidateRunnerSession.mock.calls.length, 0);
+  assert.equal(mockExecuteRunnerCommandWithSession.mock.calls.length, 2);
+  assert.equal(mockExecuteRunnerCommandWithSession.mock.calls[1]?.[2].command, 'status');
+  assert.match(diagnostics, /ios_runner_command_status_recovery/);
+  assert.match(diagnostics, /"readinessPreflightSkipped":true/);
+  assert.match(diagnostics, /"readinessPreflightSkipReason":"recent_successful_response"/);
+});
+
 test('mutating commands keep invalidating when status cannot find the command', async () => {
   const session = makeRunnerSession({ port: 8100, ready: true });
 
@@ -347,3 +402,21 @@ function makeRunnerSession(overrides: Partial<RunnerSession> = {}): RunnerSessio
     ...overrides,
   } as RunnerSession;
 }
+
+async function captureDiagnostics(callback: () => Promise<void>): Promise<string> {
+  const previousHome = process.env.HOME;
+  process.env.HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-runner-diag-'));
+  try {
+    return await withDiagnosticsScope(
+      { session: 'runner-client-test', requestId: 'request-1', command: 'tap' },
+      async () => {
+        await callback();
+        const diagnosticsPath = flushDiagnosticsToSessionFile({ force: true });
+        assert.ok(diagnosticsPath);
+        return fs.readFileSync(diagnosticsPath, 'utf8');
+      },
+    );
+  } finally {
+    process.env.HOME = previousHome;
+  }
+}

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

@@ -1,8 +1,12 @@
 import assert from 'node:assert/strict';
 import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { beforeEach, test, vi } from 'vitest';
 import { IOS_SIMULATOR } from '../../../__tests__/test-utils/index.ts';
 import { AppError } from '../../../utils/errors.ts';
+import { flushDiagnosticsToSessionFile, withDiagnosticsScope } from '../../../utils/diagnostics.ts';
 import type { RunnerSession } from '../runner-session-types.ts';
 
 const {
@@ -196,6 +200,26 @@ test('runner session probes readiness before mutating commands', async () => {
   });
 });
 
+test('runner session emits explicit diagnostics when readiness preflight is used', async () => {
+  const session = makeRunnerSession({ ready: false });
+  mockWaitForRunner.mockResolvedValueOnce(runnerResponse({ uptimeMs: 42 }));
+  mockSendRunnerCommandOnce.mockResolvedValueOnce(runnerResponse({ tapped: true }));
+
+  const diagnostics = await captureDiagnostics(async () => {
+    await executeRunnerCommandWithSession(
+      IOS_SIMULATOR,
+      session,
+      { command: 'tap', x: 120, y: 240, appBundleId: 'com.example.demo' },
+      '/tmp/runner.log',
+      30_000,
+    );
+  });
+
+  assert.match(diagnostics, /ios_runner_readiness_preflight_used/);
+  assert.match(diagnostics, /"reason":"startup"/);
+  assert.match(diagnostics, /ios_runner_readiness_preflight/);
+});
+
 test('runner session skips readiness preflight for tap commands after a recent successful response', async () => {
   const session = makeRunnerSession({ ready: true, lastSuccessfulRunnerResponseAtMs: Date.now() });
   mockSendRunnerCommandOnce.mockResolvedValueOnce(runnerResponse({ tapped: true }));
@@ -213,6 +237,47 @@ test('runner session skips readiness preflight for tap commands after a recent s
   assert.equal(mockSendRunnerCommandOnce.mock.calls.length, 1);
 });
 
+test('runner session emits explicit diagnostics when readiness preflight is skipped', async () => {
+  const session = makeRunnerSession({ ready: true, lastSuccessfulRunnerResponseAtMs: Date.now() });
+  mockSendRunnerCommandOnce.mockResolvedValueOnce(runnerResponse({ tapped: true }));
+
+  const diagnostics = await captureDiagnostics(async () => {
+    await executeRunnerCommandWithSession(
+      IOS_SIMULATOR,
+      session,
+      { command: 'tap', x: 120, y: 240, appBundleId: 'com.example.demo' },
+      '/tmp/runner.log',
+      30_000,
+    );
+  });
+
+  assert.match(diagnostics, /ios_runner_readiness_preflight_skipped/);
+  assert.match(diagnostics, /"reason":"recent_successful_response"/);
+  assert.doesNotMatch(diagnostics, /ios_runner_readiness_preflight_used/);
+});
+
+test('runner session marks transport failures after skipped readiness preflight', async () => {
+  const session = makeRunnerSession({ ready: true, lastSuccessfulRunnerResponseAtMs: Date.now() });
+  mockSendRunnerCommandOnce.mockRejectedValueOnce(new Error('fetch failed'));
+
+  await assert.rejects(
+    () =>
+      executeRunnerCommandWithSession(
+        IOS_SIMULATOR,
+        session,
+        { command: 'tap', x: 120, y: 240, appBundleId: 'com.example.demo' },
+        '/tmp/runner.log',
+        30_000,
+      ),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.details?.runnerReadinessPreflightSkipped, true);
+      assert.equal(error.details?.runnerReadinessPreflightSkipReason, 'recent_successful_response');
+      return true;
+    },
+  );
+});
+
 test('runner session skips readiness preflight for selector taps after a recent successful response', async () => {
   const session = makeRunnerSession({ ready: true, lastSuccessfulRunnerResponseAtMs: Date.now() });
   mockSendRunnerCommandOnce.mockResolvedValueOnce(runnerResponse({ tapped: true }));
@@ -489,6 +554,24 @@ function runnerError(error: { code: string; message: string }): Response {
   return new Response(JSON.stringify({ ok: false, error }));
 }
 
+async function captureDiagnostics(callback: () => Promise<void>): Promise<string> {
+  const previousHome = process.env.HOME;
+  process.env.HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-runner-diag-'));
+  try {
+    return await withDiagnosticsScope(
+      { session: 'runner-session-test', requestId: 'request-1', command: 'tap' },
+      async () => {
+        await callback();
+        const diagnosticsPath = flushDiagnosticsToSessionFile({ force: true });
+        assert.ok(diagnosticsPath);
+        return fs.readFileSync(diagnosticsPath, 'utf8');
+      },
+    );
+  } finally {
+    process.env.HOME = previousHome;
+  }
+}
+
 function assertRunnerCommand(
   actual: unknown,
   expected: Record<string, unknown>,

src/platforms/ios/runner-client.ts

@@ -175,14 +175,25 @@ async function executeRunnerCommand(
       );
       session = await ensureRunnerSession(device, { ...options, cleanStaleBundles: true });
       try {
-        return await executeRunnerCommandWithSession(
+        const recovered = await executeRunnerCommandWithSession(
           device,
           session,
           command,
           options.logPath,
           RUNNER_STARTUP_TIMEOUT_MS,
           signal,
         );
+        emitDiagnostic({
+          level: 'debug',
+          phase: 'ios_runner_readiness_preflight_recovered',
+          data: {
+            command: command.command,
+            commandId: command.commandId,
+            recovery: 'session_restarted',
+            sessionId: session.sessionId,
+          },
+        });
+        return recovered;
       } catch (retryErr) {
         const retryAppErr =
           retryErr instanceof AppError
@@ -249,6 +260,14 @@ async function tryRecoverRunnerCommandAfterTransportError(
         command: command.command,
         commandId: command.commandId,
         error: error instanceof Error ? error.message : String(error),
+        readinessPreflightSkipped: readBooleanDetail(
+          transportError,
+          'runnerReadinessPreflightSkipped',
+        ),
+        readinessPreflightSkipReason: readStringDetail(
+          transportError,
+          'runnerReadinessPreflightSkipReason',
+        ),
       },
     });
     return undefined;
@@ -262,6 +281,14 @@ async function tryRecoverRunnerCommandAfterTransportError(
       command: command.command,
       commandId: command.commandId,
       lifecycleState,
+      readinessPreflightSkipped: readBooleanDetail(
+        transportError,
+        'runnerReadinessPreflightSkipped',
+      ),
+      readinessPreflightSkipReason: readStringDetail(
+        transportError,
+        'runnerReadinessPreflightSkipReason',
+      ),
     },
   });
   return handleRunnerCommandStatusRecovery(
@@ -423,6 +450,16 @@ function isRunnerReadinessPreflightTimeout(error: AppError): boolean {
   return message.includes('timeout') || message.includes('timed out');
 }
 
+function readBooleanDetail(error: AppError, key: string): boolean | undefined {
+  const value = error.details?.[key];
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function readStringDetail(error: AppError, key: string): string | undefined {
+  const value = error.details?.[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
 export {
   resolveRunnerDestination,
   resolveRunnerBuildDestination,