thinkpool-pair 0.7.327 → 0.7.330

package/README.md

@@ -1,235 +1,272 @@
-# thinkpool-pair — the ThinkPool Code bridge
+# `thinkpool-pair`
 
-Pair two people on one live **coding agent** — running **any model you choose**
-(Claude, GPT, Gemini, Llama, or a local model) — in a ThinkPool Code room. Both
-people see the live stream and can both drive it, no copy/paste.
+`thinkpool-pair` connects coding agents running on a machine you control to a
+Thinkpool Code room. Both people in the room can watch and steer the visible
+agent lanes from a browser or phone.
 
-> A web page can't read your terminal directly (browser security). This tiny
-> helper is the bridge: it runs CLIs in PTYs and streams them to the room.
+The bridge makes outbound connections to Thinkpool’s Supabase project. It does
+not require an inbound port, tunnel, or public IP.
 
-> **Don't want it tied to your laptop?** Run this same bridge on an always-on box
-> you control (a cheap VM, a home server, a Raspberry Pi) so the agent stays live
-> with your laptop closed. It's outbound-only — no ports, no public IP. See
-> [**Run it in the cloud**](#run-it-in-the-cloud-remote-host--vm--container) below.
+## Requirements
 
-## Run it (one command)
+- Node.js 18 or newer
+- A Thinkpool account and Code session
+- At least one supported runtime available on the host:
+  - Claude
+  - Codex
+  - Hermes
+- The provider login or API credentials required by that runtime
+
+## Start the bridge
+
+Run the launcher from the project directory the agents should use:
 
 ```bash
-cd bridge && npm i        # one-time (builds node-pty — needs Xcode CLT / build-essential)
-node bridge.mjs <ROOM>    # picks an installed agent, shared into room <ROOM>
+npx thinkpool-pair@latest
 ```
 
-- `<ROOM>` is the 5-char room code from the ThinkPool Code web UI (`/code`).
-- Share a specific CLI: `node bridge.mjs <ROOM> -- aider`  /  `… -- bash`.
-- Pure relay (no local terminal): `node bridge.mjs <ROOM> --headless`.
-
-## Keep it stable (auto-restart)
-
-The bridge self-heals at three levels — all cross-platform (macOS / Linux / Windows):
-
-- **`--supervise`** — wrap it so a crash respawns automatically (exponential
-  backoff). Zero-dependency. Combined with session restore (below), a crash is
-  invisible — the room reconnects and the Claude session resumes where it left off.
-  ```bash
-  npx thinkpool-pair@latest <ROOM> --supervise -- claude
-  ```
-- **Boot-persistent service** — survive reboot/logout too. Installs the right
-  native service for your OS (launchd on macOS, systemd `--user` on Linux, a
-  Startup-folder script on Windows):
-  ```bash
-  npx thinkpool-pair@latest install-service <ROOM> -- claude   # set and forget
-  npx thinkpool-pair@latest uninstall-service <ROOM>           # remove it
-  ```
-  The service runs `npx thinkpool-pair@latest`, so it **auto-updates** — new
-  versions apply on the next restart, no re-install. (Linux: run
-  `loginctl enable-linger $USER` once to keep it running after logout.)
-- **Watchdog** — if the realtime channel wedges for >60s, the bridge exits so the
-  supervisor/service restarts a clean process. Brief network blips reconnect on
-  their own.
-
-Structured Claude sessions persist their scrollback + session id to
-`~/.thinkpool-pair/<ROOM>/` and **resume on restart** (live context if recent),
-so none of the above loses your place.
-
-### Codex App Server driver
-
-Structured Codex lanes use the long-lived App Server transport (streaming prose,
-mid-turn steering, shared approval and question cards, and native image inputs)
-when the installed Codex CLI is in the bridge's tested protocol range. To force
-the stable `codex exec --json` fallback, set the kill switch before starting the
-bridge:
-
-```bash
-export TP_CODEX_APP_SERVER=0
-```
-
-The bridge performs the initialize handshake before creating a thread and falls
-back to `codex exec` when App Server is disabled, outside the tested version
-range, or cannot initialize before a turn. It never retries a prompt via the
-fallback after `turn/start` has been accepted, preventing duplicate work.
-
-Your first agent runs **attached** — use it exactly like your normal terminal,
-every byte mirrors to the web. The web's **"+ New terminal"** spawns additional
-**headless** terminals here (same directory, same env), driven entirely from
-the room. One bridge, many terminals.
-
-### Built-in viewport capture
-
-Structured Claude and Codex lanes have bridge-owned visual QA tools, even when
-their own sandbox cannot bind localhost or launch Chrome:
-
-- `preview_start` serves a built directory inside that lane's workspace
-  (`dist` by default; it must contain `index.html`).
-- `preview_capture` returns exact desktop (1440×900) and mobile (390×844)
-  screenshots to the agent as verification evidence. It creates no transcript
-  artifact by default. Pass `card: true` only for an intentional user-facing
-  mockup/Design deliverable; a settled complete pair is then queued after the
-  agent's final response. Loading, empty, and public-auth fallback shells are
-  rejected before a card can be created.
-- `preview_inspect` returns rendered DOM text, document size, and optional
-  selector geometry at either viewport.
-- `preview_stop` releases the preview port.
-
-The bridge launches the host's Chrome/Chromium lazily. Set `TP_BROWSER_PATH`
-if it is installed somewhere non-standard. Preview files are read-only, roots
-cannot escape the lane workspace (including through symlinks), and page network
-requests are restricted to the preview server's exact loopback origin. The
-tools never execute a caller-supplied command or open an arbitrary URL.
-
-## Run it in the cloud (remote host / VM / container)
-
-The bridge connects **outbound** to Supabase — no inbound ports, no public IP, no
-tunnel. So a cloud VM, container, devcontainer, or remote dev box can stream its
-Claude Code into the room exactly like a laptop. Run the same command there:
-
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...                  # headless auth (no Keychain login)
-cd /path/to/your/repo
-npx thinkpool-pair@latest <ROOM> -- claude           # structured Claude, no TTY needed
-```
-
-- **Auth** — two ways to sign in on a box with no browser. Both are your own
-  account on your own hardware, so both are fine:
-  - **API key** — `export ANTHROPIC_API_KEY=sk-ant-...` from your Anthropic
-    Console. Simplest, pay-per-token, cleanest cost tracking.
-  - **Your Claude subscription** — a server has no browser, so mint a long-lived
-    token *on a machine that does*: run `claude setup-token` there (prints a
-    ~1-year `CLAUDE_CODE_OAUTH_TOKEN`), then `export CLAUDE_CODE_OAUTH_TOKEN=...`
-    on the box. Uses your existing Pro/Max plan — no per-token bill.
-
-  The Agent SDK reads either one automatically and runs its bundled `claude`, so
-  you don't need Claude Code installed separately. (Note: this is *you* running
-  *your* login on *your* machine. Handing a subscription token to a third-party
-  host to run for you is what Anthropic's terms forbid — that's why a future
-  "we host it for you" option would require an API key, not your subscription.)
-- **Use `@latest`**: a bare `npx thinkpool-pair` reuses npx's local cache and can
-  run a stale version across restarts. `@latest` (and the service below) always
-  re-resolve the newest publish.
-- **No TTY required**: the agent picker auto-selects and raw-mode is skipped when
-  there's no terminal, so it runs fine under CI / a service / `nohup`.
-- **Always-on + auto-update**: `npx thinkpool-pair@latest install-service <ROOM> -- claude`
-  installs a systemd `--user` unit (auto-restart + boot-persistent). The bridge
-  polls npm for new publishes and **self-restarts at the next idle moment** into
-  the new version — the structured session resumes, so an away/unattended box
-  upgrades itself with nobody losing their place. On a server, also run
-  `loginctl enable-linger $USER` so it survives logout.
-  Tune with `THINKPOOL_PAIR_UPDATE_INTERVAL` (poll seconds, default 1800) and
-  `THINKPOOL_PAIR_UPDATE_IDLE` (idle seconds before restart, default 90). Live
-  auto-update applies to the launchd/systemd service tiers; bare `--supervise`
-  respawns the same version, so it updates only on the next manual/boot restart.
-- **Security**: anyone with the room code can drive the agent (shell-trust by
-  design) — on a server that's a real shell, so treat the room code like a secret.
-
-## How it works
-
-`bridge.mjs` ⇄ **Supabase realtime** (`tpcode:<ROOM>`) ⇄ web `xterm`:
-- `bridge` — announce: installed agents + live terminals.
-- `pty-out` — terminal bytes (base64, per-terminal) → web clients render them.
-- `pty-in` — keystrokes/prompts from the web → written to that terminal's PTY.
-- `term-open` / `term-close` / `term-exit` — web-driven terminal lifecycle.
-- `replay-request` / `pty-replay` — each terminal keeps a rolling ~120 KB
-  scrollback buffer for live recovery. Thinkpool also stores the cleaned reader
-  transcript and room events so members can reopen the room. It does not store
-  a copy of the repository or the raw PTY byte stream.
-- `resize` — web viewport size → headless PTYs only (the attached terminal
-  follows your own TTY).
-
-## Inspect the privacy boundary
-
-Run a local report before pairing a repository:
+The launcher shows the linked account, detected runtimes, current directory,
+and background-service state. On first use it asks to link the machine in a
+browser. Then choose one of:
+
+- **Serve all my sessions** — runs in the current terminal until `Ctrl-C`.
+- **Always-on background service** — starts at login/reboot and restarts after a
+  crash. The normal install is pinned to the confirmed package version; use the
+  launcher’s **Restart & update bridge** action when a new version should land.
+
+Back in the room, open the runtime/model you want for each terminal.
+
+## Account and service commands
+
+Link the machine without opening the full launcher:
 
 ```bash
-npx thinkpool-pair@latest privacy-report
+npx thinkpool-pair@latest login
+```
+
+Install or remove the account-wide background service:
+
+```bash
+npx thinkpool-pair@latest install-service
+npx thinkpool-pair@latest restart-service
+npx thinkpool-pair@latest uninstall-service
+```
+
+`install-service` is pinned by default so a later bad npm publish cannot
+silently replace a working unattended bridge. Opt into tracking `@latest` only
+when that trade-off is intentional:
+
+```bash
+npx thinkpool-pair@latest install-service --auto-update
 ```
 
-It lists the project directories configured for this bridge, the local records
-present under `~/.thinkpool-pair`, known outbound service domains, what
-Thinkpool stores remotely, and the limits of the report. It never prints a
-provider key, refresh token, or bridge private key.
+Service implementation by platform:
 
-## Run any model
+- macOS: LaunchAgent
+- Linux: systemd user service; run `loginctl enable-linger "$USER"` once if it
+  must survive logout
+- Windows: Startup-folder command file
 
-ThinkPool Code runs **any model you choose** — not just Anthropic. The agent
-talks the Anthropic Messages API, so you point it at any endpoint that speaks
-that format:
+On Windows the startup entry launches at login; update it from the launcher and
+relaunch the bridge window to apply the new version.
 
-- **Anthropic-compatible endpoints directly** — Z.ai GLM, Moonshot Kimi, OpenRouter, your own proxy.
-- **Any other model via a translating gateway** — put **LiteLLM** (or a proxy of
-  your own) in front and run **GPT, Gemini, Llama, DeepSeek, or a local model**;
-  it presents the Anthropic Messages API while calling whatever you pick.
+## Project directories
 
-> OpenRouter is the exception worth knowing: its `/v1/messages` surface is a
-> pass-through for **Anthropic models only**. Per OpenRouter's own docs, "Claude
-> Code expects Anthropic request semantics, so non-Anthropic models aren't
-> supported through the native endpoint" — and this bridge spawns the `claude`
-> CLI. To reach a non-Anthropic model, use a translating gateway (LiteLLM),
-> not OpenRouter's Anthropic endpoint.
+The account bridge serves sessions from their bound project directories. Set a
+default for new/unbound sessions:
 
 ```bash
-npx thinkpool-pair@latest provider custom --base <url> --token <key> [--model <name>]
+npx thinkpool-pair@latest set-default-dir /path/to/project
 ```
 
-Common base urls (the agent appends `/v1/messages`):
+Bind one room explicitly when needed:
 
-| Provider / gateway | Base url                          | Models                       |
-|--------------------|-----------------------------------|------------------------------|
-| Z.ai GLM           | `https://api.z.ai/api/anthropic`  | GLM                          |
-| Moonshot Kimi      | `https://api.moonshot.ai/anthropic` | Kimi                       |
-| OpenRouter         | `https://openrouter.ai/api`       | Anthropic models only        |
-| LiteLLM (your own) | `http://localhost:4000`           | GPT, Gemini, Llama, local, … |
+```bash
+npx thinkpool-pair@latest bind <ROOM> /path/to/project
+```
+
+Room codes are treated as secrets because room members can drive agents that
+have access to the bound project and the host permissions granted to that lane.
 
-> The endpoint must serve the Anthropic Messages API (`/v1/messages`). A raw
-> OpenAI-style `/v1/chat/completions` won't work directly — that's exactly what a
-> gateway is for. Avoid LiteLLM 1.82.7 / 1.82.8 (compromised releases); use a
-> current version.
+## Runtimes and providers
 
-Show the current provider (`npx thinkpool-pair@latest provider`), or reset back to your
-regular Claude login:
+| Runtime | Authentication/provider behavior |
+|---|---|
+| Claude | Uses the host’s normal Anthropic login by default. A registered Anthropic-compatible provider can be selected for a lane. |
+| Codex | Uses the host’s Codex/OpenAI login. Custom bridge providers are not wired to Codex lanes. |
+| Hermes | Uses an isolated Thinkpool ACP profile. Set it up explicitly before the first Hermes lane. |
+
+The launcher’s **Settings → Provider** flow configures the host default for
+Claude-compatible lanes. The equivalent CLI commands are:
 
 ```bash
+npx thinkpool-pair@latest provider
 npx thinkpool-pair@latest provider anthropic
+npx thinkpool-pair@latest provider custom --base <url> --token <key> --model <id>
 ```
 
-Provider config is stored in `~/.thinkpool-pair/provider.json` (mode 0600) and
-applies to every bridge on the machine. Restart the bridge (or its launchd
-service) after changing it — the choice is read once at startup.
+The custom endpoint must implement the Anthropic Messages API. A raw
+OpenAI-compatible chat-completions endpoint is not enough; place a translating
+gateway in front of it or use the runtime that natively owns that provider.
 
-### Context meter for non-Claude models
+Set up an isolated Hermes profile with one of:
 
-The context-usage meter (`ctx N%` in the room) is computed by the Agent SDK from
-the model id it thinks it's talking to — for a non-Claude model bridged in over
-an Anthropic-compatible endpoint, that assumed window is wrong, so the meter can
-run past 100%. The bridge corrects it for common models automatically (GLM-4.5/4.6,
-DeepSeek V3.x, Kimi K2, Qwen3-Coder — matched by model id).
+```bash
+npx thinkpool-pair@latest setup-hermes --clone
+npx thinkpool-pair@latest setup-hermes --clean
+```
+
+`--clone` copies the active Hermes provider/configuration into the isolated
+profile. `--clean` creates the isolation boundary without copying credentials.
+
+## Direct single-room mode
+
+The account-wide launcher is the normal path. A direct room process is still
+available for debugging or a deliberately single-room host:
+
+```bash
+npx thinkpool-pair@latest <ROOM> -- claude
+npx thinkpool-pair@latest <ROOM> -- codex
+npx thinkpool-pair@latest <ROOM> -- hermes
+```
 
-For any model not in that list, set the real window explicitly per bridge:
+Add `--headless` when the process should be driven only from the room. Direct
+room services use the same command with the room code:
 
 ```bash
-export TP_CONTEXT_MAX=131072   # your model's context window, in tokens
+npx thinkpool-pair@latest install-service <ROOM> -- claude
+npx thinkpool-pair@latest uninstall-service <ROOM>
 ```
 
-`TP_CONTEXT_MAX` overrides the built-in map (and applies even to Claude ids if
-you set it). Unset it to fall back to the automatic correction.
+## Cloud or always-on host
+
+The bridge can run on a VM, dev box, home server, or container because its room
+connection is outbound-only. Use the same launcher/service commands and provide
+the runtime’s headless credentials through the host’s secret manager.
+
+For Claude, either an Anthropic API key or a valid Claude Code OAuth token can
+authenticate the runtime. Treat subscription/OAuth tokens as personal secrets;
+do not hand them to a third-party host.
+
+## What crosses the boundary
+
+The bridge and web app deliberately split responsibility:
+
+- Agent processes, repository access, provider credentials, and raw terminal
+  bytes remain on the bridge machine.
+- Thinkpool relays room events and terminal output to authorized room members.
+- Thinkpool stores the cleaned reader transcript and room events so members can
+  reopen the room.
+- Thinkpool does not store a copy of the repository or a second copy of the raw
+  PTY byte stream.
+- Voice dictation is an application API path and uses the configured
+  transcription service; it is not a local-only bridge operation.
+
+Inspect the host-side boundary before pairing a sensitive repository:
+
+```bash
+npx thinkpool-pair@latest privacy-report
+```
+
+The report lists configured project directories, local bridge records, known
+outbound domains, remote storage categories, and the report’s limits. It does
+not print provider keys, refresh tokens, or bridge private keys.
+
+Structured session state is stored below `~/.thinkpool-pair/` so an agent lane
+can resume after a bridge restart. Protect that directory like other local
+developer credentials and session state.
+
+## Visual verification tools
+
+Structured Claude and Codex lanes can use bridge-owned preview tools even when
+their own sandbox cannot bind a port or launch a browser:
+
+- `preview_start` serves a built directory inside the lane worktree.
+- `preview_capture` records exact desktop and mobile renders.
+- `preview_inspect` reads rendered DOM text and geometry.
+- `preview_stop` releases the preview server.
+
+Preview roots are read-only, cannot escape the lane worktree, and accept only
+the preview server’s loopback origin for page requests.
+
+## Optional bridge environment variables
+
+| Variable | Purpose |
+|---|---|
+| `TP_NAME` | Label this bridge in the room |
+| `TP_PAIR_ROOT` | Override the local state directory |
+| `TP_SUPABASE_URL` / `TP_SUPABASE_ANON` | Override the built-in Thinkpool project endpoint/public key |
+| `TP_ANTHROPIC_BASE_URL` / `TP_ANTHROPIC_AUTH_TOKEN` / `TP_ANTHROPIC_MODEL` | Override the Claude-compatible provider without writing provider config |
+| `TP_CONTEXT_MAX` | Override the context-window size used by the room meter |
+| `TP_BROWSER_PATH` | Point preview capture at a non-standard Chrome/Chromium binary |
+| `TP_FLOW_OFF=1` | Disable Flow dispatch on this bridge |
+| `TP_SPAWN_OFF=1` | Disable agent-spawned worker lanes |
+| `TP_PAIRBUS_OFF=1` | Disable the paired-room bus |
+| `TP_CROSSROOM_OFF=1` | Disable cross-session reach |
+
+Provider and account configuration written by the launcher is preferred for a
+managed service because shell startup files are not guaranteed to be sourced.
+
+## Troubleshooting
+
+### The room cannot see the bridge
+
+Run the launcher and check its account/runtime/service header. If the account
+link is missing or expired, rerun:
+
+```bash
+npx thinkpool-pair@latest login
+```
+
+### A service is installed but not serving
+
+Use the launcher’s restart/update action or:
+
+```bash
+npx thinkpool-pair@latest restart-service
+```
+
+The install command prints the platform-specific log directory. Inspect that
+log before reinstalling; repeated installation can hide the original failure.
+
+### No runtimes are available
+
+Install/sign in to Claude, Codex, or Hermes on the host, then restart the
+launcher. Runtime availability is detected from the host; the web room cannot
+install a missing CLI for you.
+
+### A custom model fails immediately
+
+Check that the endpoint implements Anthropic Messages semantics and that the
+model ID exists on that provider. Codex lanes ignore the bridge’s custom Claude
+provider configuration and use the Codex/OpenAI login.
+
+### Preview capture cannot find Chrome
+
+Install Chrome/Chromium on the bridge host or set `TP_BROWSER_PATH` to its
+executable.
+
+## Develop the bridge package
+
+From the repository root:
+
+```bash
+npm --prefix bridge ci
+npm run test:bridge
+node bridge/test-packed-artifact.mjs
+```
+
+Run the checked-out launcher with:
+
+```bash
+node bridge/bridge.mjs
+```
+
+Publishing is separate from the web-app deploy:
+
+```bash
+npm --prefix bridge run release
+```
 
-Public anon creds are embedded (the same ones the web app ships). Override with
-`TP_SUPABASE_URL` / `TP_SUPABASE_ANON` if needed. Set `TP_NAME` to label yourself.
+The release command has external side effects and requires npm publish
+authority. Do not use it as a local verification command.

package/bridge-service.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# bridge/bridge-service.sh — install thinkpool-pair as an AUTO-UPDATING launchd
+# service for a room, with a fast update poll so a new `npm publish` lands in the
+# room within ~1 min of an idle moment (no manual restart, no re-install).
+#
+# The stock `thinkpool-pair install-service <ROOM>` already runs under launchd
+# KeepAlive with `npx -y thinkpool-pair@latest` (so each restart fetches the newest
+# publish) and sets THINKPOOL_PAIR_AUTOUPDATE=1 — but it leaves the poll interval at
+# the 30-min default. This wrapper installs it, then injects the faster poll/idle
+# knobs into the generated LaunchAgent plist and reloads it.
+#
+#   Usage:  bash bridge/bridge-service.sh <ROOM> [-- <extra bridge args>]
+#   e.g.    bash bridge/bridge-service.sh P6O6I            # default: --headless --auto=claude
+#           bash bridge/bridge-service.sh P6O6I -- --headless --auto=claude
+#   Env:    TP_UPDATE_INTERVAL (default 60)   registry poll seconds
+#           TP_UPDATE_IDLE     (default 20)   idle seconds before an update restart
+#           TP_FORCE=1                        skip the "bare bridge already running" guard
+#   Remove: npx thinkpool-pair@latest uninstall-service <ROOM>
+set -euo pipefail
+
+ROOM_RAW="${1:-}"
+[ -n "$ROOM_RAW" ] && [ "${ROOM_RAW#-}" = "$ROOM_RAW" ] || { echo "usage: bash bridge/bridge-service.sh <ROOM> [-- <extra bridge args>]"; exit 1; }
+ROOM="$(printf '%s' "$ROOM_RAW" | tr '[:lower:]' '[:upper:]')"
+shift || true
+# Everything after a literal `--` is forwarded to the bridge; default to the
+# headless auto-claude invocation the rooms run interactively today.
+TAIL=()
+if [ "${1:-}" = "--" ]; then shift; TAIL=("$@"); else TAIL=(--headless --auto=claude); fi
+
+INTERVAL="${TP_UPDATE_INTERVAL:-60}"
+IDLE="${TP_UPDATE_IDLE:-20}"
+PLIST="$HOME/Library/LaunchAgents/io.thinkpool.pair.$(printf '%s' "$ROOM" | tr '[:upper:]' '[:lower:]').plist"
+
+[ "$(uname)" = "Darwin" ] || { echo "✗ this wrapper is macOS/launchd only (Linux: use systemd via 'npx thinkpool-pair@latest install-service')"; exit 1; }
+
+# Guard: a bare (foreground) bridge for this room would fight the service —
+# two relays on one realtime channel duplicate everything. Stop it first.
+# NOTE: macOS pgrep is POSIX-ERE — no \b. Match "bridge.mjs <ROOM>" with the room
+# delimited by whitespace or end-of-arg. (A \b guard here once failed silently and
+# serviced the live room, restarting its bridge — don't reintroduce it.)
+BRIDGE_RE="bridge\.mjs[[:space:]]+${ROOM}([[:space:]]|\$)"
+if [ -z "${TP_FORCE:-}" ] && pgrep -f "$BRIDGE_RE" >/dev/null 2>&1; then
+  echo "✗ a bare bridge is already running for ${ROOM} (pid $(pgrep -f "$BRIDGE_RE" | tr '\n' ' '))."
+  echo "  Stop it first (close its terminal / kill it), then re-run — or TP_FORCE=1 to override."
+  echo "  NOTE: if ${ROOM} is hosting the Claude session you're talking to RIGHT NOW, servicing it restarts the bridge and drops that chat."
+  exit 2
+fi
+
+echo "◆ installing auto-updating service for ${ROOM} (npx thinkpool-pair@latest ${TAIL[*]})…"
+npx -y thinkpool-pair@latest install-service "$ROOM" -- "${TAIL[@]}"
+
+[ -f "$PLIST" ] || { echo "✗ expected plist not found at $PLIST — install may have failed"; exit 3; }
+
+# Inject the fast-poll knobs into EnvironmentVariables (Add, or Set if present).
+pb() { /usr/libexec/PlistBuddy -c "$1" "$PLIST" >/dev/null 2>&1; }
+pb "Add :EnvironmentVariables:THINKPOOL_PAIR_UPDATE_INTERVAL string ${INTERVAL}" || pb "Set :EnvironmentVariables:THINKPOOL_PAIR_UPDATE_INTERVAL ${INTERVAL}"
+pb "Add :EnvironmentVariables:THINKPOOL_PAIR_UPDATE_IDLE string ${IDLE}"         || pb "Set :EnvironmentVariables:THINKPOOL_PAIR_UPDATE_IDLE ${IDLE}"
+
+# Reload so the new env takes effect immediately.
+launchctl unload "$PLIST" 2>/dev/null || true
+launchctl load  "$PLIST"
+
+echo "✓ ${ROOM} is now a launchd service:"
+echo "    • tracks thinkpool-pair@latest, polls npm every ${INTERVAL}s, self-restarts at the next idle ≥${IDLE}s"
+echo "    • plist: $PLIST"
+echo "    • logs:  ~/.thinkpool-pair/${ROOM}.log"
+echo "    • remove: npx thinkpool-pair@latest uninstall-service ${ROOM}"

package/bridge.mjs

@@ -117,7 +117,7 @@ const flowRedispatch = new Map()
 // wave BEFORE overrun. Lives bridge-side because waves dispatch across separate
 // broadcasts; without persistent state the cap can never bite.
 const flowBudgets = new Map()
-import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, SPAWN, CROSSROOM, CROSSROOM_BUS, formatPairRoster, crossRoomPostDecision, formatRoomNow, formatClosableHint, closeLaneDecision, laneBusyOf, laneStatusOf, settleLaneBusy, nativeClaudeFallbackHint, buildDispatchPreview, authorizeDirectDispatch } from './cross-terminal.mjs'
+import { formatPeek, PEEK, readTerminalBudgetDecision, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, SPAWN, CROSSROOM, CROSSROOM_BUS, formatPairRoster, crossRoomPostDecision, formatRoomNow, formatClosableHint, closeLaneDecision, laneBusyOf, laneStatusOf, settleLaneBusy, nativeClaudeFallbackHint, buildDispatchPreview, authorizeDirectDispatch } from './cross-terminal.mjs'
 import { createStandalonePairResponder, standalonePairIdentity } from './direct-pair-room.mjs'
 import { dispatchPendingRecap, recoverInterruptedTurn, recoverMissingResumeOnce, sendInterruptedContinue, shouldAttemptNativeResume, supersedeInterruptedResume } from './interrupted-resume.mjs'
 import { supersedeDispatchLease } from './dispatch-lease.mjs'
