@swmansion/argent 0.21.0 → 0.21.1-next.0

package/dist/tool-server.cjs

@@ -98753,6 +98753,19 @@ var ARGENT_BOOTSTRAP_DYLIB_BASENAMES = /* @__PURE__ */ new Set([
   "libArgentInjectionBootstrap.dylib",
   "libInjectionBootstrap.dylib"
 ]);
+function processCarriesInjection(env, endpoint) {
+  const inserted = [...ARGENT_BOOTSTRAP_DYLIB_BASENAMES].some((name) => env.includes(name));
+  if (!inserted) return false;
+  const expected = endpoint.transport === "tcp" ? `NATIVE_DEVTOOLS_IOS_CDP_PORT=${endpoint.port}` : `NATIVE_DEVTOOLS_IOS_CDP_SOCKET=${endpoint.socketPath}`;
+  return env.split(/\s+/).includes(expected);
+}
+var PS_PROBE_TIMEOUT_MS = 5e3;
+function parsePsElapsedSeconds(etime) {
+  const match = etime.trim().match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/);
+  if (!match) return null;
+  const [, days, hours, minutes, seconds] = match;
+  return Number(days ?? 0) * 86400 + Number(hours ?? 0) * 3600 + Number(minutes) * 60 + Number(seconds);
+}
 function splitDyldInsertLibraries(value) {
   return value.split(":").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
 }
@@ -98861,17 +98874,20 @@ async function setupNativeDevtoolsEnvRemote(udid, endpoint) {
   }
   await setSimulatorEnv(udid, "NATIVE_DEVTOOLS_IOS_CDP_PORT", String(endpoint.port));
 }
