feat: include device_udid and ios_simulator_device_set in iOS JSON payloads (#180)

Add device identity fields to open, appstate, and session_list responses
for iOS targets, enabling isolation verification in concurrent multi-session
runs without extra simctl calls.

Closes #173

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

Author: thymikee

skills/agent-device/SKILL.md

@@ -176,7 +176,8 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - Android `.aab` requires `bundletool` in `PATH`, or `AGENT_DEVICE_BUNDLETOOL_JAR=<path-to-bundletool-all.jar>` with `java` in `PATH`.
 - Android `.aab` optional: set `AGENT_DEVICE_ANDROID_BUNDLETOOL_MODE=<mode>` to control bundletool `build-apks --mode` (default: `universal`).
 - iOS `.ipa`: extract/install from `Payload/*.app`; when multiple app bundles are present, `<app>` is used as a bundle id/name hint.
-- iOS `appstate` is session-scoped; Android `appstate` is live foreground state.
+- iOS `appstate` is session-scoped; Android `appstate` is live foreground state. iOS responses include `device_udid` and `ios_simulator_device_set` for isolation verification.
+- iOS `open` responses include `device_udid` and `ios_simulator_device_set` to confirm which simulator handled the session.
 - Clipboard helpers: `clipboard read` / `clipboard write <text>` are supported on Android and iOS simulators; iOS physical devices are not supported yet.
 - Android keyboard helpers: `keyboard status|get|dismiss` report keyboard visibility/type and dismiss via keyevent when visible.
 - `network dump` is best-effort and parses HTTP(s) entries from the session app log file.

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

@@ -47,6 +47,8 @@ agent-device devices --platform android --android-device-allowlist emulator-5554
 agent-device session list
 ```
 
+iOS session entries include `device_udid` and `ios_simulator_device_set` (null when using the default set). Use these fields to confirm device routing in concurrent multi-session runs without additional `simctl` calls.
+
 ## Replay within sessions
 
 ```bash

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

@@ -668,6 +668,8 @@ test('appstate with explicit selector matching session returns session state', a
     assert.equal(response.data?.appName, 'Maps');
     assert.equal(response.data?.appBundleId, 'com.apple.Maps');
     assert.equal(response.data?.source, 'session');
+    assert.equal(response.data?.device_udid, 'sim-1');
+    assert.equal(response.data?.ios_simulator_device_set, null);
   }
 });
 
@@ -716,6 +718,8 @@ test('appstate returns session appName when bundle id is unavailable', async ()
     assert.equal(response.data?.appName, 'Maps');
     assert.equal(response.data?.appBundleId, undefined);
     assert.equal(response.data?.source, 'session');
+    assert.equal(response.data?.device_udid, 'sim-1');
+    assert.equal(response.data?.ios_simulator_device_set, null);
   }
 });
 
@@ -1411,6 +1415,10 @@ test('open app on existing iOS session resolves and stores bundle id', async ()
   assert.equal(updated?.appBundleId, 'com.apple.Preferences');
   assert.equal(updated?.appName, 'settings');
   assert.equal(dispatchedContext?.appBundleId, 'com.apple.Preferences');
+  if (response && response.ok) {
+    assert.equal(response.data?.device_udid, 'sim-1');
+    assert.equal(response.data?.ios_simulator_device_set, null);
+  }
 });
 
 test('open app on existing Android session resolves and stores package id', async () => {
@@ -2770,3 +2778,62 @@ test('network dump validates include mode and limit', async () => {
     assert.match(invalidMode.error.message, /summary, headers, body, all/);
   }
 });
+
+test('session_list includes device_udid and ios_simulator_device_set for iOS sessions', async () => {
+  const sessionStore = makeSessionStore();
+  sessionStore.set(
+    'ios-default',
+    makeSession('ios-default', {
+      platform: 'ios',
+      id: 'ABC-123',
+      name: 'iPhone 16',
+      kind: 'simulator',
+      booted: true,
+    }),
+  );
+  sessionStore.set(
+    'ios-scoped',
+    makeSession('ios-scoped', {
+      platform: 'ios',
+      id: 'DEF-456',
+      name: 'iPhone 16',
+      kind: 'simulator',
+      booted: true,
+      simulatorSetPath: '/tmp/tenant-a/simulators',
+    }),
+  );
+  sessionStore.set(
+    'android-1',
+    makeSession('android-1', {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Pixel Emulator',
+      kind: 'emulator',
+      booted: true,
+    }),
+  );
+
+  const response = await handleSessionCommands({
+    req: { token: 't', session: 'default', command: 'session_list', positionals: [] },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  if (response && response.ok) {
+    const sessions = response.data?.sessions as Array<Record<string, unknown>>;
+    assert.ok(Array.isArray(sessions));
+    const iosDefault = sessions.find((s) => s.name === 'ios-default');
+    assert.equal(iosDefault?.device_udid, 'ABC-123');
+    assert.equal(iosDefault?.ios_simulator_device_set, null);
+    const iosScoped = sessions.find((s) => s.name === 'ios-scoped');
+    assert.equal(iosScoped?.device_udid, 'DEF-456');
+    assert.equal(iosScoped?.ios_simulator_device_set, '/tmp/tenant-a/simulators');
+    const android = sessions.find((s) => s.name === 'android-1');
+    assert.equal(android?.device_udid, undefined);
+    assert.equal(android?.ios_simulator_device_set, undefined);
+  }
+});

src/daemon/handlers/session.ts

@@ -99,12 +99,17 @@ function buildOpenResult(params: {
   appName?: string;
   appBundleId?: string;
   startup?: StartupPerfSample;
+  device?: DeviceInfo;
 }): Record<string, unknown> {
-  const { sessionName, appName, appBundleId, startup } = params;
+  const { sessionName, appName, appBundleId, startup, device } = params;
   const result: Record<string, unknown> = { session: sessionName };
   if (appName) result.appName = appName;
   if (appBundleId) result.appBundleId = appBundleId;
   if (startup) result.startup = startup;
+  if (device?.platform === 'ios') {
+    result.device_udid = device.id;
+    result.ios_simulator_device_set = device.simulatorSetPath ?? null;
+  }
   return result;
 }
 
@@ -593,6 +598,8 @@ async function handleAppStateCommand(params: {
         appName: appName ?? 'unknown',
         appBundleId: session.appBundleId,
         source: 'session',
+        device_udid: session.device.id,
+        ios_simulator_device_set: session.device.simulatorSetPath ?? null,
       },
     };
   }
@@ -741,6 +748,10 @@ export async function handleSessionCommands(params: {
         device: s.device.name,
         id: s.device.id,
         createdAt: s.createdAt,
+        ...(s.device.platform === 'ios' && {
+          device_udid: s.device.id,
+          ios_simulator_device_set: s.device.simulatorSetPath ?? null,
+        }),
       })),
     };
     return { ok: true, data };
@@ -1127,6 +1138,7 @@ export async function handleSessionCommands(params: {
         appName: openTarget,
         appBundleId,
         startup: startupSample,
+        device: session.device,
       });
       sessionStore.recordAction(nextSession, {
         command,
@@ -1205,6 +1217,7 @@ export async function handleSessionCommands(params: {
       appName: openTarget,
       appBundleId,
       startup: startupSample,
+      device,
     });
     sessionStore.recordAction(session, {
       command,