frizz 0.2.0 → 0.4.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <h1 align="center">🧵<br/>Frizz</h1>
+  <h1 align="center"><img src="assets/logo-concepts/final/fff-tile.png" alt="" width="104" height="104"><br/>Frizz</h1>
   <p align="center">A local web UI for running many coding agents at once.
     <br/>
     by <a href="https://x.com/colinhacks">@colinhacks</a>
@@ -30,19 +30,19 @@ Frizz is for you if you have any of these opinions:
 Then run it in any directory — a repo, a jj checkout, or a folder of scripts. Frizz has no opinion about version control and does not require Git.
 
 ```sh
-$ cd path/to/project
+$ cd path/to/acme
 $ npx frizz
 
-  FRIZZ v0.2.0  ready in 4.0s
+  FRIZZ v0.4.0  ready in 4.0s
 
-  ➜  Local:    http://127.0.0.1:4922/
-  ➜  Project:  project — path/to/project
-  ➜  Logs:     ~/.frizz/projects/979dae3c-fe15-4038-817e-11d0e7491959/logs/frizz-2026-08-01T13-44-43-16931.log
+  ➜  Local:    http://127.0.0.1:9393/project/acme/
+  ➜  Project:  acme — path/to/acme
+  ➜  Logs:     ~/Library/Application Support/Frizz/projects/979dae3c-fe15-4038-817e-11d0e7491959/logs/frizz-2026-08-01T13-44-43-16931.log
 
   press ctrl-c to stop · run with --debug for the full event feed
 ```
 
-A browser tab opens on localhost — a dedicated workspace for this directory. **One tab per project!** Runs on macOS, Linux, and Windows.
+A browser tab opens on localhost — a dedicated workspace for this directory. **One tab per project!** One Frizz serves every project on the machine, each at its own `/project/<name>` URL, so running it in a second directory joins the server already running rather than starting another. Runs on macOS, Linux, and Windows.
 
 <p align="center">
   <img src="assets/board.png" alt="Frizz running in a browser tab at 127.0.0.1:4921: a sidebar of threads on the left, and on the right a card where an agent is asking an answerable question with lettered options, above Snooze and Mark as done." width="100%">
@@ -62,7 +62,7 @@ Frizz is a browser tab, a queue, and the agent CLIs you already pay for. It brin
 - 🐙 **GitHub integration.** Browse your repo's issues and pull requests without leaving the composer, and turn a selection of them into threads. Workers can read issues, diffs, and CI on their own.
 - 👀 **Built-in CI and PR watchers.** A worker waiting on a build or a review doesn't hand the thread back to you to be told "keep going." It watches, and picks the work back up when the run goes green or a review lands.
 - 📝 **No magic.** A thread behaves like a Claude Code session you started yourself. Frizz adds no worktrees, no branches, no dev server, no build integration, no workflow engine to fight with.
-- 🔒 **Local only.** No cloud, no account, no telemetry. The server binds `127.0.0.1` by default and its state lives in `~/.frizz/`, never in your checkout.
+- 🔒 **Local only.** No cloud, no account, no telemetry. The server binds `127.0.0.1` by default and its state lives in your user directory, never in your checkout.
 
 ### The queue
 
@@ -133,21 +133,24 @@ Options:
   --host [address]       serve on a network address instead of loopback (bare --host means 0.0.0.0)
   --allowed-host <name>  with --host, also accept this DNS name as the board's address (repeatable)
   --public-origin <url>  serve behind a proxy/tunnel reachable at this exact origin
+  --link                 print a fresh single-use access link for the running board
   --debug                stream the full event feed to the terminal instead of the compact readout
   -h, --help             show this help
 
 Environment:
-  FRIZZ_HOST             same as --host
-  FRIZZ_ALLOWED_HOSTS    same as --allowed-host, comma separated
-  FRIZZ_PUBLIC_ORIGIN    same as --public-origin
+  FRIZZ_HOST              same as --host
+  FRIZZ_ALLOWED_HOSTS     same as --allowed-host, comma separated
+  FRIZZ_PUBLIC_ORIGIN     same as --public-origin
+  FRIZZ_PUBLIC_TOKEN      standing secret for HEADLESS boxes that cannot show a QR
 