-function parseUIKitApplicationBundleIds(stdout) {
-  const bundleIds = /* @__PURE__ */ new Set();
+function parseUIKitApplicationJobs(stdout) {
+  const jobs = /* @__PURE__ */ new Map();
   for (const line of stdout.split("\n")) {
     const match = line.match(/UIKitApplication:([^[]+)/);
-    if (match) {
-      bundleIds.add(match[1].trim());
-    }
+    if (!match) continue;
+    const pid = line.match(/^(\d+)\s/);
+    jobs.set(match[1].trim(), pid ? Number(pid[1]) : null);
   }
-  return bundleIds;
+  return jobs;
 }
-async function listRunningUIKitApplicationBundleIds(udid) {
+function parseUIKitApplicationBundleIds(stdout) {
+  return new Set(parseUIKitApplicationJobs(stdout).keys());
+}
+async function listRunningApps(udid) {
   const { stdout } = await execFileAsync8(
     "xcrun",
     await simctlArgsForUdid(udid, ["spawn", udid, "launchctl", "list"]),
@@ -98881,7 +98897,42 @@ async function listRunningUIKitApplicationBundleIds(udid) {
       killSignal: SIMCTL_KILL_SIGNAL
     }
   );
-  return parseUIKitApplicationBundleIds(stdout);
+  return stdout;
+}
+async function listRunningUIKitApplicationBundleIds(udid) {
+  return parseUIKitApplicationBundleIds(await listRunningApps(udid));
+}
+async function readProcessLaunchState(pid) {
+  let stdout;
+  try {
+    ({ stdout } = await execFileAsync8(PS_BIN, ["eww", "-p", String(pid), "-o", "etime=,command="], {
+      encoding: "utf8",
+      timeout: PS_PROBE_TIMEOUT_MS,
+      // Matches the other `ps` probes (vega-process.ts). An environment can run
+      // to `kern.argmax` (1 MiB), exactly Node's default cap, so the default
+      // would ENOBUFS on a maximal one instead of reading it.
+      maxBuffer: 16 * 1024 * 1024
+    }));
+  } catch (err) {
+    process.stderr.write(`[ios-host] ps probe failed for pid ${pid}: ${String(err)}
+`);
+    return null;
+  }
+  const trimmed = stdout.trim();
+  const boundary = trimmed.search(/\s/);
+  if (boundary === -1) return null;
+  const ageSeconds = parsePsElapsedSeconds(trimmed.slice(0, boundary));
+  if (ageSeconds === null) return null;
+  return { pid, ageMs: ageSeconds * 1e3, env: trimmed.slice(boundary + 1) };
+}
+async function inspectRunningAppLocal(udid, bundleId) {
+  const jobs = parseUIKitApplicationJobs(await listRunningApps(udid));
+  if (!jobs.has(bundleId)) return { running: false, process: null };
+  const pid = jobs.get(bundleId) ?? null;
+  const process3 = pid === null ? null : await readProcessLaunchState(pid);
+  if (process3 !== null) return { running: true, process: process3 };
+  const stillListed = parseUIKitApplicationJobs(await listRunningApps(udid)).has(bundleId);
+  return { running: stillListed, process: null };
 }
 function spawnAxDaemonLocal(udid, endpoint) {
   const binaryPath = endpoint.transport === "tcp" ? axServiceBinaryPathTcp() : axServiceBinaryPath();
@@ -98931,6 +98982,7 @@ var localIosHost = {
   requiresTcp: false,
   setupNativeDevtoolsEnv: setupNativeDevtoolsEnvLocal,
   listRunningBundleIds: listRunningUIKitApplicationBundleIds,
+  inspectRunningApp: inspectRunningAppLocal,
   async bootstrapAx(udid) {
     await ensureAutomationEnabled(udid);
     return { entitlementBypassActive: await isEntitlementBypassActive(udid) };
@@ -98954,6 +99006,13 @@ var remoteIosHost = {
     const { stdout } = await simctlSpawn(udid, { args: ["launchctl", "list"] });
     return parseUIKitApplicationBundleIds(stdout);
   },
+  // App processes live on the orchestrator, so the local process table says
+  // nothing about how they were launched. Only running-ness is answerable; the
+  // null process keeps callers on their no-evidence path.
+  async inspectRunningApp(udid, bundleId) {
+    const { stdout } = await simctlSpawn(udid, { args: ["launchctl", "list"] });
+    return { running: parseUIKitApplicationJobs(stdout).has(bundleId), process: null };
+  },
   // Apply the accessibility defaults the tool-server needs (the local host does
   // this via `defaults write`; here we run the same writes through the remote
   // generic spawn). The entitlement-bypass plist is assumed active on cloud
@@ -112178,6 +112237,22 @@ function isInjectableBundleId(bundleId) {
 var NON_INJECTABLE_NATIVE_WARNING = "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.";
 var NON_INJECTABLE_RECOVERY = "Use the standard `describe` tool (its accessibility path reads the screen without injection) or `screenshot` (then interact by coordinate). " + NON_INJECTABLE_NATIVE_WARNING;
 var MAX_NATIVE_DEVTOOLS_INIT_ATTEMPTS = 3;
+var NATIVE_DEVTOOLS_AGE_SLOP_MS = 3e3;
+var NATIVE_DEVTOOLS_CONNECT_BUDGET_MS = 15e3;
+function buildAppStateMessage(bundleId, state3) {
+  switch (state3) {
+    case "not_running":
+      return `${bundleId} has no running process on this simulator, so there is no injected process to read. Call launch-app (or restart-app) then retry. If that launch fails rather than starting the app, the bundle id is not installed on this device \u2014 this state cannot tell the two apart; install it and no relaunch will be needed.`;
+    case "stale_process":
+      return `The running ${bundleId} process cannot reach this simulator's native-devtools endpoint \u2014 it was launched either before argent's instrumentation was in place or against an earlier tool-server's listener. A fresh process picks up the current one: call restart-app then retry.`;
+    case "unregistered":
+      return `${bundleId} is running with argent's native devtools injected and pointed at this simulator's devtools endpoint, but the service never registered its connection. Restarting the app cannot change that \u2014 it already launched under exactly the terms a restart would recreate. Restart the tool-server (\`argent server stop && argent server start --detach\`) and retry. If you have already restarted the tool-server for this app and it reads this way again, stop: the process is loading argent's dylib but never dialing, which no further restart on either side fixes. Treat native devtools as unavailable \u2014 read the screen with describe or screenshot and drive it by coordinate.`;
+    case "connecting":
+      return `${bundleId} is running with argent's native devtools injected and pointed at this simulator's devtools endpoint, and it launched moments ago \u2014 its connection has not finished being established. Wait a few seconds and retry the same call. Do NOT restart the app: launching it is what starts the connection, so a relaunch discards the one in progress and returns you to this same state.`;
+    case "indeterminate":
+      return `Native devtools are not connected to ${bundleId}, and its process could not be inspected to tell whether it is injected. Call restart-app then retry. If it is still not connected after that restart, the native-devtools service is stale rather than the app being uninjected \u2014 do not keep restarting the app; restart the tool-server (\`argent server stop && argent server start --detach\`) and retry.`;
+  }
+}
 function buildInitFailedResult(udid, failure) {
   return {
     status: "init_failed",
@@ -112185,10 +112260,33 @@ function buildInitFailedResult(udid, failure) {
     attempts: failure.attempts
   };
 }
+var NATIVE_DEVTOOLS_PRECHECK_TOOLS = /* @__PURE__ */ new Set([
+  "native-describe-screen",
+  "native-find-views",
+  "native-full-hierarchy",
+  "native-network-logs",
+  "native-view-at-point",
+  "native-user-interactable-view-at-point",
+  "native-devtools-status",
+  "launch-app",
+  "restart-app"
+]);
+var NATIVE_DEVTOOLS_BLOCK_STATUSES = /* @__PURE__ */ new Set([
+  "init_failed",
+  "restart_required",
+  "service_stale",
+  "connect_pending"
+]);
+function isNativeDevtoolsBlockResult(toolId, result) {
+  if (!NATIVE_DEVTOOLS_PRECHECK_TOOLS.has(toolId)) return false;
+  if (typeof result !== "object" || result === null) return false;
+  const status = result.status;
+  return typeof status === "string" && NATIVE_DEVTOOLS_BLOCK_STATUSES.has(status);
+}
 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 can never be injected into it. ` + NON_INJECTABLE_RECOVERY,
+      `${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,
       {
         error_code: FAILURE_CODES.NATIVE_DEVTOOLS_NOT_INJECTABLE,
         failure_stage: "native_devtools_precheck",
@@ -112210,13 +112308,21 @@ async function precheckNativeDevtools(api, udid, bundleId) {
       givenUp: false
     });
   }
-  if (bundleId !== void 0 && await api.requiresAppRestart(bundleId)) {
-    return {
-      status: "restart_required",
-      message: "Native devtools are not injected into the running app. Call restart-app then retry."
-    };
-  }
-  return null;
+  if (bundleId === void 0) return null;
+  const state3 = await api.appConnectionState(bundleId).catch(() => {
+    const failure = api.getInitFailure();
+    return failure ? buildInitFailedResult(udid, failure) : "indeterminate";
+  });
+  if (typeof state3 !== "string") return state3;
+  if (state3 === "connected") return null;
+  return {
+    // Neither `unregistered` (a relaunch provably cannot fix it) nor
+    // `connecting` (a relaunch aborts the handshake and resets the age the
+    // verdict reads) may be reported as restart_required — obeying that would
+    // return here forever.
+    status: state3 === "unregistered" ? "service_stale" : state3 === "connecting" ? "connect_pending" : "restart_required",
+    message: buildAppStateMessage(bundleId, state3)
+  };
 }
 function nativeDevtoolsRef(device, { transport = "unix" } = {}) {
   const transportSuffix = transport === "tcp" ? ":tcp" : "";
@@ -112478,6 +112584,7 @@ var nativeDevtoolsBlueprint = {
     } else {
       await bindNativeDevtoolsUnixSocket(server, socketPath);
     }
+    const listeningSince = Date.now();
     await ensureEnvReady().catch(() => {
     });
     const api = {
@@ -112489,10 +112596,28 @@ var nativeDevtoolsBlueprint = {
       isConnected: (bundleId) => connections2.has(bundleId),
       isAppRunning,
       listConnectedBundleIds: () => [...connections2.keys()],
-      async requiresAppRestart(bundleId) {
-        if (connections2.has(bundleId)) return false;
+      async appConnectionState(bundleId) {
+        if (connections2.has(bundleId)) return "connected";
         await reverifyEnv();
-        return true;
+        const inspection = await host.inspectRunningApp(udid, bundleId).catch((err) => {
+          process.stderr.write(
+            `[native-devtools] app inspection failed for ${bundleId}: ${String(err)}
+`
+          );
+          return null;
+        });
+        if (connections2.has(bundleId)) return "connected";
+        if (inspection === null) return "indeterminate";
+        if (!inspection.running) return "not_running";
+        if (inspection.process === null) return "indeterminate";
+        if (!processCarriesInjection(inspection.process.env, endpoint)) return "stale_process";
+        const listenerAgeMs = Date.now() - listeningSince;
+        const processAgeMs = inspection.process.ageMs;
+        if (processAgeMs + NATIVE_DEVTOOLS_AGE_SLOP_MS >= listenerAgeMs) {
+          return "stale_process";
+        }
+        if (processAgeMs < NATIVE_DEVTOOLS_CONNECT_BUDGET_MS) return "connecting";
+        return "unregistered";
       },
       activateNetworkInspection(bundleId) {
         activatedBundleIds.add(bundleId);
@@ -112846,7 +112971,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 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 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;
 function emptyTree() {
   return parseDescribeResult({
     role: "AXGroup",
@@ -112878,27 +113003,43 @@ async function describeIos(registry2, device, params, options = {}) {
   if (params.bundleId && !isInjectableBundleId(params.bundleId)) {
     return { tree, source: "ax-service", hint: hint ?? NON_INJECTABLE_HINT };
   }
+  let nativeApi;
   try {
     const ndRef = nativeDevtoolsRef(device);
-    const nativeApi = await registry2.resolveService(ndRef.urn, ndRef.options);
+    nativeApi = await registry2.resolveService(ndRef.urn, ndRef.options);
+  } catch (err) {
+    return { tree, source: "ax-service", hint: unexplainedHint(hint, errMsg(err), params) };
+  }
+  try {
     const target = await resolveNativeTargetApp(nativeApi, params.bundleId);
-    if (await nativeApi.requiresAppRestart(target.bundleId)) {
-      return { tree, source: "ax-service", should_restart: true, hint };
+    const state3 = await nativeApi.appConnectionState(target.bundleId).catch(() => "indeterminate");
+    if (state3 !== "connected") {
+      const diagnosis = buildAppStateMessage(target.bundleId, state3);
+      const merged = hint ? `${hint} ${diagnosis}` : diagnosis;
+      return state3 === "unregistered" || state3 === "connecting" ? { tree, source: "ax-service", hint: merged } : { tree, source: "ax-service", should_restart: true, hint: merged };
     }
     const rawResult = await nativeApi.queryViewHierarchy(
       target.bundleId,
       "ViewHierarchy.describeScreen"
     );
     if (rawResult.error) {
-      return { tree, source: "ax-service", hint };
+      return { tree, source: "ax-service", hint: unexplainedHint(hint, rawResult.error, params) };
     }
     const parsed = parseNativeDescribeScreenResult(rawResult);
     const nativeTree = adaptNativeDescribeToDescribeResult(parsed);
     return { tree: nativeTree, source: "native-devtools", hint };
-  } catch {
-    return { tree, source: "ax-service", hint };
+  } catch (err) {
+    return { tree, source: "ax-service", hint: unexplainedHint(hint, errMsg(err), params) };
   }
 }
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function unexplainedHint(hint, detail, params) {
+  const next = params.bundleId ? "Take a `screenshot` to see what is there." : "Pass `bundleId` to have the connection state measured, or take a `screenshot` to see what is there.";
+  const why = `The native view hierarchy could not be read (${detail}), so this empty accessibility tree is not evidence that nothing is on screen. ${next}`;
+  return hint ? `${hint} ${why}` : why;
+}
 
 // ../tool-server/src/tools/describe/platforms/android/index.ts
 init_src();
@@ -117164,6 +117305,9 @@ var zodSchema2 = external_exports.object({
   udid: external_exports.string().describe("Simulator UDID"),
   bundleId: external_exports.string().describe("Bundle ID of the app to check (e.g. com.example.MyApp)")
 });
+function envSetupReading(api, connected) {
+  return api.isEnvSetup() && (connected || api.getInitFailure() === null);
+}
 var nativeDevtoolsStatusTool = {
   id: "native-devtools-status",
   interaction: {
@@ -117179,18 +117323,23 @@ var nativeDevtoolsStatusTool = {
   description: `Check whether native devtools are connected to a specific app and whether the next launch is prepared for injection.
 Use when you need to verify native devtools readiness before calling native-full-hierarchy, native-describe-screen, or native-network-logs.
 
-Returns { envSetup, appRunning, connected, requiresRestart, nextLaunchWillBeInjected, injectable }:
+Returns { envSetup, appRunning, connected, requiresRestart, state, message, nextLaunchWillBeInjected, injectable }:
 - envSetup: DYLD_INSERT_LIBRARIES is configured in the simulator's launchd environment
 - appRunning: the target bundle currently has a running UIKit process on the simulator
 - connected: the dylib is active in the current running process for this bundleId
-- requiresRestart: the app is already running but its current process does not have native devtools injected (always false for a non-injectable app)
+- requiresRestart: the app is already running and a fresh process would reach this simulator's devtools endpoint where the current one does not \u2014 it carries no argent injection, was pointed at an earlier tool-server's listener, or could not be inspected to tell. Always false for a non-injectable app, and false when state is unregistered or connecting, where a relaunch cannot help.
+- 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 ever be injected into this app. Apple system apps (bundle ids under com.apple.) are platform binaries with library validation, so the dylib can never load into them.
+- 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.
 
 Call this before using app-scoped native hierarchy tools or native-network-logs.
-If injectable is false: this is a TERMINAL state \u2014 the app can never be injected. 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 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 appRunning is false and nextLaunchWillBeInjected is true: use launch-app normally.
-If requiresRestart is true: call restart-app, then proceed with the native feature.
+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.
+If state is connecting: do NOT restart the app \u2014 launching it is what starts the connection, so a relaunch discards the one in progress and returns this same state. Wait a few seconds and repeat this call.
+If state is indeterminate: the process could not be inspected, so restart-app is worth one attempt. If this call still reports it after that restart, do NOT restart the app again \u2014 the service is stale rather than the app uninjected, so restart the tool-server (\`argent server stop && argent server start --detach\`) and retry. Remote simulators can never inspect the process, so this is the only unconnected state a running app reaches there.
 Returns { status: "init_failed", message, attempts } instead when the simulator's native-devtools environment failed to initialize.
 Fails if the simulator server is not running for the given UDID.`,
   zodSchema: zodSchema2,
@@ -117202,18 +117351,19 @@ Fails if the simulator server is not running for the given UDID.`,
     await ensureDeps(device.platform === "ios-remote" ? ["sim-remote"] : ["xcrun"]);
     const api = services.nativeDevtools;
     if (!isInjectableBundleId(params.bundleId)) {
+      const connected2 = api.isConnected(params.bundleId);
       let appRunning2;
       try {
         appRunning2 = await api.isAppRunning(params.bundleId);
       } catch (err) {
-        const blocked2 = await precheckNativeDevtools(api, params.udid);
-        if (blocked2) return blocked2;
+        const failure = api.getInitFailure();
+        if (failure) return buildInitFailedResult(params.udid, failure);
         throw err;
       }
       return {
-        envSetup: api.isEnvSetup(),
+        envSetup: envSetupReading(api, connected2),
         appRunning: appRunning2,
-        connected: api.isConnected(params.bundleId),
+        connected: connected2,
         requiresRestart: false,
         nextLaunchWillBeInjected: false,
         injectable: false
@@ -117221,18 +117371,41 @@ Fails if the simulator server is not running for the given UDID.`,
     }
     const blocked = await precheckNativeDevtools(api, params.udid);
     if (blocked) return blocked;
-    const appRunning = await api.isAppRunning(params.bundleId);
-    const connected = api.isConnected(params.bundleId);
-    if (!connected) {
-      await api.reverifyEnv().catch(() => {
-      });
+    const measured = await api.appConnectionState(params.bundleId).catch(() => "indeterminate");
+    const connected = measured === "connected";
+    let appRunning;
+    let state3 = measured;
+    if (state3 === "indeterminate") {
+      try {
+        appRunning = await api.isAppRunning(params.bundleId);
+      } catch (err) {
+        const failure = api.getInitFailure();
+        if (failure) return buildInitFailedResult(params.udid, failure);
+        throw err;
+      }
+      if (!appRunning) state3 = "not_running";
+    } else {
+      appRunning = state3 !== "not_running";
     }
-    const envSetup = api.isEnvSetup();
+    const envSetup = envSetupReading(api, connected);
     return {
       envSetup,
       appRunning,
       connected,
-      requiresRestart: appRunning && !connected,
+      // Derived from the one state, so it can never disagree with it: a relaunch
+      // provably changes nothing for `unregistered`, destroys the handshake for
+      // `connecting`, and `not_running` needs a launch. That leaves the two a
+      // fresh process fixes — `indeterminate` among them, since an uninspectable
+      // host (ios-remote) supports no finer reading. Both already carry a live
+      // process (the settling above rewrote an empty `indeterminate` to
+      // `not_running`), so an `appRunning` conjunct would only restate the state.
+      requiresRestart: state3 === "stale_process" || state3 === "indeterminate",
+      state: state3,
+      // The booleans cannot express "one restart, then stop" — the shape
+      // `indeterminate` needs, and the only one ios-remote can report for a
+      // running app. Carrying the same prose as every other consumer keeps that
+      // escape off the agent having read this tool's description.
+      ...state3 === "connected" ? {} : { message: buildAppStateMessage(params.bundleId, state3) },
       nextLaunchWillBeInjected: envSetup,
       injectable: true
     };
@@ -117258,8 +117431,9 @@ var nativeNetworkLogsTool = {
   description: `Retrieve network requests captured at the native NSURLProtocol level. 
 Unlike the JS-level network inspector (view-network-logs), this captures ALL network traffic from the app including native modules, Swift/Objective-C networking, and background transfers that bypass JS fetch. 
 Use when you need to inspect native-level HTTP traffic that is invisible to JS fetch interception. 
-Returns { status, count, events } where each event contains URL, method, status code, headers, and timing. Returns { status: "restart_required" } if the dylib is not injected - if this happens, call "restart-app" then retry. 
-Fails if native devtools are not connected or the app is not running.`,
+Returns { status, count, events } where each event contains URL, method, status code, headers, and timing.
+If status is restart_required: follow the message (usually restart-app), then retry. If status is service_stale: the app is already injected, so restarting it cannot help \u2014 restart the tool-server (\`argent server stop && argent server start --detach\`) and retry. If the same status comes back after that restart, stop restarting: follow the message, which names the terminal fallback. If status is connect_pending: the app is injected and still connecting \u2014 do not restart it, wait a few seconds and retry. If status is init_failed: the simulator's native-devtools environment could not be initialised \u2014 follow the message (re-boot the simulator) rather than retrying this tool.
+A not-connected or not-running app comes back as one of those statuses rather than a failure. Failures are separate: an Apple system app is rejected outright (terminal \u2014 never retry it), while a missing host dependency or a udid that is not an Apple device is not.`,
   zodSchema: zodSchema3,
   services: (params) => ({
     nativeDevtools: nativeDevtoolsRef(resolveDevice(params.udid))
@@ -117309,7 +117483,8 @@ var nativeFindViewsTool = {
 Use when you need to locate a specific view by its properties without dumping the entire hierarchy.
 Returns { status: "ok", matches } with matching views including their frames, properties, optional ancestors, and optional children. Much more targeted than native-full-hierarchy.
 At least one of className, identifier, label, tag, or nativeID must be provided.
-Fails if native devtools are not connected, the app is not running, or status is restart_required (call restart-app then retry).`,
+If status is restart_required: follow the message (usually restart-app), then retry. If status is service_stale: the app is already injected, so restarting it cannot help \u2014 restart the tool-server (\`argent server stop && argent server start --detach\`) and retry. If the same status comes back after that restart, stop restarting: follow the message, which names the terminal fallback. If status is connect_pending: the app is injected and still connecting \u2014 do not restart it, wait a few seconds and retry. If status is init_failed: the simulator's native-devtools environment could not be initialised \u2014 follow the message (re-boot the simulator) rather than retrying this tool.
+A not-connected or not-running app comes back as one of those statuses rather than a failure. Failures are separate: an Apple system app is rejected outright (terminal \u2014 never retry it), and the hierarchy query itself can error or time out.`,
   zodSchema: zodSchema4,
   services: (params) => ({
     nativeDevtools: nativeDevtoolsRef(resolveDevice(params.udid))
@@ -117376,8 +117551,9 @@ var nativeFullHierarchyTool = {
 WARNING: Output can be extremely large (100KB\u2013500KB+) for complex apps, especially those built with SwiftUI. Prefer native-find-views for targeted queries.
 Use skipClasses / skipClassPrefixes to prune SwiftUI internal subtrees and reduce output size. Use the fields param to request only the properties you need.
 Use when you need deep layout debugging, finding views with no accessibility labels, or verifying view structure not exposed through the accessibility tree.
-Returns { status: "ok", windows } with the full view hierarchy, or { status: "restart_required" } if the dylib is not injected.
-Fails if native devtools are not connected or the app is not running.`,
+Returns { status: "ok", windows } with the full view hierarchy.
+If status is restart_required: follow the message (usually restart-app), then retry. If status is service_stale: the app is already injected, so restarting it cannot help \u2014 restart the tool-server (\`argent server stop && argent server start --detach\`) and retry. If the same status comes back after that restart, stop restarting: follow the message, which names the terminal fallback. If status is connect_pending: the app is injected and still connecting \u2014 do not restart it, wait a few seconds and retry. If status is init_failed: the simulator's native-devtools environment could not be initialised \u2014 follow the message (re-boot the simulator) rather than retrying this tool.
+A not-connected or not-running app comes back as one of those statuses rather than a failure. Failures are separate: an Apple system app is rejected outright (terminal \u2014 never retry it), and the hierarchy query itself can error or time out.`,
   zodSchema: zodSchema5,
   services: (params) => ({
     nativeDevtools: nativeDevtoolsRef(resolveDevice(params.udid))
@@ -117435,9 +117611,12 @@ Returns a flat list of accessibility leaf elements with:
 This is a low-level native inspection tool. The normalized fields are intended to help
 with backend migration work, but the public describe contract is still separate.
 
-Useful for evaluating or debugging the lower-level native data that powers the public describe tool.
+Use when you are evaluating or debugging the lower-level native data behind the public
+describe tool, or when you need its raw point-space geometry rather than describe's
+normalized contract.
 
-If status is restart_required: call restart-app then retry.`,
+If status is restart_required: follow the message (usually restart-app), then retry. If status is service_stale: the app is already injected, so restarting it cannot help \u2014 restart the tool-server (\`argent server stop && argent server start --detach\`) and retry. If the same status comes back after that restart, stop restarting: follow the message, which names the terminal fallback. If status is connect_pending: the app is injected and still connecting \u2014 do not restart it, wait a few seconds and retry. If status is init_failed: the simulator's native-devtools environment could not be initialised \u2014 follow the message (re-boot the simulator) rather than retrying this tool.
+A not-connected or not-running app comes back as one of those statuses rather than a failure. Failures are separate: an Apple system app is rejected outright (terminal \u2014 never retry it), and the screen query itself can error or time out.`,
   zodSchema: zodSchema6,
   services: (params) => ({
     nativeDevtools: nativeDevtoolsRef(resolveDevice(params.udid))
@@ -117504,10 +117683,19 @@ var nativeViewAtPointTool = {
 Unlike native-user-interactable-view-at-point, this ignores userInteractionEnabled,
 so it answers "what is visually here?" rather than "what would receive the touch?".
 
+Use when a screenshot shows something the accessibility tree does not name \u2014 an
+unlabeled icon, a decorative overlay, a custom-drawn cell \u2014 and you need the class,
+identifier or nativeID of whatever draws it.
+
+Returns { status: "ok", view }: the matched view with its class name, frames,
+identifier, label and layer name, its ancestor chain by default, and its subviews on
+request. view is null when nothing is drawn at that point.
+
 IMPORTANT: x and y are raw iOS window coordinates in points, NOT normalized [0,1]
 simulator tap coordinates.
 
-If status is restart_required: call restart-app then retry.`,
+If status is restart_required: follow the message (usually restart-app), then retry. If status is service_stale: the app is already injected, so restarting it cannot help \u2014 restart the tool-server (\`argent server stop && argent server start --detach\`) and retry. If the same status comes back after that restart, stop restarting: follow the message, which names the terminal fallback. If status is connect_pending: the app is injected and still connecting \u2014 do not restart it, wait a few seconds and retry. If status is init_failed: the simulator's native-devtools environment could not be initialised \u2014 follow the message (re-boot the simulator) rather than retrying this tool.
+A not-connected or not-running app comes back as one of those statuses rather than a failure. Failures are separate: an Apple system app is rejected outright (terminal \u2014 never retry it), and the point query itself can error or time out.`,
   zodSchema: zodSchema7,
   services: (params) => ({
     nativeDevtools: nativeDevtoolsRef(resolveDevice(params.udid))
@@ -117580,10 +117768,19 @@ var nativeUserInteractableViewAtPointTool = {
 Unlike native-view-at-point, this respects userInteractionEnabled and is closer to
 UIKit hit-testing semantics.
 
+Use when a tap lands somewhere unexpected or does nothing, to see which control
+UIKit would hand the touch to \u2014 a transparent overlay swallowing it, a parent
+recognizer, a disabled button.
+
+Returns { status: "ok", view }: the hit-test winner with its class name, frames,
+identifier, label and layer name, its ancestor chain by default, and its subviews on
+request. view is null when no touchable view sits under that point.
+
 IMPORTANT: x and y are raw iOS window coordinates in points, NOT normalized [0,1]
 simulator tap coordinates.
 
-If status is restart_required: call restart-app then retry.`,
+If status is restart_required: follow the message (usually restart-app), then retry. If status is service_stale: the app is already injected, so restarting it cannot help \u2014 restart the tool-server (\`argent server stop && argent server start --detach\`) and retry. If the same status comes back after that restart, stop restarting: follow the message, which names the terminal fallback. If status is connect_pending: the app is injected and still connecting \u2014 do not restart it, wait a few seconds and retry. If status is init_failed: the simulator's native-devtools environment could not be initialised \u2014 follow the message (re-boot the simulator) rather than retrying this tool.
+A not-connected or not-running app comes back as one of those statuses rather than a failure. Failures are separate: an Apple system app is rejected outright (terminal \u2014 never retry it), and the point query itself can error or time out.`,
   zodSchema: zodSchema8,
   services: (params) => ({
     nativeDevtools: nativeDevtoolsRef(resolveDevice(params.udid))
@@ -129257,17 +129454,17 @@ function tagExpWithClosingIndex(xmlData, i, closingChar = ">") {
     }
   }
 }
-function findClosingIndex(xmlData, str, i, errMsg3) {
+function findClosingIndex(xmlData, str, i, errMsg4) {
   const closingIndex = xmlData.indexOf(str, i);
   if (closingIndex === -1) {
-    throw new Error(errMsg3);
+    throw new Error(errMsg4);
   } else {
     return closingIndex + str.length - 1;
   }
 }
-function findClosingChar(xmlData, char, i, errMsg3) {
+function findClosingChar(xmlData, char, i, errMsg4) {
   const closingIndex = xmlData.indexOf(char, i);
-  if (closingIndex === -1) throw new Error(errMsg3);
+  if (closingIndex === -1) throw new Error(errMsg4);
   return closingIndex;
 }
 function readTagExp(xmlData, i, removeNSPrefix, closingChar = ">") {
@@ -145259,6 +145456,16 @@ var FULL_HIERARCHY_FIELDS = [
   // request, which just leaves the wait's poll unconfirmed.
   "firstResponder"
 ];
+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.`;
+  }
+  const state3 = await nativeApi.appConnectionState(bundleId).catch(() => "indeterminate");
+  if (state3 === "connected") {
+    return `native devtools reported no connected app while this tree was being read, but ${bundleId} is connected now \u2014 the connection arrived mid-read. Retry: flows resolve selectors against the full view hierarchy native devtools serve.`;
+  }
+  return `${buildAppStateMessage(bundleId, state3)} Flows resolve selectors against the full view hierarchy native devtools serve.`;
+}
 async function queryFullHierarchyTree(registry2, device, launchedNativeApp) {
   let nativeApi;
   try {
@@ -145266,10 +145473,13 @@ async function queryFullHierarchyTree(registry2, device, launchedNativeApp) {
     nativeApi = await registry2.resolveService(ndRef.urn, ndRef.options);
   } catch (err) {
     throw new Error(
-      `native devtools is unavailable (${errMsg(err)}) \u2014 flows resolve selectors against the full view hierarchy it serves`,
+      `native devtools is unavailable (${errMsg2(err)}) \u2014 flows resolve selectors against the full view hierarchy it serves`,
       { 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);
@@ -145281,11 +145491,6 @@ async function queryFullHierarchyTree(registry2, device, launchedNativeApp) {
       throw err;
     }
   }
-  if (await nativeApi.requiresAppRestart(target.bundleId)) {
-    throw new Error(
-      `${target.bundleId} was launched before argent's instrumentation loaded \u2014 relaunch it (launch-app, or a flow \`launch\` step) so the full view hierarchy is readable`
-    );
-  }
   const rawResult = await nativeApi.queryViewHierarchy(
     target.bundleId,
     "ViewHierarchy.getFullHierarchy",
@@ -145305,7 +145510,7 @@ async function queryFullHierarchyTree(registry2, device, launchedNativeApp) {
   const { tree, screen } = adaptFullHierarchy(rawResult);
   return { tree, source: "native-devtools", ...screen ? { screen } : {} };
 }
-function errMsg(err) {
+function errMsg2(err) {
   return err instanceof Error ? err.message : String(err);
 }
 
@@ -145538,15 +145743,23 @@ var REPLAY_TREE_SOURCES = {
   ios: "native-devtools",
   android: "android-devtools"
 };
+function recordedLaunchedApp(session, platform) {
+  for (let i = session.flow.steps.length - 1; i >= 0; i--) {
+    const step = session.flow.steps[i];
+    if (step.kind === "launch") return appIdForPlatform(step.app, platform) ?? void 0;
+  }
+  return void 0;
+}
 function fallbackSourceWarning(source, platform) {
   const expected = REPLAY_TREE_SOURCES[platform];
   if (!expected || source === expected) return void 0;
   return `selector captured from the fallback ${source} tree (${expected} unavailable) \u2014 replay resolves against the full hierarchy, which may not match it`;
 }
-async function captureTapSelector(registry2, udid, point) {
+async function captureTapSelector(registry2, session, udid, point) {
   try {
     const device = resolveDevice(udid);
-    const { tree, source } = await fetchFlowTree(registry2, device);
+    const launched = recordedLaunchedApp(session, device.platform);
+    const { tree, source } = await fetchFlowTree(registry2, device, launched);
     const node = nodeAtPoint(tree, point);
     if (!node) return { warning: "no element found under the tap; kept coordinates (brittle)" };
     const selector = deriveSelector(node);
@@ -145702,7 +145915,7 @@ If a step was recorded by mistake, edit the .yaml to remove it \u2014 against a
       const isTap = params.command === "gesture-tap" && params.delayMs === void 0 && typeof args.udid === "string" && typeof args.x === "number" && typeof args.y === "number";
       let captured;
       if (isTap) {
-        captured = await captureTapSelector(registry2, args.udid, {
+        captured = await captureTapSelector(registry2, session, args.udid, {
           x: args.x,
           y: args.y
         });
@@ -149129,8 +149342,9 @@ var fileInputs3 = [
 ];
 var MAX_RUN_DEPTH = 20;
 var POST_LAUNCH_SETTLE_MS = 1500;
-var NATIVE_READY_TIMEOUT_MS = 15e3;
+var NATIVE_READY_TIMEOUT_MS = NATIVE_DEVTOOLS_CONNECT_BUDGET_MS;
 var NATIVE_READY_POLL_MS = 250;
+var LAUNCH_TO_VERDICT_MS = POST_LAUNCH_SETTLE_MS + NATIVE_READY_TIMEOUT_MS;
 var FOREGROUND_CHANGING_TOOLS = /* @__PURE__ */ new Set([
   "launch-app",
   "restart-app",
@@ -149143,15 +149357,35 @@ async function waitForNativeDevtools(registry2, device, bundleId, signal) {
   try {
     const ref = nativeDevtoolsRef(device);
     api = await registry2.resolveService(ref.urn, ref.options);
-  } catch {
-    return false;
+  } catch (err) {
+    if (!isInjectableBundleId(bundleId)) return null;
+    return `the native-devtools service is unavailable for ${bundleId} (${errMsg3(err)})`;
   }
   const deadline = Date.now() + NATIVE_READY_TIMEOUT_MS;
   for (; ; ) {
-    if (signal?.aborted) return false;
-    if (api.isConnected(bundleId)) return true;
-    if (Date.now() >= deadline) return false;
-    if (!await sleepOrAbort(NATIVE_READY_POLL_MS, signal)) return false;
+    if (signal?.aborted) return null;
+    if (api.isConnected(bundleId)) return null;
+    if (Date.now() >= deadline) break;
+    if (!await sleepOrAbort(NATIVE_READY_POLL_MS, signal)) return null;
+  }
+  if (!isInjectableBundleId(bundleId)) return null;
+  const state3 = await api.appConnectionState(bundleId).catch(() => "indeterminate");
+  if (state3 === "connected") return null;
+  return flowLaunchGateReason(bundleId, state3);
+}
+function flowLaunchGateReason(bundleId, state3) {
+  const measured = buildAppStateMessage(bundleId, state3);
+  switch (state3) {
+    case "not_running":
+      return `${bundleId} was relaunched by this step and is no longer running ${LAUNCH_TO_VERDICT_MS} ms later, so it exited after launch rather than failing to connect. Re-running the flow repeats the same launch: start it by hand (launch-app, then describe or screenshot) to see the crash or early exit first.`;
+    case "stale_process":
+      return `${measured} This step already relaunched it, so the process it measured predates whatever the relaunch would have given it \u2014 re-run the flow to launch again. If it lands here twice, the simulator's launchd environment is not holding argent's instrumentation: re-boot the device (boot-device with force) before re-running.`;
+    case "unregistered":
+      return `${measured} A cold start slower than the ${LAUNCH_TO_VERDICT_MS} ms this step waited reads the same way \u2014 if that is likely, re-run the flow to relaunch and wait again before restarting anything.`;
+    case "connecting":
+      return `${measured} This step launched it ${LAUNCH_TO_VERDICT_MS} ms before that reading, so the process being measured started after the step's own launch \u2014 something relaunched it in between. Re-run the flow once the app is settled.`;
+    case "indeterminate":
+      return `${measured} This step already performed that one restart, so re-run the flow at most once more before restarting the tool-server rather than the app.`;
   }
 }
 async function waitForVegaAutomation(device, signal) {
@@ -149178,9 +149412,9 @@ async function androidDevtoolsReady(registry2, device) {
 }
 async function treeSourceGate(registry2, device, bundleId, signal) {
   if (device.platform === "ios" && !signal?.aborted) {
-    const connected = await waitForNativeDevtools(registry2, device, bundleId, signal);
-    if (!connected && !signal?.aborted) {
-      return `could not connect to native devtools for ${bundleId}. Re-run to relaunch the app and retry. If it keeps failing, a stale or duplicate argent server may be holding the devtools connection \u2014 restart the argent server and try again.`;
+    const reason = await waitForNativeDevtools(registry2, device, bundleId, signal);
+    if (reason !== null && !signal?.aborted) {
+      return `could not connect to native devtools. ${reason}`;
     }
   }
   if (device.platform === "android" && !signal?.aborted) {
@@ -149209,11 +149443,15 @@ async function runLaunch(state3, app) {
       reason: `no app id declared for platform "${device.platform}" \u2014 add a launch entry for it`
     };
   }
+  let restart;
   try {
-    await invokeOnDevice(env, "restart-app", { bundleId });
+    restart = await invokeOnDevice(env, "restart-app", { bundleId });
   } catch (err) {
     if (signal?.aborted) return ABORTED_OUTCOME;
-    return { ok: false, reason: `restart-app failed: ${errMsg2(err)}` };
+    return { ok: false, reason: `restart-app failed: ${errMsg3(err)}` };
+  }
+  if (isNativeDevtoolsBlockResult("restart-app", restart)) {
+    return { ok: false, reason: `restart-app did not start ${bundleId}: ${restart.message}` };
   }
   if (!await sleepOrAbort(POST_LAUNCH_SETTLE_MS, signal)) return ABORTED_OUTCOME;
   const gate = await treeSourceGate(registry2, device, bundleId, signal);
@@ -149247,7 +149485,7 @@ async function runChromiumLaunch(state3, app) {
   } catch (err) {
     return {
       ok: false,
-      reason: `could not attach to chromium instance "${device.id}": ${errMsg2(err)}`
+      reason: `could not attach to chromium instance "${device.id}": ${errMsg3(err)}`
     };
   }
   state3.attachedAppPath = await resolveAppPath(spec.path, state3.flowsDir);
@@ -149314,7 +149552,7 @@ function singleInstanceLockHint(suspects) {
   return `A clean exit before CDP comes up is the signature of a single-instance lock \u2014 an already-running copy of the app quits the new one at startup. ${clauses.join(" ")}`;
 }
 async function chromiumBootFailureReason(state3, err) {
-  const base = `could not boot the chromium app: ${errMsg2(err)}`;
+  const base = `could not boot the chromium app: ${errMsg3(err)}`;
   if (!singleInstanceLockSignal(err)) return base;
   return `${base} ${singleInstanceLockHint(await liveLockSuspects(state3))}`;
 }
@@ -149597,7 +149835,7 @@ function resolveOpts(params) {
 function hoistedBootFailure(err) {
   const signal = singleInstanceLockSignal(err);
   if (!signal) return err;
-  return wrapFailure(err, signal, `${errMsg2(err)} ${singleInstanceLockHint(NO_LOCK_SUSPECTS)}`);
+  return wrapFailure(err, signal, `${errMsg3(err)} ${singleInstanceLockHint(NO_LOCK_SUSPECTS)}`);
 }
 function pinnedToChromium(device) {
   return device !== void 0 && resolveDevice(device).platform === "chromium";
@@ -150017,7 +150255,7 @@ async function execRunStep(state3, step, scope) {
   try {
     fragment = parseFlow(await fs49.readFile(canonical, "utf8"));
   } catch (err) {
-    return fail(`could not load fragment "${target}": ${errMsg2(err)}`);
+    return fail(`could not load fragment "${target}": ${errMsg3(err)}`);
   }
   pushReport(state3, {
     index,
@@ -150072,7 +150310,7 @@ async function execLeafStep(state3, step, index, scope) {
           ...r.warning !== void 0 ? { warning: r.warning } : {}
         };
       } catch (err) {
-        return { ...base, status: "error", reason: errMsg2(err) };
+        return { ...base, status: "error", reason: errMsg3(err) };
       }
     }
     case "wait": {
@@ -150101,7 +150339,7 @@ async function execLeafStep(state3, step, index, scope) {
           artifacts: r.artifacts
         };
       } catch (err) {
-        return { ...base, status: "error", reason: errMsg2(err) };
+        return { ...base, status: "error", reason: errMsg3(err) };
       }
     }
     case "tool": {
@@ -150157,16 +150395,31 @@ async function execLeafStep(state3, step, index, scope) {
             args
           };
         }
+        if (isNativeDevtoolsBlockResult(step.name, result)) {
+          return {
+            ...base,
+            status: "fail",
+            tool: step.name,
+            reason: `${step.name} did not run (${result.status}): ${result.message}`,
+            result,
+            outputHint,
+            args
+          };
+        }
+        if (step.name === "launch-app" || step.name === "restart-app") {
+          const launched = args.bundleId;
+          if (typeof launched === "string") state3.launchedNativeApp = launched;
+        }
         return { ...base, status: "pass", tool: step.name, result, outputHint, args };
       } catch (err) {
-        return { ...base, status: "error", tool: step.name, reason: errMsg2(err) };
+        return { ...base, status: "error", tool: step.name, reason: errMsg3(err) };
       }
     }
     default:
       return { ...base, status: "error", reason: `unsupported step kind` };
   }
 }
-function errMsg2(err) {
+function errMsg3(err) {
   return err instanceof Error ? err.message : String(err);
 }
 async function resolveFlowSource(params, fileInput, flowPathInput) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.21.0",
+  "version": "0.21.1-next.0",
   "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/reliability-and-recovery.md

@@ -43,7 +43,7 @@ The full iOS flow tree exists only for an app launched by Argent with instrument
 
 1. If Metro, Expo, Xcode, an icon, or a prior process launched the app, call `restart-app`. Restore the source screen and retry capture. `launch-app` can only foreground the existing process.
 2. Tap capture does **not** wait for that connection. It makes one tree read and turns any failure straight into the kept-coordinates warning. A recording-time `restart-app` returns before the devtools connection opens, so the first tap after a restart can warn transiently. Re-record that tap once before escalating; only a warning that survives the retry is evidence of a real fault.
-3. If the warning survives, call `native-devtools-status` with the same UDID and bundle id. If `requiresRestart` is true, restart once and check again.
+3. If the warning survives, call `native-devtools-status` with the same UDID and bundle id and follow its `message`, which names the one action that helps and says when to stop. `requiresRestart` covers only the states a fresh process fixes: an `unregistered` or `connecting` app reports it false, because it already launched under the terms a restart would recreate.
 4. If an injectable app remains disconnected, call `stop-all-simulator-servers` once, **scoped to `devices: [<this simulator's UDID>]`**. One tool-server serves every agent on this Argent install, so an unscoped call tears down their devices too. This does not change app or account data. Then restart and check status again.
 5. If it still fails, report an instrumentation blocker. Do not replace selectors with coordinates in a QA flow.
 
@@ -53,20 +53,20 @@ 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 cannot load the instrumentation, and nothing in the launch path exempts them. A `launch:` step on iOS always waits for the devtools connection, so for one of these apps it spends that budget, fails, and every later step is skipped.
+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.
 
-**Never give such a flow a `launch:` step.** Start it with a raw `tool: restart-app`, which terminates and relaunches without the readiness gate. Accept that the result is a **fragment**: its first non-echo step is not `launch:`, so the runner never classifies it as e2e. 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 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:
 
 - Raw `tool: await-ui-element` accessibility checks.
 - Point taps or long-presses derived from `describe`, each named by an echo.
 - A point focus tap plus a raw text-only `keyboard` with `delayMs: 500`, and a second raw `keyboard` with `key: "enter"` to submit.
 - Raw swipes with `settle: true` because `scroll-to` needs the missing flow tree. Momentum-free scrolling keeps later coordinate taps valid.
 
-Every point tap or long-press in such a flow passes **carrying a warning**. The app loads no instrumentation, so every tree read fails and each [selector-less gesture](flow-yaml.md#directives) dispatches unsettled. Nothing here repairs it. Accept the warnings, read each green as "the gesture was sent, not that it landed", and put an explicit `wait:` or a raw `tool: await-ui-element` before a gesture that follows a transition. Raw `tool:` steps never take that settle, so they never warn.
+Every point tap or long-press in such a flow passes **carrying a warning** for as long as the app serves no tree: each [selector-less gesture](flow-yaml.md#directives) dispatches unsettled. Nothing here repairs it. Accept the warnings, read each green as "the gesture was sent, not that it landed", and put an explicit `wait:` or a raw `tool: await-ui-element` before a gesture that follows a transition. Raw `tool:` steps never take that settle, so they never warn.
 
 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.
 
-The same fragment fallback covers a normally injectable app that is broken in the environment: raw `restart-app` in place of `launch:` still makes a self-resetting flow. Either way it is not e2e and 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 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.
 
 ## Tree source recovery on Android, Chromium, and Vega
 

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

@@ -106,7 +106,7 @@ Read the exact error and choose the action that matches it:
 - `describe` succeeds but is not detailed enough for a React Native app:
   use `debugger-component-tree` next.
 - You need app-scoped inspection with full UIKit properties (`accessibilityIdentifier`, `viewClassName`):
-  use `native-describe-screen` with an explicit `bundleId`. This requires native devtools (dylib) injection — call `restart-app` first if needed.
+  use `native-describe-screen` with an explicit `bundleId`. This requires native devtools (dylib) injection.
 - You already have a candidate point and want to confirm what would actually receive touch:
   use `native-user-interactable-view-at-point`. Use `native-view-at-point` when you want the visually deepest view instead of the hit-test target.