feat: add --shutdown option to close command for iOS simulator teardown (#176)

* feat: add --shutdown option to close command for iOS simulator teardown (#172)

When --shutdown is passed, close ends the session then runs xcrun simctl
shutdown on the associated simulator. Shutdown result (success, exitCode,
stdout, stderr) is included in the JSON response data.

The option is silently ignored for non-simulator targets (physical iOS
devices, Android). A shutdownSimulator override is injected into
handleSessionCommands for testability.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: document close --shutdown option for iOS simulator teardown

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: keep close --shutdown successful when simulator shutdown fails

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: thymikee

skills/agent-device/references/session-management.md

@@ -21,6 +21,7 @@ Sessions isolate device context. A device can only be held by one session at a t
 - On iOS, `appstate` is session-scoped and requires a matching active session on the target device.
 - For dev loops where runtime state can persist (for example React Native Fast Refresh), use `open <app> --relaunch` to restart the app process in the same session.
 - Use `--save-script [path]` to record replay scripts on `close`; path is a file path and parent directories are created automatically.
+- Use `close --shutdown` (iOS simulator only) to shut down the simulator as part of session teardown, preventing resource leakage in multi-tenant or CI workloads.
 - For ambiguous bare `--save-script` values, prefer `--save-script=workflow.ad` or `./workflow.ad`.
 - For deterministic replay scripts, prefer selector-based actions and assertions.
 - Use `replay -u` to update selector drift during maintenance.

src/__tests__/cli-close.test.ts

@@ -153,3 +153,22 @@ test('close treats structured daemon startup failure as no-op without relying on
   assert.equal(result.stdout, '');
   assert.equal(result.stderr, '');
 });
+
+test('close --shutdown is accepted as a valid flag', async () => {
+  const result = await runCliCapture(['close', '--shutdown']);
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  assert.equal(result.stdout, '');
+  assert.equal(result.stderr, '');
+});
+
+test('close --shutdown --json treats daemon startup failure as no-op success', async () => {
+  const result = await runCliCapture(['close', '--shutdown', '--json']);
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  const payload = JSON.parse(result.stdout);
+  assert.equal(payload.success, true);
+  assert.equal(payload.data.closed, 'session');
+  assert.equal(payload.data.source, 'no-daemon');
+  assert.equal(result.stderr, '');
+});

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

@@ -2837,3 +2837,179 @@ test('session_list includes device_udid and ios_simulator_device_set for iOS ses
     assert.equal(android?.ios_simulator_device_set, undefined);
   }
 });