---host puts a board that can run shell commands as you on the network, and Frizz has no login:
-anyone who reaches the port controls it. Only do this on a network you trust. An IP address works
-as-is; to reach the board by DNS name you must list that name with --allowed-host ("*" allows any).
+--host puts a board that can run shell commands as you on the network, and Frizz has no login: anyone
+who reaches the port controls it. Only do this on a network you trust. An IP address works as-is; to
+reach the board by DNS name you must list that name with --allowed-host ("*" allows any).
 
 --public-origin serves the board through a tunnel or reverse proxy without putting it on the LAN
-at all — Frizz stays on loopback and the tunnel dials it. Frizz still has no login, so require
-authentication at the proxy: with Cloudflare Access, that is the whole of your access control.
+at all — Frizz stays on loopback and the tunnel dials it. It prints a SINGLE-USE access link, and
+shows it as a QR so you can scan it from a phone; press L for a fresh one at any time. Scanning it
+trades the code for a session cookie, so the link itself stops working the moment it is used.
 ```
 
 <br/>
@@ -178,7 +181,7 @@ authentication at the proxy: with Cloudflare Access, that is the whole of your a
 <details>
 <summary><b>Does it put junk in my repo?</b></summary>
 
-> Barely. Dispatching a thread writes no thread file into your repo — the agent session *is* the thread. All Frizz adds to your working tree is a `.frizz/` directory holding a scratchpad per thread plus a couple of tiny hook state files. Everything durable lives outside your checkout in `~/.frizz/projects/<id>/`, so you can delete `.frizz/` and keep every thread and setting. Frizz does not touch your `.gitignore`, so add `.frizz/` yourself if you don't want it in `git status`.
+> Barely. Dispatching a thread writes no thread file into your repo — the agent session *is* the thread. All Frizz adds to your working tree is a `.frizz/` directory holding a scratch directory per thread (empty unless the agent writes something in it) plus a couple of tiny hook state files. Everything durable lives outside your checkout, under `~/.frizz/` if you already have one and otherwise in your platform's own data directory (`~/Library/Application Support/Frizz` on macOS, `$XDG_DATA_HOME/frizz` on Linux, LocalAppData on Windows), so you can delete `.frizz/` and keep every thread and setting. Frizz does not touch your `.gitignore`, so add `.frizz/` yourself if you don't want it in `git status`.
 
 </details>
 
@@ -208,7 +211,7 @@ authentication at the proxy: with Cloudflare Access, that is the whole of your a
 >
 > Frizz prints the addresses to use and warns you as it starts. Reaching it by IP works as-is; reach it by name and you have to say so — `--host --allowed-host frizz.local` — because an unlisted name is how DNS rebinding gets a browser to treat an attacker's page as same-origin with your board. `FRIZZ_HOST` and `FRIZZ_ALLOWED_HOSTS` do the same thing when the launch command lives in an image or a unit file.
 >
-> Understand what you're turning on. Frizz has no login: reaching the port *is* the authorization, and the board runs shell commands as you. Only do this on a network you trust, and prefer a tunnel (`ssh -L 4922:127.0.0.1:4922 you@box`, using the port Frizz printed, the same on both ends) if you just want your own board from your own laptop — that needs no flag at all.
+> Understand what you're turning on. Frizz has no login: reaching the port *is* the authorization, and the board runs shell commands as you. Only do this on a network you trust, and prefer a tunnel (`ssh -L 9393:127.0.0.1:9393 you@box`, using the port Frizz printed, the same on both ends) if you just want your own board from your own laptop — that needs no flag at all.
 
 </details>
 
@@ -219,14 +222,16 @@ authentication at the proxy: with Cloudflare Access, that is the whole of your a
 >
 > ```sh
 > npx frizz --public-origin https://frizz.example.com
-> cloudflared tunnel --url http://127.0.0.1:4922   # the port Frizz printed
+> cloudflared tunnel --url http://127.0.0.1:9393   # the port Frizz printed
 > ```
 >
 > Frizz stays bound to `127.0.0.1` — `--public-origin` is not `--host` and does not put anything on your LAN. The tunnel runs on the same machine and dials the loopback port, so the only way in is through the tunnel. That is also what makes this the *good* remote option rather than merely a working one: the tunnel terminates TLS, so the board is a real `https://` origin and therefore a secure context, which plain `--host` over a LAN IP is not. Copy buttons and desktop notifications work again, and it works on a phone.
 >
 > The address you pass must be the exact origin your browser shows — scheme and host, no path. Frizz accepts that one origin, and accepts `X-Forwarded-*` only on requests that actually arrived as it.
 >
