refactor(tabs): cut the surface to serve / list / suggest (v0.7.0)

[colevels]

v0.6.0 was the widest this ever got: eight tabs subcommands around a long-polling
bridge. The loop those commands existed to serve is three steps — the extension pushes
tabs, the agent reads them, the agent proposes a script the user accepts or denies — and
Claude Code's /loop already owns the pacing tabs watch was built for.

Breaking. Pin v0.6.0 if you depend on a command that disappears.

The surface

tabs serve           Start the local bridge the extension exports your tabs to
tabs list            Show the tabs the extension last sent, and recent answers
tabs suggest <file>  Propose a script, with a note they read before deciding

Removed: tabs watch, tabs push, tabs check, tabs history, tabs prompt, and the
--port / --out / --wait / --no-wait / --variant flags. docs,
login/whoami/logout and update are untouched; init now installs one skill
instead of two.

+1,709 / −4,022 lines, 38 → 32 source files.

What changed, and why

The bridge lost every long poll. Protocol 3 has five routes: POST /tabs,
POST /suggestion, GET /suggestion, POST /decision, GET /health. Gone are the three
long polls only the CLI ever issued (GET /tabs, GET /history, GET /decision) and the
protocol-1 /script pair — along with park()/wake(), the waiter sets, and the
idleTimeout: 0 workaround that existed only because Bun kills a 10s-idle request.

A shipped protocol-2 extension is unaffected. The four routes it actually calls are
unchanged, byte for byte. It reaches GET /suggestion first and only fell back to
/script on a 404, so it never notices that pair is gone.

suggest is fire-and-forget. Instead of holding a socket open across a human
decision, serve records the verdict in a five-entry ring inside tabs.json, and
tabs list reports it. That gives the agent memory of "denied, and why" which survives a
tab change and a restart of the bridge — and an undecided entry is the natural "don't
pile a second proposal on the first" signal.

tabs list prints the extension's own rendered snapshot rather than building a table
from raw tabs. It is the exact format the skill is written against, it carries the group
titles and windows the table dropped, and it keeps the CLI from reimplementing (and
drifting from) the extension's renderSnapshot. When the payload has no snapshot it says
so rather than growing a second renderer.

One skill instead of two. With push and check gone, a one-off request and a
standing watch are the same three steps, so tabbrew-tabs and tabbrew-auto had nothing
left to disagree about (they differed on whether to confirm a DEL in chat — the panel's
Accept card is the confirmation either way). init deletes an orphaned tabbrew-auto,
which would otherwise keep telling the agent to run a command that no longer exists.

Deleting check took the vendored simulator with it, which ends this repo's
obligation to mirror the extension executor's phase order. Only the grammar is shared now.

Bugs found and fixed during review

An adversarial review and a docs audit ran against the refactor. Four things they caught:

• The loop could wedge permanently. A suggestion queued but never claimed became
  undeliverable after a bridge restart (pending is RAM-only) yet stayed PENDING
  forever — and the skill stops on PENDING. One Ctrl+C ended the watch for the
  session. serve now closes those out at startup, using a persisted claimedAt so it
  distinguishes "never delivered" from "may still be on screen" as a fact, not a guess.
• --out moved only the writer. list and suggest kept reading
  config.serve.outPath, so serve --out ./here.json left them silently reporting a
  stale default file — the same reader/writer split --port was removed for. Flag
  removed; TABBREW_TABS_PATH moves all three.
• Concurrent writes could roll each other back. The extension POSTs /tabs while the
  CLI POSTs /suggestion; both raced a rename. Writes are serialized now.
• tabs-history.jsonl was orphaned. Removing the writer and tabs history --clear
  left upgrading users with a file of closed-tab titles and URLs and no supported way to
  delete it. serve now deletes it on startup and says so.

Verification

typecheck + test + build pass. Beyond that, the accept/deny round trip only exists
across the browser boundary, so it was driven by hand with curl standing in for the
extension:

• full loop: post tabs → suggest → claim → deny with a reason → re-post tabs → tabs list
  shows DENIED with the reason; same for accept, and the ring survives a serve restart
• restart reconciliation both ways: unclaimed becomes STALE and unblocks the loop;
  claimed stays PENDING and a later Accept still lands as ACCEPTED
• 50 concurrent writers land version 26 of 26, ring cap holds, file stays parseable
• garbage tolerance: a ring containing null, a bare string and a field-less object
  renders without crashing; a v0.6.0 tabs.json with no suggestions key still works
• forbidden_host on a spoofed Host:; tabs.json written 0600
• init install / re-run / uninstall, including deletion of a planted tabbrew-auto
• docs/commands.html checked in Chrome at 1280px and 390px — tags balance, no console
  errors, no horizontal overflow, card counts match the reach legend

Not in this PR

The extension side. Both the tab uplink and the suggestion poll are gated on
step === 'cli' && cliPhase === 'waiting' in OrganizeFlow.tsx, and Accept lands on
step: 'done' — so a /loop gets one round before it is talking to nobody. Gating on
autoMode instead is the fix, in colevels/tabbrew. No lockstep needed: the shipped
extension works against this bridge unchanged.

The one interim regression is the developer-mode Connect panel, which polls
GET /script. Nothing fills that queue once tabs push is gone, so it goes with it.

🤖 Generated with Claude Code