+
+test('close --shutdown calls shutdownSimulator for iOS simulator and includes result in response', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-shutdown-session';
+  sessionStore.set(sessionName, makeSession(sessionName, {
+    platform: 'ios',
+    id: 'sim-udid-1',
+    name: 'iPhone 15',
+    kind: 'simulator',
+    booted: true,
+  }));
+
+  const shutdownCalls: string[] = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'close',
+      positionals: [],
+      flags: { shutdown: true },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    stopIosRunner: async () => {},
+    shutdownSimulator: async (device) => {
+      shutdownCalls.push(device.id);
+      return { success: true, exitCode: 0, stdout: '', stderr: '' };
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.deepEqual(shutdownCalls, ['sim-udid-1']);
+  assert.equal(sessionStore.get(sessionName), undefined);
+  if (response && response.ok) {
+    assert.equal(response.data?.session, sessionName);
+    assert.deepEqual(response.data?.shutdown, { success: true, exitCode: 0, stdout: '', stderr: '' });
+  }
+});
+
+test('close --shutdown is ignored for non-simulator iOS devices', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-device-shutdown-session';
+  sessionStore.set(sessionName, makeSession(sessionName, {
+    platform: 'ios',
+    id: 'physical-device-1',
+    name: 'My iPhone',
+    kind: 'device',
+    booted: true,
+  }));
+
+  const shutdownCalls: string[] = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'close',
+      positionals: [],
+      flags: { shutdown: true },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    stopIosRunner: async () => {},
+    shutdownSimulator: async (device) => {
+      shutdownCalls.push(device.id);
+      return { success: true, exitCode: 0, stdout: '', stderr: '' };
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.deepEqual(shutdownCalls, []);
+  assert.equal(sessionStore.get(sessionName), undefined);
+  if (response && response.ok) {
+    assert.equal(response.data?.session, sessionName);
+    assert.equal(response.data?.shutdown, undefined);
+  }
+});
+
+test('close without --shutdown does not call shutdownSimulator', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-no-shutdown-session';
+  sessionStore.set(sessionName, makeSession(sessionName, {
+    platform: 'ios',
+    id: 'sim-udid-2',
+    name: 'iPhone 15',
+    kind: 'simulator',
+    booted: true,
+  }));
+
+  const shutdownCalls: string[] = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'close',
+      positionals: [],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    stopIosRunner: async () => {},
+    shutdownSimulator: async (device) => {
+      shutdownCalls.push(device.id);
+      return { success: true, exitCode: 0, stdout: '', stderr: '' };
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.deepEqual(shutdownCalls, []);
+  if (response && response.ok) {
+    assert.equal(response.data?.shutdown, undefined);
+  }
+});
+
+test('close --shutdown returns success and failure payload when shutdownSimulator throws', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-shutdown-failure-session';
+  sessionStore.set(sessionName, makeSession(sessionName, {
+    platform: 'ios',
+    id: 'sim-udid-3',
+    name: 'iPhone 15',
+    kind: 'simulator',
+    booted: true,
+  }));
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'close',
+      positionals: [],
+      flags: { shutdown: true },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    stopIosRunner: async () => {},
+    shutdownSimulator: async () => {
+      throw new AppError('COMMAND_FAILED', 'simctl shutdown failed');
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.equal(sessionStore.get(sessionName), undefined);
+  if (response && response.ok) {
+    const shutdown = response.data?.shutdown as
+      | {
+        success?: boolean;
+        exitCode?: number;
+        stdout?: string;
+        stderr?: string;
+        error?: {
+          code?: string;
+          message?: string;
+        };
+      }
+      | undefined;
+    assert.equal(response.data?.session, sessionName);
+    assert.equal(shutdown?.success, false);
+    assert.equal(shutdown?.exitCode, -1);
+    assert.equal(shutdown?.stdout, '');
+    assert.equal(shutdown?.stderr, 'simctl shutdown failed');
+    assert.equal(shutdown?.error?.code, 'COMMAND_FAILED');
+    assert.equal(shutdown?.error?.message, 'simctl shutdown failed');
+  }
+});

src/daemon/handlers/session.ts

@@ -17,6 +17,7 @@ import { SessionStore } from '../session-store.ts';
 import { contextFromFlags } from '../context.ts';
 import { ensureDeviceReady } from '../device-ready.ts';
 import { stopIosRunnerSession } from '../../platforms/ios/runner-client.ts';