-> **This is the part that matters: Frizz has no login, so whatever you put in front of the tunnel *is* your access control.** A bare tunnel publishes a shell-capable board to the open internet for anyone who has the URL. Require authentication at the proxy — with Cloudflare, that means a [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/) application over the hostname, with a policy allowing only your own email, created *before* the hostname resolves. Tailscale Serve is the same idea with device identity instead of SSO. Frizz prints this warning on every launch that names a public origin, and it is not boilerplate.
+> Frizz prints a **single-use** access link and renders it as a QR in your terminal, so you can scan it from a phone without typing forty characters. Scanning trades the code for a session cookie and the link immediately stops working; press **L** any time for a fresh one. A code expires in five minutes, and a spent one says so rather than failing silently.
+
+**Even so: Frizz has no accounts, so that link — and anything you put in front of the tunnel — *is* your access control.** A bare tunnel publishes a shell-capable board to the open internet for anyone who has the URL. Require authentication at the proxy — with Cloudflare, that means a [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/) application over the hostname, with a policy allowing only your own email, created *before* the hostname resolves. Tailscale Serve is the same idea with device identity instead of SSO. Frizz prints this warning on every launch that names a public origin, and it is not boilerplate.
 
 </details>
 

package/dist/claude-agent-broker.js

@@ -19861,6 +19861,7 @@ var CLAUDE_BROKER_CAPABILITY_CANCEL_INPUT = "cancel-input-v1";
 var CLAUDE_BROKER_CAPABILITY_STOP_TASK = "stop-task-v1";
 var CLAUDE_BROKER_CAPABILITY_RELOAD_PLUGINS = "reload-plugins-v1";
 var CLAUDE_BROKER_CAPABILITY_RENAME = "rename-v1";
