frogoe 0.5.5 → 0.6.0

package/dist/cli.js

@@ -1586,34 +1586,623 @@ var init_art_verify = __esm({
   }
 });
 
-// src/browser.ts
+// src/net/tunnel.ts
+import { spawn, spawnSync } from "child_process";
+import { existsSync as existsSync6, mkdirSync as mkdirSync3, chmodSync, writeFileSync as writeFileSync3 } from "fs";
+import os from "os";
 import path7 from "path";
-var browserPath, ensureBrowser;
-var init_browser = __esm({
-  "src/browser.ts"() {
+import { gunzipSync } from "zlib";
+var URL_PATTERN, parseTunnelUrl, TAG_PATTERN, assertSafeTag, octalAt, extractSingleFile, ENV_PIN, assetName, binaryFileName, cacheBase, resolveLatestTag, mb, downloadWithProgress, binaryEchoes, resolveBinary, startTunnel;
+var init_tunnel = __esm({
+  "src/net/tunnel.ts"() {
+    "use strict";
+    URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/iu;
+    parseTunnelUrl = (chunk) => URL_PATTERN.exec(chunk)?.[0];
+    TAG_PATTERN = /^\d{4}\.\d+\.\d+(-[A-Za-z0-9.]+)?$/u;
+    assertSafeTag = (tag) => {
+      if (!TAG_PATTERN.test(tag)) {
+        throw new Error(
+          `cloudflared version "${tag}" is not a valid release tag (expected e.g. 2025.10.1)`
+        );
+      }
+      return tag;
+    };
+    octalAt = (block, offset, length) => {
+      const raw = block.subarray(offset, offset + length).toString("utf-8");
+      const digits = raw.replace(/[\0 ]/gu, "");
+      return digits.length === 0 ? 0 : Number.parseInt(digits, 8);
+    };
+    extractSingleFile = (tar, wanted) => {
+      for (let offset = 0; offset + 512 <= tar.length; ) {
+        const header = tar.subarray(offset, offset + 512);
+        const name = header.subarray(0, 100).toString("utf-8").replace(/\0.*$/u, "");
+        const size = octalAt(header, 124, 12);
+        const type = header.toString("utf-8").charCodeAt(156);
+        const dataStart = offset + 512;
+        const dataEnd = dataStart + size;
+        if (dataEnd > tar.length) return null;
+        if (name === wanted && (type === 48 || type === 0)) {
+          return tar.subarray(dataStart, dataEnd);
+        }
+        offset = dataStart + Math.ceil(size / 512) * 512;
+      }
+      return null;
+    };
+    ENV_PIN = "FROGOE_CLOUDFLARED_VERSION";
+    assetName = (platform, arch) => {
+      const a = arch === "arm64" ? "arm64" : arch === "x64" ? "amd64" : arch === "ia32" ? "386" : null;
+      if (!a) return null;
+      switch (platform) {
+        case "darwin":
+          return a === "386" ? null : `cloudflared-darwin-${a}.tgz`;
+        case "linux":
+          return `cloudflared-linux-${a}`;
+        // bare binaries
+        case "win32":
+          return a === "arm64" ? null : `cloudflared-windows-${a}.exe`;
+        // bare executables
+        default:
+          return null;
+      }
+    };
+    binaryFileName = (platform) => platform === "win32" ? "cloudflared.exe" : "cloudflared";
+    cacheBase = (platform, env, home) => {
+      if (platform === "darwin") return path7.join(home, "Library", "Caches");
+      if (platform === "win32") return env.LOCALAPPDATA ?? path7.join(home, "AppData", "Local");
+      return path7.join(home, ".cache");
+    };
+    resolveLatestTag = async () => {
+      const res = await fetch("https://api.github.com/repos/cloudflare/cloudflared/releases/latest", {
+        headers: { accept: "application/vnd.github+json" }
+      });
+      if (!res.ok) throw new Error(`github api ${res.status}`);
+      const body = await res.json();
+      if (!body.tag_name) throw new Error("github api returned no tag_name");
+      return body.tag_name;
+    };
+    mb = (bytes) => (bytes / (1024 * 1024)).toFixed(0);
+    downloadWithProgress = async (res, onChunk) => {
+      const total = Number(res.headers.get("content-length") ?? 0);
+      const reader = res.body?.getReader();
+      if (!reader) return Buffer.from(await res.arrayBuffer());
+      const chunks = [];
+      let done = 0;
+      let nextReport = 0;
+      for (; ; ) {
+        const step = await reader.read();
+        if (step.done) break;
+        chunks.push(Buffer.from(step.value));
+        done += step.value.byteLength;
+        if (done >= nextReport) {
+          onChunk(done, total);
+          nextReport = done + 5 * 1024 * 1024;
+        }
+      }
+      return Buffer.concat(chunks);
+    };
+    binaryEchoes = (bin, tag) => {
+      try {
+        const probe = spawnSync(bin, ["--version"], { encoding: "utf-8", timeout: 1e4 });
+        const out = `${probe.stdout ?? ""}${probe.stderr ?? ""}`;
+        return probe.status === 0 && out.includes(tag);
+      } catch {
+        return false;
+      }
+    };
+    resolveBinary = async (onProgress) => {
+      const pathProbe = spawnSync("cloudflared", ["--version"], { stdio: "ignore", timeout: 5e3 });
+      if (pathProbe.status === 0) return { downloaded: false, path: "cloudflared" };
+      const platform = process.platform;
+      const asset = assetName(platform, process.arch);
+      if (!asset) {
+        throw new Error(
+          `cloudflared publishes no build for ${platform}/${process.arch} \u2014 install it and put \`cloudflared\` on PATH`
+        );
+      }
+      const tag = process.env[ENV_PIN] ? assertSafeTag(process.env[ENV_PIN]) : assertSafeTag(await resolveLatestTag());
+      const root = path7.join(cacheBase(platform, process.env, os.homedir()), "frogoe", "cloudflared");
+      const dir = path7.join(root, tag);
+      const bin = path7.join(dir, binaryFileName(platform));
+      const rootResolved = path7.resolve(root);
+      const binResolved = path7.resolve(bin);
+      if (!binResolved.startsWith(rootResolved + path7.sep)) {
+        throw new Error("cloudflared binary path escaped the frogoe cache \u2014 refusing to execute");
+      }
+      if (existsSync6(bin) && binaryEchoes(bin, tag)) return { downloaded: false, path: bin };
+      onProgress?.(`downloading cloudflared ${tag} (~25 MB, once)\u2026`);
+      const res = await fetch(
+        `https://github.com/cloudflare/cloudflared/releases/download/${tag}/${asset}`
+      );
+      if (!res.ok) throw new Error(`cloudflared ${tag} download failed (${res.status})`);
+      const raw = await downloadWithProgress(res, (done, total) => {
+        onProgress?.(`downloading cloudflared ${tag} \u2014 ${mb(done)}${total ? `/${mb(total)}` : ""} MB`);
+      });
+      const binary = asset.endsWith(".tgz") ? extractSingleFile(gunzipSync(raw), "cloudflared") : raw;
+      if (!binary) throw new Error("cloudflared archive did not contain the binary");
+      mkdirSync3(dir, { recursive: true });
+      writeFileSync3(bin, binary);
+      if (platform !== "win32") chmodSync(bin, 493);
+      if (!binaryEchoes(bin, tag)) {
+        throw new Error(
+          `cloudflared ${tag} failed its version check \u2014 deleted; set ${ENV_PIN} or install via brew`
+        );
+      }
+      return { downloaded: true, path: bin };
+    };
+    startTunnel = async (port, options) => {
+      const timeoutMs = options?.timeoutMs ?? 2e4;
+      const bin = await resolveBinary(options?.onProgress);
+      return new Promise((resolve2, reject) => {
+        const child = spawn(
+          bin.path,
+          ["tunnel", "--url", `http://localhost:${port}`, "--no-autoupdate"],
+          {
+            detached: true,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true
+          }
+        );
+        let settled = false;
+        let url;
+        let buffer = "";
+        const exited = new Promise((notify) => {
+          child.once("exit", () => notify());
+        });
+        const killTree = () => {
+          if (process.platform === "win32" || !child.pid) {
+            child.kill("SIGTERM");
+            return;
+          }
+          try {
+            process.kill(-child.pid, "SIGTERM");
+          } catch {
+            child.kill("SIGTERM");
+          }
+        };
+        const finish = (error) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          if (error || !url) {
+            killTree();
+            const tail = buffer.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean).slice(-2).join(" | ");
+            const base = error?.message ?? "frogoe tunnel: cloudflared exited before producing a URL";
+            reject(new Error(tail ? `${base} \u2014 ${tail}` : base));
+            return;
+          }
+          resolve2({ exited, stop: killTree, url });
+        };
+        const timer = setTimeout(() => {
+          finish(
+            new Error(
+              `frogoe tunnel: no URL from cloudflared within ${timeoutMs / 1e3}s \u2014 check your internet, or brew install cloudflared`
+            )
+          );
+        }, timeoutMs);
+        child.once("exit", (code) => {
+          if (!settled) {
+            finish(new Error(`frogoe tunnel: cloudflared exited early (code ${code ?? "signal"})`));
+          }
+        });
+        const watch2 = (stream) => {
+          stream.on("data", (data) => {
+            if (settled && url) return;
+            buffer += data.toString("utf-8");
+            const found = parseTunnelUrl(buffer);
+            if (found && !url) {
+              url = found;
+              finish();
+            }
+          });
+        };
+        if (child.stderr && child.stdout) {
+          watch2(child.stderr);
+          watch2(child.stdout);
+        }
+      });
+    };
+  }
+});
+
+// src/browser/lock.ts
+import { existsSync as existsSync7, mkdirSync as mkdirSync4, rmSync, statSync, utimesSync } from "fs";
+import path8 from "path";
+var DEFAULT_LOCK_TIMINGS, LOCK_DIR_NAME, RECLAIM_DIR_NAME, isErrno, sleep2, tryAcquireDirLock, isDirLockStale, touch, reclaimStaleLock, withInstallLock;
+var init_lock = __esm({
+  "src/browser/lock.ts"() {
+    "use strict";
+    DEFAULT_LOCK_TIMINGS = {
+      heartbeatMs: 15e3,
+      pollMs: 200,
+      staleMs: 12e4,
+      waitNoticeMs: 1e4
+    };
+    LOCK_DIR_NAME = ".chrome.install.lock";
+    RECLAIM_DIR_NAME = ".chrome.install.reclaim.lock";
+    isErrno = (error, code) => {
+      if (typeof error === "object" && error !== null && "code" in error) {
+        return error.code === code;
+      }
+      return false;
+    };
+    sleep2 = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+    tryAcquireDirLock = (lockDir) => {
+      try {
+        mkdirSync4(lockDir, { recursive: false });
+        return true;
+      } catch (error) {
+        if (!isErrno(error, "EEXIST")) throw error;
+        return false;
+      }
+    };
+    isDirLockStale = (lockDir, staleMs) => {
+      try {
+        return Date.now() - statSync(lockDir).mtimeMs > staleMs;
+      } catch (error) {
+        if (isErrno(error, "ENOENT")) return false;
+        throw error;
+      }
+    };
+    touch = (lockDir) => {
+      try {
+        const now = /* @__PURE__ */ new Date();
+        utimesSync(lockDir, now, now);
+      } catch {
+      }
+    };
+    reclaimStaleLock = (lockDir, reclaimDir, staleMs) => {
+      if (!tryAcquireDirLock(reclaimDir)) return;
+      try {
+        if (isDirLockStale(lockDir, staleMs)) {
+          rmSync(lockDir, { recursive: true, force: true });
+        }
+      } finally {
+        rmSync(reclaimDir, { recursive: true, force: true });
+      }
+    };
+    withInstallLock = async (fn, rootDir, options) => {
+      const timings = options?.timings ?? DEFAULT_LOCK_TIMINGS;
+      const log = options?.log ?? ((line) => console.error(line));
+      const lockDir = path8.join(rootDir, LOCK_DIR_NAME);
+      const reclaimDir = path8.join(rootDir, RECLAIM_DIR_NAME);
+      if (!existsSync7(rootDir)) mkdirSync4(rootDir, { recursive: true });
+      let deadline = Date.now() + timings.staleMs;
+      const waitStart = Date.now();
+      let lastNoticeMs = 0;
+      for (; ; ) {
+        if (existsSync7(reclaimDir)) {
+          if (isDirLockStale(reclaimDir, timings.staleMs)) {
+            rmSync(reclaimDir, { recursive: true, force: true });
+          }
+          await sleep2(timings.pollMs);
+          continue;
+        }
+        if (tryAcquireDirLock(lockDir)) {
+          rmSync(reclaimDir, { recursive: true, force: true });
+          break;
+        }
+        const waitedMs = Date.now() - waitStart;
+        if (waitedMs - lastNoticeMs >= timings.waitNoticeMs) {
+          lastNoticeMs = waitedMs;
+          log(
+            `  browser: waiting for another frogoe process to finish installing chrome-headless-shell (${Math.round(waitedMs / 1e3)}s elapsed)\u2026`
+          );
+        }
+        if (isDirLockStale(lockDir, timings.staleMs) || Date.now() > deadline) {
+          reclaimStaleLock(lockDir, reclaimDir, timings.staleMs);
+          deadline = Date.now() + timings.staleMs;
+          continue;
+        }
+        await sleep2(timings.pollMs);
+      }
+      const heartbeat = setInterval(() => touch(lockDir), timings.heartbeatMs);
+      if (typeof heartbeat.unref === "function") heartbeat.unref();
+      try {
+        return await fn();
+      } finally {
+        clearInterval(heartbeat);
+        rmSync(lockDir, { recursive: true, force: true });
+      }
+    };
+  }
+});
+
+// src/browser/manager.ts
+import { cpSync as cpSync2, existsSync as existsSync8, mkdirSync as mkdirSync5, readdirSync as readdirSync2, renameSync, rmSync as rmSync2 } from "fs";
+import { homedir } from "os";
+import path9 from "path";
+var CHROME_BUILD, BROWSER_PATH_ENV, CACHE_ROOT, CACHE_DIR, ARCHIVE_CHECKSUMS, messageOf, positiveIntEnv, isCorruptInstallError, browserPathHintForPlatform, wrapDownloadFailure, isTimeoutError, wrapLaunchFailure, findInCache, legacyCacheDir, migrateLegacyCache, pruneLegacyCache, progressReporter, downloadBrowser, resolved, ensureBrowser;
+var init_manager = __esm({
+  "src/browser/manager.ts"() {
+    "use strict";
+    init_tunnel();
+    init_lock();
+    CHROME_BUILD = "131.0.6778.204";
+    BROWSER_PATH_ENV = "FROGOE_BROWSER_PATH";
+    CACHE_ROOT = path9.join(cacheBase(process.platform, process.env, homedir()), "frogoe");
+    CACHE_DIR = path9.join(CACHE_ROOT, "chrome");
+    ARCHIVE_CHECKSUMS = {
+      linux: "afaac86e302c4874245991a3d509d529c50ecdd447affff0cdc2b08520906c32",
+      mac: "933463c27a951d3fc153c408c4b8a96c89b9344379963f68a5ff9aa1718bcaf9",
+      mac_arm: "9dae11ffda8d77f92c56f64de84f81fa6781c9d41235a8e9397117d7d004a017",
+      win32: "e1a14441accf82785fd81b78d34d8faf5cc78bbab6b2f90fa7e7e972d93ed77f",
+      win64: "d45834686f461ef6f487c0eacc2063bc311a5de86e92de46600895bf44136714"
+    };
+    messageOf = (error) => {
+      if (error instanceof Error) return error.message;
+      if (typeof error === "string") return error;
+      return "";
+    };
+    positiveIntEnv = (name, raw, fallback) => {
+      if (raw === void 0 || raw.trim() === "") return fallback;
+      const trimmed = raw.trim();
+      if (!/^\d+$/u.test(trimmed) || Number.parseInt(trimmed, 10) <= 0) {
+        throw new Error(
+          `frogoe browser: ${name} must be a positive integer of milliseconds (got "${raw}") \u2014 unset it or fix the value, then re-run`
+        );
+      }
+      return Number.parseInt(trimmed, 10);
+    };
+    isCorruptInstallError = (error) => {
+      const message2 = messageOf(error).toLowerCase();
+      return message2.includes("end of central directory") || message2.includes("end-of-central-directory") || message2.includes("invalid or corrupt") || message2.includes("corrupt zip") || message2.includes("corrupted") || message2.includes("not a zip") || message2.includes("unexpected end of") || message2.includes("integrity check failed") || message2.includes("exists but the executable");
+    };
+    browserPathHintForPlatform = (platform) => {
+      if (platform === "darwin") return "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+      if (platform === "win32") return "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe";
+      return "/usr/bin/google-chrome";
+    };
+    wrapDownloadFailure = (cause) => {
+      const original = messageOf(cause) || String(cause);
+      return new Error(
+        `frogoe browser: failed to download chrome-headless-shell ${CHROME_BUILD} \u2014 ${original}
+
+Point frogoe at an already-installed Chrome/Chromium instead:
+
+  export ${BROWSER_PATH_ENV}="${browserPathHintForPlatform(process.platform)}"
+
+Then re-run your command. Any Chrome build works for the sandbox; the pinned
+headless-shell re-downloads into ${CACHE_DIR} once the network allows.`,
+        { cause: cause instanceof Error ? cause : void 0 }
+      );
+    };
+    isTimeoutError = (error) => {
+      if (!(error instanceof Error)) return false;
+      return error.name === "TimeoutError" || /timed out \d+ ms/u.test(error.message);
+    };
+    wrapLaunchFailure = (cause, timeoutMs) => {
+      const head = isTimeoutError(cause) ? `frogoe browser: headless chrome did not start within ${String(timeoutMs)} ms.
+
+Raise the budget or point frogoe at an installed Chrome:
+
+  FROGOE_LAUNCH_TIMEOUT_MS=${String(timeoutMs * 2)} <your command>
+  export ${BROWSER_PATH_ENV}="${browserPathHintForPlatform(process.platform)}"
+` : `frogoe browser: headless chrome failed to launch \u2014 ${messageOf(cause) || String(cause)}
+
+If a local Chrome exists, point frogoe at it:
+
+  export ${BROWSER_PATH_ENV}="${browserPathHintForPlatform(process.platform)}"
+`;
+      return new Error(
+        `${head}
+Then re-run your command. (The pinned binary lives in ${CACHE_DIR} \u2014
+see skills/frogoe-cli \u2192 references/live-sandbox.md)`,
+        { cause: cause instanceof Error ? cause : void 0 }
+      );
+    };
+    findInCache = async (cacheDir, buildId) => {
+      if (!existsSync8(cacheDir)) return {};
+      const { Browser, detectBrowserPlatform, getInstalledBrowsers } = await import("@puppeteer/browsers");
+      const platform = detectBrowserPlatform();
+      const match = (await getInstalledBrowsers({ cacheDir })).find(
+        (entry) => entry.browser === Browser.CHROMEHEADLESSSHELL && entry.buildId === buildId && entry.platform === platform
+      );
+      if (!match) return {};
+      if (existsSync8(match.executablePath)) return { executablePath: match.executablePath };
+      return { staleInstallPath: match.path };
+    };
+    legacyCacheDir = (dir) => path9.resolve(dir, "node_modules", ".frogoe-browser");
+    migrateLegacyCache = async (legacyDir, cacheDir, buildId, log) => {
+      if (!existsSync8(legacyDir)) return null;
+      const { Browser, getInstalledBrowsers } = await import("@puppeteer/browsers");
+      const legacy = (await getInstalledBrowsers({ cacheDir: legacyDir })).find(
+        (entry) => entry.browser === Browser.CHROMEHEADLESSSHELL && entry.buildId === buildId && existsSync8(entry.executablePath)
+      );
+      if (!legacy) return null;
+      const browserRootName = path9.basename(path9.dirname(legacy.path));
+      const installName = path9.basename(legacy.path);
+      const destination = path9.join(cacheDir, browserRootName, installName);
+      mkdirSync5(path9.dirname(destination), { recursive: true });
+      rmSync2(destination, { recursive: true, force: true });
+      try {
+        try {
+          renameSync(legacy.path, destination);
+        } catch (error) {
+          if (!isErrno(error, "EXDEV")) throw error;
+          const staging = `${destination}.migrating-${String(process.pid)}`;
+          rmSync2(staging, { recursive: true, force: true });
+          try {
+            cpSync2(legacy.path, staging, { recursive: true });
+            renameSync(staging, destination);
+          } finally {
+            rmSync2(staging, { recursive: true, force: true });
+          }
+          rmSync2(legacy.path, { recursive: true, force: true });
+        }
+      } catch {
+        return null;
+      }
+      const found = await findInCache(cacheDir, buildId);
+      if (!found.executablePath) return null;
+      rmSync2(path9.dirname(legacy.path), { recursive: true, force: true });
+      rmSync2(legacyDir, { recursive: true, force: true });
+      log?.(`  browser: migrated the cached chrome-headless-shell into ${cacheDir} (one-time)`);
+      return found.executablePath;
+    };
+    pruneLegacyCache = (legacyDir, buildId) => {
+      if (!existsSync8(legacyDir)) return false;
+      try {
+        const browserRoot = path9.join(legacyDir, "chrome-headless-shell");
+        if (existsSync8(browserRoot)) {
+          const entries = readdirSync2(browserRoot);
+          if (entries.length > 0 && !entries.some((name) => name.endsWith(`-${buildId}`))) {
+            return false;
+          }
+        } else if (readdirSync2(legacyDir).length > 0) {
+          return false;
+        }
+        rmSync2(legacyDir, { recursive: true, force: true });
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    progressReporter = () => {
+      const tty = process.stderr.isTTY === true;
+      const mb2 = (bytes) => (bytes / (1024 * 1024)).toFixed(1);
+      let lastPaintMs = 0;
+      let nextMilestone = 0.25;
+      return (downloaded, total) => {
+        if (tty) {
+          const finished = total > 0 && downloaded >= total;
+          if (Date.now() - lastPaintMs < 100 && !finished) return;
+          lastPaintMs = Date.now();
+          process.stderr.write(
+            `\r  browser: downloading chrome-headless-shell \u2014 ${mb2(downloaded)}${total > 0 ? `/${mb2(total)}` : ""} MB`
+          );
+          if (finished) process.stderr.write("\n");
+          return;
+        }
+        if (total <= 0 || downloaded / total < nextMilestone) return;
+        process.stderr.write(
+          `  browser: downloading chrome-headless-shell \u2014 ${Math.round(nextMilestone * 100)}% (${mb2(total)} MB)
+`
+        );
+        nextMilestone += 0.25;
+      };
+    };
+    downloadBrowser = async (log) => {
+      const { Browser, detectBrowserPlatform, install } = await import("@puppeteer/browsers");
+      const platform = detectBrowserPlatform();
+      if (!platform) {
+        throw wrapDownloadFailure(
+          new Error(`no chrome-headless-shell build exists for ${process.platform}/${process.arch}`)
+        );
+      }
+      const expectedHash = ARCHIVE_CHECKSUMS[platform];
+      if (expectedHash === void 0) {
+        log(
+          `  browser: no pinned checksum for ${platform} \u2014 downloading WITHOUT integrity verification`
+        );
+      }
+      const runInstall = () => install({
+        browser: Browser.CHROMEHEADLESSSHELL,
+        buildId: CHROME_BUILD,
+        cacheDir: CACHE_DIR,
+        unpack: true,
+        ...expectedHash === void 0 ? {} : { expectedHash },
+        downloadProgressCallback: progressReporter()
+      });
+      try {
+        return (await runInstall()).executablePath;
+      } catch (error) {
+        if (!isCorruptInstallError(error)) throw wrapDownloadFailure(error);
+        log("  browser: cached archive was corrupt \u2014 purging and retrying once\u2026");
+        rmSync2(CACHE_DIR, { recursive: true, force: true });
+        try {
+          return (await runInstall()).executablePath;
+        } catch (retryError) {
+          throw wrapDownloadFailure(retryError);
+        }
+      }
+    };
+    ensureBrowser = async (options) => {
+      if (resolved) return resolved;
+      const log = (line) => console.error(line);
+      const fromEnv = process.env[BROWSER_PATH_ENV]?.trim();
+      if (fromEnv !== void 0 && fromEnv !== "") {
+        if (!existsSync8(fromEnv)) {
+          throw new Error(
+            `frogoe browser: ${BROWSER_PATH_ENV} is set but "${fromEnv}" does not exist \u2014 fix the path or unset the variable, then re-run`
+          );
+        }
+        resolved = fromEnv;
+        return resolved;
+      }
+      const legacyDirs = options?.legacyDirs ?? [legacyCacheDir(process.cwd())];
+      const pre = await findInCache(CACHE_DIR, CHROME_BUILD);
+      if (pre.executablePath) {
+        resolved = pre.executablePath;
+      } else {
+        resolved = await withInstallLock(
+          async () => {
+            const post = await findInCache(CACHE_DIR, CHROME_BUILD);
+            if (post.executablePath) return post.executablePath;
+            if (post.staleInstallPath) {
+              log("  browser: incomplete install in the cache \u2014 purging before reinstalling\u2026");
+              rmSync2(post.staleInstallPath, { recursive: true, force: true });
+            }
+            for (const legacyDir of legacyDirs) {
+              const migrated = await migrateLegacyCache(legacyDir, CACHE_DIR, CHROME_BUILD, log);
+              if (migrated) return migrated;
+            }
+            return downloadBrowser(log);
+          },
+          CACHE_ROOT,
+          { log }
+        );
+      }
+      for (const legacyDir of legacyDirs) {
+        if (pruneLegacyCache(legacyDir, CHROME_BUILD)) {
+          log(`  browser: removed the superseded per-project cache at ${legacyDir}`);
+        }
+      }
+      return resolved;
+    };
+  }
+});
+
+// src/browser/launch.ts
+var LAUNCH_TIMEOUT_ENV, PROTOCOL_TIMEOUT_ENV, DEFAULT_LAUNCH_TIMEOUT_MS, DEFAULT_PROTOCOL_TIMEOUT_MS, launchBudgets, launchBrowser;
+var init_launch = __esm({
+  "src/browser/launch.ts"() {
     "use strict";
-    ensureBrowser = async () => {
-      if (browserPath) {
-        return browserPath;
-      }
-      const { Browser, getInstalledBrowsers, install } = await import("@puppeteer/browsers");
-      const cacheDir = path7.resolve(process.cwd(), "node_modules/.frogoe-browser");
-      const installed = await getInstalledBrowsers({ cacheDir });
-      const existing = installed.find((b) => b.browser === Browser.CHROMEHEADLESSSHELL);
-      browserPath = existing?.executablePath ?? (await install({
-        browser: Browser.CHROMEHEADLESSSHELL,
-        buildId: "131.0.6778.204",
-        cacheDir,
-        unpack: true
-      })).executablePath;
-      return browserPath;
+    init_manager();
+    LAUNCH_TIMEOUT_ENV = "FROGOE_LAUNCH_TIMEOUT_MS";
+    PROTOCOL_TIMEOUT_ENV = "FROGOE_PROTOCOL_TIMEOUT_MS";
+    DEFAULT_LAUNCH_TIMEOUT_MS = 12e4;
+    DEFAULT_PROTOCOL_TIMEOUT_MS = 3e5;
+    launchBudgets = (env = process.env) => ({
+      launchMs: positiveIntEnv(LAUNCH_TIMEOUT_ENV, env[LAUNCH_TIMEOUT_ENV], DEFAULT_LAUNCH_TIMEOUT_MS),
+      protocolMs: positiveIntEnv(
+        PROTOCOL_TIMEOUT_ENV,
+        env[PROTOCOL_TIMEOUT_ENV],
+        DEFAULT_PROTOCOL_TIMEOUT_MS
+      )
+    });
+    launchBrowser = async (options) => {
+      const { default: puppeteer } = await import("puppeteer-core");
+      const budgets = launchBudgets();
+      const executablePath = await ensureBrowser({ legacyDirs: options?.legacyDirs });
+      try {
+        return await puppeteer.launch({
+          args: ["--no-sandbox", "--disable-gpu"],
+          defaultViewport: options?.defaultViewport === void 0 ? null : options.defaultViewport,
+          executablePath,
+          headless: true,
+          protocolTimeout: budgets.protocolMs,
+          timeout: budgets.launchMs
+        });
+      } catch (error) {
+        throw wrapLaunchFailure(error, budgets.launchMs);
+      }
     };
   }
 });
 
 // src/net/ip.ts
 import { execSync } from "child_process";
-import os from "os";
+import os2 from "os";
 var VIRTUAL, isPrivateV4, isLoopback, selfAddresses, pickLanIp, interfaceFromRouteOutput, ROUTE_PROBES, routedInterfaceName, resolveLan;
 var init_ip = __esm({
   "src/net/ip.ts"() {
@@ -1713,7 +2302,7 @@ var init_ip = __esm({
       }
       return null;
     };
-    resolveLan = () => pickLanIp(os.networkInterfaces(), routedInterfaceName());
+    resolveLan = () => pickLanIp(os2.networkInterfaces(), routedInterfaceName());
   }
 });
 
@@ -1832,8 +2421,8 @@ var init_records = __esm({
 });
 
 // src/telemetry/session.ts
-import { appendFileSync, mkdirSync as mkdirSync3, readdirSync as readdirSync2 } from "fs";
-import path8 from "path";
+import { appendFileSync, mkdirSync as mkdirSync6, readdirSync as readdirSync3 } from "fs";
+import path10 from "path";
 var pad, sessionStamp, createSessionStore, latestSessionFile;
 var init_session = __esm({
   "src/telemetry/session.ts"() {
@@ -1844,25 +2433,25 @@ var init_session = __esm({
       return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
     };
     createSessionStore = (gameDir, startedWall) => {
-      const dir = path8.join(gameDir, ".frogoe", "sessions");
+      const dir = path10.join(gameDir, ".frogoe", "sessions");
       let file;
       return {
         file: () => file,
         write: (records) => {
           if (records.length === 0) return;
           if (!file) {
-            mkdirSync3(dir, { recursive: true });
-            file = path8.join(dir, `${sessionStamp(startedWall)}.jsonl`);
+            mkdirSync6(dir, { recursive: true });
+            file = path10.join(dir, `${sessionStamp(startedWall)}.jsonl`);
           }
           appendFileSync(file, records.map((r) => JSON.stringify(r)).join("\n") + "\n", "utf-8");
         }
       };
     };
     latestSessionFile = (gameDir) => {
-      const dir = path8.join(gameDir, ".frogoe", "sessions");
+      const dir = path10.join(gameDir, ".frogoe", "sessions");
       try {
-        const files = readdirSync2(dir).filter((f) => f.endsWith(".jsonl")).sort();
-        return files.length > 0 ? path8.join(dir, files[files.length - 1] ?? "") : null;
+        const files = readdirSync3(dir).filter((f) => f.endsWith(".jsonl")).sort();
+        return files.length > 0 ? path10.join(dir, files[files.length - 1] ?? "") : null;
       } catch {
         return null;
       }
@@ -1875,9 +2464,9 @@ var run_exports = {};
 __export(run_exports, {
   startServer: () => startServer
 });
-import { existsSync as existsSync6, readFileSync as readFileSync7, statSync, watch } from "fs";
-import os2 from "os";
-import path9 from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync7, statSync as statSync2, watch } from "fs";
+import os3 from "os";
+import path11 from "path";
 import { createAdaptorServer } from "@hono/node-server";
 import { getConnInfo } from "@hono/node-server/conninfo";
 import { Hono } from "hono";
@@ -1905,15 +2494,15 @@ var init_run = __esm({
       woff2: "font/woff2"
     };
     startServer = async (dir, requestedPort = 0, telemetry) => {
-      const root = path9.resolve(dir);
-      if (!existsSync6(path9.join(root, "index.html"))) {
+      const root = path11.resolve(dir);
+      if (!existsSync9(path11.join(root, "index.html"))) {
         throw new Error(`frogoe run: no index.html in ${root} \u2014 is this a game folder?`);
       }
       const clients = /* @__PURE__ */ new Set();
       let version = 0;
       let remoteSeen = false;
       let lastRemote = "";
-      const own = selfAddresses(os2.networkInterfaces());
+      const own = selfAddresses(os3.networkInterfaces());
       const session = telemetry ? createSessionStore(root, Date.now()) : void 0;
       const app = new Hono();
       app.use("*", async (c, next) => {
@@ -1964,19 +2553,19 @@ var init_run = __esm({
       });
       app.get("*", (c) => {
         const raw = decodeURIComponent(new URL(c.req.url).pathname);
-        const safe = path9.normalize(raw).replaceAll("\\", "/");
-        let file = path9.join(root, safe === "/" ? "index.html" : safe);
+        const safe = path11.normalize(raw).replaceAll("\\", "/");
+        let file = path11.join(root, safe === "/" ? "index.html" : safe);
         if (!file.startsWith(root)) {
           return c.text("forbidden", 403);
         }
-        if (existsSync6(file) && statSync(file).isDirectory()) {
-          file = path9.join(file, "index.html");
+        if (existsSync9(file) && statSync2(file).isDirectory()) {
+          file = path11.join(file, "index.html");
         }
-        if (!existsSync6(file)) {
+        if (!existsSync9(file)) {
           return c.text(`frogoe run: not found: ${raw}`, 404);
         }
         const body = readFileSync7(file);
-        const ext = path9.extname(file).slice(1).toLowerCase();
+        const ext = path11.extname(file).slice(1).toLowerCase();
         const type = MIME2[ext] ?? "application/octet-stream";
         if (ext === "html" || ext === "htm") {
           const html = body.toString("utf-8");
@@ -2005,7 +2594,7 @@ var init_run = __esm({
       const lan = lanInfo.ip ? `http://${lanInfo.ip}:${port}` : void 0;
       let timer;
       const watcher = watch(root, { recursive: true }, (_event, file) => {
-        const first = file?.split(path9.sep)[0];
+        const first = file?.split(path11.sep)[0];
         if (first === "snapshots" || first === ".frogoe" || first === "dist") {
           return;
         }
@@ -2039,9 +2628,9 @@ var init_run = __esm({
 });
 
 // src/raster.ts
-import { existsSync as existsSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync8, statSync as statSync2 } from "fs";
-import path10 from "path";
-var SCENES, sleep2, rasterScriptFor, rasterizeArt;
+import { existsSync as existsSync10, mkdirSync as mkdirSync7, readFileSync as readFileSync8, statSync as statSync3 } from "fs";
+import path12 from "path";
+var SCENES, sleep3, rasterScriptFor, rasterizeArt;
 var init_raster = __esm({
   "src/raster.ts"() {
     "use strict";
@@ -2049,32 +2638,33 @@ var init_raster = __esm({
     init_runtime_source();
     init_art_verify();
     init_runtime_source();
-    init_browser();
+    init_launch();
+    init_manager();
     SCENES = [
       {
         draw: "drawPoster",
         height: 1920,
-        out: path10.join("dist", "assets", "poster.png"),
+        out: path12.join("dist", "assets", "poster.png"),
         size: "w, h",
-        source: path10.join("assets", "poster.js"),
+        source: path12.join("assets", "poster.js"),
         width: 1080
       },
       {
         draw: "drawIcon",
         height: 1024,
-        out: path10.join("dist", "assets", "icon.png"),
+        out: path12.join("dist", "assets", "icon.png"),
         size: "size",
-        source: path10.join("assets", "icon.js"),
+        source: path12.join("assets", "icon.js"),
         width: 1024
       }
     ];
-    sleep2 = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+    sleep3 = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
     rasterScriptFor = (scene, palette) => {
       const sizeArg = scene.draw === "drawIcon" ? String(scene.width) : `${String(scene.width)}, ${String(scene.height)}`;
       const analyze = scene.draw === "drawIcon" ? "analyzeIconCorners" : "analyzeTitleBand";
       return `(async () => {
   ${runtimeSource()}
-  const mod = await import("./assets/${path10.basename(scene.source)}");
+  const mod = await import("./assets/${path12.basename(scene.source)}");
   const canvas = document.createElement("canvas");
   canvas.id = "__frogoe_raster";
   canvas.width = ${String(scene.width)};
@@ -2101,8 +2691,8 @@ var init_raster = __esm({
 })()`;
     };
     rasterizeArt = async (options) => {
-      const dir = path10.resolve(options.dir);
-      const missing = SCENES.filter((scene) => !existsSync7(path10.join(dir, scene.source)));
+      const dir = path12.resolve(options.dir);
+      const missing = SCENES.filter((scene) => !existsSync10(path12.join(dir, scene.source)));
       if (missing.length > 0) {
         throw new Error(
           `bundle/art-missing \u2014 author the identity scenes first (${missing.map((scene) => scene.source).join(", ")}); run \`frogoe check\` and see frogoe-creative \u2192 references/art.md`
@@ -2110,17 +2700,10 @@ var init_raster = __esm({
       }
       const { startServer: startServer2 } = await Promise.resolve().then(() => (init_run(), run_exports));
       const server = await startServer2(dir);
-      const { default: puppeteer } = await import("puppeteer-core");
-      const executablePath = await ensureBrowser();
-      const browser = await puppeteer.launch({
-        args: ["--no-sandbox", "--disable-gpu"],
-        defaultViewport: null,
-        executablePath,
-        headless: true
-      });
+      const browser = await launchBrowser({ legacyDirs: [legacyCacheDir(dir)] });
       try {
         const base = server.urls.local.replace(/\/$/u, "");
-        const brief = parseBrief(readFileSync8(path10.join(dir, "BRIEF.md"), "utf-8"));
+        const brief = parseBrief(readFileSync8(path12.join(dir, "BRIEF.md"), "utf-8"));
         const palette = {
           accent: brief?.accent ?? "#ff3b3b",
           bg: brief?.bg ?? "#101418",
@@ -2166,7 +2749,7 @@ var init_raster = __esm({
               }
             } else {
               const report = await page.evaluate("window.__frogoeArtReport");
-              const gameSource = readFileSync8(path10.join(dir, "game.js"), "utf-8");
+              const gameSource = readFileSync8(path12.join(dir, "game.js"), "utf-8");
               const verdict = verifyIconFullbleed(report, [...hexColorsOf(gameSource)]);
               if (verdict !== null) throw new Error(verdict);
               if (metrics.coverage < 0.08) {
@@ -2175,13 +2758,13 @@ var init_raster = __esm({
                 );
               }
             }
-            await sleep2(80);
+            await sleep3(80);
             const canvas = await page.$("#__frogoe_raster");
             if (canvas === null) throw new Error(`bundle/art-crash \u2014 ${scene.source}: no canvas`);
-            const outPath = path10.join(dir, scene.out);
-            mkdirSync4(path10.dirname(outPath), { recursive: true });
+            const outPath = path12.join(dir, scene.out);
+            mkdirSync7(path12.dirname(outPath), { recursive: true });
             await canvas.screenshot({ omitBackground: true, path: outPath, type: "png" });
-            files.push({ bytes: statSync2(outPath).size, file: scene.out });
+            files.push({ bytes: statSync3(outPath).size, file: scene.out });
           } finally {
             await page.close();
           }
@@ -2201,8 +2784,8 @@ __export(bundle_exports, {
   command: () => command2
 });
 import { defineCommand as defineCommand2 } from "citty";
-import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync3 } from "fs";
-import path11 from "path";
+import { mkdirSync as mkdirSync8, writeFileSync as writeFileSync4 } from "fs";
+import path13 from "path";
 var command2;
 var init_bundle2 = __esm({
   "src/commands/bundle.ts"() {
@@ -2218,9 +2801,9 @@ var init_bundle2 = __esm({
       async run({ args }) {
         const dir = args.dir ? String(args.dir) : process.cwd();
         const report = await bundle({ dir });
-        const outPath = args.out ? path11.resolve(String(args.out)) : path11.join(dir, "dist", "index.html");
-        mkdirSync5(path11.dirname(outPath), { recursive: true });
-        writeFileSync3(outPath, report.artifact, "utf-8");
+        const outPath = args.out ? path13.resolve(String(args.out)) : path13.join(dir, "dist", "index.html");
+        mkdirSync8(path13.dirname(outPath), { recursive: true });
+        writeFileSync4(outPath, report.artifact, "utf-8");
         const art = await rasterizeArt({ dir });
         for (const warning of [...report.warnings, ...art.warnings]) {
           console.log(`  \u26A0 ${warning}`);
@@ -2835,7 +3418,7 @@ var init_decisions = __esm({
 });
 
 // src/live/phases.ts
-var END_BUDGET_MS, RETRY_NAV_MS, PLAY_STEPS, PLAY_STEP_MS, HOLD_STEP_INDEX, DRAG_STEP_INDEX, DRAG_SPAN, HOLD_MS, POLL_MS, GRACE_MS, STABILITY_CYCLES, START_BURST_TAPS, DESKTOP_FPS_MS, sleep3, jitterX, jitterY, hasError, runBootChecks, runDesktopPass, overShotName, retryShotName, waitForOver, runStartBurst, verifyDeath, runLifecycle;
+var END_BUDGET_MS, RETRY_NAV_MS, PLAY_STEPS, PLAY_STEP_MS, HOLD_STEP_INDEX, DRAG_STEP_INDEX, DRAG_SPAN, HOLD_MS, POLL_MS, GRACE_MS, STABILITY_CYCLES, START_BURST_TAPS, DESKTOP_FPS_MS, sleep4, jitterX, jitterY, hasError, runBootChecks, runDesktopPass, overShotName, retryShotName, waitForOver, runStartBurst, verifyDeath, runLifecycle;
 var init_phases = __esm({
   "src/live/phases.ts"() {
     "use strict";
@@ -2853,7 +3436,7 @@ var init_phases = __esm({
     STABILITY_CYCLES = 2;
     START_BURST_TAPS = 3;
     DESKTOP_FPS_MS = 2e3;
-    sleep3 = (ms) => new Promise((resolve2) => {
+    sleep4 = (ms) => new Promise((resolve2) => {
       setTimeout(resolve2, ms);
     });
     jitterX = (step) => step * 37 % 121 - 60;
@@ -2900,7 +3483,7 @@ var init_phases = __esm({
       return findings;
     };
     runDesktopPass = async (driver, ctx) => {
-      const doSleep = ctx.sleep ?? sleep3;
+      const doSleep = ctx.sleep ?? sleep4;
       const findings = await runBootChecks(driver, ctx);
       if (hasError(findings)) {
         return { findings };
@@ -2931,7 +3514,7 @@ var init_phases = __esm({
       return false;
     };
     runStartBurst = async (driver, ctx) => {
-      const doSleep = ctx.sleep ?? sleep3;
+      const doSleep = ctx.sleep ?? sleep4;
       for (let step = 0; step < START_BURST_TAPS; step++) {
         const x = Math.round(ctx.viewport.width / 2 + jitterX(step));
         const y = Math.round(ctx.viewport.height / 2 + jitterY(step));
@@ -2940,7 +3523,7 @@ var init_phases = __esm({
       }
     };
     verifyDeath = async (driver, ctx, findings, cycle) => {
-      const doSleep = ctx.sleep ?? sleep3;
+      const doSleep = ctx.sleep ?? sleep4;
       let events = await driver.finishEvents();
       if (events.length === 0) {
         await doSleep(GRACE_MS);
@@ -2961,7 +3544,7 @@ var init_phases = __esm({
       return presence.retry;
     };
     runLifecycle = async (driver, ctx) => {
-      const doSleep = ctx.sleep ?? sleep3;
+      const doSleep = ctx.sleep ?? sleep4;
       const settle = ctx.settleMs ?? 2e3;
       const name = ctx.viewport.name;
       const findings = [];
@@ -3134,13 +3717,14 @@ var live_exports = {};
 __export(live_exports, {
   collectLive: () => collectLive
 });
-import { mkdirSync as mkdirSync6, writeFileSync as writeFileSync4 } from "fs";
-import path12 from "path";
+import { mkdirSync as mkdirSync9, writeFileSync as writeFileSync5 } from "fs";
+import path14 from "path";
 var VIEWPORTS, waitForServer, collectLive;
 var init_live = __esm({
   "src/live/index.ts"() {
     "use strict";
-    init_browser();
+    init_launch();
+    init_manager();
     init_driver();
     init_phases();
     VIEWPORTS = [
@@ -3156,11 +3740,11 @@ var init_live = __esm({
           }
         } catch {
         }
-        await sleep3(500);
+        await sleep4(500);
       }
     };
     collectLive = async (options) => {
-      const dir = path12.resolve(options.dir);
+      const dir = path14.resolve(options.dir);
       const settle = options.settleMs ?? 2e3;
       const findings = [];
       const screenshots = [];
@@ -3170,16 +3754,9 @@ var init_live = __esm({
       };
       const { startServer: startServer2 } = await Promise.resolve().then(() => (init_run(), run_exports));
       const server = await startServer2(dir);
-      const snapshotDir = path12.join(dir, "snapshots");
-      mkdirSync6(snapshotDir, { recursive: true });
-      const { default: puppeteer } = await import("puppeteer-core");
-      const executablePath = await ensureBrowser();
-      const browser = await puppeteer.launch({
-        args: ["--no-sandbox", "--disable-gpu"],
-        defaultViewport: null,
-        executablePath,
-        headless: true
-      });
+      const snapshotDir = path14.join(dir, "snapshots");
+      mkdirSync9(snapshotDir, { recursive: true });
+      const browser = await launchBrowser({ legacyDirs: [legacyCacheDir(dir)] });
       try {
         let serverReady = false;
         for (const viewport of VIEWPORTS) {
@@ -3191,15 +3768,15 @@ var init_live = __esm({
               size: { height: viewport2.height, width: viewport2.width }
             });
             const shot = async (name) => {
-              writeFileSync4(path12.join(snapshotDir, name), await driver.screenshot());
-              screenshots.push(path12.join("snapshots", name));
+              writeFileSync5(path14.join(snapshotDir, name), await driver.screenshot());
+              screenshots.push(path14.join("snapshots", name));
             };
             if (!serverReady) {
               await waitForServer(server.urls.local);
               serverReady = true;
             }
             await page.goto(server.urls.local, { timeout: 15e3, waitUntil: "domcontentloaded" });
-            await sleep3(settle);
+            await sleep4(settle);
             if (viewport2.name === "mobile") {
               const outcome = await runLifecycle(driver, {
                 settleMs: settle,
@@ -3628,8 +4205,8 @@ var init_compose = __esm({
 
 // src/manifest.ts
 import { createHash as createHash2 } from "crypto";
-import { existsSync as existsSync8, readFileSync as readFileSync9 } from "fs";
-import path13 from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync9 } from "fs";
+import path15 from "path";
 var DESCRIPTION_CAP, descriptionFrom, buildManifest;
 var init_manifest = __esm({
   "src/manifest.ts"() {
@@ -3648,16 +4225,16 @@ var init_manifest = __esm({
       return null;
     };
     buildManifest = (options) => {
-      const dir = path13.resolve(options.dir);
-      const briefSource = readFileSync9(path13.join(dir, "BRIEF.md"), "utf-8");
+      const dir = path15.resolve(options.dir);
+      const briefSource = readFileSync9(path15.join(dir, "BRIEF.md"), "utf-8");
       const brief = parseBrief(briefSource);
       if (!brief?.title) return null;
-      const pin = existsSync8(path13.join(dir, "frogoe.json")) ? JSON.parse(readFileSync9(path13.join(dir, "frogoe.json"), "utf-8")).contract ?? "0.1.0" : "0.1.0";
-      const artifact = options.artifactHtml ?? readFileSync9(path13.join(dir, "dist", "index.html"), "utf-8");
+      const pin = existsSync11(path15.join(dir, "frogoe.json")) ? JSON.parse(readFileSync9(path15.join(dir, "frogoe.json"), "utf-8")).contract ?? "0.1.0" : "0.1.0";
+      const artifact = options.artifactHtml ?? readFileSync9(path15.join(dir, "dist", "index.html"), "utf-8");
       const sha2562 = createHash2("sha256").update(artifact, "utf-8").digest("hex");
       const mediaSha = (file) => {
-        const full = path13.join(dir, "dist", "assets", file);
-        return existsSync8(full) ? createHash2("sha256").update(readFileSync9(full)).digest("hex") : null;
+        const full = path15.join(dir, "dist", "assets", file);
+        return existsSync11(full) ? createHash2("sha256").update(readFileSync9(full)).digest("hex") : null;
       };
       return {
         artifact: "index.html",
@@ -3666,7 +4243,7 @@ var init_manifest = __esm({
         description: descriptionFrom(briefSource),
         entry: "index.html",
         fonts: brief.fonts ?? null,
-        icon: existsSync8(path13.join(dir, "dist", "assets", "icon.png")) ? "assets/icon.png" : null,
+        icon: existsSync11(path15.join(dir, "dist", "assets", "icon.png")) ? "assets/icon.png" : null,
         iconSha256: mediaSha("icon.png"),
         mood: brief.mood ?? null,
         palette: {
@@ -3675,7 +4252,7 @@ var init_manifest = __esm({
           fg: brief.fg ?? "",
           ...brief.outline ? { outline: brief.outline } : {}
         },
-        poster: existsSync8(path13.join(dir, "dist", "assets", "poster.png")) ? "assets/poster.png" : null,
+        poster: existsSync11(path15.join(dir, "dist", "assets", "poster.png")) ? "assets/poster.png" : null,
         posterSha256: mediaSha("poster.png"),
         title: brief.title,
         verb: brief.verb ?? "tap"
@@ -3689,8 +4266,8 @@ var embed_exports = {};
 __export(embed_exports, {
   command: () => command4
 });
-import { existsSync as existsSync9, mkdirSync as mkdirSync7, readFileSync as readFileSync10, writeFileSync as writeFileSync5 } from "fs";
-import path14 from "path";
+import { existsSync as existsSync12, mkdirSync as mkdirSync10, readFileSync as readFileSync10, writeFileSync as writeFileSync6 } from "fs";
+import path16 from "path";
 import { defineCommand as defineCommand4 } from "citty";
 var dataUri2, command4;
 var init_embed = __esm({
@@ -3700,15 +4277,15 @@ var init_embed = __esm({
     init_card();
     init_compose();
     init_manifest();
-    dataUri2 = (file) => existsSync9(file) ? `data:image/png;base64,${readFileSync10(file).toString("base64")}` : null;
+    dataUri2 = (file) => existsSync12(file) ? `data:image/png;base64,${readFileSync10(file).toString("base64")}` : null;
     command4 = defineCommand4({
       args: {
         dir: { type: "positional", required: false, description: "game folder (default: cwd)" }
       },
       async run({ args }) {
         const dir = args.dir ? String(args.dir) : process.cwd();
-        const artifactPath = path14.join(dir, "dist", "index.html");
-        if (!existsSync9(artifactPath)) {
+        const artifactPath = path16.join(dir, "dist", "index.html");
+        if (!existsSync12(artifactPath)) {
           throw new Error(
             "frogoe embed: no dist/index.html \u2014 run `frogoe bundle` first (and `frogoe check` before it: check \u2192 bundle \u2192 embed)"
           );
@@ -3724,20 +4301,20 @@ var init_embed = __esm({
         if (!manifest) {
           throw new Error("frogoe embed: could not build the manifest from BRIEF.md");
         }
-        const posterDataUri = dataUri2(path14.join(dir, "dist", "assets", "poster.png"));
-        const iconDataUri = dataUri2(path14.join(dir, "dist", "assets", "icon.png"));
+        const posterDataUri = dataUri2(path16.join(dir, "dist", "assets", "poster.png"));
+        const iconDataUri = dataUri2(path16.join(dir, "dist", "assets", "icon.png"));
         const gameHtml = readFileSync10(artifactPath, "utf-8");
         const { payloadB64 } = composePayload(gameHtml);
         const html = composeEmbedHtml({ iconDataUri, manifest, payloadB64, posterDataUri });
-        mkdirSync7(path14.join(dir, "dist"), { recursive: true });
-        writeFileSync5(
-          path14.join(dir, "dist", "manifest.json"),
+        mkdirSync10(path16.join(dir, "dist"), { recursive: true });
+        writeFileSync6(
+          path16.join(dir, "dist", "manifest.json"),
           `${JSON.stringify(manifest, null, 2)}
 `,
           "utf-8"
         );
-        const outPath = path14.join(dir, "dist", "embed.html");
-        writeFileSync5(outPath, html, "utf-8");
+        const outPath = path16.join(dir, "dist", "embed.html");
+        writeFileSync6(outPath, html, "utf-8");
         console.log(`  frogoe embed \u2192 ${outPath}`);
         console.log(
           `  ${html.length.toLocaleString("en-US")} bytes \xB7 sandbox allow-scripts \xB7 sha256 ${manifest.artifactSha256.slice(0, 12)}`
@@ -3864,17 +4441,18 @@ var vision_exports = {};
 __export(vision_exports, {
   command: () => command5
 });
-import { existsSync as existsSync10, readFileSync as readFileSync11 } from "fs";
-import path15 from "path";
+import { existsSync as existsSync13, readFileSync as readFileSync11 } from "fs";
+import path17 from "path";
 import { defineCommand as defineCommand5 } from "citty";
 var HELPERS, PAGE_SCRIPT, show, metricLine, command5;
 var init_vision = __esm({
   "src/commands/vision.ts"() {
     "use strict";
     init_src();
+    init_launch();
+    init_manager();
     init_art_eyes();
     init_art_verify();
-    init_browser();
     HELPERS = [
       luminance,
       contrastRatio2,
@@ -3984,9 +4562,9 @@ var init_vision = __esm({
         objects: { type: "boolean", description: "SPRITES objects only" }
       },
       async run({ args }) {
-        const dir = path15.resolve(args.dir ? String(args.dir) : process.cwd());
-        const briefPath = path15.join(dir, "BRIEF.md");
-        if (!existsSync10(briefPath)) {
+        const dir = path17.resolve(args.dir ? String(args.dir) : process.cwd());
+        const briefPath = path17.join(dir, "BRIEF.md");
+        if (!existsSync13(briefPath)) {
           throw new Error(
             "frogoe vision: no BRIEF.md in this folder \u2014 run this from a game (frogoe init)"
           );
@@ -4011,12 +4589,9 @@ var init_vision = __esm({
         const compact = !wantAll;
         const { startServer: startServer2 } = await Promise.resolve().then(() => (init_run(), run_exports));
         const server = await startServer2(dir);
-        const { default: puppeteer } = await import("puppeteer-core");
-        const browser = await puppeteer.launch({
-          args: ["--no-sandbox", "--disable-gpu"],
+        const browser = await launchBrowser({
           defaultViewport: { height: 844, width: 390 },
-          executablePath: await ensureBrowser(),
-          headless: true
+          legacyDirs: [legacyCacheDir(dir)]
         });
         let report;
         try {
@@ -4101,7 +4676,7 @@ var init_vision = __esm({
             console.log(show(icon, pretty));
           }
         }
-        if (!targeted && !existsSync10(path15.join(dir, "assets", "poster.js"))) {
+        if (!targeted && !existsSync13(path17.join(dir, "assets", "poster.js"))) {
           console.log("\n(note: run `frogoe check` first \u2014 vision only looks, it never gates)");
         }
       },
@@ -4240,8 +4815,8 @@ var init_firewall = __esm({
         return null;
       }
     };
-    binaryBlocked = (path17) => {
-      const out = run(`--getappblocked "${path17}"`);
+    binaryBlocked = (path18) => {
+      const out = run(`--getappblocked "${path18}"`);
       if (out === null) return null;
       if (/blocked/iu.test(out)) return true;
       if (/allowed/iu.test(out)) return false;
@@ -4297,224 +4872,6 @@ var init_plan = __esm({
   }
 });
 
-// src/net/tunnel.ts
-import { spawn, spawnSync } from "child_process";
-import { existsSync as existsSync11, mkdirSync as mkdirSync8, chmodSync, writeFileSync as writeFileSync6 } from "fs";
-import os3 from "os";
-import path16 from "path";
-import { gunzipSync } from "zlib";
-var URL_PATTERN, parseTunnelUrl, TAG_PATTERN, assertSafeTag, octalAt, extractSingleFile, ENV_PIN, assetName, binaryFileName, cacheBase, resolveLatestTag, mb, downloadWithProgress, binaryEchoes, resolveBinary, startTunnel;
-var init_tunnel = __esm({
-  "src/net/tunnel.ts"() {
-    "use strict";
-    URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/iu;
-    parseTunnelUrl = (chunk) => URL_PATTERN.exec(chunk)?.[0];
-    TAG_PATTERN = /^\d{4}\.\d+\.\d+(-[A-Za-z0-9.]+)?$/u;
-    assertSafeTag = (tag) => {
-      if (!TAG_PATTERN.test(tag)) {
-        throw new Error(
-          `cloudflared version "${tag}" is not a valid release tag (expected e.g. 2025.10.1)`
-        );
-      }
-      return tag;
-    };
-    octalAt = (block, offset, length) => {
-      const raw = block.subarray(offset, offset + length).toString("utf-8");
-      const digits = raw.replace(/[\0 ]/gu, "");
-      return digits.length === 0 ? 0 : Number.parseInt(digits, 8);
-    };
-    extractSingleFile = (tar, wanted) => {
-      for (let offset = 0; offset + 512 <= tar.length; ) {
-        const header = tar.subarray(offset, offset + 512);
-        const name = header.subarray(0, 100).toString("utf-8").replace(/\0.*$/u, "");
-        const size = octalAt(header, 124, 12);
-        const type = header.toString("utf-8").charCodeAt(156);
-        const dataStart = offset + 512;
-        const dataEnd = dataStart + size;
-        if (dataEnd > tar.length) return null;
-        if (name === wanted && (type === 48 || type === 0)) {
-          return tar.subarray(dataStart, dataEnd);
-        }
-        offset = dataStart + Math.ceil(size / 512) * 512;
-      }
-      return null;
-    };
-    ENV_PIN = "FROGOE_CLOUDFLARED_VERSION";
-    assetName = (platform, arch) => {
-      const a = arch === "arm64" ? "arm64" : arch === "x64" ? "amd64" : arch === "ia32" ? "386" : null;
-      if (!a) return null;
-      switch (platform) {
-        case "darwin":
-          return a === "386" ? null : `cloudflared-darwin-${a}.tgz`;
-        case "linux":
-          return `cloudflared-linux-${a}`;
-        // bare binaries
-        case "win32":
-          return a === "arm64" ? null : `cloudflared-windows-${a}.exe`;
-        // bare executables
-        default:
-          return null;
-      }
-    };
-    binaryFileName = (platform) => platform === "win32" ? "cloudflared.exe" : "cloudflared";
-    cacheBase = (platform, env, home) => {
-      if (platform === "darwin") return path16.join(home, "Library", "Caches");
-      if (platform === "win32") return env.LOCALAPPDATA ?? path16.join(home, "AppData", "Local");
-      return path16.join(home, ".cache");
-    };
-    resolveLatestTag = async () => {
-      const res = await fetch("https://api.github.com/repos/cloudflare/cloudflared/releases/latest", {
-        headers: { accept: "application/vnd.github+json" }
-      });
-      if (!res.ok) throw new Error(`github api ${res.status}`);
-      const body = await res.json();
-      if (!body.tag_name) throw new Error("github api returned no tag_name");
-      return body.tag_name;
-    };
-    mb = (bytes) => (bytes / (1024 * 1024)).toFixed(0);
-    downloadWithProgress = async (res, onChunk) => {
-      const total = Number(res.headers.get("content-length") ?? 0);
-      const reader = res.body?.getReader();
-      if (!reader) return Buffer.from(await res.arrayBuffer());
-      const chunks = [];
-      let done = 0;
-      let nextReport = 0;
-      for (; ; ) {
-        const step = await reader.read();
-        if (step.done) break;
-        chunks.push(Buffer.from(step.value));
-        done += step.value.byteLength;
-        if (done >= nextReport) {
-          onChunk(done, total);
-          nextReport = done + 5 * 1024 * 1024;
-        }
-      }
-      return Buffer.concat(chunks);
-    };
-    binaryEchoes = (bin, tag) => {
-      try {
-        const probe = spawnSync(bin, ["--version"], { encoding: "utf-8", timeout: 1e4 });
-        const out = `${probe.stdout ?? ""}${probe.stderr ?? ""}`;
-        return probe.status === 0 && out.includes(tag);
-      } catch {
-        return false;
-      }
-    };
-    resolveBinary = async (onProgress) => {
-      const pathProbe = spawnSync("cloudflared", ["--version"], { stdio: "ignore", timeout: 5e3 });
-      if (pathProbe.status === 0) return { downloaded: false, path: "cloudflared" };
-      const platform = process.platform;
-      const asset = assetName(platform, process.arch);
-      if (!asset) {
-        throw new Error(
-          `cloudflared publishes no build for ${platform}/${process.arch} \u2014 install it and put \`cloudflared\` on PATH`
-        );
-      }
-      const tag = process.env[ENV_PIN] ? assertSafeTag(process.env[ENV_PIN]) : assertSafeTag(await resolveLatestTag());
-      const root = path16.join(cacheBase(platform, process.env, os3.homedir()), "frogoe", "cloudflared");
-      const dir = path16.join(root, tag);
-      const bin = path16.join(dir, binaryFileName(platform));
-      const rootResolved = path16.resolve(root);
-      const binResolved = path16.resolve(bin);
-      if (!binResolved.startsWith(rootResolved + path16.sep)) {
-        throw new Error("cloudflared binary path escaped the frogoe cache \u2014 refusing to execute");
-      }
-      if (existsSync11(bin) && binaryEchoes(bin, tag)) return { downloaded: false, path: bin };
-      onProgress?.(`downloading cloudflared ${tag} (~25 MB, once)\u2026`);
-      const res = await fetch(
-        `https://github.com/cloudflare/cloudflared/releases/download/${tag}/${asset}`
-      );
-      if (!res.ok) throw new Error(`cloudflared ${tag} download failed (${res.status})`);
-      const raw = await downloadWithProgress(res, (done, total) => {
-        onProgress?.(`downloading cloudflared ${tag} \u2014 ${mb(done)}${total ? `/${mb(total)}` : ""} MB`);
-      });
-      const binary = asset.endsWith(".tgz") ? extractSingleFile(gunzipSync(raw), "cloudflared") : raw;
-      if (!binary) throw new Error("cloudflared archive did not contain the binary");
-      mkdirSync8(dir, { recursive: true });
-      writeFileSync6(bin, binary);
-      if (platform !== "win32") chmodSync(bin, 493);
-      if (!binaryEchoes(bin, tag)) {
-        throw new Error(
-          `cloudflared ${tag} failed its version check \u2014 deleted; set ${ENV_PIN} or install via brew`
-        );
-      }
-      return { downloaded: true, path: bin };
-    };
-    startTunnel = async (port, options) => {
-      const timeoutMs = options?.timeoutMs ?? 2e4;
-      const bin = await resolveBinary(options?.onProgress);
-      return new Promise((resolve2, reject) => {
-        const child = spawn(
-          bin.path,
-          ["tunnel", "--url", `http://localhost:${port}`, "--no-autoupdate"],
-          {
-            detached: true,
-            stdio: ["ignore", "pipe", "pipe"],
-            windowsHide: true
-          }
-        );
-        let settled = false;
-        let url;
-        let buffer = "";
-        const exited = new Promise((notify) => {
-          child.once("exit", () => notify());
-        });
-        const killTree = () => {
-          if (process.platform === "win32" || !child.pid) {
-            child.kill("SIGTERM");
-            return;
-          }
-          try {
-            process.kill(-child.pid, "SIGTERM");
-          } catch {
-            child.kill("SIGTERM");
-          }
-        };
-        const finish = (error) => {
-          if (settled) return;
-          settled = true;
-          clearTimeout(timer);
-          if (error || !url) {
-            killTree();
-            const tail = buffer.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean).slice(-2).join(" | ");
-            const base = error?.message ?? "frogoe tunnel: cloudflared exited before producing a URL";
-            reject(new Error(tail ? `${base} \u2014 ${tail}` : base));
-            return;
-          }
-          resolve2({ exited, stop: killTree, url });
-        };
-        const timer = setTimeout(() => {
-          finish(
-            new Error(
-              `frogoe tunnel: no URL from cloudflared within ${timeoutMs / 1e3}s \u2014 check your internet, or brew install cloudflared`
-            )
-          );
-        }, timeoutMs);
-        child.once("exit", (code) => {
-          if (!settled) {
-            finish(new Error(`frogoe tunnel: cloudflared exited early (code ${code ?? "signal"})`));
-          }
-        });
-        const watch2 = (stream) => {
-          stream.on("data", (data) => {
-            if (settled && url) return;
-            buffer += data.toString("utf-8");
-            const found = parseTunnelUrl(buffer);
-            if (found && !url) {
-              url = found;
-              finish();
-            }
-          });
-        };
-        if (child.stderr && child.stdout) {
-          watch2(child.stderr);
-          watch2(child.stdout);
-        }
-      });
-    };
-  }
-});
-
 // src/commands/run.ts
 var run_exports2 = {};
 __export(run_exports2, {
@@ -4644,8 +5001,8 @@ var init_run2 = __esm({
 // src/utils/skillsManifest.ts
 import { execFile } from "child_process";
 import { createHash as createHash3 } from "crypto";
-import { existsSync as existsSync12, readdirSync as readdirSync3, readFileSync as readFileSync13, statSync as statSync3 } from "fs";
-import { homedir } from "os";
+import { existsSync as existsSync14, readdirSync as readdirSync4, readFileSync as readFileSync13, statSync as statSync4 } from "fs";
+import { homedir as homedir2 } from "os";
 import { isAbsolute, join, relative, resolve, sep } from "path";
 import { promisify } from "util";
 function isCoreSkill(name) {
@@ -4654,10 +5011,10 @@ function isCoreSkill(name) {
 function listFilesSorted(dir) {
   const out = [];
   const walk = (d) => {
-    for (const name of readdirSync3(d)) {
+    for (const name of readdirSync4(d)) {
       if (name === ".DS_Store") continue;
       const p = join(d, name);
-      if (statSync3(p).isDirectory()) walk(p);
+      if (statSync4(p).isDirectory()) walk(p);
       else out.push(p);
     }
   };
@@ -4680,7 +5037,7 @@ function hashSkillBundle(skillDir) {
   return { hash: h.digest("hex").slice(0, 16), files: files.length };
 }
 function buildManifest2(skillsRoot, meta) {
-  const names = readdirSync3(skillsRoot).filter((n) => existsSync12(join(skillsRoot, n, "SKILL.md"))).sort();
+  const names = readdirSync4(skillsRoot).filter((n) => existsSync14(join(skillsRoot, n, "SKILL.md"))).sort();
   const skills = {};
   for (const name of names) skills[name] = hashSkillBundle(join(skillsRoot, name));
   return { source: meta.source, skills };
@@ -4696,7 +5053,7 @@ function agentFromDir(dir) {
 }
 function listSubdirs(dir) {
   try {
-    return readdirSync3(dir, { withFileTypes: true }).filter((e) => e.isDirectory() || e.isSymbolicLink()).map((e) => e.name);
+    return readdirSync4(dir, { withFileTypes: true }).filter((e) => e.isDirectory() || e.isSymbolicLink()).map((e) => e.name);
   } catch {
     return [];
   }
@@ -4705,7 +5062,7 @@ function discoverSkillRoots(base, scope) {
   const candidates = [];
   const add = (hostBase, host) => {
     const dir = join(hostBase, host, "skills");
-    if (existsSync12(dir) && statSync3(dir).isDirectory())
+    if (existsSync14(dir) && statSync4(dir).isDirectory())
       candidates.push({ dir, agent: agentLabel(host), scope });
   };
   for (const host of listSubdirs(base)) add(base, host);
@@ -4732,18 +5089,18 @@ function scopeForDir(dir, home, cwd) {
 }
 function locateInstall(skillNames, opts = {}) {
   if (opts.dir) {
-    return existsSync12(opts.dir) ? {
+    return existsSync14(opts.dir) ? {
       dir: opts.dir,
       agent: agentFromDir(opts.dir),
-      scope: scopeForDir(opts.dir, opts.home ?? homedir(), opts.cwd ?? process.cwd())
+      scope: scopeForDir(opts.dir, opts.home ?? homedir2(), opts.cwd ?? process.cwd())
     } : null;
   }
   const roots = [
-    ...discoverSkillRoots(opts.home ?? homedir(), "global"),
+    ...discoverSkillRoots(opts.home ?? homedir2(), "global"),
     ...discoverSkillRoots(opts.cwd ?? process.cwd(), "project")
   ];
   for (const root of roots) {
-    if (skillNames.some((n) => existsSync12(join(root.dir, n, "SKILL.md")))) return root;
+    if (skillNames.some((n) => existsSync14(join(root.dir, n, "SKILL.md")))) return root;
   }
   return null;
 }
@@ -4751,7 +5108,7 @@ function hashInstalled(root, skillNames) {
   const out = {};
   for (const name of skillNames) {
     const skillDir = join(root.dir, name);
-    if (existsSync12(join(skillDir, "SKILL.md"))) out[name] = hashSkillBundle(skillDir);
+    if (existsSync14(join(skillDir, "SKILL.md"))) out[name] = hashSkillBundle(skillDir);
   }
   return out;
 }
@@ -4788,7 +5145,7 @@ function findRepoManifest(cwd = process.cwd()) {
   let dir = cwd;
   for (let i = 0; i < 16; i++) {
     const p = join(dir, MANIFEST_FILE);
-    if (existsSync12(p)) return p;
+    if (existsSync14(p)) return p;
     const parent = join(dir, "..");
     if (parent === dir) break;
     dir = parent;
@@ -4828,9 +5185,9 @@ async function remoteHeadSha(repoSlug) {
 }
 function resolveLocalManifest(source) {
   const direct = source.endsWith(".json") ? source : join(source, MANIFEST_FILE);
-  if (existsSync12(direct)) return JSON.parse(readFileSync13(direct, "utf8"));
+  if (existsSync14(direct)) return JSON.parse(readFileSync13(direct, "utf8"));
   const skillsRoot = source.endsWith("skills") ? source : join(source, "skills");
-  if (existsSync12(skillsRoot)) return buildManifest2(skillsRoot, { source: skillsRoot });
+  if (existsSync14(skillsRoot)) return buildManifest2(skillsRoot, { source: skillsRoot });
   throw new Error(`No skills manifest found at: ${source}`);
 }
 async function fetchRemoteManifest(source) {
@@ -5120,7 +5477,7 @@ import { defineCommand as defineCommand11, runMain } from "citty";
 // package.json
 var package_default = {
   name: "frogoe",
-  version: "0.5.5",
+  version: "0.6.0",
   description: "froge CLI \u2014 the agent's hands: init, add, run, check, bundle",
   homepage: "https://github.com/frogoe/engine#readme",
   bugs: "https://github.com/frogoe/engine/issues",