@@ -941,7 +941,7 @@ function recordCodeUsage (model, usage, provider) {
 let _presence = null
 const trackPresence = (payload) => { (_presence ||= makeThrottledTrack(channel, { minMs: 5000 }))(payload) }
 const channel = supabase.channel(`tpcode:${room}`, {
-  config: { broadcast: { self: false }, presence: { key: `bridge:${name}` } },
+  config: { private: true, broadcast: { self: false }, presence: { key: `bridge:${name}` } },
 })
 
 // Thinkpool Flow rides its OWN topic, separate from the room's primary tpcode channel.
@@ -953,13 +953,13 @@ const flowChannel = supabase.channel(`tpflow:${room}`, {
   config: { broadcast: { self: false } },
 })
 
-// Source-changing Design Mode control never rides the public tpcode topic.
+// Source-changing Design Mode control stays isolated from the primary room bus.
 // Membership RLS on realtime.messages gates join, receive, and send.
 const designChannel = supabase.channel(`tpdesign:${room}`, {
   config: { private: true, broadcast: { self: false } },
 })
 
-// Host-changing room commands are isolated from the public collaboration topic.
+// Host-changing room commands are isolated from the primary collaboration topic.
 // Realtime RLS admits current room members and authenticates every send/receive.
 const controlChannel = supabase.channel(`tpcontrol:${room}`, {
   config: { private: true, broadcast: { self: false } },
@@ -1463,7 +1463,7 @@ async function receiveCrossRoomPost({ fromRoom, fromHost, fromTerminalName, text
   if (decision !== 'allow') return { error: `The people in room ${room} declined the incoming task from ${fromLabel}.` }
   // Injected turn: one room-hop deep, fresh in-room budgets (the loop-breaker reset
   // point is code-turn — a real human turn — which this is NOT, so the deeper hop sticks).
-  te.roomHop = 1; te.hop = (te.hop || 0) + 1; te.peekCount = 0; te.postCount = 0; te.pairPeekCount = 0; te.crossRoomPostCount = 0
+  te.roomHop = 1; te.hop = (te.hop || 0) + 1; te.peekCount = 0; te.peekRosterCount = 0; te.postCount = 0; te.pairPeekCount = 0; te.crossRoomPostCount = 0
   const msg = `[From: room ${fromLabel} — relayed via the ThinkPool cross-room Ensemble, approved by a person in this room]\n${body}`
   const evt = { kind: 'you', text: msg, by: `room ${fromRoom}`, crosspost: true, relaySourceName: String(fromTerminalName || '').trim().slice(0, 80) || undefined }
   autoNameTerminal(targetId, body)
@@ -2581,18 +2581,29 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       ...createViewportTools({ tool, z, manager: entry.viewport }),
       tool(
         'read_terminal',
-        'Read-only view of ANOTHER terminal in this ThinkPool Code room (a sibling agent or a shell the people are using). Call with no arguments to list every open terminal with busy/idle state, last-action age, and any STUCK/BLOCKED flag; call with `terminal` (a ref, id, or command from that list) to read its recent activity. It never changes another terminal — reading only. Use the one-read roster to identify a lane that needs attention before opening its transcript.',
+        'Read-only view of ANOTHER terminal in this ThinkPool Code room (a sibling agent or a shell the people are using). The current ROOM NOW snapshot is the default roster. Call with no arguments only when that snapshot is missing or truncated; this optional full-roster lookup has its own one-call allowance. Call with `terminal` (a ref, id, name, or command) only when that lane’s detailed activity is needed. Targeted transcript reads have a separate bounded allowance: never poll, collect each finished owned worker once, then close it immediately.',
         {
           terminal: z.string().optional().describe('ref, id, or command of the terminal to read; omit to list the open terminals'),
           lines: z.number().int().positive().max(PEEK.maxLines).optional().describe(`how many recent lines to return (default ${PEEK.defaultLines})`),
         },
         async (args) => {
-          entry.peekCount = (entry.peekCount || 0) + 1
-          if (entry.peekCount > PEEK.perTurnCap) {
-            return { content: [{ type: 'text', text: `Cross-terminal read limit reached for this turn (${PEEK.perTurnCap}). Continue with what you have, or ask the people in the room.` }] }
-          }
           const sib = siblingsOf({ selfId: id, sessions, terms, names: termNames })
           const target = args?.terminal ? resolveSibling(sib, args.terminal) : null
+          // A malformed/stale ref is a no-op, so reject it before spending either
+          // allowance. Discovery and transcript reads are metered independently:
+          // ROOM NOW makes the roster optional, while targeted reads stay available
+          // for actual worker collection and the final review.
+          if (args?.terminal && !target) {
+            return { content: [{ type: 'text', text: formatPeek({ selfId: id, sessions, terms, names: termNames, terminal: args.terminal, lines: args?.lines }) }] }
+          }
+          const budget = readTerminalBudgetDecision({
+            targeted: !!args?.terminal,
+            targetedCount: entry.peekCount,
+            rosterCount: entry.peekRosterCount,
+          })
+          entry.peekCount = budget.targetedCount
+          entry.peekRosterCount = budget.rosterCount
+          if (!budget.ok) return { content: [{ type: 'text', text: budget.reason }] }
           const targetEntry = target?.kind === 'agent' ? sessions.get(target.id) : null
           const text = formatPeek({ selfId: id, sessions, terms, names: termNames, terminal: args?.terminal, lines: args?.lines })
             + nativeClaudeFallbackHint({ parentRuntime: entry.runtime, parentModels: entry.models, targetRuntime: targetEntry?.runtime, targetLog: targetEntry?.log })
@@ -2705,6 +2716,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           // The injected turn starts fresh budgets, one hop deeper (loop breaker).
           te.hop = (entry.hop || 0) + 1
           te.peekCount = 0
+          te.peekRosterCount = 0
           te.postCount = 0
           // Echo the injected prompt into the TARGET lane so both people see what
           // arrived (rides the existing code-event 'you' path — no new topic).
@@ -2762,7 +2774,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
             if (args?.name) { delete termNames[newId]; saveNames(room, termNames) }
             return okText('Could not open the main conductor terminal — the machine terminal cap may have just been reached.')
           }
-          conductor.peekCount = 0; conductor.postCount = 0; conductor.spawnTimes = []
+          conductor.peekCount = 0; conductor.peekRosterCount = 0; conductor.postCount = 0; conductor.spawnTimes = []
           announce()
           const msg = `[Task from main terminal ${fromRef}'s agent — opened as an independent MAIN CASCADE CONDUCTOR terminal, not an Ensemble child]\n${String(args.task).trim()}`
           const evt = { kind: 'you', text: msg, by: `main terminal ${fromRef} (agent)`, crosspost: true, relaySourceName: termNames[id] || undefined }
@@ -2837,7 +2849,10 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
                 resolvedModel: resolved.model,
               },
             })
-          } catch { return okText('Dispatch preview could not be built safely. No lane was created.') }
+          } catch (error) {
+            process.stderr.write(`\n  ${A.red}✗ dispatch preview rejected — ${error?.message || error}${A.rst}\n`)
+            return okText('Dispatch preview could not be built safely. No lane was created.')
+          }
           const currentNow = Date.now()
           const current = dispatchContext(currentNow)
           const authorization = authorizeDirectDispatch({
@@ -2880,7 +2895,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           openStructured({ id: newId, runtime: resolved.runtime, model: resolved.model, provider: resolved.provider, mode: effectiveArgs.mode, sliceType: args?.sliceType, flowReviewTargets: manualReviewSnapshots.map((item) => item.taskKey), flowReviewSnapshots: manualReviewSnapshots, spawnedBy: id, spawnDepth: childSpawnDepth, cascadeRole: 'worker', hop: childHop })
           const ne = sessions.get(newId)
           if (!ne) { if (args?.name) { delete termNames[newId]; saveNames(room, termNames) } return okText('Could not open a new lane — the terminal cap may have just been reached. Close one and retry.') }
-          ne.peekCount = 0; ne.postCount = 0; ne.spawnTimes = []
+          ne.peekCount = 0; ne.peekRosterCount = 0; ne.postCount = 0; ne.spawnTimes = []
           announce()          // (defensive) ensure the web renders the new tab live
           if (args?.task) {
             // The user-visible relay reinforces (but never defines) the structural
@@ -4244,6 +4259,7 @@ channel
     // through here, so its deeper hop level + spent budget stick until a person
     // speaks again.
     s.peekCount = 0
+    s.peekRosterCount = 0
     s.postCount = 0
     s.pairPeekCount = 0   // cross-room read budget resets with the in-room ones (Tier 1)
     s.crossRoomPostCount = 0   // Tier 3 cross-room post budget resets on a real human turn
@@ -4508,7 +4524,7 @@ channel
     const s = payload?.term && sessions.get(payload.term)
     const p = s && payload.id && s.pending.get(payload.id)
     if (!p) return
-    // `tpcode` is a public transport. Treat the frame only as a wake-up hint and
+    // `tpcode` is membership-gated transport. Treat the frame only as a wake-up hint and
     // reproduce its resolved item + unique delivery attempt through owner-authenticated
     // RLS reads before touching the local pending resolver. A forged broadcast then
     // has no more authority than packet noise.

package/claude-session.mjs

@@ -240,7 +240,6 @@ const TP_ROOM_REMINDER = [
   'You are Claude in a ThinkPool Code room, driven live from a phone or browser — NOT a local terminal. Keep using the room\'s features.',
   THINKPOOL_RUNTIME_TURN_REMINDER,
   'TERMINAL HIERARCHY: obey your authoritative TERMINAL ROLE. Conductors are independent main terminals; Ensemble lanes are workers only. When a person explicitly asks to open, launch, start, or spawn a separate Cascade/conductor terminal, use open_main_terminal — NEVER spawn_terminal. If open_main_terminal is unavailable, say so; never substitute an Ensemble child. Only conductor-capable roles fan worker slices out with spawn_terminal. Leaf, worker, Side, and managed Flow lanes work directly. Never use built-in invisible Task/Agent subagents or hijack a busy sibling.',
-  'PEER: before substantive work, check what the other lanes are doing (the ROOM NOW snapshot below, read_terminal for detail; list_sessions/read_session across rooms) — coordinate on shared files/branches instead of colliding.',
   'WORKTREES: parallel lanes share one repo — before code edits run `git worktree list`; if linked worktrees exist, take your OWN worktree + branch, never the shared checkout or a branch another lane is on.',
   'BUILD WORKFLOW (default, no magic word): right-size within your TERMINAL ROLE — a trivial ask or delegated slice you just do; a conductor-capable role with a genuinely decomposable build FIRST writes a short plan in chat, THEN fans worker slices into visible spawn_terminal lanes and verifies them. Worker/leaf/Side/managed Flow roles do not fan out. A requested separate conductor uses open_main_terminal. Never plan-mode/ExitPlanMode; plans live in chat and lanes in the existing list.',
 ].join(' ')
@@ -748,14 +747,13 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
       THINKPOOL_CASCADE_RULE,
       'CRUCIAL RECONCILIATION for that workflow: it is NOT plan mode. Never call ExitPlanMode and never make the room wait behind a "plan ready — approve to start" card — your plan lives in the CHAT as a message, and your lanes live in the room\'s EXISTING terminal/lane list. Reuse only those two surfaces; there is no new Flow panel or mode to switch into, and you must not ask for one. Keep the plan and the lanes VISIBLE — that shared visibility is the whole point (it is the pair differentiator, and it catches bugs a single silent lane would hide); never collapse a decomposable build into one hidden lane just to look tidy.',
       ...THINKPOOL_REMOTE_DELIVERY_RULES,
-      'CROSS-TERMINAL AWARENESS: this room may have other terminals open alongside yours — other agents working, or shells the people are driving. You have a READ-ONLY tool, read_terminal: call it with no arguments to list the other open terminals, or with a terminal ref/id/command to read that terminal\'s recent activity. Reach for it when your work depends on what another terminal is doing (e.g. someone says "see what the other terminal hit", or you need to coordinate with a sibling agent before acting). It only ever reads — it never changes another terminal. Identify a terminal by its NAME or its ref/id from the roster, never by an on-screen number like "Terminal 2" — those positional labels renumber when a terminal is closed, so they do not reliably point at a lane.',
+      'CROSS-TERMINAL AWARENESS: ROOM NOW is the default roster and already satisfies the room check when it has enough detail. Do not repeat it with a no-argument read_terminal call unless it is missing or truncated. Use a targeted read_terminal call only when the current task depends on a specific lane’s detailed activity; never poll. Identify a terminal by its NAME or stable ref/id, never by an on-screen number like "Terminal 2" — positional labels renumber when a terminal is closed. The tool is read-only and its optional roster lookup is budgeted separately from bounded targeted transcript reads.',
       'CROSS-TERMINAL HAND-OFF: you also have post_to_terminal(terminal, text) to send a message or task to ANOTHER AGENT terminal in this room (not a plain shell). Use it sparingly and only when the people clearly want the lanes to coordinate — e.g. "tell the backend terminal the API is ready", or to hand a sibling agent a concrete task. Every post requires a person in the room to approve a card before it is delivered, and an agent that was itself reached via a cross-post cannot post onward — so do not rely on it for chit-chat or loops. Prefer read_terminal to understand a sibling before you ever post to it.',
-      'TERMINAL CREATION CONTRACT: conductors and workers use different tools. When a person explicitly asks to open, launch, start, or spawn a separate Cascade/conductor terminal, use open_main_terminal(name?, task?, model?) — it creates an independent MAIN terminal with no Ensemble owner. Never use spawn_terminal for that request, and if open_main_terminal is unavailable say so instead of substituting. Use spawn_terminal(name?, task?, model?, sliceType?) only for bounded WORKER SUB-TERMINALS when your authoritative role permits delegation. Workers never receive the creation tools and never conduct. Do not dump work into busy siblings. Spawned workers are always autonomous in bypassPermissions and never ask the room for an approval card; the bridge still enforces room caps, hop limits, the kill-switch, and isolated linked worktrees. Collect each worker with read_terminal and close_terminal immediately after using its result. Main conductors are independent terminals, keep their requested permission mode, and are not owned/closed through Ensemble.',
+      'TERMINAL CREATION CONTRACT: conductors and workers use different tools. When a person explicitly asks to open, launch, start, or spawn a separate Cascade/conductor terminal, use open_main_terminal(name?, task?, model?) — it creates an independent MAIN terminal with no Ensemble owner. Never use spawn_terminal for that request, and if open_main_terminal is unavailable say so instead of substituting. Use spawn_terminal(name?, task?, model?, sliceType?) only for bounded WORKER SUB-TERMINALS when your authoritative role permits delegation. Workers never receive the creation tools and never conduct. Do not dump work into busy siblings. Spawned workers are always autonomous in bypassPermissions and never ask the room for an approval card; the bridge still enforces room caps, hop limits, the kill-switch, and isolated linked worktrees. Wait for ROOM NOW or a completion signal instead of polling; after a worker finishes, collect it with one targeted read_terminal call and close_terminal immediately. Main conductors are independent terminals, keep their requested permission mode, and are not owned/closed through Ensemble.',
       'CROSS-SESSION AWARENESS: the Ensemble reaches across your SESSIONS, not just the terminals in this room. list_sessions() lists your OTHER ThinkPool Code rooms — both your own rooms running on this machine AND your partner\'s rooms in the same pair, reachable over the per-pair bus (a room on the partner\'s machine shows its host). read_session(session, terminal?) reads recent activity inside one (omit `terminal` to list that room\'s terminals, or pass a ref/name to read that lane). Both are READ-ONLY — they never change another session, and they reach ONLY your own rooms and rooms you share with your partner, never a stranger\'s. Reach for them when work spans rooms — "what\'s the other project up to", "pick up where the other session left off", or to check a long-running task elsewhere before you act here.',
       'CROSS-SESSION HAND-OFF: post_to_session(session, text, terminal?) sends a task or message to an agent in ANOTHER of your rooms — your own, or your partner\'s over the pair bus. Use it sparingly and only when the people clearly want the rooms to coordinate — e.g. hand the API room\'s agent a concrete follow-up once the frontend is ready. It is dual-consent: a person in YOUR room approves sending, and a person in the TARGET room approves receiving, before anything is delivered — so never rely on it for chit-chat or loops, and an agent that was itself reached via a cross-room post cannot post onward to a third room. It spends real model tokens in the other room (maybe on the other person\'s machine), so prefer read_session to understand a room before you ever post into it, and only post one concrete hand-off at a time. Outbound list/read/post tools need the ThinkPool account bridge; a standalone owner room can still receive a paired hand-off directly and will always raise its own approval card before delivery.',
       'SUBAGENT POLICY: in this room, a main conductor delegates worker slices through visible spawn_terminal Ensemble lanes. A requested separate conductor is created with open_main_terminal, never Ensemble. Worker, leaf, Side, and managed Flow lanes do their assigned work directly. Do NOT reach for built-in Task/Agent subagents: an in-process subagent is invisible to the room, cannot be peered at or steered, and its work is lost to the Ensemble.',
       'RESEARCH LANE: you have a `research` tool that runs a REAL multi-source web search + adversarial verification and returns each claim marked HELD or REJECTED with citations. Reach for it when the people would genuinely benefit from looking something external up or settling a question of current fact — pricing, "is X still maintained / deprecated", "is that benchmark real", a debate over facts you are not sure of. Do NOT run it unprompted or for things you already know: first OFFER in plain language ("want me to spawn a research lane on that and check it?"), and only call `research(question)` once they agree — it spends real budget (plan-gated Free 5 / Plus 100 runs a month) and takes ~a minute. When it returns, present the held/rejected findings clearly and invite both people to weigh the sources, flagging any held claim that rests on a source they might not trust — that shared scrutiny is the point.',
-      'PEER FIRST: other lanes may be working in the same repo as you, right now. Before starting substantive work — and before any code edit that could overlap another lane — check what the room is doing: the ROOM NOW snapshot appended to your latest turn, or read_terminal for detail; list_sessions/read_session when the question spans your other rooms. If a sibling is touching the same files or branch, coordinate (read its lane, or raise it in chat) instead of colliding.',
       'WORKTREES: parallel lanes share one machine and usually one repo. Run `git worktree list` before your first code edit; if linked worktrees exist, the shared main checkout is contended (and may be guard-blocked) — do your work in your OWN worktree on your OWN branch (`git worktree add <dir> -b <branch>`), and never edit a checkout or ride a branch another lane is using.',
       'WRITE PLANS INTO THE CHAT: whenever you form or revise a plan — because the room is in Plan mode, or because someone asked you to plan, design, or think it through first — write the actual plan out as a normal message in the room as you develop it: the approach, the concrete steps, the files you will touch, the open questions. The room does NOT surface plan files at all, and the plan-approval card does not reliably carry the plan text, so a plan that lives only in a plan file or only inside ExitPlanMode is INVISIBLE to the people you are working with — they just see "plan ready" with no content. The chat is the canonical place your plan lives; put it there so the room can read and react to it before you proceed.',
     ].join(' '),

package/cross-terminal.mjs

@@ -18,11 +18,38 @@ export const PEEK = {
   // explicitly when a diagnosis genuinely needs deeper sibling history.
   defaultLines: 20,
   maxLines: 200,
-  perTurnCap: 10,     // read_terminal calls allowed per user turn (bridge resets it)
+  perTurnCap: 10,     // targeted transcript reads allowed per user turn (bridge resets it)
+  rosterPerTurnCap: 1, // no-argument roster reads use a separate allowance; ROOM NOW is default
   lineCap: 200,       // per-line truncation
   rosterPreview: 100, // last-line preview length in the roster listing
 }
 
+// ROOM NOW already gives every agent a compact live roster. Keep the one optional
+// full-roster lookup separate from transcript reads so a redundant discovery call
+// cannot consume the budget needed to collect workers and run the final review.
+// Unknown terminal refs are rejected before this helper is called and spend neither
+// allowance. The bridge stores the returned counters on the current lane.
+export const readTerminalBudgetDecision = ({ targeted = false, targetedCount = 0, rosterCount = 0 } = {}, limits = PEEK) => {
+  const nextTargeted = Math.max(0, Number(targetedCount) || 0)
+  const nextRoster = Math.max(0, Number(rosterCount) || 0)
+  if (targeted) {
+    if (nextTargeted >= limits.perTurnCap) return {
+      ok: false,
+      targetedCount: nextTargeted,
+      rosterCount: nextRoster,
+      reason: `Cross-terminal transcript read limit reached for this turn (${limits.perTurnCap}). Stop polling and continue with the worker results already collected; a new person-authored turn resets the allowance.`,
+    }
+    return { ok: true, targetedCount: nextTargeted + 1, rosterCount: nextRoster }
+  }
+  if (nextRoster >= limits.rosterPerTurnCap) return {
+    ok: false,
+    targetedCount: nextTargeted,
+    rosterCount: nextRoster,
+    reason: `The full terminal roster was already read this turn (${limits.rosterPerTurnCap}/${limits.rosterPerTurnCap}). Use the current ROOM NOW snapshot or read one relevant terminal by ref or name.`,
+  }
+  return { ok: true, targetedCount: nextTargeted, rosterCount: nextRoster + 1 }
+}
+
 // One shared lane-status classifier for every roster consumer: the bridge wire,
 // read_terminal, and ROOM NOW. Timestamps stay absolute on the wire so clients can
 // keep the displayed age current without a broadcast every second.
@@ -320,7 +347,7 @@ export const formatRoomNow = ({ selfId, sessions, terms, names = {}, worktrees =
       return `- ${label(x)} · ${x.kind} · ${laneStatusText(x)} — ${clip(preview, limits.previewLen)}`
     })
     if (sib.length > shown.length) rows.push(`- … +${sib.length - shown.length} more (read_terminal lists all)`)
-    out.push(`Other lanes in this room right now (read_terminal for detail):\n${rows.join('\n')}`)
+    out.push(`Other lanes in this room right now (this is the roster; use targeted read_terminal only for needed detail):\n${rows.join('\n')}`)
   }
   const wtAll = Array.isArray(worktrees) ? worktrees : []
   const wt = wtAll.slice(0, limits.wtCap)
@@ -447,7 +474,10 @@ export const spawnDecision = ({ hop = 0, spawnTimes = [], now = 0, spawnedLive =
 // rechecks immediately before it spends a lane. No token, provider credential,
 // host path, or mutable process object is copied into the preview.
 const DISPATCH_ARG_KEYS = Object.freeze(['mode', 'model', 'name', 'provider', 'runtime', 'sliceType', 'task'])
-const DISPATCH_MODES = new Set(['default', 'acceptEdits', 'bypassPermissions', 'plan'])
+// `review` is an internal Codex-only mode selected by structuredModeForSlice.
+// It is not user-selectable in the spawn schema, but it must survive the immutable
+// preview boundary or every Codex review lane fails before creation.
+const DISPATCH_MODES = new Set(['default', 'acceptEdits', 'bypassPermissions', 'plan', 'review'])
 const DISPATCH_RUNTIMES = new Set(['claude', 'codex', 'hermes'])
 const DISPATCH_SLICES = new Set(['scaffold', 'feature', 'fix', 'review'])
 const secretValue = /((?<![a-z0-9])sk-[a-z0-9_-]{8,}|(?<![a-z0-9])gsk_[a-z0-9_-]{8,}|(?<![a-z0-9])AIza[a-z0-9_-]{8,}|bearer\s+[a-z0-9._-]{8,})/ig
@@ -524,7 +554,8 @@ export function buildDispatchPreview ({ args, initiatorTerminalId, roomCode, bri
     }),
     permissions: Object.freeze({ mode: exactArgs.mode, consequence: exactArgs.mode === 'bypassPermissions'
       ? 'Unattended local access within this worker’s sandbox and tool policy.'
-      : exactArgs.mode === 'plan' ? 'Planning only; execution remains gated.' : 'Protected local actions keep their normal permission gates.' }),
+      : exactArgs.mode === 'review' ? 'Read-only inspection of the pinned parent snapshot; writes and approval escapes are unavailable.'
+        : exactArgs.mode === 'plan' ? 'Planning only; execution remains gated.' : 'Protected local actions keep their normal permission gates.' }),
     worktree: 'Automatically creates one visible lateral worker lane and an isolated git worktree on this machine.',
     caps,
   })

