@swmansion/argent 0.23.1-next.0 → 0.23.1-next.2

package/README.md

@@ -23,7 +23,7 @@ Argent drives a growing set of targets through a single toolkit, each with the r
 
 | Platform          | Targets                                                                 | Interaction      |
 | ----------------- | ----------------------------------------------------------------------- | ---------------- |
-| **iOS**           | Simulators and physical iPhones (USB)                                   | Touch / gesture  |
+| **iOS**           | Simulators and physical iPhones                                         | Touch / gesture  |
 | **Android**       | Emulators (AVDs) and physical devices over adb                          | Touch / gesture  |
 | **TV**            | Apple TV (tvOS), Android TV / Google TV, Amazon Fire TV (Vega)          | D-pad / remote   |
 | **Desktop & web** | Electron and Chromium apps (incl. React Native Web / Expo web) over CDP | Mouse / keyboard |

package/dist/cli-cmds.mjs

@@ -1805,14 +1805,10 @@ async function sweepDeadStateFiles() {
       continue;
     }
     if (fs.existsSync(fresh.bundlePath)) continue;
-    const guarded = process.platform !== "win32";
-    if (guarded && !processCommandMatches(fresh.pid, fresh.bundlePath)) continue;
+    if (!couldBeOurToolServer(fresh.pid, fresh.bundlePath)) continue;
     await unlink(file).catch(() => {
     });
-    void terminatePid(
-      fresh.pid,
-      guarded ? () => processCommandMatches(fresh.pid, fresh.bundlePath) : void 0
-    );
+    void terminatePid(fresh.pid, () => couldBeOurToolServer(fresh.pid, fresh.bundlePath));
   }
 }
 var readState = readToolsServerState;
@@ -1851,20 +1847,37 @@ async function killToolServer(bundlePath) {
   await terminatePid(state2.pid);
   await clearToolsServerState(bundlePath ?? state2.bundlePath);
 }
