@swmansion/argent 0.20.1-next.7 → 0.20.1-next.9

package/dist/tool-server.cjs

@@ -16776,10 +16776,10 @@ var require_browser = __commonJS({
     exports2.useColors = useColors;
     exports2.storage = localstorage();
     exports2.destroy = /* @__PURE__ */ (() => {
-      let warned = false;
+      let warned2 = false;
       return () => {
-        if (!warned) {
-          warned = true;
+        if (!warned2) {
+          warned2 = true;
           console.warn("Instance method `debug.destroy()` is deprecated and no longer does anything. It will be removed in the next major version of `debug`.");
         }
       };
@@ -109158,12 +109158,16 @@ function settleWithin(p, ms, signal) {
     };
     p.then(
       (value) => finish({ type: "value", value }),
-      (err) => finish({ type: "error", error: err instanceof Error ? err.message : String(err) })
+      (err) => {
+        const cause = err instanceof Error ? err : new Error(String(err));
+        finish({ type: "error", error: cause.message, cause });
+      }
     );
     if (signal?.aborted) return finish({ type: "aborted" });
     const onAbort = () => finish({ type: "aborted" });
     signal?.addEventListener("abort", onAbort, { once: true });
     teardown.push(() => signal?.removeEventListener("abort", onAbort));
+    if (ms === void 0) return;
     const timer = setTimeout(() => finish({ type: "timeout" }), Math.max(0, ms));
     teardown.push(() => clearTimeout(timer));
   });
@@ -133794,89 +133798,130 @@ var ARGENT_PROFILER_PREFIX = "__argent_";
 function isArgentProfilerFunction(name) {
   return name.startsWith(ARGENT_PROFILER_PREFIX);
 }
-function buildCpuSampleIndex(cpuProfile, firstCommitTimestampMs) {
+function buildCpuSampleIndex(cpuProfile) {
   const { nodes, samples, timeDeltas, startTime, endTime } = cpuProfile;
   const nodeMap = /* @__PURE__ */ new Map();
   for (const node of nodes) {
     nodeMap.set(node.id, node);
   }
-  const cpuStartMs = startTime / 1e3;
-  let clockOffsetMs = 0;
-  if (firstCommitTimestampMs !== null && firstCommitTimestampMs > 0) {
-    const diff = firstCommitTimestampMs - cpuStartMs;
-    if (Math.abs(diff) > 1e3) {
-      clockOffsetMs = diff;
-    }
-  }
   const timestampsMs = new Float64Array(samples.length);
-  let accumulatedUs = startTime;
+  const intervalStartsMs = new Float64Array(samples.length);
+  let accumulatedUs = 0;
   for (let i = 0; i < samples.length; i++) {
-    accumulatedUs += timeDeltas[i] ?? 0;
-    timestampsMs[i] = accumulatedUs / 1e3 + clockOffsetMs;
+    const raw = timeDeltas[i];
+    const delta = Number.isFinite(raw) && (raw ?? 0) >= 0 ? raw : 0;
+    intervalStartsMs[i] = accumulatedUs / 1e3;
+    accumulatedUs += delta;
+    timestampsMs[i] = accumulatedUs / 1e3;
   }
   return {
+    childToParent: buildChildToParent(nodeMap),
     timestampsMs,
+    intervalStartsMs,
     sampleNodeIds: samples,
     nodeMap,
     durationMs: (endTime - startTime) / 1e3
   };
 }
+var IDLE_FRAME_NAMES = /* @__PURE__ */ new Set(["(idle)", "(program)", "(root)", "[idle]", "[root]"]);
+function isIdleFrame(name) {
+  return !name || IDLE_FRAME_NAMES.has(name);
+}
 function queryCpuWindow(index, startMs, endMs, topN2 = 5) {
-  const { timestampsMs, sampleNodeIds, nodeMap } = index;
+  const { timestampsMs, intervalStartsMs, sampleNodeIds, nodeMap } = index;
+  const n = timestampsMs.length;
+  const sampleRangeMs = {
+    start: n > 0 ? intervalStartsMs[0] : 0,
+    end: n > 0 ? timestampsMs[n - 1] : 0
+  };
+  const empty2 = {
+    hotspots: [],
+    samplesInWindow: 0,
+    coveredMs: 0,
+    idleMs: 0,
+    sampleRangeMs,
+    medianIntervalMs: 0,
+    maxIntervalMs: 0
+  };
+  if (n === 0) return empty2;
   let lo = 0;
-  let hi = timestampsMs.length;
+  let hi = n;
   while (lo < hi) {
     const mid = lo + hi >>> 1;
     if (timestampsMs[mid] < startMs) lo = mid + 1;
     else hi = mid;
   }
-  const selfHits = /* @__PURE__ */ new Map();
-  let totalSamples = 0;
-  for (let i = lo; i < timestampsMs.length; i++) {
-    if (timestampsMs[i] > endMs) break;
+  const selfMsByNode = /* @__PURE__ */ new Map();
+  const intervals = [];
+  let samplesInWindow = 0;
+  let coveredMs = 0;
+  let idleMs = 0;
+  let maxIntervalMs = 0;
+  for (let i = lo; i < n; i++) {
+    const from2 = intervalStartsMs[i];
+    if (from2 > endMs) break;
+    const overlap = Math.min(endMs, timestampsMs[i]) - Math.max(startMs, from2);
+    if (overlap <= 0) continue;
+    samplesInWindow++;
+    coveredMs += overlap;
+    intervals.push(timestampsMs[i] - from2);
+    if (timestampsMs[i] - from2 > maxIntervalMs) maxIntervalMs = timestampsMs[i] - from2;
     const nodeId = sampleNodeIds[i];
-    selfHits.set(nodeId, (selfHits.get(nodeId) ?? 0) + 1);
-    totalSamples++;
-  }
-  if (totalSamples === 0) return [];
-  const windowDurationMs = endMs - startMs;
-  const avgIntervalMs = totalSamples > 1 ? windowDurationMs / totalSamples : 1;
-  const childToParent = /* @__PURE__ */ new Map();
-  for (const node of nodeMap.values()) {
-    for (const childId of node.children ?? []) {
-      childToParent.set(childId, node.id);
+    const node = nodeMap.get(nodeId);
+    if (isIdleFrame(node?.callFrame.functionName)) {
+      idleMs += overlap;
+      continue;
     }
+    selfMsByNode.set(nodeId, (selfMsByNode.get(nodeId) ?? 0) + overlap);
   }
-  const totalHits = /* @__PURE__ */ new Map();
-  for (const [nodeId, hits] of selfHits) {
-    totalHits.set(nodeId, (totalHits.get(nodeId) ?? 0) + hits);
+  if (samplesInWindow === 0) return { ...empty2, sampleRangeMs };
+  intervals.sort((a, b) => a - b);
+  const medianIntervalMs = intervals[Math.floor(intervals.length / 2)] ?? 0;
+  const childToParent = index.childToParent ?? buildChildToParent(nodeMap);
+  const totalMsByNode = /* @__PURE__ */ new Map();
+  for (const [nodeId, ms] of selfMsByNode) {
+    totalMsByNode.set(nodeId, (totalMsByNode.get(nodeId) ?? 0) + ms);
     let current = nodeId;
+    const seen = /* @__PURE__ */ new Set([current]);
     while (childToParent.has(current)) {
       const parent = childToParent.get(current);
-      totalHits.set(parent, (totalHits.get(parent) ?? 0) + hits);
+      if (seen.has(parent)) break;
+      seen.add(parent);
+      totalMsByNode.set(parent, (totalMsByNode.get(parent) ?? 0) + ms);
       current = parent;
     }
   }
   const entries = [];
-  for (const [nodeId, hits] of selfHits) {
+  for (const [nodeId, ms] of selfMsByNode) {
     const node = nodeMap.get(nodeId);
     if (!node) continue;
     const name = node.callFrame.functionName;
-    if (!name || name === "(idle)" || name === "(program)" || name === "(root)" || name === "[idle]" || name === "[root]")
-      continue;
     if (isArgentProfilerFunction(name)) continue;
-    const selfMs = Math.round(hits * avgIntervalMs * 100) / 100;
-    const totalMs = Math.round((totalHits.get(nodeId) ?? hits) * avgIntervalMs * 100) / 100;
     entries.push({
       name,
-      selfMs,
-      totalMs,
+      selfMs: Math.round(ms * 100) / 100,
+      totalMs: Math.round((totalMsByNode.get(nodeId) ?? ms) * 100) / 100,
       url: node.callFrame.url || void 0,
       lineNumber: node.callFrame.lineNumber >= 0 ? node.callFrame.lineNumber : void 0
     });
   }
   entries.sort((a, b) => b.selfMs - a.selfMs);
-  return entries.slice(0, topN2);
+  return {
+    hotspots: entries.slice(0, topN2),
+    samplesInWindow,
+    coveredMs,
+    idleMs,
+    sampleRangeMs,
+    medianIntervalMs,
+    maxIntervalMs
+  };
+}
+function buildChildToParent(nodeMap) {
+  const childToParent = /* @__PURE__ */ new Map();
+  for (const node of nodeMap.values()) {
+    for (const childId of node.children ?? []) childToParent.set(childId, node.id);
+  }
+  return childToParent;
 }
 function correlateCpuWithCommits(summaries, index, topNPerCommit = 5) {
   if (!index) return summaries;
@@ -133884,28 +133929,35 @@ function correlateCpuWithCommits(summaries, index, topNPerCommit = 5) {
     if (summary.isMargin) return summary;
     const startMs = summary.timestampMs;
     const endMs = summary.timestampMs + summary.totalRenderMs;
-    const hotspots = queryCpuWindow(index, startMs, endMs, topNPerCommit);
+    const { hotspots } = queryCpuWindow(index, startMs, endMs, topNPerCommit);
     if (hotspots.length === 0) return summary;
     return { ...summary, cpuHotspots: hotspots };
   });
 }
 function serializeCpuSampleIndex(index) {
   return {
+    version: 2,
     timestampsMs: Array.from(index.timestampsMs),
+    intervalStartsMs: Array.from(index.intervalStartsMs),
     sampleNodeIds: index.sampleNodeIds,
     nodes: [...index.nodeMap.values()],
     durationMs: index.durationMs
   };
 }
 function deserializeCpuSampleIndex(raw) {
+  if (raw?.version !== 2 || !Array.isArray(raw.timestampsMs) || !Array.isArray(raw.nodes)) {
+    throw new Error("unsupported CPU sample index format");
+  }
   const nodeMap = /* @__PURE__ */ new Map();
   for (const node of raw.nodes) {
     nodeMap.set(node.id, node);
   }
   return {
     timestampsMs: new Float64Array(raw.timestampsMs),
+    intervalStartsMs: new Float64Array(raw.intervalStartsMs ?? []),
     sampleNodeIds: raw.sampleNodeIds,
     nodeMap,
+    childToParent: buildChildToParent(nodeMap),
     durationMs: raw.durationMs
   };
 }
@@ -134208,8 +134260,7 @@ async function runPipeline(input, options) {
     hotCommitIndices,
     input.sessionMeta.unattributedByCommit
   );
-  const firstCommitTs = preprocessed.length > 0 ? preprocessed[0].timestamp : null;
-  const cpuSampleIndex = input.flamegraph ? buildCpuSampleIndex(input.flamegraph, firstCommitTs) : null;
+  const cpuSampleIndex = input.flamegraph ? buildCpuSampleIndex(input.flamegraph) : null;
   const hotCommitSummaries = correlateCpuWithCommits(rawHotCommitSummaries, cpuSampleIndex);
   const preprocessedCommitTree = { ...input.commitTree, commits: preprocessed };
   const reduceOutput = reduce(
@@ -140615,8 +140666,12 @@ init_zod();
 init_src();
 var import_fs18 = require("fs");
 var timeWindowSchema = external_exports.object({
-  start: external_exports.coerce.number().describe("Start of window in ms (performance.now clock)"),
-  end: external_exports.coerce.number().describe("End of window in ms (performance.now clock)")
+  start: external_exports.coerce.number().describe(
+    "Start of window in ms since profiling started \u2014 the same clock profiler-commit-query prints"
+  ),
+  end: external_exports.coerce.number().describe(
+    "End of window in ms since profiling started \u2014 the same clock profiler-commit-query prints"
+  )
 });
 var zodSchema53 = external_exports.object({
   port: external_exports.coerce.number().default(8081).describe("Metro server port"),
@@ -140626,7 +140681,9 @@ var zodSchema53 = external_exports.object({
   mode: external_exports.enum(["top_functions", "time_window", "call_tree", "component_cpu"]).describe(
     "Query mode: top_functions (global hotspots), time_window (CPU in a time range), call_tree (callers/callees of a function), component_cpu (CPU during a component's commits)"
   ),
-  time_window_ms: timeWindowSchema.optional().describe("Time window filter for time_window mode (ms, performance.now clock)"),
+  time_window_ms: timeWindowSchema.optional().describe(
+    "Time window filter for time_window mode (ms since profiling started \u2014 the same clock profiler-commit-query prints)"
+  ),
   component_name: external_exports.string().optional().describe("Component name for component_cpu mode"),
   function_name: external_exports.string().optional().describe("Function name for call_tree mode"),
   top_n: external_exports.coerce.number().int().positive().default(15).describe("Number of results to return (default 15)"),
@@ -140659,31 +140716,60 @@ async function getIndex(sessionPaths) {
   }
   const cpuProfile = await readCpuProfile(sessionPaths.cpuProfilePath);
   let commitTree = null;
-  let firstCommitTs = null;
   if (sessionPaths.commitsPath) {
     const onDisk = await readCommitTree(sessionPaths.commitsPath);
     commitTree = { commits: onDisk.commits };
-    firstCommitTs = onDisk.commits[0]?.timestamp ?? null;
   }
-  return { index: buildCpuSampleIndex(cpuProfile, firstCommitTs), commitTree };
+  return { index: buildCpuSampleIndex(cpuProfile), commitTree };
+}
+function explainEmptyWindow(res, startMs, endMs) {
+  const range = `${res.sampleRangeMs.start.toFixed(1)}\u2013${res.sampleRangeMs.end.toFixed(1)}ms`;
+  const window2 = `${startMs.toFixed(1)}\u2013${endMs.toFixed(1)}ms`;
+  if (res.sampleRangeMs.end === 0 && res.samplesInWindow === 0) {
+    return "_The CPU profile contains no samples. Sampling produced no data for this session \u2014 that is a capture failure, not a measurement of idleness._";
+  }
+  if (endMs < res.sampleRangeMs.start || startMs > res.sampleRangeMs.end) {
+    return `_No CPU samples exist in ${window2} \u2014 that is outside the recorded sample range (${range}). This is a coverage gap, not a measurement: nothing can be concluded about CPU cost here. Sample times are ms since profiling started, the same clock \`profiler-commit-query\` prints._`;
+  }
+  if (res.samplesInWindow > 0) {
+    return `_${res.samplesInWindow} sample(s) covering ${res.coveredMs.toFixed(1)}ms fell inside ${window2}, and all of them were idle \u2014 the JS thread was not executing during this window. Native or UI-thread work would not appear here; use \`native-profiler-start\` for that._`;
+  }
+  return `_No CPU samples fell inside ${window2} (${(endMs - startMs).toFixed(1)}ms wide), although it lies within the recorded range (${range}). The sampler runs roughly every ${res.medianIntervalMs > 0 ? res.medianIntervalMs.toFixed(1) : "13"}ms, so a window this narrow can contain none at all. **Absence of samples is not evidence that this commit was cheap.** Widen the window, or use \`mode=component_cpu\`._`;
+}
+function coverageNote(res, startMs, endMs) {
+  const widthMs = endMs - startMs;
+  const lines = [
+    `**Window:** ${startMs.toFixed(1)}ms \u2192 ${endMs.toFixed(1)}ms (${widthMs.toFixed(1)}ms)`,
+    `**Samples:** ${res.samplesInWindow} covering ${res.coveredMs.toFixed(1)}ms` + (res.idleMs > 0 ? `, of which ${res.idleMs.toFixed(1)}ms idle` : "") + ` \u2014 sampling interval ~${res.medianIntervalMs.toFixed(1)}ms. Self-times sum to sampled coverage, not to the window width.`
+  ];
+  if (widthMs > 0 && widthMs < 3 * res.medianIntervalMs) {
+    lines.push(
+      `> This window is narrower than ~3 sampling intervals, so every figure carries \xB11 sample (\u2248${res.medianIntervalMs.toFixed(1)}ms).`
+    );
+  }
+  if (res.maxIntervalMs > 50 && res.maxIntervalMs > 5 * res.medianIntervalMs) {
+    lines.push(
+      `> The sampler stalled for ${res.maxIntervalMs.toFixed(1)}ms inside this window; that whole gap is attributed to whichever function was caught by the sample that ended it.`
+    );
+  }
+  return lines.join("\n\n");
 }
 function renderTopFunctions(index, topN2, startMs, endMs) {
-  const windowStart = startMs ?? index.timestampsMs[0];
-  const windowEnd = endMs ?? index.timestampsMs[index.timestampsMs.length - 1];
-  const hotspots = queryCpuWindow(index, windowStart, windowEnd, topN2);
-  if (hotspots.length === 0) return "_No CPU hotspots found in the specified range._";
+  const windowStart = startMs ?? index.intervalStartsMs[0] ?? 0;
+  const windowEnd = endMs ?? index.timestampsMs[index.timestampsMs.length - 1] ?? 0;
+  const res = queryCpuWindow(index, windowStart, windowEnd, topN2);
+  if (res.hotspots.length === 0) return explainEmptyWindow(res, windowStart, windowEnd);
   const header = "| Function | Self (ms) | Total (ms) | Location |";
   const sep7 = "|---|---|---|---|";
-  const rows = hotspots.map((hs) => {
+  const rows = res.hotspots.map((hs) => {
     const loc = hs.url ? `${shortenUrl(hs.url)}${hs.lineNumber != null ? `:${hs.lineNumber}` : ""}` : "\u2014";
     return `| \`${hs.name}\` | ${hs.selfMs} | ${hs.totalMs} | ${loc} |`;
   });
-  const rangeNote = startMs != null ? `**Window:** ${startMs.toFixed(1)}ms \u2192 ${endMs.toFixed(1)}ms
-
-` : "";
   return `## CPU Hotspots
 
-${rangeNote}${header}
+${coverageNote(res, windowStart, windowEnd)}
+
+${header}
 ${sep7}
 ${rows.join("\n")}`;
 }
@@ -140813,7 +140899,7 @@ function renderComponentCpu(index, commitTree, componentName, topN2) {
   }
   const aggregated = /* @__PURE__ */ new Map();
   for (const window2 of commitWindows.values()) {
-    const hotspots = queryCpuWindow(index, window2.start, window2.end, 50);
+    const { hotspots } = queryCpuWindow(index, window2.start, window2.end, 50);
     for (const hs of hotspots) {
       const existing = aggregated.get(hs.name);
       if (existing) {
@@ -140867,6 +140953,10 @@ Requires react-profiler-stop (and ideally react-profiler-analyze) to have been c
 Modes:
 - top_functions: Global CPU hotspots ranked by self-time. Optional time_window_ms to filter.
 - time_window: CPU breakdown for a specific time range (e.g. during a slow commit or hang).
+
+Self-times are the summed sampling intervals of the samples that landed in the window, so they
+measure sampled coverage rather than the window's width and do not change if you widen the query.
+Every table states how many samples it covers and how much of that was idle.
 - call_tree: For a given function_name, show its callees and optionally callers.
 - component_cpu: For a given component_name, aggregate CPU activity across all its commits.
 Use when investigating JS CPU hotspots or correlating CPU cost with specific components.
@@ -140952,8 +141042,12 @@ Fails if no CPU profile is stored \u2014 run react-profiler-stop first.`,
 init_zod();
 init_src();
 var timeRangeSchema = external_exports.object({
-  start: external_exports.coerce.number().describe("Start of range in ms (performance.now clock)"),
-  end: external_exports.coerce.number().describe("End of range in ms (performance.now clock)")
+  start: external_exports.coerce.number().describe(
+    "Start of range in ms since profiling started \u2014 the same clock profiler-commit-query prints"
+  ),
+  end: external_exports.coerce.number().describe(
+    "End of range in ms since profiling started \u2014 the same clock profiler-commit-query prints"
+  )
 });
 var zodSchema54 = external_exports.object({
   port: external_exports.coerce.number().default(8081).describe("Metro server port"),
@@ -145165,19 +145259,18 @@ async function queryVegaTree(device) {
 
 // ../tool-server/src/tools/flows/flow-tree.ts
 async function fetchFlowTree(registry2, device, launchedNativeApp) {
-  if (device.platform === "ios") {
-    return queryFullHierarchyTree(registry2, device, launchedNativeApp);
-  }
-  if (device.platform === "android") {
-    return queryAndroidFullHierarchy(registry2, device);
-  }
-  if (device.platform === "chromium") {
-    return queryChromiumTree(registry2, device);
-  }
-  if (device.platform === "vega") {
-    return queryVegaTree(device);
-  }
-  return fetchTree(registry2, device);
+  const source = FLOW_TREE_SOURCES[device.platform];
+  if (!source) return fetchTree(registry2, device);
+  return source(registry2, device, launchedNativeApp);
+}
+var FLOW_TREE_SOURCES = {
+  ios: (registry2, device, launchedNativeApp) => queryFullHierarchyTree(registry2, device, launchedNativeApp),
+  android: (registry2, device) => queryAndroidFullHierarchy(registry2, device),
+  chromium: (registry2, device) => queryChromiumTree(registry2, device),
+  vega: (_registry, device) => queryVegaTree(device)
+};
+function supportsFlowTree(platform) {
+  return FLOW_TREE_SOURCES[platform] !== void 0;
 }
 
 // ../tool-server/src/tools/flows/flow-add-step.ts
@@ -145511,11 +145604,16 @@ function runSequenceOutcome(result) {
   }
   return void 0;
 }
+var NESTED_ORCHESTRATORS = /* @__PURE__ */ new Map([
+  [FLOW_EXECUTE_TOOL_ID, flowExecuteOutcome],
+  [RUN_SEQUENCE_TOOL_ID, runSequenceOutcome]
+]);
+function isNestedOrchestratorTool(tool) {
+  return NESTED_ORCHESTRATORS.has(tool);
+}
 function nestedOrchestratorOutcome(tool, result) {
   if (!isRecord(result)) return void 0;
-  if (tool === FLOW_EXECUTE_TOOL_ID) return flowExecuteOutcome(result);
-  if (tool === RUN_SEQUENCE_TOOL_ID) return runSequenceOutcome(result);
-  return void 0;
+  return NESTED_ORCHESTRATORS.get(tool)?.(result);
 }
 
 // ../tool-server/src/tools/flows/flow-pixels.ts
@@ -145659,6 +145757,7 @@ var FOCUS_REPORTING_SOURCES = /* @__PURE__ */ new Set([
 ]);
 var SETTLE_POLL_MS = 250;
 var SETTLE_TIMEOUT_MS = 3e3;
+var SETTLE_MIN_READS = 2;
 var MAX_SCROLL_ITERATIONS = 25;
 var SCROLL_INCREMENT = 0.5;
 var MIN_SCROLL_INCREMENT = 0.05;
@@ -145709,19 +145808,34 @@ function flowSelectorToFrame(tree, sel) {
   }
   return void 0;
 }
-async function settleTree(env) {
+function provenTreeOutage(env) {
+  const proven = env.treeOutage?.proven;
+  return proven && proven.deviceId === env.device.id ? proven.error : void 0;
+}
+function readFlowTree(env) {
+  return fetchFlowTree(env.registry, env.device, env.launchedNativeApp).then((data) => {
+    if (env.treeOutage) env.treeOutage.proven = void 0;
+    return data;
+  });
+}
+async function settleTree(env, opts = {}) {
   const deadline = Date.now() + SETTLE_TIMEOUT_MS;
   let prevFp;
   let prevTree;
   let lastError;
+  let reads = 0;
   for (; ; ) {
     if (env.signal?.aborted) return void 0;
+    const proven = provenTreeOutage(env);
+    if (opts.skipProvenOutage && proven) throw proven;
+    const read = await settleWithin(readFlowTree(env), void 0, env.signal);
     let tree;
-    try {
-      ({ tree } = await fetchFlowTree(env.registry, env.device, env.launchedNativeApp));
-    } catch (err) {
-      lastError = err instanceof Error ? err : new Error(String(err));
+    if (read.type === "value") {
+      tree = read.value.tree;
+    } else if (read.type === "error") {
+      lastError = read.cause;
     }
+    reads += 1;
     if (env.signal?.aborted) return void 0;
     if (tree !== void 0) {
       const fp = treeFingerprint(tree);
@@ -145730,7 +145844,11 @@ async function settleTree(env) {
       prevTree = tree;
     }
     if (Date.now() >= deadline) {
-      if (prevTree === void 0 && lastError !== void 0) throw lastError;
+      if (reads < SETTLE_MIN_READS) continue;
+      if (prevTree === void 0 && lastError !== void 0) {
+        if (env.treeOutage) env.treeOutage.proven = { deviceId: env.device.id, error: lastError };
+        throw lastError;
+      }
       return prevTree;
     }
     if (!await sleepOrAbort(SETTLE_POLL_MS, env.signal)) return void 0;
@@ -145779,7 +145897,7 @@ async function waitForFocus(env, into, tappedFrame) {
   for (; ; ) {
     if (env.signal?.aborted) return;
     try {
-      const { tree, source } = await fetchFlowTree(env.registry, env.device, env.launchedNativeApp);
+      const { tree, source } = await readFlowTree(env);
       if (!FOCUS_REPORTING_SOURCES.has(source)) return;
       const target = flowSelectorToFrame(tree, into) ?? tappedFrame;
       if (collectFocused(tree, []).some((n) => framesOverlap(n.frame, target))) return;
@@ -145892,6 +146010,25 @@ async function runDirective(env, step) {
       return runRotate(env, step);
   }
 }
+async function settleForGesture(env) {
+  let warning;
+  if (supportsFlowTree(env.device.platform)) {
+    try {
+      await settleTree(env, { skipProvenOutage: true });
+    } catch (err) {
+      warning = unsettledGestureWarning(err);
+    }
+  }
+  if (env.signal?.aborted) return { aborted: true };
+  return warning !== void 0 ? { warning } : {};
+}
+function warned(settle) {
+  return settle.warning !== void 0 ? { warning: settle.warning } : {};
+}
+function unsettledGestureWarning(err) {
+  const reason = err instanceof Error ? err.message : String(err);
+  return `dispatched without settling the screen first: the UI tree could not be read (${reason}), so there was no way to tell whether anything was moving. The gesture went out against whatever was in flight, and one aimed at a moving element can miss it entirely - this step passing says it was sent, not that it landed. Restore the tree source, or put an explicit \`wait:\` in front of gestures that follow a transition.`;
+}
 async function resolveTargetPoint(env, target) {
   if (target.selector) {
     const frame = await waitForFrame(env, target.selector);
@@ -145899,26 +146036,29 @@ async function resolveTargetPoint(env, target) {
     if (!frame) {
       return { fail: { ok: false, reason: offscreenHint(target.selector) } };
     }
-    return getDescribeTapPoint(frame);
+    return { point: getDescribeTapPoint(frame) };
   }
   if (typeof target.x === "number" && typeof target.y === "number") {
-    return { x: target.x, y: target.y };
+    const settle = await settleForGesture(env);
+    if (settle.aborted) return { fail: ABORTED_OUTCOME };
+    return { point: { x: target.x, y: target.y }, ...warned(settle) };
   }
   return { fail: { ok: false, reason: "gesture needs a selector or x/y coordinates" } };
 }
 async function runTap(env, target) {
-  const point = await resolveTargetPoint(env, target);
-  if ("fail" in point) return point.fail;
+  const resolved = await resolveTargetPoint(env, target);
+  if ("fail" in resolved) return resolved.fail;
   await invokeOnDevice(env, "gesture-tap", {
-    ...point,
+    ...resolved.point,
     ...target.times !== void 0 ? { clickCount: target.times } : {}
   });
-  return { ok: true };
+  return { ok: true, ...warned(resolved) };
 }
 var DEFAULT_LONG_PRESS_MS = 800;
 async function runLongPress(env, step) {
-  const point = await resolveTargetPoint(env, step);
-  if ("fail" in point) return point.fail;
+  const resolved = await resolveTargetPoint(env, step);
+  if ("fail" in resolved) return resolved.fail;
+  const point = resolved.point;
   const duration3 = step.duration ?? DEFAULT_LONG_PRESS_MS;
   if (env.device.platform === "chromium") {
     await invokeOnDevice(env, "gesture-drag", {
@@ -145936,17 +146076,21 @@ async function runLongPress(env, step) {
       ]
     });
   }
-  return { ok: true };
+  return { ok: true, ...warned(resolved) };
 }
 async function runPinch(env, step) {
   let center = { x: 0.5, y: 0.5 };
   let frame;
+  let settle = {};
   if (step.selector) {
     const resolved = await waitForFrame(env, step.selector);
     if (resolved === "aborted") return ABORTED_OUTCOME;
     if (!resolved) return { ok: false, reason: offscreenHint(step.selector) };
     frame = resolved;
     center = getDescribeTapPoint(resolved);
+  } else {
+    settle = await settleForGesture(env);
+    if (settle.aborted) return ABORTED_OUTCOME;
   }
   const { n, per } = decomposePinch(step.scale);
   const guards = systemEdgeGuards(env.device);
@@ -145977,11 +146121,11 @@ async function runPinch(env, step) {
     await invokeOnDevice(env, "gesture-pinch", args);
     if (i < n - 1 && !await sleepOrAbort(PINCH_SETTLE_MS, env.signal)) return ABORTED_OUTCOME;
   }
-  return { ok: true };
+  return { ok: true, ...warned(settle) };
 }
 async function fetchScreenAspect(env) {
   try {
-    const { screen } = await fetchFlowTree(env.registry, env.device, env.launchedNativeApp);
+    const { screen } = await readFlowTree(env);
     return screen && screen.width > 0 && screen.height > 0 ? screen.width / screen.height : void 0;
   } catch {
     return void 0;
@@ -145990,12 +146134,16 @@ async function fetchScreenAspect(env) {
 async function runRotate(env, step) {
   let center = { x: 0.5, y: 0.5 };
   let frame;
+  let settle = {};
   if (step.selector) {
     const resolved = await waitForFrame(env, step.selector);
     if (resolved === "aborted") return ABORTED_OUTCOME;
     if (!resolved) return { ok: false, reason: offscreenHint(step.selector) };
     frame = resolved;
     center = getDescribeTapPoint(resolved);
+  } else {
+    settle = await settleForGesture(env);
+    if (settle.aborted) return ABORTED_OUTCOME;
   }
   const aspect = await fetchScreenAspect(env);
   const guards = systemEdgeGuards(env.device);
@@ -146037,7 +146185,7 @@ async function runRotate(env, step) {
     if (env.signal?.aborted) return ABORTED_OUTCOME;
     throw err;
   }
-  return { ok: true };
+  return { ok: true, ...warned(settle) };
 }
 async function runType(env, step) {
   const frame = await waitForFrame(env, step.into);
@@ -146069,7 +146217,7 @@ async function waitForCondition(env, step, timeoutMs) {
   for (; ; ) {
     if (env.signal?.aborted) return ABORTED_OUTCOME;
     try {
-      const data = await fetchFlowTree(env.registry, env.device, env.launchedNativeApp);
+      const data = await readFlowTree(env);
       lastMatches = flowFindAll(data.tree, step.selector);
       fetchError = void 0;
       everMatched ||= lastMatches.length > 0;
@@ -146164,11 +146312,7 @@ async function waitForIdle(env, step) {
     const roundStartedAt = Date.now();
     let answeredReadMs;
     const [read, frame] = await Promise.all([
-      settleWithin(
-        fetchFlowTree(env.registry, env.device, env.launchedNativeApp),
-        roundBudget,
-        env.signal
-      ).then((r) => {
+      settleWithin(readFlowTree(env), roundBudget, env.signal).then((r) => {
         answeredReadMs = Date.now() - roundStartedAt;
         return r;
       }),
@@ -148807,6 +148951,7 @@ async function treeSourceGate(registry2, device, bundleId, signal) {
 async function runLaunch(state3, app) {
   const env = deviceEnv(state3);
   const { registry: registry2, device, signal } = env;
+  if (state3.treeOutage) state3.treeOutage.proven = void 0;
   if (device.platform === "chromium") return runChromiumLaunch(state3, app);
   const bundleId = appIdForPlatform(app, device.platform);
   if (!bundleId) {
@@ -149028,8 +149173,8 @@ when \`on\` is omitted; distinct from the \`rotate\` tool, which changes device
 for a UI condition, and additionally takes the one condition that has no selector: \`idle: true\` waits
 until the screen has content and stops moving in BOTH the UI tree and the rendered pixels (it never
 fails a run \u2014 a screen that never settles passes carrying a \`warning\`, which is what makes it safe to
-persist; the one outcome that does stop the run is an \`error\` for a tree source that could not be read
-at all \u2014 a broken window rather than a verdict about the app, which leaves the run not-ok and skips
+persist; the one idle outcome that does stop the run is an \`error\` for a tree source THIS step could not
+read at all \u2014 a broken window rather than a verdict about the app, which leaves the run not-ok and skips
 every later step; it says nothing about WHICH screen settled \u2014 a dropped tap leaves the source screen
 perfectly idle \u2014 so pair it with the element check that names the destination); \`wait\` pauses for a fixed number of milliseconds; \`assert\` checks one now; \`snapshot\`
 diffs a screenshot \u2014 or, with \`cropOn: <selector>\`, one element's cropped region \u2014 against a stored
@@ -149037,6 +149182,14 @@ baseline (a missing baseline fails the step \u2014 set updateBaselines to adopt
 cropped element whose size drifted fails on dimensions); \`echo\` annotates; \`run\` executes another flow
 inline \u2014 a YAML path resolved against the directory of the flow file that references it (co-located
 runs only).
+A selector-less gesture \u2014 a coordinate \`tap\`/\`long-press\`, or a \`pinch\`/\`rotate\` with no \`on\` \u2014 resolves
+no frame out of the tree, so an unreadable tree source does NOT stop it the way it stops \`idle\`: it
+settles best-effort, dispatches anyway, and the step PASSES carrying a \`warning\` that quotes the source's
+own error. That green says the gesture was SENT, not that it landed. Restore the tree source (usually
+relaunch the app so the instrumentation loads), or accept the warning where the app can serve no tree;
+the first such gesture proves the outage and later ones spend that verdict without paying the settle
+window again. A tree read that comes back, or a relaunch, retires that verdict \u2014 which only makes the
+next gesture pay a fresh window, and it warns again if the source is still down.
 A \`when:\` block (condition + \`steps:\`, no else) runs its steps only if the condition holds \u2014
 checked once with the short assert grace \u2014 for one-sided divergences like interstitials and coach
 marks; a skipped block reports distinctly and failures inside an entered block are real failures.
@@ -149118,6 +149271,12 @@ Pass exactly one flow source: name for a saved flow under project_root, or flow_
         device,
         deviceIsExplicit: Boolean(params.device),
         signal,
+        // One holder per ExecState, shared by nested `run:` flows: `deviceEnv`
+        // spreads the reference, so what one step's settle learns about the
+        // tree source the next one already has. A `tool: flow-execute` builds
+        // its own instead, which is why that step spends this verdict rather
+        // than inheriting whatever the sub-run proved.
+        treeOutage: {},
         flowsDir,
         viaUpload,
         baselineKey: baselineKeyFor(canonicalPath, flowName),
@@ -149711,6 +149870,10 @@ async function execLeafStep(state3, step, index, scope) {
       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)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.20.1-next.7",
+  "version": "0.20.1-next.9",
   "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

@@ -112,6 +112,8 @@ In a `scroll-to` map, put the selector under `target:`. The map supports `up`, `
 
 `type` presses Enter unless `submit: false`. A polished focus tap plus keyboard call usually needs `submit: false`. Store external values as `{{secret:NAME}}`. The runner uses the first source that defines the name: environment `ARGENT_SECRET_NAME`; project `.argent/secrets.env`; project `.env.local`, then `.env`; then `~/.argent/secrets.env`. The two `secrets.env` files accept the bare `NAME`, but the shared dotenv files expose only `ARGENT_SECRET_`-prefixed keys, so a bare `NAME=…` in `.env` or `.env.local` stays unresolved. The runner redacts every resolved value, so do not use a placeholder for content a report must show.
 
+A **selector-less gesture** — a coordinate `tap`/`long-press`, or a `pinch`/`rotate` with no `on:` — resolves no frame, so a tree source it cannot read does not fail it. It settles best effort, dispatches anyway, and the step **passes carrying a warning** that quotes the source's own error. That green says the gesture was sent, not that it landed: one aimed at a moving element can miss it entirely. Restore the tree source, usually by relaunching the app so the instrumentation loads. Accept the warning only where the app serves no tree at all, and put an explicit `wait:` before a gesture that follows a transition. The first such gesture proves the outage and later ones spend that verdict without paying the settle window again. A tree read that comes back, or a relaunch, retires that verdict — which only makes the next gesture pay a fresh window, and it warns again if the source is still down.
+
 ## Verification conditions
 
 ```yaml
@@ -164,7 +166,7 @@ It **never fails a run.** Every outcome short of a clean settle passes with a wa
 - **settled on the UI tree alone** — no screenshot pair could be read, so presentation-layer animation was never waited out.
 - **too few reads** — a settle needs three reads across two intervals and this step got fewer, so it ended with no evidence either way.
 
-Only a tree source that cannot be read stops the run, as an errored step — one still failing when the wait ends, one that wedges after answering, one that answers with an empty tree it flags as degraded (an unattached Vega toolkit, an AX service asking to be relaunched), or one that never answers (raise `timeout` before suspecting the app). The run is then not ok and every later step is skipped. A single failed read is not that: the hold restarts from the next good read.
+Only a tree source this step could not read stops the run, as an errored step — one still failing when the wait ends, one that wedges after answering, one that answers with an empty tree it flags as degraded (an unattached Vega toolkit, an AX service asking to be relaunched), or one that never answers (raise `timeout` before suspecting the app). The run is then not ok and every later step is skipped. A single failed read is not that: the hold restarts from the next good read. The same outage stops no [selector-less gesture](#directives), which needs no frame and passes with its own warning instead.
 
 `idle` proves readiness only and never identifies the screen, so it cannot serve as acceptance evidence or replace the identity gate. Gate the next action on a stable element. Add `idle` during polish after each screen change, not after every step.
 

package/skills/argent-create-flow/references/live-authoring.md

@@ -239,4 +239,6 @@ Manual rescue invalidates the pass. An `errored` step was never evaluated: an `i
 
 **A passing step that carries a `warning` is a finding, not noise.** `await: { idle: true }` raises [six different warnings](flow-yaml.md#idle-readiness) and they do not share one meaning. Two say the screen was moving; one says the wait ran out mid-hold and is repaired by raising the step's `timeout:`; one says the tree stayed empty; one says the tree did hold still and only the screenshot pairs were missing, so the capture path is what to check; one says the step ended with no evidence either way. No report separates intended motion from a load that never finished. Read which one it is, look at that screen, disclose what you found, and confirm the following step targets a stable element rather than stillness.
 
+A [selector-less gesture](flow-yaml.md#directives) raises a warning of a different shape, not one of those six: a tree-source outage left it unsettled, so it dispatched blind and the green says only that the gesture was sent. Restore the source, usually by relaunching the app so the instrumentation loads. Accept it only where the app serves no tree at all, such as the [injection-free iOS form](reliability-and-recovery.md#terminally-non-injectable-ios-apps).
+
 One uninterrupted full pass completes a normal flow. `argent-qa-flows` requires two consecutive passes of unchanged YAML. For CI, use `argent flow run <name> [--platform ...]`; it exits non-zero on failure.

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

@@ -62,6 +62,8 @@ Apple system apps cannot load the instrumentation, and nothing in the launch pat
 - A point focus tap plus raw keyboard with `delayMs: 500`.
 - 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.
+
 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.
@@ -111,6 +113,7 @@ Classify before editing:
 | Partial divergence | An intermediate result disagrees with its echo | Find the first divergent transition                                                                                                                     |
 | Acceptance failure | Actions pass but a requested check fails       | Preserve the check and investigate behavior                                                                                                             |
 | Idle warning       | A readiness step passes without settling       | Read [which of the six warnings](flow-yaml.md#idle-readiness) it is, then gate the next action on a stable element                                      |
+| Unsettled gesture  | A selector-less gesture passes unsettled       | Restore the tree source, usually by relaunching the app; the green says [only that the gesture was sent](flow-yaml.md#directives)                       |
 
 Then:
 

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

@@ -101,7 +101,7 @@ After the last edit and audit, set the streak to zero:
 2. Seed, review, and freeze snapshot baselines. Baseline updates do not count as passes.
 3. Before mobile pass 1, recycle Argent services for this flow's device: two warm passes are correlated evidence, because a fixed timing margin can pass twice simply because environment speed did not change. Scope `stop-all-simulator-servers` to `devices: [<device>]`. Never omit the scope — a bare call is the machine-wide sweep, and step 7 restarts this proof often enough to reap every other agent's devices repeatedly. Use the MCP call for `flow-execute`, or `argent run stop-all-simulator-servers --devices <device>` from the standalone runner's install. The reset must not change app or account data. For Chromium, let the runner boot the declared app and omit `device`. Vega owns no recyclable Argent services, so the teardown is a no-op there and both passes are warm.
 4. Run from the flow's launch and setup without baseline-update mode. Count a pass only when `ok: true` and every acceptance check executed. A false `when:` can skip optional setup only. An errored step does not advance the streak, and the count mixes two kinds — read each reason. One that could not run (an unreadable tree under `idle`, an unresolvable `run:` target) is environment: fix it and rerun. **A failed `launch:` also scores `errored`, and it is a verdict about the app** — an app that no longer installs or starts is the regression this test exists to catch, so report it instead of rerunning.
-5. Resolve every passing-step warning before completion. `await: { idle: true }` raises [six different warnings](../argent-create-flow/references/flow-yaml.md#idle-readiness), so read which one it is first. Two say the screen was moving. One says the wait ran out mid-hold and needs a larger `timeout:`. One says the tree stayed empty. One — **settled on the UI tree alone** — says the hierarchy did hold still and only the screenshot pairs were missing, so inspect the capture path rather than the app's rendering. One says the step ended with no evidence either way. Inspect the screen, disclose the cause, and verify that surrounding acceptance checks use stable elements rather than stillness.
+5. Resolve every passing-step warning before completion. `await: { idle: true }` raises [six different warnings](../argent-create-flow/references/flow-yaml.md#idle-readiness), so read which one it is first. Two say the screen was moving. One says the wait ran out mid-hold and needs a larger `timeout:`. One says the tree stayed empty. One — **settled on the UI tree alone** — says the hierarchy did hold still and only the screenshot pairs were missing, so inspect the capture path rather than the app's rendering. One says the step ended with no evidence either way. Inspect the screen, disclose the cause, and verify that surrounding acceptance checks use stable elements rather than stillness. A [selector-less gesture](../argent-create-flow/references/flow-yaml.md#directives) — a coordinate `tap`/`long-press`, or a `pinch`/`rotate` with no `on:` — warns in a different shape: a tree-source outage left it unsettled, so it dispatched blind and the green says only that the gesture was sent. Restore the tree source, usually by relaunching the app so the instrumentation loads, and rerun. Accepting that warning needs an app that serves no tree, which cannot satisfy this contract anyway.
 6. Run the same YAML again immediately with the same runner. Do not manually reset app or account data.
 7. Reset the streak after any failure, edit, re-recording, baseline update, or state-changing manual recovery. Repair through `argent-create-flow`, audit again, and restart with fresh services.