fix(platform-ios): gracefully stop XCTest agent (#139)

## What is this?

Harness now ends the iOS XCTest permission agent gracefully when a test
run finishes, instead of immediately signalling `xcodebuild` to stop.
Previously, normal teardown sent `SIGTERM` to the long-running
`xcodebuild test-without-building` session while its UI test was still
active, interrupting an otherwise-passing agent session and leaving
stray simulator and `xcodebuild` processes behind.

## How does it work?

The on-device XCTest agent gains a `/shutdown` endpoint. When it
receives the request it flips an internal flag, its session loop exits
on the next tick, and the UI test completes on its own so `xcodebuild`
finishes and tears down its own child processes. During teardown the
platform controller asks the agent to shut down first and waits, bounded
by a timeout, for the process to exit. If the request fails or the agent
does not stop in time, Harness falls back to the existing
`SIGTERM`/`SIGKILL` termination. The shutdown timeout is raised to
accommodate the slower-but-clean exit.

## Why is this useful?

Test runs finish without cutting off a healthy agent session, and fewer
orphaned simulator and `xcodebuild` processes survive teardown —
reducing flakiness and resource leaks across consecutive iOS runs.

Author: mrousavy

.nx/version-plans/graceful-ios-xctest-agent-shutdown.md

@@ -0,0 +1,5 @@
+---
+__default__: patch
+---
+
+Harness now asks the iOS XCTest permission agent to stop gracefully when a test run ends, letting its session finish on its own before Harness falls back to terminating xcodebuild. This avoids cutting off an otherwise-passing agent session during teardown and leaves fewer stray simulator and xcodebuild processes behind after tests complete.

packages/platform-ios/src/__tests__/xctest-agent-client.test.ts

@@ -33,6 +33,16 @@ describe('xctest-agent client', () => {
         }),
         headers: {},
         statusCode: 200,
+      })
+      .mockResolvedValueOnce({
+        body: JSON.stringify({
+          permissions: {
+            autoAcceptPermissions: true,
+          },
+          status: 'shutting-down',
+        }),
+        headers: {},
+        statusCode: 200,
       });
     const dispose = vi.fn(async () => undefined);
     const client = createXCTestAgentClient({
@@ -56,6 +66,7 @@ describe('xctest-agent client', () => {
     await expect(client.getPermissionsConfig()).resolves.toEqual({
       autoAcceptPermissions: true,
     });
+    await expect(client.shutdown()).resolves.toBeUndefined();
 
     expect(request).toHaveBeenNthCalledWith(1, {
       method: 'GET',
@@ -74,6 +85,11 @@ describe('xctest-agent client', () => {
       path: '/permissions',
       body: undefined,
     });
+    expect(request).toHaveBeenNthCalledWith(4, {
+      method: 'POST',
+      path: '/shutdown',
+      body: undefined,
+    });
     await client.dispose();
     expect(dispose).toHaveBeenCalledTimes(1);
   });

packages/platform-ios/src/__tests__/xctest-agent.test.ts

@@ -18,6 +18,7 @@ const mocks = vi.hoisted(() => ({
     status: 'ok',
   })),
   kill: vi.fn(),
+  shutdown: vi.fn(async () => undefined),
   spawn: vi.fn(),
 }));
 
@@ -38,6 +39,7 @@ vi.mock('../xctest-agent-client.js', () => ({
     dispose: mocks.disposeClient,
     getPermissionsConfig: vi.fn(),
     health: mocks.health,
+    shutdown: mocks.shutdown,
   })),
 }));
 
