@swmansion/argent 0.22.2-next.0 → 0.22.2-next.10

package/dist/tool-server.cjs

@@ -628,6 +628,9 @@ var init_failure_codes = __esm({
       SIMULATOR_SERVER_READY_TIMEOUT: "SIMULATOR_SERVER_READY_TIMEOUT",
       SIMULATOR_SERVER_PROCESS_ERROR: "SIMULATOR_SERVER_PROCESS_ERROR",
       SIMULATOR_SERVER_TERMINATED: "SIMULATOR_SERVER_TERMINATED",
+      SIMULATOR_COMMAND_REJECTED: "SIMULATOR_COMMAND_REJECTED",
+      SIMULATOR_COMMAND_ACK_TIMEOUT: "SIMULATOR_COMMAND_ACK_TIMEOUT",
+      SIMULATOR_COMMAND_TRANSPORT_FAILED: "SIMULATOR_COMMAND_TRANSPORT_FAILED",
       AX_QUERY_TIMEOUT: "AX_QUERY_TIMEOUT",
       AX_DAEMON_READY_TIMEOUT: "AX_DAEMON_READY_TIMEOUT",
       AX_DAEMON_EXITED_BEFORE_READY: "AX_DAEMON_EXITED_BEFORE_READY",
@@ -76339,15 +76342,28 @@ async function emulatorSupportsFlag(flag, options = {}) {
   const cached3 = emulatorFlagSupportCache.get(cacheKey3);
   if (cached3 !== void 0) return cached3;
   let output;
+  let failure = null;
   try {
     const { stdout, stderr } = await execFileAsync9(emulatorPath, ["-help"], {
       timeout: options.timeoutMs ?? 1e4,
+      // Same hazard runAdb guards against: a SIGTERM-immune child (emulator
+      // wedged in Qt/graphics init) leaves execFile unsettled forever, and
+      // this await has no deadline of its own.
+      killSignal: "SIGKILL",
       maxBuffer: 8 * 1024 * 1024
     });
     output = stdout + stderr;
   } catch (err) {
     const e = err;
-    output = (e.stdout ?? "") + (e.stderr ?? "");
+    output = e.killed ? "" : (e.stdout ?? "") + (e.stderr ?? "");
+    failure = err instanceof Error ? err.message : String(err);
+  }
+  if (output === "") {
+    process.stderr.write(
+      `[argent] \`${emulatorPath} -help\` produced no complete listing ` + (failure ? `(${failure})` : "but exited successfully") + `; assuming "${flag}" unsupported for this boot and retrying on the next one
+`
+    );
+    return false;
   }
   const supported = output.includes(flag);
   emulatorFlagSupportCache.set(cacheKey3, supported);
@@ -76557,7 +76573,10 @@ async function listAvds() {
   const emulatorPath = await resolveAndroidBinary("emulator");
   if (!emulatorPath) return [];
   try {
-    const { stdout } = await execFileAsync9(emulatorPath, ["-list-avds"], { timeout: 5e3 });
+    const { stdout } = await execFileAsync9(emulatorPath, ["-list-avds"], {
+      timeout: 5e3,
+      killSignal: "SIGKILL"
+    });
     return stdout.split("\n").map((l) => l.trim()).filter((l) => l && AVD_NAME_PATTERN.test(l)).map((name) => ({ name }));
   } catch {
     return [];
@@ -76575,6 +76594,7 @@ async function checkSnapshotLoadable(avdName, snapshotName = "default_boot", opt
     ];
     const { stdout } = await execFileAsync9(emulatorPath, args, {
       timeout: options.timeoutMs ?? 1e4,
+      killSignal: "SIGKILL",
       maxBuffer: 4 * 1024 * 1024
     });
     const tail = stdout.split("\n").slice(-6).join("\n");
@@ -89978,6 +89998,10 @@ var FLAG_REGISTRY = [
     name: "disable-auto-screenshot",
     description: "Disable the automatic screenshot captured after interaction tools."
   },
+  {
+    name: "disable-auto-describe",
+    description: "Disable the accessibility element tree appended after interaction tools."
+  },
   {
     name: "argent-lens",
     description: "Argent Lens \u2014 the propose_variant / await_user_selection tools and the Electron preview window for staging UI design variants and letting a human pick among them. Off by default while the feature is in development."
@@ -90278,6 +90302,14 @@ var CONFIG_SCHEMA = [
     // drained/reset, not just the file rewritten.
     manageCommand: "argent telemetry"
   },
+  {
+    key: "allowlist.enabled",
+    description: "Whether `argent update` re-applies editor auto-approve allowlist rules. Unset (the default) keeps the current behavior: update refreshes the rules for editors that already have argent configured. Set to `false` to keep update from touching editor allowlists. `false` in either scope wins, so a committed project opt-out holds for every teammate.",
+    scopes: ["project", "global"],
+    parse: asBoolean,
+    merge: "prioritize-restrictive",
+    example: "false"
+  },
   {
     key: "lens.agent",
     description: "Coding-agent id remembered by `argent lens` to skip the picker.",
@@ -93869,7 +93901,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.2-next.0";
+    return "0.22.2-next.10";
   }
   return "0.0.0";
 }
@@ -94237,7 +94269,10 @@ function simulatorServerBinaryPath() {
   }
   return p;
 }
-function simulatorServerBinaryDir() {
+function simulatorServerRunDir() {
+  if (fs7.existsSync(path8.join(BIN_DIR, "resources", "android"))) {
+    return BIN_DIR;
+  }
   return platformBinDir();
 }
 function requireBinIn(dir, name) {
@@ -95381,13 +95416,56 @@ var import_express = __toESM(require_express2());
 
 // ../tool-server/src/blueprints/simulator-server.ts
 var import_node_child_process10 = require("node:child_process");
-var readline2 = __toESM(require("node:readline"));
+var readline = __toESM(require("node:readline"));
 init_src();
 
 // ../tool-server/src/blueprints/ax-service.ts
 var net = __toESM(require("node:net"));
 var fs13 = __toESM(require("node:fs"));
-var readline = __toESM(require("node:readline"));
+
+// ../tool-server/src/utils/ndjson-socket.ts
+var PREVIEW_CHARS = 80;
+function preview(raw) {
+  const printable = raw.replace(/[\x00-\x1f\x7f\u2028\u2029]/g, "\xB7");
+  return printable.length > PREVIEW_CHARS ? `${printable.slice(0, PREVIEW_CHARS)}\u2026` : printable;
+}
+function reportDroppedFrameToStderr(tag3) {
+  return ({ bytes, preview: preview2 }) => {
+    process.stderr.write(`[${tag3}] dropped unparseable frame (${bytes} bytes): ${preview2}
+`);
+  };
+}
+function attachNdjsonReader(socket, handlers) {
+  socket.setEncoding("utf8");
+  let buf = "";
+  const deliver = (raw) => {
+    if (raw.length === 0 || raw === "\r") return;
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      handlers.onDropped({ bytes: Buffer.byteLength(raw, "utf8"), preview: preview(raw) });
+      return;
+    }
+    handlers.onMessage(msg);
+  };
+  socket.on("data", (chunk) => {
+    buf += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    let nl;
+    while ((nl = buf.indexOf("\n")) !== -1) {
+      const raw = buf.slice(0, nl);
+      buf = buf.slice(nl + 1);
+      deliver(raw);
+    }
+  });
+  socket.on("end", () => {
+    const rest = buf;
+    buf = "";
+    if (rest.length > 0) deliver(rest);
+  });
+}
+
+// ../tool-server/src/blueprints/ax-service.ts
 init_src();
 
 // ../tool-server/src/utils/ios-host.ts
@@ -95686,9 +95764,8 @@ async function simctlShutdown(udid) {
   await run(["simctl", "shutdown", stripRemotePrefix(udid)]);
 }
 async function simctlBootstatus(udid, opts) {
-  const args = ["simctl", "bootstatus"];
+  const args = ["simctl", "bootstatus", stripRemotePrefix(udid)];
   if (opts?.boot) args.push("-b");
-  args.push(stripRemotePrefix(udid));
   await run(args, { timeoutMs: 5 * 6e4 });
 }
 async function simctlLaunch(udid, bundleId, args = []) {
@@ -96223,37 +96300,33 @@ var axServiceBlueprint = {
         daemonSocket.destroy();
       }
       daemonSocket = socket;
-      const rl = readline.createInterface({ input: socket });
-      rl.on("line", (raw) => {
-        let msg;
-        try {
-          msg = JSON.parse(raw);
-        } catch {
-          return;
-        }
-        if (typeof msg.id !== "number") return;
-        const pending = pendingRpc.get(msg.id);
-        if (!pending) return;
-        pendingRpc.delete(msg.id);
-        clearTimeout(pending.timer);
-        if (msg.error !== void 0 && msg.error !== null) {
-          pending.reject(
-            new FailureError(
-              typeof msg.error === "string" ? msg.error : JSON.stringify(msg.error),
-              {
-                error_code: FAILURE_CODES.AX_QUERY_FAILED,
-                failure_stage: "ax_service_query_rpc",
-                failure_area: "tool_server",
-                error_kind: "unknown"
-              }
-            )
-          );
-        } else {
-          pending.resolve(msg.result);
+      attachNdjsonReader(socket, {
+        onDropped: reportDroppedFrameToStderr(`ax-service ${udid.slice(0, 8)}`),
+        onMessage: (parsed) => {
+          const msg = parsed;
+          if (typeof msg.id !== "number") return;
+          const pending = pendingRpc.get(msg.id);
+          if (!pending) return;
+          pendingRpc.delete(msg.id);
+          clearTimeout(pending.timer);
+          if (msg.error !== void 0 && msg.error !== null) {
+            pending.reject(
+              new FailureError(
+                typeof msg.error === "string" ? msg.error : JSON.stringify(msg.error),
+                {
+                  error_code: FAILURE_CODES.AX_QUERY_FAILED,
+                  failure_stage: "ax_service_query_rpc",
+                  failure_area: "tool_server",
+                  error_kind: "unknown"
+                }
+              )
+            );
+          } else {
+            pending.resolve(msg.result);
+          }
         }
       });
       socket.on("close", () => {
-        rl.close();
         if (daemonSocket === socket) {
           daemonSocket = null;
           if (!disposed) {
@@ -106263,33 +106336,127 @@ var DEFAULT_SCREENSHOT_SCALE = 0.25;
 var NO_IMAGE_ERROR = /no image to export/i;
 var FIRST_FRAME_WAIT_MS = 6e3;
 var FIRST_FRAME_POLL_MS = 250;
+var COMMAND_ACK_TIMEOUT_MS = 5e3;
 var connections = /* @__PURE__ */ new Map();
 var cmdId = 0;
-function getOrCreateWs(api) {
+function failAllPending(conn, makeError) {
+  const entries = [...conn.pending.values()];
+  conn.pending.clear();
+  for (const entry of entries) entry.settle(makeError(entry.cmd));
+}
+function transportError(cmd, apiUrl, detail) {
+  return new FailureError(
+    `simulator-server did not accept the '${cmd}' command: ${detail}. The command was NOT delivered to the device. Check that the simulator is still booted and the simulator-server for ${apiUrl} is running.`,
+    {
+      error_code: FAILURE_CODES.SIMULATOR_COMMAND_TRANSPORT_FAILED,
+      failure_stage: "simulator_command_transport",
+      failure_area: "tool_server",
+      error_kind: "network",
+      network_failure: "connection_reset",
+      failure_command: "simulator_server"
+    }
+  );
+}
+function getOrCreateConnection(api) {
   const key2 = api.apiUrl;
   const existing = connections.get(key2);
-  if (existing && (existing.readyState === wrapper_default.OPEN || existing.readyState === wrapper_default.CONNECTING)) {
+  if (existing && (existing.ws.readyState === wrapper_default.OPEN || existing.ws.readyState === wrapper_default.CONNECTING)) {
     return existing;
   }
   const { host } = new URL(api.apiUrl);
   const ws = new wrapper_default(`ws://${host}/ws`);
-  ws.on("error", () => connections.delete(key2));
-  ws.on("close", () => connections.delete(key2));
-  connections.set(key2, ws);
-  return ws;
+  const conn = { ws, pending: /* @__PURE__ */ new Map() };
+  ws.on("message", (data) => {
+    const text = Buffer.isBuffer(data) ? data.toString() : Array.isArray(data) ? Buffer.concat(data).toString() : Buffer.from(data).toString();
+    let ack;
+    try {
+      ack = JSON.parse(text);
+    } catch {
+      return;
+    }
+    if (ack.status !== "ok" && ack.status !== "error") return;
+    if (ack.id != null && !conn.pending.has(ack.id)) return;
+    const id = ack.id ?? conn.pending.keys().next().value;
+    if (id == null) return;
+    const entry = conn.pending.get(id);
+    if (entry == null) return;
+    conn.pending.delete(id);
+    if (ack.status === "ok") {
+      entry.settle();
+      return;
+    }
+    entry.settle(
+      new FailureError(
+        `simulator-server rejected the '${entry.cmd}' command: ${ack.message ?? "unknown error"}. The command was NOT delivered to the device.`,
+        {
+          error_code: FAILURE_CODES.SIMULATOR_COMMAND_REJECTED,
+          failure_stage: "simulator_command_rejected",
+          failure_area: "tool_server",
+          error_kind: "unknown",
+          failure_command: "simulator_server"
+        }
+      )
+    );
+  });
+  ws.on("error", (err) => {
+    connections.delete(key2);
+    failAllPending(conn, (cmd) => transportError(cmd, key2, err.message));
+  });
+  ws.on("close", () => {
+    connections.delete(key2);
+    failAllPending(conn, (cmd) => transportError(cmd, key2, "the connection closed"));
+  });
+  connections.set(key2, conn);
+  return conn;
 }
 function sendCommand(api, cmd) {
   if (api.transport) {
     routeViaTransport(api.transport, cmd);
-    return;
-  }
-  const ws = getOrCreateWs(api);
-  const payload = JSON.stringify({ id: String(++cmdId), ...cmd });
-  if (ws.readyState === wrapper_default.OPEN) {
-    ws.send(payload);
-  } else {
-    ws.once("open", () => ws.send(payload));
+    return Promise.resolve();
   }
+  const conn = getOrCreateConnection(api);
+  const id = String(++cmdId);
+  const cmdName = typeof cmd.cmd === "string" ? cmd.cmd : "unknown";
+  const payload = JSON.stringify({ id, ...cmd });
+  return new Promise((resolve12, reject) => {
+    let done = false;
+    const settle = (err) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      conn.pending.delete(id);
+      if (err) reject(err);
+      else resolve12();
+    };
+    const timer = setTimeout(
+      () => settleAndDropConnection(
+        new FailureError(
+          `simulator-server did not acknowledge the '${cmdName}' command within ${COMMAND_ACK_TIMEOUT_MS}ms. The command may not have reached the device \u2014 the simulator may be wedged or the simulator-server unresponsive.`,
+          {
+            error_code: FAILURE_CODES.SIMULATOR_COMMAND_ACK_TIMEOUT,
+            failure_stage: "simulator_command_ack",
+            failure_area: "tool_server",
+            error_kind: "timeout",
+            network_failure: "timeout",
+            failure_command: "simulator_server"
+          }
+        )
+      ),
+      COMMAND_ACK_TIMEOUT_MS
+    );
+    timer.unref?.();
+    const settleAndDropConnection = (err) => {
+      settle(err);
+      connections.delete(api.apiUrl);
+      conn.ws.close();
+    };
+    conn.pending.set(id, { settle, cmd: cmdName });
+    const write = () => conn.ws.send(payload, (err) => {
+      if (err) settle(transportError(cmdName, api.apiUrl, err.message));
+    });
+    if (conn.ws.readyState === wrapper_default.OPEN) write();
+    else conn.ws.once("open", write);
+  });
 }
 function setPointerVisible(api, show, signal) {
   return pointerPost(api, { show }, signal);
@@ -106517,8 +106684,8 @@ function simulatorServerRef(device) {
 }
 var getPaths = () => {
   const BINARY_PATH = simulatorServerBinaryPath();
-  const BINARY_DIR = simulatorServerBinaryDir();
-  return { BINARY_PATH, BINARY_DIR };
+  const RUN_DIR = simulatorServerRunDir();
+  return { BINARY_PATH, RUN_DIR };
 };
 var READY_TIMEOUT_MS = 3e4;
 async function buildRemoteInstance(device) {
@@ -106562,12 +106729,12 @@ async function spawnSimulatorServerProcess(udid, subcommand) {
     throw new Error(`Refusing to start simulator-server for unsafe device id "${udid}".`);
   }
   const deviceSet = subcommand === "ios" ? await deviceSetForUdid(udid) : null;
-  const { BINARY_PATH, BINARY_DIR } = getPaths();
+  const { BINARY_PATH, RUN_DIR } = getPaths();
   return new Promise((resolve12, reject) => {
     const args = [subcommand, "--id", udid];
     if (deviceSet) args.push("--device-set", deviceSet);
     const proc = (0, import_node_child_process10.spawn)(BINARY_PATH, args, {
-      cwd: BINARY_DIR,
+      cwd: RUN_DIR,
       stdio: ["pipe", "pipe", "pipe"]
     });
     let apiUrl = null;
@@ -106575,7 +106742,7 @@ async function spawnSimulatorServerProcess(udid, subcommand) {
     let settled = false;
     const STREAM_GRACE_MS = 500;
     let apiReadyTimer = null;
-    const rl = readline2.createInterface({ input: proc.stdout });
+    const rl = readline.createInterface({ input: proc.stdout });
     const settle = (fn, cleanup) => {
       if (settled) return;
       settled = true;
@@ -109223,7 +109390,6 @@ var variantProposalStore = new VariantProposalStore();
 // ../tool-server/src/blueprints/native-devtools.ts
 var net2 = __toESM(require("node:net"));
 var fs18 = __toESM(require("node:fs"));
-var readline3 = __toESM(require("node:readline"));
 init_src();
 var NATIVE_DEVTOOLS_NAMESPACE = "NativeDevtools";
 function isInjectableBundleId(bundleId) {
@@ -109490,67 +109656,63 @@ var nativeDevtoolsBlueprint = {
     }
     const server = net2.createServer((socket) => {
       let bundleId = null;
-      const rl = readline3.createInterface({ input: socket });
-      rl.on("line", (raw) => {
-        let msg;
-        try {
-          msg = JSON.parse(raw);
-        } catch {
-          return;
-        }
-        if (bundleId === null) {
-          if (msg.type !== "Control") return;
-          bundleId = msg.payload.bundleId;
-          const existing = connections2.get(bundleId);
-          if (existing) {
-            existing.socket.destroy();
-          }
-          connections2.set(bundleId, { socket, networkLog: [] });
-          if (activatedBundleIds.has(bundleId)) {
-            socket.write(
-              JSON.stringify({
-                type: "Control",
-                payload: { command: "activateNetworkInspection" }
-              }) + "\n"
-            );
+      attachNdjsonReader(socket, {
+        onDropped: reportDroppedFrameToStderr(`native-devtools ${udid.slice(0, 8)}`),
+        onMessage: (parsed) => {
+          const msg = parsed;
+          if (bundleId === null) {
+            if (msg.type !== "Control") return;
+            bundleId = msg.payload.bundleId;
+            const existing = connections2.get(bundleId);
+            if (existing) {
+              existing.socket.destroy();
+            }
+            connections2.set(bundleId, { socket, networkLog: [] });
+            if (activatedBundleIds.has(bundleId)) {
+              socket.write(
+                JSON.stringify({
+                  type: "Control",
+                  payload: { command: "activateNetworkInspection" }
+                }) + "\n"
+              );
+            }
+            return;
           }
-          return;
-        }
-        if (msg.type === "CDP") {
-          const p = msg.payload;
-          if (p.method && p.id === void 0) {
-            const conn = connections2.get(bundleId);
-            if (conn) {
-              if (conn.networkLog.length >= MAX_LOG_ENTRIES) {
-                conn.networkLog.shift();
+          if (msg.type === "CDP") {
+            const p = msg.payload;
+            if (p.method && p.id === void 0) {
+              const conn = connections2.get(bundleId);
+              if (conn) {
+                if (conn.networkLog.length >= MAX_LOG_ENTRIES) {
+                  conn.networkLog.shift();
+                }
+                conn.networkLog.push({
+                  method: p.method,
+                  params: p.params,
+                  timestamp: Date.now()
+                });
               }
-              conn.networkLog.push({
-                method: p.method,
-                params: p.params,
-                timestamp: Date.now()
-              });
             }
           }
-        }
-        if (msg.type === "ViewInspector") {
-          const p = msg.payload;
-          const pending = pendingRpc.get(p.id);
-          if (!pending) return;
-          pendingRpc.delete(p.id);
-          if (p.error) {
-            pending.reject(
-              new FailureError(p.error.message, {
-                error_code: FAILURE_CODES.NATIVE_DEVTOOLS_RPC_ERROR,
-                failure_stage: "native_devtools_rpc_response",
-                failure_area: "tool_server",
-                error_kind: "subprocess"
-              })
-            );
-          } else pending.resolve(p.result);
+          if (msg.type === "ViewInspector") {
+            const p = msg.payload;
+            const pending = pendingRpc.get(p.id);
+            if (!pending) return;
+            pendingRpc.delete(p.id);
+            if (p.error) {
+              pending.reject(
+                new FailureError(p.error.message, {
+                  error_code: FAILURE_CODES.NATIVE_DEVTOOLS_RPC_ERROR,
+                  failure_stage: "native_devtools_rpc_response",
+                  failure_area: "tool_server",
+                  error_kind: "subprocess"
+                })
+              );
+            } else pending.resolve(p.result);
+          }
         }
       });
       socket.on("close", () => {
-        rl.close();
         if (bundleId !== null) {
           if (connections2.get(bundleId)?.socket === socket) {
             connections2.delete(bundleId);
@@ -109994,22 +110156,28 @@ async function describeIos(registry2, device, params, options = {}) {
   if (isTvOs) {
     return { tree: emptyTree(), source: "ax-service", hint: TVOS_HINT };
   }
-  let tree;
+  let tree = emptyTree();
   let degraded;
   let resolverHint;
+  let readFailureHint;
+  let axApi;
   try {
     const axRef = axServiceRef(device);
-    const axApi = await registry2.resolveService(axRef.urn, axRef.options);
-    const response = await axApi.describe();
-    tree = adaptAXDescribeToDescribeResult(response);
+    axApi = await registry2.resolveService(axRef.urn, axRef.options);
     degraded = axApi.degraded;
   } catch (err) {
-    tree = emptyTree();
     resolverHint = tcpArtifactHint(err);
     degraded = resolverHint === void 0;
   }
+  if (axApi) {
+    try {
+      tree = adaptAXDescribeToDescribeResult(await axApi.describe());
+    } catch (err) {
+      readFailureHint = `The accessibility read failed (${errMsg(err)}).`;
+    }
+  }
   const degradedHint = !degraded ? void 0 : tree.children.length === 0 ? DEGRADED_BLIND_HINT : DEGRADED_STANDING_HINT;
-  const hint = resolverHint ?? degradedHint;
+  const hint = resolverHint ?? (readFailureHint ? degradedHint ? `${degradedHint}. ${readFailureHint}` : readFailureHint : degradedHint);
   if (tree.children.length > 0) {
     return { tree, source: "ax-service", hint };
   }
@@ -110501,7 +110669,7 @@ function parseUiAutomatorDump(rawOutput, screenW, screenH, options = {}) {
 
 // ../tool-server/src/blueprints/android-devtools.ts
 var import_node_child_process13 = require("node:child_process");
-var readline5 = __toESM(require("node:readline"));
+var readline2 = __toESM(require("node:readline"));
 init_src();
 
 // ../native-devtools-android/src/index.ts
@@ -110898,7 +111066,6 @@ async function ensureAndroidDevtoolsInstalled(serial) {
 
 // ../tool-server/src/utils/android-devtools-client.ts
 var net3 = __toESM(require("node:net"));
-var readline4 = __toESM(require("node:readline"));
 init_src();
 var DEFAULT_RPC_TIMEOUT_MS = 5e3;
 var LONG_RPC_TIMEOUT_MS = 15e3;
@@ -110932,36 +111099,32 @@ function connectAndroidDevtoolsClient(localPort, onTerminated) {
       onTerminated(error52);
     };
     socket.once("connect", () => {
-      const rl = readline4.createInterface({ input: socket });
-      rl.on("line", (line) => {
-        if (!line.trim()) return;
-        let parsed;
-        try {
-          parsed = JSON.parse(line);
-        } catch {
-          return;
-        }
-        if (typeof parsed.id !== "number") return;
-        const req = pending.get(parsed.id);
-        if (!req) return;
-        pending.delete(parsed.id);
-        clearTimeout(req.timer);
-        if (parsed.error) {
-          const message = parsed.error.message ?? "Unknown helper error";
-          const type = parsed.error.type ?? "HelperError";
-          req.reject(
-            new FailureError(`${type}: ${message}`, {
-              error_code: FAILURE_CODES.ANDROID_DEVTOOLS_RPC_ERROR,
-              failure_stage: "android_devtools_rpc_response",
-              failure_area: "tool_server",
-              error_kind: "subprocess"
-            })
-          );
-        } else {
-          req.resolve(parsed.result);
+      attachNdjsonReader(socket, {
+        onDropped: reportDroppedFrameToStderr("android-devtools"),
+        onMessage: (raw) => {
+          const parsed = raw;
+          if (typeof parsed.id !== "number") return;
+          const req = pending.get(parsed.id);
+          if (!req) return;
+          pending.delete(parsed.id);
+          clearTimeout(req.timer);
+          if (parsed.error) {
+            const message = parsed.error.message ?? "Unknown helper error";
+            const type = parsed.error.type ?? "HelperError";
+            req.reject(
+              new FailureError(`${type}: ${message}`, {
+                error_code: FAILURE_CODES.ANDROID_DEVTOOLS_RPC_ERROR,
+                failure_stage: "android_devtools_rpc_response",
+                failure_area: "tool_server",
+                error_kind: "subprocess"
+              })
+            );
+          } else {
+            req.resolve(parsed.result);
+          }
         }
       });
-      rl.on("close", () => cleanup());
+      socket.on("close", () => cleanup());
       resolve12({
         request(method, params = {}) {
           const send = () => {
@@ -111076,7 +111239,7 @@ async function spawnHelper(serial) {
       cleanup?.();
       fn();
     };
-    const rl = readline5.createInterface({ input: proc.stdout });
+    const rl = readline2.createInterface({ input: proc.stdout });
     rl.on("line", async (rawLine) => {
       const line = rawLine.trim();
       const portMatch = HELPER_PORT_MARKER.exec(line);
@@ -116837,13 +117000,7 @@ var zodSchema9 = external_exports.object({
 function bootTarget(params) {
   return params.udid ?? params.avdName ?? params.vvdImage ?? params.electronAppPath ?? "device";
 }
-var LAUNCH_HARDENING_ARGS = [
-  "-no-boot-anim",
-  "-netfast",
-  "-crash-report-mode",
-  "never",
-  "-no-metrics"
-];
+var LAUNCH_HARDENING_ARGS = ["-no-boot-anim", "-netfast", "-no-metrics"];
 function launchHardeningArgs(sound) {
   return sound ? [...LAUNCH_HARDENING_ARGS] : ["-noaudio", ...LAUNCH_HARDENING_ARGS];
 }
@@ -117357,7 +117514,7 @@ async function bootAndroidImpl(params) {
   } else {
     const RENDERER_ARGS = ["-gpu", gpuMode, ...extraEmulatorArgs];
     const probe3 = await checkSnapshotLoadable(params.avdName, "default_boot", {
-      extraArgs: [...RENDERER_ARGS, ...hardeningArgs]
+      extraArgs: [...RENDERER_ARGS, ...hardeningArgs, ...crashReportArgs]
     });
     if (!probe3.loadable) {
       hotBootFailureReason = `-check-snapshot-loadable: ${probe3.reason ?? "unknown"}`;
@@ -119392,7 +119549,7 @@ Before tapping, determine the correct coordinates by using discovery tools \u201
     const api = services.simulatorServer;
     for (let i = 1; i <= clickCount; i++) {
       if (i > 1) await sleep2(MULTI_TAP_GAP_MS);
-      sendCommand(api, {
+      await sendCommand(api, {
         cmd: "touch",
         type: "Down",
         x: params.x,
@@ -119401,7 +119558,7 @@ Before tapping, determine the correct coordinates by using discovery tools \u201
         second_y: null
       });
       await sleep2(TAP_HOLD_MS);
-      sendCommand(api, {
+      await sendCommand(api, {
         cmd: "touch",
         type: "Up",
         x: params.x,
@@ -119417,18 +119574,39 @@ Before tapping, determine the correct coordinates by using discovery tools \u201
 // ../tool-server/src/tools/gesture-swipe/index.ts
 init_zod();
 var sleep3 = (ms) => new Promise((r) => setTimeout(r, ms));
-var SETTLE_EASE_EXPONENT = 3;
+var MOMENTUM_FREE_EASE_EXPONENT = 3;
+var DEFAULT_DURATION_MS = 300;
+var MOMENTUM_FREE_MIN_DURATION_MS = 150;
+var MAX_DURATION_MS = 1e4;
 var zodSchema17 = external_exports.object({
   udid: external_exports.string().describe("Target device id from `list-devices` (iOS UDID or Android serial)."),
   fromX: external_exports.number().describe("Start x: normalized 0.0\u20131.0 (not pixels; same as tap)"),
   fromY: external_exports.number().describe("Start y: normalized 0.0\u20131.0 (not pixels; same as tap)"),
   toX: external_exports.number().describe("End x: normalized 0.0\u20131.0 (not pixels; same as tap)"),
   toY: external_exports.number().describe("End y: normalized 0.0\u20131.0 (not pixels; same as tap)"),
-  durationMs: external_exports.number().optional().describe("Total gesture duration in milliseconds (default 300)"),
-  settle: external_exports.boolean().optional().describe(
-    "Momentum-free swipe: decelerate into the end point (ease-out) so the OS reads ~0 release velocity and applies little to no fling. Use for scroll-to-element loops; default false (a natural flinging swipe)."
+  durationMs: external_exports.number().max(MAX_DURATION_MS, {
+    message: `durationMs must be at most ${MAX_DURATION_MS} (10s): every frame is a real 16ms sleep with the finger held down, so a larger value is that many milliseconds of wall clock spent holding a touch the device cannot shake off.`
+  }).optional().describe(
+    `Total gesture duration in milliseconds (default 300, at most ${MAX_DURATION_MS} - the gesture holds a finger down for exactly this long)`
+  ),
+  momentum: external_exports.boolean().optional().describe(
+    `Whether the swipe releases with momentum; default true (a natural flinging swipe). Pass false for a momentum-free swipe at the default durationMs: the finger decelerates into the end point (ease-out) so the OS reads ~0 release velocity and applies little to no fling. Use false for scroll-to-element loops. momentum: false needs durationMs >= ${MOMENTUM_FREE_MIN_DURATION_MS} and is rejected below it: a shorter ease-out gives the OS velocity fit too little wall clock to read the deceleration as a stop, and it flings harder than a plain swipe instead (on Android, backwards). At ${MOMENTUM_FREE_MIN_DURATION_MS} itself the swipe lands short of where the finger stopped, and 2 of 47 runs still flung backwards.`
+  ),
+  // `momentum`'s shipped spelling, with the opposite polarity. Declared so this
+  // non-strict object refuses it instead of stripping it and flinging - the exact
+  // inverse of the gesture the caller asked for.
+  settle: external_exports.never({
+    error: "gesture-swipe's `settle` was renamed to `momentum`, with the opposite sense \u2014 write `momentum: false` for the momentum-free swipe that `settle: true` used to mean (plain `settle: false` was the default, so just drop it)"
+  }).optional().describe(
+    "Retired: renamed to `momentum` with the opposite sense. Pass `momentum: false` for what `settle: true` meant; `settle: false` was the default, so drop the key."
   )
-});
+}).refine(
+  (p) => p.momentum !== false || (p.durationMs ?? DEFAULT_DURATION_MS) >= MOMENTUM_FREE_MIN_DURATION_MS,
+  {
+    message: `momentum: false needs durationMs of at least ${MOMENTUM_FREE_MIN_DURATION_MS}: below that the ease-out has too little wall clock for the OS velocity fit to read it as a stop rather than a flick, so it flings harder than a plain swipe and, on Android, backwards. Raise durationMs, or drop momentum: false for a plain flinging swipe at the duration you asked for.`,
+    path: ["durationMs"]
+  }
+);
 var capability9 = {
   apple: { simulator: true, device: true },
   appleRemote: { simulator: true },
@@ -119441,11 +119619,13 @@ var gestureSwipeTool = {
     completedMsg: ({ params }) => `Swiped from (${Math.round(params.fromX * 100)}%, ${Math.round(params.fromY * 100)}%) to (${Math.round(params.toX * 100)}%, ${Math.round(params.toY * 100)}%)`,
     failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to swipe: ${failureSignal2.error_code}`
   },
+  // The bounds are spelled out rather than interpolated: extract-tools scans this
+  // description statically, so a `${}` in it drops the tool out of the scan.
   description: `Execute a smooth swipe / drag touch gesture between two points on the device (iOS simulator or Android emulator). All from/to positions are normalized 0.0\u20131.0 (fractions of screen width/height, not pixels), same as gesture-tap.
 Generates interpolated Move events for a natural feel (~60fps).
 Swipe up (fromY > toY) to scroll content down.
 Use when you need to scroll a list, dismiss a modal, drag an element, or navigate between pages. Not supported on Chromium \u2014 use gesture-scroll there instead.
-Pass settle:true for a momentum-free swipe that lands exactly where the finger lifts (no fling), when you need a deterministic scroll distance. Returns { swiped: true, timestampMs }. Fails if the simulator-server / emulator backend is not reachable for the given device.`,
+Pass momentum:false for a momentum-free swipe that lands where the finger lifts (little to no fling at the 300 default), when you need a deterministic scroll distance; it needs durationMs >= 150 and is rejected below that, a shorter ease-out leaving the OS too little wall clock to read the deceleration as a stop. At 150 it lands short of the lift point instead, and 2 of 47 runs still flung backwards. A plain swipe takes any duration up to 10000ms and is delivered as close to the speed it was authored as a 16ms frame allows: below ~32ms the whole travel lands in one or two frames, which the OS flings as hard as it flings anything. Returns { swiped: true, timestampMs }. Fails if the simulator-server / emulator backend is not reachable for the given device.`,
   alwaysLoad: true,
   searchHint: "swipe scroll drag pan gesture device simulator emulator touch move",
   zodSchema: zodSchema17,
@@ -119453,19 +119633,52 @@ Pass settle:true for a momentum-free swipe that lands exactly where the finger l
   services: (params) => ({
     simulatorServer: simulatorServerRef(resolveDevice(params.udid))
   }),
-  async execute(services, params) {
-    const duration3 = params.durationMs ?? 300;
-    const settle = params.settle ?? false;
+  async execute(services, params, ctx) {
+    const duration3 = params.durationMs ?? DEFAULT_DURATION_MS;
+    const momentumFree = params.momentum === false;
     const timestampMs = Date.now();
     const api = services.simulatorServer;
     const steps = Math.max(1, Math.round(duration3 / 16));
+    let lastX = 0;
+    let lastY = 0;
     for (let i = 0; i <= steps; i++) {
+      if (ctx?.signal?.aborted) {
+        const err = new Error(
+          `gesture-swipe aborted - cancelled mid-gesture after ${i} of ${steps + 1} frames`
+        );
+        err.name = "AbortError";
+        if (i > 0) {
+          try {
+            await sendCommand(api, {
+              cmd: "touch",
+              type: "Up",
+              x: lastX,
+              y: lastY,
+              second_x: null,
+              second_y: null
+            });
+          } catch (liftErr) {
+            err.cause = liftErr;
+          }
+        }
+        throw err;
+      }
       const t = i / steps;
-      const progress = settle ? 1 - Math.pow(1 - t, SETTLE_EASE_EXPONENT) : t;
+      const progress = momentumFree ? 1 - Math.pow(1 - t, MOMENTUM_FREE_EASE_EXPONENT) : t;
       const x = params.fromX + (params.toX - params.fromX) * progress;
       const y = params.fromY + (params.toY - params.fromY) * progress;
       const type = i === 0 ? "Down" : i === steps ? "Up" : "Move";
-      sendCommand(api, {
+      if (type === "Up") {
+        await sendCommand(api, {
+          cmd: "touch",
+          type: "Move",
+          x,
+          y,
+          second_x: null,
+          second_y: null
+        });
+      }
+      await sendCommand(api, {
         cmd: "touch",
         type,
         x,
@@ -119473,6 +119686,8 @@ Pass settle:true for a momentum-free swipe that lands exactly where the finger l
         second_x: null,
         second_y: null
       });
+      lastX = x;
+      lastY = y;
       if (i < steps) await sleep3(16);
     }
     return { swiped: true, timestampMs };
@@ -119548,13 +119763,30 @@ Returns { scrolled: true, timestampMs }. Fails if the Chromium CDP session is no
 // ../tool-server/src/tools/gesture-drag/index.ts
 init_zod();
 var sleep5 = (ms) => new Promise((r) => setTimeout(r, ms));
+var MOMENTUM_FREE_EASE_EXPONENT2 = 3;
+var MOMENTUM_FREE_MIN_STEPS = 8;
+var MAX_DURATION_MS2 = 1e4;
 var zodSchema19 = external_exports.object({
   udid: external_exports.string().describe("Target Chromium device id from `list-devices` (chromium-cdp-<port>)."),
   fromX: external_exports.number().describe("Press x: normalized 0.0\u20131.0 (fraction of window width, not pixels)."),
   fromY: external_exports.number().describe("Press y: normalized 0.0\u20131.0 (fraction of window height, not pixels)."),
   toX: external_exports.number().describe("Release x: normalized 0.0\u20131.0 (not pixels; same space as tap)."),
   toY: external_exports.number().describe("Release y: normalized 0.0\u20131.0 (not pixels; same space as tap)."),
-  durationMs: external_exports.number().optional().describe("Total drag duration in milliseconds (default 300), interpolated at ~60fps.")
+  durationMs: external_exports.number().max(MAX_DURATION_MS2, {
+    message: `durationMs must be at most ${MAX_DURATION_MS2} (10s): the drag holds the left button down for exactly this long, one frame per ~16ms, so a larger value is that much wall clock spent mid-press.`
+  }).optional().describe(
+    `Total drag duration in milliseconds (default 300, at most ${MAX_DURATION_MS2} - the button stays down for exactly this long), interpolated at ~60fps.`
+  ),
+  momentum: external_exports.boolean().optional().describe(
+    "Whether the drag releases with momentum; default true (a constant-speed drag). Pass false to decelerate into the release point (ease-out) so an app deriving fling from pointer release velocity (carousels, drag libraries) reads ~0 and applies little to no momentum \u2014 use it when the drag must stop where it was aimed rather than fling past. Deceleration needs wall clock: under ~100ms the whole drag fits inside the velocity window a page averages over (tens of ms), so some fling survives, and under ~70ms its extra frames cannot dispatch fast enough to fit durationMs. Keep durationMs at its default when the fling must be fully suppressed."
+  ),
+  // `momentum`'s earlier spelling, with the opposite polarity. Declared so this
+  // non-strict object refuses it instead of stripping it and running the default.
+  settle: external_exports.never({
+    error: "gesture-drag's `settle` was renamed to `momentum`, with the opposite sense - write `momentum: false` for the momentum-free drag that `settle: true` used to mean (plain `settle: false` was the default, so just drop it)"
+  }).optional().describe(
+    "Retired: renamed to `momentum` with the opposite sense. Pass `momentum: false` for what `settle: true` meant; `settle: false` was the default, so drop the key."
+  )
 });
 var capability11 = {
   chromium: { app: true }
@@ -119566,9 +119798,9 @@ var gestureDragTool = {
     completedMsg: ({ params }) => `Dragged from (${Math.round(params.fromX * 100)}%, ${Math.round(params.fromY * 100)}%) to (${Math.round(params.toX * 100)}%, ${Math.round(params.toY * 100)}%)`,
     failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to drag: ${failureSignal2.error_code}`
   },
-  description: `Press the left mouse button at a start point, move to an end point, and release \u2014 a desktop mouse drag in a Chromium app. All positions are normalized 0.0\u20131.0 (fractions of the window, not pixels), same coordinate space as gesture-tap and describe. Interpolates mouse-move events at ~60fps over durationMs for a natural drag.
+  description: `Press the left mouse button at a start point, move to an end point, and release \u2014 a desktop mouse drag in a Chromium app. All positions are normalized 0.0\u20131.0 (fractions of the window, not pixels), same coordinate space as gesture-tap and describe, except that a coordinate of exactly 1.0 lands one pixel inside the window edge (gesture-tap maps it to the edge itself). Interpolates mouse-move events at ~60fps over durationMs for a natural drag (a momentum-free drag samples more finely when durationMs is short, so its ease-out has a curve).
 Use for slider thumbs, drag-and-drop, text selection, or draggable UI elements. Dragging never scrolls content on desktop \u2014 use gesture-scroll for lists/pages. Chromium only \u2014 on iOS/Android use gesture-swipe.
-Returns { dragged: true, timestampMs }. Fails if the Chromium CDP session is not reachable for the given device.`,
+Pass momentum:false for a momentum-free drag that decelerates into the release, so apps that compute a fling from the pointer stream read ~0 velocity and the drag ends where it was aimed instead of flinging past it (a durationMs under ~100ms is too short for the deceleration to suppress the fling entirely). Returns { dragged: true, timestampMs }. Fails if the Chromium CDP session is not reachable for the given device.`,
   alwaysLoad: true,
   searchHint: "drag drop slider mouse press move release chromium select",
   zodSchema: zodSchema19,
@@ -119576,15 +119808,49 @@ Returns { dragged: true, timestampMs }. Fails if the Chromium CDP session is not
   services: (params) => ({
     chromium: chromiumCdpRef(resolveDevice(params.udid))
   }),
-  async execute(services, params) {
+  async execute(services, params, ctx) {
     const timestampMs = Date.now();
     const chromium = services.chromium;
     await assertChromiumWindowVisible(chromium, "drag", "chromium_drag_window_hidden");
     const vp = chromium.getViewport();
-    const startPx = { x: params.fromX * vp.width, y: params.fromY * vp.height };
-    const endPx = { x: params.toX * vp.width, y: params.toY * vp.height };
+    const clampPx2 = (px, size) => Math.min(Math.max(px, 0), size - 1);
+    const startPx = {
+      x: clampPx2(params.fromX * vp.width, vp.width),
+      y: clampPx2(params.fromY * vp.height, vp.height)
+    };
+    const endPx = {
+      x: clampPx2(params.toX * vp.width, vp.width),
+      y: clampPx2(params.toY * vp.height, vp.height)
+    };
     const durationMs = params.durationMs ?? 300;
-    const steps = Math.max(2, Math.round(durationMs / 16));
+    const momentumFree = params.momentum === false;
+    const steps = Math.max(momentumFree ? MOMENTUM_FREE_MIN_STEPS : 2, Math.round(durationMs / 16));
+    const frameMs = durationMs / steps;
+    const t0 = Date.now();
+    let lastX = startPx.x;
+    let lastY = startPx.y;
+    const abortError = (frame) => {
+      const err = new Error(
+        `gesture-drag aborted - cancelled mid-drag after ${frame} of ${steps + 1} frames`
+      );
+      err.name = "AbortError";
+      return err;
+    };
+    const releaseAndAbort = async (frame) => {
+      const err = abortError(frame);
+      try {
+        await chromium.dispatchMouseEvent({
+          type: "mouseReleased",
+          x: lastX,
+          y: lastY,
+          clickCount: 1
+        });
+      } catch (releaseErr) {
+        err.cause = releaseErr;
+      }
+      throw err;
+    };
+    if (ctx?.signal?.aborted) throw abortError(0);
     await chromium.dispatchMouseEvent({
       type: "mousePressed",
       x: startPx.x,
@@ -119592,15 +119858,19 @@ Returns { dragged: true, timestampMs }. Fails if the Chromium CDP session is not
       clickCount: 1
     });
     for (let i = 1; i < steps; i++) {
+      if (ctx?.signal?.aborted) await releaseAndAbort(i);
+      await sleep5(Math.max(0, t0 + i * frameMs - Date.now()));
       const t = i / steps;
-      await chromium.dispatchMouseEvent({
-        type: "mouseMoved",
-        x: startPx.x + (endPx.x - startPx.x) * t,
-        y: startPx.y + (endPx.y - startPx.y) * t,
-        button: "left"
-      });
-      await sleep5(16);
-    }
+      const progress = momentumFree ? 1 - Math.pow(1 - t, MOMENTUM_FREE_EASE_EXPONENT2) : t;
+      const x = startPx.x + (endPx.x - startPx.x) * progress;
+      const y = startPx.y + (endPx.y - startPx.y) * progress;
+      await chromium.dispatchMouseEvent({ type: "mouseMoved", x, y, button: "left" });
+      lastX = x;
+      lastY = y;
+    }
+    if (ctx?.signal?.aborted) await releaseAndAbort(steps);
+    await sleep5(Math.max(0, t0 + durationMs - Date.now()));
+    if (ctx?.signal?.aborted) await releaseAndAbort(steps);
     await chromium.dispatchMouseEvent({
       type: "mouseReleased",
       x: endPx.x,
@@ -119651,7 +119921,7 @@ function interpolateEvents(events, steps) {
   return result;
 }
 function sendTouchEvent(api, type, x, y, x2, y2) {
-  sendCommand(api, {
+  return sendCommand(api, {
     cmd: "touch",
     type,
     x,
@@ -119722,7 +119992,7 @@ Example pinch-to-zoom (with interpolate:10 for smoothness):
     const events = params.interpolate && params.interpolate > 0 ? interpolateEvents(params.events, params.interpolate) : params.events;
     for (const event2 of events) {
       await sleep6(event2.delayMs ?? 16);
-      sendCommand(api, {
+      await sendCommand(api, {
         cmd: "touch",
         type: event2.type,
         x: event2.x,
@@ -119805,7 +120075,7 @@ Use when you need to zoom in or out on a map, image, or zoomable view. Returns {
       const y2 = cy + halfDist * sinA;
       const type = i === 0 ? "Down" : i === steps ? "Up" : "Move";
       if (i === 0) timestampMs = Date.now();
-      sendTouchEvent(api, type, x1, y1, x2, y2);
+      await sendTouchEvent(api, type, x1, y1, x2, y2);
       if (i < steps) await sleep(16);
     }
     return { pinched: true, timestampMs };
@@ -119883,11 +120153,17 @@ Size the orbit with radius, or with radiusX and radiusY together (the pair overr
     let lastY2 = 0;
     for (let i = 0; i <= steps; i++) {
       if (ctx?.signal?.aborted) {
-        if (i > 0) sendTouchEvent(api, "Up", lastX1, lastY1, lastX2, lastY2);
         const err = new Error(
           `gesture-rotate aborted \u2014 cancelled mid-gesture after ${i} of ${steps + 1} frames`
         );
         err.name = "AbortError";
+        if (i > 0) {
+          try {
+            await sendTouchEvent(api, "Up", lastX1, lastY1, lastX2, lastY2);
+          } catch (liftErr) {
+            err.cause = liftErr;
+          }
+        }
         throw err;
       }
       const t = i / steps;
@@ -119899,7 +120175,7 @@ Size the orbit with radius, or with radiusX and radiusY together (the pair overr
       const y2 = params.centerY - radiusY * Math.sin(angleRad);
       const type = i === 0 ? "Down" : i === steps ? "Up" : "Move";
       if (i === 0) timestampMs = Date.now();
-      sendTouchEvent(api, type, x1, y1, x2, y2);
+      await sendTouchEvent(api, type, x1, y1, x2, y2);
       lastX1 = x1;
       lastY1 = y1;
       lastX2 = x2;
@@ -119968,13 +120244,13 @@ Fails if the device backend is not reachable \u2014 the simulator-server for iOS
       return { pressed: params.button };
     }
     const api = services.simulatorServer;
-    sendCommand(api, {
+    await sendCommand(api, {
       cmd: "button",
       direction: "Down",
       button: params.button
     });
     await sleep7(50);
-    sendCommand(api, { cmd: "button", direction: "Up", button: params.button });
+    await sendCommand(api, { cmd: "button", direction: "Up", button: params.button });
     return { pressed: params.button };
   }
 };
@@ -120785,7 +121061,7 @@ Returns { orientation }. Fails if the target device is not booted.`,
   }),
   async execute(services, params) {
     const api = services.simulatorServer;
-    sendCommand(api, { cmd: "rotate", direction: params.orientation });
+    await sendCommand(api, { cmd: "rotate", direction: params.orientation });
     return { orientation: params.orientation };
   }
 };
@@ -127820,9 +128096,9 @@ a prior tap), use individual tool calls instead.
 Allowed tools and their args (udid is auto-injected, do NOT include it in args):
 
   gesture-tap:    { x: number, y: number, clickCount?: number }                                                        [ios/android/chromium]
-  gesture-swipe:  { fromX: number, fromY: number, toX: number, toY: number, durationMs?: number }                       [ios/android]
+  gesture-swipe:  { fromX: number, fromY: number, toX: number, toY: number, durationMs?: number, momentum?: boolean }   [ios/android]
   gesture-scroll: { x: number, y: number, deltaX?: number, deltaY?: number, durationMs?: number }                       [chromium only]
-  gesture-drag:   { fromX: number, fromY: number, toX: number, toY: number, durationMs?: number }                       [chromium only]
+  gesture-drag:   { fromX: number, fromY: number, toX: number, toY: number, durationMs?: number, momentum?: boolean }   [chromium only]
   gesture-custom: { events: [{ type: "Down"|"Move"|"Up", x: number, y: number, x2?: number, y2?: number, delayMs?: number }], interpolate?: number }  [ios/android]
   gesture-pinch:  { centerX: number, centerY: number, startDistance: number, endDistance: number, endCenterX?: number, endCenterY?: number, angle?: number, durationMs?: number }  [ios/android]
   gesture-rotate: { centerX: number, centerY: number, radius?: number, radiusX?: number, radiusY?: number, startAngle: number, endAngle: number, durationMs?: number }  [ios/android]
@@ -140883,6 +141159,12 @@ function chromiumLaunchSpec(launch) {
   return typeof c === "string" ? { path: c } : { path: c.path, args: c.args };
 }
 function selectorToYaml(sel) {
+  const unknown2 = Object.keys(sel).filter((key2) => !WRITABLE_SELECTOR_KEYS.includes(key2));
+  if (unknown2.length > 0) {
+    throw new Error(
+      `Cannot serialize flow selector: ${describeUnknownKeys(unknown2, WRITABLE_SELECTOR_KEYS)} - allowed keys: ${WRITABLE_SELECTOR_KEYS.join(", ")}.`
+    );
+  }
   if (sel.text !== void 0 && sel.textMatches !== void 0) {
     throw new Error(
       'Cannot serialize flow selector without losing constraints: both `text` and `textMatches` are set, but flow YAML can represent only one `text` constraint (a literal string or `{ matches: "<regex>" }`). Use either literal or regex text matching.'
@@ -141005,6 +141287,79 @@ function targetToYaml(step) {
   }
   return { x: step.x, y: step.y };
 }
+function swipeTargetToYaml(target, label) {
+  const yaml = targetToYaml(target);
+  if (typeof yaml !== "string" && "x" in yaml && !Object.keys(target).every((key2) => key2 === "x" || key2 === "y")) {
+    throw new Error(`Cannot serialize flow ${label}: a coordinate target takes only { x, y }`);
+  }
+  return yaml;
+}
+var SWIPE_MIN_TRAVEL = 0.03;
+var SWIPE_MIN_DURATION_MS = 150;
+var SWIPE_MAX_DURATION_MS = 1e4;
+var LONG_PRESS_MAX_DURATION_MS = SWIPE_MAX_DURATION_MS;
+function swipeByToYaml(by) {
+  const keys = Object.keys(by);
+  if (keys.some((key2) => key2 !== "x" && key2 !== "y")) {
+    throw new Error("Cannot serialize flow swipe.by: accepts only x and y");
+  }
+  const axes = ["x", "y"].filter((axis) => by[axis] !== void 0);
+  if (axes.length === 0) {
+    throw new Error("Cannot serialize flow swipe.by: needs at least one of x or y");
+  }
+  const result = {};
+  for (const axis of axes) {
+    const value = by[axis];
+    if (!Number.isFinite(value) || value === 0 || value < -1 || value > 1) {
+      throw new Error(
+        `Cannot serialize flow swipe.by.${axis}: must be a non-zero fraction of the screen between -1 and 1`
+      );
+    }
+    result[axis] = value;
+  }
+  const magnitude = Math.hypot(result.x ?? 0, result.y ?? 0);
+  if (magnitude < SWIPE_MIN_TRAVEL) {
+    throw new Error(
+      `Cannot serialize flow swipe.by: travels only ${magnitude} \u2014 below the minimum swipe travel of ${SWIPE_MIN_TRAVEL} \u2014 a travel that small is a tap, not a swipe`
+    );
+  }
+  return result;
+}
+function swipeByLabel(by) {
+  return ["x", "y"].filter((axis) => by[axis] !== void 0).map((axis) => `${axis}=${by[axis]}`).join(", ");
+}
+function isPositiveMs(raw) {
+  return typeof raw === "number" && Number.isFinite(raw) && raw > 0;
+}
+function positiveMsToYaml(value, label) {
+  if (!isPositiveMs(value)) {
+    throw new Error(`Cannot serialize flow ${label}: needs a positive number of milliseconds`);
+  }
+  return value;
+}
+function swipeDurationToYaml(value) {
+  const duration3 = positiveMsToYaml(value, "swipe.duration");
+  if (duration3 < SWIPE_MIN_DURATION_MS) {
+    throw new Error(
+      `Cannot serialize flow swipe.duration: only ${duration3}ms \u2014 below the minimum swipe duration of ${SWIPE_MIN_DURATION_MS}ms \u2014 that leaves too few 16ms frames for the content to track the travel it was given, so it overshoots instead of landing on it`
+    );
+  }
+  if (duration3 > SWIPE_MAX_DURATION_MS) {
+    throw new Error(
+      `Cannot serialize flow swipe.duration: ${duration3}ms - above the maximum swipe duration of ${SWIPE_MAX_DURATION_MS}ms - the step would hold a finger on the screen for exactly that long, one dispatched frame per 16ms`
+    );
+  }
+  return duration3;
+}
+function longPressDurationToYaml(value) {
+  const duration3 = positiveMsToYaml(value, "long-press.duration");
+  if (duration3 > LONG_PRESS_MAX_DURATION_MS) {
+    throw new Error(
+      `Cannot serialize flow long-press.duration: ${duration3}ms - above the maximum long-press duration of ${LONG_PRESS_MAX_DURATION_MS}ms - the step would hold a finger down for exactly that long`
+    );
+  }
+  return duration3;
+}
 function waitToYaml(condition, selector, expectedText, textMatch, timeoutMs) {
   const sel = selectorToYaml(selector);
   let body;
@@ -141022,7 +141377,7 @@ function waitToYaml(condition, selector, expectedText, textMatch, timeoutMs) {
       body = textWaitToYaml(sel, expectedText, textMatch);
       break;
   }
-  if (timeoutMs !== void 0) body.timeout = timeoutMs;
+  if (timeoutMs !== void 0) body.timeout = positiveMsToYaml(timeoutMs, "await.timeout");
   return body;
 }
 function idleToYaml(step) {
@@ -141058,9 +141413,29 @@ function toYamlStep(step) {
     case "long-press": {
       const target = targetToYaml(step);
       return {
-        "long-press": step.duration !== void 0 ? { on: target, duration: step.duration } : target
+        "long-press": step.duration !== void 0 ? { on: target, duration: longPressDurationToYaml(step.duration) } : target
       };
     }
+    case "swipe": {
+      const travels = ["direction", "to", "by"].filter((key2) => step[key2] !== void 0);
+      if (travels.length !== 1) {
+        throw new Error("Cannot serialize flow swipe: needs exactly one of direction, to, or by");
+      }
+      if (step.momentum !== void 0 && typeof step.momentum !== "boolean") {
+        throw new Error("Cannot serialize flow swipe.momentum: must be true or false");
+      }
+      if (step.direction !== void 0 && step.from === void 0 && step.to === void 0 && step.by === void 0 && step.momentum !== false && step.duration === void 0) {
+        return { swipe: step.direction };
+      }
+      const body = {};
+      if (step.from !== void 0) body.from = swipeTargetToYaml(step.from, "swipe.from");
+      if (step.direction !== void 0) body.direction = step.direction;
+      if (step.to !== void 0) body.to = swipeTargetToYaml(step.to, "swipe.to");
+      if (step.by !== void 0) body.by = swipeByToYaml(step.by);
+      if (step.momentum === false) body.momentum = false;
+      if (step.duration !== void 0) body.duration = swipeDurationToYaml(step.duration);
+      return { swipe: body };
+    }
     case "type": {
       const body = {
         into: selectorToYaml(step.into),
@@ -141153,6 +141528,12 @@ function badEntry(raw, detail) {
     error_kind: "validation"
   });
 }
+function parsePositiveMs(raw, entry, label, example) {
+  if (!isPositiveMs(raw)) {
+    badEntry(entry, `${label} needs a positive number of milliseconds (e.g. \`${example}\`)`);
+  }
+  return raw;
+}
 function validatePattern(raw, pattern, where) {
   try {
     new RegExp(pattern);
@@ -141216,6 +141597,17 @@ var SELECTOR_KEYS = [
   "any",
   ...SELECTOR_RELATIONS
 ];
+var WRITABLE_SELECTOR_KEYS = Object.keys({
+  text: true,
+  textMatches: true,
+  identifier: true,
+  role: true,
+  any: true,
+  loose: true,
+  within: true,
+  after: true,
+  next: true
+});
 var MAX_SELECTOR_SCOPES = 6;
 function parseSelector(raw, where, budget = { scopes: MAX_SELECTOR_SCOPES }) {
   if (budget.scopes < 0) {
@@ -141346,7 +141738,7 @@ function parseWaitFields(raw, kind) {
         "assert has no timeout \u2014 it is an immediate check; use `await` for a timed wait"
       );
     }
-    timeout = parseAwaitTimeout({ [kind]: b }, b.timeout);
+    timeout = parsePositiveMs(b.timeout, { [kind]: b }, "await.timeout", "timeout: 10000");
   }
   rejectUnknownKeys(
     { [kind]: b },
@@ -141515,6 +141907,7 @@ var STEP_DIRECTIVE_KEYS = [
   "tool",
   "tap",
   "long-press",
+  "swipe",
   "type",
   "await",
   "assert",
@@ -141613,13 +142006,19 @@ function parseLongPress(body, entry) {
     }
     const step = { kind: "long-press", ...parseTarget(obj.on, "long-press.on") };
     if (obj.duration !== void 0) {
-      if (typeof obj.duration !== "number" || !Number.isFinite(obj.duration) || obj.duration <= 0) {
+      const duration3 = parsePositiveMs(
+        obj.duration,
+        entry,
+        "long-press.duration",
+        "duration: 1200"
+      );
+      if (duration3 > LONG_PRESS_MAX_DURATION_MS) {
         badEntry(
           entry,
-          "long-press.duration needs a positive number of milliseconds (e.g. `duration: 1200`)"
+          `long-press.duration is ${duration3}ms - above the maximum long-press duration of ${LONG_PRESS_MAX_DURATION_MS}ms; the step holds a finger down for exactly that long, and on Chromium it dispatches a gesture-drag that refuses more`
         );
       }
-      step.duration = obj.duration;
+      step.duration = duration3;
     }
     return step;
   }
@@ -141789,6 +142188,116 @@ function completeRunExtension(value) {
   const candidate = `${value}.yaml`;
   return FLOW_FILE_NAME_PATTERN.test(path32.posix.basename(candidate)) ? candidate : value;
 }
+var SWIPE_DIRECTIONS = ["up", "down", "left", "right"];
+var SWIPE_OPTION_KEYS = ["from", "direction", "to", "by", "momentum", "duration"];
+function parseSwipeBy(raw, entry) {
+  if (raw === null || typeof raw !== "object") {
+    badEntry(entry, "swipe.by needs { x } and/or { y } \u2014 signed 0\u20131 fractions of the screen");
+  }
+  const obj = raw;
+  rejectUnknownKeys(entry, obj, ["x", "y"], "swipe.by");
+  if (obj.x === void 0 && obj.y === void 0) {
+    badEntry(entry, "swipe.by needs at least one of x, y");
+  }
+  const by = {};
+  for (const axis of ["x", "y"]) {
+    const v = obj[axis];
+    if (v === void 0) continue;
+    if (typeof v !== "number" || !Number.isFinite(v) || v === 0 || v < -1 || v > 1) {
+      badEntry(
+        entry,
+        `swipe.by.${axis} must be a non-zero fraction of the screen between -1 and 1 (omit the axis instead of 0)`
+      );
+    }
+    by[axis] = v;
+  }
+  const magnitude = Math.hypot(by.x ?? 0, by.y ?? 0);
+  if (magnitude < SWIPE_MIN_TRAVEL) {
+    badEntry(
+      entry,
+      `swipe.by travels only ${magnitude} \u2014 below the minimum swipe travel of ${SWIPE_MIN_TRAVEL}; a travel that small is a tap, not a swipe`
+    );
+  }
+  return by;
+}
+function parseSwipe(body, entry) {
+  if (typeof body === "string") {
+    if (!SWIPE_DIRECTIONS.includes(body)) {
+      badEntry(
+        entry,
+        `swipe takes a direction (${SWIPE_DIRECTIONS.join(", ")}) \u2014 to anchor on an element use swipe: { from: <target>, direction: \u2026 }`
+      );
+    }
+    return { kind: "swipe", direction: body };
+  }
+  if (body === null || typeof body !== "object") {
+    badEntry(entry, `swipe needs a direction (${SWIPE_DIRECTIONS.join(", ")}) or an options map`);
+  }
+  const obj = body;
+  if (hasSelectorField(obj)) {
+    badEntry(
+      entry,
+      'the swipe options form takes a nested target \u2014 e.g. swipe: { from: { text: "Card" }, direction: left }'
+    );
+  }
+  if (obj.x !== void 0 || obj.y !== void 0) {
+    badEntry(
+      entry,
+      "the swipe options form takes a nested point \u2014 e.g. swipe: { from: { x: 0.5, y: 0.5 }, direction: left }"
+    );
+  }
+  if (obj.settle !== void 0) {
+    badEntry(
+      entry,
+      "swipe.settle was renamed to swipe.momentum, with the opposite sense \u2014 write `momentum: false` for the momentum-free swipe that `settle: true` used to mean (plain `settle: false` was the default, so just drop it)"
+    );
+  }
+  rejectUnknownKeys(entry, obj, SWIPE_OPTION_KEYS, "swipe");
+  const travels = ["direction", "to", "by"].filter((k) => obj[k] !== void 0);
+  if (travels.length !== 1) {
+    badEntry(entry, "swipe needs exactly one of `direction`, `to`, or `by`");
+  }
+  const step = { kind: "swipe" };
+  if (obj.from !== void 0) step.from = parseTarget(obj.from, "swipe.from");
+  switch (travels[0]) {
+    case "direction": {
+      if (typeof obj.direction !== "string" || !SWIPE_DIRECTIONS.includes(obj.direction)) {
+        badEntry(entry, `swipe.direction must be one of ${SWIPE_DIRECTIONS.join(", ")}`);
+      }
+      step.direction = obj.direction;
+      break;
+    }
+    case "to":
+      step.to = parseTarget(obj.to, "swipe.to");
+      break;
+    case "by":
+      step.by = parseSwipeBy(obj.by, entry);
+      break;
+  }
+  if (obj.momentum !== void 0) {
+    if (typeof obj.momentum !== "boolean") {
+      badEntry(entry, "swipe.momentum must be true or false");
+    }
+    if (!obj.momentum) step.momentum = false;
+  }
+  if (obj.duration !== void 0) {
+    const duration3 = parsePositiveMs(obj.duration, entry, "swipe.duration", "duration: 800");
+    if (duration3 < SWIPE_MIN_DURATION_MS) {
+      badEntry(
+        entry,
+        `swipe.duration is only ${duration3}ms \u2014 below the minimum swipe duration of ${SWIPE_MIN_DURATION_MS}ms; that leaves too few 16ms frames for the content to track the travel it was given, so it overshoots instead of landing on it`
+      );
+    }
+    if (duration3 > SWIPE_MAX_DURATION_MS) {
+      badEntry(
+        entry,
+        `swipe.duration is ${duration3}ms - above the maximum swipe duration of ${SWIPE_MAX_DURATION_MS}ms; the step holds a finger on the screen for exactly that long, one dispatched frame per 16ms, and nothing outside the run can cut it short`
+      );
+    }
+    step.duration = duration3;
+  }
+  return step;
+}
 function fromYamlStep(raw, blockDepth = 0) {
   const entry = raw;
   if ("optional" in raw) {
@@ -141830,6 +142339,7 @@ function fromYamlStep(raw, blockDepth = 0) {
   if ("long-press" in raw) {
     return parseLongPress(raw["long-press"], raw);
   }
+  if ("swipe" in raw) return parseSwipe(raw.swipe, raw);
   if ("type" in raw) {
     const body = raw.type;
     if (!body || typeof body !== "object") badEntry(raw, "type needs { into, text }");
@@ -142446,6 +142956,7 @@ function stepRequiresDevice(registry2, step) {
     case "launch":
     case "tap":
     case "long-press":
+    case "swipe":
     case "type":
     case "await":
     case "assert":
@@ -143287,22 +143798,32 @@ async function settleTree(env, opts = {}) {
     if (!await sleepOrAbort(SETTLE_POLL_MS, env.signal)) return void 0;
   }
 }
-async function waitForFrame(env, selector) {
+async function waitForFrames(env, selectors) {
+  const pending = selectors.flatMap((selector, i) => selector ? [{ i, selector }] : []);
+  if (pending.length === 0) return selectors.map(() => void 0);
   const deadline = Date.now() + DEFAULT_ACTION_TIMEOUT_MS;
+  let unresolved = pending[0].selector;
   for (; ; ) {
     if (env.signal?.aborted) return "aborted";
     const tree = await settleTree(env);
     if (tree) {
-      const frame = flowSelectorToFrame(tree, selector);
-      if (frame) return frame;
+      const frames = selectors.map((s) => s ? flowSelectorToFrame(tree, s) : void 0);
+      const missing = pending.find(({ i }) => frames[i] === void 0);
+      if (!missing) return frames;
+      unresolved = missing.selector;
     } else if (env.signal?.aborted) {
       return "aborted";
     }
-    if (Date.now() >= deadline) return void 0;
+    if (Date.now() >= deadline) return { unresolved };
     const sleepMs = Math.min(POLL_INTERVAL_MS, Math.max(0, deadline - Date.now()));
     if (!await sleepOrAbort(sleepMs, env.signal)) return "aborted";
   }
 }
+async function waitForFrame(env, selector) {
+  const frames = await waitForFrames(env, [selector]);
+  if (frames === "aborted") return "aborted";
+  return Array.isArray(frames) ? frames[0] : void 0;
+}
 function framesOverlap(a, b) {
   return a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
 }
@@ -143366,14 +143887,19 @@ async function scrollIncrement(env, direction, region) {
       to = { x: clamp014(cx + dist), y: cy };
       break;
   }
-  await invokeOnDevice(env, "gesture-swipe", {
-    fromX: cx,
-    fromY: cy,
-    toX: to.x,
-    toY: to.y,
-    settle: true,
-    durationMs: 600
-  });
+  try {
+    await invokeOnDevice(env, "gesture-swipe", {
+      fromX: cx,
+      fromY: cy,
+      toX: to.x,
+      toY: to.y,
+      momentum: false,
+      durationMs: 600
+    });
+  } catch (err) {
+    if (env.signal?.aborted) return;
+    throw err;
+  }
 }
 async function scrollToVisible(env, target, direction, within) {
   let prevFp;
@@ -143407,7 +143933,7 @@ function offscreenHint(sel) {
   return `no visible element matched selector ${describeSelector(sel)} \u2014 if it is off-screen, add a scroll-to step before this one`;
 }
 async function runDirective(env, step) {
-  if (env.device.platform === "vega" && (step.kind === "tap" || step.kind === "long-press" || step.kind === "type" || step.kind === "scroll-to" || step.kind === "pinch" || step.kind === "rotate")) {
+  if (env.device.platform === "vega" && (step.kind === "tap" || step.kind === "long-press" || step.kind === "swipe" || step.kind === "type" || step.kind === "scroll-to" || step.kind === "pinch" || step.kind === "rotate")) {
     return {
       ok: false,
       reason: `${step.kind} is a touch directive and Vega is remote-driven \u2014 move focus with \`tool: tv-remote\` steps (and type via \`tool: keyboard\`) instead`
@@ -143424,6 +143950,8 @@ async function runDirective(env, step) {
       return runTap(env, step);
     case "long-press":
       return runLongPress(env, step);
+    case "swipe":
+      return runSwipe(env, step);
     case "type":
       return runType(env, step);
     case "await":
@@ -143471,10 +143999,16 @@ async function resolveTargetPoint(env, target) {
     }
     return { point: getDescribeTapPoint(frame) };
   }
+  const point = targetPointFromFrame(target, void 0);
+  if ("fail" in point) return point;
+  const settle = await settleForGesture(env);
+  if (settle.aborted) return { fail: ABORTED_OUTCOME };
+  return { point, ...warned(settle) };
+}
+function targetPointFromFrame(target, frame) {
+  if (frame) return getDescribeTapPoint(frame);
   if (typeof target.x === "number" && typeof target.y === "number") {
-    const settle = await settleForGesture(env);
-    if (settle.aborted) return { fail: ABORTED_OUTCOME };
-    return { point: { x: target.x, y: target.y }, ...warned(settle) };
+    return { x: target.x, y: target.y };
   }
   return { fail: { ok: false, reason: "gesture needs a selector or x/y coordinates" } };
 }
@@ -143494,13 +144028,18 @@ async function runLongPress(env, step) {
   const point = resolved.point;
   const duration3 = step.duration ?? DEFAULT_LONG_PRESS_MS;
   if (env.device.platform === "chromium") {
-    await invokeOnDevice(env, "gesture-drag", {
-      fromX: point.x,
-      fromY: point.y,
-      toX: point.x,
-      toY: point.y,
-      durationMs: duration3
-    });
+    try {
+      await invokeOnDevice(env, "gesture-drag", {
+        fromX: point.x,
+        fromY: point.y,
+        toX: point.x,
+        toY: point.y,
+        durationMs: duration3
+      });
+    } catch (err) {
+      if (env.signal?.aborted) return ABORTED_OUTCOME;
+      throw err;
+    }
   } else {
     await invokeOnDevice(env, "gesture-custom", {
       events: [
@@ -143620,6 +144159,132 @@ async function runRotate(env, step) {
   }
   return { ok: true, ...warned(settle) };
 }
+var SWIPE_GEOMETRY = {
+  left: { start: { x: 0.9, y: 0.5 }, axis: "x", end: 0.1 },
+  right: { start: { x: 0.1, y: 0.5 }, axis: "x", end: 0.9 },
+  down: { start: { x: 0.5, y: 0.2 }, axis: "y", end: 0.9 },
+  up: { start: { x: 0.5, y: 0.5 }, axis: "y", end: 0.1 }
+};
+async function runSwipe(env, step) {
+  const ends = [step.from, step.to];
+  const selectors = ends.map((end2) => end2 && "selector" in end2 ? end2.selector : void 0);
+  const frames = await waitForFrames(env, selectors);
+  if (frames === "aborted") return ABORTED_OUTCOME;
+  if (!Array.isArray(frames)) return { ok: false, reason: offscreenHint(frames.unresolved) };
+  const [fromFrame, toFrame] = frames;
+  let settle = {};
+  if (selectors.every((selector) => selector === void 0)) {
+    settle = await settleForGesture(env);
+    if (settle.aborted) return ABORTED_OUTCOME;
+  }
+  let toPoint;
+  if (step.to) {
+    const p = targetPointFromFrame(step.to, toFrame);
+    if ("fail" in p) return p.fail;
+    toPoint = p;
+  }
+  let start2;
+  if (step.from) {
+    const p = targetPointFromFrame(step.from, fromFrame);
+    if ("fail" in p) return p.fail;
+    start2 = p;
+  } else if (step.direction) {
+    start2 = { ...SWIPE_GEOMETRY[step.direction].start };
+  } else {
+    start2 = { x: 0.5, y: 0.5 };
+  }
+  if (!Number.isFinite(start2.x) || start2.x < 0 || start2.x > 1 || !Number.isFinite(start2.y) || start2.y < 0 || start2.y > 1) {
+    return {
+      ok: false,
+      reason: `swipe.from resolved outside the normalized screen: (${start2.x}, ${start2.y}); both coordinates must be between 0 and 1`
+    };
+  }
+  let end;
+  if (step.direction) {
+    const g = SWIPE_GEOMETRY[step.direction];
+    const startOnTravelAxis = start2[g.axis];
+    const endOnTravelAxis = step.from ? clamp014(startOnTravelAxis + (g.end - g.start[g.axis])) : g.end;
+    end = g.axis === "x" ? { x: endOnTravelAxis, y: start2.y } : { x: start2.x, y: endOnTravelAxis };
+    const travel2 = Math.abs(endOnTravelAxis - startOnTravelAxis);
+    if (travel2 < SWIPE_MIN_TRAVEL) {
+      return {
+        ok: false,
+        reason: `cannot swipe ${step.direction} from ${g.axis}=${startOnTravelAxis}: only ${travel2} of travel to the screen edge, less than the minimum swipe travel of ${SWIPE_MIN_TRAVEL} \u2014 a tap, not a swipe`
+      };
+    }
+  } else if (step.by) {
+    const overflowAxis = ["x", "y"].find((axis) => {
+      const d = step.by[axis];
+      return d !== void 0 && (start2[axis] + d < 0 || start2[axis] + d > 1);
+    });
+    if (overflowAxis === void 0) {
+      end = {
+        x: step.by.x !== void 0 ? start2.x + step.by.x : start2.x,
+        y: step.by.y !== void 0 ? start2.y + step.by.y : start2.y
+      };
+    } else if (step.from) {
+      const requested = step.by[overflowAxis];
+      const raw = start2[overflowAxis] + requested;
+      return {
+        ok: false,
+        reason: `swipe.by.${overflowAxis} of ${requested} from ${overflowAxis}=${start2[overflowAxis]} lands at ${raw}, off the normalized screen; reduce the delta so from + by stays within [0, 1]`
+      };
+    } else {
+      end = { x: start2.x, y: start2.y };
+      for (const axis of ["x", "y"]) {
+        const d = step.by[axis];
+        if (d === void 0) {
+          end[axis] = start2[axis];
+          continue;
+        }
+        const s = start2[axis];
+        const lo = Math.min(s, s + d);
+        const hi = Math.max(s, s + d);
+        const shift = lo < 0 ? -lo : hi > 1 ? 1 - hi : 0;
+        start2[axis] = s + shift;
+        end[axis] = s + d + shift;
+      }
+    }
+  } else {
+    end = toPoint;
+    if (!Number.isFinite(end.x) || end.x < 0 || end.x > 1 || !Number.isFinite(end.y) || end.y < 0 || end.y > 1) {
+      return {
+        ok: false,
+        reason: `swipe.to resolved outside the normalized screen: (${end.x}, ${end.y}); both coordinates must be between 0 and 1`
+      };
+    }
+    if (Math.hypot(end.x - start2.x, end.y - start2.y) < SWIPE_MIN_TRAVEL) {
+      return {
+        ok: false,
+        reason: `swipe.to (${end.x}, ${end.y}) resolved within the minimum swipe travel of the start point (${start2.x}, ${start2.y}); aim it at a point or element farther from the start`
+      };
+    }
+  }
+  const travel = {
+    fromX: start2.x,
+    fromY: start2.y,
+    toX: end.x,
+    toY: end.y,
+    ...step.duration !== void 0 ? { durationMs: step.duration } : {},
+    ...step.momentum === false ? { momentum: false } : {}
+  };
+  try {
+    await invokeOnDevice(
+      env,
+      env.device.platform === "chromium" ? "gesture-drag" : "gesture-swipe",
+      travel
+    );
+  } catch (err) {
+    if (env.signal?.aborted) return ABORTED_OUTCOME;
+    throw err;
+  }
+  try {
+    await settleTree(env);
+  } catch {
+  }
+  if (env.signal?.aborted) return ABORTED_OUTCOME;
+  return { ok: true, ...warned(settle) };
+}
 async function runType(env, step) {
   const frame = await waitForFrame(env, step.into);
   if (frame === "aborted") return ABORTED_OUTCOME;
@@ -143951,6 +144616,9 @@ function textConditionLabel(sel, expectedText, textMatch) {
   const expected = expectedText ?? "";
   return textMatch === "matches" ? `text ${selector} matches /${expected}/` : textMatch === "equals" ? `text ${selector} == ${JSON.stringify(expected)}` : `text ${selector} contains ${JSON.stringify(expected)}`;
 }
+function targetLabel(target) {
+  return "selector" in target ? selectorLabel(target.selector) : `(${target.x}, ${target.y})`;
+}
 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(
@@ -144078,11 +144746,23 @@ function summarizeStep(step, n) {
       return `${n}. run: ${step.flow}`;
     case "tap":
     case "long-press": {
-      const target = step.selector ? selectorLabel(step.selector) : `(${step.x}, ${step.y})`;
+      const target = targetLabel(
+        step.selector ? { selector: step.selector } : { x: step.x, y: 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 "swipe": {
+      const travel = step.direction ?? (step.by ? `by ${swipeByLabel(step.by)}` : `to ${targetLabel(step.to)}`);
+      const from2 = step.from ? ` from ${targetLabel(step.from)}` : "";
+      const options = [
+        ...step.momentum === false ? ["momentum-free"] : [],
+        ...step.duration !== void 0 ? [`${step.duration}ms`] : []
+      ];
+      const tail = options.length > 0 ? ` (${options.join(", ")})` : "";
+      return `${n}. swipe: ${travel}${from2}${tail}`;
+    }
     case "type":
       return `${n}. type: ${selectorLabel(step.into)} \u2190 "${step.text}"`;
     case "await":
@@ -144124,7 +144804,7 @@ var zodSchema63 = external_exports.object({
     "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") \u2014 a TOOL, not a flow directive. A flow-file directive name ("tap", "launch", "run", "type", "await", "assert", "pinch", "echo", "wait", "long-press", "scroll-to", "snapshot", "when") is answered with guidance, and nothing runs or is recorded: most name the tool that records the directive, while "wait", "long-press", "scroll-to", "snapshot" and "when" have no recording tool at all and are answered with what to do instead. A recording tool (flow-add-step, flow-add-echo, flow-start-recording, flow-finish-recording) is refused the same way, each for its own reason \u2014 nesting one would erase this flow at replay, end the take, or write the step twice.'
+    'MCP tool name (e.g. "gesture-tap", "screenshot", "launch-app") \u2014 a TOOL, not a flow directive. A flow-file directive name ("tap", "launch", "run", "type", "await", "assert", "pinch", "swipe", "echo", "wait", "long-press", "scroll-to", "snapshot", "when") is answered with guidance, and nothing runs or is recorded: most name the tool that records the directive, while "wait", "long-press", "scroll-to", "snapshot" and "when" have no recording tool at all and are answered with what to do instead. A recording tool (flow-add-step, flow-add-echo, flow-start-recording, flow-finish-recording) is refused the same way, each for its own reason \u2014 nesting one would erase this flow at replay, end the take, or write the step twice.'
   ),
   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.`
@@ -144378,6 +145058,9 @@ function isToolNotFound(err, command) {
   return err instanceof ToolNotFoundError && err.toolId === command;
 }
 function directiveCommandHint(command) {
+  if (command === "swipe") {
+    return `"swipe" is a flow directive, not a tool. Record the movement by calling \`gesture-swipe\` (\`gesture-drag\` on chromium, where gesture-swipe is not supported) through flow-add-step. It is stored as the raw \`tool:\` step for whichever one you called; converting it to \`swipe:\` is part of the polish pass.`;
+  }
   if (command === "echo") {
     return `"echo" is a flow directive, not a tool. Call \`flow-add-echo\` DIRECTLY \u2014 not through flow-add-step, which would run it as a nested tool AND record a \`tool: flow-add-echo\` step that fails on every replay.`;
   }
@@ -147402,15 +148085,71 @@ function displayFlowName(params) {
   const stem = params.flow_path === void 0 ? void 0 : path36.basename(params.flow_path, ".yaml");
   return params.name || stem || params.flow_path || "(unspecified)";
 }
-function* walkSteps(steps) {
-  for (const step of steps) {
-    yield step;
+function* walkSteps(steps, within = "") {
+  for (const [i, step] of steps.entries()) {
+    const where = `step ${i + 1}${within}`;
+    yield { step, where };
     const inner = blockSteps(step);
-    if (inner) yield* walkSteps(inner);
+    if (inner) yield* walkSteps(inner, ` of the ${step.kind}: block at ${where}`);
+  }
+}
+function retiredKeyGuidance(prop) {
+  const schema = prop;
+  if (!schema?.not || Object.keys(schema.not).length > 0) return void 0;
+  return (schema.description ?? "").replace(/^Retired:\s*/, "");
+}
+function toolArgProps(registry2, tool) {
+  return registry2.getTool(tool)?.inputSchema?.properties;
+}
+function retiredArgIn(props, tool, args, where) {
+  for (const key2 of Object.keys(args)) {
+    const guidance = retiredKeyGuidance(props[key2]);
+    if (guidance !== void 0) return { where, tool, key: key2, guidance };
   }
+  return void 0;
+}
+function* nestedInvocations(props, args) {
+  for (const [key2, value] of Object.entries(args)) {
+    if (!Object.hasOwn(props, key2)) continue;
+    const entries = Array.isArray(value) ? value : [value];
+    for (const [i, entry] of entries.entries()) {
+      const call = entry;
+      if (typeof call?.tool !== "string") continue;
+      if (typeof call.args !== "object" || call.args === null || Array.isArray(call.args)) continue;
+      yield {
+        tool: call.tool,
+        args: call.args,
+        at: Array.isArray(value) ? `step ${i + 1}` : `\`${key2}\``
+      };
+    }
+  }
+}
+function findRetiredToolArg(registry2, steps) {
+  for (const { step, where } of walkSteps(steps)) {
+    if (step.kind !== "tool") continue;
+    const props = toolArgProps(registry2, step.name);
+    if (!props) continue;
+    const direct = retiredArgIn(props, step.name, step.args, where);
+    if (direct) return direct;
+    for (const call of nestedInvocations(props, step.args)) {
+      const nestedProps = toolArgProps(registry2, call.tool);
+      if (!nestedProps) continue;
+      const hit = retiredArgIn(
+        nestedProps,
+        call.tool,
+        call.args,
+        `${call.at} of the ${step.name} step at ${where}`
+      );
+      if (hit) return hit;
+    }
+  }
+  return void 0;
+}
+function retiredArgReason(use) {
+  return `${use.where} as written (echo included) passes ${use.tool}'s retired \`${use.key}\` key${use.guidance ? `: ${use.guidance}` : ""}`;
 }
 function assertUploadSelfContained(flow) {
-  for (const step of walkSteps(flow.steps)) {
+  for (const { step } of walkSteps(flow.steps)) {
     if (step.kind === "run") {
       throw new FailureError(
         `This flow uses run: composition ("run: ${step.flow}"), which requires a co-located client and tool server \u2014 an uploaded flow's referenced files are not available on this host.`,
@@ -147444,6 +148183,9 @@ function createRunFlowTool(registry2) {
       failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to run flow ${displayFlowName(params)}: ${failureSignal2.error_code}`
     },
     description: `Run a saved flow from the .argent/flows/ directory, or an explicit boundary-managed flow_path.
+Use when a scenario is already authored as YAML and the whole of it should replay in one call with a
+per-step verdict; reach for the individual gesture tools when nothing is authored yet, and for
+run-sequence when the steps are an ad-hoc list rather than a stored flow.
 Steps run in order: \`launch\` starts an app from scratch (terminate + relaunch) and waits until it is
 ready (on iOS it also pins later element lookups to that app rather than auto-detecting the frontmost
 one); \`tool\` calls dispatch through the registry (a raw \`tool\` step ends that iOS pin, so lookups
@@ -147458,6 +148200,11 @@ order), \`next: <selector>\` (CSS \`+\` \u2014 the nearest such follower, which
 non-matching neighbour rather than failing), plus \`any: true\` (CSS \`*\` \u2014 legal only WITH a scope and
 never beside text/id/role). Scopes nest to disambiguate \u2014 \`within: { id: card, within: { id: list } }\`
 reads "inside card inside list", each container's frame inside the next);
+\`swipe\` performs one finger flick (\`swipe: left\`, or \`swipe: { from?, direction|to|by, momentum?, duration? }\` \u2014
+direction is the FINGER's travel, the opposite sense of scroll-to's content direction; \`by: { x?, y? }\` \u2014 signed
+0\u20131 screen fractions, combined length at least 0.03 (a diagonal clears it where neither axis does); duration in ms,
+default 300, minimum 150, maximum 10000; each bound is a parse error that rejects the file before any step runs;
+\`momentum: false\` lands exactly where the finger lifts instead of flinging);
 \`scroll-to\` scrolls (momentum-free) until a target is visible; \`pinch\` zooms
 (\`pinch: { on?, scale }\` \u2014 scale > 1 in, < 1 out; screen center when \`on\` is omitted); \`rotate\` is the
 two-finger rotation gesture (\`rotate: { on?, by }\` \u2014 degrees, + clockwise, within \xB13000\xB0; screen center
@@ -147474,7 +148221,7 @@ 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
+A selector-less gesture \u2014 a coordinate \`tap\`/\`long-press\`/\`swipe\`, 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
@@ -147522,6 +148269,15 @@ Pass exactly one flow source: name for a saved flow under project_root, or flow_
       const flowsDir = path36.dirname(canonicalPath);
       const flow = parseFlow(await fs51.readFile(canonicalPath, "utf8"));
       if (viaUpload) assertUploadSelfContained(flow);
+      const retiredArg = findRetiredToolArg(registry2, flow.steps);
+      if (retiredArg) {
+        throw new FailureError(`Flow "${flowName}" ${retiredArgReason(retiredArg)}`, {
+          error_code: FAILURE_CODES.FLOW_FILE_INVALID,
+          failure_stage: "flow_run_validate",
+          failure_area: "tool_server",
+          error_kind: "validation"
+        });
+      }
       const rootEntry = { canonical: canonicalPath, display: flowName };
       if (flow.executionPrerequisite && !pinnedToChromium(params.device)) {
         const leading = await leadingLaunch(flow, [rootEntry]);
@@ -147792,6 +148548,9 @@ function conditionLabel(cond, renderSelector) {
   }
   return `${cond.condition} ${sel}`;
 }
+function gestureTargetLabel(target) {
+  return "selector" in target ? selectorLabel2(target.selector) : `(${target.x}, ${target.y})`;
+}
 function stepTarget(step) {
   switch (step.kind) {
     case "tap":
@@ -147799,6 +148558,19 @@ function stepTarget(step) {
       if (step.selector) return selectorLabel2(step.selector);
       if (step.x !== void 0 && step.y !== void 0) return `(${step.x}, ${step.y})`;
       return void 0;
+    case "swipe": {
+      let travel;
+      if (step.direction !== void 0) {
+        travel = step.direction;
+      } else if (step.by !== void 0) {
+        travel = `by ${swipeByLabel(step.by)}`;
+      } else if (step.to !== void 0) {
+        travel = `to ${gestureTargetLabel(step.to)}`;
+      } else {
+        return void 0;
+      }
+      return `${travel}${step.from ? ` from ${gestureTargetLabel(step.from)}` : ""}`;
+    }
     case "type":
       return `into ${selectorLabel2(step.into)}`;
     case "await":
@@ -148061,6 +148833,8 @@ async function execRunStep(state3, step, scope) {
   } catch (err) {
     return fail(`could not load fragment "${target}": ${errMsg3(err)}`);
   }
+  const retiredArg = findRetiredToolArg(state3.registry, fragment.steps);
+  if (retiredArg) return fail(`fragment "${target}" ${retiredArgReason(retiredArg)}`);
   pushReport(state3, {
     index,
     kind: "run",
@@ -148094,6 +148868,7 @@ async function execLeafStep(state3, step, index, scope) {
     }
     case "tap":
     case "long-press":
+    case "swipe":
     case "type":
     case "await":
     case "assert":
@@ -148221,6 +148996,9 @@ async function execLeafStep(state3, step, index, scope) {
         }
         return { ...base, status: "pass", tool: step.name, result, outputHint, args };
       } catch (err) {
+        if (signal?.aborted) {
+          return { ...base, status: "skip", tool: step.name, reason: ABORTED_OUTCOME.reason };
+        }
         const reframed = describeNestedParamError(registry2, err, step.name, args, step.args ?? {});
         return { ...base, status: "error", tool: step.name, reason: reframed ?? errMsg3(err) };
       }
@@ -148400,10 +149178,13 @@ var flowReadPrerequisiteTool = {
     failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to read flow prerequisite: ${failureSignal2.error_code}`
   },
   description: `Read the execution prerequisite of a flow without running it \u2014 a saved flow from the .argent/flows/ directory, or an explicit boundary-managed flow_path.
-Returns the prerequisite description so you can verify the required state is met before calling flow-execute.
-Use when you need to check what app/simulator state is required before executing a flow; pass the same flow
-source (name or flow_path) you will pass to flow-execute, so the prerequisite you read is the contract of
-the flow that will actually run.
+Returns { flow, executionPrerequisite }: the logical name, plus the precondition its author recorded
+verbatim. Empty when none was declared, which is always so for a self-contained scenario: one opening
+on a launch may declare no prerequisite, because it builds its own start state.
+Use when deciding whether the device already sits where a fragment expects it (correct app foregrounded,
+correct account, correct screen) before committing to a run, or when relaying that requirement to a human.
+Touches no device: nothing is launched, tapped, dispatched or torn down, and no simulator or emulator
+needs booting, so calling this costs nothing but a file read.
 Fails if the flow file does not exist.
 Address the flow exactly as you will address it in flow-execute: name or flow_path, one and only one; supplying both or neither is rejected. The name goes in \`name\`, which resolves <project_root>/.argent/flows/<name>.yaml.`,
   zodSchema: zodSchema66,
@@ -148911,7 +149692,7 @@ var updateArgentTool = {
       });
       child.unref();
     }, 2e3);
-    const targetLabel = effectiveTarget === "both" ? "global and project-local installs" : `${effectiveTarget} install`;
+    const targetLabel2 = effectiveTarget === "both" ? "global and project-local installs" : `${effectiveTarget} install`;
     const otherHint = requested === "auto" && resolved !== "both" ? resolved === "local" ? ` If you also have a global install, call this tool again with target "global" to update it too.` : ` If you also have a project-local install, run \`argent update --local\` in that project to update it too.` : "";
     const bothDegradedNote = resolved === "both" && effectiveTarget === "global" ? ` The project-local install was skipped: no project declaring ${PACKAGE_NAME2} could be located from this server \u2014 run \`argent update --local\` in the project directory for it.` : "";
     const versionInfo = targetsOnlyRunningInstall ? `(v${currentVersion} -> v${installableVersion}) ` : "";
@@ -148919,7 +149700,7 @@ var updateArgentTool = {
     const coversRunningInstall = targetsOnlyRunningInstall || effectiveTarget === "both";
     const restartNote = coversRunningInstall ? ` The tool server will stop and restart automatically once the update is installed. Subsequent tool calls will reconnect to the updated server.` : ` This session's tool server is not affected and keeps running; the update applies only to the targeted install.`;
     return {
-      message: `Argent update initiated ${versionInfo}for the ${targetLabel}.` + crossTargetNote + restartNote + `${otherHint}${bothDegradedNote}`
+      message: `Argent update initiated ${versionInfo}for the ${targetLabel2}.` + crossTargetNote + restartNote + `${otherHint}${bothDegradedNote}`
     };
   }
 };