package/cumulative-event-relay.mjs

@@ -1,7 +1,12 @@
 // Cumulative provider snapshots are replace-in-place UI state, not transcript
 // facts. Deliver the first immediately and coalesce a burst to its latest frame;
 // any durable event flushes the pending snapshot first to preserve wire order.
-export function createCumulativeEventRelay(emit, waitMs = 150) {
+//
+// 75ms is a readable 13.3fps ceiling: quick enough for an active reply without
+// turning every provider delta into a realtime broadcast or a full UI repaint.
+export const CUMULATIVE_EVENT_RELAY_WAIT_MS = 75
+
+export function createCumulativeEventRelay(emit, waitMs = CUMULATIVE_EVENT_RELAY_WAIT_MS) {
   let lastSentAt = 0
   let pending = null
   let timer = null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.327",
+  "version": "0.7.330",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "bridge.mjs",
+    "bridge-service.sh",
     "command-guidance.mjs",
     "abort-turn-barrier.mjs",
     "host-memory.mjs",

package/terminal-name.mjs

@@ -7,7 +7,8 @@ const SKIP = new Set([
   'do', 'much', 'better', 'really', 'need', 'want', 'your', 'their', 'its',
   'also', 'all', 'away', 'before', 'cause', 'does', 'dont', "don't", 'fully', 'has',
   'have', 'now', 'occasionally', 'return', 'second', 'so', 'sometimes', 'still',
-  'than', 'then', 'there', 'whenever', 'why', 'working',
+  'than', 'then', 'there', 'what', 'when', 'where', 'which', 'who', 'whenever',
+  'why', 'working',
 ])
 
 const GENERIC = /^(?:new )?(?:agent |coding )?(?:terminal|task|lane|session|work)$/i
@@ -16,6 +17,8 @@ const ANY_HEADING = /^(?:#{1,6}\s+|(?:context|background|constraints?|inputs?|ou
 const NOISE = /^(?:context|background|for reference|here(?:'s| is)|note|current(?:ly)?|example|environment|room now|constraints?|acceptance|success criteria)\b/i
 const EXPLANATION = /^(?:because|cause|since|so that|this is because)\b/i
 const CONSTRAINT = /^(?:users? can still|keep|must|never|should|without)\b/i
+const INFORMATION_REQUEST = /^(?:which|what|who|where|when|why|how)\b/i
+const NEGATIVE_PREFERENCE = /^(?:(?:i|we)\s+)?(?:do not|don't|dont|would not|wouldn't|won't|wont)\s+(?:(?:want|wanna|need)(?:\s+to)?|use|include|choose)\b|^(?:(?:i|we)\s+)?(?:want|wanna|need)(?:\s+to)?\s+avoid\b/i
 const ISSUE = /\b(?:broken|buggy|crash(?:es|ed|ing)?|duplicate|error|fail(?:s|ed|ing|ure)?|flash(?:es|ed|ing)?|missing|no animation|not working|out of (?:scrollable )?view|stuck|wrong)\b/i
 const REQUEST = /^(?:please\s+)?(?:can|could|would|will)\s+(?:we|you)\b|^(?:please\s+)?(?:how about|let's|let us|we need to|i want you to)\b/i
 const SECRET = /(?<![\p{L}\p{N}])(?:sk-(?:proj-)?[a-z0-9_-]{8,}|gsk_[a-z0-9_-]{8,}|xox[baprs]-[a-z0-9_-]{8,}|gh[pousr]_[a-z0-9_-]{8,}|glpat-[a-z0-9_-]{8,}|npm_[a-z0-9]{24,}|(?:sk|rk)_(?:live|test)_[a-z0-9]{8,}|whsec_[a-z0-9]{8,}|AIza[a-z0-9_-]{8,}|AKIA[A-Z0-9]{12,}|bearer\s+[a-z0-9._-]{8,}|eyJ[a-z0-9_-]{8,}\.[a-z0-9_-]{8,}\.[a-z0-9_-]{8,})(?![\p{L}\p{N}])/giu
@@ -125,12 +128,14 @@ const bestIntentClause = (text) => {
     const action = bestAction(clause)
     let score = action?.score || 0
     if (REQUEST.test(clause)) score += 18
+    if (INFORMATION_REQUEST.test(clause)) score += 36
     if (ISSUE.test(clause)) score += /\b(?:crash|fail|flash|stuck|wrong)\w*\b/i.test(clause) ? 36 : 26
     if (words.length >= 3 && words.length <= 24) score += 10
     else if (words.length > 40) score -= 14
     if (NOISE.test(clause)) score -= 30
     if (EXPLANATION.test(clause)) score -= 34
     if (CONSTRAINT.test(clause)) score -= 45
+    if (NEGATIVE_PREFERENCE.test(clause)) score -= 70
     score += Math.round((i / Math.max(1, clauses.length - 1)) * 4)
     if (!best || score > best.score) best = { clause, score }
   }
@@ -163,7 +168,7 @@ export function cleanTerminalName(value) {
 
 const titleWord = (word) => {
   const lower = word.toLowerCase()
-  if (lower === 'thinkpool') return 'ThinkPool'
+  if (lower === 'thinkpool' || lower === 'thinkpool.io') return 'ThinkPool'
   if (lower === 'serverside') return 'Server-Side'
   if (/^(?:api|ci|css|db|html|llm|mcp|npm|sdk|ui|ux)$/i.test(word)) return lower.toUpperCase()
   if (/^[A-Z\d+#.-]{2,}$/.test(word) || /\d/.test(word)) return word
@@ -194,6 +199,9 @@ const taskTitle = (value) => {
     .replace(/^\s*(?:how about|i (?:do not|don't) know|i guess|i want you to|we need to|your task is to|let(?:'s| us))\s+/i, '')
     .trim()
   if (!body) return null
+  if (NEGATIVE_PREFERENCE.test(body)) return null
+  const informationRequest = INFORMATION_REQUEST.test(body)
+  if (informationRequest) body = body.replace(/^\s*(?:which|what)\s+/i, '').trim()
   const signalText = body
   body = body
     .replace(/\s*,?\s+(?:so (?:that|you|we|it)\b|because\b|cause\b|if you know what i mean\b)[\s\S]*$/i, '')
@@ -205,7 +213,6 @@ const taskTitle = (value) => {
   let verb = issue ? 'Fix' : action?.title
   if (!verb && /\bclos(?:e|es|ed|ing)\b/i.test(body)) verb = 'Close'
   if (!verb && /\bopen(?:s|ed|ing)?\b/i.test(body)) verb = 'Open'
-  if (!verb) verb = 'Work On'
 
   if (/\bautomatic(?:ally)?\b[\s\S]{0,24}\bnam(?:e|ing)\b/i.test(signalText) && /\bterminals?\b/i.test(signalText)) {
     if (/\bcontext\b[\s\S]{0,24}\broom\b|\broom\b[\s\S]{0,24}\bcontext\b/i.test(signalText)) return 'Auto-Name Terminals From Room Context'
@@ -226,9 +233,13 @@ const taskTitle = (value) => {
   }
   let object = contentWords(objectText)
   if (!object.length) object = contentWords(body)
+  if (informationRequest) {
+    const available = object.findIndex((word) => /^available$/i.test(word))
+    if (available > 0) object = [object[available], ...object.slice(0, available), ...object.slice(available + 1)]
+  }
   const picked = [...domain, ...object].filter((word, index, all) => all.findIndex((other) => other.toLowerCase() === word.toLowerCase()) === index).slice(0, 4)
   if (!picked.length) return null
-  return cleanTerminalName([verb, ...picked.map(titleWord)].join(' '))
+  return cleanTerminalName([verb, ...picked.map(titleWord)].filter(Boolean).join(' '))
 }
 
 export function fallbackTerminalName(text) {

package/thinkpool-capabilities.json

@@ -1,16 +1,16 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": 14,
+  "bundleVersion": 15,
   "contracts": [
     {
       "id": "room-coordination",
-      "version": 2,
+      "version": 3,
       "routes": [
         {
           "id": "room-awareness",
           "tools": ["read_terminal"],
           "trigger": "\\b(other|another|sibling|peer)\\s+(lane|terminal)|\\bread_terminal\\b",
-          "prompt": "When the request depends on another lane, a sibling may overlap the work, or a person refers to another terminal, inspect it with read_terminal before acting."
+          "prompt": "When the request depends on another lane, a sibling may overlap the work, or a person refers to another terminal, use the current ROOM NOW snapshot as the default roster. Do not repeat it with a no-argument read_terminal call unless the snapshot is missing or truncated; that roster lookup has its own one-call allowance. Read only the relevant terminal by ref or name when its detailed transcript is actually needed. Never poll with read_terminal: wait for the room snapshot or completion signal to show a state change, collect each finished owned worker once, then close it immediately. Preserve the bounded targeted-read allowance for worker collection and final review."
         },
         {
           "id": "cross-room-awareness",
@@ -22,7 +22,7 @@
           "id": "visible-handoff",
           "tools": ["post_to_terminal", "post_to_session"],
           "trigger": "\\b(hand[ -]?off|tell|send|post)\\b.{0,40}\\b(lane|terminal|room|session|agent)\\b|\\b(post_to_terminal|post_to_session)\\b",
-          "prompt": "When the people want a handoff, read the target first, then use post_to_terminal or post_to_session; let the room approval contract handle consent."
+          "prompt": "When the people want a handoff, read the target once if its current details are not already available, then use post_to_terminal or post_to_session; let the room approval contract handle consent."
         }
       ],
       "impact": [
@@ -41,7 +41,7 @@
     },
     {
       "id": "work-routing",
-      "version": 5,
+      "version": 6,
       "providerRoutingContract": "A Claude lane may select a connected Anthropic-compatible provider by durable id, unique display name, or unique configured model. Unknown or ambiguous references fail closed and must never fall through to built-in Claude.",
       "openerParityContract": "Every top-level terminal may use spawn_terminal or open_main_terminal to open every supported structured runtime: Claude, Codex, or Hermes. Runtime-specific provider/model validation remains authoritative and occurs before inference.",
       "routes": [
@@ -49,10 +49,10 @@
           "id": "work-routing",
           "tools": ["spawn_terminal", "open_main_terminal", "close_terminal"],
           "trigger": "\\b(parallel|delegate|worker|sub[- ]?terminal|conductor|cascade|spawn_terminal|open_main_terminal|close_terminal)\\b",
-          "prompt": "For genuinely decomposable work in a conductor-capable role, open visible worker slices with spawn_terminal, collect and verify them, then close_terminal. An explicitly requested separate Cascade/conductor uses open_main_terminal, never spawn_terminal. Review slices are structurally read-only and must use the review slice type; they never inherit autonomous bypass authority."
+          "prompt": "For genuinely decomposable work in a conductor-capable role, open visible worker slices with spawn_terminal, collect and verify each result with one targeted read_terminal call after completion, then close_terminal immediately. Do not poll workers or repeat the ROOM NOW roster. An explicitly requested separate Cascade/conductor uses open_main_terminal, never spawn_terminal. Review slices are structurally read-only and must use the review slice type; they never inherit autonomous bypass authority."
         }
       ],
-      "expandedPrompt": "CASCADE WORKFLOW (default for non-trivial work that genuinely decomposes; mandatory when the people ask for Cascade, tiered lanes, one-shot flow, or unattended multi-slice execution): first investigate enough to name evidence-backed slices and their dependencies, then post a short plan in the room. The current top-level/conductor terminal keeps decomposition, integration, and final judgment; use spawn_terminal only for bounded worker slices, while an explicitly requested separate conductor uses open_main_terminal. Parallelize only disjoint slices and encode dependencies instead of holding them in your head. Choose sliceType=scaffold for mechanical/search work, feature or fix for implementation, and review with a balanced capable tier for adversarial verification. Review slices are structurally read-only: they resolve to a native review/Plan mode before launch and can never inherit autonomous bypass authority. Every worker brief names the evidence/diagnosis, exact scope, observable acceptance proof, relevant repo gates, whether merge/publish is required, and a safe-skip escape hatch. After dispatch, remain responsible: use read_terminal to collect each owned lane, verify its claim, close_terminal immediately, and dispatch newly unblocked work; never declare the Cascade done or yield a final result while owned workers remain uncollected. Check origin/main CI before merge-bearing waves, coordinate shared fixtures/publishers, and treat sibling pushes as context rather than proof. Run an adversarial review after builders (or pipeline review behind completed phases), finish with production-condition evidence, verify every reported SHA/version, and close every worker you opened.",
+      "expandedPrompt": "CASCADE WORKFLOW (default for non-trivial work that genuinely decomposes; mandatory when the people ask for Cascade, tiered lanes, one-shot flow, or unattended multi-slice execution): first investigate enough to name evidence-backed slices and their dependencies, then post a short plan in the room. The current top-level/conductor terminal keeps decomposition, integration, and final judgment; use spawn_terminal only for bounded worker slices, while an explicitly requested separate conductor uses open_main_terminal. Parallelize only disjoint slices and encode dependencies instead of holding them in your head. Choose sliceType=scaffold for mechanical/search work, feature or fix for implementation, and review with a balanced capable tier for adversarial verification. Review slices are structurally read-only: they resolve to a native review/Plan mode before launch and can never inherit autonomous bypass authority. Every worker brief names the evidence/diagnosis, exact scope, observable acceptance proof, relevant repo gates, whether merge/publish is required, and a safe-skip escape hatch. ROOM NOW is the default roster and completion signals wake the conductor; do not spend the bounded read allowance polling or repeating a no-argument roster. After dispatch, remain responsible: once an owned worker is finished, make one targeted read_terminal call to collect its result, verify its claim, close_terminal immediately, and dispatch newly unblocked work. Preserve enough targeted reads for every open worker and the final adversarial review; never declare the Cascade done or yield a final result while owned workers remain uncollected. Check origin/main CI before merge-bearing waves, coordinate shared fixtures/publishers, and treat sibling pushes as context rather than proof. Run an adversarial review after builders (or pipeline review behind completed phases), finish with production-condition evidence, verify every reported SHA/version, and close every worker you opened.",
       "impact": [
         {"path": "bridge/bridge.mjs", "diffPattern": "spawn_terminal|open_main_terminal|close_terminal|cascadeRole|spawnDepth"},
         {"path": "bridge/lane-lifecycle.mjs"},