iframer-toolkit 0.10.5 → 0.10.8

package/dist/local-server.cjs

@@ -35,6 +35,23 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// src/lib/paths.ts
+var paths_exports = {};
+__export(paths_exports, {
+  getDataDir: () => getDataDir
+});
+function getDataDir() {
+  return process.env.IFRAMER_DATA_DIR || import_path.default.join(import_os.default.homedir(), ".iframer");
+}
+var import_path, import_os;
+var init_paths = __esm({
+  "src/lib/paths.ts"() {
+    "use strict";
+    import_path = __toESM(require("path"));
+    import_os = __toESM(require("os"));
+  }
+});
+
 // src/lib/session/persistence.ts
 var persistence_exports = {};
 __export(persistence_exports, {
@@ -96,23 +113,6 @@ var init_persistence = __esm({
   }
 });
 
-// src/lib/paths.ts
-var paths_exports = {};
-__export(paths_exports, {
-  getDataDir: () => getDataDir
-});
-function getDataDir() {
-  return process.env.IFRAMER_DATA_DIR || import_path.default.join(import_os.default.homedir(), ".iframer");
-}
-var import_path, import_os;
-var init_paths = __esm({
-  "src/lib/paths.ts"() {
-    "use strict";
-    import_path = __toESM(require("path"));
-    import_os = __toESM(require("os"));
-  }
-});
-
 // index.ts
 var import_express = __toESM(require("express"));
 var import_path12 = __toESM(require("path"));
@@ -127,11 +127,11 @@ var import_path11 = __toESM(require("path"));
 var import_url = require("url");
 
 // src/lib/browser/session-manager.ts
-var import_child_process = require("child_process");
-var import_fs2 = __toESM(require("fs"));
+var import_child_process2 = require("child_process");
+var import_fs3 = __toESM(require("fs"));
 
 // src/lib/browser/launcher.ts
-var import_fs = __toESM(require("fs"));
+var import_fs2 = __toESM(require("fs"));
 var import_patchright = require("patchright");
 
 // src/lib/browser/stealth.ts
@@ -542,22 +542,213 @@ function createLogger(tag) {
   };
 }
 
+// src/lib/browser/registry.ts
+var import_fs = __toESM(require("fs"));
+var import_path2 = __toESM(require("path"));
+var import_child_process = require("child_process");
+init_paths();
+var log = createLogger("registry");
+function browsersDir() {
+  const dir = import_path2.default.join(getDataDir(), "browsers");
+  import_fs.default.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+function serverInfoPath() {
+  return import_path2.default.join(getDataDir(), "server.json");
+}
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function pidMatchesMarker(pid, marker) {
+  if (!isPidAlive(pid)) return false;
+  try {
+    const cmd = (0, import_child_process.execSync)(`ps -o command= -p ${pid}`, { encoding: "utf8" });
+    return cmd.includes(marker);
+  } catch {
+    return false;
+  }
+}
+function findChromePidByMarker(marker) {
+  try {
+    const out = (0, import_child_process.execSync)(`pgrep -f -- "${marker}"`, { encoding: "utf8" }).trim();
+    const pids = out.split("\n").map((s) => parseInt(s, 10)).filter((n) => Number.isInteger(n) && n !== process.pid);
+    if (pids.length === 0) return null;
+    return Math.min(...pids);
+  } catch {
+    return null;
+  }
+}
+function registerBrowser(rec) {
+  try {
+    import_fs.default.writeFileSync(import_path2.default.join(browsersDir(), `${rec.chromePid}.json`), JSON.stringify(rec, null, 2));
+  } catch (err) {
+    log.warn(`failed to write browser record for pid ${rec.chromePid}: ${err}`);
+  }
+}
+function unregisterBrowser(chromePid) {
+  try {
+    import_fs.default.unlinkSync(import_path2.default.join(browsersDir(), `${chromePid}.json`));
+  } catch {
+  }
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function forceKillBrowser(rec) {
+  if (!isPidAlive(rec.chromePid)) return true;
+  if (!pidMatchesMarker(rec.chromePid, rec.marker)) {
+    return true;
+  }
+  try {
+    process.kill(rec.chromePid, "SIGKILL");
+  } catch {
+  }
+  const deadline = Date.now() + 2e3;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(rec.chromePid)) return true;
+    await sleep(100);
+  }
+  return !isPidAlive(rec.chromePid);
+}
+async function reapOrphanBrowsers() {
+  let reaped = 0;
+  let skipped = 0;
+  let files = [];
+  try {
+    files = import_fs.default.readdirSync(browsersDir()).filter((f) => f.endsWith(".json"));
+  } catch {
+    return { reaped, skipped };
+  }
+  for (const file of files) {
+    const full = import_path2.default.join(browsersDir(), file);
+    let rec;
+    try {
+      rec = JSON.parse(import_fs.default.readFileSync(full, "utf8"));
+    } catch {
+      try {
+        import_fs.default.unlinkSync(full);
+      } catch {
+      }
+      continue;
+    }
+    if (!isPidAlive(rec.chromePid) || !pidMatchesMarker(rec.chromePid, rec.marker)) {
+      try {
+        import_fs.default.unlinkSync(full);
+      } catch {
+      }
+      continue;
+    }
+    if (isPidAlive(rec.ownerPid)) {
+      skipped++;
+      continue;
+    }
+    log.info(`reaping orphan Chrome pid=${rec.chromePid} (${rec.key}), owner ${rec.ownerPid} is dead`);
+    if (await forceKillBrowser(rec)) {
+      try {
+        import_fs.default.unlinkSync(full);
+      } catch {
+      }
+      reaped++;
+    } else {
+      log.warn(`failed to kill orphan Chrome pid=${rec.chromePid} \u2014 leaving record for next sweep`);
+    }
+  }
+  return { reaped, skipped };
+}
+function writeServerInfo(info) {
+  import_fs.default.writeFileSync(serverInfoPath(), JSON.stringify(info, null, 2));
+}
+function readServerInfo() {
+  try {
+    const info = JSON.parse(import_fs.default.readFileSync(serverInfoPath(), "utf8"));
+    if (!Number.isInteger(info.pid) || !Number.isInteger(info.port)) return null;
+    return info;
+  } catch {
+    return null;
+  }
+}
+function clearServerInfo(pid) {
+  const info = readServerInfo();
+  if (info && info.pid === pid) {
+    try {
+      import_fs.default.unlinkSync(serverInfoPath());
+    } catch {
+    }
+  }
+}
+
 // src/lib/browser/launcher.ts
