iframer-toolkit 0.10.6 → 0.10.8

package/dist/cli.js

@@ -902,10 +902,54 @@ function findChromeExecutable() {
   if (import_fs3.default.existsSync("/usr/bin/google-chrome-stable")) return "/usr/bin/google-chrome-stable";
   return void 0;
 }
+function armHeadedIdleTimer() {
+  if (headedIdleTimer) clearTimeout(headedIdleTimer);
+  headedIdleTimer = setTimeout(() => {
+    if (!headedBrowser) return;
+    const pages = headedBrowser.contexts().reduce((n, c) => n + c.pages().length, 0);
+    if (pages > 0) {
+      armHeadedIdleTimer();
+      return;
+    }
+    log2.info("idle timeout for the pivot headed browser, closing");
+    void closeHeadedBrowser();
+  }, HEADED_IDLE_MS);
+}
 async function getHeadedBrowser() {
-  if (!headedBrowser?.isConnected()) headedBrowser = await import_patchright.chromium.launch({ headless: false, args: STEALTH_ARGS });
+  if (!headedBrowser?.isConnected()) {
+    const marker = `--iframer-key=pivot-headed-${process.pid}-${Date.now()}`;
+    headedBrowser = await import_patchright.chromium.launch({ headless: false, args: [...STEALTH_ARGS, marker] });
+    headedPid = findChromePidByMarker(marker);
+    if (headedPid) {
+      registerBrowser({
+        key: "pivot::headed",
+        chromePid: headedPid,
+        ownerPid: process.pid,
+        marker,
+        launchedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    } else {
+      log2.warn("could not resolve Chrome PID for the pivot headed browser \u2014 force-kill unavailable");
+    }
+  }
+  armHeadedIdleTimer();
   return headedBrowser;
 }
+async function closeHeadedBrowser() {
+  if (headedIdleTimer) {
+    clearTimeout(headedIdleTimer);
+    headedIdleTimer = null;
+  }
+  if (headedBrowser) {
+    await headedBrowser.close().catch(() => {
+    });
+    headedBrowser = null;
+  }
+  if (headedPid !== null) {
+    unregisterBrowser(headedPid);
+    headedPid = null;
+  }
+}
 async function getBrowser(_name = "chromium") {
   if (cachedBrowser) {
     if (cachedBrowser.isConnected()) return cachedBrowser;
@@ -923,11 +967,7 @@ async function getBrowser(_name = "chromium") {
   return cachedBrowser;
 }
 async function closeBrowser() {
-  if (headedBrowser) {
-    await headedBrowser.close().catch(() => {
-    });
-    headedBrowser = null;
-  }
+  await closeHeadedBrowser();
   if (!cachedBrowser) return;
   try {
     await cachedBrowser.close();
@@ -964,7 +1004,7 @@ async function launchHeadful(displayNum) {
   log2.debug(`headful: ${executablePath || "patchright chromium"}, extensions: ${hasExtensions}`);
   return import_patchright.chromium.launch(launchOpts);
 }
-var import_fs3, import_patchright, log2, UBLOCK_PATH, cachedBrowser, headedBrowser;
+var import_fs3, import_patchright, log2, UBLOCK_PATH, cachedBrowser, headedBrowser, headedPid, headedIdleTimer, HEADED_IDLE_MS;
 var init_launcher = __esm({
   "src/lib/browser/launcher.ts"() {
     "use strict";
@@ -972,10 +1012,14 @@ var init_launcher = __esm({
     import_patchright = require("patchright");
     init_stealth();
     init_logger();
+    init_registry();
     log2 = createLogger("launcher");
     UBLOCK_PATH = "/extensions/uBlock0.chromium";
     cachedBrowser = null;
     headedBrowser = null;
+    headedPid = null;
+    headedIdleTimer = null;
+    HEADED_IDLE_MS = 5 * 60 * 1e3;
   }
 });
 
@@ -1033,7 +1077,13 @@ var init_constants = __esm({
       /** Scroll step delay */
       SCROLL_DELAY: 150,
       /** Stale state check interval */
-      STALE_CHECK_INTERVAL: 2e3
+      STALE_CHECK_INTERVAL: 2e3,
+      /** captureApi: grace period after the last step for a submit's XHR to fire */
+      CAPTURE_SETTLE: 300,
+      /** captureApi: max wait for in-flight requests to answer before stopping */
+      CAPTURE_PENDING_MAX: 3e3,
+      /** Post-failure probe ("does the selector exist right now?") budget */
+      FAILURE_PROBE: 3e3
     };
     CAPTCHA_GRID = {
       /** Pixels from bframe top to grid start (reCAPTCHA) */
@@ -1071,6 +1121,10 @@ var init_constants = __esm({
       DEFAULT_STALE: 2e4,
       NAVIGATION: 6e4,
       SELECTOR_WAIT: 1e4,
+      // Actionability wait for click. Under the 20s stale timer on purpose, so
+      // Playwright's own reason (not visible, covered by another element…) reaches
+      // the agent instead of a generic "no state change".
+      CLICK: 8e3,
       TOTP_INPUT: 5e3,
       API_REQUEST: 18e4,
       HEALTH_CHECK: 3e3,
@@ -1827,7 +1881,7 @@ var init_cloak_browser = __esm({
 function keyOf(mode, instanceId) {
   return `${mode}::${instanceId}`;
 }
-var import_patchright2, import_crypto2, log7, DEFAULT_IDLE_TIMEOUT, CLOSE_GRACE_MS, DEFAULT_INSTANCE, sleep3, BrowserDaemon;
+var import_patchright2, import_crypto2, log7, DEFAULT_IDLE_TIMEOUT, CLOSE_GRACE_MS, BUSY_MAX_MS, BLANK_IDLE_MS, DEFAULT_INSTANCE, sleep3, BrowserDaemon;
 var init_daemon = __esm({
   "src/lib/browser/daemon.ts"() {
     "use strict";
@@ -1840,6 +1894,8 @@ var init_daemon = __esm({
     log7 = createLogger("daemon");
     DEFAULT_IDLE_TIMEOUT = 5 * 60 * 1e3;
     CLOSE_GRACE_MS = 5e3;
+    BUSY_MAX_MS = 30 * 60 * 1e3;
+    BLANK_IDLE_MS = 2 * 60 * 1e3;
     DEFAULT_INSTANCE = "default";
     sleep3 = (ms) => new Promise((r) => setTimeout(r, ms));
     BrowserDaemon = class {
@@ -1928,7 +1984,8 @@ var init_daemon = __esm({
           createdAt: /* @__PURE__ */ new Date(),
           chromePid,
           marker,
-          active: 0
+          active: 0,
+          busySince: null
         };
         this.instances.set(key, instance);
         this.resetIdleTimer(key);
@@ -1940,14 +1997,19 @@ var init_daemon = __esm({
        *  Always pair with release() in a finally block. */
       acquire(mode, instanceId = DEFAULT_INSTANCE) {
         const instance = this.instances.get(keyOf(mode, instanceId));
-        if (instance) instance.active++;
+        if (!instance) return;
+        if (instance.active === 0) instance.busySince = Date.now();
+        instance.active++;
       }
       release(mode, instanceId = DEFAULT_INSTANCE) {
         const key = keyOf(mode, instanceId);
         const instance = this.instances.get(key);
         if (!instance) return;
         instance.active = Math.max(0, instance.active - 1);
-        if (instance.active === 0) this.resetIdleTimer(key);
+        if (instance.active === 0) {
+          instance.busySince = null;
+          this.resetIdleTimer(key);
+        }
       }
       isRunning(mode, instanceId = DEFAULT_INSTANCE) {
         const instance = this.instances.get(keyOf(mode, instanceId));
@@ -1958,6 +2020,35 @@ var init_daemon = __esm({
           return false;
         }
       }
+      /** Close instances that never left about:blank and have been idle a while.
+       *  Those are accidents — a pipeline that failed before its first navigate, or
+       *  a mode picked for a call that never needed a browser — and in headful mode
+       *  each one is an empty window sitting on the user's desktop. Called on the
+       *  server's reap tick, so it also catches instances whose idle timer was lost
+       *  (e.g. the daemon was restarted under them). */
+      sweepBlankInstances() {
+        const stopped = [];
+        const now = Date.now();
+        for (const [key, inst] of this.instances.entries()) {
+          if (inst.active > 0) continue;
+          if (now - inst.createdAt.getTime() < BLANK_IDLE_MS) continue;
+          let blank = false;
+          try {
+            const pages = inst.context.pages();
+            blank = pages.length === 0 || pages.every((p) => {
+              const u = p.url();
+              return u === "about:blank" || u === "" || u === "chrome://newtab/";
+            });
+          } catch {
+            continue;
+          }
+          if (!blank) continue;
+          log7.info(`blank-orphan sweep: ${key} never left about:blank, stopping`);
+          stopped.push(key);
+          this.stopKey(key).catch((err) => log7.warn(`blank sweep stop failed for ${key}: ${err}`));
+        }
+        return stopped;
+      }
       /** Distinct modes that currently have at least one live instance. */
       runningModes() {
         return [...new Set(this.liveInstances().map((i) => i.mode))];
@@ -2076,8 +2167,14 @@ var init_daemon = __esm({
           setTimeout(() => {
             const instance = this.instances.get(key);
             if (instance && instance.active > 0) {
-              this.resetIdleTimer(key);
-              return;
+              const busyMs = instance.busySince ? Date.now() - instance.busySince : 0;
+              if (busyMs < BUSY_MAX_MS) {
+                this.resetIdleTimer(key);
+                return;
+              }
+              log7.warn(`${key} reported busy for ${Math.round(busyMs / 6e4)}m \u2014 treating active=${instance.active} as leaked, stopping`);
+              instance.active = 0;
+              instance.busySince = null;
             }
             log7.info(`Idle timeout for ${key}, stopping...`);
             this.stopKey(key).catch((err) => log7.warn(`idle stop failed for ${key}: ${err}`));
@@ -2479,6 +2576,24 @@ async function humanType(page, selector, text, opts = {}) {
     await sleep4(randRange(TIMING.POST_CLICK));
   }
   await assertFocused(page, selector, !opts.skipClick);
+  if (opts.clear) {
+    const hadText = await page.evaluate(() => {
+      const el = document.activeElement;
+      if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+        el.select();
+        return el.value.length > 0;
+      }
+      if (el?.isContentEditable) {
+        window.getSelection()?.selectAllChildren(el);
+        return (el.textContent || "").length > 0;
+      }
+      return false;
+    });
+    if (hadText) {
+      await page.keyboard.press("Backspace");
+      await sleep4(randRange(TIMING.CHAR_DELAY));
+    }
+  }
   const factor = SPEED_FACTOR[opts.speed || "normal"] ?? 1;
   for (const char of text) {
     await page.keyboard.type(char);
@@ -2640,7 +2755,41 @@ var init_humanize = __esm({
   }
 });
 
+// src/lib/budget.ts
+function withBudget(p, ms, label = "page call") {
+  p.catch(() => void 0);
+  let timer;
+  return Promise.race([
+    p,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new BudgetExceededError(label, ms)), ms);
+      timer.unref?.();
+    })
+  ]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}
+var BudgetExceededError;
+var init_budget = __esm({
+  "src/lib/budget.ts"() {
+    "use strict";
+    BudgetExceededError = class extends Error {
+      constructor(label, ms) {
+        super(`${label} did not answer within ${ms}ms`);
+        this.name = "BudgetExceededError";
+      }
+    };
+  }
+});
+
 // src/lib/actions/resolve-selector.ts
+function assertCssSelector(selector) {
+  if (PLAYWRIGHT_ONLY.test(selector)) {
+    throw new Error(
+      `Unsupported selector "${selector}": Playwright text/role selectors (text=, :has-text(), :text-is(), >>) aren't supported. Locate the element by its text with a \`find\` step (e.g. { type: "find", text: "Texas" } or { role: "option", name: "Texas" }) and act on the @e ref it returns, in the same execute call.`
+    );
+  }
+}
 function resolveSelector(selector, ctx) {
   if (selector.startsWith("@a:")) {
     const name = selector.slice(3);
@@ -2661,23 +2810,160 @@ function resolveSelector(selector, ctx) {
     }
     return ref.selector;
   }
+  assertCssSelector(selector);
   return selector;
 }
 function anchorNameOf(selector) {
   return typeof selector === "string" && selector.startsWith("@a:") ? selector.slice(3) : null;
 }
+var PLAYWRIGHT_ONLY;
 var init_resolve_selector = __esm({
   "src/lib/actions/resolve-selector.ts"() {
     "use strict";
+    PLAYWRIGHT_ONLY = /^\s*(text|xpath|role|id|data-testid|internal:[\w-]+)\s*=|:(has-text|text|text-is|text-matches|visible|nth-match|right-of|left-of|above|below|near)\b|\s>>\s/;
+  }
+});
+
+// src/lib/reachability.ts
+function isHoneypotReason(reason) {
+  return !!reason && HONEYPOT_REASONS.has(reason);
+}
+function looksLikeBaitField(attrs) {
+  const name = attrs.name || "";
+  const id = attrs.id || "";
+  if (HONEYPOT_NAME_RE.test(name) || HONEYPOT_NAME_RE.test(id)) return true;
+  const textual = !attrs.type || /^(text|email|url|tel|search|number)$/i.test(attrs.type);
+  if (textual && attrs.tabindex === "-1") return true;
+  return false;
+}
+function honeypotRefusalMessage(selector, reason, name) {
+  const what = name ? `"${name}" (${selector})` : selector;
+  return `fill: refusing to fill ${what} \u2014 no human can reach this field (${reason}). It is almost certainly a honeypot: filling it marks the submission as a bot and the form fails with a generic error. Skip it. If you are certain it is a real field, retry with force: true.`;
+}
+async function probeField(page, selector) {
+  const r = await page.evaluate((sel) => {
+    const el = document.querySelector(sel);
+    if (!el) return { found: false };
+    const attrs = {
+      name: el.getAttribute("name"),
+      id: el.id || null,
+      tabindex: el.getAttribute("tabindex"),
+      type: el.getAttribute("type")
+    };
+    const tag = el.tagName.toLowerCase();
+    {
+      const r0 = el.getBoundingClientRect();
+      const cx0 = r0.left + r0.width / 2, cy0 = r0.top + r0.height / 2;
+      const dx = cx0 < 0 || cx0 >= window.innerWidth ? cx0 - window.innerWidth / 2 : 0;
+      const dy = cy0 < 0 || cy0 >= window.innerHeight ? cy0 - window.innerHeight / 2 : 0;
+      if (dx || dy) try {
+        window.scrollBy(dx, dy);
+      } catch {
+      }
+    }
+    const rect = el.getBoundingClientRect();
+    let reason = null;
+    if (rect.width === 0 || rect.height === 0) reason = "zero-size";
+    const style = getComputedStyle(el);
+    if (!reason && (style.display === "none" || style.visibility === "hidden")) reason = "hidden";
+    if (!reason) {
+      let opacity = 1;
+      for (let n = el; n && n !== document.documentElement; n = n.parentElement) {
+        const o = parseFloat(getComputedStyle(n).opacity);
+        const animating = o < 1 && typeof n.getAnimations === "function" && n.getAnimations().length > 0;
+        if (!isNaN(o) && !animating) opacity *= o;
+      }
+      if (opacity < 0.05) reason = "transparent";
+    }
+    if (!reason) {
+      const docW = Math.max(document.documentElement.scrollWidth, window.innerWidth);
+      const docH = Math.max(document.documentElement.scrollHeight, window.innerHeight);
+      const left = rect.left + window.scrollX, right = rect.right + window.scrollX;
+      const top = rect.top + window.scrollY, bottom = rect.bottom + window.scrollY;
+      if (right <= 0 || left >= docW || bottom <= 0 || top >= docH) reason = "offscreen";
+    }
+    if (!reason) {
+      const cx = rect.left + rect.width / 2, cy = rect.top + rect.height / 2;
+      const inViewport = cx >= 0 && cy >= 0 && cx < window.innerWidth && cy < window.innerHeight;
+      let clipped = false;
+      for (let a = el.parentElement; a && a !== document.body; a = a.parentElement) {
+        const s = getComputedStyle(a);
+        const clipsX = /hidden|clip/.test(s.overflowX), clipsY = /hidden|clip/.test(s.overflowY);
+        if (!clipsX && !clipsY) continue;
+        const ar = a.getBoundingClientRect();
+        const outside = clipsX && (cx < ar.left || cx > ar.right) || clipsY && (cy < ar.top || cy > ar.bottom);
+        const tiny = clipsY && ar.height <= 2 || clipsX && ar.width <= 2;
+        if (outside || tiny) {
+          clipped = true;
+          break;
+        }
+      }
+      if (inViewport) {
+        const hit = document.elementFromPoint(cx, cy);
+        if (!(hit && (hit === el || el.contains(hit)))) reason = clipped ? "clipped" : "covered";
+      } else if (clipped) {
+        reason = "clipped";
+      }
+    }
+    return { found: true, reason, attrs, tag };
+  }, selector);
+  if (!r.found) return { found: false, hiddenReason: null, suspiciousName: false };
+  return {
+    found: true,
+    hiddenReason: r.reason ?? null,
+    suspiciousName: looksLikeBaitField(r.attrs),
+    tag: r.tag,
+    name: r.attrs.name ?? void 0
+  };
+}
+var HONEYPOT_REASONS, HONEYPOT_NAME_RE;
+var init_reachability = __esm({
+  "src/lib/reachability.ts"() {
+    "use strict";
+    HONEYPOT_REASONS = /* @__PURE__ */ new Set(["zero-size", "hidden", "transparent", "offscreen", "clipped"]);
+    HONEYPOT_NAME_RE = /^(website|url|homepage|fax|honeypot|honey|hp|hp_[\w-]*|bot|bot_[\w-]*|trap|_gotcha|leave_?blank|do_?not_?fill)$/i;
   }
 });
 
 // src/lib/actions/handlers/navigation.ts
-async function navigate(page, step, ctx) {
-  await page.goto(step.url, {
-    waitUntil: step.waitUntil || "domcontentloaded",
-    timeout: TIMEOUTS.NAVIGATION
-  });
+async function navigate(page, step, ctx, monitor) {
+  const waitUntil = step.waitUntil || "domcontentloaded";
+  const urlBefore = page.url();
+  const onDialog = (d) => {
+    (d.type() === "beforeunload" ? d.accept() : d.dismiss()).catch(() => void 0);
+  };
+  page.on("dialog", onDialog);
+  try {
+    const nav = page.goto(step.url, { waitUntil, timeout: TIMEOUTS.NAVIGATION });
+    nav.catch(() => void 0);
+    let suspectTimer;
+    const outcome = await Promise.race([
+      nav.then(() => "done"),
+      new Promise((r) => {
+        suspectTimer = setTimeout(() => r("slow"), NAV_COMMIT_SUSPECT_MS);
+      })
+    ]).finally(() => clearTimeout(suspectTimer));
+    if (outcome === "slow") {
+      if (page.url() !== urlBefore) {
+        await nav;
+      } else {
+        log9.warn(`navigate: no commit after ${NAV_COMMIT_SUSPECT_MS}ms, falling back to location.assign`);
+        monitor?.reportActivity();
+        await withBudget(page.evaluate((u) => {
+          location.assign(u);
+        }, step.url), 3e3, "location.assign").catch(() => void 0);
+        try {
+          await page.waitForURL((u) => u.toString() !== urlBefore, { timeout: 15e3, waitUntil });
+        } catch {
+          throw new Error(
+            `navigate: the page never left ${urlBefore} for ${step.url} (tried a normal navigation, then location.assign). The site is blocking the route change. Use a click on the site's own link to get there.`
+          );
+        }
+      }
+    }
+  } finally {
+    page.off("dialog", onDialog);
+  }
   const stealthScript = contextStealthScripts.get(page.context()) ?? STEALTH_SCRIPT;
   try {
     await page.evaluate(stealthScript);
@@ -2693,14 +2979,37 @@ async function navigate(page, step, ctx) {
   }
 }
 async function click(page, step, ctx) {
-  await page.click(resolveSelector(step.selector, ctx));
+  await page.click(resolveSelector(step.selector, ctx), { timeout: TIMEOUTS.CLICK });
+}
+async function isCombobox(page, selector) {
+  return withBudget(
+    page.evaluate((sel) => {
+      const el = document.querySelector(sel);
+      if (!el) return false;
+      const role = el.getAttribute("role");
+      return role === "combobox" || el.hasAttribute("aria-autocomplete") || el.getAttribute("aria-haspopup") === "listbox" || el.hasAttribute("list") || !!el.closest('[role="combobox"]');
+    }, selector),
+    3e3
+  ).catch(() => false);
 }
 async function fill(page, step, ctx) {
   const selector = resolveSelector(step.selector, ctx);
   const value = step.value;
+  if (!step.force) {
+    let probe = null;
+    try {
+      probe = await probeField(page, selector);
+    } catch {
+      probe = null;
+    }
+    if (probe?.found && isHoneypotReason(probe.hiddenReason)) {
+      throw new Error(honeypotRefusalMessage(step.selector, probe.hiddenReason, probe.name));
+    }
+  }
+  const combobox = await isCombobox(page, selector);
   await page.fill(selector, value);
   const stuck = await page.evaluate(
-    ({ sel, val }) => {
+    ({ sel, val, keepFocus }) => {
       const el = document.querySelector(sel);
       if (!el) return false;
       const proto = el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
@@ -2716,13 +3025,15 @@ async function fill(page, step, ctx) {
       }
       el.dispatchEvent(new Event("input", { bubbles: true }));
       el.dispatchEvent(new Event("change", { bubbles: true }));
-      try {
-        el.blur();
-      } catch {
+      if (!keepFocus) {
+        try {
+          el.blur();
+        } catch {
+        }
       }
       return el.value === val;
     },
-    { sel: selector, val: value }
+    { sel: selector, val: value, keepFocus: combobox }
   );
   if (!stuck) {
     const loc = page.locator(selector);
@@ -2730,10 +3041,12 @@ async function fill(page, step, ctx) {
       await loc.click();
       await loc.fill("");
       await loc.pressSequentially(value, { delay: 15 });
-      await page.evaluate((sel) => {
-        const el = document.querySelector(sel);
-        el?.blur?.();
-      }, selector);
+      if (!combobox) {
+        await page.evaluate((sel) => {
+          const el = document.querySelector(sel);
+          el?.blur?.();
+        }, selector);
+      }
     } catch {
     }
   }
@@ -2757,7 +3070,7 @@ async function rightClick(page, step, ctx) {
   }
 }
 async function humanTypeStep(page, step, ctx) {
-  await humanType(page, resolveSelector(step.selector, ctx), step.value, { skipClick: step.skipClick, speed: step.speed });
+  await humanType(page, resolveSelector(step.selector, ctx), step.value, { skipClick: step.skipClick, speed: step.speed, clear: step.clear });
 }
 async function selectOption(page, step, ctx) {
   const selector = resolveSelector(step.selector, ctx);
@@ -2800,7 +3113,29 @@ async function scroll(page, step, ctx) {
     { dy: step.deltaY ?? 0, sel: selector }
   );
 }
-async function keyboard(page, step) {
+async function selectAllInFocused(page) {
+  await page.evaluate(() => {
+    const el = document.activeElement;
+    if (el && (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement)) {
+      el.select();
+    } else if (el && el.isContentEditable) {
+      const sel = window.getSelection();
+      sel?.selectAllChildren(el);
+    } else {
+      window.getSelection()?.selectAllChildren(document.body);
+    }
+  });
+}
+async function keyboard(page, step, ctx) {
+  if ((step.meta || step.ctrl) && step.key.toLowerCase() === "a" && !step.shift && !step.alt) {
+    await selectAllInFocused(page);
+    return;
+  }
+  if ((step.meta || step.ctrl) && ctx.driver === "extension") {
+    throw new Error(
+      `keyboard: ${step.meta ? "Cmd" : "Ctrl"}+${step.key} can't be sent in extension mode (the relay drops Cmd/Ctrl, so it would arrive as a plain "${step.key}"). Nothing was pressed. Instead: select-all \u2192 keyboard {key:"a", meta:true} (handled in-page); replace a field's text \u2192 fill, or human-type with clear:true; paste \u2192 the paste step.`
+    );
+  }
   const mods = [
     step.meta ? "Meta" : null,
     step.ctrl ? "Control" : null,
@@ -2871,7 +3206,7 @@ async function typeCode(page, step, ctx) {
   }
   return { typed: code.length };
 }
-var log9;
+var log9, NAV_COMMIT_SUSPECT_MS;
 var init_navigation = __esm({
   "src/lib/actions/handlers/navigation.ts"() {
     "use strict";
@@ -2881,8 +3216,11 @@ var init_navigation = __esm({
     init_persistence();
     init_logger();
     init_constants();
+    init_budget();
     init_resolve_selector();
+    init_reachability();
     log9 = createLogger("actions");
+    NAV_COMMIT_SUSPECT_MS = 12e3;
   }
 });
 
@@ -3004,6 +3342,56 @@ async function takeSnapshot(page, ctx, options) {
       if (rect.bottom < 0 || rect.top > window.innerHeight + 200) return false;
       return true;
     }
+    function isFillable(el) {
+      if (el.tagName === "TEXTAREA" || el.tagName === "SELECT") return true;
+      if (el.hasAttribute("contenteditable") && el.getAttribute("contenteditable") !== "false") return true;
+      if (el.tagName !== "INPUT") return false;
+      const t = (el.type || "text").toLowerCase();
+      return !["button", "submit", "reset", "image", "checkbox", "radio", "file", "hidden", "range", "color"].includes(t);
+    }
+    function unreachableReason(el) {
+      const rect = el.getBoundingClientRect();
+      const style = getComputedStyle(el);
+      let opacity = 1;
+      for (let n = el; n && n !== document.documentElement; n = n.parentElement) {
+        const o = parseFloat(n === el ? style.opacity : getComputedStyle(n).opacity);
+        const animating = o < 1 && typeof n.getAnimations === "function" && n.getAnimations().length > 0;
+        if (!isNaN(o) && !animating) opacity *= o;
+      }
+      if (opacity < 0.05) return "transparent";
+      const docW = Math.max(document.documentElement.scrollWidth, window.innerWidth);
+      const docH = Math.max(document.documentElement.scrollHeight, window.innerHeight);
+      const left = rect.left + window.scrollX, right = rect.right + window.scrollX;
+      const top = rect.top + window.scrollY, bottom = rect.bottom + window.scrollY;
+      if (right <= 0 || left >= docW || bottom <= 0 || top >= docH) return "offscreen";
+      const cx = rect.left + rect.width / 2, cy = rect.top + rect.height / 2;
+      let clipped = false;
+      for (let a = el.parentElement; a && a !== document.body; a = a.parentElement) {
+        const s = getComputedStyle(a);
+        const clipsX = /hidden|clip/.test(s.overflowX), clipsY = /hidden|clip/.test(s.overflowY);
+        if (!clipsX && !clipsY) continue;
+        const ar = a.getBoundingClientRect();
+        const outside = clipsX && (cx < ar.left || cx > ar.right) || clipsY && (cy < ar.top || cy > ar.bottom);
+        const tiny = clipsY && ar.height <= 2 || clipsX && ar.width <= 2;
+        if (tiny) return "clipped";
+        if (outside) clipped = true;
+      }
+      const inViewport = cx >= 0 && cy >= 0 && cx < window.innerWidth && cy < window.innerHeight;
+      if (inViewport) {
+        const hit = document.elementFromPoint(cx, cy);
+        if (hit && (hit === el || el.contains(hit))) return null;
+        return clipped ? "clipped" : null;
+      }
+      return null;
+    }
+    const baitName = /^(website|url|homepage|fax|honeypot|honey|hp|hp_[\w-]*|bot|bot_[\w-]*|trap|_gotcha|leave_?blank|do_?not_?fill)$/i;
+    function looksLikeBait(el) {
+      const name = el.getAttribute("name") || "", id = el.id || "";
+      if (baitName.test(name) || baitName.test(id)) return true;
+      const type = (el.getAttribute("type") || "text").toLowerCase();
+      const textual = /^(text|email|url|tel|search|number)$/.test(type);
+      return textual && el.getAttribute("tabindex") === "-1";
+    }
     function buildSelector(el) {
       const path14 = [];
       let current = el;
@@ -3046,6 +3434,11 @@ async function takeSnapshot(page, ctx, options) {
       if (results.length >= maxElements2) break;
       if (interactiveOnly2 && !isInteractive(el)) continue;
       if (!isVisible(el)) continue;
+      let suspect;
+      if (isFillable(el)) {
+        if (unreachableReason(el)) continue;
+        if (looksLikeBait(el)) suspect = "honeypot?";
+      }
       const tag = el.tagName.toLowerCase();
       const role = el.getAttribute("role") || "";
       const type = el.type || "";
@@ -3058,7 +3451,8 @@ async function takeSnapshot(page, ctx, options) {
         checked: el.checked || false,
         disabled: el.disabled || false,
         selector: buildSelector(el),
-        isVisible: true
+        isVisible: true,
+        suspect
       });
     }
     return results;
@@ -3079,6 +3473,7 @@ async function takeSnapshot(page, ctx, options) {
     const state = [];
     if (el.disabled) state.push("disabled");
     if (el.checked) state.push("checked");
+    if (el.suspect) state.push(el.suspect);
     let description = "";
     if (el.placeholder && el.name !== el.placeholder) description = `placeholder="${el.placeholder}"`;
     if (el.type && !["text", "submit", "button", ""].includes(el.type)) {
@@ -4596,12 +4991,15 @@ var init_registry2 = __esm({
 });
 
 // src/lib/stale-monitor.ts
-var DEFAULT_STALE_TIMEOUT_MS, StaleStateMonitor, StaleStateError;
+var DEFAULT_STALE_TIMEOUT_MS, PROBE_BUDGET_MS, UNRESPONSIVE_GRACE_MS, StaleStateMonitor, StaleStateError;
 var init_stale_monitor = __esm({
   "src/lib/stale-monitor.ts"() {
     "use strict";
     init_constants();
+    init_budget();
     DEFAULT_STALE_TIMEOUT_MS = 2e4;
+    PROBE_BUDGET_MS = 3e3;
+    UNRESPONSIVE_GRACE_MS = 8e3;
     StaleStateMonitor = class _StaleStateMonitor {
       page;
       timeoutMs;
@@ -4613,21 +5011,24 @@ var init_stale_monitor = __esm({
       }
       async snapshot() {
         try {
-          const [url, state] = await Promise.all([
-            Promise.resolve(this.page.url()),
+          const url = this.page.url();
+          let unresponsive = false;
+          const state = await withBudget(
             this.page.evaluate(() => ({
               documentReadyState: document.readyState,
               bodyTextLength: document.body?.innerText?.length || 0,
               elementCount: document.querySelectorAll("*").length
-            })).catch(() => ({
-              documentReadyState: "unknown",
-              bodyTextLength: 0,
-              elementCount: 0
-            }))
-          ]);
+            })),
+            PROBE_BUDGET_MS,
+            "state probe"
+          ).catch((e) => {
+            unresponsive = e instanceof BudgetExceededError;
+            return { documentReadyState: "unknown", bodyTextLength: 0, elementCount: 0 };
+          });
           return {
             url,
             ...state,
+            unresponsive,
             timestamp: Date.now()
           };
         } catch {
@@ -4671,6 +5072,8 @@ var init_stale_monitor = __esm({
         return new Promise((resolve, reject) => {
           let resolved = false;
           let checkInterval = null;
+          let probing = false;
+          let unresponsiveSince = null;
           const cleanup = () => {
             resolved = true;
             if (checkInterval) clearInterval(checkInterval);
@@ -4678,11 +5081,25 @@ var init_stale_monitor = __esm({
             this.timer = null;
           };
           checkInterval = setInterval(async () => {
-            if (resolved) return;
+            if (resolved || probing) return;
             const elapsed = Date.now() - this.lastActivity;
             if (elapsed < this.timeoutMs) return;
+            probing = true;
             try {
               const currentSnapshot = await this.snapshot();
+              if (resolved) return;
+              if (currentSnapshot.unresponsive) {
+                unresponsiveSince ??= Date.now();
+                if (Date.now() - unresponsiveSince < UNRESPONSIVE_GRACE_MS) return;
+                cleanup();
+                reject(new StaleStateError(
+                  `The tab stopped responding: its JavaScript did not answer for ${Math.round((Date.now() - unresponsiveSince) / 1e3)}s (a blocking dialog, a frozen re-render, or a navigation that never finished)`,
+                  this.timeoutMs,
+                  true
+                ));
+                return;
+              }
+              unresponsiveSince = null;
               if (_StaleStateMonitor.hasChanged(beforeSnapshot, currentSnapshot)) {
                 this.lastActivity = Date.now();
                 return;
@@ -4690,6 +5107,8 @@ var init_stale_monitor = __esm({
             } catch {
               this.lastActivity = Date.now();
               return;
+            } finally {
+              probing = false;
             }
             cleanup();
             reject(new StaleStateError(
@@ -4713,10 +5132,13 @@ var init_stale_monitor = __esm({
     };
     StaleStateError = class extends Error {
       timeoutMs;
-      constructor(message, timeoutMs) {
+      /** True when the page stopped answering at all (vs. answering but not changing). */
+      unresponsive;
+      constructor(message, timeoutMs, unresponsive = false) {
         super(message);
         this.name = "StaleStateError";
         this.timeoutMs = timeoutMs;
+        this.unresponsive = unresponsive;
       }
     };
   }
@@ -4945,10 +5367,14 @@ async function capturePageState(page, ctx, opts) {
     url = page.url();
   } catch {
   }
-  const title = await page.title().catch(() => "");
+  const title = await withBudget(page.title(), 2e3, "title").catch(() => "");
   if (!screenshot2) return { url, title };
   try {
-    const buf = await page.screenshot({ type: "jpeg", quality: 50, fullPage: false });
+    const buf = await withBudget(
+      page.screenshot({ type: "jpeg", quality: 50, fullPage: false, timeout: 12e3 }),
+      13e3,
+      "screenshot"
+    );
     const screenshotUrl = saveScreenshot(buf, `${namePrefix}-${Date.now()}.jpg`, ctx.screenshotDir, ctx.publicUrl);
     return { url, title, screenshotUrl };
   } catch {
@@ -4959,6 +5385,7 @@ var init_page_state = __esm({
   "src/lib/page-state.ts"() {
     "use strict";
     init_screenshot();
+    init_budget();
   }
 });
 
@@ -5160,6 +5587,24 @@ function buildCurl(method, url, headers, auth, body) {
   parts.push(`  '${url}'`);
   return parts.join(" \\\n");
 }
+function serverErrorsFrom(requests) {
+  const out = [];
+  for (const r of requests) {
+    if (r.responseStatus < 400) continue;
+    let body;
+    if (r.responseBody !== void 0 && r.responseBody !== null) {
+      const raw = typeof r.responseBody === "string" ? r.responseBody : JSON.stringify(r.responseBody);
+      const flat = raw.replace(/\s+/g, " ").trim();
+      body = flat.length > SERVER_ERROR_BODY_MAX ? flat.slice(0, SERVER_ERROR_BODY_MAX) + "\u2026" : flat;
+      if (/^\s*<(!doctype|html)/i.test(raw)) {
+        const m = raw.match(/<title[^>]*>([^<]*)<\/title>|<h1[^>]*>([^<]*)<\/h1>/i);
+        body = m ? `[html] ${(m[1] || m[2] || "").trim()}` : "[html page]";
+      }
+    }
+    out.push({ stepIndex: r.triggeredAtStep, method: r.method, url: r.url, status: r.responseStatus, body });
+  }
+  return out;
+}
 function extractAuth(requests) {
   const auth = { cookies: {}, tokens: {} };
   for (const req of requests) {
@@ -5245,7 +5690,7 @@ function buildCapturedApi(requests) {
   }
   return apis.sort((a, b) => b.endpoints.length - a.endpoints.length);
 }
-var SKIP_RESOURCE_TYPES, SKIP_EXTENSIONS, BROWSER_NOISE_HEADERS, AUTH_HEADER_PATTERNS, ID_PATTERNS, ApiCapture;
+var SKIP_RESOURCE_TYPES, SKIP_EXTENSIONS, BROWSER_NOISE_HEADERS, AUTH_HEADER_PATTERNS, ID_PATTERNS, ApiCapture, SERVER_ERROR_BODY_MAX;
 var init_api_capture = __esm({
   "src/lib/api-capture.ts"() {
     "use strict";
@@ -5415,10 +5860,19 @@ var init_api_capture = __esm({
           await new Promise((r) => setTimeout(r, 100));
         }
       }
+      /** Requests fired but not yet answered. */
+      hasPending() {
+        return this.pendingRequests.size > 0;
+      }
       getResults() {
         return buildCapturedApi(this.requests);
       }
+      /** Every HTTP >= 400 response, compact, in capture order. */
+      getServerErrors() {
+        return serverErrorsFrom(this.requests);
+      }
     };
+    SERVER_ERROR_BODY_MAX = 600;
   }
 });
 
@@ -5597,10 +6051,35 @@ function classifyError(err, step) {
   if (step.type === "solve-captcha") return "captcha-unsolvable";
   return "action-failed";
 }
+async function refineError(page, step, ctx, errorType, message) {
+  if (errorType !== "stale-state" && errorType !== "timeout") return { errorType, message };
+  const raw = step.selector;
+  if (typeof raw !== "string") return { errorType, message };
+  let resolved;
+  try {
+    resolved = resolveSelector(raw, ctx);
+  } catch {
+    return { errorType, message };
+  }
+  try {
+    const probe = page.evaluate((sel) => !!document.querySelector(sel), resolved);
+    const budget = new Promise((r) => setTimeout(() => r(null), TIMING.FAILURE_PROBE));
+    const found = await Promise.race([probe, budget]);
+    if (found !== false) return { errorType, message };
+  } catch {
+    return { errorType, message };
+  }
+  const shown = resolved === raw ? `"${raw}"` : `"${raw}" (\u2192 ${resolved})`;
+  return {
+    errorType: "element-not-found",
+    message: `No element matches ${shown} on the current page \u2014 the step waited for it to appear and it never did. It most likely existed when you looked and was re-rendered away before this step ran. (${message})`
+  };
+}
 function isRetryable(errorType) {
   return errorType === "stale-state" || errorType === "timeout" || errorType === "element-not-found";
 }
-function getSuggestion(errorType, step) {
+function getSuggestion(errorType, step, message = "") {
+  if (message.includes("tab stopped responding")) return UNRESPONSIVE_SUGGESTION;
   const usedEphemeralRef = typeof step.selector === "string" && step.selector.startsWith("@e");
   if (usedEphemeralRef && (errorType === "element-not-found" || errorType === "timeout" || errorType === "stale-state")) {
     return "The @e ref went stale \u2014 the page (likely a React/SPA) re-rendered and dropped it since the snapshot. Take a fresh `snapshot`/`find` right before acting, or save the element as a durable `@a:` anchor with the `remember` tool.";
@@ -5609,7 +6088,7 @@ function getSuggestion(errorType, step) {
     case "stale-state":
       return "The page stopped responding. The step may have triggered a very slow load or the server may be unreachable.";
     case "element-not-found":
-      return `Selector not found. The page structure may have changed. Take a screenshot to inspect the current state.`;
+      return "Selector not found. Either it is wrong, or the page re-rendered the element away (SPAs swap DOM nodes on every state change, so a selector that worked a second ago can return nothing now). Take a fresh `snapshot`/`find` immediately before acting and retry; if it keeps vanishing, `wait-for` it first.";
     case "navigation-failed":
       return "Navigation failed. The URL may be unreachable, blocked, or require authentication.";
     case "captcha-unsolvable":
@@ -5620,7 +6099,7 @@ function getSuggestion(errorType, step) {
       return void 0;
   }
 }
-var DEFAULT_STALE_TIMEOUT_MS2, PipelineRunner;
+var DEFAULT_STALE_TIMEOUT_MS2, UNRESPONSIVE_SUGGESTION, PipelineRunner;
 var init_pipeline = __esm({
   "src/lib/pipeline.ts"() {
     "use strict";
@@ -5636,7 +6115,10 @@ var init_pipeline = __esm({
     init_constants();
     init_component_map();
     init_resolve_selector();
+    init_constants();
+    init_budget();
     DEFAULT_STALE_TIMEOUT_MS2 = 2e4;
+    UNRESPONSIVE_SUGGESTION = "The tab's JavaScript stopped answering during this step. Run a single `read` or `snapshot` on its own to see if it recovered (it usually does). If this step froze it, don't repeat it as-is: for a route change in a single-page app use `evaluate` with `location.assign(url)`; for a click, use a fresh `@e` ref from `find`; avoid `evaluate` calls that scroll or re-render.";
     PipelineRunner = class {
       constructor(ctx, hooks) {
         this.ctx = ctx;
@@ -5644,6 +6126,9 @@ var init_pipeline = __esm({
       }
       ctx;
       hooks;
+      /** Live progress, readable while run() is still pending — lets an outer
+       *  watchdog report WHICH step hung and what already finished. */
+      progress = { stepIndex: -1, results: [] };
       async run(initialPage, pipeline) {
         const tracker = new TabTracker(initialPage.context(), initialPage);
         try {
@@ -5661,6 +6146,7 @@ var init_pipeline = __esm({
         const continueOnError = opts.continueOnError ?? false;
         const results = [];
         const obstacles = [];
+        this.progress.results = results;
         const navStep = pipeline.steps.find((s) => s.type === "navigate");
         try {
           const host = new URL(navStep?.url || safePageUrl(initialPage) || "http://x").hostname;
@@ -5678,12 +6164,18 @@ var init_pipeline = __esm({
         if (capture) capture.start();
         const finishCapture = async () => {
           if (!capture) return void 0;
+          await capture.drain(TIMING.CAPTURE_SETTLE, TIMING.CAPTURE_PENDING_MAX);
           capture.stop();
+          for (const se of capture.getServerErrors()) {
+            const r = results.find((x) => x.stepIndex === se.stepIndex);
+            if (r) (r.serverErrors ??= []).push(se);
+          }
           return capture.getResults();
         };
         for (let i = 0; i < pipeline.steps.length; i++) {
           if (capture) capture.setStep(i);
           const step = pipeline.steps[i];
+          this.progress.stepIndex = i;
           const page = tracker.active();
           const urlBefore = safePageUrl(page);
           const monitor = new StaleStateMonitor(page, staleTimeoutMs);
@@ -5703,9 +6195,10 @@ var init_pipeline = __esm({
               throw err;
             }
             const asError = err instanceof Error ? err : new Error(String(err));
-            const errorType = classifyError(asError, step);
+            const refined = await refineError(tracker.active(), step, this.ctx, classifyError(asError, step), asError.message);
+            const errorType = refined.errorType;
             const pageState = await capturePageState(tracker.active(), this.ctx, { screenshot: true });
-            stepResult = failedStepResult(step, asError.message, Date.now() - startTime, i);
+            stepResult = failedStepResult(step, refined.message, Date.now() - startTime, i);
             results.push(stepResult);
             recordAnchor(step, false);
             return {
@@ -5719,9 +6212,9 @@ var init_pipeline = __esm({
                 failedAtStep: i,
                 failedStep: step,
                 errorType,
-                message: asError.message,
+                message: refined.message,
                 pageState,
-                suggestion: getSuggestion(errorType, step),
+                suggestion: getSuggestion(errorType, step, refined.message),
                 retryable: isRetryable(errorType)
               },
               durationMs: Date.now() - startTime,
@@ -5755,8 +6248,16 @@ var init_pipeline = __esm({
           }
           results.push(stepResult);
           if (!stepResult.ok && !continueOnError) {
+            const refined = await refineError(
+              tracker.active(),
+              step,
+              this.ctx,
+              classifyError(new Error(stepResult.error || ""), step),
+              stepResult.error || "Step failed"
+            );
+            stepResult.error = refined.message;
+            const errorType = refined.errorType;
             const pageState = await capturePageState(tracker.active(), this.ctx, { screenshot: true });
-            const errorType = classifyError(new Error(stepResult.error || ""), step);
             return {
               ok: false,
               completedSteps: i,
@@ -5770,7 +6271,7 @@ var init_pipeline = __esm({
                 errorType,
                 message: stepResult.error || "Step failed",
                 pageState,
-                suggestion: getSuggestion(errorType, step),
+                suggestion: getSuggestion(errorType, step, refined.message),
                 retryable: isRetryable(errorType)
               },
               durationMs: Date.now() - startTime,
@@ -5780,7 +6281,7 @@ var init_pipeline = __esm({
           if (step.type === "navigate" && continueOnObstacle) {
             const obstacleStart = Date.now();
             const obstaclePage = tracker.active();
-            const obstacle = await detectObstacles(obstaclePage);
+            const obstacle = await withBudget(detectObstacles(obstaclePage), 1e4, "obstacle check").catch(() => null);
             if (obstacle) {
               const resolution = await resolveObstacle(obstaclePage, obstacle, this.ctx, monitor);
               obstacles.push({
@@ -10235,7 +10736,7 @@ var init_cdp_relay = __esm({
           return await Promise.race([
             first,
             new Promise((_, reject) => {
-              const t = setTimeout(() => reject(new Error("screenshot timed out (no compositor frame)")), 1e4);
+              const t = setTimeout(() => reject(new Error("screenshot timed out (no compositor frame)")), 5e3);
               t.unref?.();
             })
           ]);
@@ -10295,6 +10796,24 @@ var init_cdp_relay = __esm({
 });
 
 // src/lib/execution/pipeline-executor.ts
+function blankPipelineResult(pipeline, modeUsed, error) {
+  return {
+    ok: false,
+    completedSteps: 0,
+    totalSteps: pipeline.steps.length,
+    results: [],
+    obstacles: [],
+    error: {
+      failedAtStep: 0,
+      failedStep: pipeline.steps[0],
+      pageState: { url: "", title: "" },
+      ...error
+    },
+    durationMs: 0,
+    modeUsed,
+    finalState: { url: "", title: "" }
+  };
+}
 var import_playwright_core, log18, PipelineExecutor;
 var init_pipeline_executor = __esm({
   "src/lib/execution/pipeline-executor.ts"() {
@@ -10351,8 +10870,24 @@ var init_pipeline_executor = __esm({
         const forcedMode = opts.mode;
         const autoEscalate = opts.autoEscalate !== false;
         const instanceId = opts.instanceId || DEFAULT_INSTANCE;
+        if (forcedMode === "extension") {
+          return blankPipelineResult(pipeline, "extension", {
+            errorType: "action-failed",
+            message: 'mode="extension" requires options.tabId (the real-Chrome tab to drive).',
+            suggestion: "Call the `tabs` tool (or GET /extension/tabs) to list open tabs, then pass that tab id. Nothing was launched.",
+            retryable: false
+          });
+        }
         const firstNav = pipeline.steps.find((s) => s.type === "navigate");
         const domain = firstNav ? new URL(firstNav.url).hostname : null;
+        if (!firstNav && !this.deps.daemon.findLiveMode(instanceId)) {
+          return blankPipelineResult(pipeline, forcedMode || "headless", {
+            errorType: "action-failed",
+            message: `No navigate step and no live browser for instanceId "${instanceId}" to act on.`,
+            suggestion: "Add a navigate step, or reattach to a live window (check `status` / `iframer instances` for instanceId). To drive a real Chrome tab, pass options.tabId from the `tabs` tool. Nothing was launched.",
+            retryable: false
+          });
+        }
         const availableModes = this.deps.availableModes();
         const liveMode = forcedMode ? null : this.deps.daemon.findLiveMode(instanceId);
         let mode;
@@ -10416,6 +10951,7 @@ var init_pipeline_executor = __esm({
         const startTime = Date.now();
         const relay = new CdpRelay(tabId, clientId, pipeline.options?.focus);
         let browser;
+        let runner;
         try {
           await relay.start();
           browser = await import_playwright_core.chromium.connectOverCDP(relay.httpEndpoint(), { timeout: 3e4 });
@@ -10428,7 +10964,8 @@ var init_pipeline_executor = __esm({
           if (!page) throw new Error("no page available for the tab (is it still open?)");
           const ctx = this.deps.refStore.makeContext(userId, token);
           if (this.pendingElicitOtp) ctx.elicitOtp = this.pendingElicitOtp;
-          const runner = new PipelineRunner(ctx);
+          ctx.driver = "extension";
+          runner = new PipelineRunner(ctx);
           const typeChars = pipeline.steps.reduce((n, s) => {
             const v = s.value;
             return (s.type === "human-type" || s.type === "type-code") && typeof v === "string" ? n + v.length : n;
@@ -10445,7 +10982,7 @@ var init_pipeline_executor = __esm({
                 watchdog = setTimeout(
                   () => reject(
                     new Error(
-                      `pipeline exceeded ${Math.round(capMs / 1e3)}s \u2014 the tab may have stopped rendering (minimized window?). Un-minimize the Chrome window or retry with options.focus=true.`
+                      `pipeline exceeded ${Math.round(capMs / 1e3)}s \u2014 a call into the tab never returned.`
                     )
                   ),
                   capMs
@@ -10469,23 +11006,26 @@ var init_pipeline_executor = __esm({
         } catch (err) {
           const msg = getErrorMessage(err);
           const stalled = msg.includes("pipeline exceeded");
+          const done = runner ? runner.progress.results.filter((r) => r.ok) : [];
+          const hungAt = stalled && runner && runner.progress.stepIndex >= 0 ? runner.progress.stepIndex : 0;
+          const hungStep = pipeline.steps[hungAt];
           return {
             ok: false,
-            completedSteps: 0,
+            completedSteps: stalled ? done.length : 0,
             totalSteps: pipeline.steps.length,
-            results: [],
+            results: stalled ? done : [],
             finalState: { url: "", title: "" },
             obstacles: [],
             durationMs: Date.now() - startTime,
             modeUsed: "extension",
             error: {
-              failedAtStep: 0,
-              failedStep: pipeline.steps[0],
-              errorType: "action-failed",
-              message: `Extension mode failed: ${msg}`,
+              failedAtStep: hungAt,
+              failedStep: hungStep,
+              errorType: stalled ? "stale-state" : "action-failed",
+              message: stalled ? `Extension mode: step ${hungAt} (${hungStep?.type}) never returned; ${msg}` : `Extension mode failed: ${msg}`,
               pageState: { url: "", title: "" },
-              suggestion: stalled ? "STOP retrying and tell the user what happened: the Chrome tab being driven stopped responding \u2014 its window is likely minimized or the page is wedged. Ask them to un-minimize the Chrome window (leaving it behind other windows is fine), or ask permission to rerun with options.focus=true to bring it to the front." : "Ensure the iframer extension is connected (green dot) and the tab is still open. See chrome://extensions.",
-              retryable: !stalled
+              suggestion: stalled ? `Step ${hungAt} (${hungStep?.type}) hung inside the tab. Steps before it completed. Run a single \`read\` or \`snapshot\` on its own to check the tab recovered (it usually does), then continue from that step in its own execute call. Don't repeat the same step unchanged: for a route change use \`evaluate\` with \`location.assign(url)\`, for a click use a fresh \`@e\` ref from \`find\`. If the tab stays unresponsive, tell the user.` : "Ensure the iframer extension is connected (green dot) and the tab is still open. See chrome://extensions.",
+              retryable: stalled
             }
           };
         } finally {
@@ -11105,6 +11645,11 @@ var init_iframer = __esm({
       listInstances() {
         return this.daemon.instancesInfo();
       }
+      /** Close browsers that never navigated anywhere. See
+       *  BrowserDaemon.sweepBlankInstances — called from the server's reap tick. */
+      sweepBlankBrowsers() {
+        return this.daemon.sweepBlankInstances();
+      }
       /** Kill all browser instances and reset state. Next execute call will
        *  launch a fresh browser automatically — no manual restart needed. */
       async restartBrowser() {
@@ -11244,6 +11789,13 @@ ${api.domain} (${api.baseUrl})`);
       }
     }
   }
+  const serverErrors = (data.results || []).flatMap((r) => r.serverErrors || []);
+  if (serverErrors.length > 0) {
+    lines.push("\n--- Server errors (HTTP >= 400) ---");
+    for (const se of serverErrors) {
+      lines.push(`  [step ${se.stepIndex}] ${se.method} ${se.url} \u2192 ${se.status}${se.body ? `: ${se.body}` : ""}`);
+    }
+  }
   if (data.error) {
     lines.push("\n--- Failure ---");
     if (typeof data.error === "string") {
@@ -11254,6 +11806,10 @@ ${api.domain} (${api.baseUrl})`);
       lines.push(`Message: ${data.error.message}`);
       lines.push(`Retryable: ${data.error.retryable}`);
       if (data.error.suggestion) lines.push(`Suggestion: ${data.error.suggestion}`);
+      const atFailure = serverErrors.filter((se) => se.stepIndex === data.error?.failedAtStep);
+      for (const se of atFailure) {
+        lines.push(`Server responded: ${se.method} ${se.url} \u2192 ${se.status}${se.body ? `: ${se.body}` : ""}`);
+      }
       if (data.error.pageState?.url) lines.push(`URL at failure: ${data.error.pageState.url}`);
     }
   }
@@ -11670,6 +12226,21 @@ function parseFlag(args2, flag, hasValue = true) {
 function hasFlag(args2, flag) {
   return args2.includes(flag);
 }
+var LAUNCH_MODES = ["headless", "binary-headful", "docker-headful"];
+function parseModeFlag(args2) {
+  const mode = parseFlag(args2, "--mode");
+  if (!mode) return void 0;
+  if (LAUNCH_MODES.includes(mode)) return mode;
+  if (mode === "extension") {
+    console.error("\n  --mode extension is not available from the CLI: it needs a tab id.");
+    console.error("  Use the `tabs` tool from your agent, or POST /extension/execute with a tabId.\n");
+    process.exit(1);
+  }
+  console.error(`
+  Unknown --mode "${mode}". Use one of: ${LAUNCH_MODES.join(", ")}.
+`);
+  process.exit(1);
+}
 function handleResponse(data, screenshotPath) {
   const { screenshot: screenshot2, tileScreenshots, ...rest } = data;
   if (screenshot2 && screenshotPath) {
@@ -12144,7 +12715,7 @@ async function main() {
         process.exit(1);
       }
       const options = { ...inputOptions };
-      const mode = parseFlag(args, "--mode");
+      const mode = parseModeFlag(args);
       if (mode) options.mode = mode;
       if (hasFlag(args, "--capture-api")) options.captureApi = true;
       if (hasFlag(args, "--continue-on-error")) options.continueOnError = true;
@@ -12229,7 +12800,7 @@ Screenshot: ${shot}`);
       const url = args[0];
       const outPath = parseFlag(args, "--output") || parseFlag(args, "-o") || "/tmp/iframer-screenshot.jpg";
       if (url && url.startsWith("http")) {
-        const mode = parseFlag(args, "--mode") || "headless";
+        const mode = parseModeFlag(args) || "headless";
         const annotate = hasFlag(args, "--annotate");
         const docker = await isDockerRunning();
         const steps = [
@@ -12460,7 +13031,7 @@ Screenshot: ${shot}`);
         process.exit(1);
       }
       const options = { captureApi: true };
-      const mode = parseFlag(args, "--mode");
+      const mode = parseModeFlag(args);
       if (mode) options.mode = mode;
       const docker = await isDockerRunning();
       let result;