@@ -148,6 +150,11 @@ describe('xctest-agent orchestration', () => {
     deviceBuildRoot = path.join(tempProjectRoot, '.harness', 'xctest-agent');
     rmBuildRoot();
     mocks.activeAgentStops.length = 0;
+    mocks.shutdown.mockImplementation(async () => {
+      for (const stop of mocks.activeAgentStops) {
+        stop();
+      }
+    });
     mocks.spawn.mockImplementation((file: string, args?: string[]) => {
       if (file === 'xcodebuild' && args?.join(' ') === '-version') {
         return Promise.resolve({ stdout: xcodeVersion });
@@ -466,7 +473,8 @@ describe('xctest-agent orchestration', () => {
 
     await controller.dispose();
 
-    expect(mocks.kill).toHaveBeenCalledTimes(1);
+    expect(mocks.shutdown).toHaveBeenCalledTimes(1);
+    expect(mocks.kill).not.toHaveBeenCalled();
     expect(mocks.disposeClient).toHaveBeenCalledTimes(1);
   });
 
@@ -488,7 +496,48 @@ describe('xctest-agent orchestration', () => {
     });
   });
 
-  it('kills the agent process during disposal', async () => {
+  it('requests graceful shutdown during disposal', async () => {
+    const controller = createXCTestAgentController({
+      port: 49154,
+      shutdownTimeoutMs: 100,
+      target: {
+        kind: 'simulator',
+        id: 'sim-timeout',
+      },
+    });
+
+    await controller.ensureStarted();
+    await controller.dispose();
+
+    expect(mocks.shutdown).toHaveBeenCalledTimes(1);
+    expect(mocks.disposeClient).toHaveBeenCalledTimes(1);
+    expect(mocks.kill).not.toHaveBeenCalled();
+  });
+
+  it('kills the agent process when graceful shutdown times out', async () => {
+    mocks.shutdown.mockResolvedValue(undefined);
+
+    const controller = createXCTestAgentController({
+      port: 49154,
+      shutdownTimeoutMs: 1,
+      target: {
+        kind: 'simulator',
+        id: 'sim-timeout',
+      },
+    });
+
+    await controller.ensureStarted();
+    await controller.dispose();
+
+    expect(mocks.kill).toHaveBeenCalledTimes(1);
+    expect(mocks.kill).toHaveBeenCalledWith('SIGTERM');
+  });
+
+  it('kills the agent process when the graceful shutdown request hangs', async () => {
+    mocks.shutdown.mockImplementation(
+      () => new Promise<undefined>(() => undefined)
+    );
+
     const controller = createXCTestAgentController({
       port: 49154,
       shutdownTimeoutMs: 1,
@@ -506,6 +555,8 @@ describe('xctest-agent orchestration', () => {
   });
 
   it('force kills the agent process when graceful shutdown times out', async () => {
+    mocks.shutdown.mockResolvedValue(undefined);
+
     mocks.spawn.mockImplementation((file: string, args?: string[]) => {
       if (file === 'xcodebuild' && args?.join(' ') === '-version') {
         return Promise.resolve({ stdout: xcodeVersion });

packages/platform-ios/src/xctest-agent-client.ts

@@ -9,7 +9,7 @@ export type XCTestAgentPermissionsConfiguration = {
 
 type XCTestAgentHealthResponse = {
   permissions: XCTestAgentPermissionsConfiguration;
-  status: 'ok';
+  status: 'ok' | 'shutting-down';
 };
 
 type XCTestAgentPermissionsResponse = {
@@ -23,6 +23,7 @@ export type XCTestAgentClient = {
   dispose: () => Promise<void>;
   getPermissionsConfig: () => Promise<XCTestAgentPermissionsConfiguration>;
   health: () => Promise<XCTestAgentHealthResponse>;
+  shutdown: () => Promise<void>;
 };
 
 export const createXCTestAgentClient = (
@@ -67,6 +68,12 @@ export const createXCTestAgentClient = (
 
       return response.permissions;
     },
+    shutdown: async () => {
+      await requestJson<XCTestAgentHealthResponse>({
+        method: 'POST',
+        path: '/shutdown',
+      });
+    },
     dispose: async () => {
       await transport.dispose();
     },

packages/platform-ios/src/xctest-agent.ts

@@ -33,7 +33,7 @@ const XCTEST_AGENT_XCTESTRUN_FILE_ENV = 'HARNESS_IOS_XCTESTRUN_FILE';
 const XCTEST_AGENT_DERIVED_DATA_PATH_ENV =
   'HARNESS_IOS_XCTEST_DERIVED_DATA_PATH';
 const XCTEST_AGENT_STARTUP_TIMEOUT_MS = 120_000;
-const XCTEST_AGENT_SHUTDOWN_TIMEOUT_MS = 5_000;
+const XCTEST_AGENT_SHUTDOWN_TIMEOUT_MS = 30_000;
 const XCTEST_AGENT_STARTUP_POLL_INTERVAL_MS = 250;
 const HARNESS_DIRNAME = '.harness';
 const XCTEST_AGENT_BUILD_DIRNAME = 'xctest-agent';
@@ -778,6 +778,36 @@ const waitForShutdown = async (options: {
   return result !== timedOut;
 };
 
+const waitForGracefulShutdown = async (options: {
+  client: ReturnType<typeof createXCTestAgentClient>;
+  processTask: Promise<void> | null;
+  shutdownTimeoutMs: number;
+}): Promise<{ didStop: boolean; requestError: unknown | null }> => {
+  let requestError: unknown | null = null;
+  const timedOut = Symbol('timedOut');
+
+  const result = await Promise.race([
+    (async () => {
+      try {
+        await options.client.shutdown();
+      } catch (error) {
+        requestError = error;
+      }
+
+      return await waitForShutdown({
+        processTask: options.processTask,
+        shutdownTimeoutMs: options.shutdownTimeoutMs,
+      });
+    })(),
+    delay(options.shutdownTimeoutMs).then(() => timedOut),
+  ]);
+
+  return {
+    didStop: result !== timedOut && result === true,
+    requestError,
+  };
+};
+
 const waitForChildProcessExit = async (subprocess: Subprocess) => {
   const childProcess = await subprocess.nodeChildProcess;
 
@@ -1122,6 +1152,50 @@ export const createXCTestAgentController = (options: {
       target.kind
     );
 
+    if (currentClient) {
+      try {
+        xctestAgentLogger.info(
+          'Requesting XCTest agent graceful shutdown for %s target',
+          target.kind,
+        );
+
+        const gracefulShutdown = await waitForGracefulShutdown({
+          client: currentClient,
+          processTask: currentProcessTask,
+          shutdownTimeoutMs,
+        });
+
+        if (gracefulShutdown.didStop) {
+          xctestAgentLogger.info(
+            'XCTest agent session for %s target stopped gracefully',
+            target.kind,
+          );
+          await currentClient.dispose();
+          return;
+        }
+
+        if (gracefulShutdown.requestError) {
+          xctestAgentLogger.warn(
+            'XCTest agent graceful shutdown request failed for %s: %s',
+            target.kind,
+            getErrorMessage(gracefulShutdown.requestError),
+          );
+        }
+
+        xctestAgentLogger.warn(
+          'XCTest agent session for %s target did not stop gracefully after %dms; terminating xcodebuild',
+          target.kind,
+          shutdownTimeoutMs,
+        );
+      } catch (error) {
+        xctestAgentLogger.warn(
+          'XCTest agent graceful shutdown failed for %s: %s',
+          target.kind,
+          getErrorMessage(error),
+        );
+      }
+    }
+
     await currentClient?.dispose();
     await stopProcess({
       process: currentProcess,

packages/platform-ios/xctest-agent/HarnessXCTestAgentUITests/HarnessXCTestAgentUITests.swift

@@ -4,6 +4,7 @@ import Network
 final class HarnessXCTestAgentState {
   private let lock = NSLock()
   private var _permissions: PermissionPromptConfiguration
+  private var _shouldShutdown = false
 
   init(permissions: PermissionPromptConfiguration) {
     _permissions = permissions
@@ -20,6 +21,18 @@ final class HarnessXCTestAgentState {
     _permissions = permissions
     lock.unlock()
   }
+
+  var shouldShutdown: Bool {
+    lock.lock()
+    defer { lock.unlock() }
+    return _shouldShutdown
+  }
+
+  func requestShutdown() {
+    lock.lock()
+    _shouldShutdown = true
+    lock.unlock()
+  }
 }
 
 private struct XCTestAgentHealthResponse: Codable {
@@ -264,6 +277,15 @@ final class HarnessXCTestAgentUITests: XCTestCase {
       return jsonResponse(XCTestAgentPermissionsResponse(permissions: state.permissions))
     case ("GET", "/permissions"):
       return jsonResponse(XCTestAgentPermissionsResponse(permissions: state.permissions))
+    case ("POST", "/shutdown"):
+      log("shutdown requested")
+      state.requestShutdown()
+      return jsonResponse(
+        XCTestAgentHealthResponse(
+          permissions: state.permissions,
+          status: "shutting-down"
+        )
+      )
     default:
       return XCTestAgentResponse(body: Data("{\"error\":\"not found\"}".utf8), statusCode: 404)
     }
@@ -315,7 +337,7 @@ final class HarnessXCTestAgentUITests: XCTestCase {
 
     let sessionDeadline = Date().addingTimeInterval(Constants.defaultSessionDuration)
 
-    while Date() < sessionDeadline {
+    while Date() < sessionDeadline && !state.shouldShutdown {
       observeTargetApplication()
 
       for capability in capabilities {
@@ -327,6 +349,6 @@ final class HarnessXCTestAgentUITests: XCTestCase {
       )
     }
 
-    log("testAgentSession completed")
+    log("testAgentSession completed (shutdownRequested=\(state.shouldShutdown))")
   }
 }