@swmansion/argent 0.22.1-next.7 → 0.22.1-next.8

package/dist/cli-cmds.mjs

@@ -7210,7 +7210,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.22.1-next.7";
+    return "0.22.1-next.8";
   }
   return "0.0.0";
 }

package/dist/installer.mjs

@@ -16428,7 +16428,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID4();
 function readCliVersion() {
   if (true) {
-    return "0.22.1-next.7";
+    return "0.22.1-next.8";
   }
   return "0.0.0";
 }

package/dist/tool-server.cjs

@@ -95734,7 +95734,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.22.1-next.7";
+    return "0.22.1-next.8";
   }
   return "0.0.0";
 }
@@ -111155,7 +111155,7 @@ function isNativeDevtoolsBlockResult(toolId, result) {
 async function precheckNativeDevtools(api, udid, bundleId) {
   if (bundleId !== void 0 && !isInjectableBundleId(bundleId)) {
     throw new FailureError(
-      `${bundleId} is an Apple system app: it is a platform binary with library validation, so Argent native devtools cannot be relied on to inject into it \u2014 treat it as unavailable rather than retrying. ` + NON_INJECTABLE_RECOVERY,
+      `${bundleId} is an Apple system app: it is never the app under test, so Argent native devtools refuse to read one \u2014 treat it as unavailable rather than retrying. ` + NON_INJECTABLE_RECOVERY,
       {
         error_code: FAILURE_CODES.NATIVE_DEVTOOLS_NOT_INJECTABLE,
         failure_stage: "native_devtools_precheck",
@@ -111854,7 +111854,7 @@ function tcpArtifactHint(err) {
   return /TCP-transport (?:binary|dylib) not found/.test(message) ? message : void 0;
 }
 var TVOS_HINT = "This is an Apple TV (tvOS) simulator, which the iOS accessibility service does not support. Use the `describe` tool to read the focused and focusable elements, `tv-remote` (up/down/left/right/select/back/menu/home) to move focus, and `keyboard` to type. See the argent-tv-interact skill.";
-var NON_INJECTABLE_HINT = "This is an Apple system app (com.apple.*), which cannot be relied on to load argent's native-devtools instrumentation \u2014 the native view hierarchy is unavailable and restarting the app will NOT help. Take a `screenshot` to see the screen and interact by coordinate. " + NON_INJECTABLE_NATIVE_WARNING;
+var NON_INJECTABLE_HINT = "This is an Apple system app (com.apple.*), which argent's native-devtools instrumentation does not support \u2014 the native view hierarchy is unavailable and restarting the app will NOT help. Take a `screenshot` to see the screen and interact by coordinate. " + NON_INJECTABLE_NATIVE_WARNING;
 function emptyTree() {
   return parseDescribeResult({
     role: "AXGroup",
@@ -116225,10 +116225,10 @@ Returns { envSetup, appRunning, connected, requiresRestart, state, message, next
 - state: why devtools are or aren't live, measured from the running process. "connected"; "not_running"; "stale_process" (the process cannot reach this simulator's devtools endpoint \u2014 launched either before argent's instrumentation was in place or against an earlier tool-server's listener \u2014 so restart-app fixes it); "unregistered" (the process IS injected and pointed at this simulator's devtools endpoint yet the service never registered it, so restarting the app cannot help); "connecting" (the process IS injected but launched moments ago and is still connecting, so waiting is what helps); "indeterminate" (the process could not be inspected). Omitted when injectable is false, which is terminal on its own.
 - message: the remedy for that state, in full. Omitted when connected or non-injectable. Prefer it over inferring one from the booleans \u2014 it is the only field that can tell you to stop restarting the app.
 - nextLaunchWillBeInjected: if you launch this bundle now, native devtools env setup is already in place (always false for a non-injectable app)
-- injectable: whether native devtools can be relied on to inject into this app. Apple system apps (bundle ids under com.apple.) are platform binaries with library validation, so the dylib cannot be counted on to load into them \u2014 it has been observed both loading and not loading, depending on the simulator runtime.
+- injectable: whether this app is a supported target for Argent native devtools. Apple system apps (bundle ids under com.apple.) are not: they are never the app under test, so the native tools refuse to read one.
 
 Call this before using app-scoped native hierarchy tools or native-network-logs.
-If injectable is false: treat this as TERMINAL \u2014 injection cannot be relied on for this app, and no relaunch changes which way it goes. Do NOT restart/retry. Use the standard \`describe\` tool (its accessibility path reads the screen without injection) or \`screenshot\` (then interact by coordinate). Do not fall back to the native-devtools feature tools (native-describe-screen, native-find-views, native-full-hierarchy, native-network-logs, native-view-at-point, native-user-interactable-view-at-point) \u2014 they run the same injection precheck and fail with the same non-injectable error.
+If injectable is false: treat this as TERMINAL \u2014 the app is not a supported native-devtools target, and no relaunch changes that. Do NOT restart/retry. Use the standard \`describe\` tool (its accessibility path reads the screen without injection) or \`screenshot\` (then interact by coordinate). Do not fall back to the native-devtools feature tools (native-describe-screen, native-find-views, native-full-hierarchy, native-network-logs, native-view-at-point, native-user-interactable-view-at-point) \u2014 they run the same injection precheck and fail with the same non-injectable error.
 If appRunning is false and nextLaunchWillBeInjected is true: use launch-app normally.
 If requiresRestart is true: call restart-app once, then proceed with the native feature. Read state before acting on a second such reading \u2014 indeterminate reaches this rule too, and its line below bounds it at that one restart.
 If state is unregistered: do NOT restart the app again \u2014 it already launched under the terms a restart would recreate. Restart the tool-server (\`argent server stop && argent server start --detach\`), then retry. If it reads unregistered again after that restart, stop: the process loads argent's dylib but never dials, and no further restart on either side changes it \u2014 treat native devtools as unavailable, then use \`describe\` or \`screenshot\` and drive by coordinate.
@@ -144653,7 +144653,7 @@ var FULL_HIERARCHY_FIELDS = [
 ];
 async function unreadableHierarchyReason(nativeApi, bundleId) {
   if (!isInjectableBundleId(bundleId)) {
-    return `${bundleId} is an Apple system app: it is a platform binary with library validation, so argent's native devtools cannot be relied on to inject into it, and without them a flow has no view hierarchy to resolve selectors against. Replace the selector steps with coordinate ones \u2014 \`tap: { x: 0.5, y: 0.35 }\` takes a point directly and reads no tree \u2014 or target an app argent installs.`;
+    return `${bundleId} is an Apple system app: it is never the app under test, so argent's native devtools refuse to read one, and without them a flow has no view hierarchy to resolve selectors against. Replace the selector steps with coordinate ones \u2014 \`tap: { x: 0.5, y: 0.35 }\` takes a point directly and reads no tree \u2014 or target an app argent installs.`;
   }
   const state3 = await nativeApi.appConnectionState(bundleId).catch(() => "indeterminate");
   if (state3 === "connected") {
@@ -144661,7 +144661,10 @@ async function unreadableHierarchyReason(nativeApi, bundleId) {
   }
   return `${buildAppStateMessage(bundleId, state3)} Flows resolve selectors against the full view hierarchy native devtools serve.`;
 }
-async function queryFullHierarchyTree(registry2, device, launchedNativeApp) {
+function systemAppFlowTargetRefusal(bundleId) {
+  return `${bundleId} is an Apple system app (com.apple.*) - never a valid flow target: it is not the app under test, and argent's native devtools refuse to read one (a system process either never services the read, or describes offscreen UI as if it were the launched app), so this flow has no view hierarchy to resolve selectors against and no relaunch or retry changes this verdict. Replace the selector steps with coordinate ones - \`tap: { x: 0.5, y: 0.35 }\` takes a point directly and reads no tree - or point this flow's \`launch\` step at the app under test.`;
+}
+async function queryFullHierarchyTree(registry2, device, target) {
   let nativeApi;
   try {
     const ndRef = nativeDevtoolsRef(device);
@@ -144672,22 +144675,113 @@ async function queryFullHierarchyTree(registry2, device, launchedNativeApp) {
       { cause: err }
     );
   }
-  if (launchedNativeApp !== void 0 && nativeApi.listConnectedBundleIds().length === 0) {
-    throw new Error(await unreadableHierarchyReason(nativeApi, launchedNativeApp));
-  }
-  let target;
-  try {
-    target = await resolveNativeTargetApp(nativeApi, void 0);
-  } catch (err) {
-    const timedOut = getFailureSignal(err)?.error_code === FAILURE_CODES.NATIVE_DEVTOOLS_RPC_TIMEOUT;
-    if (timedOut && launchedNativeApp !== void 0 && nativeApi.listConnectedBundleIds().includes(launchedNativeApp)) {
-      target = { bundleId: launchedNativeApp };
-    } else {
-      throw err;
+  let bundleId;
+  if (target?.pinned) {
+    bundleId = target.bundleId;
+    if (!isInjectableBundleId(bundleId)) {
+      throw new FailureError(systemAppFlowTargetRefusal(bundleId), {
+        error_code: FAILURE_CODES.NATIVE_DEVTOOLS_NOT_INJECTABLE,
+        failure_stage: "flow_tree_pinned_target",
+        failure_area: "tool_server",
+        error_kind: "validation"
+      });
+    }
+    if (!nativeApi.isConnected(bundleId)) {
+      throw new FailureError(
+        `${bundleId} lost its devtools connection after launch (the app crashed, was terminated, or its socket closed) - restart it (restart-app, or a flow \`launch\` step) so the full view hierarchy is readable; launch-app recovers only the causes that killed the process, since on iOS it just foregrounds one that is still alive`,
+        {
+          error_code: FAILURE_CODES.NATIVE_DEVTOOLS_NOT_CONNECTED,
+          failure_stage: "flow_tree_pinned_target",
+          failure_area: "tool_server",
+          error_kind: "not_found"
+        }
+      );
     }
+    let pinnedState;
+    try {
+      pinnedState = await nativeApi.getAppState(bundleId);
+      target.probeAnswered = true;
+    } catch (err) {
+      if (getFailureSignal(err)?.error_code !== FAILURE_CODES.NATIVE_DEVTOOLS_RPC_TIMEOUT) {
+        throw err;
+      }
+      if (target.probeAnswered) {
+        throw new FailureError(
+          `${bundleId} (the launched app) stopped answering Application.getState - the probe timed out although an earlier one in this run answered, so the app's main queue is no longer being serviced. For a pinned app that is usually the suspension iOS applies once a flow leaves it (e.g. a tap that opened another app), and a suspended app's hierarchy is not what is on screen; in-app work blocking the main thread past the probe timeout looks the same from here. Reading anyway parks on that same unserviced queue: certain to time out if the app is suspended, and paying the longer hierarchy timeout to find that out if it is not. If this flow's subject IS the other app, give the flow a \`launch:\` step for that app - it re-pins reads to it, and a pinned read probes only the app it names, so the silent ${bundleId} is never touched; \`tool: launch-app\` or \`tool: restart-app\` naming that app works too - each re-targets reads at the app it starts, and is how a recorded flow switches apps. A foreground-NEUTRAL raw \`tool:\` step does not work here, because demoting the pin sends reads back to auto-resolve, which probes every connection at once and is sunk by this same silent one. If the flow left ${bundleId} but is still about it, make it return before reading the UI. If it never left, the main thread is busy: raise the step's \`timeout:\` so the poll re-reads past the work, or \`launch\` ${bundleId} again.`,
+          {
+            // The timeout's own code, NOT
+            // NATIVE_TARGET_SINGLE_APP_NOT_FOREGROUND: nothing answered, so no
+            // app state was observed to classify it by.
+            error_code: FAILURE_CODES.NATIVE_DEVTOOLS_RPC_TIMEOUT,
+            failure_stage: "flow_tree_pinned_target",
+            failure_area: "tool_server",
+            error_kind: "timeout"
+          },
+          err instanceof Error ? { cause: err } : void 0
+        );
+      }
+    }
+    if (pinnedState && !chooseFrontmostConnectedApp([pinnedState])) {
+      throw new FailureError(
+        `${bundleId} (the launched app) has no foreground presence at all (applicationState=${pinnedState.applicationState}, foregroundActiveScenes=${pinnedState.foregroundActiveSceneCount}, foregroundInactiveScenes=${pinnedState.foregroundInactiveSceneCount}) - a step in this flow left the app (e.g. a tap that opened another app), so a read of its hierarchy would describe a screen that is not on screen. Transitional states are NOT refused here: an \`inactive\` app, or one still holding a foreground scene, is read as usual - under a system alert or mid-transition it is still the app on screen. If this flow's subject IS another app, give the flow a \`launch:\` step for that app - it re-pins reads to it, and no wedged sibling connection can sink a pinned read; a raw \`tool:\` step demotes the pin and returns reads to frontmost auto-resolve, which works when the app on screen answers but is sunk by a single wedged connection. Otherwise make the flow return to ${bundleId} before reading the UI, or \`launch\` it again.`,
+        {
+          error_code: FAILURE_CODES.NATIVE_TARGET_SINGLE_APP_NOT_FOREGROUND,
+          failure_stage: "flow_tree_pinned_target",
+          failure_area: "tool_server",
+          error_kind: "validation"
+        }
+      );
+    }
+  } else {
+    if (target && nativeApi.listConnectedBundleIds().length === 0) {
+      throw new Error(await unreadableHierarchyReason(nativeApi, target.bundleId));
+    }
+    let resolved;
+    try {
+      resolved = await resolveNativeTargetApp(nativeApi, void 0);
+    } catch (err) {
+      const timedOut = getFailureSignal(err)?.error_code === FAILURE_CODES.NATIVE_DEVTOOLS_RPC_TIMEOUT;
+      if (!timedOut || !target) throw err;
+      if (!isInjectableBundleId(target.bundleId)) {
+        throw new FailureError(
+          systemAppFlowTargetRefusal(target.bundleId),
+          {
+            error_code: FAILURE_CODES.NATIVE_DEVTOOLS_NOT_INJECTABLE,
+            failure_stage: "flow_tree_unpinned_hint",
+            failure_area: "tool_server",
+            error_kind: "validation"
+          },
+          err instanceof Error ? { cause: err } : void 0
+        );
+      }
+      if (!nativeApi.listConnectedBundleIds().includes(target.bundleId)) throw err;
+      let hintState;
+      try {
+        hintState = await nativeApi.getAppState(target.bundleId);
+      } catch (probeErr) {
+        if (getFailureSignal(probeErr)?.error_code === FAILURE_CODES.NATIVE_DEVTOOLS_RPC_TIMEOUT) {
+          throw err;
+        }
+        throw probeErr;
+      }
+      if (!chooseFrontmostConnectedApp([hintState])) {
+        throw new FailureError(
+          `${target.bundleId} (the launched app) has no foreground presence at all (applicationState=${hintState.applicationState}, foregroundActiveScenes=${hintState.foregroundActiveSceneCount}, foregroundInactiveScenes=${hintState.foregroundInactiveSceneCount}) - auto-resolve's probe of every connection timed out and the read fell back to the launched app, but a step in this flow left it (e.g. a tap that opened another app), so reading its hierarchy would describe a screen that is not on screen. Transitional states are NOT refused here: an \`inactive\` app, or one still holding a foreground scene, is read as usual. If this flow's subject IS another app, give the flow a \`launch:\` step for that app; otherwise make the flow return to ${target.bundleId} before reading the UI, or \`launch\` it again.`,
+          {
+            error_code: FAILURE_CODES.NATIVE_TARGET_SINGLE_APP_NOT_FOREGROUND,
+            failure_stage: "flow_tree_unpinned_hint",
+            failure_area: "tool_server",
+            error_kind: "validation"
+          },
+          err instanceof Error ? { cause: err } : void 0
+        );
+      }
+      resolved = { bundleId: target.bundleId };
+    }
+    bundleId = resolved.bundleId;
   }
   const rawResult = await nativeApi.queryViewHierarchy(
-    target.bundleId,
+    bundleId,
     "ViewHierarchy.getFullHierarchy",
     {
       fields: FULL_HIERARCHY_FIELDS,
@@ -144695,11 +144789,11 @@ async function queryFullHierarchyTree(registry2, device, launchedNativeApp) {
     }
   );
   if (rawResult.error) {
-    throw new Error(`getFullHierarchy failed for ${target.bundleId}: ${rawResult.error}`);
+    throw new Error(`getFullHierarchy failed for ${bundleId}: ${rawResult.error}`);
   }
   if (!Array.isArray(rawResult.windows) || rawResult.windows.length === 0) {
     throw new Error(
-      `getFullHierarchy returned no windows for ${target.bundleId} \u2014 the app is not injectable (e.g. an Apple system app) or has no readable foreground window, so flows cannot resolve selectors against its view hierarchy`
+      `getFullHierarchy returned no windows for ${bundleId} - it has no window attached to read (backgrounded, or its first window not attached yet), so flows cannot resolve selectors against its view hierarchy; foreground or relaunch it, and if that bundle id is a com.apple.* system process the read resolved to a background system app rather than the app under test, so give this flow a \`launch\` step to pin reads to the right app`
     );
   }
   const { tree, screen } = adaptFullHierarchy(rawResult);
@@ -144906,13 +145000,15 @@ async function queryVegaTree(device) {
 }
 
 // ../tool-server/src/tools/flows/flow-tree.ts
-async function fetchFlowTree(registry2, device, launchedNativeApp) {
+async function fetchFlowTree(registry2, device, target) {
   const source = FLOW_TREE_SOURCES[device.platform];
   if (!source) return fetchTree(registry2, device);
-  return source(registry2, device, launchedNativeApp);
+  return source(registry2, device, target);
 }
 var FLOW_TREE_SOURCES = {
-  ios: (registry2, device, launchedNativeApp) => queryFullHierarchyTree(registry2, device, launchedNativeApp),
+  // Only iOS consumes the target: the platforms below resolve their tree
+  // source per-device and never auto-resolve.
+  ios: (registry2, device, target) => queryFullHierarchyTree(registry2, device, target),
   android: (registry2, device) => queryAndroidFullHierarchy(registry2, device),
   chromium: (registry2, device) => queryChromiumTree(registry2, device),
   vega: (_registry, device) => queryVegaTree(device)
@@ -145118,7 +145214,7 @@ function provenTreeOutage(env) {
   return proven && proven.deviceId === env.device.id ? proven.error : void 0;
 }
 function readFlowTree(env) {
-  return fetchFlowTree(env.registry, env.device, env.launchedNativeApp).then((data) => {
+  return fetchFlowTree(env.registry, env.device, env.treeTarget).then((data) => {
     if (env.treeOutage) env.treeOutage.proven = void 0;
     return data;
   });
@@ -146173,7 +146269,11 @@ async function captureTapSelector(registry2, session, udid, point) {
   try {
     const device = resolveDevice(udid);
     const launched = recordedLaunchedApp(session, device.platform);
-    const { tree, source } = await fetchFlowTree(registry2, device, launched);
+    const { tree, source } = await fetchFlowTree(
+      registry2,
+      device,
+      launched ? { bundleId: launched, pinned: false, probeAnswered: false } : void 0
+    );
     const node = nodeAtPoint(tree, point);
     if (!node) return { warning: "no element found under the tap; kept coordinates (brittle)" };
     const selector = deriveSelector(node);
@@ -149111,6 +149211,7 @@ async function runLaunch(state3, app) {
       reason: `no app id declared for platform "${device.platform}" \u2014 add a launch entry for it`
     };
   }
+  state3.treeTarget = void 0;
   let restart;
   try {
     restart = await invokeOnDevice(env, "restart-app", { bundleId });
@@ -149125,7 +149226,7 @@ async function runLaunch(state3, app) {
   const gate = await treeSourceGate(registry2, device, bundleId, signal);
   if (signal?.aborted) return ABORTED_OUTCOME;
   if (gate) return { ok: false, reason: gate };
-  state3.launchedNativeApp = bundleId;
+  state3.treeTarget = { bundleId, pinned: true, probeAnswered: false };
   return { ok: true };
 }
 async function runChromiumLaunch(state3, app) {
@@ -149312,7 +149413,11 @@ function createRunFlowTool(registry2) {
     },
     description: `Run a saved flow from the .argent/flows/ directory, or an explicit boundary-managed flow_path.
 Steps run in order: \`launch\` starts an app from scratch (terminate + relaunch) and waits until it is
-ready; \`tool\` calls dispatch through the registry; \`tap\`/\`long-press\`/\`type\` resolve a selector to an
+ready (on iOS it also pins later element lookups to that app rather than auto-detecting the frontmost
+one); \`tool\` calls dispatch through the registry (a raw \`tool\` step ends that iOS pin, so lookups
+auto-detect again until the next \`launch\`, though a tool that cannot change the foreground app leaves the
+launched id as a fallback for a timed-out auto-detect, and \`launch-app\`/\`restart-app\` leave the id they
+started as that fallback instead); \`tap\`/\`long-press\`/\`type\` resolve a selector to an
 element and act on it (\`tap: { on, times: 2 }\` double-taps; \`long-press: { on, duration }\` presses and
 holds; \`tap\`/\`long-press\` alternatively take a raw normalized point \u2014 bare \`{ x, y }\` or \`on: { x, y }\`;
 any selector may scope its matches geometrically, the CSS combinators read off frames: \`within: <selector>\`
@@ -150021,14 +150126,17 @@ async function execLeafStep(state3, step, index, scope) {
       if (step.delayMs && !await sleepOrAbort(step.delayMs, signal)) {
         return { ...base, status: "skip", tool: step.name, reason: "run aborted during delay" };
       }
+      if (FOREGROUND_CHANGING_TOOLS.has(step.name)) {
+        state3.treeTarget = void 0;
+        if (state3.treeOutage) state3.treeOutage.proven = void 0;
+      } else if (state3.treeTarget?.pinned) {
+        state3.treeTarget = { ...state3.treeTarget, pinned: false };
+        if (state3.treeOutage) state3.treeOutage.proven = void 0;
+      }
+      if (isNestedOrchestratorTool(step.name) && state3.treeOutage) {
+        state3.treeOutage.proven = void 0;
+      }
       try {
-        if (FOREGROUND_CHANGING_TOOLS.has(step.name)) {
-          state3.launchedNativeApp = void 0;
-          if (state3.treeOutage) state3.treeOutage.proven = void 0;
-        }
-        if (isNestedOrchestratorTool(step.name) && state3.treeOutage) {
-          state3.treeOutage.proven = void 0;
-        }
         const result = await invokeSubTool(registry2, ctx, step.name, args);
         if (isUnmetUiWaitResult(step.name, result)) {
           const note = result.note;
@@ -150075,7 +150183,9 @@ async function execLeafStep(state3, step, index, scope) {
         }
         if (step.name === "launch-app" || step.name === "restart-app") {
           const launched = args.bundleId;
-          if (typeof launched === "string") state3.launchedNativeApp = launched;
+          if (typeof launched === "string") {
+            state3.treeTarget = { bundleId: launched, pinned: false, probeAnswered: false };
+          }
         }
         return { ...base, status: "pass", tool: step.name, result, outputHint, args };
       } catch (err) {

package/package.json

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

package/skills/argent-create-flow/references/flow-yaml.md

@@ -70,6 +70,12 @@ On iOS, Android, and Chromium, an id absent from `describe` can still resolve in
 
 The recorder rechecks each successful `await-ui-element` against the runner tree. Follow any `message` warning and replay each conversion. On Vega, a mismatch usually means the screen changed. A `text` check can also select different elements from the same source. See [Live waits and checks](live-authoring.md#live-waits-and-checks).
 
+**On iOS, a `launch:` step also decides which app the runner reads.** A successful `launch:` pins later runner-tree reads to that app, so a read probes only that app instead of fanning out over every connected one to find the frontmost. A pinned read still refuses, naming the reason, when the app has no foreground presence left, when it stops answering after an earlier read got through, when its devtools connection dropped, or when the pinned id is a `com.apple.*` system app.
+
+Any raw `tool:` step ends the pin, because its effect on the screen is opaque to the runner, and reads auto-detect the frontmost app again until the next `launch:` re-pins. A tool that cannot change the foreground app leaves the launched id as an unpinned fallback, which takes the read only when auto-detection times out and the launched app vouches for itself with a probe of its own. `launch-app`, `restart-app`, `reinstall-app`, `open-url`, and `button` drop even that; `launch-app` and `restart-app` replace it with the app they just started, still unpinned. Nested `run:` fragments inherit both the pin and its clearing.
+
+So on iOS recording and replay can read different apps, not only different projections: recording has no run state and always auto-detects the frontmost connected app, while a replay read between a `launch:` and the next raw `tool:` step reads the launched app.
+
 **On iOS, never copy a `role` from `describe` into a flow selector.** The runner derives iOS roles from the UIView class name and `describe` from accessibility traits, so a React Native `Pressable` (class `RCTView`) is `AXGroup` to the runner and `AXButton` to `describe`. Select on `id`/`text`, or confirm the role against the runner's own tree.
 
 When several nodes match, the directive decides:
@@ -99,7 +105,7 @@ Scopes can combine and nest, with at most six scope keys. Use strict selectors f
 
 Directives stop the flow on failure and skip later steps. `flow-execute` documents their shapes. The available directives are `launch`, `tap`, `long-press`, `type`, `scroll-to`, `pinch`, `rotate`, `await`, `assert`, `wait`, `snapshot`, `run`, `when`, `echo`, and `tool`.
 
-Use the launch map for cross-platform flows. A bare launch applies everywhere and becomes an app path on Chromium. The map takes `native:`, `ios:`, `android:`, `vega:`, and `chromium:`. `native:` is one id shared by iOS, Android, and Vega, and a per-platform key overrides it for that platform. `chromium:` accepts a relative or absolute app path. A launch that declares no id for the run's platform is an error, not a cue to switch platforms.
+Use the launch map for cross-platform flows. A bare launch applies everywhere and becomes an app path on Chromium. The map takes `native:`, `ios:`, `android:`, `vega:`, and `chromium:`. `native:` is one id shared by iOS, Android, and Vega, and a per-platform key overrides it for that platform. `chromium:` accepts a relative or absolute app path. A launch that declares no id for the run's platform is an error, not a cue to switch platforms. On iOS, a successful launch also pins later tree reads to that app until the next raw `tool:` step, so read [The runner tree is not the discovery tree](#the-runner-tree-is-not-the-discovery-tree) when a read describes the wrong screen.
 
 ```yaml
 - launch: { native: com.acme.app, chromium: ../../app }

package/skills/argent-create-flow/references/reliability-and-recovery.md

@@ -53,9 +53,9 @@ Use the same explicit UDID throughout. Multiple booted simulators are not an inj
 
 This fallback applies only to `com.apple.*` system apps. A connection failure in another app never authorizes it.
 
-Apple system apps are platform binaries with library validation, so the instrumentation cannot be relied on to load into them — it has been seen both loading and not loading, depending on the simulator runtime. Either way it is no basis for a selector.
+Argent refuses `com.apple.*` bundle ids at every native-devtools read that names one, because a system app is never the app under test. The instrumentation has been seen both loading and not loading into one, depending on the simulator runtime — either way it is no basis for a selector. `restart-app`, `launch-app`, and `describe` still work on one; it just never gets a flow tree.
 
-Give the flow a `launch:` step as usual. On iOS the launch waits the full devtools budget out, then passes for one of these bundle ids: starting the app is all that step is for, and a coordinate-driven flow needs nothing more. The flow stays e2e; it just pays roughly sixteen seconds at the launch. Where the impossibility bites is selector resolution, and the first selector step reports it there — terminally, naming the coordinate remedy — rather than as a launch failure. The rest of the injection-free form:
+Give the flow a `launch:` step as usual. On iOS the launch waits the full devtools budget out, then passes for one of these bundle ids: starting the app is all that step is for, and a coordinate-driven flow needs nothing more. The flow stays e2e; it just pays roughly sixteen seconds at the launch. Where the refusal bites is selector resolution, and the first selector step reports it there — terminally, naming the coordinate remedy — rather than as a launch failure. The rest of the tree-free form:
 
 - Raw `tool: await-ui-element` accessibility checks.
 - Point taps or long-presses derived from `describe`, each named by an echo.
@@ -66,9 +66,9 @@ Every point tap or long-press in such a flow passes **carrying a warning** for a
 
 A recorded wait carries a different warning: it adds about one second and reports that the runner tree is unavailable. That warning is expected too. Keep the wait as a raw `tool:` step.
 
-Report that the flow is injection-free and its coordinates are not portable. It cannot satisfy the QA contract. Report the artifact and platform blocker instead.
+Report that the flow has no flow tree and its coordinates are not portable. It cannot satisfy the QA contract. Report the artifact and platform blocker instead.
 
-A normally injectable app that is broken in the environment gets the same coordinate-only treatment, but not the same launch: there the `launch:` step fails, since the gate withholds its verdict only for a bundle id injection may never reach. Start such a flow with a raw `tool: restart-app`, which terminates and relaunches without the readiness gate, and accept that the result is a **fragment** — its first non-echo step is not `launch:`, so the runner never classifies it as e2e, and it cannot complete `argent-qa-flows`, which requires a leading `launch:`. Report the blocker rather than labeling that fallback a completed QA test.
+A normally injectable app that is broken in the environment gets the same coordinate-only treatment, but not the same launch: there the `launch:` step fails, since the gate withholds its verdict only for a bundle id argent refuses outright. Start such a flow with a raw `tool: restart-app`, which terminates and relaunches without the readiness gate, and accept that the result is a **fragment** — its first non-echo step is not `launch:`, so the runner never classifies it as e2e, and it cannot complete `argent-qa-flows`, which requires a leading `launch:`. Report the blocker rather than labeling that fallback a completed QA test.
 
 ## Tree source recovery on Android, Chromium, and Vega