-var log = createLogger("launcher");
+var log2 = createLogger("launcher");
 var UBLOCK_PATH = "/extensions/uBlock0.chromium";
 function findChromeExecutable() {
   if (process.env.CHROME_EXECUTABLE) return process.env.CHROME_EXECUTABLE;
-  if (import_fs.default.existsSync("/usr/bin/google-chrome-stable")) return "/usr/bin/google-chrome-stable";
+  if (import_fs2.default.existsSync("/usr/bin/google-chrome-stable")) return "/usr/bin/google-chrome-stable";
   return void 0;
 }
 var cachedBrowser = null;
+var headedBrowser = null;
+var headedPid = null;
+var headedIdleTimer = null;
+var HEADED_IDLE_MS = 5 * 60 * 1e3;
+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()) {
+    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;
     try {
       await cachedBrowser.close();
     } catch (e) {
-      log.warn(`stale browser close failed: ${e}`);
+      log2.warn(`stale browser close failed: ${e}`);
     }
     cachedBrowser = null;
   }
@@ -568,11 +759,12 @@ async function getBrowser(_name = "chromium") {
   return cachedBrowser;
 }
 async function closeBrowser() {
+  await closeHeadedBrowser();
   if (!cachedBrowser) return;
   try {
     await cachedBrowser.close();
   } catch (e) {
-    log.warn(`closeBrowser failed: ${e}`);
+    log2.warn(`closeBrowser failed: ${e}`);
   }
   cachedBrowser = null;
 }
