fix: support foldable simulators lent by an external device provider

packages/docs/docs/reference/device-providers.mdx

@@ -57,6 +57,7 @@ An external device appears in `list-devices` with the other devices. Its id star
 | `external`     | Always `true`. It marks the device as the device of a provider.                |
 | `provider`     | The id and the name of the provider, and the project that the provider opened. |
 | `capabilities` | The mechanisms that the provider granted for this device.                      |
+| `foldable`     | `true` for a foldable iOS simulator, as on a plain entry. Absent otherwise.    |
 
 The agent drives an external device with the usual tools. Two rules are different:
 

packages/tool-server/src/blueprints/ax-service.ts

@@ -14,6 +14,7 @@ import {
 } from "@argent/registry";
 import { assertExternalCapability } from "../utils/external-devices";
 import { pickIosHost, type IosEndpoint } from "../utils/ios-host";
+import { axServiceSocketPath } from "../utils/socket-tag";
 
 // Moved to ../utils/ax-prefs; re-exported so existing import paths keep working.
 export {
@@ -159,10 +160,6 @@ const LIVE_PANEL_TIMEOUT_MS = 2_000;
  */
 const FILL_TIMEOUT_MS = 6_000;
 
-function getSocketPath(udid: string): string {
-  return `/tmp/ax-${udid.slice(0, 8)}.sock`;
-}
-
 interface PendingRpc {
   resolve: (value: unknown) => void;
   reject: (err: Error) => void;
@@ -345,7 +342,7 @@ export const axServiceBlueprint: ServiceBlueprint<AXServiceApi, DeviceInfo> = {
     const endpoint: IosEndpoint =
       transport === "tcp"
         ? { transport: "tcp" }
-        : { transport: "unix", socketPath: getSocketPath(udid) };
+        : { transport: "unix", socketPath: axServiceSocketPath(udid) };
     const events = new TypedEventEmitter<ServiceEvents>();
 
     const pendingRpc = new Map<number, PendingRpc>();

packages/tool-server/src/blueprints/native-devtools.ts

@@ -10,6 +10,7 @@ import {
   type ServiceEvents,
 } from "@argent/registry";
 import { assertExternalCapability, externalClaimForAnyId } from "../utils/external-devices";
+import { nativeDevtoolsSocketPath } from "../utils/socket-tag";
 import {
   pickIosHost,
   buildDyldInsertLibraries,
@@ -501,12 +502,6 @@ interface AppConnection {
   networkLog: NetworkEvent[];
 }
 
-function getNativeDevtoolsSocketPath(udid: string): string {
-  // Deterministic and short: 28 chars, well under the 104-char macOS Unix
-  // socket limit.
-  return `/tmp/argent-nd-${udid.slice(0, 8)}.sock`;
-}
-
 /**
  * Bind the per-UDID unix socket with the same guarded, self-healing treatment
  * the TCP branch gets. Exported for testing.
@@ -639,7 +634,7 @@ export const nativeDevtoolsBlueprint: ServiceBlueprint<NativeDevtoolsApi, Device
       : (opts.transport ?? "unix");
 
     const udid = device.id;
-    const socketPath = getNativeDevtoolsSocketPath(udid);
+    const socketPath = nativeDevtoolsSocketPath(udid);
     // For TCP, `port` starts undefined (ephemeral) and is populated by the
     // listen block below, before ensureEnvReady and dispose read it.
     const endpoint: IosEndpoint =

packages/tool-server/src/tools/devices/list-devices.ts

@@ -7,7 +7,7 @@ import {
   ADB_DEVICES_TIMEOUT_MS,
 } from "../../utils/adb";
 import { listRunningVvdConsolePorts } from "../../utils/vega-process";
-import { listIosSimulators, type IosSimulator } from "../../utils/ios-devices";
+import { isFoldableSimulator, listIosSimulators, type IosSimulator } from "../../utils/ios-devices";
 import { listIosPhysicalDevices } from "../../utils/ios-device/devicectl";
 import { simctlListDevices } from "../../utils/sim-remote";
 import { withRemotePrefix } from "../../utils/device-info";
@@ -72,6 +72,11 @@ type AndroidDevice = {
 type ExternalListedDevice = {
   capabilities: string[];
   external: true;
+  /**
+   * Present and true for a foldable simulator (the iPhone Duo), as on a plain
+   * iOS row.
+   */
+  foldable?: true;
   id: string;
   kind: "device" | "emulator" | "simulator";
   name: string;
@@ -233,10 +238,11 @@ export async function withDeadline<T>(p: Promise<T>, fallback: T, label: string)
   }
 }
 
-function toListedExternal(device: ExternalDevice): ExternalListedDevice {
+function toListedExternal(device: ExternalDevice, foldable: boolean): ExternalListedDevice {
   return {
     capabilities: Array.from(device.capabilities).sort(),
     external: true,
+    ...(foldable ? { foldable: true as const } : {}),
     id: device.id,
     kind: device.kind,
     name: device.name,
@@ -252,6 +258,30 @@ function toListedExternal(device: ExternalDevice): ExternalListedDevice {
   };
 }
 
+type ExternalEntry = { device: ExternalDevice; foldable: boolean };
+
+/**
+ * Pair each external device with whether it is a foldable simulator (the iPhone
+ * Duo), read from the provider's device set. An agent needs the flag to know
+ * `fold` applies, whoever drives the device. This runs inside the external
+ * discovery branch, so it overlaps the other branches instead of adding to
+ * them; the branch's worst case (a provider probe, then one `simctl` listing
+ * and one device-type read) stays under `BRANCH_DEADLINE_MS`.
+ * `isFoldableSimulator` memoizes every verdict the device set answers, so a
+ * simulator the set lists costs one `simctl` call per tool-server run.
+ */
+async function withFoldableFlags(external: readonly ExternalDevice[]): Promise<ExternalEntry[]> {
+  return Promise.all(
+    external.map(async (device) => ({
+      device,
+      foldable:
+        device.platform === "ios" &&
+        device.kind === "simulator" &&
+        (await isFoldableSimulator(device.id).catch(() => false)),
+    }))
+  );
+}
+
 /**
  * Native ids a provider is currently claiming.
  *
@@ -332,16 +362,19 @@ Booted/ready devices are listed first. Platforms whose CLI is unavailable are si
         ),
         /**
          * One directory stat when no provider is registered (the common case)
-         * and a short HTTP probe per provider otherwise.
+         * and a short HTTP probe per provider otherwise, then the foldable
+         * check of each lent simulator.
          */
         withDeadline(
-          listExternalDevices().catch(() => []),
+          listExternalDevices()
+            .catch(() => [])
+            .then(withFoldableFlags),
           [],
           "external"
         ),
       ]);
 
-    const externalShadows = externalShadowIds(external);
+    const externalShadows = externalShadowIds(external.map(({ device }) => device));
 
     const iosTagged: IosDevice[] = ios
       .filter((simulator) => !externalShadows.has(simulator.udid))
@@ -389,7 +422,7 @@ Booted/ready devices are listed first. Platforms whose CLI is unavailable are si
       ...androidDeduped,
       ...chromium,
       ...vega,
-      ...external.map(toListedExternal),
+      ...external.map(({ device, foldable }) => toListedExternal(device, foldable)),
     ];
     devices.sort((a, b) => readinessRank(a) - readinessRank(b));
 

packages/tool-server/src/utils/socket-tag.ts

@@ -0,0 +1,29 @@
+import { createHash } from "node:crypto";
+
+/**
+ * The per-device part of a `/tmp/<prefix>-<tag>.sock` path.
+ *
+ * A plain UDID gives its first 8 characters. Any other id, such as an external
+ * provider's `ext:<provider>:<udid>`, gives 12 hex characters of its SHA-256:
+ * the first 8 characters of such an id are `ext:` plus the first 4 of the
+ * provider id, the same for every device of that provider and of any provider
+ * whose id starts the same way. The hash keeps the path short (macOS
+ * caps `sun_path` at 104 bytes) and can never equal an 8-character UDID tag.
+ */
+export function socketTag(deviceId: string): string {
+  if (/^[A-Za-z0-9-]+$/.test(deviceId)) return deviceId.slice(0, 8);
+  return createHash("sha256").update(deviceId).digest("hex").slice(0, 12);
+}
+
+/** The Unix socket the ax-service daemon of a device listens on. */
+export function axServiceSocketPath(deviceId: string): string {
+  return `/tmp/ax-${socketTag(deviceId)}.sock`;
+}
+
+/**
+ * The Unix socket the native-devtools library of a device connects to. At most
+ * 32 characters, well under the 104-byte macOS limit.
+ */
+export function nativeDevtoolsSocketPath(deviceId: string): string {
+  return `/tmp/argent-nd-${socketTag(deviceId)}.sock`;
+}

packages/tool-server/test/blueprints/ax-service.test.ts

@@ -3,7 +3,7 @@ import type { DeviceInfo } from "@argent/registry";
 import { axServiceBlueprint } from "../../src/blueprints/ax-service";
 
 // Regression: same crash class as simulator-server. A missing udid would
-// throw `getSocketPath(undefined).slice` synchronously and `udid.slice` in
+// reach `axServiceSocketPath(undefined)` and throw `udid.slice` in
 // the stderr listener fatally. The id-shape check sits *after* the apple-
 // only check so an Android caller still gets the clearer iOS-only error.
 describe("ax-service blueprint — input validation", () => {

packages/tool-server/test/helpers/process-scoped-udid.ts

@@ -2,13 +2,13 @@
  * A UDID whose first 8 characters belong to this process alone.
  *
  * The native-devtools factory really binds `/tmp/argent-nd-<first 8 UDID
- * chars>.sock` (getNativeDevtoolsSocketPath), and the bind unlinks and rebinds
+ * chars>.sock` (`nativeDevtoolsSocketPath`), and the bind unlinks and rebinds
  * over whatever already holds that path. A constant UDID therefore makes two
  * concurrent runs — a second checkout, a CI matrix cell — silently destroy each
  * other's live socket, and the loser reads its own device back as unregistered.
  *
  * `tail` supplies the remaining UDID groups, which distinguish two devices to
- * everything EXCEPT the socket: getNativeDevtoolsSocketPath reads only the
+ * everything EXCEPT the socket: `nativeDevtoolsSocketPath` reads only the
  * first 8 characters, so every UDID from this helper maps to one
  * `/tmp/argent-nd-<pid8>.sock`. A file needing two devices that both bind has
  * to vary the leading group itself.

packages/tool-server/test/list-devices.test.ts

@@ -97,13 +97,29 @@ vi.mock("../src/utils/ios-device/devicectl", async () => {
   };
 });
 
+// Whether a provider's simulator is foldable is read from its device set; that
+// read is the seam, off by default. The plain listing is wrapped so a test can
+// hold it open.
+vi.mock("../src/utils/ios-devices", async () => {
+  const actual = await vi.importActual<typeof import("../src/utils/ios-devices")>(
+    "../src/utils/ios-devices"
+  );
+
+  return {
+    ...actual,
+    isFoldableSimulator: vi.fn(async () => false),
+    listIosSimulators: vi.fn(actual.listIosSimulators),
+  };
+});
+
 import * as fs from "node:fs";
 import * as http from "node:http";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AddressInfo } from "node:net";
 import { listDevicesTool } from "../src/tools/devices/list-devices";
 import { listIosPhysicalDevices } from "../src/utils/ios-device/devicectl";
+import { isFoldableSimulator, listIosSimulators } from "../src/utils/ios-devices";
 import {
   __resetExternalDeviceCacheForTesting,
   __resetProviderWarningsForTesting,
@@ -664,6 +680,7 @@ describe("list-devices — external provider shadows", () => {
     process.env.ARGENT_DEVICE_PROVIDERS = descriptorPath;
     __resetExternalDeviceCacheForTesting();
     __resetProviderWarningsForTesting();
+    vi.mocked(isFoldableSimulator).mockClear();
   });
 
   afterEach(async () => {
@@ -703,6 +720,93 @@ describe("list-devices — external provider shadows", () => {
     });
   });
 
+  it("marks a claimed foldable simulator with foldable: true", async () => {
+    /**
+     * The provider's device set is not configured, so the plain listing does
+     * not see the device; the verdict is read from the provider's set.
+     */
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "adb" && args[0] === "devices") {
+        return { stderr: "", stdout: "List of devices attached\n" };
+      }
+
+      return { stderr: "", stdout: "" };
+    });
+
+    vi.mocked(isFoldableSimulator).mockResolvedValueOnce(true);
+
+    const result = await listDevicesTool.execute!({}, {});
+
+    const claimed = result.devices.find(
+      (device) => "udid" in device && device.udid === `ext:acme-3f2a9c:${CLAIMED_UDID}`
+    );
+
+    expect(claimed).toMatchObject({ external: true, foldable: true });
+    expect(isFoldableSimulator).toHaveBeenCalledWith(`ext:acme-3f2a9c:${CLAIMED_UDID}`);
+  });
+
+  it("leaves foldable off a claimed simulator that is not foldable", async () => {
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "xcrun" && args[0] === "simctl") {
+        return { stderr: "", stdout: simctlJson() };
+      }
+
+      if (cmd === "adb" && args[0] === "devices") {
+        return { stderr: "", stdout: "List of devices attached\n" };
+      }
+
+      return { stderr: "", stdout: "" };
+    });
+
+    const result = await listDevicesTool.execute!({}, {});
+
+    const claimed = result.devices.find(
+      (device) => "udid" in device && device.udid === `ext:acme-3f2a9c:${CLAIMED_UDID}`
+    );
+
+    expect(claimed).toBeDefined();
+    expect(claimed).not.toHaveProperty("foldable");
+    expect(isFoldableSimulator).toHaveBeenCalledWith(`ext:acme-3f2a9c:${CLAIMED_UDID}`);
+  });
+
+  it("checks foldables while the plain simulator listing is still running", async () => {
+    /**
+     * A wedged CoreSimulator holds every `simctl` call until its timeout. The
+     * foldable check must overlap the plain listing rather than wait for it or
+     * the two timeouts add up. Here the listing settles only once the check has
+     * run, so a check that waited for it would hang this test.
+     */
+    let releaseListing: (() => void) | undefined;
+
+    vi.mocked(listIosSimulators).mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          releaseListing = () => resolve([]);
+        })
+    );
+
+    vi.mocked(isFoldableSimulator).mockImplementationOnce(async () => {
+      releaseListing?.();
+      return true;
+    });
+
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "adb" && args[0] === "devices") {
+        return { stderr: "", stdout: "List of devices attached\n" };
+      }
+
+      return { stderr: "", stdout: "" };
+    });
+
+    const result = await listDevicesTool.execute!({}, {});
+
+    const claimed = result.devices.find(
+      (device) => "udid" in device && device.udid === `ext:acme-3f2a9c:${CLAIMED_UDID}`
+    );
+
+    expect(claimed).toMatchObject({ external: true, foldable: true });
+  });
+
   it("leaves an unclaimed simulator in the plain listing", async () => {
     execFileMock.mockImplementation((cmd: string, args: string[]) => {
       if (cmd === "xcrun" && args[0] === "simctl") {

packages/tool-server/test/native-devtools-socket-bind.test.ts

@@ -21,7 +21,7 @@ const track = (s: net.Server) => {
 
 // A unix socket path must fit sun_path (108 bytes on Linux, 104 on macOS), which
 // is why production pins the short `/tmp/argent-nd-<udid8>.sock`
-// (getNativeDevtoolsSocketPath). Root the fixtures at the same short base rather
+// (`nativeDevtoolsSocketPath`). Root the fixtures at the same short base rather
 // than os.tmpdir(): that honors an ambient $TMPDIR, and a long one — easily
 // reached by a CI workspace path — pushes these fixtures past the limit and
 // fails the bind with EINVAL, testing the host's TMPDIR instead of the code.
@@ -49,7 +49,7 @@ afterEach(() => {
 });
 
 // Production pins the socket under /tmp unconditionally
-// (getNativeDevtoolsSocketPath), so this path is POSIX-only by construction
+// (`nativeDevtoolsSocketPath`), so this path is POSIX-only by construction
 // and SOCK_ROOT above follows it. On win32 there is no /tmp to mkdtemp into.
 describe.skipIf(process.platform === "win32")("bindNativeDevtoolsUnixSocket", () => {
   it("binds cleanly on a free path", async () => {