-function processCommandMatches(pid, marker) {
+var PS_BIN = ["/bin/ps", "/usr/bin/ps"].find((p) => fs.existsSync(p)) ?? "ps";
+var PS_WIDTH_FLAGS = ["-ww"];
+function readProcessCommandLine(pid, flags2 = PS_WIDTH_FLAGS) {
+  return execFileSync(PS_BIN, [...flags2, "-p", String(pid), "-o", "command="], {
+    encoding: "utf8",
+    timeout: 2e3,
+    // A recycled pid can sit on a process with an argv past Node's 1 MiB exec
+    // default, where the overrun surfaces as ENOBUFS instead of a command line.
+    // Same ceiling as tool-server's vega-process ps probes.
+    maxBuffer: 16 * 1024 * 1024,
+    // Piping ps's stderr is what puts a rejected flag ("ps: invalid option --
+    // 'w'") into the thrown error's message.
+    stdio: ["ignore", "pipe", "pipe"]
+  }).trim();
+}
+function couldBeOurToolServer(pid, marker) {
   if (!marker) return false;
+  if (process.platform === "win32") return true;
+  let cmd;
   try {
-    const cmd = execFileSync("ps", ["-p", String(pid), "-o", "command="], {
-      encoding: "utf8",
-      timeout: 2e3,
-      stdio: ["ignore", "pipe", "ignore"]
-    }).trim();
-    if (!cmd) return false;
-    const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    return new RegExp(`(?:^|\\s)${escaped} start(?:\\s|$)`).test(cmd);
-  } catch {
+    cmd = readProcessCommandLine(pid);
+  } catch (err) {
+    process.stderr.write(
+      `[launcher] ps could not read pid ${pid}'s command line; leaving it alone: ${String(err)}
+`
+    );
     return false;
   }
+  if (!cmd) return false;
+  const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?:^|\\s)${escaped} start(?:\\s|$)`).test(cmd);
 }
 var LOCK_WAIT_TIMEOUT_MS = 3e4;
 var LOCK_STALE_MS = 45e3;
@@ -1953,8 +1966,8 @@ async function ensureToolsServer(paths) {
     const state2 = await readState(paths.bundlePath);
     const reuse = await reusableHandle(state2, paths.bundlePath, paths.version);
     if (reuse) return reuse;
-    if (state2 && state2.managed === "autospawn" && state2.bundlePath === paths.bundlePath && isProcessAlive(state2.pid) && processCommandMatches(state2.pid, state2.bundlePath)) {
-      await terminatePid(state2.pid, () => processCommandMatches(state2.pid, state2.bundlePath));
+    if (state2 && state2.managed === "autospawn" && state2.bundlePath === paths.bundlePath && isProcessAlive(state2.pid) && couldBeOurToolServer(state2.pid, state2.bundlePath)) {
+      await terminatePid(state2.pid, () => couldBeOurToolServer(state2.pid, state2.bundlePath));
     }
     await clearToolsServerState(paths.bundlePath);
     await sweepDeadStateFiles();
@@ -7240,7 +7253,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.23.1-next.0";
+    return "0.23.1-next.2";
   }
   return "0.0.0";
 }

package/dist/installer.mjs

@@ -16625,7 +16625,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID4();
 function readCliVersion() {
   if (true) {
-    return "0.23.1-next.0";
+    return "0.23.1-next.2";
   }
   return "0.0.0";
 }
@@ -23046,15 +23046,11 @@ async function killToolServerForInstallDir(packageDir) {
     const fresh = await readStateFile(file);
     if (!fresh || fresh.pid !== state2.pid || fresh.bundlePath !== state2.bundlePath) continue;
     const alive = isProcessAlive(fresh.pid);
-    const guarded = process.platform !== "win32";
-    if (alive && guarded && !processCommandMatches(fresh.pid, fresh.bundlePath)) {
+    if (alive && !couldBeOurToolServer(fresh.pid, fresh.bundlePath)) {
       continue;
     }
     if (alive) {
-      await terminatePid(
-        fresh.pid,
-        guarded ? () => processCommandMatches(fresh.pid, fresh.bundlePath) : void 0
-      );
+      await terminatePid(fresh.pid, () => couldBeOurToolServer(fresh.pid, fresh.bundlePath));
     }
     await unlink(file).catch(() => {
     });
@@ -23062,20 +23058,37 @@ async function killToolServerForInstallDir(packageDir) {
   }
   return killed;
 }
-function processCommandMatches(pid, marker) {
+var PS_BIN = ["/bin/ps", "/usr/bin/ps"].find((p) => fs16.existsSync(p)) ?? "ps";
+var PS_WIDTH_FLAGS = ["-ww"];
+function readProcessCommandLine(pid, flags = PS_WIDTH_FLAGS) {
+  return execFileSync5(PS_BIN, [...flags, "-p", String(pid), "-o", "command="], {
+    encoding: "utf8",
+    timeout: 2e3,
+    // A recycled pid can sit on a process with an argv past Node's 1 MiB exec
+    // default, where the overrun surfaces as ENOBUFS instead of a command line.
+    // Same ceiling as tool-server's vega-process ps probes.
+    maxBuffer: 16 * 1024 * 1024,
+    // Piping ps's stderr is what puts a rejected flag ("ps: invalid option --
+    // 'w'") into the thrown error's message.
+    stdio: ["ignore", "pipe", "pipe"]
+  }).trim();
+}
+function couldBeOurToolServer(pid, marker) {
   if (!marker) return false;
+  if (process.platform === "win32") return true;
+  let cmd;
   try {
-    const cmd = execFileSync5("ps", ["-p", String(pid), "-o", "command="], {
-      encoding: "utf8",
-      timeout: 2e3,
-      stdio: ["ignore", "pipe", "ignore"]
-    }).trim();
-    if (!cmd) return false;
-    const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    return new RegExp(`(?:^|\\s)${escaped} start(?:\\s|$)`).test(cmd);
-  } catch {
+    cmd = readProcessCommandLine(pid);
+  } catch (err) {
+    process.stderr.write(
+      `[launcher] ps could not read pid ${pid}'s command line; leaving it alone: ${String(err)}
+`
+    );
     return false;
   }
+  if (!cmd) return false;
+  const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?:^|\\s)${escaped} start(?:\\s|$)`).test(cmd);
 }
 
 // ../argent-tools-client/src/link-config.ts