@@ -581,7 +773,7 @@ async function getBrowserWithFallback(_preferred) {
 }
 async function launchHeadful(displayNum) {
   const executablePath = findChromeExecutable();
-  const hasExtensions = import_fs.default.existsSync(UBLOCK_PATH);
+  const hasExtensions = import_fs2.default.existsSync(UBLOCK_PATH);
   const args = [
     "--no-sandbox",
     "--disable-setuid-sandbox",
@@ -601,7 +793,7 @@ async function launchHeadful(displayNum) {
     env: { ...process.env, DISPLAY: `:${displayNum}` }
   };
   if (executablePath) launchOpts.executablePath = executablePath;
-  log.debug(`headful: ${executablePath || "patchright chromium"}, extensions: ${hasExtensions}`);
+  log2.debug(`headful: ${executablePath || "patchright chromium"}, extensions: ${hasExtensions}`);
   return import_patchright.chromium.launch(launchOpts);
 }
 
@@ -658,7 +850,13 @@ var TIMING = {
   /** 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
 };
 var CAPTCHA_GRID = {
   /** Pixels from bframe top to grid start (reCAPTCHA) */
@@ -696,6 +894,10 @@ var TIMEOUTS = {
   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,
@@ -742,7 +944,7 @@ function generateWindowsFingerprint() {
 }
 
 // src/lib/browser/session-manager.ts
-var log2 = createLogger("session");
+var log3 = createLogger("session");
 var BASE_DISPLAY = parseInt(process.env.VNC_BASE_DISPLAY || "99", 10);
 var MAX_SESSIONS = parseInt(process.env.VNC_MAX_SESSIONS || "20", 10);
 var SESSION_TIMEOUT = parseInt(process.env.VNC_SESSION_TIMEOUT_MS || "300000", 10);
@@ -766,7 +968,7 @@ function waitForSocket(displayNum, timeoutMs = 5e3) {
   return new Promise((resolve, reject) => {
     const start = Date.now();
     const check = () => {
-      if (import_fs2.default.existsSync(socketPath)) return resolve();
+      if (import_fs3.default.existsSync(socketPath)) return resolve();
       if (Date.now() - start > timeoutMs) return reject(new Error(`Xvfb socket not ready after ${timeoutMs}ms`));
       setTimeout(check, 100);
     };
@@ -788,17 +990,17 @@ async function startSession(userId) {
   const displayNum = allocateDisplay();
   const vncPort = 5900 + displayNum;
   const wsPort = 6080 + (displayNum - BASE_DISPLAY);
-  const xvfb = (0, import_child_process.spawn)("Xvfb", [`:${displayNum}`, "-screen", "0", "1920x1080x24", "-ac"], {
+  const xvfb = (0, import_child_process2.spawn)("Xvfb", [`:${displayNum}`, "-screen", "0", "1920x1080x24", "-ac"], {
     stdio: "ignore"
   });
   await waitForSocket(displayNum);
-  const x11vnc = (0, import_child_process.spawn)(
+  const x11vnc = (0, import_child_process2.spawn)(
     "x11vnc",
     ["-display", `:${displayNum}`, "-nopw", "-listen", "localhost", "-rfbport", String(vncPort), "-shared", "-forever"],
     { stdio: "ignore" }
   );
-  const noVncPath = import_fs2.default.existsSync("/usr/share/novnc") ? "/usr/share/novnc" : "/usr/share/noVNC";
-  const websockify = (0, import_child_process.spawn)("websockify", ["--web", noVncPath, String(wsPort), `localhost:${vncPort}`], {
+  const noVncPath = import_fs3.default.existsSync("/usr/share/novnc") ? "/usr/share/novnc" : "/usr/share/noVNC";
+  const websockify = (0, import_child_process2.spawn)("websockify", ["--web", noVncPath, String(wsPort), `localhost:${vncPort}`], {
     stdio: "ignore"
   });
   await new Promise((r) => setTimeout(r, 500));
@@ -809,7 +1011,7 @@ async function startSession(userId) {
   const stealthScript = buildStealthScript(fingerprint);
   contextStealthScripts.set(context, stealthScript);
   const page = await context.newPage();
-  log2.debug(`fingerprint: ${fingerprint.userAgent.slice(0, 60)}... DPR=${fingerprint.deviceScaleFactor} screen=${fingerprint.screenWidth}x${fingerprint.screenHeight}`);
+  log3.debug(`fingerprint: ${fingerprint.userAgent.slice(0, 60)}... DPR=${fingerprint.deviceScaleFactor} screen=${fingerprint.screenWidth}x${fingerprint.screenHeight}`);
   const session = {
     displayNum,
     vncPort,
@@ -861,7 +1063,7 @@ async function stopSession(userId) {
   killProcess(session.xvfb);
   await new Promise((r) => setTimeout(r, 1e3));
   try {
-    import_fs2.default.unlinkSync(`/tmp/.X11-unix/X${session.displayNum}`);
+    import_fs3.default.unlinkSync(`/tmp/.X11-unix/X${session.displayNum}`);
   } catch {
   }
   freeDisplay(session.displayNum);
@@ -875,9 +1077,9 @@ async function cleanupAllSessions() {
 
 // src/lib/auth/crypto.ts
 var import_crypto = __toESM(require("crypto"));
-var import_fs3 = __toESM(require("fs"));
+var import_fs4 = __toESM(require("fs"));
 var import_os2 = __toESM(require("os"));
-var import_path2 = __toESM(require("path"));
+var import_path3 = __toESM(require("path"));
 init_paths();
 var SALT = "iframer-session";
 var INFO = "encryption";
@@ -887,21 +1089,21 @@ var TAG_LENGTH = 16;
 function getLocalToken() {
   if (process.env.IFRAMER_SECRET) return process.env.IFRAMER_SECRET;
   const candidates = [
-    import_path2.default.join(getDataDir(), "secret"),
-    import_path2.default.join(process.env.XDG_RUNTIME_DIR || import_os2.default.tmpdir(), "iframer-secret")
+    import_path3.default.join(getDataDir(), "secret"),
+    import_path3.default.join(process.env.XDG_RUNTIME_DIR || import_os2.default.tmpdir(), "iframer-secret")
   ];
   for (const file of candidates) {
     try {
-      const existing = import_fs3.default.readFileSync(file, "utf8").trim();
+      const existing = import_fs4.default.readFileSync(file, "utf8").trim();
       if (existing) return existing;
     } catch {
     }
   }
   for (const file of candidates) {
     try {
-      import_fs3.default.mkdirSync(import_path2.default.dirname(file), { recursive: true });
+      import_fs4.default.mkdirSync(import_path3.default.dirname(file), { recursive: true });
       const secret = import_crypto.default.randomBytes(32).toString("hex");
-      import_fs3.default.writeFileSync(file, secret, { mode: 384 });
+      import_fs4.default.writeFileSync(file, secret, { mode: 384 });
       return secret;
     } catch {
     }
@@ -961,17 +1163,17 @@ function generateTOTP(secret, period = 30, digits = 6) {
 init_persistence();
 
 // src/lib/screenshot.ts
-var import_fs4 = __toESM(require("fs"));
-var import_path3 = __toESM(require("path"));
-var log3 = createLogger("screenshot");
+var import_fs5 = __toESM(require("fs"));
+var import_path4 = __toESM(require("path"));
+var log4 = createLogger("screenshot");
 var MAX_AGE_MS = parseInt(process.env.IFRAMER_SCREENSHOT_MAX_AGE_MS || String(24 * 60 * 60 * 1e3), 10);
 var MAX_FILES = parseInt(process.env.IFRAMER_SCREENSHOT_MAX_FILES || "500", 10);
 var PRUNE_THROTTLE_MS = 5 * 60 * 1e3;
 var lastPruneAt = 0;
 function saveScreenshot(buffer, filename, screenshotDir, publicUrl) {
-  import_fs4.default.mkdirSync(screenshotDir, { recursive: true });
-  const filePath = import_path3.default.join(screenshotDir, filename);
-  import_fs4.default.writeFileSync(filePath, buffer);
+  import_fs5.default.mkdirSync(screenshotDir, { recursive: true });
+  const filePath = import_path4.default.join(screenshotDir, filename);
+  import_fs5.default.writeFileSync(filePath, buffer);
   maybePrune(screenshotDir);
   return `${publicUrl}/screenshots/${filename}`;
 }
@@ -986,10 +1188,10 @@ function pruneScreenshots(dir, opts = {}) {
   const maxFiles = opts.maxFiles ?? MAX_FILES;
   const now = opts.now ?? Date.now();
   try {
-    const entries = import_fs4.default.readdirSync(dir).filter((f) => f.endsWith(".jpg") || f.endsWith(".jpeg") || f.endsWith(".png")).map((f) => {
-      const full = import_path3.default.join(dir, f);
+    const entries = import_fs5.default.readdirSync(dir).filter((f) => f.endsWith(".jpg") || f.endsWith(".jpeg") || f.endsWith(".png")).map((f) => {
+      const full = import_path4.default.join(dir, f);
       try {
-        return { full, mtimeMs: import_fs4.default.statSync(full).mtimeMs };
+        return { full, mtimeMs: import_fs5.default.statSync(full).mtimeMs };
       } catch {
         return null;
       }
@@ -999,7 +1201,7 @@ function pruneScreenshots(dir, opts = {}) {
     for (const e of entries) {
       if (now - e.mtimeMs > maxAgeMs) {
         try {
-          import_fs4.default.unlinkSync(e.full);
+          import_fs5.default.unlinkSync(e.full);
           removed++;
         } catch {
         }
@@ -1011,23 +1213,23 @@ function pruneScreenshots(dir, opts = {}) {
       survivors.sort((a, b) => a.mtimeMs - b.mtimeMs);
       for (const e of survivors.slice(0, survivors.length - maxFiles)) {
         try {
-          import_fs4.default.unlinkSync(e.full);
+          import_fs5.default.unlinkSync(e.full);
           removed++;
         } catch {
         }
       }
     }
-    if (removed > 0) log3.debug(`pruned ${removed} old screenshot(s) from ${dir}`);
+    if (removed > 0) log4.debug(`pruned ${removed} old screenshot(s) from ${dir}`);
     return removed;
   } catch (err) {
-    log3.warn(`screenshot prune failed: ${err instanceof Error ? err.message : String(err)}`);
+    log4.warn(`screenshot prune failed: ${err instanceof Error ? err.message : String(err)}`);
     return 0;
   }
 }
 
 // src/lib/session/sqlite-store.ts
-var import_path4 = __toESM(require("path"));
-var import_fs5 = __toESM(require("fs"));
+var import_path5 = __toESM(require("path"));
+var import_fs6 = __toESM(require("fs"));
 var IS_BUN = typeof globalThis.Bun !== "undefined";
 function createBunDb(dbPath) {
   const { Database } = require("bun:sqlite");
@@ -1066,8 +1268,8 @@ function createNodeDb(dbPath) {
 var SqliteStore = class {
   db;
   constructor(dataDir) {
-    import_fs5.default.mkdirSync(dataDir, { recursive: true });
-    const dbPath = import_path4.default.join(dataDir, "iframer.db");
+    import_fs6.default.mkdirSync(dataDir, { recursive: true });
+    const dbPath = import_path5.default.join(dataDir, "iframer.db");
     this.db = IS_BUN ? createBunDb(dbPath) : createNodeDb(dbPath);
     this.db.run(`
       CREATE TABLE IF NOT EXISTS sessions (
@@ -1147,13 +1349,13 @@ var import_patchright2 = require("patchright");
 var import_crypto2 = require("crypto");
 
 // src/lib/browser/chrome-downloader.ts
-var import_fs6 = __toESM(require("fs"));
-var import_path5 = __toESM(require("path"));
+var import_fs7 = __toESM(require("fs"));
+var import_path6 = __toESM(require("path"));
 var import_os3 = __toESM(require("os"));
-var import_child_process2 = require("child_process");
-var log4 = createLogger("chrome");
+var import_child_process3 = require("child_process");
+var log5 = createLogger("chrome");
 var CHROME_VERSIONS_URL = "https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json";
-var DEFAULT_INSTALL_DIR = import_path5.default.join(import_os3.default.homedir(), ".iframer", "chrome");
+var DEFAULT_INSTALL_DIR = import_path6.default.join(import_os3.default.homedir(), ".iframer", "chrome");
 function getPlatform() {
   const arch = process.arch;
   const platform = process.platform;
@@ -1165,24 +1367,24 @@ function getPlatform() {
 function getChromeExecutablePath(installDir) {
   const platform = process.platform;
   if (platform === "darwin") {
-    const entries = import_fs6.default.readdirSync(installDir).filter((e) => e.startsWith("chrome-"));
+    const entries = import_fs7.default.readdirSync(installDir).filter((e) => e.startsWith("chrome-"));
     const dir = entries[0] || "chrome-mac-arm64";
-    return import_path5.default.join(installDir, dir, "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing");
+    return import_path6.default.join(installDir, dir, "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing");
   }
   if (platform === "linux") {
-    const entries = import_fs6.default.readdirSync(installDir).filter((e) => e.startsWith("chrome-"));
+    const entries = import_fs7.default.readdirSync(installDir).filter((e) => e.startsWith("chrome-"));
     const dir = entries[0] || "chrome-linux64";
-    return import_path5.default.join(installDir, dir, "chrome");
+    return import_path6.default.join(installDir, dir, "chrome");
   }
   if (platform === "win32") {
-    const entries = import_fs6.default.readdirSync(installDir).filter((e) => e.startsWith("chrome-"));
+    const entries = import_fs7.default.readdirSync(installDir).filter((e) => e.startsWith("chrome-"));
     const dir = entries[0] || "chrome-win64";
-    return import_path5.default.join(installDir, dir, "chrome.exe");
+    return import_path6.default.join(installDir, dir, "chrome.exe");
   }
   throw new Error(`Unsupported platform: ${platform}`);
 }
 async function downloadChrome(installDir = DEFAULT_INSTALL_DIR) {
-  log4.info("Downloading Chrome for Testing (first time only)...");
+  log5.info("Downloading Chrome for Testing (first time only)...");
   const res = await fetch(CHROME_VERSIONS_URL);
   if (!res.ok) throw new Error(`Failed to fetch Chrome versions: ${res.status}`);
   const data = await res.json();
@@ -1193,35 +1395,35 @@ async function downloadChrome(installDir = DEFAULT_INSTALL_DIR) {
   if (!download2) throw new Error(`No Chrome for Testing download for platform: ${platform}`);
   const url = download2.url;
   const version = channel.version;
-  log4.debug(`Version ${version} for ${platform}`);
-  log4.debug(`URL: ${url}`);
-  import_fs6.default.mkdirSync(installDir, { recursive: true });
-  const zipPath = import_path5.default.join(installDir, "chrome.zip");
+  log5.debug(`Version ${version} for ${platform}`);
+  log5.debug(`URL: ${url}`);
+  import_fs7.default.mkdirSync(installDir, { recursive: true });
+  const zipPath = import_path6.default.join(installDir, "chrome.zip");
   const dlRes = await fetch(url);
   if (!dlRes.ok) throw new Error(`Download failed: ${dlRes.status}`);
   const buf = Buffer.from(await dlRes.arrayBuffer());
-  import_fs6.default.writeFileSync(zipPath, buf);
-  log4.info(`Downloaded ${(buf.length / 1024 / 1024).toFixed(1)}MB`);
-  (0, import_child_process2.execSync)(`unzip -o -q "${zipPath}" -d "${installDir}"`, { stdio: "inherit" });
-  import_fs6.default.unlinkSync(zipPath);
+  import_fs7.default.writeFileSync(zipPath, buf);
+  log5.info(`Downloaded ${(buf.length / 1024 / 1024).toFixed(1)}MB`);
+  (0, import_child_process3.execSync)(`unzip -o -q "${zipPath}" -d "${installDir}"`, { stdio: "inherit" });
+  import_fs7.default.unlinkSync(zipPath);
   const execPath = getChromeExecutablePath(installDir);
-  if (!import_fs6.default.existsSync(execPath)) {
+  if (!import_fs7.default.existsSync(execPath)) {
     throw new Error(`Chrome executable not found after extraction: ${execPath}`);
   }
   if (process.platform !== "win32") {
-    import_fs6.default.chmodSync(execPath, 493);
+    import_fs7.default.chmodSync(execPath, 493);
   }
-  import_fs6.default.writeFileSync(import_path5.default.join(installDir, "version.json"), JSON.stringify({ version, platform, downloadedAt: (/* @__PURE__ */ new Date()).toISOString() }));
-  log4.info(`Installed at: ${execPath}`);
+  import_fs7.default.writeFileSync(import_path6.default.join(installDir, "version.json"), JSON.stringify({ version, platform, downloadedAt: (/* @__PURE__ */ new Date()).toISOString() }));
+  log5.info(`Installed at: ${execPath}`);
   return execPath;
 }
 function findChromeForTesting() {
   if (process.env.CHROME_EXECUTABLE) {
-    if (import_fs6.default.existsSync(process.env.CHROME_EXECUTABLE)) return process.env.CHROME_EXECUTABLE;
+    if (import_fs7.default.existsSync(process.env.CHROME_EXECUTABLE)) return process.env.CHROME_EXECUTABLE;
   }
   try {
     const execPath = getChromeExecutablePath(DEFAULT_INSTALL_DIR);
-    if (import_fs6.default.existsSync(execPath)) return execPath;
+    if (import_fs7.default.existsSync(execPath)) return execPath;
   } catch {
   }
   return null;
@@ -1241,8 +1443,8 @@ function findChrome() {
     // Playwright/Patchright installed browsers (Docker containers)
     ...(() => {
       try {
-        const dirs = import_fs6.default.readdirSync("/ms-playwright").filter((d) => d.startsWith("chromium-")).sort().reverse();
-        return dirs.map((d) => import_path5.default.join("/ms-playwright", d, "chrome-linux", "chrome"));
+        const dirs = import_fs7.default.readdirSync("/ms-playwright").filter((d) => d.startsWith("chromium-")).sort().reverse();
+        return dirs.map((d) => import_path6.default.join("/ms-playwright", d, "chrome-linux", "chrome"));
       } catch {
         return [];
       }
@@ -1252,7 +1454,7 @@ function findChrome() {
     "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe"
   ];
   for (const p of systemPaths) {
-    if (import_fs6.default.existsSync(p)) return p;
+    if (import_fs7.default.existsSync(p)) return p;
   }
   return null;
 }
@@ -1262,10 +1464,10 @@ async function ensureChrome() {
   try {
     return await downloadChrome();
   } catch (err) {
-    log4.error(`Failed to download Chrome for Testing: ${err instanceof Error ? err.message : String(err)}`);
+    log5.error(`Failed to download Chrome for Testing: ${err instanceof Error ? err.message : String(err)}`);
     const system = findChrome();
     if (system) {
-      log4.warn(`Falling back to system Chrome: ${system}`);
+      log5.warn(`Falling back to system Chrome: ${system}`);
       return system;
     }
     throw new Error("No Chrome found. Download failed and no system Chrome available.");
@@ -1273,7 +1475,7 @@ async function ensureChrome() {
 }
 
 // src/lib/browser/cloak-browser.ts
-var log5 = createLogger("cloak");
+var log6 = createLogger("cloak");
 var _available = null;
 function cloakEnabled() {
   return process.env.IFRAMER_USE_CLOAKBROWSER === "1" || process.env.IFRAMER_USE_CLOAKBROWSER === "true";
@@ -1292,14 +1494,14 @@ async function ensureBinary() {
   try {
     const info = cloak.binaryInfo();
     if (!info.installed) {
-      log5.info("Downloading CloakBrowser binary...");
+      log6.info("Downloading CloakBrowser binary...");
       await cloak.ensureBinary();
-      log5.info("CloakBrowser ready");
+      log6.info("CloakBrowser ready");
     }
     _available = true;
     return true;
   } catch (err) {
-    log5.warn(`CloakBrowser setup failed: ${err instanceof Error ? err.message : String(err)}`);
+    log6.warn(`CloakBrowser setup failed: ${err instanceof Error ? err.message : String(err)}`);
     _available = false;
     return false;
   }
@@ -1314,157 +1516,20 @@ async function launchCloakBrowser(options) {
       headless: options.headless,
       args: options.args
     });
-    log5.info(`CloakBrowser launched (headless=${options.headless})`);
+    log6.info(`CloakBrowser launched (headless=${options.headless})`);
     return browser;
   } catch (err) {
-    log5.warn(`CloakBrowser launch failed: ${err instanceof Error ? err.message : String(err)}`);
+    log6.warn(`CloakBrowser launch failed: ${err instanceof Error ? err.message : String(err)}`);
     return null;
   }
 }
 
-// src/lib/browser/registry.ts
-var import_fs7 = __toESM(require("fs"));
-var import_path6 = __toESM(require("path"));
-var import_child_process3 = require("child_process");
-init_paths();
-var log6 = createLogger("registry");
-function browsersDir() {
-  const dir = import_path6.default.join(getDataDir(), "browsers");
-  import_fs7.default.mkdirSync(dir, { recursive: true });
-  return dir;
-}
-function serverInfoPath() {
-  return import_path6.default.join(getDataDir(), "server.json");
-}
-function isPidAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 1) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function pidMatchesMarker(pid, marker) {
-  if (!isPidAlive(pid)) return false;
-  try {
-    const cmd = (0, import_child_process3.execSync)(`ps -o command= -p ${pid}`, { encoding: "utf8" });
-    return cmd.includes(marker);
-  } catch {
-    return false;
-  }
-}
-function findChromePidByMarker(marker) {
-  try {
-    const out = (0, import_child_process3.execSync)(`pgrep -f -- "${marker}"`, { encoding: "utf8" }).trim();
-    const pids = out.split("\n").map((s) => parseInt(s, 10)).filter((n) => Number.isInteger(n) && n !== process.pid);
-    if (pids.length === 0) return null;
-    return Math.min(...pids);
-  } catch {
-    return null;
-  }
-}
-function registerBrowser(rec) {
-  try {
-    import_fs7.default.writeFileSync(import_path6.default.join(browsersDir(), `${rec.chromePid}.json`), JSON.stringify(rec, null, 2));
-  } catch (err) {
-    log6.warn(`failed to write browser record for pid ${rec.chromePid}: ${err}`);
-  }
-}
-function unregisterBrowser(chromePid) {
-  try {
-    import_fs7.default.unlinkSync(import_path6.default.join(browsersDir(), `${chromePid}.json`));
-  } catch {
-  }
-}
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-async function forceKillBrowser(rec) {
-  if (!isPidAlive(rec.chromePid)) return true;
-  if (!pidMatchesMarker(rec.chromePid, rec.marker)) {
-    return true;
-  }
-  try {
-    process.kill(rec.chromePid, "SIGKILL");
-  } catch {
-  }
-  const deadline = Date.now() + 2e3;
-  while (Date.now() < deadline) {
-    if (!isPidAlive(rec.chromePid)) return true;
-    await sleep(100);
-  }
-  return !isPidAlive(rec.chromePid);
-}
-async function reapOrphanBrowsers() {
-  let reaped = 0;
-  let skipped = 0;
-  let files = [];
-  try {
-    files = import_fs7.default.readdirSync(browsersDir()).filter((f) => f.endsWith(".json"));
-  } catch {
-    return { reaped, skipped };
-  }
-  for (const file of files) {
-    const full = import_path6.default.join(browsersDir(), file);
-    let rec;
-    try {
-      rec = JSON.parse(import_fs7.default.readFileSync(full, "utf8"));
-    } catch {
-      try {
-        import_fs7.default.unlinkSync(full);
-      } catch {
-      }
-      continue;
-    }
-    if (!isPidAlive(rec.chromePid) || !pidMatchesMarker(rec.chromePid, rec.marker)) {
-      try {
-        import_fs7.default.unlinkSync(full);
-      } catch {
-      }
-      continue;
-    }
-    if (isPidAlive(rec.ownerPid)) {
-      skipped++;
-      continue;
-    }
-    log6.info(`reaping orphan Chrome pid=${rec.chromePid} (${rec.key}), owner ${rec.ownerPid} is dead`);
-    if (await forceKillBrowser(rec)) {
-      try {
-        import_fs7.default.unlinkSync(full);
-      } catch {
-      }
-      reaped++;
-    } else {
-      log6.warn(`failed to kill orphan Chrome pid=${rec.chromePid} \u2014 leaving record for next sweep`);
-    }
-  }
-  return { reaped, skipped };
-}
-function writeServerInfo(info) {
-  import_fs7.default.writeFileSync(serverInfoPath(), JSON.stringify(info, null, 2));
-}
-function readServerInfo() {
-  try {
-    const info = JSON.parse(import_fs7.default.readFileSync(serverInfoPath(), "utf8"));
-    if (!Number.isInteger(info.pid) || !Number.isInteger(info.port)) return null;
-    return info;
-  } catch {
-    return null;
-  }
-}
-function clearServerInfo(pid) {
-  const info = readServerInfo();
-  if (info && info.pid === pid) {
-    try {
-      import_fs7.default.unlinkSync(serverInfoPath());
-    } catch {
-    }
-  }
-}
-
 // src/lib/browser/daemon.ts
 var log7 = createLogger("daemon");
 var DEFAULT_IDLE_TIMEOUT = 5 * 60 * 1e3;
 var CLOSE_GRACE_MS = 5e3;
+var BUSY_MAX_MS = 30 * 60 * 1e3;
+var BLANK_IDLE_MS = 2 * 60 * 1e3;
 var DEFAULT_INSTANCE = "default";
 function keyOf(mode, instanceId) {
   return `${mode}::${instanceId}`;
@@ -1556,7 +1621,8 @@ var BrowserDaemon = class {
       createdAt: /* @__PURE__ */ new Date(),
       chromePid,
       marker,
-      active: 0
+      active: 0,
+      busySince: null
     };
     this.instances.set(key, instance);
     this.resetIdleTimer(key);
@@ -1568,14 +1634,19 @@ var BrowserDaemon = class {
    *  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));
@@ -1586,6 +1657,35 @@ var BrowserDaemon = class {
       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))];
@@ -1704,8 +1804,14 @@ var BrowserDaemon = class {
       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}`));
@@ -1880,6 +1986,53 @@ var RefStore = class {
   }
 };
 
+// src/lib/site-protection.ts
+var PROTECTED_INTERVAL_MS = 3e3;
+var nextRequest = /* @__PURE__ */ new Map();
+async function paceProtectedDomain(domain) {
+  const now = Date.now();
+  const slot = Math.max(now, nextRequest.get(domain) || 0);
+  nextRequest.set(domain, slot + PROTECTED_INTERVAL_MS);
+  if (slot > now) await new Promise((resolve) => setTimeout(resolve, slot - now));
+}
+async function detectSiteProtection(page) {
+  const cookies = await page.context().cookies(page.url()).catch(() => []);
+  if (cookies.some((c) => /^(incap_ses_|visid_incap_|nlbi_)/i.test(c.name))) return "imperva";
+  if (cookies.some((c) => /^(?:_abck|bm_sz|ak_bmsc|bm_sv)$/.test(c.name))) return "akamai";
+  const html = await page.content().catch(() => "");
+  if (/\/[_]Incapsula_Resource|incapsula incident id|powered by imperva/i.test(html)) return "imperva";
+  if (/errors\.edgesuite\.net|akamai bot manager/i.test(html)) return "akamai";
+  return null;
+}
+var HeadedRequiredError = class extends Error {
+  constructor(url) {
+    super("This site requires a headed browser.");
+    this.url = url;
+  }
+  url;
+  stepIndex = 0;
+  results = [];
+  obstacles = [];
+};
+function protectionHooks(headless, respectful = false) {
+  return {
+    before: async (page, step) => {
+      const protection = await detectSiteProtection(page);
+      if (protection) {
+        respectful = true;
+        if (headless) throw new HeadedRequiredError(page.url());
+      }
+      if (respectful) await paceProtectedDomain(new URL(step.url || page.url()).hostname);
+    },
+    after: async (page) => {
+      const protection = await detectSiteProtection(page);
+      if (!protection) return;
+      respectful = true;
+      if (headless) throw new HeadedRequiredError(page.url());
+    }
+  };
+}
+
 // src/lib/execution/pipeline-executor.ts
 var import_playwright_core = require("playwright-core");
 
@@ -2017,6 +2170,24 @@ async function humanType(page, selector, text, opts = {}) {
     await sleep3(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 sleep3(randRange(TIMING.CHAR_DELAY));
+    }
+  }
   const factor = SPEED_FACTOR[opts.speed || "normal"] ?? 1;
   for (const char of text) {
     await page.keyboard.type(char);
@@ -2172,7 +2343,36 @@ function sleep3(ms) {
 // src/lib/actions/handlers/navigation.ts
 init_persistence();
 
+// src/lib/budget.ts
+var BudgetExceededError = class extends Error {
+  constructor(label, ms) {
+    super(`${label} did not answer within ${ms}ms`);
+    this.name = "BudgetExceededError";
+  }
+};
+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);
+  });
+}
+
 // src/lib/actions/resolve-selector.ts
+var 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/;
+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);
@@ -2193,19 +2393,149 @@ 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;
 }
 
+// src/lib/reachability.ts
+var HONEYPOT_REASONS = /* @__PURE__ */ new Set(["zero-size", "hidden", "transparent", "offscreen", "clipped"]);
+var HONEYPOT_NAME_RE = /^(website|url|homepage|fax|honeypot|honey|hp|hp_[\w-]*|bot|bot_[\w-]*|trap|_gotcha|leave_?blank|do_?not_?fill)$/i;
+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
+  };
+}
+
 // src/lib/actions/handlers/navigation.ts
 var log9 = createLogger("actions");
-async function navigate(page, step, ctx) {
-  await page.goto(step.url, {
-    waitUntil: step.waitUntil || "domcontentloaded",
-    timeout: TIMEOUTS.NAVIGATION
-  });
+var NAV_COMMIT_SUSPECT_MS = 12e3;
+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);
@@ -2221,14 +2551,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;
@@ -2244,13 +2597,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);
@@ -2258,10 +2613,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 {
     }
   }
@@ -2285,7 +2642,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);
@@ -2328,7 +2685,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,
@@ -2513,6 +2892,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 path13 = [];
       let current = el;
@@ -2555,6 +2984,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 || "";
@@ -2567,7 +3001,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;
@@ -2588,6 +3023,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)) {
@@ -3936,6 +4372,8 @@ async function executeAction(page, step, ctx, monitor) {
 
 // src/lib/stale-monitor.ts
 var DEFAULT_STALE_TIMEOUT_MS = 2e4;
+var PROBE_BUDGET_MS = 3e3;
+var UNRESPONSIVE_GRACE_MS = 8e3;
 var StaleStateMonitor = class _StaleStateMonitor {
   page;
   timeoutMs;
@@ -3947,21 +4385,24 @@ var StaleStateMonitor = class _StaleStateMonitor {
   }
   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 {
@@ -4005,6 +4446,8 @@ var StaleStateMonitor = class _StaleStateMonitor {
     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);
@@ -4012,11 +4455,25 @@ var StaleStateMonitor = class _StaleStateMonitor {
         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;
@@ -4024,6 +4481,8 @@ var StaleStateMonitor = class _StaleStateMonitor {
         } catch {
           this.lastActivity = Date.now();
           return;
+        } finally {
+          probing = false;
         }
         cleanup();
         reject(new StaleStateError(
@@ -4047,10 +4506,13 @@ var StaleStateMonitor = class _StaleStateMonitor {
 };
 var 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;
   }
 };
 
@@ -4261,10 +4723,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 {
@@ -4636,10 +5102,37 @@ var ApiCapture = class {
       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);
+  }
 };
+var SERVER_ERROR_BODY_MAX = 600;
+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 auth2 = { cookies: {}, tokens: {} };
   for (const req of requests) {
@@ -4888,10 +5381,36 @@ 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) {
+var 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.";
+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.";
@@ -4900,7 +5419,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":
@@ -4912,10 +5431,15 @@ function getSuggestion(errorType, step) {
   }
 }
 var PipelineRunner = class {
-  constructor(ctx) {
+  constructor(ctx, hooks) {
     this.ctx = ctx;
+    this.hooks = hooks;
   }
   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 {
@@ -4933,6 +5457,7 @@ var PipelineRunner = class {
     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;
@@ -4950,27 +5475,41 @@ var PipelineRunner = class {
     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);
       let stepResult;
       try {
+        await this.hooks?.before(page, step);
         stepResult = await monitor.withMonitoring(async () => {
           const r = await executeAction(page, step, this.ctx, monitor);
+          if (step.type === "navigate") await this.hooks?.after(page, step.url);
           r.stepIndex = i;
           return r;
         });
       } catch (err) {
+        if (err instanceof HeadedRequiredError) {
+          Object.assign(err, { stepIndex: i, results, obstacles });
+          await finishCapture();
+          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 {
@@ -4984,9 +5523,9 @@ var PipelineRunner = class {
             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,
@@ -5020,8 +5559,16 @@ var PipelineRunner = class {
       }
       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,
@@ -5035,7 +5582,7 @@ var PipelineRunner = class {
             errorType,
             message: stepResult.error || "Step failed",
             pageState,
-            suggestion: getSuggestion(errorType, step),
+            suggestion: getSuggestion(errorType, step, refined.message),
             retryable: isRetryable(errorType)
           },
           durationMs: Date.now() - startTime,
@@ -5045,7 +5592,7 @@ var PipelineRunner = class {
       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({
@@ -5743,7 +6290,7 @@ var CdpRelay = class {
         return {};
       case "Browser.close":
         return {};
-      // patchright disconnect — don't kill the user's Chrome
+      // Disconnect without closing the user's Chrome.
       case "Target.setDiscoverTargets":
         return {};
       case "Target.getTargets":
@@ -5786,7 +6333,7 @@ var CdpRelay = class {
       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?.();
         })
       ]);
@@ -5845,13 +6392,31 @@ var CdpRelay = class {
 
 // src/lib/execution/pipeline-executor.ts
 var log18 = createLogger("iframer");
+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 PipelineExecutor = class {
   constructor(deps) {
     this.deps = deps;
   }
   deps;
-  /** Runtime elicitation hook, set per-call via execute(). Consumed once by
-   *  executeLocal and immediately cleared. */
+  /** Shared runtime hook read by local and extension execution;
+   *  execute() clears it when the call finishes. */
   pendingElicitOtp;
   /** One pipeline per real tab at a time: chrome.debugger and the CDP relay
    *  can't share a tab, so concurrent executes on the same tab queue up here. */
@@ -5882,8 +6447,24 @@ var PipelineExecutor = class {
     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;
@@ -5897,6 +6478,7 @@ var PipelineExecutor = class {
       mode = availableModes[0] || "headless";
     }
     let result = await this.executeWithMode(userId, token, pipeline, mode, instanceId);
+    mode = result.modeUsed || mode;
     if (!result.ok && autoEscalate && domain && result.error?.errorType === "bot-blocked") {
       const failedMode = mode;
       if (domain) this.deps.domainModes.recordFailure(domain, failedMode, result.error?.message || "blocked");
@@ -5933,11 +6515,11 @@ var PipelineExecutor = class {
     }
     return result;
   }
-  async executeWithMode(userId, token, pipeline, mode, instanceId = DEFAULT_INSTANCE) {
+  async executeWithMode(userId, token, pipeline, mode, instanceId = DEFAULT_INSTANCE, respectful = false) {
     if (mode === "docker-headful") {
-      return this.executeDocker(userId, token, pipeline);
+      return this.executeDocker(userId, token, pipeline, respectful);
     }
-    return this.executeLocal(userId, token, pipeline, mode, instanceId);
+    return this.executeLocal(userId, token, pipeline, mode, instanceId, respectful);
   }
   /** Execute against the user's real Chrome tab via the extension CDP relay,
    *  using the SAME PipelineRunner as every other mode. No session inject/extract
@@ -5946,6 +6528,7 @@ var PipelineExecutor = class {
     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 });
@@ -5958,7 +6541,8 @@ var PipelineExecutor = class {
       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;
@@ -5975,7 +6559,7 @@ var PipelineExecutor = class {
             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
@@ -5999,23 +6583,26 @@ var PipelineExecutor = class {
     } 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 {
@@ -6030,7 +6617,7 @@ var PipelineExecutor = class {
     }
   }
   /** Execute via Docker session-manager. */
-  async executeDocker(userId, token, pipeline) {
+  async executeDocker(userId, token, pipeline, respectful = false) {
     let session = getSession(userId);
     if (!session) {
       const firstNav = pipeline.steps.find((s) => s.type === "navigate");
@@ -6039,7 +6626,7 @@ var PipelineExecutor = class {
     }
     resetTimeout(userId);
     const ctx = this.deps.refStore.makeContext(userId, token);
-    const runner = new PipelineRunner(ctx);
+    const runner = new PipelineRunner(ctx, protectionHooks(false, respectful));
     const result = await runner.run(session.page, pipeline);
     if (result.ok) {
       const blockResult = await detectBlock(session.page);
@@ -6066,7 +6653,7 @@ var PipelineExecutor = class {
     return result;
   }
   /** Execute via local Chrome daemon (headless + binary-headful). */
-  async executeLocal(userId, token, pipeline, mode, instanceId = DEFAULT_INSTANCE) {
+  async executeLocal(userId, token, pipeline, mode, instanceId = DEFAULT_INSTANCE, respectful = false) {
     const startTime = Date.now();
     let acquired = false;
     try {
@@ -6088,8 +6675,38 @@ var PipelineExecutor = class {
       const ctx = this.deps.refStore.makeContext(userId, token);
       if (sessionData) ctx.sessionData = sessionData;
       if (this.pendingElicitOtp) ctx.elicitOtp = this.pendingElicitOtp;
-      const runner = new PipelineRunner(ctx);
-      const result = await runner.run(page, pipeline);
+      const runner = new PipelineRunner(ctx, protectionHooks(mode === "headless", respectful));
+      let result;
+      try {
+        result = await runner.run(page, pipeline);
+      } catch (err) {
+        if (!(err instanceof HeadedRequiredError)) throw err;
+        this.deps.daemon.release(mode, instanceId);
+        acquired = false;
+        await this.deps.daemon.stopMode(mode, instanceId);
+        const available = this.deps.availableModes();
+        const headed = available.includes("binary-headful") ? "binary-headful" : "docker-headful";
+        if (!available.includes(headed)) throw new Error("A headed browser is required but unavailable.");
+        await new Promise((resolve) => setTimeout(resolve, PROTECTED_INTERVAL_MS));
+        const index = err.stepIndex;
+        const remaining = pipeline.steps.slice(index);
+        const insertedNavigation = remaining[0]?.type !== "navigate";
+        if (insertedNavigation) remaining.unshift({ type: "navigate", url: err.url });
+        const resumed = await this.executeWithMode(userId, token, { ...pipeline, steps: remaining }, headed, instanceId, true);
+        const offset = index - Number(insertedNavigation);
+        resumed.results = [...err.results, ...resumed.results.filter((r) => !insertedNavigation || r.stepIndex > 0).map((r) => ({ ...r, stepIndex: r.stepIndex + offset }))];
+        resumed.completedSteps = index + Math.max(0, resumed.completedSteps - Number(insertedNavigation));
+        resumed.totalSteps = pipeline.steps.length;
+        resumed.obstacles = [...err.obstacles, ...resumed.obstacles];
+        if (resumed.error) {
+          resumed.error.failedAtStep = Math.max(index, resumed.error.failedAtStep + offset);
+          resumed.error.failedStep = pipeline.steps[resumed.error.failedAtStep];
+        }
+        resumed.durationMs = Date.now() - startTime;
+        resumed.modeEscalated = true;
+        resumed.modeUsed = headed;
+        return resumed;
+      }
       if (result.ok) {
         const blockResult = await detectBlock(page);
         if (blockResult.blocked) {
@@ -6180,12 +6797,30 @@ var FetchService = class {
       const { browser, name: browserName } = await getBrowserWithFallback(preferredBrowser);
       context = await browser.newContext(stealthContextOptions({ locale, extraHTTPHeaders: { ...headers } }, userId ?? void 0));
       if (sessionData) await injectCookies(context, sessionData);
-      const page = await context.newPage();
+      let page = await context.newPage();
       await applyStealthToPage(page);
       await page.goto(url, { waitUntil: waitUntil || "domcontentloaded", timeout: TIMEOUTS.NAVIGATION });
+      let protection = false;
+      const pivotIfDetected = async () => {
+        if (protection || !await detectSiteProtection(page)) return;
+        protection = true;
+        const targetUrl = page.url();
+        const cookies = await context.cookies();
+        await context.close();
+        context = await (await getHeadedBrowser()).newContext(stealthContextOptions({ locale, extraHTTPHeaders: { ...headers } }, userId ?? void 0));
+        await context.addCookies(cookies);
+        page = await context.newPage();
+        await applyStealthToPage(page);
+        await new Promise((resolve) => setTimeout(resolve, PROTECTED_INTERVAL_MS));
+        await paceProtectedDomain(new URL(targetUrl).hostname);
+        await page.goto(targetUrl, { waitUntil, timeout: TIMEOUTS.NAVIGATION });
+      };
+      await pivotIfDetected();
       if (sessionData) await injectStorage(page, sessionData);
       if (waitForSelector) await page.waitForSelector(waitForSelector, { timeout: TIMEOUTS.SELECTOR_WAIT });
       for (const action of actions) {
+        await pivotIfDetected();
+        if (protection) await paceProtectedDomain(new URL(page.url()).hostname);
         switch (action.type) {
           case "click":
             await page.click(action.selector);
@@ -6216,6 +6851,7 @@ var FetchService = class {
             break;
         }
       }
+      await pivotIfDetected();
       const finalUrl = page.url();
       const html = returnHtml ? await page.content() : void 0;
       const result = extract2 ? await page.evaluate(extract2) : void 0;
@@ -6521,6 +7157,11 @@ var Iframer = class {
   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() {
@@ -6937,6 +7578,10 @@ var reapTimer = setInterval(async () => {
     await reapOrphanBrowsers();
   } catch {
   }
+  try {
+    iframer.sweepBlankBrowsers();
+  } catch {
+  }
   const idleMs = Date.now() - lastActivity;
   if (idleMs > IDLE_EXIT_MS && !iframer.browserHealth().alive && !extensionBridge.hasClients()) {
     gracefulShutdown(`idle for ${Math.round(idleMs / 6e4)}min with no browsers`);