fix: resolve simulator app PID via idempotent simctl launch

The --console-pty flag causes PTY buffering that prevents the PID
banner from flushing to the log file reliably (0/5 in testing).

Replace file-based PID polling with an idempotent simctl launch
call via CommandExecutor. Calling simctl launch on an already-running
app returns the existing PID without relaunching (verified 10/10).

Algorithm:
1. Spawn --console-pty with fd-to-file (captures print/NSLog)
2. Wait for app startup
3. Plain simctl launch returns existing app PID
4. Start oslog stream separately for Logger messages

Author: cameroncooke

src/mcp/tools/simulator/__tests__/build_run_sim.test.ts

@@ -15,6 +15,7 @@ import type { LaunchWithLoggingResult } from '../../../../utils/simulator-steps.
 const mockLauncher: SimulatorLauncher = async (
   _uuid,
   _bundleId,
+  _executor,
   _opts?,
 ): Promise<LaunchWithLoggingResult> => ({
   success: true,

src/mcp/tools/simulator/__tests__/launch_app_sim.test.ts

@@ -7,7 +7,7 @@ import type { LaunchWithLoggingResult } from '../../../../utils/simulator-steps.
 import { runLogic } from '../../../../test-utils/test-helpers.ts';
 
 function createMockLauncher(overrides?: Partial<LaunchWithLoggingResult>): SimulatorLauncher {
-  return async (_uuid, _bundleId, _opts?) => ({
+  return async (_uuid, _bundleId, _executor, _opts?) => ({
     success: true,
     processId: 12345,
     logFilePath: '/tmp/mock-logs/test.log',
@@ -112,7 +112,7 @@ describe('launch_app_sim tool', () => {
     it('should pass args and env through to launcher', async () => {
       let capturedArgs: string[] | undefined;
       let capturedEnv: Record<string, string> | undefined;
-      const trackingLauncher: SimulatorLauncher = async (_uuid, _bundleId, opts?) => {
+      const trackingLauncher: SimulatorLauncher = async (_uuid, _bundleId, _executor, opts?) => {
         capturedArgs = opts?.args;
         capturedEnv = opts?.env;
         return { success: true, processId: 12345, logFilePath: '/tmp/test.log' };
@@ -262,7 +262,7 @@ describe('launch_app_sim tool', () => {
 
     it('should not pass env when env is undefined', async () => {
       let capturedEnv: Record<string, string> | undefined;
-      const trackingLauncher: SimulatorLauncher = async (_uuid, _bundleId, opts?) => {
+      const trackingLauncher: SimulatorLauncher = async (_uuid, _bundleId, _executor, opts?) => {
         capturedEnv = opts?.env;
         return { success: true, processId: 12345, logFilePath: '/tmp/test.log' };
       };

src/mcp/tools/simulator/build_run_sim.ts

@@ -452,7 +452,11 @@ export async function build_run_simLogic(
         data: { step: 'launch-app', status: 'started', appPath: appBundlePath },
       });
 
-      const launchResult: LaunchWithLoggingResult = await launcher(simulatorId, bundleId);
+      const launchResult: LaunchWithLoggingResult = await launcher(
+        simulatorId,
+        bundleId,
+        executor,
+      );
       if (!launchResult.success) {
         const errorMessage = launchResult.error ?? 'Failed to launch app';
         log('error', `Failed to launch app: ${errorMessage}`);

src/mcp/tools/simulator/launch_app_sim.ts

@@ -103,10 +103,15 @@ export async function launch_app_simLogic(
   return withErrorHandling(
     ctx,
     async () => {
-      const launchResult: LaunchWithLoggingResult = await launcher(simulatorId, params.bundleId, {
-        args: params.args,
-        env: params.env,
-      });
+      const launchResult: LaunchWithLoggingResult = await launcher(
+        simulatorId,
+        params.bundleId,
+        executor,
+        {
+          args: params.args,
+          env: params.env,
+        },
+      );
 
       if (!launchResult.success) {
         ctx.emit(headerEvent);

src/utils/__tests__/simulator-steps-pid.test.ts

@@ -1,8 +1,8 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
-import * as fs from 'node:fs';
 import type { ChildProcess, SpawnOptions } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import { launchSimulatorAppWithLogging } from '../simulator-steps.ts';
+import type { CommandExecutor } from '../CommandExecutor.ts';
 
 function createMockChild(exitCode: number | null = null): ChildProcess {
   const emitter = new EventEmitter();
@@ -13,38 +13,34 @@ function createMockChild(exitCode: number | null = null): ChildProcess {
   return child;
 }
 
-function createFileWritingSpawner(content: string, delayMs: number = 0) {
-  return (command: string, args: string[], options: SpawnOptions): ChildProcess => {
-    const child = createMockChild(null);
-    const stdio = options.stdio as [unknown, number, number];
-    const fd = stdio[1];
-    if (typeof fd === 'number') {
-      if (delayMs > 0) {
-        setTimeout(() => {
-          try {
-            fs.writeSync(fd, content);
-          } catch {
-            // fd may already be closed by the caller
-          }
-        }, delayMs);
-      } else {
-        fs.writeSync(fd, content);
-      }
-    }
-    return child;
+function createMockSpawner() {
+  return (_command: string, _args: string[], _options: SpawnOptions): ChildProcess => {
+    return createMockChild(null);
   };
 }
 
-describe('launchSimulatorAppWithLogging PID parsing', () => {
+function createMockExecutor(pid?: number): CommandExecutor {
+  return async () => ({
+    success: true,
+    output: pid !== undefined ? `com.example.app: ${pid}` : '',
+    process: { pid: 1 } as never,
+    exitCode: 0,
+  });
+}
+
+describe('launchSimulatorAppWithLogging PID resolution', () => {
   afterEach(() => {
     vi.restoreAllMocks();
   });
 
-  it('extracts PID from standard simctl colon format (bundleId: PID)', async () => {
-    const spawner = createFileWritingSpawner('com.example.app: 42567\n');
+  it('resolves PID via idempotent simctl launch', async () => {
+    const spawner = createMockSpawner();
+    const executor = createMockExecutor(42567);
+
     const result = await launchSimulatorAppWithLogging(
       'test-sim-uuid',
       'com.example.app',
+      executor,
       undefined,
       { spawner },
     );
@@ -53,48 +49,58 @@ describe('launchSimulatorAppWithLogging PID parsing', () => {
     expect(result.processId).toBe(42567);
   });
 
-  it('extracts PID from first line even when app output has bracketed numbers', async () => {
-    const spawner = createFileWritingSpawner(
-      'com.example.app: 42567\n[404] Not Found\nHTTP [200] OK\n',
-    );
+  it('returns undefined processId when executor returns no PID', async () => {
+    const spawner = createMockSpawner();
+    const executor = createMockExecutor();
+
     const result = await launchSimulatorAppWithLogging(
       'test-sim-uuid',
       'com.example.app',
+      executor,
       undefined,
       { spawner },
     );
 
     expect(result.success).toBe(true);
-    expect(result.processId).toBe(42567);
+    expect(result.processId).toBeUndefined();
   });
 
-  it('ignores non-PID first lines and returns undefined', async () => {
-    const spawner = createFileWritingSpawner('Loading resources...\n[404] Not Found\n');
+  it('returns undefined processId when executor fails', async () => {
+    const spawner = createMockSpawner();
+    const executor: CommandExecutor = async () => ({
+      success: false,
+      output: 'Unable to launch',
+      error: 'App not installed',
+      process: { pid: 1 } as never,
+      exitCode: 1,
+    });
+
     const result = await launchSimulatorAppWithLogging(
       'test-sim-uuid',
       'com.example.app',
+      executor,
       undefined,
       { spawner },
     );
 
     expect(result.success).toBe(true);
-    // First line has no colon PID pattern, bracketed numbers are not matched
     expect(result.processId).toBeUndefined();
   });
 
-  it('returns undefined when no PID is found within timeout', async () => {
-    // Write content with no PID pattern at all
-    const spawner = createFileWritingSpawner('Starting application...\nLoading resources...\n');
+  it('reports failure when spawn exits immediately with error', async () => {
+    const spawner = (_command: string, _args: string[], _options: SpawnOptions): ChildProcess => {
+      return createMockChild(1);
+    };
+    const executor = createMockExecutor(42567);
 
-    // Use a short timeout to not slow down tests
     const result = await launchSimulatorAppWithLogging(
       'test-sim-uuid',
       'com.example.app',
+      executor,
       undefined,
       { spawner },
     );
 
-    expect(result.success).toBe(true);
-    expect(result.processId).toBeUndefined();
+    expect(result.success).toBe(false);
   });
 });

src/utils/simulator-steps.ts

@@ -112,9 +112,6 @@ export async function launchSimulatorApp(
   return { success: true, processId };
 }
 
-const PID_POLL_TIMEOUT_MS = 5000;
-const PID_POLL_INTERVAL_MS = 100;
-
 export type ProcessSpawner = (
   command: string,
   args: string[],
@@ -131,13 +128,20 @@ export interface LaunchWithLoggingResult {
 
 /**
  * Launch an app on a simulator with implicit runtime logging.
- * Uses `simctl launch --console-pty` to both launch the app and stream its
- * stdout/stderr directly to a log file via OS-level fd inheritance.
- * The process is fully detached — no Node.js streams or lifecycle management.
+ *
+ * Uses a two-phase approach:
+ * 1. `simctl launch --console-pty` captures the app's stdout/stderr (print/NSLog)
+ *    to a log file via detached fd inheritance. PTY buffering prevents reading
+ *    the PID banner from this file reliably.
+ * 2. A follow-up idempotent `simctl launch` (without --terminate) returns the
+ *    already-running app's PID without relaunching it.
+ *
+ * OSLog (Logger) messages are captured separately via `simctl spawn log stream`.
  */
 export async function launchSimulatorAppWithLogging(
   simulatorUuid: string,
   bundleId: string,
+  executor: CommandExecutor,
   options?: {
     args?: string[];
     env?: Record<string, string>;
@@ -183,8 +187,8 @@ export async function launchSimulatorAppWithLogging(
     fs.closeSync(fd);
     fd = undefined;
 
-    // Brief wait then check for immediate crash
-    await new Promise((resolve) => setTimeout(resolve, 300));
+    // Wait for app startup then check for immediate crash
+    await new Promise((resolve) => setTimeout(resolve, 500));
     if (child.exitCode !== null && child.exitCode !== 0) {
       const logContent = readLogFileSafe(logFilePath);
       return {
@@ -194,7 +198,8 @@ export async function launchSimulatorAppWithLogging(
       };
     }
 
-    const processId = await resolveAppPid(logFilePath);
+    // Resolve PID via idempotent simctl launch (returns existing app's PID)
+    const processId = await resolveAppPidViaLaunch(simulatorUuid, bundleId, executor);
 
     // Start OSLog stream as a separate detached process writing to its own file
     const osLogPath = startOsLogStream(simulatorUuid, bundleId, logsDir, spawner);
@@ -215,22 +220,24 @@ export async function launchSimulatorAppWithLogging(
   }
 }
 
-async function resolveAppPid(logFilePath: string): Promise<number | undefined> {
-  const start = Date.now();
-  while (Date.now() - start < PID_POLL_TIMEOUT_MS) {
-    const content = readLogFileSafe(logFilePath);
-    if (content) {
-      const firstLine = content.split('\n').find((l) => l.trim().length > 0);
-      if (firstLine) {
-        const colonMatch = firstLine.match(/:\s*(\d+)\s*$/);
-        if (colonMatch) {
-          return parseInt(colonMatch[1], 10);
-        }
-      }
-    }
-    await new Promise((resolve) => setTimeout(resolve, PID_POLL_INTERVAL_MS));
+async function resolveAppPidViaLaunch(
+  simulatorUuid: string,
+  bundleId: string,
+  executor: CommandExecutor,
+): Promise<number | undefined> {
+  // simctl launch is idempotent: calling it on an already-running app
+  // returns the existing PID without relaunching.
+  const result = await executor(
+    ['xcrun', 'simctl', 'launch', simulatorUuid, bundleId],
+    'Resolve App PID',
+    false,
+  );
+  if (!result.success) {
+    log('warn', `Failed to resolve app PID: ${result.error ?? result.output}`);
+    return undefined;
   }
-  return undefined;
+  const pidMatch = result.output?.match(/:\s*(\d+)\s*$/);
+  return pidMatch ? parseInt(pidMatch[1], 10) : undefined;
 }
 
 function readLogFileSafe(filePath: string): string {