+import { shutdownSimulator } from '../../platforms/ios/simulator.ts';
 import { attachRefs, type RawSnapshotNode, type SnapshotState } from '../../utils/snapshot.ts';
 import { pruneGroupNodes } from '../snapshot-processing.ts';
 import {
@@ -712,6 +713,7 @@ export async function handleSessionCommands(params: {
     openTarget: string | undefined,
   ) => Promise<string | undefined>;
   settleSimulator?: typeof settleIosSimulator;
+  shutdownSimulator?: typeof shutdownSimulator;
 }): Promise<DaemonResponse | null> {
   const {
     req,
@@ -732,12 +734,14 @@ export async function handleSessionCommands(params: {
     ensureAndroidEmulatorBoot: ensureAndroidEmulatorBootOverride = defaultEnsureAndroidEmulatorBoot,
     resolveAndroidPackageForOpen: resolveAndroidPackageForOpenOverride = resolveAndroidPackageForOpen,
     settleSimulator: settleSimulatorOverride,
+    shutdownSimulator: shutdownSimulatorOverride,
   } = params;
   const dispatch = dispatchOverride ?? dispatchCommand;
   const ensureReady = ensureReadyOverride ?? ensureDeviceReady;
   const resolveDevice = resolveTargetDeviceOverride ?? resolveTargetDevice;
   const stopIosRunner = stopIosRunnerOverride ?? stopIosRunnerSession;
   const settleSimulator = settleSimulatorOverride ?? settleIosSimulator;
+  const doShutdownSimulator = shutdownSimulatorOverride ?? shutdownSimulator;
   const command = req.command;
 
   if (command === 'session_list') {
@@ -1583,6 +1587,31 @@ export async function handleSessionCommands(params: {
     }
     sessionStore.writeSessionLog(session);
     sessionStore.delete(sessionName);
+    if (req.flags?.shutdown && isIosSimulator(session.device)) {
+      let shutdownResult: {
+        success: boolean;
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+        error?: ReturnType<typeof normalizeError>;
+      };
+      try {
+        shutdownResult = await doShutdownSimulator(session.device);
+      } catch (error) {
+        const normalized = normalizeError(error);
+        shutdownResult = {
+          success: false,
+          exitCode: -1,
+          stdout: '',
+          stderr: normalized.message,
+          error: normalized,
+        };
+      }
+      return {
+        ok: true,
+        data: { session: sessionName, shutdown: shutdownResult },
+      };
+    }
     return { ok: true, data: { session: sessionName } };
   }
 

src/platforms/ios/simulator.ts

@@ -142,6 +142,22 @@ export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {
   }
 }
 
+export async function shutdownSimulator(device: DeviceInfo): Promise<{
+  success: boolean;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}> {
+  const args = buildSimctlArgsForDevice(device, ['shutdown', device.id]);
+  const result = await runCmd('xcrun', args, { allowFailure: true, timeoutMs: 15_000 });
+  return {
+    success: result.exitCode === 0,
+    exitCode: result.exitCode,
+    stdout: String(result.stdout ?? ''),
+    stderr: String(result.stderr ?? ''),
+  };
+}
+
 export async function getSimulatorState(deviceOrUdid: DeviceInfo | string): Promise<string | null> {
   const udid = typeof deviceOrUdid === 'string' ? deviceOrUdid : deviceOrUdid.id;
   const simctlArgs = typeof deviceOrUdid === 'string'

src/utils/command-schema.ts

@@ -38,6 +38,7 @@ export type CliFlags = {
   pattern?: 'one-way' | 'ping-pong';
   activity?: string;
   saveScript?: boolean | string;
+  shutdown?: boolean;
   relaunch?: boolean;
   headless?: boolean;
   restart?: boolean;
@@ -347,6 +348,13 @@ const FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     usageLabel: '--save-script [path]',
     usageDescription: 'Save session script (.ad) on close; optional custom output path',
   },
+  {
+    key: 'shutdown',
+    names: ['--shutdown'],
+    type: 'boolean',
+    usageLabel: '--shutdown',
+    usageDescription: 'close: shutdown associated iOS simulator after ending session',
+  },
   {
     key: 'relaunch',
     names: ['--relaunch'],
@@ -504,7 +512,7 @@ const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
   close: {
     description: 'Close app or just end session',
     positionalArgs: ['app?'],
-    allowedFlags: ['saveScript'],
+    allowedFlags: ['saveScript', 'shutdown'],
   },
   reinstall: {
     description: 'Uninstall + install app from binary path',

website/docs/docs/sessions.md

@@ -21,6 +21,12 @@ agent-device snapshot -i
 agent-device close --session my-session
 ```
 
+Shut down the simulator on close (iOS simulator only, prevents resource leakage in CI/multi-tenant workloads):
+
+```bash
+agent-device close --platform ios --shutdown
+```
+
 Notes:
 
 - `open <app>` within an existing session switches the active app and updates the session bundle id.