package/dist/mcp-server.mjs

@@ -16057,14 +16057,10 @@ async function sweepDeadStateFiles() {
       continue;
     }
     if (fs.existsSync(fresh.bundlePath)) continue;
-    const guarded = process.platform !== "win32";
-    if (guarded && !processCommandMatches(fresh.pid, fresh.bundlePath)) continue;
+    if (!couldBeOurToolServer(fresh.pid, fresh.bundlePath)) continue;
     await unlink(file).catch(() => {
     });
-    void terminatePid(
-      fresh.pid,
-      guarded ? () => processCommandMatches(fresh.pid, fresh.bundlePath) : void 0
-    );
+    void terminatePid(fresh.pid, () => couldBeOurToolServer(fresh.pid, fresh.bundlePath));
   }
 }
 var readState = readToolsServerState;
@@ -16097,20 +16093,37 @@ async function terminatePid(pid, stillOurs) {
   }
   await waitForExit(pid, SIGKILL_GRACE_MS);
 }
-function processCommandMatches(pid, marker) {
+var PS_BIN = ["/bin/ps", "/usr/bin/ps"].find((p) => fs.existsSync(p)) ?? "ps";
+var PS_WIDTH_FLAGS = ["-ww"];
+function readProcessCommandLine(pid, flags = PS_WIDTH_FLAGS) {
+  return execFileSync(PS_BIN, [...flags, "-p", String(pid), "-o", "command="], {
+    encoding: "utf8",
+    timeout: 2e3,
+    // A recycled pid can sit on a process with an argv past Node's 1 MiB exec
+    // default, where the overrun surfaces as ENOBUFS instead of a command line.
+    // Same ceiling as tool-server's vega-process ps probes.
+    maxBuffer: 16 * 1024 * 1024,
+    // Piping ps's stderr is what puts a rejected flag ("ps: invalid option --
+    // 'w'") into the thrown error's message.
+    stdio: ["ignore", "pipe", "pipe"]
+  }).trim();
+}
+function couldBeOurToolServer(pid, marker) {
   if (!marker) return false;
+  if (process.platform === "win32") return true;
+  let cmd;
   try {
-    const cmd = execFileSync("ps", ["-p", String(pid), "-o", "command="], {
-      encoding: "utf8",
-      timeout: 2e3,
-      stdio: ["ignore", "pipe", "ignore"]
-    }).trim();
-    if (!cmd) return false;
-    const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    return new RegExp(`(?:^|\\s)${escaped} start(?:\\s|$)`).test(cmd);
-  } catch {
+    cmd = readProcessCommandLine(pid);
+  } catch (err) {
+    process.stderr.write(
+      `[launcher] ps could not read pid ${pid}'s command line; leaving it alone: ${String(err)}
+`
+    );
     return false;
   }
+  if (!cmd) return false;
+  const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?:^|\\s)${escaped} start(?:\\s|$)`).test(cmd);
 }
 var LOCK_WAIT_TIMEOUT_MS = 3e4;
 var LOCK_STALE_MS = 45e3;
@@ -16199,8 +16212,8 @@ async function ensureToolsServer(paths) {
     const state = await readState(paths.bundlePath);
     const reuse = await reusableHandle(state, paths.bundlePath, paths.version);
     if (reuse) return reuse;
-    if (state && state.managed === "autospawn" && state.bundlePath === paths.bundlePath && isProcessAlive(state.pid) && processCommandMatches(state.pid, state.bundlePath)) {
-      await terminatePid(state.pid, () => processCommandMatches(state.pid, state.bundlePath));
+    if (state && state.managed === "autospawn" && state.bundlePath === paths.bundlePath && isProcessAlive(state.pid) && couldBeOurToolServer(state.pid, state.bundlePath)) {
+      await terminatePid(state.pid, () => couldBeOurToolServer(state.pid, state.bundlePath));
     }
     await clearToolsServerState(paths.bundlePath);
     await sweepDeadStateFiles();

package/dist/tool-server.cjs

@@ -93916,7 +93916,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.23.1-next.0";
+    return "0.23.1-next.2";
   }
   return "0.0.0";
 }
@@ -95451,6 +95451,11 @@ function subjectValue(subject, key2) {
   }
   return null;
 }
+function signingLabel(commonName) {
+  const match = /^([^:]+):.*\(([A-Za-z0-9]+)\)\s*$/.exec(commonName);
+  if (match) return `${match[1].trim()} (${match[2]})`;
+  return commonName.split(":")[0].trim();
+}
 function parseSigningTeams(pem) {
   const newestByTeam = /* @__PURE__ */ new Map();
   for (const block of pem.match(PEM_BLOCK_RE) ?? []) {
@@ -95461,11 +95466,12 @@ function parseSigningTeams(pem) {
       continue;
     }
     const teamId = subjectValue(cert.subject, "OU");
-    const label = subjectValue(cert.subject, "CN");
+    const commonName = subjectValue(cert.subject, "CN");
     const issuedAtMs = Date.parse(cert.validFrom);
-    if (!teamId || !label || Number.isNaN(issuedAtMs)) {
+    if (!teamId || !commonName || Number.isNaN(issuedAtMs)) {
       continue;
     }
+    const label = signingLabel(commonName);
     const known = newestByTeam.get(teamId);
     if (!known || issuedAtMs > known.issuedAtMs) {
       newestByTeam.set(teamId, { teamId, label, issuedAtMs });
@@ -113260,7 +113266,9 @@ function extractDeviceArg(data) {
   return null;
 }
 function targetsIosPhysicalDevice(data) {
-  const deviceArg = extractDeviceArg(data);
+  const record2 = data && typeof data === "object" ? data : null;
+  const flowDevice = typeof record2?.device === "string" ? record2.device : null;
+  const deviceArg = extractDeviceArg(data) ?? flowDevice;
   return deviceArg !== null && isIosPhysicalDevice(resolveDevice(deviceArg));
 }
 function inferPlatform(deviceId) {
@@ -122048,7 +122056,7 @@ var gestureSwipeTool = {
 Generates interpolated Move events for a natural feel (~60fps).
 Swipe up (fromY > toY) to scroll content down.
 Use when you need to scroll a list, dismiss a modal, drag an element, or navigate between pages. Not supported on Chromium \u2014 use gesture-scroll there instead.
-Physical iOS: an edge gesture (back-swipe) needs fromX 0 exactly.
+Physical iOS: an edge gesture (back-swipe) needs fromX 0 exactly; durationMs sets drag speed, not time; momentum:false only rests 300ms at the end and does not damp.
 Pass momentum:false for a momentum-free swipe that lands where the finger lifts (little to no fling at the 300 default), when you need a deterministic scroll distance; it needs durationMs >= 150 and is rejected below that, a shorter ease-out leaving the OS too little wall clock to read the deceleration as a stop. At 150 it lands short of the lift point instead, and 2 of 47 runs still flung backwards. A plain swipe takes any duration up to 10000ms and is delivered as close to the speed it was authored as a 16ms frame allows: below ~32ms the whole travel lands in one or two frames, which the OS flings as hard as it flings anything. Returns { swiped: true, timestampMs }. On physical iOS, reactivated: true = app was re-fronted; re-describe. Fails if the simulator-server / emulator backend is not reachable for the given device.`,
   alwaysLoad: true,
   searchHint: "swipe scroll drag pan gesture device simulator emulator touch move",
@@ -133313,7 +133321,7 @@ The tree carries no z-order or occlusion information: an element listed at a poi
 by an overlay (e.g. a toolbar over list rows), so check a screenshot when a tap lands unexpectedly.
 
 For app-scoped inspection with full UIKit properties (accessibilityIdentifier, viewClassName),
-use native-describe-screen with an explicit bundleId instead (iOS only).
+use native-describe-screen with an explicit bundleId instead (iOS simulator only).
 For React Native apps, debugger-component-tree returns React component names with tap coordinates.
 
 On a TV target (Apple TV / Android TV \u2014 a \`list-devices\` entry with runtimeKind 'tv') this returns
@@ -145637,7 +145645,7 @@ function connectedIosDeviceHint(devices, platform) {
   if (platform && platform !== "ios") return "";
   const ids = devices.filter((d) => d.platform === "ios" && d.kind === "device" && d.state === "connected").map((d) => d.udid).filter((id) => Boolean(id));
   if (ids.length === 0) return "";
-  return ` A physical iPhone is connected (${ids.join(", ")}); hardware is never picked automatically, pass --device <udid> to run on it.`;
+  return ` A physical iPhone is connected (${ids.join(", ")}); hardware is never picked automatically, pass device <udid> (--device on the CLI) to run on it.`;
 }
 function describeDevice(d) {
   return `${deviceEntryId(d) ?? "?"} (${d.platform}${d.state ? `, ${d.state}` : ""})`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.23.1-next.0",
+  "version": "0.23.1-next.2",
   "mcpName": "io.github.software-mansion/argent",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",

package/rules/argent.md

@@ -83,7 +83,7 @@ Decision order:
   argent install, so an unscoped call tears down their devices too; reserve that form for a deliberate
   machine-wide cleanup.
   If the user started Metro separately, ask whether to call `stop-metro` (specify the port if not 8081).
-- If tools provided by mcp-server are not sufficient and action can be done using `xcrun`, `adb`, or other commands, use the command. Examples: changing device options, performing a device action such as lock, shake, etc.
+- If tools provided by mcp-server are not sufficient and action can be done using `xcrun`, `adb`, or other commands, use the command. Examples: changing device options, performing a device action such as lock, shake, etc. Not on a physical iPhone.
 - When waiting for an action, do not call `screenshot` repeatedly without a proper wait mechanism. Use the `await-ui-element` tool to block until the UI settles (e.g. wait for an element to become `visible`/`hidden`, or to contain expected `text`) instead of polling.
   </general_rules>
 
@@ -114,7 +114,7 @@ When: Beginning a task that involves the Android emulator, no emulator running y
 
 PHYSICAL iPHONE (USB)
 Skills: `argent-ios-device-setup` (cable, trust, signing), then `argent-ios-device-interact` (the app-scoped interaction contract)
-When: The user names a physical iPhone, a real device, or hardware, or the target `list-devices` iOS entry has kind `"device"`. Never for a simulator, and never because a cabled phone is listed first. On hardware every interaction starts with `launch-app`; `paste`, `settings-permissions`, two-finger gestures, `rotate` and `shake` do not exist there.
+When: The user names a physical iPhone, a real device, or hardware, or the target `list-devices` iOS entry has kind `"device"`. Never for a simulator, and never because a cabled phone is listed first. On hardware every interaction starts with `launch-app`; `paste`, `settings-permissions`, two-finger gestures, `rotate`, `shake`, screen recording, `debugger-*`, `react-profiler-*`, `native-profiler-*` and `native-*` do not exist there.
 Prompt keywords: physical iPhone, real device, on my phone, USB, hardware
 
 TAPPING, SWIPING, TYPING, GESTURES, SCREENSHOTS, SCROLLING

package/skills/argent-create-flow/SKILL.md

@@ -13,7 +13,7 @@ For a saved QA test case, ticket, or acceptance criterion, load `argent-qa-flows
 
 - Before creating or changing a flow, read [Live authoring](references/live-authoring.md) completely.
 - When polishing, composing, or manually reviewing YAML, read [Flow YAML](references/flow-yaml.md). For Vega, read its platform limits before recording remote or keyboard tools.
-- Flows run on physical iPhones (an iOS `list-devices` entry with kind `"device"`), but replay never auto-binds one, even when no simulator is booted: pass the phone's udid as `device` (CLI `--device`), and only a `connected` phone can run. `pinch`/`rotate` steps fail there like the live tools. See `argent-ios-device-interact` for the hardware contract.
+- Flows run on physical iPhones (an iOS `list-devices` entry with kind `"device"`), but replay never auto-binds one, even when no simulator is booted: pass the phone's udid as `device` (CLI `--device`), and only a `connected` phone can run. `pinch`/`rotate` steps fail there like the live tools. On hardware the flow tree is the `describe` tree: same ids and roles, no UIView hierarchy. See `argent-ios-device-interact` for the hardware contract.
 - On capture warnings, raw coordinates, unavailable trees, mistimed transitions, overlays, or replay failures, read [Reliability and recovery](references/reliability-and-recovery.md).
 
 ## Non-negotiable rules

package/skills/argent-ios-device-interact/SKILL.md

@@ -9,10 +9,12 @@ Read this only for a physical iPhone. `argent-device-interact` still applies for
 
 ## Contract
 
-- Observation never changes the screen; mutation may. `describe` and `await-ui-element` fail on a backgrounded target instead of re-fronting it. Gestures and `keyboard` re-front it and return `reactivated: true`; re-describe before the next step.
-- Each tool's description states its own hardware limits (named keys, `gesture-custom` shapes, buttons, edge swipes, tap counts), and every failure names its fix.
+- Observation never changes the screen; mutation may. `describe` and `await-ui-element` fail on a backgrounded target instead of re-fronting it; `await-screen-idle` returns `settled: false` with no reason. The first `describe` within a second of `button home` can still return the old tree; describe again. Gestures and `keyboard` re-front it and return `reactivated: true`; re-describe before the next step.
+- `launch-app`, `open-url` and `restart-app` set the app under automation; `reinstall-app` clears it; a tool-server restart forgets it: launch again.
+- Each tool's description states its own hardware limits (named keys, `gesture-custom` shapes, buttons, edge swipes, tap counts). A gated tool fails with a bare `not supported on ios device`: the fix is in the list below, not in the error.
 
 ## Tools on hardware
 
-- Only these exist: `list-devices`, `launch-app`, `restart-app`, `reinstall-app`, `open-url`, `describe`, `screenshot`, `screenshot-diff`, `gesture-tap`, `gesture-swipe`, `gesture-custom`, `button`, `keyboard`, `await-ui-element`, `await-screen-idle`, `run-sequence`, the flow tools, and `stop-simulator-server`. Everything else fails with `not supported on ios device`.
-- No two-finger gestures, `rotate`, `shake`, `paste`, or `settings-permissions`: drive the app's own zoom and rotate UI with taps and drags, move the phone by hand, type with `keyboard`, and change permissions in the phone's Settings.
+- Only these exist: `list-devices`, `launch-app`, `restart-app`, `reinstall-app`, `open-url`, `describe`, `screenshot`, `screenshot-diff`, `gesture-tap`, `gesture-swipe`, `gesture-custom`, `button` (`home`, `volumeUp`, `volumeDown`, `actionButton` on models that have one), `keyboard`, `await-ui-element`, `await-screen-idle`, `run-sequence`, the flow tools, `stop-simulator-server` and `stop-all-simulator-servers` (session end). Every other device tool fails with `not supported on ios device`.
+- No two-finger gestures, `rotate`, `shake`, `paste`, `settings-permissions`, screen recording, `debugger-*`, `react-profiler-*`, `native-profiler-*`, `native-*`, `boot-device`: drive the app's own zoom and rotate UI with taps and drags, move the phone by hand, type with `keyboard`, change permissions in the phone's Settings, and debug, profile or record on a simulator.
+- `gesture-swipe`: `durationMs` sets drag speed, not time; `momentum:false` only rests 300 ms at the end, no damping. `open-url` https lands in Safari, never in the app that owns the link: pass `bundleId`.

package/skills/argent-ios-device-setup/SKILL.md

@@ -10,11 +10,11 @@ Read this only for a physical iPhone. Simulators use `argent-ios-simulator-setup
 ## First run
 
 1. Cable the phone, unlock it, keep the screen awake, and turn on Developer Mode (Settings > Privacy & Security > Developer Mode). `list-devices` must show it `connected`.
-2. Run the first interaction tool. It builds and signs the on-device runner: seconds from cache, minutes on a cold build.
+2. `launch-app` only registers the app. The first `describe`, gesture or `screenshot` builds, signs and starts the on-device runner: minutes cold, tens of seconds from cache or after a tool-server restart. Build cap 15 min, runner ready 120 s.
 3. On the first install the phone asks to trust the developer (Settings > General > VPN & Device Management), and an **ArgentRunner** app appears on the home screen. Tell the user it is argent's automation runner and must stay installed.
 
 ## Signing and failures
 
-Signing needs no configuration. The result note or the error text names the team picked, the `ARGENT_IOS_TEAM_ID` override, and the fix for every signing, cable, lock, or trust failure: apply it and retry the same call.
+Signing needs no configuration. The first phone call of a tool-server process carries a note naming the team picked and the `ARGENT_IOS_TEAM_ID` override (tool-server environment; a change forces a cold rebuild). Cable, lock, trust, expired-profile and missing-certificate errors name their fix: apply it, retry the same call. Also: `errSecInternalComponent`: run `security set-key-partition-list -S apple-tool:,apple:,codesign: -s ~/Library/Keychains/login.keychain-db` (asks the user's login password), retry. `team has no devices`: keep the phone cabled, retry. Bundle id registration failed: free-team app-id cap, wait days or sign under a paid team. Any other xcodebuild failure prints raw `error:` lines: read `~/.argent/ios-device-runner/logs/runner-<udid8>.log`. `RUNNER_WEDGED`: `stop-simulator-server` for the udid, retry.
 
 Then read `argent-ios-device-interact`.

package/skills/argent-ios-simulator-setup/SKILL.md

@@ -8,7 +8,7 @@ description: Set up and connect to an iOS simulator using argent MCP tools. Use
 If you delegate simulator tasks to sub-agents, make sure they have MCP permissions.
 
 1. **Find a booted simulator**
-   Use `list-devices`. Filter for entries with `platform: "ios"` — booted iPhones are listed first.
+   Use `list-devices`. Filter for entries with `platform: "ios"` and skip any with `kind: "device"` (a physical iPhone, never a simulator target): booted simulators are listed first.
    If none are booted, call `boot-device` with `udid: <chosen UDID>`.
 
 2. **Verify connection**

package/skills/argent-metro-debugger/SKILL.md

@@ -5,6 +5,8 @@ description: Debug a JS runtime via CDP using argent debugger tools. Primary pat
 
 ## 1. Prerequisites
 
+Physical iPhone: not supported; every `debugger-*` tool rejects `kind: "device"`. Use a simulator.
+
 For **React Native (iOS / Android)**: requires **Metro dev server running** (default `localhost:8081`) and **a React Native app connected to Metro** (at least one CDP target). Verify via `debugger-status` — it returns `status: "connected"` or `status: "not_connected"` with a `reason` and `guidance` (it does not fail when the debugger is unreachable).
 
 For **Vega (Fire TV)**: requires a **Debug `.vpkg`** (a Release build never attaches) and **Metro reachable from the device** (`vega device start-port-forwarding --port 8081 --forward false`). Verify via `debugger-status`. `debugger-component-tree`, `debugger-inspect-element`, `debugger-reload-metro` and the `react-profiler-*` / `profiler-*` tools are unavailable there — see the `argent-tv-interact` skill.

package/skills/argent-native-profiler/SKILL.md

@@ -10,6 +10,7 @@ description: Native profiling for CPU hotspots, UI hangs, memory issues. iOS via
 - `native-profiler-analyze` — parse exported trace data and return a structured bottleneck payload.
 - `profiler-stack-query` — drill into parsed data: hang stacks, function callers, thread breakdown, leak details.
 - `profiler-load` — list and reload previous trace sessions from disk for re-investigation.
+- Physical iPhone: not supported; use a simulator.
 
 ---
 

package/skills/argent-qa-flows/SKILL.md

@@ -11,7 +11,7 @@ Load `argent-create-flow` as the authoring engine. Follow its required reference
 
 **Apple TV and Android TV are out of scope.** The runner does not reject touch directives there, so they fail at the gesture layer instead of with authoring guidance. Use `argent-tv-interact` and report the limitation.
 
-**Physical iPhones** run QA flows, with two hardware limits: replay never auto-binds a phone, so pass its udid as `device` (CLI `--device`) and keep it `connected`, and `pinch`/`rotate` steps fail there like the live tools, so drive the app's own zoom UI instead. Read `argent-ios-device-interact` for the app-scoped contract before recording.
+**Physical iPhones** run QA flows, with three hardware limits: replay never auto-binds a phone, so pass its udid as `device` (CLI `--device`) and keep it `connected`; `pinch`/`rotate` steps fail there like the live tools, so drive the app's own zoom UI instead; the flow tree is the `describe` tree (same ids and roles), so a selector authored on a simulator can miss there. Read `argent-ios-device-interact` for the app-scoped contract before recording.
 
 ## Definition of done
 

package/skills/argent-react-native-app-workflow/SKILL.md

@@ -3,6 +3,8 @@ name: argent-react-native-app-workflow
 description: Step-by-step workflows for developing or debugging React Native apps on iOS simulator or Android emulator. Use when starting the app, debugging Metro, fixing builds, diagnosing runtime errors, or running tests.
 ---
 
+Physical iPhone (`kind: "device"`): Metro debugging and profiling tools reject it. Use a simulator.
+
 ## 1. Starting the React Native App
 
 ### 1.1 Explore Configuration (MANDATORY — Do This First)

package/skills/argent-react-native-profiler/SKILL.md

@@ -5,6 +5,8 @@ description: Profile a React Native Hermes app to measure re-render and CPU perf
 
 This skill is complementary to `argent-react-native-optimization`, not a replacement for it.
 
+Physical iPhone: not supported; `react-profiler-*` reject `kind: "device"`. Profile on a simulator.
+
 ## 2. Tool Overview
 
 ### React Profiler (Hermes / React commits)

package/skills/argent-test-ui-flow/SKILL.md

@@ -5,6 +5,8 @@ description: Autonomously test an app UI (iOS or Android) by running interact-sc
 
 ## Platform-agnostic
 
+Physical iPhone (`kind: "device"`): read `argent-ios-device-interact` first. `launch-app` before anything; `describe` fails while the app is backgrounded.
+
 The interaction tool names are identical on iOS and Android — `gesture-tap`, `gesture-swipe`, `describe`, `screenshot`, `launch-app`, etc. — and the tool-server auto-dispatches based on the `udid` you pass (UUID-shape → iOS, adb serial → Android).
 
 **Before testing, resolve which device to test on.** Call `list-devices` and follow `<device_selection_rule>`: prefer a running device on any platform;