@swmansion/argent 0.22.0 → 0.22.1-next.0

package/dist/tool-server.cjs

@@ -95692,7 +95692,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.22.0";
+    return "0.22.1-next.0";
   }
   return "0.0.0";
 }
@@ -123431,13 +123431,15 @@ async function pollDescribeTree(args) {
   let polls = 0;
   let lastData = null;
   let lastError;
+  let lastAttemptSettled = false;
   const outcome = (result, aborted2) => ({
     result,
     aborted: aborted2,
     polls,
     elapsedMs: Date.now() - start2,
     lastData,
-    lastError
+    lastError,
+    lastAttemptSettled
   });
   for (; ; ) {
     if (signal?.aborted) return outcome(void 0, true);
@@ -123445,6 +123447,7 @@ async function pollDescribeTree(args) {
     const settled = await settleWithin(fetchTree2(), remaining, signal);
     polls += 1;
     if (settled.type === "aborted") return outcome(void 0, true);
+    lastAttemptSettled = settled.type !== "timeout";
     if (settled.type === "timeout") {
       if (lastData === null) {
         lastError ??= `tree fetch did not complete within the ${timeoutMs}ms wait budget`;
@@ -129524,6 +129527,20 @@ var AWAIT_UI_ELEMENT_TOOL_ID = "await-ui-element";
 function isUnmetUiWaitResult(tool, result) {
   return tool === AWAIT_UI_ELEMENT_TOOL_ID && typeof result === "object" && result !== null && result.success === false;
 }
+var WAIT_CANCELLED_NOTE = "wait was cancelled before the condition was met";
+var TREE_FETCH_FAILED_NOTE_PREFIX = "last tree fetch failed: ";
+var HIDDEN_UNREADABLE_NOTE = "could not confirm the element is hidden \u2014 the UI tree was empty or unreadable at timeout";
+function unmetUiWaitCause(result) {
+  const carried = result?.cause;
+  if (carried === "unmet" || carried === "unreadable" || carried === "cancelled") return carried;
+  const note = result?.note;
+  if (typeof note !== "string") return "unmet";
+  if (note === WAIT_CANCELLED_NOTE) return "cancelled";
+  if (note.startsWith(TREE_FETCH_FAILED_NOTE_PREFIX) || note.startsWith(HIDDEN_UNREADABLE_NOTE)) {
+    return "unreadable";
+  }
+  return "unmet";
+}
 var DEFAULT_TIMEOUT_MS3 = 5e3;
 var DEFAULT_POLL_INTERVAL_MS = 400;
 var zodSchema27 = external_exports.object({
@@ -129561,6 +129578,19 @@ var conditionCompleted = {
   hidden: "UI element became hidden",
   text: "UI element matched expected text"
 };
+var DARK_TAIL_TOLERANCE_INTERVALS = 2;
+var DARK_TAIL_TOLERANCE_MAX_MS = 2e3;
+function timeoutCause(condition, lastTrustedReadAt, finalRead, pollIntervalMs) {
+  if (lastTrustedReadAt === void 0) return "unreadable";
+  if (finalRead === "trusted") return "unmet";
+  if (finalRead === "untrusted" && condition === "hidden") return "unreadable";
+  const darkTailMs = Date.now() - lastTrustedReadAt;
+  const tolerance = Math.min(
+    DARK_TAIL_TOLERANCE_INTERVALS * pollIntervalMs,
+    DARK_TAIL_TOLERANCE_MAX_MS
+  );
+  return darkTailMs > tolerance ? "unreadable" : "unmet";
+}
 var capability21 = {
   apple: { simulator: true, device: true },
   android: { emulator: true, device: true, unknown: true },
@@ -129586,7 +129616,7 @@ function appendDiagnostics(base, lastData) {
   return extras.length === 0 ? base : `${base} (${extras.join("; ")})`;
 }
 function timeoutNote(params, lastTree, fetchError, lastData) {
-  if (fetchError) return `last tree fetch failed: ${fetchError}`;
+  if (fetchError) return `${TREE_FETCH_FAILED_NOTE_PREFIX}${fetchError}`;
   const matches2 = lastTree ? findAll(lastTree, params.selector) : [];
   let base;
   switch (params.condition) {
@@ -129597,7 +129627,7 @@ function timeoutNote(params, lastTree, fetchError, lastData) {
       break;
     }
     case "hidden":
-      base = matches2.some(isVisible) ? "an element matching the selector was still visible at timeout" : "could not confirm the element is hidden \u2014 the UI tree was empty or unreadable at timeout";
+      base = matches2.some(isVisible) ? "an element matching the selector was still visible at timeout" : HIDDEN_UNREADABLE_NOTE;
       break;
     case "visible":
       base = matches2.length > 0 ? "element(s) matched but none was visible (zero-area frame) before timeout" : "no element matched the selector before timeout";
@@ -129646,9 +129676,11 @@ It polls the same accessibility / DOM tree as \`describe\`
 (iOS AXRuntime, Android uiautomator, Chromium CDP, Vega automation toolkit) every pollIntervalMs
 (default ${DEFAULT_POLL_INTERVAL_MS}ms) until timeoutMs (default ${DEFAULT_TIMEOUT_MS3}ms).
 
-Returns { success: boolean, elapsed: number } \u2014 success=false means the condition never held before the
-timeout (a \`note\` then explains what was seen). Use this after a tap/navigation to wait for the next screen,
-or before tapping an element that appears asynchronously.`,
+Returns { success: boolean, elapsed: number, note?, cause? } \u2014 success=false means the wait ended without the
+condition holding, which is not always a verdict on the condition: \`cause\` says which it was \u2014 \`unmet\` (the tree
+was read and the condition was false there), \`unreadable\` (no trustworthy read, so nothing was judged) or
+\`cancelled\` \u2014 and \`note\` describes what was seen. Only \`unmet\` licenses rewriting the check. Use this after a
+tap/navigation to wait for the next screen, or before tapping an element that appears asynchronously.`,
     alwaysLoad: true,
     searchHint: "wait await poll until visible hidden exists text appears disappears timeout element condition settle",
     longRunning: true,
@@ -129674,21 +129706,24 @@ or before tapping an element that appears asynchronously.`,
       const cancelled = () => ({
         success: false,
         elapsed: Date.now() - start2,
-        note: "wait was cancelled before the condition was met"
+        note: WAIT_CANCELLED_NOTE,
+        cause: "cancelled"
       });
       const timeoutMs = params.timeoutMs ?? DEFAULT_TIMEOUT_MS3;
       const pollIntervalMs = params.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
       const selector = params.selector;
       let everMatched = false;
+      let lastTrustedReadAt;
       const poll = await pollDescribeTree({
         fetchTree: () => fetchTree2(device, params, services, isTvOs, androidIsTv),
         timeoutMs,
         pollIntervalMs,
         signal,
-        onSample: (data) => {
+        onSample: (data, nowMs) => {
           const matches2 = findAll(data.tree, selector);
           if (matches2.length > 0) everMatched = true;
           const blind = isBlindRead(data, everMatched);
+          if (!blind) lastTrustedReadAt = nowMs;
           if (!blind && evaluateMatches(params, matches2)) {
             const result = { success: true, elapsed: Date.now() - start2 };
             if (params.condition === "hidden" && !everMatched) {
@@ -129701,10 +129736,12 @@ or before tapping an element that appears asynchronously.`,
       });
       if (poll.aborted) return cancelled();
       if (poll.result) return poll.result;
+      const finalRead = !poll.lastAttemptSettled ? "unsettled" : poll.lastError === void 0 && poll.lastData !== null && !isBlindRead(poll.lastData, everMatched) ? "trusted" : "untrusted";
       return {
         success: false,
         elapsed: Date.now() - start2,
-        note: timeoutNote(params, poll.lastData?.tree ?? null, poll.lastError, poll.lastData)
+        note: timeoutNote(params, poll.lastData?.tree ?? null, poll.lastError, poll.lastData),
+        cause: timeoutCause(params.condition, lastTrustedReadAt, finalRead, pollIntervalMs)
       };
     }
   };
@@ -144185,13 +144222,58 @@ function assertSessionStillLive(session, step) {
     }
   );
 }
+function renderStepForCompare(step) {
+  try {
+    return JSON.stringify(step);
+  } catch {
+    return null;
+  }
+}
+function sameStepRun(now, before, n, nowFrom, beforeFrom) {
+  if (now.length < nowFrom + n || before.length < beforeFrom + n) return false;
+  for (let i = 0; i < n; i += 1) {
+    const rendered = now[nowFrom + i];
+    if (rendered === null || rendered !== before[beforeFrom + i]) {
+      return false;
+    }
+  }
+  return true;
+}
+function anchorHolds(now, before, n) {
+  if (!sameStepRun(now, before, n, 0, 0)) return false;
+  const deleted = before.length - now.length;
+  const inserted = now.length - before.length;
+  for (let at = 0; at < n; at += 1) {
+    for (let size = 1; size <= deleted; size += 1) {
+      if (sameStepRun(now, before, n - at, at, at + size)) return false;
+    }
+    for (let size = 1; size <= inserted; size += 1) {
+      if (sameStepRun(now, before, n - at, at + size, at)) return false;
+    }
+  }
+  return true;
+}
+function dropMovedWarnings(warnings, now, before) {
+  if (!warnings) return 0;
+  const nowRendered = now.map(renderStepForCompare);
+  const beforeRendered = before.map(renderStepForCompare);
+  let dropped = 0;
+  for (const n of [...warnings.keys()]) {
+    if (anchorHolds(nowRendered, beforeRendered, n)) continue;
+    warnings.delete(n);
+    dropped += 1;
+  }
+  return dropped;
+}
 async function appendStepToFlow(session, step) {
   return withFlowLock(session.key, async () => {
     assertSessionStillLive(session, step);
     session.lastTouchedSeq = touch();
     if (session.persist === "host") {
+      const before = session.flow.steps;
       const flowFile = await appendStep(session.filePath, step);
       session.flow = parseFlow(flowFile);
+      session.discardedWarnings = (session.discardedWarnings ?? 0) + dropMovedWarnings(session.stepWarnings, session.flow.steps.slice(0, -1), before);
       return { savedTo: session.filePath, stepCount: session.flow.steps.length };
     }
     session.flow.steps.push(step);
@@ -144248,16 +144330,24 @@ land in another's file. Steps still run LIVE, so give each concurrent recording
 its own device and pick a name unique to your task.
 
 After starting, use flow-add-step to append tool calls \u2014 each step is executed
-LIVE so you can verify it works before it gets recorded. For a self-contained
+LIVE so you can verify it works before it gets recorded. Read each step's
+\`message\`: an await-ui-element whose condition never held is still recorded (it
+returns success:false rather than failing), and a check that passes live can
+still fail once polished into an \`await:\`/\`assert:\` directive, which resolves
+against a different tree. flow-add-step warns about both when you record the
+wait DIRECTLY. A wait nested inside a recorded run-sequence gets neither warning
+\u2014 that tool reports its own shape \u2014 so for those, read \`toolResult\`. For a self-contained
 e2e flow, record a restart-app of the app under test as the FIRST step (captured
 as the flow's \`launch\` step); for a reusable fragment, skip that and pass
 executionPrerequisite instead. Use flow-add-echo to add labels. Call
 flow-finish-recording when done.
 
-If a recorded step turns out to be wrong, you can edit the .yaml file directly
-to remove or reorder steps. Against a remote client, only after
-flow-finish-recording: the in-memory copy is authoritative there, and every
-write serializes it over your edit.`,
+If a recorded step turns out to be wrong, edit the .yaml file directly to
+remove or reorder steps - after flow-finish-recording, not during the
+recording. Against a remote client the in-memory copy is authoritative and
+every write serializes it over your edit; in host mode the recorder re-reads
+the file before each append, so a mid-recording edit renumbers the steps and
+costs the finish the cross-tree verdicts anchored to them.`,
   zodSchema: zodSchema61,
   fileInputs: fileInputs2,
   services: () => ({}),
@@ -144315,141 +144405,10 @@ write serializes it over your edit.`,
 
 // ../tool-server/src/tools/flows/flow-add-step.ts
 init_zod();
-var fs47 = __toESM(require("node:fs/promises"));
+var fs48 = __toESM(require("node:fs/promises"));
 var path33 = __toESM(require("node:path"));
 init_src();
 
-// ../tool-server/src/tools/flows/flow-finish-recording.ts
-init_zod();
-var fs46 = __toESM(require("node:fs/promises"));
-function selectorLabel(sel) {
-  return JSON.stringify(selectorToYaml(sel));
-}
-function textConditionLabel(sel, expectedText, textMatch) {
-  const selector = selectorLabel(sel);
-  const expected = expectedText ?? "";
-  return textMatch === "matches" ? `text ${selector} matches /${expected}/` : textMatch === "equals" ? `text ${selector} == ${JSON.stringify(expected)}` : `text ${selector} contains ${JSON.stringify(expected)}`;
-}
-var zodSchema62 = external_exports.object({
-  name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
-  project_root: external_exports.string().describe(
-    "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording to finish."
-  )
-});
-var flowFinishRecordingTool = {
-  id: "flow-finish-recording",
-  interaction: {
-    // Name the flow: other recordings stay live across this call, so an
-    // unqualified "Finishing flow recording" would not identify which one.
-    startedMsg: ({ params }) => `Finishing recording of flow ${params.name}`,
-    // `params.name` rather than the basename of `result.path`: the two are the
-    // same string on every branch — `assertSafeFlowName` admits no dots or
-    // separators, so `getFlowPath` produces `<name>.yaml` and nothing else —
-    // and this spelling matches the two formatters either side of it.
-    completedMsg: ({ params }) => `Saved recorded flow ${params.name}`,
-    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to finish recording of flow ${params.name}: ${failureSignal2.error_code}`
-  },
-  description: `Finish recording the flow named by \`name\` + \`project_root\`, leaving recordings under any other key untouched. Returns { message, path, executionPrerequisite, steps, summary, flowFile, savedTo } - a summary of all recorded steps plus the final YAML. Use when you have added all desired steps and want to finalize the flow file. Fails if that flow has no recording in progress.
-You can still edit the .yaml file directly afterwards to remove or reorder steps.`,
-  zodSchema: zodSchema62,
-  services: () => ({}),
-  async execute(_services, params) {
-    const { filePath, flowFile, savedTo, flow, summary } = await withFlowFileLock(
-      params.project_root,
-      params.name,
-      async () => {
-        const session = await requireRecordingSession(params.project_root, params.name);
-        const filePath2 = session.filePath;
-        let flowFile2;
-        let savedTo2;
-        if (session.persist === "client") {
-          flowFile2 = serializeFlow(session.flow);
-          savedTo2 = clientFileDirective(filePath2, flowFile2);
-        } else {
-          flowFile2 = await fs46.readFile(filePath2, "utf8");
-          savedTo2 = filePath2;
-        }
-        const flow2 = parseFlow(flowFile2);
-        const summary2 = summarizeSteps(flow2);
-        clearRecordingSession(session);
-        return { filePath: filePath2, flowFile: flowFile2, savedTo: savedTo2, flow: flow2, summary: summary2 };
-      }
-    );
-    return {
-      message: `Finished recording "${params.name}" flow (${flow.steps.length} steps)`,
-      path: filePath,
-      executionPrerequisite: flow.executionPrerequisite,
-      steps: flow.steps.length,
-      summary,
-      flowFile,
-      savedTo
-    };
-  }
-};
-function renderToolArgs(args) {
-  try {
-    return `${JSON.stringify(args)}`;
-  } catch {
-    return "[cyclic args]";
-  }
-}
-function delayLabel(step) {
-  if (!step.delayMs) return "";
-  const ms = Number(step.delayMs);
-  return Number.isFinite(ms) && ms >= 1 ? ` (after ${ms}ms)` : "";
-}
-function summarizeSteps(flow) {
-  return flow.steps.map((step, i) => summarizeStep(step, i + 1));
-}
-function summarizeStep(step, n) {
-  switch (step.kind) {
-    case "echo":
-      return `${n}. echo: ${step.message}`;
-    case "launch":
-      return `${n}. launch: ${typeof step.app === "string" ? step.app : JSON.stringify(step.app)}`;
-    case "run":
-      return `${n}. run: ${step.flow}`;
-    case "tap":
-    case "long-press": {
-      const target = step.selector ? selectorLabel(step.selector) : `(${step.x}, ${step.y})`;
-      const times = step.kind === "tap" && step.times !== void 0 && step.times > 1 ? ` \xD7${step.times}` : "";
-      const held = step.kind === "long-press" && step.duration !== void 0 ? ` for ${step.duration}ms` : "";
-      return `${n}. ${step.kind}: ${target}${times}${held}`;
-    }
-    case "type":
-      return `${n}. type: ${selectorLabel(step.into)} \u2190 "${step.text}"`;
-    case "await":
-    case "assert": {
-      const tail = step.condition === "text" ? textConditionLabel(step.selector, step.expectedText, step.textMatch) : `${step.condition} ${selectorLabel(step.selector)}`;
-      return `${n}. ${step.kind}: ${tail}`;
-    }
-    case "wait":
-      return `${n}. wait: ${step.ms}ms`;
-    case "when": {
-      const cond = step.condition.kind === "platform" ? `platform ${step.condition.platform}` : step.condition.condition === "text" ? textConditionLabel(
-        step.condition.selector,
-        step.condition.expectedText,
-        step.condition.textMatch
-      ) : `${step.condition.condition} ${selectorLabel(step.condition.selector)}`;
-      const count2 = step.steps.length;
-      return `${n}. when: ${cond} (${count2} step${count2 === 1 ? "" : "s"})`;
-    }
-    case "scroll-to":
-      return `${n}. scroll-to: ${selectorLabel(step.target)} (${step.direction})`;
-    case "pinch":
-      return `${n}. pinch: scale ${step.scale}${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
-    case "rotate":
-      return `${n}. rotate: by ${step.by}\xB0${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
-    case "snapshot":
-      return `${n}. snapshot: ${step.name}`;
-    case "idle":
-      return `${n}. await: screen idle`;
-    case "tool":
-    default:
-      return `${n}. tool: ${step.name} ${renderToolArgs(step.args)}${delayLabel(step)}`;
-  }
-}
-
 // ../tool-server/src/tools/flows/flow-device.ts
 init_src();
 var DEVICE_BIND_KEYS = ["udid", "device_id", "device"];
@@ -145030,359 +144989,8 @@ function supportsFlowTree(platform) {
   return FLOW_TREE_SOURCES[platform] !== void 0;
 }
 
-// ../tool-server/src/tools/flows/flow-add-step.ts
-var zodSchema63 = external_exports.object({
-  name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
-  project_root: external_exports.string().describe(
-    "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording this step belongs to."
-  ),
-  command: external_exports.string().describe('MCP tool name (e.g. "gesture-tap", "screenshot", "launch-app")'),
-  args: external_exports.string().optional().describe(
-    `Tool arguments as a JSON string, e.g. '{"udid": "ABC", "x": 0.5, "y": 0.3}'. Omit for tools with no arguments.`
-  ),
-  delayMs: external_exports.number().int().min(0).optional().describe("Milliseconds to sleep before executing this step during replay.")
-});
-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, session, udid, point) {
-  try {
-    const device = resolveDevice(udid);
-    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);
-    if (!selector)
-      return { warning: "tapped element has no stable text/id; kept coordinates (brittle)" };
-    const resolved = selectorToFrame(tree, selector);
-    if (!resolved) {
-      return {
-        warning: `selector ${describeSelector(selector)} matches no element on this screen; kept coordinates (brittle)`
-      };
-    }
-    if (!frameContains(resolved, point.x, point.y)) {
-      return {
-        warning: `selector ${describeSelector(selector)} resolves to a different element on this screen; kept coordinates (brittle)`
-      };
-    }
-    return { selector, warning: fallbackSourceWarning(source, device.platform) };
-  } catch (err) {
-    return {
-      warning: `selector capture failed (${err instanceof Error ? err.message : String(err)}); kept coordinates`
-    };
-  }
-}
-var RUN_TARGET_COMMAND = "flow-execute";
-async function rewriteSiblingFlowPath(session, args) {
-  const flowPath = args.flow_path;
-  if (typeof flowPath !== "string" || args.name !== void 0) return;
-  const invalid = (detail) => new FailureError(
-    `Cannot record a flow-execute of flow_path "${flowPath}": ${detail}. flow_path carries no file-input resolution through flow-add-step's opaque args \u2014 pass name + project_root for a flow saved beside the recording, or add a \`run: <relative path>.yaml\` step to the flow YAML by hand for a cross-directory target.`,
-    {
-      error_code: FAILURE_CODES.FLOW_FILE_INVALID,
-      failure_stage: "flow_add_step_flow_path",
-      failure_area: "tool_server",
-      error_kind: "validation"
-    }
-  );
-  if (!session || session.persist !== "host") {
-    throw invalid(
-      "the recording is not persisted on this host, so its siblings cannot be resolved here"
-    );
-  }
-  if (flowPath.split(/[\\/]+/).includes("..")) {
-    throw invalid(
-      'flow paths must not contain ".." segments \u2014 sibling identity is decided lexically from this path, and a symlinked directory component would make the rewrite run a different file than the path opens'
-    );
-  }
-  const ext = path33.extname(flowPath);
-  const bareExtension = path33.basename(flowPath).toLowerCase() === ".yaml";
-  if (!bareExtension && ext !== ".yaml") {
-    throw invalid(
-      ext.toLowerCase() === ".yaml" ? `flow files must use the lowercase .yaml extension, not "${ext}"` : "flow files must use the .yaml extension"
-    );
-  }
-  const flowsDir = path33.dirname(session.filePath);
-  if (path33.resolve(path33.dirname(flowPath)) !== path33.resolve(flowsDir)) {
-    throw invalid(
-      `it is not in the recording's flow directory ("${flowsDir}"), and a raw tool: step has no boundary to resolve a path through at replay`
-    );
-  }
-  const stem = bareExtension ? "" : path33.basename(flowPath, ".yaml");
-  assertSafeFlowName(stem);
-  const projectRoot = args.project_root;
-  if (typeof projectRoot !== "string" || !path33.isAbsolute(projectRoot)) {
-    throw invalid(
-      `project_root must be an absolute path (got ${typeof projectRoot === "string" ? `"${projectRoot}"` : "none"}) \u2014 a relative root would be resolved against the tool server's cwd, not the calling agent's`
-    );
-  }
-  if (path33.resolve(flowsDirFor(projectRoot), `${stem}.yaml`) !== path33.resolve(flowPath)) {
-    throw invalid(`project_root "${projectRoot}" does not resolve "${stem}" to it`);
-  }
-  const suppliedBase = path33.basename(flowPath);
-  const spelling = await classifyOnDiskSpelling(flowsDir, suppliedBase);
-  if (spelling.state !== "listed") {
-    const recovery = spelling.state === "absent" ? `pass the basename exactly as it appears on disk` : spelling.addressable ? `pass flow_path with the on-disk basename "${spelling.actual}"` : `rename "${spelling.actual}" to "${suppliedBase}" to record it \u2014 flow files must be lowercase .yaml`;
-    throw invalid(
-      `the file must be named as it appears on disk \u2014 no directory entry is named "${suppliedBase}"` + (spelling.state === "case_folded" ? ` (this filesystem matched it case-insensitively to "${spelling.actual}")` : "") + `, so the recorded run: step would name a flow no case-sensitive checkout can find \u2014 ` + recovery
-    );
-  }
-  delete args.flow_path;
-  args.name = stem;
-}
-async function captureRunTarget(session, args) {
-  const name = typeof args.name === "string" ? args.name : void 0;
-  if (name === void 0) {
-    return { warning: "flow-execute call had no flow name; kept the raw step" };
-  }
-  if (session.persist !== "host") {
-    return {
-      warning: `kept the raw flow-execute step \u2014 run: composition is host-resolved, so a remote recording can't reference "${name}" portably`
-    };
-  }
-  try {
-    assertSafeFlowName(name);
-    const realFlowPath = await fs47.realpath(session.filePath);
-    const flowsDir = path33.dirname(realFlowPath);
-    const fragPath = path33.join(flowsDir, `${name}.yaml`);
-    const projectRoot = args.project_root;
-    if (typeof projectRoot !== "string" || !path33.isAbsolute(projectRoot)) {
-      return {
-        warning: `kept the raw flow-execute step \u2014 project_root must be an absolute path (got ${typeof projectRoot === "string" ? `"${projectRoot}"` : "none"}) to confirm "${name}" names the recording's own sibling`
-      };
-    }
-    const spelling = await classifyOnDiskSpelling(flowsDir, `${name}.yaml`);
-    if (spelling.state === "case_folded") {
-      const recovery = spelling.addressable ? `re-run it as name "${path33.basename(spelling.actual, ".yaml")}" to record it` : `rename "${spelling.actual}" to "${name}.yaml" to record it \u2014 flow files must be lowercase .yaml`;
-      return {
-        warning: `kept the raw flow-execute step \u2014 no sibling is named "${name}.yaml" (this filesystem matched it case-insensitively to "${spelling.actual}"), so a run: ${name} step would name a flow no case-sensitive checkout can find \u2014 ${recovery}`
-      };
-    }
-    parseFlow(await fs47.readFile(fragPath, "utf8"));
-    let executedPath;
-    try {
-      executedPath = await fs47.realpath(path33.join(flowsDirFor(projectRoot), `${name}.yaml`));
-    } catch {
-      executedPath = void 0;
-    }
-    if (executedPath === void 0) {
-      return {
-        warning: `kept the raw flow-execute step \u2014 could not verify which file the live flow-execute ran ("${name}" has no canonical file in project_root's flows dir to compare the sibling against)`
-      };
-    }
-    if (executedPath !== await fs47.realpath(fragPath)) {
-      return {
-        warning: `kept the raw flow-execute step \u2014 project_root "${projectRoot}" resolves "${name}" to "${executedPath}", not the recording's sibling "${fragPath}", so "${name}.yaml" beside the recording's real file is not the file the live flow-execute ran and a run: ${name} step would replay a different flow than the one that just ran`
-      };
-    }
-    return { flow: `${name}.yaml` };
-  } catch (err) {
-    return {
-      warning: `could not resolve "${name}" as a sibling fragment (${err instanceof Error ? err.message : String(err)}); kept the raw flow-execute step`
-    };
-  }
-}
-function createFlowAddStepTool(registry2) {
-  return {
-    id: "flow-add-step",
-    interaction: {
-      // Name the flow: recordings are concurrent, so several of these lines can
-      // interleave in one log and "the recorded flow" would not identify which.
-      startedMsg: ({ params }) => `Adding ${params.command} step to flow ${params.name}`,
-      completedMsg: ({ params }) => `Added ${params.command} step to flow ${params.name}`,
-      failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to add ${params.command} step to flow ${params.name}: ${failureSignal2.error_code}`
-    },
-    description: `Execute a tool call and record it as a step in the flow named by \`name\` + \`project_root\` (the recording must already be open \u2014 see flow-start-recording). Use when recording a flow and you want to run and capture each action. A coordinate \`gesture-tap\` is recorded as a portable \`tap: { selector }\` step when the tapped element has stable text/identifier (otherwise coordinates are kept with a warning); a \`restart-app\` is recorded as a \`launch\` step (record one FIRST to make the flow a self-contained e2e flow; restart-app has no chromium support, so a chromium flow records as a fragment \u2014 add the \`launch: { chromium: <app path> }\` line to the YAML afterward, deleting the executionPrerequisite line if one was recorded: a flow that starts with a launch must not declare it).
-Returns { message, toolResult, stepCount, recorded, savedTo } on success. If it fails an error is returned and nothing is recorded.
-If a step was recorded by mistake, edit the .yaml to remove it \u2014 against a remote client, only after \`flow-finish-recording\`: the in-memory copy is authoritative there, and every write serializes it over your edit.`,
-    zodSchema: zodSchema63,
-    services: () => ({}),
-    async execute(_services, params, ctx) {
-      const session = await requireRecordingSession(params.project_root, params.name);
-      const args = params.args ? JSON.parse(params.args) : {};
-      if (params.command === RUN_TARGET_COMMAND) await rewriteSiblingFlowPath(session, args);
-      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, session, args.udid, {
-          x: args.x,
-          y: args.y
-        });
-      }
-      const toolResult = await invokeSubTool(registry2, ctx, params.command, args);
-      const runTarget = params.command === RUN_TARGET_COMMAND && params.delayMs === void 0 ? await captureRunTarget(session, args) : void 0;
-      const strippedArgs = stripDeviceKeys(args);
-      const isLaunch = params.command === "restart-app" && params.delayMs === void 0 && typeof strippedArgs.bundleId === "string" && Object.keys(strippedArgs).length === 1;
-      const cc = args.clickCount;
-      const tapTimes = isTap && typeof cc === "number" && Number.isInteger(cc) && cc >= 2 && cc <= 10 ? { times: cc } : {};
-      let step;
-      let warning;
-      if (captured?.selector) {
-        step = { kind: "tap", selector: captured.selector, ...tapTimes };
-        warning = captured.warning;
-      } else if (isTap) {
-        step = { kind: "tap", x: args.x, y: args.y, ...tapTimes };
-        warning = captured?.warning;
-      } else if (isLaunch) {
-        step = { kind: "launch", app: strippedArgs.bundleId };
-      } else if (runTarget?.flow) {
-        step = { kind: "run", flow: runTarget.flow };
-      } else {
-        warning = runTarget?.warning;
-        step = {
-          kind: "tool",
-          name: params.command,
-          args: strippedArgs,
-          delayMs: params.delayMs
-        };
-      }
-      const { savedTo, stepCount } = await appendStepToFlow(session, step);
-      return {
-        message: `Step added to "${params.name}" flow${warning ? ` \u2014 ${warning}` : ""}`,
-        toolResult,
-        stepCount,
-        recorded: summarizeStep(step, stepCount),
-        // Host mode: a path. Client mode: the directive that carries the YAML
-        // to the client, which IS the persistence mechanism there — the one
-        // place the full file still has to travel per step.
-        savedTo
-      };
-    }
-  };
-}
-
-// ../tool-server/src/tools/flows/flow-insert-echo.ts
-init_zod();
-var zodSchema64 = external_exports.object({
-  name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
-  project_root: external_exports.string().describe(
-    "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording this echo belongs to."
-  ),
-  message: external_exports.string().describe("Message to echo when the flow is replayed")
-});
-var flowInsertEchoTool = {
-  id: "flow-add-echo",
-  interaction: {
-    // Name the flow: recordings are concurrent, so several of these lines can
-    // interleave in one log and "the recorded flow" would not identify which.
-    startedMsg: ({ params }) => `Adding note to flow ${params.name}`,
-    completedMsg: ({ params }) => `Added note to flow ${params.name}`,
-    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to add note to flow ${params.name}: ${failureSignal2.error_code}`
-  },
-  description: `Record an echo step in the flow named by \`name\` + \`project_root\`. Echo steps print a message when the flow is replayed \u2014 useful as labels between tool calls.
-Use when you want to annotate a recorded flow with a human-readable label or checkpoint message.
-Returns { message, stepCount, savedTo }. Fails if that flow has no recording in progress.`,
-  zodSchema: zodSchema64,
-  services: () => ({}),
-  async execute(_services, params) {
-    const session = await requireRecordingSession(params.project_root, params.name);
-    const { savedTo, stepCount } = await appendStepToFlow(session, {
-      kind: "echo",
-      message: params.message
-    });
-    return {
-      message: `Echo added to "${params.name}" flow`,
-      stepCount,
-      savedTo
-    };
-  }
-};
-
-// ../tool-server/src/tools/flows/flow-run.ts
-init_zod();
-var fs51 = __toESM(require("node:fs/promises"));
-var path36 = __toESM(require("node:path"));
-init_src();
-
-// ../tool-server/src/tools/flows/flow-nested-outcome.ts
-var FLOW_EXECUTE_TOOL_ID = "flow-execute";
-var RUN_SEQUENCE_TOOL_ID = "run-sequence";
-function isRecord(value) {
-  return typeof value === "object" && value !== null;
-}
-function firstFailingStep(steps) {
-  if (!Array.isArray(steps)) return void 0;
-  for (const entry of steps) {
-    if (!isRecord(entry)) continue;
-    if (entry.status !== "fail" && entry.status !== "error") continue;
-    const what = typeof entry.tool === "string" ? entry.tool : typeof entry.kind === "string" ? entry.kind : "step";
-    const why = typeof entry.reason === "string" ? entry.reason : "no reason given";
-    return `${what}: ${why}`;
-  }
-  return void 0;
-}
-function count(value) {
-  return typeof value === "number" ? value : 0;
-}
-function flowExecuteOutcome(result) {
-  const flow = typeof result.flow === "string" ? result.flow : "the composed flow";
-  if (!("steps" in result) && typeof result.notice === "string") {
-    const prerequisite = typeof result.executionPrerequisite === "string" && result.executionPrerequisite ? `: ${result.executionPrerequisite}` : "";
-    return {
-      status: "error",
-      reason: `flow "${flow}" did not run \u2014 its execution prerequisite was not acknowledged${prerequisite}. Add prerequisiteAcknowledged: true to the step's args, or compose with run: instead.`
-    };
-  }
-  if (result.aborted === true) {
-    return { status: "skip", reason: `flow "${flow}" was aborted` };
-  }
-  if (result.ok === false) {
-    const detail = firstFailingStep(result.steps);
-    return {
-      status: "fail",
-      reason: `flow "${flow}" failed: ${count(result.passed)} passed, ${count(result.failed)} failed, ${count(result.errored)} errored${detail ? ` (${detail})` : ""}`
-    };
-  }
-  return void 0;
-}
-function runSequenceOutcome(result) {
-  const steps = result.steps;
-  if (!Array.isArray(steps)) return void 0;
-  const failed = steps.find((s) => isRecord(s) && typeof s.error === "string");
-  if (failed && isRecord(failed)) {
-    const tool = typeof failed.tool === "string" ? failed.tool : "step";
-    return {
-      status: "fail",
-      reason: `run-sequence stopped at ${tool} after ${count(result.completed)} of ${count(result.total)} steps: ${String(failed.error)}`
-    };
-  }
-  const total = count(result.total);
-  if (total > 0 && steps.length < total) {
-    return {
-      status: "skip",
-      reason: `run-sequence was aborted after ${count(result.completed)} of ${total} steps`
-    };
-  }
-  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;
-  return NESTED_ORCHESTRATORS.get(tool)?.(result);
-}
-
 // ../tool-server/src/tools/flows/flow-pixels.ts
-var fs48 = __toESM(require("node:fs/promises"));
+var fs46 = __toESM(require("node:fs/promises"));
 var import_pngjs2 = __toESM(require_png());
 init_adb();
 var CAPTURE_SCALE = 0.25;
@@ -145452,9 +145060,9 @@ async function capturePng(env, budgetMs) {
   if (env.device.platform === "chromium") return captureChromiumPng(env);
   const file2 = await captureFile(env, budgetMs);
   try {
-    return await fs48.readFile(file2);
+    return await fs46.readFile(file2);
   } finally {
-    await fs48.rm(file2, { force: true }).catch(() => {
+    await fs46.rm(file2, { force: true }).catch(() => {
     });
   }
 }
@@ -146268,6 +145876,715 @@ function assertReason(condition, selector, expectedText, textMatch, matches2) {
   }
 }
 
+// ../tool-server/src/tools/flows/flow-finish-recording.ts
+init_zod();
+var fs47 = __toESM(require("node:fs/promises"));
+function selectorLabel(sel) {
+  const yaml = selectorToYaml(sel);
+  if (typeof yaml !== "object" || yaml === null) return JSON.stringify(yaml);
+  const sorted = Object.fromEntries(
+    Object.entries(yaml).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+  );
+  return JSON.stringify(sorted);
+}
+function textConditionLabel(sel, expectedText, textMatch) {
+  const selector = selectorLabel(sel);
+  const expected = expectedText ?? "";
+  return textMatch === "matches" ? `text ${selector} matches /${expected}/` : textMatch === "equals" ? `text ${selector} == ${JSON.stringify(expected)}` : `text ${selector} contains ${JSON.stringify(expected)}`;
+}
+var zodSchema62 = external_exports.object({
+  name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
+  project_root: external_exports.string().describe(
+    "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording to finish."
+  )
+});
+function attachStepWarnings(summary, warnings) {
+  if (warnings.size === 0) return summary;
+  return summary.flatMap((line, i) => {
+    const recorded = warnings.get(i + 1);
+    return recorded ? [line, `   warning: ${recorded.warning}`] : [line];
+  });
+}
+function warningHeadline(warnings, discarded) {
+  const counts = { conversion: 0, wait: 0 };
+  for (const { kind } of warnings.values()) counts[kind] += 1;
+  const clauses = [];
+  if (counts.conversion > 0) {
+    clauses.push(
+      `${counts.conversion} ${counts.conversion === 1 ? "step carries" : "steps carry"} a cross-tree warning about converting a recorded wait`
+    );
+  }
+  if (counts.wait > 0) {
+    clauses.push(
+      `${counts.wait} ${counts.wait === 1 ? "step" : "steps"} recorded a wait that did not pass`
+    );
+  }
+  const carried = clauses.length === 0 ? "" : ` \u2014 ${clauses.join(", and ")}; read \`summary\` before converting or replaying`;
+  if (discarded === 0) return carried;
+  const one = discarded === 1;
+  const drop = `${discarded} ${one ? "warning" : "warnings"} raised during this recording ${one ? "is" : "are"} NOT in \`summary\`: a hand edit to the .yaml moved the ${one ? "step it judged" : "steps they judged"}, so which step ${one ? "it belongs" : "they belong"} to is no longer knowable \u2014 re-record ${one ? "that wait" : "those waits"} to see ${one ? "it" : "them"} again`;
+  return carried === "" ? ` \u2014 ${drop}` : `${carried}. ${drop}`;
+}
+function anchoredWarnings(session, steps) {
+  const kept = /* @__PURE__ */ new Map();
+  const recorded = session.flow.steps;
+  if (recorded.length !== steps.length) return kept;
+  if (!steps.every((step, i) => stepAnchor(step) === stepAnchor(recorded[i]))) return kept;
+  for (const [n, verdict] of session.stepWarnings ?? []) {
+    const step = steps[n - 1];
+    if (step !== void 0 && stepAnchor(step) === verdict.step) kept.set(n, verdict);
+  }
+  return kept;
+}
+var flowFinishRecordingTool = {
+  id: "flow-finish-recording",
+  interaction: {
+    // Name the flow: other recordings stay live across this call, so an
+    // unqualified "Finishing flow recording" would not identify which one.
+    startedMsg: ({ params }) => `Finishing recording of flow ${params.name}`,
+    // `params.name` rather than the basename of `result.path`: the two are the
+    // same string on every branch — `assertSafeFlowName` admits no dots or
+    // separators, so `getFlowPath` produces `<name>.yaml` and nothing else —
+    // and this spelling matches the two formatters either side of it.
+    completedMsg: ({ params }) => `Saved recorded flow ${params.name}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to finish recording of flow ${params.name}: ${failureSignal2.error_code}`
+  },
+  description: `Finish recording the flow named by \`name\` + \`project_root\`, leaving recordings under any other key untouched. Returns { message, path, executionPrerequisite, steps, summary, flowFile, savedTo } - a summary of all recorded steps plus the final YAML. Use when you have added all desired steps and want to finalize the flow file. Fails if that flow has no recording in progress.
+A warning flow-add-step raised on a recorded \`await-ui-element\` is repeated in \`summary\` as a \`warning:\` line of its own, right below the step it judges, and \`message\` counts them by kind. A warning is repeated only while the step it judges is still identifiable by its number: hand-editing the .yaml during the recording moves the steps, so those warnings are DROPPED rather than pinned on whichever step inherited the number, and \`message\` says how many were dropped. A step that carries a cross-tree warning was re-probed against the runner's tree: read it before converting that wait to \`await:\`/\`assert:\`, which is what the verdict is about and what this moment is for. A step that recorded a wait which did not pass was never probed at all, and its own warning names the CAUSE, because only one of them judges the condition: an unmet wait was read and found false, and it stops the run at replay; a wait whose tree source could not be read, or one that was cancelled, observed nothing and leaves the condition UNKNOWN rather than known-bad. Read those before replaying.
+You can still edit the .yaml file directly afterwards to remove or reorder steps.`,
+  zodSchema: zodSchema62,
+  services: () => ({}),
+  async execute(_services, params) {
+    const { filePath, flowFile, savedTo, flow, summary, headline } = await withFlowFileLock(
+      params.project_root,
+      params.name,
+      async () => {
+        const session = await requireRecordingSession(params.project_root, params.name);
+        const filePath2 = session.filePath;
+        let flowFile2;
+        let savedTo2;
+        if (session.persist === "client") {
+          flowFile2 = serializeFlow(session.flow);
+          savedTo2 = clientFileDirective(filePath2, flowFile2);
+        } else {
+          flowFile2 = await fs47.readFile(filePath2, "utf8");
+          savedTo2 = filePath2;
+        }
+        const flow2 = parseFlow(flowFile2);
+        const anchored = anchoredWarnings(session, flow2.steps);
+        const summary2 = attachStepWarnings(summarizeSteps(flow2), anchored);
+        const discarded = (session.discardedWarnings ?? 0) + (session.stepWarnings?.size ?? 0) - anchored.size;
+        const headline2 = warningHeadline(anchored, discarded);
+        clearRecordingSession(session);
+        return { filePath: filePath2, flowFile: flowFile2, savedTo: savedTo2, flow: flow2, summary: summary2, headline: headline2 };
+      }
+    );
+    return {
+      // Name the counts in `message` as well. A caller that reads only
+      // `message` would otherwise polish blind.
+      message: `Finished recording "${params.name}" flow (${flow.steps.length} steps)` + headline,
+      path: filePath,
+      executionPrerequisite: flow.executionPrerequisite,
+      steps: flow.steps.length,
+      summary,
+      flowFile,
+      savedTo
+    };
+  }
+};
+function renderToolArgs(args) {
+  try {
+    return `${JSON.stringify(args)}`;
+  } catch {
+    return "[cyclic args]";
+  }
+}
+function delayLabel(step) {
+  if (!step.delayMs) return "";
+  const ms = Number(step.delayMs);
+  return Number.isFinite(ms) && ms >= 1 ? ` (after ${ms}ms)` : "";
+}
+function summarizeSteps(flow) {
+  return flow.steps.map((step, i) => summarizeStep(step, i + 1));
+}
+function stepAnchor(step) {
+  return summarizeStep(step, 0);
+}
+function summarizeStep(step, n) {
+  switch (step.kind) {
+    case "echo":
+      return `${n}. echo: ${step.message}`;
+    case "launch":
+      return `${n}. launch: ${typeof step.app === "string" ? step.app : JSON.stringify(step.app)}`;
+    case "run":
+      return `${n}. run: ${step.flow}`;
+    case "tap":
+    case "long-press": {
+      const target = step.selector ? selectorLabel(step.selector) : `(${step.x}, ${step.y})`;
+      const times = step.kind === "tap" && step.times !== void 0 && step.times > 1 ? ` \xD7${step.times}` : "";
+      const held = step.kind === "long-press" && step.duration !== void 0 ? ` for ${step.duration}ms` : "";
+      return `${n}. ${step.kind}: ${target}${times}${held}`;
+    }
+    case "type":
+      return `${n}. type: ${selectorLabel(step.into)} \u2190 "${step.text}"`;
+    case "await":
+    case "assert": {
+      const tail = step.condition === "text" ? textConditionLabel(step.selector, step.expectedText, step.textMatch) : `${step.condition} ${selectorLabel(step.selector)}`;
+      return `${n}. ${step.kind}: ${tail}`;
+    }
+    case "wait":
+      return `${n}. wait: ${step.ms}ms`;
+    case "when": {
+      const cond = step.condition.kind === "platform" ? `platform ${step.condition.platform}` : step.condition.condition === "text" ? textConditionLabel(
+        step.condition.selector,
+        step.condition.expectedText,
+        step.condition.textMatch
+      ) : `${step.condition.condition} ${selectorLabel(step.condition.selector)}`;
+      const count2 = step.steps.length;
+      return `${n}. when: ${cond} (${count2} step${count2 === 1 ? "" : "s"})`;
+    }
+    case "scroll-to":
+      return `${n}. scroll-to: ${selectorLabel(step.target)} (${step.direction})`;
+    case "pinch":
+      return `${n}. pinch: scale ${step.scale}${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
+    case "rotate":
+      return `${n}. rotate: by ${step.by}\xB0${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
+    case "snapshot":
+      return `${n}. snapshot: ${step.name}`;
+    case "idle":
+      return `${n}. await: screen idle`;
+    case "tool":
+    default:
+      return `${n}. tool: ${step.name} ${renderToolArgs(step.args)}${delayLabel(step)}`;
+  }
+}
+
+// ../tool-server/src/tools/flows/flow-add-step.ts
+var zodSchema63 = external_exports.object({
+  name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
+  project_root: external_exports.string().describe(
+    "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording this step belongs to."
+  ),
+  command: external_exports.string().describe('MCP tool name (e.g. "gesture-tap", "screenshot", "launch-app")'),
+  args: external_exports.string().optional().describe(
+    `Tool arguments as a JSON string, e.g. '{"udid": "ABC", "x": 0.5, "y": 0.3}'. Omit for tools with no arguments.`
+  ),
+  delayMs: external_exports.number().int().min(0).optional().describe("Milliseconds to sleep before executing this step during replay.")
+});
+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`;
+}
+function platformOf(udid) {
+  return typeof udid === "string" ? resolveDevice(udid).platform : void 0;
+}
+var UNSUPPORTED_PLATFORM = {
+  divergence: "The recorder and the runner read different projections of the screen.",
+  read: "No read-only tool is known to report the runner's projection on this platform \u2014 keep the step raw"
+};
+function retargetRemedy(idKind, condition) {
+  if (condition === "hidden") {
+    return `but this verdict says that tree still HAS the element, so retargeting at ${idKind} it definitely carries is the wrong direction \u2014 either narrow the selector until it matches only what you expect to leave, or gate on something that does leave, and prove it with \`flow-execute\`; or keep the step raw`;
+  }
+  return `so retarget the DIRECTIVE at ${idKind} the full hierarchy carries and prove it with \`flow-execute\`, or keep the step raw`;
+}
+function runnerSideReadClause(udid, condition) {
+  const platform = platformOf(udid);
+  if (platform === "ios") {
+    return "No read-only tool reports the runner's projection on iOS \u2014 `native-find-views` and `native-full-hierarchy` return the RAW view tree, keeping the hidden, transparent, scroll-clipped and unlabelled container views the runner drops, and neither answers the question a selector asks: `native-find-views` matches `identifier`/`label`/`className` EXACTLY and takes no substring `text` or `role`, and `native-full-hierarchy` takes no matcher at all \u2014 it dumps the tree for you to read \u2014 " + retargetRemedy("an `id`", condition);
+  }
+  if (platform === "android") {
+    return "No read-only tool exposes the runner's full hierarchy on Android \u2014 `describe` returns the trimmed tree the recorder read, not the runner's \u2014 " + retargetRemedy("a `resource-id`", condition);
+  }
+  if (platform === "chromium") {
+    const settle = "No read-only tool exposes the runner's trimmed tree on Chromium \u2014 `describe` re-reads the same DOM on a shorter walk, so it both lists nodes the runner drops and omits nodes the runner keeps \u2014 so settle it by running the conversion: put the directive in a flow and `flow-execute` it. ";
+    if (condition === "hidden") {
+      return settle + "This verdict says that tree still HAS the element, so the usual chromium tips are the wrong direction here: a `scroll-to` before the check, or a switch to an `id`/`role` selector, only makes the directive match more surely. Absence from `describe` is not the element having left, either \u2014 on a dense page the recorder's walk stops at 5000 nodes where the runner's goes to 12000. Narrow the selector until it matches only what you expect to leave, or gate on something that does leave; or keep the step raw";
+    }
+    return settle + // Name both axes: `normRect` clamps each edge on its own, so a
+    // horizontally scrolled node comes back zero-WIDTH at a normal height.
+    "A zero-area frame in `describe` means off-viewport \u2014 zero height for a node above or below the viewport, zero width for one left or right of it, since the walker clamps each edge on its own \u2014 and the fix there is a `scroll-to` before the check rather than a different selector; a password field reaches the runner under the name `[password]`, so only an `id`/`role` selector can match it";
+  }
+  if (platform === "vega") {
+    return "`describe` reads the same source the runner does, so re-run the wait rather than re-recording the selector";
+  }
+  return UNSUPPORTED_PLATFORM.read;
+}
+var SCREEN_MAY_HAVE_MOVED = " A screen that changed between the live wait and this re-probe reads the same way, so rule that out first.";
+function treeDivergenceFor(udid, condition) {
+  const platform = platformOf(udid);
+  if (platform === "ios") {
+    return "The recorder reads the accessibility tree and the runner reads the full native view hierarchy; they overlap but neither contains the other." + SCREEN_MAY_HAVE_MOVED;
+  }
+  if (platform === "chromium") {
+    if (condition === "hidden") {
+      return "Both read the same DOM but project it differently, and here it is the RECORDER that never saw the element: the live wait passed on absence, and this verdict says the runner's tree holds it \u2014 so nothing the flow tree DROPS can be the cause. What is left is the recorder's own limit: its walk stops at 5000 nodes where the flow tree's goes to 12000, so on a dense page the element is past the end of what it read." + SCREEN_MAY_HAVE_MOVED;
+    }
+    return "Both read the same DOM but project it differently, and here it is the RUNNER's side to check: the live wait passed, so the recorder's tree did hold a matching element and its 5000-node walk limit is not what went wrong. The flow tree keeps only addressable nodes (id, label, value, clickable or focused) whose frame the walker did not clamp to zero area for being off-viewport, and it redacts a password field's name to `[password]`." + SCREEN_MAY_HAVE_MOVED;
+  }
+  if (platform === "android") {
+    return "Both read the same `getHierarchy` dump from the android-devtools helper; this host then parses it two ways. `describe`'s interactables trim collapses a `testID`-only container into a passthrough and drops the node carrying the id, while borrowing a descendant's text into an unlabelled clickable's own label \u2014 where the flow adapter keeps every view with a `resource-id` or a label, and asks for 12000 nodes against the helper's 5000 default. So each holds elements the other drops." + SCREEN_MAY_HAVE_MOVED;
+  }
+  if (platform === "vega") {
+    const cause = condition === "text" ? "disagreement means either the SCREEN changed between the live wait and this re-probe or the two sides elected different elements, as above \u2014 not that the two trees differ." : "disagreement means the SCREEN changed between the live wait and this re-probe, not that the two trees differ.";
+    return "Both read the same automation-toolkit page source, and the flow tree only re-shapes it \u2014 it drops no element and its text hoist can only add matches \u2014 so on this platform a " + cause;
+  }
+  return UNSUPPORTED_PLATFORM.divergence;
+}
+function awaitStillNeeds(condition) {
+  if (condition === "hidden") return "the element LEAVES that tree";
+  if (condition === "text") return "the element THAT tree elects comes to match on it";
+  return "the element reaches that tree";
+}
+function textTieClause(udid) {
+  const order = platformOf(udid) === "ios" ? "and the two are flat lists built from different sources \u2014 the accessibility element order and the view-hierarchy walk \u2014 so neither order follows from the other" : "and the recorder's lists a container before its children where the runner's lists children before their container";
+  return ` Check FIRST whether the selector matches more than one element, because a \`text\` check reads only one of them \u2014 the first visible match in reading order \u2014 and the two sides can elect DIFFERENT ones from the very same nodes: an exact frame tie is settled by which node its tree listed first, ${order}. The reason above quotes whichever element the RUNNER elected, so compare it against the one you meant. If that is what happened, both trees hold both elements and neither the tree differences nor a changed screen below explains anything \u2014 narrow the selector until it resolves a single node, and note that a longer \`await:\` timeout cannot help, since the text it read is already final.`;
+}
+var SPELLING_CLAUSE = "Both of those are about the selector exactly as recorded, so convert it in the strict map spelling (`{ text: \u2026 }` / `{ id: \u2026 }`, a straight copy of the step's `selector:`): a bare-string conversion (`{ visible: Continue }`) re-parses as a LOOSE selector \u2014 identifier first, text only as a fallback \u2014 which is a different check this probe never made.";
+var UNMET_WAIT_WARNING = "recorded, but the wait itself never held \u2014 `await-ui-element` reports an unmet condition by returning success:false instead of failing, so the step was written to the flow anyway. At replay an unmet wait FAILS the step and stops the run there, so re-record it once the condition can actually hold, and delete the failed step after `flow-finish-recording` rather than mid-recording: against a remote client the in-memory copy is authoritative and the next append writes the step straight back, and in host mode the recorder re-reads the file before each append, so an edit that renumbers the steps costs the finish the verdicts it would otherwise carry. The cross-tree re-probe was skipped: it asks whether a check that PASSED would survive conversion to `await:`/`assert:`, and this one did not pass";
+var UNREADABLE_WAIT_WARNING = "recorded, but this wait reached its deadline without a trustworthy read of the UI tree, so the condition was never judged \u2014 `await-ui-element` returns success:false for that too, and the step was written to the flow anyway. Either no read in the window could be trusted, or the reads went dark before the end and what they saw no longer describes it. Whether the condition holds is UNKNOWN, not known-bad: `toolResult.note` names the tree-source error where a fetch threw, and describes what was seen where the tree was merely empty or degraded. Get that source back and re-record the step to find out. Do not delete the step on this warning alone. The cross-tree re-probe was skipped: it asks whether a check that PASSED would survive conversion to `await:`/`assert:`, and this one never got an answer";
+var CANCELLED_WAIT_WARNING = "recorded, but this wait was cancelled before its deadline, so the condition was never settled \u2014 `await-ui-element` reports a cancelled wait as success:false, and the step was written to the flow anyway. Whether it holds is UNKNOWN, not known-bad: re-record the step to find out. The cross-tree re-probe was skipped for the same reason";
+function unmetWaitWarningFor(cause) {
+  if (cause === "unreadable") return UNREADABLE_WAIT_WARNING;
+  if (cause === "cancelled") return CANCELLED_WAIT_WARNING;
+  return UNMET_WAIT_WARNING;
+}
+function indeterminateReasonCaveat(udid) {
+  if (platformOf(udid) !== "ios") return "";
+  return ". That reason may tell you to pass `bundleId` \u2014 it is quoted from the shared native-target error, and it does not apply here: the probe predicts an `await:`/`assert:` directive, and no directive takes a bundleId, so neither this probe nor the runner accepts one (the `bundleId` on this step reached the live wait only). What the runner's iOS tree needs is an app with argent's instrumentation loaded \u2014 relaunch it with `launch-app` or a flow `launch:` step. An app that cannot load it at all, such as a `com.apple.*` system app, can never be probed or converted: keep the check as a raw `tool:` step";
+}
+var CANCELLED_PROBE_WARNING = "recorded, but the re-probe against the tree the RUNNER reads was cancelled before it answered. The step itself ran and is written to the flow; only the verdict is missing, so whether it would convert to `await:`/`assert:` is UNKNOWN, not known-bad \u2014 record the wait again, uncancelled, before trusting the conversion";
+var PROBE_MAX_TREE_READ_MS = 2500;
+var PROBE_ASSERT_GRACE_MS = 1e3;
+var PROBE_BUDGET_MS = PROBE_ASSERT_GRACE_MS + 2 * PROBE_MAX_TREE_READ_MS;
+var MAX_PROBE_REASON_CHARS = 200;
+var PROBE_REASON_TAIL_CHARS = 60;
+function elisionMarker(dropped) {
+  return `\u2026 (${dropped} more chars) \u2026`;
+}
+function cappedReason(reason) {
+  if (reason.length <= MAX_PROBE_REASON_CHARS) return reason;
+  const widestMarker = elisionMarker(reason.length).length;
+  const tailChars = Math.max(
+    0,
+    Math.min(PROBE_REASON_TAIL_CHARS, MAX_PROBE_REASON_CHARS - widestMarker)
+  );
+  const headChars = Math.max(0, MAX_PROBE_REASON_CHARS - widestMarker - tailChars);
+  const dropped = reason.length - headChars - tailChars;
+  return `${reason.slice(0, headChars)}${elisionMarker(dropped)}${reason.slice(reason.length - tailChars)}`;
+}
+async function probeAgainstRunnerTree(registry2, ctx, args) {
+  const selector = args.selector;
+  const condition = args.condition;
+  if (typeof condition !== "string" || selector === null || typeof selector !== "object") {
+    return {};
+  }
+  if (typeof args.udid !== "string") return {};
+  const device = resolveDevice(args.udid);
+  const giveUp = new AbortController();
+  const probeSignal = ctx?.signal ? AbortSignal.any([ctx.signal, giveUp.signal]) : giveUp.signal;
+  const settled = await settleWithin(
+    probeWhenCondition(
+      // The loop reads the signal off ActionEnv, so pass it there as well.
+      { registry: registry2, ctx, device, signal: probeSignal },
+      {
+        condition,
+        selector,
+        expectedText: typeof args.expectedText === "string" ? args.expectedText : void 0,
+        textMatch: args.textMatch
+      }
+    ),
+    PROBE_BUDGET_MS,
+    ctx?.signal
+  );
+  giveUp.abort();
+  if (settled.type === "aborted") return { warning: CANCELLED_PROBE_WARNING };
+  const timedOut = settled.type === "timeout";
+  const outcome = settled.type === "value" ? settled.value : {
+    ok: false,
+    indeterminate: true,
+    reason: timedOut ? `the runner's tree was still being read ${PROBE_BUDGET_MS}ms in, which is longer than the recorder waits \u2014 the source is slow, not down` : `reading the runner's tree failed: ${settled.error}`
+  };
+  if (outcome.ok) return {};
+  if (outcome.indeterminate) {
+    return {
+      // Deliberately NOT joined with treeDivergenceFor/runnerSideReadClause.
+      // Nothing was compared, so claiming the two trees differ would send the
+      // author to rewrite a selector that may be perfectly good.
+      //
+      // The reason is quoted whole rather than through `cappedReason`; see
+      // {@link MAX_PROBE_REASON_CHARS}.
+      warning: `this check could not be re-verified against the tree the RUNNER reads (${outcome.reason ?? "no reason given"}), so it passed against the tree \`${AWAIT_UI_ELEMENT_TOOL_ID}\` reads and nothing else. Whether it would convert to \`await:\`/\`assert:\` is UNKNOWN, not known-bad \u2014 ` + // A timeout and an outage need different next moves: "once that tree
+      // source is back" is nonsense for a source that never left.
+      (timedOut ? `re-record this step when the device is quieter, or settle the conversion directly by putting the directive in a flow and running \`flow-execute\`, which has no such ceiling` : `re-probe once that tree source is back before trusting the conversion` + indeterminateReasonCaveat(args.udid))
+    };
+  }
+  return {
+    warning: `recorded, but this condition does NOT hold against the tree the runner resolves directives against (${cappedReason(outcome.reason ?? "no match")}). As the raw \`tool: ${AWAIT_UI_ELEMENT_TOOL_ID}\` step it replays fine \u2014 it reads the same tree it just passed against. What conversion costs you depends on WHY the two disagree: if the trees really do differ over this element, an \`assert:\` conversion fails the same way (it reads that tree on the same short grace this probe just used), and an \`await:\` does too unless ${awaitStillNeeds(condition)} within its longer timeout; if the SCREEN simply moved on since the live wait, this verdict is no evidence against either \u2014 at replay the directive runs where that wait ran, not a moment after it.` + // Ahead of the tree stories: when it applies it makes all of them
+    // inapplicable.
+    (condition === "text" ? textTieClause(args.udid) : "") + " " + SPELLING_CLAUSE + ` ${treeDivergenceFor(args.udid, condition)} ${runnerSideReadClause(args.udid, condition)}`
+  };
+}
+async function captureTapSelector(registry2, session, udid, point) {
+  try {
+    const device = resolveDevice(udid);
+    const launched = recordedLaunchedApp(session, device.platform);
+    const { tree, source } = await fetchFlowTree(registry2, device, launched);
+    const node = nodeAtPoint(tree, point);
+    if (!node) return { warning: "no element found under the tap; kept coordinates (brittle)" };
+    const selector = deriveSelector(node);
+    if (!selector)
+      return { warning: "tapped element has no stable text/id; kept coordinates (brittle)" };
+    const resolved = selectorToFrame(tree, selector);
+    if (!resolved) {
+      return {
+        warning: `selector ${describeSelector(selector)} matches no element on this screen; kept coordinates (brittle)`
+      };
+    }
+    if (!frameContains(resolved, point.x, point.y)) {
+      return {
+        warning: `selector ${describeSelector(selector)} resolves to a different element on this screen; kept coordinates (brittle)`
+      };
+    }
+    return { selector, warning: fallbackSourceWarning(source, device.platform) };
+  } catch (err) {
+    return {
+      warning: `selector capture failed (${err instanceof Error ? err.message : String(err)}); kept coordinates`
+    };
+  }
+}
+var RUN_TARGET_COMMAND = "flow-execute";
+async function rewriteSiblingFlowPath(session, args) {
+  const flowPath = args.flow_path;
+  if (typeof flowPath !== "string" || args.name !== void 0) return;
+  const invalid = (detail) => new FailureError(
+    `Cannot record a flow-execute of flow_path "${flowPath}": ${detail}. flow_path carries no file-input resolution through flow-add-step's opaque args \u2014 pass name + project_root for a flow saved beside the recording, or add a \`run: <relative path>.yaml\` step to the flow YAML by hand for a cross-directory target.`,
+    {
+      error_code: FAILURE_CODES.FLOW_FILE_INVALID,
+      failure_stage: "flow_add_step_flow_path",
+      failure_area: "tool_server",
+      error_kind: "validation"
+    }
+  );
+  if (!session || session.persist !== "host") {
+    throw invalid(
+      "the recording is not persisted on this host, so its siblings cannot be resolved here"
+    );
+  }
+  if (flowPath.split(/[\\/]+/).includes("..")) {
+    throw invalid(
+      'flow paths must not contain ".." segments \u2014 sibling identity is decided lexically from this path, and a symlinked directory component would make the rewrite run a different file than the path opens'
+    );
+  }
+  const ext = path33.extname(flowPath);
+  const bareExtension = path33.basename(flowPath).toLowerCase() === ".yaml";
+  if (!bareExtension && ext !== ".yaml") {
+    throw invalid(
+      ext.toLowerCase() === ".yaml" ? `flow files must use the lowercase .yaml extension, not "${ext}"` : "flow files must use the .yaml extension"
+    );
+  }
+  const flowsDir = path33.dirname(session.filePath);
+  if (path33.resolve(path33.dirname(flowPath)) !== path33.resolve(flowsDir)) {
+    throw invalid(
+      `it is not in the recording's flow directory ("${flowsDir}"), and a raw tool: step has no boundary to resolve a path through at replay`
+    );
+  }
+  const stem = bareExtension ? "" : path33.basename(flowPath, ".yaml");
+  assertSafeFlowName(stem);
+  const projectRoot = args.project_root;
+  if (typeof projectRoot !== "string" || !path33.isAbsolute(projectRoot)) {
+    throw invalid(
+      `project_root must be an absolute path (got ${typeof projectRoot === "string" ? `"${projectRoot}"` : "none"}) \u2014 a relative root would be resolved against the tool server's cwd, not the calling agent's`
+    );
+  }
+  if (path33.resolve(flowsDirFor(projectRoot), `${stem}.yaml`) !== path33.resolve(flowPath)) {
+    throw invalid(`project_root "${projectRoot}" does not resolve "${stem}" to it`);
+  }
+  const suppliedBase = path33.basename(flowPath);
+  const spelling = await classifyOnDiskSpelling(flowsDir, suppliedBase);
+  if (spelling.state !== "listed") {
+    const recovery = spelling.state === "absent" ? `pass the basename exactly as it appears on disk` : spelling.addressable ? `pass flow_path with the on-disk basename "${spelling.actual}"` : `rename "${spelling.actual}" to "${suppliedBase}" to record it \u2014 flow files must be lowercase .yaml`;
+    throw invalid(
+      `the file must be named as it appears on disk \u2014 no directory entry is named "${suppliedBase}"` + (spelling.state === "case_folded" ? ` (this filesystem matched it case-insensitively to "${spelling.actual}")` : "") + `, so the recorded run: step would name a flow no case-sensitive checkout can find \u2014 ` + recovery
+    );
+  }
+  delete args.flow_path;
+  args.name = stem;
+}
+async function captureRunTarget(session, args) {
+  const name = typeof args.name === "string" ? args.name : void 0;
+  if (name === void 0) {
+    return { warning: "flow-execute call had no flow name; kept the raw step" };
+  }
+  if (session.persist !== "host") {
+    return {
+      warning: `kept the raw flow-execute step \u2014 run: composition is host-resolved, so a remote recording can't reference "${name}" portably`
+    };
+  }
+  try {
+    assertSafeFlowName(name);
+    const realFlowPath = await fs48.realpath(session.filePath);
+    const flowsDir = path33.dirname(realFlowPath);
+    const fragPath = path33.join(flowsDir, `${name}.yaml`);
+    const projectRoot = args.project_root;
+    if (typeof projectRoot !== "string" || !path33.isAbsolute(projectRoot)) {
+      return {
+        warning: `kept the raw flow-execute step \u2014 project_root must be an absolute path (got ${typeof projectRoot === "string" ? `"${projectRoot}"` : "none"}) to confirm "${name}" names the recording's own sibling`
+      };
+    }
+    const spelling = await classifyOnDiskSpelling(flowsDir, `${name}.yaml`);
+    if (spelling.state === "case_folded") {
+      const recovery = spelling.addressable ? `re-run it as name "${path33.basename(spelling.actual, ".yaml")}" to record it` : `rename "${spelling.actual}" to "${name}.yaml" to record it \u2014 flow files must be lowercase .yaml`;
+      return {
+        warning: `kept the raw flow-execute step \u2014 no sibling is named "${name}.yaml" (this filesystem matched it case-insensitively to "${spelling.actual}"), so a run: ${name} step would name a flow no case-sensitive checkout can find \u2014 ${recovery}`
+      };
+    }
+    parseFlow(await fs48.readFile(fragPath, "utf8"));
+    let executedPath;
+    try {
+      executedPath = await fs48.realpath(path33.join(flowsDirFor(projectRoot), `${name}.yaml`));
+    } catch {
+      executedPath = void 0;
+    }
+    if (executedPath === void 0) {
+      return {
+        warning: `kept the raw flow-execute step \u2014 could not verify which file the live flow-execute ran ("${name}" has no canonical file in project_root's flows dir to compare the sibling against)`
+      };
+    }
+    if (executedPath !== await fs48.realpath(fragPath)) {
+      return {
+        warning: `kept the raw flow-execute step \u2014 project_root "${projectRoot}" resolves "${name}" to "${executedPath}", not the recording's sibling "${fragPath}", so "${name}.yaml" beside the recording's real file is not the file the live flow-execute ran and a run: ${name} step would replay a different flow than the one that just ran`
+      };
+    }
+    return { flow: `${name}.yaml` };
+  } catch (err) {
+    return {
+      warning: `could not resolve "${name}" as a sibling fragment (${err instanceof Error ? err.message : String(err)}); kept the raw flow-execute step`
+    };
+  }
+}
+function createFlowAddStepTool(registry2) {
+  return {
+    id: "flow-add-step",
+    interaction: {
+      // Name the flow: recordings are concurrent, so several of these lines can
+      // interleave in one log and "the recorded flow" would not identify which.
+      startedMsg: ({ params }) => `Adding ${params.command} step to flow ${params.name}`,
+      completedMsg: ({ params }) => `Added ${params.command} step to flow ${params.name}`,
+      failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to add ${params.command} step to flow ${params.name}: ${failureSignal2.error_code}`
+    },
+    description: `Execute a tool call and record it as a step in the flow named by \`name\` + \`project_root\` (the recording must already be open \u2014 see flow-start-recording). Use when recording a flow and you want to run and capture each action. A coordinate \`gesture-tap\` is recorded as a portable \`tap: { selector }\` step when the tapped element has stable text/identifier (otherwise coordinates are kept with a warning); a \`restart-app\` is recorded as a \`launch\` step (record one FIRST to make the flow a self-contained e2e flow; restart-app has no chromium support, so a chromium flow records as a fragment \u2014 add the \`launch: { chromium: <app path> }\` line to the YAML afterward, deleting the executionPrerequisite line if one was recorded: a flow that starts with a launch must not declare it).
+A recorded \`await-ui-element\` that PASSED is re-probed against the tree the RUNNER resolves \`await:\`/\`assert:\` directives against, which is NOT the tree the live call read; a wait that came back \`{ success: false }\` is not probed at all, and its warning says so; when the condition does not hold there the step is still recorded and \`message\` carries a warning to read before converting \u2014 whether the conversion actually breaks depends on WHY the two disagree, since a screen that moved on between the live wait and the re-probe reads the same way. If that tree could not be read at all, the warning says so instead: the conversion is UNKNOWN, not known-bad. The probe judges the selector exactly as recorded, so write the conversion in the strict map spelling (\`{ visible: { text: Continue } }\`, copying the step's \`selector:\`) \u2014 the bare-string spelling (\`{ visible: Continue }\`) re-parses as a loose selector that resolves identifier-first and falls back to text, which is a different check. \`message\` also warns when the live wait itself came back \`{ success: false }\` \u2014 that tool reports a failed wait by returning rather than throwing, so the step is recorded either way. That warning names the cause, because only one of them judges the condition: a genuine miss will stop the run at replay, while a wait whose tree source was unreadable, or one that was cancelled, observed nothing and leaves the condition UNKNOWN.
+Returns { message, toolResult, stepCount, recorded, savedTo } on success \u2014 \`message\` is \`Step added to "<name>" flow\` plus any warning about what was recorded (read it; a warning never means the step was skipped). If it fails an error is returned and nothing is recorded.
+If a step was recorded by mistake, remove it from the .yaml after \`flow-finish-recording\` rather than during the recording: against a remote client the in-memory copy is authoritative and every write serializes it over your edit, and in host mode a mid-recording edit renumbers the steps, which costs the finish the cross-tree verdicts anchored to them.`,
+    // The recorded tool RUNS here, so this call lasts as long as whatever it
+    // wraps, and the three it most often wraps declare this too. Without it the
+    // MCP adapter capped the POST at 30s and retried the identical body four
+    // more times — and every retry re-runs the action and appends another step,
+    // because an aborted request still appends its first.
+    longRunning: true,
+    zodSchema: zodSchema63,
+    services: () => ({}),
+    async execute(_services, params, ctx) {
+      const session = await requireRecordingSession(params.project_root, params.name);
+      const args = params.args ? JSON.parse(params.args) : {};
+      if (params.command === RUN_TARGET_COMMAND) await rewriteSiblingFlowPath(session, args);
+      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, session, args.udid, {
+          x: args.x,
+          y: args.y
+        });
+      }
+      const toolResult = await invokeSubTool(registry2, ctx, params.command, args);
+      let waitWarning;
+      if (params.command === AWAIT_UI_ELEMENT_TOOL_ID) {
+        if (isUnmetUiWaitResult(params.command, toolResult)) {
+          waitWarning = {
+            warning: unmetWaitWarningFor(unmetUiWaitCause(toolResult)),
+            kind: "wait"
+          };
+        } else {
+          const probed = (await probeAgainstRunnerTree(registry2, ctx, args)).warning;
+          if (probed) waitWarning = { warning: probed, kind: "conversion" };
+        }
+      }
+      const runTarget = params.command === RUN_TARGET_COMMAND && params.delayMs === void 0 ? await captureRunTarget(session, args) : void 0;
+      const strippedArgs = stripDeviceKeys(args);
+      const isLaunch = params.command === "restart-app" && params.delayMs === void 0 && typeof strippedArgs.bundleId === "string" && Object.keys(strippedArgs).length === 1;
+      const cc = args.clickCount;
+      const tapTimes = isTap && typeof cc === "number" && Number.isInteger(cc) && cc >= 2 && cc <= 10 ? { times: cc } : {};
+      let step;
+      let warning;
+      if (captured?.selector) {
+        step = { kind: "tap", selector: captured.selector, ...tapTimes };
+        warning = captured.warning;
+      } else if (isTap) {
+        step = { kind: "tap", x: args.x, y: args.y, ...tapTimes };
+        warning = captured?.warning;
+      } else if (isLaunch) {
+        step = { kind: "launch", app: strippedArgs.bundleId };
+      } else if (runTarget?.flow) {
+        step = { kind: "run", flow: runTarget.flow };
+      } else {
+        warning = waitWarning?.warning ?? runTarget?.warning;
+        step = {
+          kind: "tool",
+          name: params.command,
+          args: strippedArgs,
+          delayMs: params.delayMs
+        };
+      }
+      const { savedTo, stepCount } = await appendStepToFlow(session, step);
+      if (waitWarning) {
+        (session.stepWarnings ??= /* @__PURE__ */ new Map()).set(stepCount, {
+          ...waitWarning,
+          step: stepAnchor(step)
+        });
+      }
+      return {
+        message: `Step added to "${params.name}" flow${warning ? ` \u2014 ${warning}` : ""}`,
+        toolResult,
+        stepCount,
+        recorded: summarizeStep(step, stepCount),
+        // Host mode: a path. Client mode: the directive that carries the YAML
+        // to the client, which IS the persistence mechanism there — the one
+        // place the full file still has to travel per step.
+        savedTo
+      };
+    }
+  };
+}
+
+// ../tool-server/src/tools/flows/flow-insert-echo.ts
+init_zod();
+var zodSchema64 = external_exports.object({
+  name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
+  project_root: external_exports.string().describe(
+    "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording this echo belongs to."
+  ),
+  message: external_exports.string().describe("Message to echo when the flow is replayed")
+});
+var flowInsertEchoTool = {
+  id: "flow-add-echo",
+  interaction: {
+    // Name the flow: recordings are concurrent, so several of these lines can
+    // interleave in one log and "the recorded flow" would not identify which.
+    startedMsg: ({ params }) => `Adding note to flow ${params.name}`,
+    completedMsg: ({ params }) => `Added note to flow ${params.name}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to add note to flow ${params.name}: ${failureSignal2.error_code}`
+  },
+  description: `Record an echo step in the flow named by \`name\` + \`project_root\`. Echo steps print a message when the flow is replayed \u2014 useful as labels between tool calls.
+Use when you want to annotate a recorded flow with a human-readable label or checkpoint message.
+Returns { message, stepCount, savedTo }. Fails if that flow has no recording in progress.`,
+  zodSchema: zodSchema64,
+  services: () => ({}),
+  async execute(_services, params) {
+    const session = await requireRecordingSession(params.project_root, params.name);
+    const { savedTo, stepCount } = await appendStepToFlow(session, {
+      kind: "echo",
+      message: params.message
+    });
+    return {
+      message: `Echo added to "${params.name}" flow`,
+      stepCount,
+      savedTo
+    };
+  }
+};
+
+// ../tool-server/src/tools/flows/flow-run.ts
+init_zod();
+var fs51 = __toESM(require("node:fs/promises"));
+var path36 = __toESM(require("node:path"));
+init_src();
+
+// ../tool-server/src/tools/flows/flow-nested-outcome.ts
+var FLOW_EXECUTE_TOOL_ID = "flow-execute";
+var RUN_SEQUENCE_TOOL_ID = "run-sequence";
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function firstFailingStep(steps) {
+  if (!Array.isArray(steps)) return void 0;
+  for (const entry of steps) {
+    if (!isRecord(entry)) continue;
+    if (entry.status !== "fail" && entry.status !== "error") continue;
+    const what = typeof entry.tool === "string" ? entry.tool : typeof entry.kind === "string" ? entry.kind : "step";
+    const why = typeof entry.reason === "string" ? entry.reason : "no reason given";
+    return `${what}: ${why}`;
+  }
+  return void 0;
+}
+function count(value) {
+  return typeof value === "number" ? value : 0;
+}
+function flowExecuteOutcome(result) {
+  const flow = typeof result.flow === "string" ? result.flow : "the composed flow";
+  if (!("steps" in result) && typeof result.notice === "string") {
+    const prerequisite = typeof result.executionPrerequisite === "string" && result.executionPrerequisite ? `: ${result.executionPrerequisite}` : "";
+    return {
+      status: "error",
+      reason: `flow "${flow}" did not run \u2014 its execution prerequisite was not acknowledged${prerequisite}. Add prerequisiteAcknowledged: true to the step's args, or compose with run: instead.`
+    };
+  }
+  if (result.aborted === true) {
+    return { status: "skip", reason: `flow "${flow}" was aborted` };
+  }
+  if (result.ok === false) {
+    const detail = firstFailingStep(result.steps);
+    return {
+      status: "fail",
+      reason: `flow "${flow}" failed: ${count(result.passed)} passed, ${count(result.failed)} failed, ${count(result.errored)} errored${detail ? ` (${detail})` : ""}`
+    };
+  }
+  return void 0;
+}
+function runSequenceOutcome(result) {
+  const steps = result.steps;
+  if (!Array.isArray(steps)) return void 0;
+  const failed = steps.find((s) => isRecord(s) && typeof s.error === "string");
+  if (failed && isRecord(failed)) {
+    const tool = typeof failed.tool === "string" ? failed.tool : "step";
+    return {
+      status: "fail",
+      reason: `run-sequence stopped at ${tool} after ${count(result.completed)} of ${count(result.total)} steps: ${String(failed.error)}`
+    };
+  }
+  const total = count(result.total);
+  if (total > 0 && steps.length < total) {
+    return {
+      status: "skip",
+      reason: `run-sequence was aborted after ${count(result.completed)} of ${total} steps`
+    };
+  }
+  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;
+  return NESTED_ORCHESTRATORS.get(tool)?.(result);
+}
+
 // ../tool-server/src/tools/flows/flow-visual.ts
 var import_node_crypto8 = require("node:crypto");
 var fs50 = __toESM(require("node:fs/promises"));