+var CLAUDE_INPUT_DROP_DIAGNOSTIC_PREFIX = "input dropped, the agent never received it";
 var ClaudeAgentSdkProtocolError = class extends Error {
   constructor(message) {
     super(message);
@@ -20114,6 +20115,7 @@ var MAX_PERMISSION_REQUESTS = 128;
 var MAX_ELICITATION_CALLBACKS = 128;
 var MAX_SESSION_TITLE_DESCRIPTION_BYTES = 64 * 1024;
 var MAX_SESSION_TITLE_BYTES = 2 * 1024;
+var UNECHOABLE_AFTER_RESULTS = 2;
 var NUB_NODE_SHIM_PATH_SEGMENT = /(?:^|[\\/])nub-node-shim-[^\\/]+$/;
 function createClaudeQueryFactory(options) {
   if (options.enabled !== true) {
@@ -20245,8 +20247,12 @@ var RealClaudeQueryHandle = class {
   input;
   diagnostic;
   lifecycleAbort;
-  outstandingInputs = /* @__PURE__ */ new Set();
-  outstandingInputOrder = [];
+  // id → the main-thread turn count at the moment it was sent. A Map rather than a Set plus a
+  // parallel order array because insertion order IS send order, which is all the oldest-first
+  // fallback release ever wanted, and the recorded turn count is what makes the bound reclaimable
+  // (see pruneUnechoableInputs).
+  outstandingInputs = /* @__PURE__ */ new Map();
+  mainThreadResults = 0;
   providerProgressCovered = false;
   closePromise;
   constructor(sdkQuery, input, sessionId, lifecycleAbort, redactor, diagnostic) {
@@ -20272,11 +20278,11 @@ var RealClaudeQueryHandle = class {
     const parsed = validateInputMessage(message);
     if (!UUID_PATTERN.test(parsed.id)) throw new ClaudeAgentSdkProtocolError("input.id must be a UUID");
     if (this.outstandingInputs.has(parsed.id)) throw new ClaudeAgentSdkProtocolError("input UUID is already outstanding");
+    if (this.outstandingInputs.size >= CLAUDE_AGENT_SDK_MAX_QUEUED_INPUTS) this.pruneUnechoableInputs();
     if (this.outstandingInputs.size >= CLAUDE_AGENT_SDK_MAX_QUEUED_INPUTS) {
       throw new ClaudeAgentSdkProtocolError("Claude outstanding input limit exceeded");
     }
-    this.outstandingInputs.add(parsed.id);
-    this.outstandingInputOrder.push(parsed.id);
+    this.outstandingInputs.set(parsed.id, this.mainThreadResults);
     try {
       this.input.push({
         type: "user",
@@ -20288,8 +20294,6 @@ var RealClaudeQueryHandle = class {
       });
     } catch (error) {
       this.outstandingInputs.delete(parsed.id);
-      const orderIndex = this.outstandingInputOrder.indexOf(parsed.id);
-      if (orderIndex >= 0) this.outstandingInputOrder.splice(orderIndex, 1);
       throw error;
     }
   }
@@ -20383,11 +20387,7 @@ var RealClaudeQueryHandle = class {
     if (typeof answer !== "boolean") {
       throw new ClaudeAgentSdkProtocolError("Claude queued-input cancellation returned an unreadable answer");
     }
-    if (answer) {
-      this.outstandingInputs.delete(messageUuid);
-      const orderIndex = this.outstandingInputOrder.indexOf(messageUuid);
-      if (orderIndex >= 0) this.outstandingInputOrder.splice(orderIndex, 1);
-    }
+    if (answer) this.outstandingInputs.delete(messageUuid);
     return answer;
   }
   async setPermissionMode(mode) {
@@ -20499,27 +20499,56 @@ var RealClaudeQueryHandle = class {
   }
   observeProviderProgress(event) {
     if (event.kind === "user" && !event.synthetic && event.toolResultIds.length === 0 && event.messageId && this.outstandingInputs.delete(event.messageId)) {
-      const orderIndex = this.outstandingInputOrder.indexOf(event.messageId);
-      if (orderIndex >= 0) this.outstandingInputOrder.splice(orderIndex, 1);
       this.providerProgressCovered = true;
       return;
     }
     const mainThreadProgress = event.kind === "assistant" && event.parentToolUseId === void 0 || event.kind === "result";
     if (mainThreadProgress) {
       if (!this.providerProgressCovered && this.releaseOldestOutstandingInput()) this.providerProgressCovered = true;
-      if (event.kind === "result") this.providerProgressCovered = false;
+      if (event.kind === "result") {
+        this.providerProgressCovered = false;
+        this.mainThreadResults += 1;
+      }
     }
   }
   releaseOldestOutstandingInput() {
-    while (this.outstandingInputOrder.length > 0) {
-      const id2 = this.outstandingInputOrder.shift();
-      if (this.outstandingInputs.delete(id2)) return true;
-    }
-    return false;
+    const oldest = this.outstandingInputs.keys().next();
+    if (oldest.done === true) return false;
+    this.outstandingInputs.delete(oldest.value);
+    return true;
+  }
+  /**
+   * Reclaim the slots of inputs the provider can no longer echo.
+   *
+   * The CLI consumes a queued input at a TURN BOUNDARY: send it to an idle session and the echo comes
+   * back on the turn that starts immediately; send it mid-turn and it is consumed when that turn ends.
+   * So an input still unechoed after TWO main-thread `result` frames have passed under it was either
+   * consumed without an echo frizz could match or lost outright — either way its echo is never coming,
+   * and holding its slot for the life of the session is a pure leak. Measured on the session in the
+   * `send` comment: 349 inputs accepted in one daemon generation, 36 of them never echoed.
+   *
+   * Deliberately NOT a "just evict the oldest to make room" eviction, which would also throw away the
+   * genuinely-queued. A flood of 64 sends inside a single turn prunes nothing and still rejects, which
+   * is the backpressure this bound exists for: `ClaudeInputQueue` cannot supply it, because the SDK
+   * drains that queue eagerly and its buffer therefore sits near empty however hard the host sends.
+   */
+  pruneUnechoableInputs() {
+    let reclaimed = 0;
+    for (const [id2, resultsAtSend] of this.outstandingInputs) {
+      if (this.mainThreadResults - resultsAtSend < UNECHOABLE_AFTER_RESULTS) continue;
+      this.outstandingInputs.delete(id2);
+      reclaimed += 1;
+    }
+    if (reclaimed === 0) return;
+    this.diagnostic?.({
+      kind: "stderr",
+      message: `reclaimed ${reclaimed} outstanding input slot(s) the provider never echoed`,
+      truncated: false
+    });
   }
   clearOutstandingInputs() {
     this.outstandingInputs.clear();
-    this.outstandingInputOrder.splice(0);
+    this.mainThreadResults = 0;
     this.providerProgressCovered = false;
   }
   async awaitOpenControl(operation) {
@@ -20594,13 +20623,18 @@ function startClaudeQuery(executablePath, options) {
       ...options.session.kind === "new" ? { sessionId } : { resume: sessionId },
       canUseTool,
       onElicitation,
-      // PROJECT + LOCAL by default — see ClaudeQueryStartOptions.settingSources. `[]` was correct while
-      // this was a standalone foundation nothing dispatched through; once the broker became the DEFAULT
+      // EVERY scope by default — see ClaudeQueryStartOptions.settingSources. `[]` was correct while this
+      // was a standalone foundation nothing dispatched through; once the broker became the DEFAULT
       // Claude transport it silently stopped every worker from seeing the repo's own `CLAUDE.md` /
       // `AGENTS.md` and its `.claude/skills`. Measured differential in the frizz repo, one variable:
       // this factory answered `NO-CLAUDE-MD` where a plain `claude -p` in the same cwd answered
-      // "# No pull requests — land on local `main`". `"user"` stays OUT on purpose (see the field docs).
-      settingSources: options.settingSources ?? ["project", "local"],
+      // "# No pull requests — land on local `main`". That fix restored PROJECT + LOCAL and left USER
+      // out, which kept a second, quieter half of the same regression: the tmux transport ran plain
+      // `claude` and got all three scopes, so a broker session was the only place the operator's
+      // `~/.claude/settings.json` stopped applying. Measured 2026-08-16 against the maintainer's real
+      // config, one variable: `--setting-sources=project,local` reported their `env` block UNSET where
+      // `user,project,local` reported it applied.
+      settingSources: options.settingSources ?? ["user", "project", "local"],
       // The frizz worker environment (see ClaudeQueryStartOptions): load the local cc-worker plugin so a
       // broker session gets the frizz sub-agent profiles + hooks, mount the MCP servers (frizz +
       // chrome-devtools), and pre-approve them.
@@ -21408,7 +21442,10 @@ var EVENT_ERROR_TOLERANCE = 5;
 function runClaudeBroker(config) {
   const generation = config.generation ?? randomUUID();
   let client = null;
+  const MAX_BACKLOG_FRAMES = 2e4;
+  const MAX_BACKLOG_BYTES = 64 * 1024 * 1024;
   const eventBacklog = [];
+  let eventBacklogBytes = 0;
   const pendingPermissions = /* @__PURE__ */ new Map();
   let permSeq = 0;
   let published = false;
@@ -21418,8 +21455,14 @@ function runClaudeBroker(config) {
   const emitEvent = (event) => {
     if (client) write(client, { t: "event", event });
     else {
-      eventBacklog.push(JSON.stringify({ t: "event", event }) + "\n");
-      if (eventBacklog.length > 2e4) eventBacklog.shift();
+      const frame = JSON.stringify({ t: "event", event }) + "\n";
+      eventBacklog.push(frame);
+      eventBacklogBytes += Buffer.byteLength(frame);
+      while (eventBacklog.length > MAX_BACKLOG_FRAMES || eventBacklogBytes > MAX_BACKLOG_BYTES) {
+        const dropped = eventBacklog.shift();
+        if (dropped === void 0) break;
+        eventBacklogBytes -= Buffer.byteLength(dropped);
+      }
     }
   };
   const writeDiagnostic = config.diagnosticLogPath ? createClaudeBrokerDiagnosticWriter(config.diagnosticLogPath, { daemonPid: process.pid, generation }) : void 0;
@@ -21514,6 +21557,7 @@ function runClaudeBroker(config) {
     write(sock, { t: "hello", sessionId: handle.sessionId, generation });
     for (const [requestId, { request }] of pendingPermissions) write(sock, { t: "permission-request", requestId, request });
     while (eventBacklog.length) sock.write(eventBacklog.shift());
+    eventBacklogBytes = 0;
     let buf = "";
     sock.on("data", (chunk) => {
       buf += chunk;
@@ -21536,7 +21580,8 @@ function runClaudeBroker(config) {
           });
           void handle.send(message).catch((error) => {
             const detail = error instanceof Error ? error.message : String(error);
-            const diagnostic = { kind: "stderr", message: `input dropped, the agent never received it: ${detail}`, truncated: false };
+            const droppedId = typeof message?.id === "string" ? ` id=${message.id}` : "";
+            const diagnostic = { kind: "stderr", message: `${CLAUDE_INPUT_DROP_DIAGNOSTIC_PREFIX}:${droppedId} ${detail}`, truncated: false };
             writeDiagnostic?.(diagnostic);
             if (client) write(client, { t: "diagnostic", diagnostic });
           });