frizz 0.5.0 → 0.6.0

package/runtime/cc-worker/bin/browser-mcp.mjs

@@ -0,0 +1,730 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * browser-mcp — frizz's LAZY PROXY in front of the upstream `chrome-devtools-mcp` server.
+ *
+ * Every frizz worker mounts a browser MCP server, because the runtime release gate needs a browser on
+ * any machine and neither backend can assume the operator configured one. Most workers never open a
+ * page. Measured on the maintainer's machine 2026-08-19, mounting the real thing eagerly through
+ * `npx -y chrome-devtools-mcp@latest` cost **6.07 GB across 78 processes** — 32% of frizz's entire
+ * footprint — split in two:
+ *
+ *   - 39 × 89 MB  the real server, started at session start whether or not a browser is ever opened;
+ *   - 39 × 70 MB  the `npm exec` shim `npx` leaves behind after it execs the real one. Pure waste:
+ *                 no behaviour is attached to it at all.
+ *
+ * This script replaces BOTH. It is a dependency-free stdio MCP server that:
+ *
+ *   1. answers `initialize`, `tools/list`, `ping` and `logging/setLevel` ITSELF, from a tool-schema
+ *      snapshot on disk — so a worker's tool registry is complete at session start with nothing
+ *      spawned but this ~17 MB node process;
+ *   2. spawns the real server LAZILY, on the first `tools/call`, as `node <resolved bin>` — no npx,
+ *      no npm shim left running;
+ *   3. proxies everything transparently from then on, in BOTH directions.
+ *
+ * ── WHY THE CLIENT'S OWN `initialize` PARAMS ARE REPLAYED VERBATIM ────────────────────────────────
+ * A proxy that introduces itself as the client is not transparent, and the failure is silent rather
+ * than loud. chrome-devtools-mcp reads the client's negotiated capabilities: with no `roots`
+ * capability it prints "File-writing tools will be restricted to the OS temp directory" on stderr and
+ * quietly confines `take_screenshot` there. Claude Code DOES negotiate roots, so a proxy that sent its
+ * own handshake would take every worker's screenshots away without failing anything. So the client's
+ * `initialize` params are stored and handed to the child unchanged, and the child's own requests back
+ * up the wire (`roots/list`, sampling, elicitation) are forwarded to the real client and their
+ * responses forwarded down. The only message this process ever authors on the child's stdin is its own
+ * `initialize`, under a reserved string id nothing else uses.
+ *
+ * ── THE TOOL-SCHEMA SNAPSHOT ──────────────────────────────────────────────────────────────────────
+ * The whole saving depends on answering `tools/list` with the real server NOT running, and the schemas
+ * only exist inside the real server. So they are cached on disk, keyed by the package version:
+ *
+ *   1. `<cache>/tools-<version>.json`      — harvested at runtime, written once per version per machine;
+ *   2. `browser-mcp-tools.json` beside     — the snapshot committed to the repo, regenerated by
+ *      this file                             `nub scripts/harvest-browser-mcp-tools.mjs` (which is this
+ *                                            file under `--frizz-harvest`). It is what makes a machine
+ *                                            that has NEVER run frizz answer `tools/list` instantly:
+ *                                            without it the first worker would have to install and boot
+ *                                            the real server inside the client's MCP-startup window,
+ *                                            and a client that gives up there leaves the worker with no
+ *                                            browser tools for its whole session.
+ *   3. a bounded live harvest              — install + boot + `tools/list` + write (1). Reached only
+ *                                            when the pinned version moved and (2) was not regenerated.
+ *   4. a version-MISMATCHED (2)            — stale schemas beat no schemas.
+ *
+ * Whatever was served, the truth is reconciled the moment the child does start: its real `tools/list`
+ * is compared with what we served, and on a difference (1) is rewritten and
+ * `notifications/tools/list_changed` is sent so the client refetches.
+ *
+ * ── WHERE THE PACKAGE COMES FROM ──────────────────────────────────────────────────────────────────
+ * `chrome-devtools-mcp` is NOT a dependency of `frizz`: it unpacks to 13 MB (it vendors puppeteer-core
+ * and has zero transitive deps), which is dead weight in the published tarball for every user who never
+ * dispatches browser work. Instead it is installed ONCE per machine per version, on first use, into
+ * `~/.frizz/browser-mcp/pkg/<version>/`, and exec'd from there forever after. That is strictly less
+ * network than the `npx -y …@latest` it replaces (which re-resolved `latest` on every single spawn).
+ * An install already present anywhere resolvable from this file wins first, so a layout that DOES vend
+ * the package needs no download at all.
+ *
+ * Concurrency is handled without a lock: each process installs into its own `mkdtemp` and then
+ * `rename`s it into place, which is atomic. A loser's rename fails on the non-empty target, it throws
+ * its copy away, and both processes end up using the winner's.
+ *
+ * ── PROTOCOL ──────────────────────────────────────────────────────────────────────────────────────
+ * MCP over stdio = newline-delimited JSON-RPC 2.0, hand-rolled for the same reasons frizz-mcp.mjs
+ * hand-rolls it: the surface is tiny and this ships as one loose .mjs inside the worker plugin, with no
+ * build, bundle or resolution step. stdout carries protocol frames and NOTHING else; every diagnostic
+ * goes to stderr, where the client logs it.
+ */
+import { spawn } from "node:child_process"
+import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const SNAPSHOT_PATH = join(HERE, "browser-mcp-tools.json")
+const PROTOCOL_FALLBACK = "2025-06-18"
+/** The id this process uses for the ONE request it authors on the child's stdin. */
+const INIT_ID = "frizz-browser-mcp/initialize"
+const LOG_ID = "frizz-browser-mcp/logging"
+/** How long `tools/list` may block on a live harvest before falling back to stale schemas. */
+const HARVEST_BUDGET_MS = 25_000
+/** How long `npm install` may run. Generous: it is paid once per machine per version. */
+const INSTALL_BUDGET_MS = 300_000
+/** How long the real server gets to answer `initialize` before the call it is holding up gives up. */
+const HANDSHAKE_BUDGET_MS = 60_000
+
+// ---- argv ----------------------------------------------------------------------------------------
+// Everything after the frizz-only `--frizz-harvest` mode flag is the upstream server's own argv,
+// forwarded byte-for-byte. `--headless` and `--isolated` ride in there and are NOT this file's to
+// second-guess: see the CHROME_DEVTOOLS_MCP comment in packages/server/src/backend/types.ts for why
+// both are required.
+const rawArgs = process.argv.slice(2)
+const HARVEST = rawArgs.includes("--frizz-harvest")
+const BROWSER_ARGS = rawArgs.filter((a) => a !== "--frizz-harvest")
+
+// ---- what package, which version ----------------------------------------------------------------
+// The server stamps FRIZZ_BROWSER_MCP_PACKAGE from the ONE canonical spec (backend/types.ts), so the
+// pin lives there and not in two places. The snapshot is the fallback so this file stays runnable by
+// hand, and `@latest` is the last resort so it degrades to the old behaviour rather than to nothing.
+const snapshot = readJson(SNAPSHOT_PATH)
+const spec = parseSpec(
+  process.env.FRIZZ_BROWSER_MCP_PACKAGE ||
+    (snapshot?.package && snapshot?.version ? `${snapshot.package}@${snapshot.version}` : "chrome-devtools-mcp@latest"),
+)
+/** Test/ops hook: an explicit install root, so a sandbox never writes to the real `~/.frizz`. */
+const CACHE_DIR = process.env.FRIZZ_BROWSER_MCP_HOME || join(homedir(), ".frizz", "browser-mcp")
+
+/** @param {string} value @returns {{name: string, version: string}} */
+function parseSpec(value) {
+  const at = value.lastIndexOf("@")
+  if (at <= 0) return { name: value, version: "latest" }
+  return { name: value.slice(0, at), version: value.slice(at + 1) }
+}
+
+/** @param {string} path @returns {any} */
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Diagnostics. stderr is where an MCP client is supposed to collect them, but a worker's client keeps
+ * that in a per-session log nobody reads, and this process does its most interesting work (installing,
+ * harvesting, starting the real server) at moments nobody is watching. `FRIZZ_BROWSER_MCP_TRACE=<path>`
+ * appends the same lines to a file so a live worker can be traced without a debugger. Off by default.
+ *
+ * @param {string} message
+ */
+function note(message) {
+  const line = `[frizz browser-mcp ${process.pid}] ${message}\n`
+  try {
+    process.stderr.write(line)
+  } catch {
+    /* a closed stderr is not worth dying over */
+  }
+  const trace = process.env.FRIZZ_BROWSER_MCP_TRACE
+  if (trace) {
+    try {
+      appendFileSync(trace, `${new Date().toISOString()} ${line}`)
+    } catch {
+      /* a trace that cannot be written is not worth failing a tool call over */
+    }
+  }
+}
+
+// ---- stdout framing ------------------------------------------------------------------------------
+/** @param {unknown} obj */
+function send(obj) {
+  try {
+    process.stdout.write(JSON.stringify(obj) + "\n")
+  } catch {
+    /* the client hung up; the exit handlers will tear the child down */
+  }
+}
+/** @param {string|number} id @param {unknown} result */
+function reply(id, result) {
+  send({ jsonrpc: "2.0", id, result })
+}
+/** @param {string|number} id @param {number} code @param {string} message */
+function replyError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } })
+}
+
+// ---- the tool-schema cache -----------------------------------------------------------------------
+const cacheFile = () => join(CACHE_DIR, `tools-${spec.version}.json`)
+
+/** The registry this process serves `initialize` + `tools/list` from. Resolved once, lazily. */
+let registry = null
+
+/**
+ * The registry WITHOUT paying for a harvest — the version cache, else the committed snapshot at any
+ * version. `initialize` uses only this: a client that does not get its handshake promptly declares the
+ * server dead, and the worker then has no browser tools AT ALL for the whole session, which is the
+ * one outcome worse than an eagerly-spawned server.
+ */
+function peekRegistry() {
+  if (registry) return registry
+  const cached = readJson(cacheFile())
+  if (cached?.tools?.length) return (registry = cached)
+  if (snapshot?.tools?.length && snapshot.version === spec.version) return (registry = snapshot)
+  return undefined
+}
+
+/** @returns {Promise<{tools: any[], capabilities?: any, serverInfo?: any, version?: string}>} */
+async function loadRegistry() {
+  const peeked = peekRegistry()
+  if (peeked) return peeked
+  // Nothing pinned to this exact version: pay the harvest, bounded, so a client that is waiting on
+  // `tools/list` gets an answer either way.
+  try {
+    const harvested = await withTimeout(harvest(), HARVEST_BUDGET_MS, "tool-schema harvest")
+    writeCache(harvested)
+    return (registry = harvested)
+  } catch (err) {
+    note(`could not harvest tool schemas (${errText(err)})`)
+  }
+  if (snapshot?.tools?.length) {
+    // Stale schemas beat none: the tool names and shapes move rarely, and a worker with a slightly
+    // out-of-date schema still gets a browser. A worker with an empty registry does not.
+    note(`serving the committed snapshot for ${snapshot.package}@${snapshot.version} against a pinned ${spec.version}`)
+    return (registry = snapshot)
+  }
+  return (registry = { tools: [] })
+}
+
+/** @param {any} value */
+function writeCache(value) {
+  try {
+    mkdirSync(CACHE_DIR, { recursive: true })
+    const tmp = `${cacheFile()}.${process.pid}.tmp`
+    writeFileSync(tmp, JSON.stringify(value))
+    renameSync(tmp, cacheFile())
+  } catch (err) {
+    note(`could not write the tool-schema cache (${errText(err)})`)
+  }
+}
+
+// ---- resolving / installing the real server ------------------------------------------------------
+/** `bin` may be a string or a map; take the entry named after the package, else the sole one. */
+function binPath(pkgDir) {
+  const pkg = readJson(join(pkgDir, "package.json"))
+  if (!pkg) return undefined
+  const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.[spec.name] ?? Object.values(pkg.bin ?? {})[0]
+  if (typeof bin !== "string") return undefined
+  const abs = join(pkgDir, bin)
+  return existsSync(abs) ? { bin: abs, version: pkg.version } : undefined
+}
+
+const installRoot = () => join(CACHE_DIR, "pkg", spec.version)
+
+/** @returns {{bin: string, version?: string} | undefined} */
+function resolveInstalled() {
+  const override = process.env.FRIZZ_BROWSER_MCP_BIN
+  if (override && existsSync(override)) return { bin: override }
+  const managed = binPath(join(installRoot(), "node_modules", spec.name))
+  if (managed) return managed
+  // An ambient copy: a layout that vends the package as a real dependency resolves from here.
+  try {
+    const manifest = createRequire(import.meta.url).resolve(`${spec.name}/package.json`)
+    const ambient = binPath(dirname(manifest))
+    if (ambient && (spec.version === "latest" || ambient.version === spec.version)) return ambient
+  } catch {
+    /* not resolvable from here — normal */
+  }
+  return undefined
+}
+
+/**
+ * `npm` as an argv, preferring the npm-cli.js beside this node over anything on PATH: the worker's
+ * PATH varies by launch context, and this avoids `npm.cmd` + a shell on Windows entirely.
+ */
+function npmArgv() {
+  const cli = join(dirname(process.execPath), "..", "lib", "node_modules", "npm", "bin", "npm-cli.js")
+  const sibling = join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")
+  for (const candidate of [cli, sibling]) if (existsSync(candidate)) return [process.execPath, candidate]
+  return [process.platform === "win32" ? "npm.cmd" : "npm"]
+}
+
+/**
+ * Staging directories this process created, so an orderly exit does not leave one behind. A SIGKILL
+ * still can, which is what sweepStaleStaging is for.
+ */
+const ownStaging = new Set()
+
+/**
+ * Delete `.install-*` directories no live install can still own. An install interrupted before its
+ * rename — the client killing a probe connection, a machine going to sleep — leaves 13 MB behind
+ * forever otherwise, and it happened on the very first real worker run.
+ */
+function sweepStaleStaging() {
+  const cutoff = Date.now() - 60 * 60 * 1000
+  try {
+    for (const entry of readdirSync(CACHE_DIR)) {
+      if (!entry.startsWith(".install-")) continue
+      const path = join(CACHE_DIR, entry)
+      if (ownStaging.has(path)) continue
+      try {
+        if (statSync(path).mtimeMs < cutoff) rmSync(path, { recursive: true, force: true })
+      } catch {
+        /* a directory that vanished under us is exactly the outcome we wanted */
+      }
+    }
+  } catch {
+    /* no cache dir yet */
+  }
+}
+
+/** @returns {Promise<{bin: string, version?: string}>} */
+async function ensureInstalled() {
+  const found = resolveInstalled()
+  if (found) return found
+  mkdirSync(CACHE_DIR, { recursive: true })
+  sweepStaleStaging()
+  const staging = mkdtempSync(join(CACHE_DIR, ".install-"))
+  ownStaging.add(staging)
+  const [cmd, ...pre] = npmArgv()
+  const args = [
+    ...pre,
+    "install",
+    "--prefix",
+    staging,
+    `${spec.name}@${spec.version}`,
+    "--no-audit",
+    "--no-fund",
+    "--no-package-lock",
+    "--loglevel=error",
+  ]
+  note(`installing ${spec.name}@${spec.version} (one time, into ${installRoot()})`)
+  try {
+    await run(cmd, args, INSTALL_BUDGET_MS)
+    mkdirSync(dirname(installRoot()), { recursive: true })
+    try {
+      renameSync(staging, installRoot())
+    } catch {
+      // Another worker won the race and landed its copy first. Its tree is as good as ours.
+      rmSync(staging, { recursive: true, force: true })
+    }
+    ownStaging.delete(staging)
+  } catch (err) {
+    rmSync(staging, { recursive: true, force: true })
+    ownStaging.delete(staging)
+    throw new Error(`could not install ${spec.name}@${spec.version}: ${errText(err)}`)
+  }
+  const installed = resolveInstalled()
+  if (!installed) throw new Error(`installed ${spec.name}@${spec.version} but found no runnable bin under ${installRoot()}`)
+  return installed
+}
+
+/** @param {string} cmd @param {string[]} args @param {number} timeoutMs */
+function run(cmd, args, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] })
+    let err = ""
+    proc.stdout.on("data", () => {})
+    proc.stderr.on("data", (d) => {
+      err += d
+    })
+    const timer = setTimeout(() => {
+      proc.kill("SIGKILL")
+      reject(new Error(`timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+    proc.on("error", (e) => {
+      clearTimeout(timer)
+      reject(e)
+    })
+    proc.on("close", (code) => {
+      clearTimeout(timer)
+      if (code === 0) resolve(undefined)
+      else reject(new Error(`exit ${code}${err ? `: ${err.trim().slice(0, 400)}` : ""}`))
+    })
+  })
+}
+
+// ---- the child, and the two-way pipe -------------------------------------------------------------
+/** @type {import("node:child_process").ChildProcessWithoutNullStreams | null} */
+let child = null
+/** Single-flight start. Cleared on failure and on exit so a later call can try again. */
+let starting = null
+/** The client's own `initialize` params, replayed to the child verbatim. See the header. */
+let clientInit = null
+/** A `logging/setLevel` the client set before the child existed, replayed on start. */
+let pendingLogLevel = null
+/** Client request ids currently in flight downstream, so a child crash can answer them. */
+const inFlight = new Set()
+/** Requests THIS process authored on the child's stdin. */
+const internal = new Map()
+
+/** @param {unknown} obj */
+function sendChild(obj) {
+  child?.stdin.write(JSON.stringify(obj) + "\n")
+}
+
+/** @param {string} id @param {string} method @param {unknown} params */
+function childRequest(id, method, params) {
+  return new Promise((resolve, reject) => {
+    internal.set(id, { resolve, reject })
+    sendChild({ jsonrpc: "2.0", id, method, params })
+  })
+}
+
+function onChildLine(line) {
+  let msg
+  try {
+    msg = JSON.parse(line)
+  } catch {
+    return // a non-protocol line on stdout is not ours to invent meaning for
+  }
+  const pending = msg.id !== undefined && msg.id !== null ? internal.get(msg.id) : undefined
+  if (pending) {
+    internal.delete(msg.id)
+    if (msg.error) pending.reject(new Error(msg.error.message ?? "child error"))
+    else pending.resolve(msg.result)
+    return
+  }
+  if (msg.id !== undefined && msg.id !== null && msg.method === undefined) inFlight.delete(msg.id)
+  send(msg) // responses to the client's requests, the child's own requests, and its notifications
+}
+
+function onChildGone(reason) {
+  const dead = inFlight.size
+  child = null
+  starting = null
+  for (const { reject } of internal.values()) reject(new Error(reason))
+  internal.clear()
+  for (const id of inFlight) replyError(id, -32000, `${spec.name} exited before answering: ${reason}`)
+  inFlight.clear()
+  if (dead) note(`the browser server died with ${dead} call(s) in flight (${reason})`)
+}
+
+/** @returns {Promise<void>} */
+function ensureChild() {
+  if (child) return Promise.resolve()
+  if (starting) return starting
+  starting = (async () => {
+    const { bin } = await ensureInstalled()
+    const proc = spawn(process.execPath, [bin, ...BROWSER_ARGS], { stdio: ["pipe", "pipe", "pipe"] })
+    child = proc
+    let buf = ""
+    proc.stdout.setEncoding("utf8")
+    proc.stdout.on("data", (chunk) => {
+      buf += chunk
+      let nl
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl).trim()
+        buf = buf.slice(nl + 1)
+        if (line) onChildLine(line)
+      }
+    })
+    proc.stderr.on("data", (d) => {
+      try {
+        process.stderr.write(d)
+      } catch {
+        /* ignore */
+      }
+    })
+    proc.on("error", (err) => onChildGone(errText(err)))
+    proc.on("exit", (code, signal) => onChildGone(signal ? `signal ${signal}` : `exit ${code}`))
+    // The CLIENT's handshake, not ours — see the header. Absent (a `tools/call` with no preceding
+    // `initialize`, which no real client does) we introduce ourselves honestly.
+    const init = clientInit ?? {
+      protocolVersion: PROTOCOL_FALLBACK,
+      capabilities: {},
+      clientInfo: { name: "frizz-browser-mcp", version: "1" },
+    }
+    const negotiated = await withTimeout(childRequest(INIT_ID, "initialize", init), HANDSHAKE_BUDGET_MS, "the browser server handshake")
+    sendChild({ jsonrpc: "2.0", method: "notifications/initialized" })
+    if (pendingLogLevel) sendChild({ jsonrpc: "2.0", id: LOG_ID, method: "logging/setLevel", params: { level: pendingLogLevel } })
+    void reconcileTools(proc, negotiated)
+  })()
+  starting.catch(() => {
+    // A child that spawned but never finished its handshake is not reusable; drop it so the NEXT call
+    // gets a clean attempt rather than an inheritance of this failure.
+    starting = null
+    try {
+      child?.kill()
+    } catch {
+      /* already gone */
+    }
+    child = null
+  })
+  return starting
+}
+
+/**
+ * The moment the real server exists, its `tools/list` is the truth. Compare it with what we served; on
+ * a difference, rewrite the version cache and tell the client to refetch. This is what keeps a stale
+ * snapshot from being a permanent lie rather than a one-session approximation.
+ */
+async function reconcileTools(proc, negotiated) {
+  try {
+    const result = await childRequest("frizz-browser-mcp/tools", "tools/list", {})
+    if (!result?.tools || child !== proc) return
+    const served = registry?.tools
+    if (served && JSON.stringify(result.tools) === JSON.stringify(served)) return
+    writeCache({
+      package: spec.name,
+      version: spec.version,
+      protocolVersion: negotiated?.protocolVersion ?? registry?.protocolVersion,
+      capabilities: negotiated?.capabilities ?? registry?.capabilities,
+      serverInfo: negotiated?.serverInfo ?? registry?.serverInfo,
+      tools: result.tools,
+    })
+    registry = { ...(registry ?? {}), tools: result.tools }
+    if (!served) return // nothing was ever served to this client, so there is nothing to correct
+    note(`tool schemas changed under version ${spec.version}; cache refreshed`)
+    send({ jsonrpc: "2.0", method: "notifications/tools/list_changed" })
+  } catch (err) {
+    note(`could not reconcile tool schemas (${errText(err)})`)
+  }
+}
+
+// ---- harvest mode --------------------------------------------------------------------------------
+/** Boot the real server once and read its registry out. Used by `--frizz-harvest` AND by loadRegistry. */
+async function harvest() {
+  const { bin, version } = await ensureInstalled()
+  const proc = spawn(process.execPath, [bin, ...BROWSER_ARGS], { stdio: ["pipe", "pipe", "ignore"] })
+  try {
+    let buf = ""
+    const pending = new Map()
+    proc.stdout.setEncoding("utf8")
+    proc.stdout.on("data", (chunk) => {
+      buf += chunk
+      let nl
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl).trim()
+        buf = buf.slice(nl + 1)
+        if (!line) continue
+        let msg
+        try {
+          msg = JSON.parse(line)
+        } catch {
+          continue
+        }
+        const waiter = pending.get(msg.id)
+        if (!waiter) continue
+        pending.delete(msg.id)
+        if (msg.error) waiter.reject(new Error(msg.error.message ?? "error"))
+        else waiter.resolve(msg.result)
+      }
+    })
+    const ask = (id, method, params) =>
+      new Promise((resolve, reject) => {
+        pending.set(id, { resolve, reject })
+        proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n")
+      })
+    proc.on("exit", () => {
+      for (const w of pending.values()) w.reject(new Error("the browser server exited during the harvest"))
+      pending.clear()
+    })
+    const init = await ask(1, "initialize", {
+      protocolVersion: PROTOCOL_FALLBACK,
+      capabilities: { roots: { listChanged: true } },
+      clientInfo: { name: "frizz-browser-mcp", version: "1" },
+    })
+    proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) + "\n")
+    const list = await ask(2, "tools/list", {})
+    return {
+      package: spec.name,
+      version: version ?? spec.version,
+      protocolVersion: init?.protocolVersion ?? PROTOCOL_FALLBACK,
+      capabilities: init?.capabilities ?? { tools: { listChanged: true } },
+      serverInfo: init?.serverInfo,
+      tools: list?.tools ?? [],
+    }
+  } finally {
+    proc.kill()
+  }
+}
+
+// ---- helpers -------------------------------------------------------------------------------------
+/** @param {Promise<any>} promise @param {number} ms @param {string} what */
+function withTimeout(promise, ms, what) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${what} timed out after ${ms}ms`)), ms)
+    promise.then(
+      (v) => {
+        clearTimeout(timer)
+        resolve(v)
+      },
+      (e) => {
+        clearTimeout(timer)
+        reject(e)
+      },
+    )
+  })
+}
+
+/** @param {unknown} err */
+function errText(err) {
+  return err instanceof Error ? err.message : String(err)
+}
+
+// ---- the client side -----------------------------------------------------------------------------
+/** @param {any} msg */
+async function handle(msg) {
+  const { id, method, params } = msg ?? {}
+  const isNotification = id === undefined || id === null
+  if (process.env.FRIZZ_BROWSER_MCP_TRACE) note(`<- ${method ?? "(response)"} id=${String(id)}`)
+
+  // A RESPONSE from the client (to a `roots/list` or a sampling request the child made) — never ours
+  // to interpret, always the child's to receive.
+  if (method === undefined) {
+    if (child) sendChild(msg)
+    return
+  }
+
+  switch (method) {
+    case "initialize": {
+      clientInit = params
+      const reg = peekRegistry()
+      const requested = params?.protocolVersion
+      reply(id, {
+        protocolVersion: typeof requested === "string" ? requested : reg?.protocolVersion ?? PROTOCOL_FALLBACK,
+        capabilities: reg?.capabilities ?? { tools: { listChanged: true } },
+        serverInfo: reg?.serverInfo ?? { name: spec.name, version: spec.version },
+      })
+      return
+    }
+    case "notifications/initialized":
+    case "initialized":
+      return // notification — no reply, and nothing to start
+    case "ping":
+      if (!isNotification) reply(id, {})
+      return
+    case "tools/list": {
+      // The whole point: answered WITHOUT the real server, unless it happens to be up already.
+      if (child) return forward(msg)
+      const reg = await loadRegistry()
+      reply(id, { tools: reg.tools })
+      return
+    }
+    case "logging/setLevel":
+      pendingLogLevel = params?.level ?? null
+      if (child) return forward(msg)
+      if (!isNotification) reply(id, {})
+      return
+    default:
+      // ONLY `tools/call` starts the browser. Everything else that reaches here is answered the way the
+      // real server answers it — which for this server is `-32601 Method not found`, since it advertises
+      // nothing but `logging` and `tools` (verified against 1.7.0 for `server/discover`, `resources/list`
+      // and `prompts/list`; all three come back -32601).
+      //
+      // THIS BRANCH IS WHERE THE WHOLE CHANGE ALMOST DIED. Claude Code opens a short-lived probe
+      // connection and sends `server/discover` (id `server-discover-probe-1`) BEFORE the real session.
+      // While `default:` meant "start the browser", every worker paid a full install + server boot at
+      // session start, in a process the client then killed — which also leaked its half-finished install
+      // staging. Caught on 2026-08-19 only by tracing a real worker's proxy (FRIZZ_BROWSER_MCP_TRACE);
+      // every unit test and the whole tool-call path passed while it was happening.
+      if (isNotification) {
+        if (child) sendChild(msg)
+        return
+      }
+      if (method !== "tools/call") {
+        if (child) forward(msg)
+        else replyError(id, -32601, "Method not found")
+        return
+      }
+      try {
+        await ensureChild()
+      } catch (err) {
+        // A tool that is LISTED but dies when called is worse than one that was never offered, so say
+        // exactly what went wrong in the tool result the MODEL reads, not only in a protocol error it
+        // never sees.
+        reply(id, {
+          content: [{ type: "text", text: `frizz could not start ${spec.name}@${spec.version}: ${errText(err)}` }],
+          isError: true,
+        })
+        return
+      }
+      forward(msg)
+      return
+  }
+}
+
+/** @param {any} msg */
+function forward(msg) {
+  if (msg.id !== undefined && msg.id !== null) inFlight.add(msg.id)
+  sendChild(msg)
+}
+
+// ---- lifecycle -----------------------------------------------------------------------------------
+function shutdown(code) {
+  try {
+    child?.kill()
+  } catch {
+    /* already gone */
+  }
+  process.exit(code)
+}
+process.on("exit", () => {
+  try {
+    child?.kill()
+  } catch {
+    /* already gone */
+  }
+  for (const path of ownStaging) {
+    try {
+      rmSync(path, { recursive: true, force: true })
+    } catch {
+      /* best effort on the way out */
+    }
+  }
+})
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(sig, () => shutdown(0))
+
+if (HARVEST) {
+  harvest().then(
+    (result) => {
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n")
+      shutdown(0)
+    },
+    (err) => {
+      note(`harvest failed: ${errText(err)}`)
+      shutdown(1)
+    },
+  )
+} else {
+  // NDJSON reader: buffer stdin, dispatch each complete line. Messages never contain raw newlines.
+  let buf = ""
+  process.stdin.setEncoding("utf8")
+  process.stdin.on("data", (chunk) => {
+    buf += chunk
+    let nl
+    while ((nl = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, nl).trim()
+      buf = buf.slice(nl + 1)
+      if (!line) continue
+      let msg
+      try {
+        msg = JSON.parse(line)
+      } catch {
+        continue // ignore unparseable lines
+      }
+      void handle(msg)
+    }
+  })
+  process.stdin.on("end", () => shutdown(0))
+}