thinkpool-pair 0.7.328 → 0.7.331

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.328",
+  "version": "0.7.331",
   "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

@@ -17,6 +17,7 @@ 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 DEPENDENT_FRAGMENT = /^(?:after|before|by|during|for|from|in|instead(?: of)?|on|through|until|with|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
@@ -29,6 +30,7 @@ const ACTIONS = Object.freeze([
   { title: 'Harden', score: 98, re: /\b(?:harden|hardens|hardened|hardening)\b/i },
   { title: 'Snap', score: 96, re: /\b(?:snap|snaps|snapped|snapping)\b/i },
   { title: 'Improve', score: 94, re: /\b(?:improve|improves|improved|improving|optimi[sz](?:e|es|ed|ing)|\bbetter\b)\b/i },
+  { title: 'Rework', score: 93, re: /\b(?:rework|reworks|reworked|reworking)\b/i },
   { title: 'Implement', score: 92, re: /\b(?:implement|implements|implemented|implementing)\b/i },
   { title: 'Build', score: 90, re: /\b(?:build|builds|built|building|create|creates|created|creating)\b/i },
   { title: 'Add', score: 88, re: /\b(?:add|adds|added|adding|wire|wires|wired|wiring)\b/i },
@@ -136,7 +138,11 @@ const bestIntentClause = (text) => {
     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)
+    // A short dependent tail such as "From ground up" or "On mobile" adds
+    // scope to the preceding request; it is not a standalone task. Recency is
+    // deliberately not a signal here: the title should represent the main
+    // theme, not whichever sentence happened to come last.
+    if (!action && !REQUEST.test(clause) && !INFORMATION_REQUEST.test(clause) && DEPENDENT_FRAGMENT.test(clause)) score -= 24
     if (!best || score > best.score) best = { clause, score }
   }
   return best?.clause || clauses[0] || null
@@ -175,13 +181,18 @@ const titleWord = (word) => {
   return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
 }
 
-const contentWords = (value) => {
+const contentWords = (value, excludedFamilies = []) => {
   const words = String(value || '').match(/[\p{L}\p{N}][\p{L}\p{N}+#.'-]*/gu) || []
   const seen = new Set()
   const result = []
   for (let word of words) {
     const lower = word.toLowerCase()
     if (SKIP.has(lower) || /^https?$/i.test(word)) continue
+    // ACTIONS intentionally folds synonyms into one title verb (review/test/verify
+    // all become Audit). Once that verb is chosen, words from the same family are
+    // not objects. Keeping them spent the title budget on "Audit Reviews Audits"
+    // before the extractor reached the actual scope.
+    if (excludedFamilies.some((family) => family.test(word))) continue
     if (lower === 'flashes' || lower === 'flashing') word = 'flash'
     if (lower === 'failing' || lower === 'failed' || lower === 'fails') word = 'failure'
     const key = word.toLowerCase().replace(/(?:s|ed|ing)$/i, '')
@@ -227,12 +238,13 @@ const taskTitle = (value) => {
     const before = body.slice(0, action.index)
     objectText = body.slice(action.index + action.match.length)
     const weakLead = bestAction(before)
-    if (weakLead?.score <= 76) domain = contentWords(before.slice(weakLead.index + weakLead.match.length)).slice(0, 3)
+    if (weakLead?.score <= 76) domain = contentWords(before.slice(weakLead.index + weakLead.match.length), [weakLead.re]).slice(0, 3)
     objectText = objectText.split(/\s*,?\s+(?:and|then)\s+(?:(?:also)\s+)?(?=(?:add|build|create|implement|remove|replace|update|wire)\b)/i, 1)[0]
     objectText = objectText.replace(/\b(?:and|then)\s+(?:audit|check|debug|investigate|review|test|verify)\b/gi, ' ')
   }
-  let object = contentWords(objectText)
-  if (!object.length) object = contentWords(body)
+  const excludedObjectFamilies = action ? [action.re] : []
+  let object = contentWords(objectText, excludedObjectFamilies)
+  if (!object.length) object = contentWords(body, excludedObjectFamilies)
   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)]

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"},