thinkpool-pair 0.7.83 → 0.7.85

package/bridge.mjs

@@ -39,7 +39,7 @@ import { createClient } from '@supabase/supabase-js'
 import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
 import { z } from 'zod'
 import { startClaudeSession } from './claude-session.mjs'
-import { formatPeek, PEEK } from './cross-terminal.mjs'
+import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision } from './cross-terminal.mjs'
 import { turnInFlight } from './update-gate.mjs'
 import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames } from './session-store.mjs'
 import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks } from './event-id.mjs'
@@ -921,15 +921,126 @@ function openStructured({ id, model, resume, log, commands, mode }) {
           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 text = formatPeek({ selfId: id, sessions, terms, terminal: args?.terminal, lines: args?.lines })
+          const text = formatPeek({ selfId: id, sessions, terms, names: termNames, terminal: args?.terminal, lines: args?.lines })
           return { content: [{ type: 'text', text }] }
         },
       ),
+      // Tier C — directed cross-lane action. WRITES into a sibling AGENT lane.
+      // The PreToolUse gate (claude-session.mjs) already enforced: precheck passed
+      // + a human approved the card. This handler routes only; it re-asserts the
+      // bounds defensively. Targets AGENT terminals only (not human shells —
+      // injecting keystrokes into someone's shell is out of scope for v1).
+      tool(
+        'post_to_terminal',
+        'Send a message or task to ANOTHER AGENT terminal in this ThinkPool Code room. Use `terminal` (a ref/id/command from read_terminal) and `text` (what to send). A person in the room must approve before it is delivered, and an agent reached via a cross-post cannot post onward. Targets agent terminals only, not plain shells. Use read_terminal first to understand the sibling.',
+        {
+          terminal: z.string().describe('ref, id, or command of the AGENT terminal to send to (from read_terminal)'),
+          text: z.string().describe('the message or task to deliver to that terminal'),
+        },
+        async (args) => {
+          const okText = (t) => ({ content: [{ type: 'text', text: t }] })
+          // Defensive re-check (the gate already passed in PreToolUse).
+          const gate = crossPostDecision({ hop: entry.hop || 0, postCount: entry.postCount || 0, disabled: process.env.TP_CROSSPOST_OFF === '1' })
+          if (!gate.ok) return okText(gate.reason)
+          const sib = siblingsOf({ selfId: id, sessions, terms, names: termNames })
+          const target = resolveSibling(sib, args?.terminal)
+          if (!target) return okText(`No terminal matches "${args?.terminal}". Call read_terminal with no argument to list the open terminals.`)
+          if (target.kind !== 'agent') return okText(`Terminal ${target.ref} is a shell, not an agent — cross-posting is only allowed to agent terminals.`)
+          const te = sessions.get(target.id)
+          if (!te?.session) return okText(`Terminal ${target.ref} is no longer live.`)
+          entry.postCount = (entry.postCount || 0) + 1
+          const fromRef = String(id).slice(0, 8)
+          const msg = `[From: terminal ${fromRef}'s agent — relayed via ThinkPool cross-terminal, approved by a person in the room]\n${args.text}`
+          // The injected turn starts fresh budgets, one hop deeper (loop breaker).
+          te.hop = (entry.hop || 0) + 1
+          te.peekCount = 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).
+          const evt = { kind: 'you', text: msg, by: `terminal ${fromRef} (agent)`, crosspost: true }
+          stampEvent(evt)
+          pushLog(te, evt)
+          bcast('code-event', { term: target.id, evt })
+          try { te.session.sendTurn(msg) } catch { return okText(`Could not deliver to terminal ${target.ref} — it may have just closed.`) }
+          return okText(`Delivered to terminal ${target.ref} (${target.cmd}). It will respond in its own lane; check back with read_terminal.`)
+        },
+      ),
+      // Tier C+ — SPAWN a fresh agent lane the caller OWNS. The motivating bug:
+      // an agent fanned a research task into SIBLINGS that were already busy (a
+      // release lane, a Q&A lane) because it had no way to make its own lanes.
+      // This opens a brand-new structured session server-side (the same path the
+      // web's "+ New terminal" and the restore loop use), so announce() surfaces
+      // its tab in the open web UI live. Auto-allowed by the PreToolUse gate but
+      // bounded by spawnDecision (hop-0-only, per-turn cap, the live terminal cap,
+      // TP_SPAWN_OFF kill-switch). A spawned lane runs one hop deep, so it cannot
+      // recursively spawn/post onward — the fork-bomb breaker (mirrors Tier C).
+      tool(
+        'spawn_terminal',
+        'Open a NEW agent terminal (a fresh Claude lane) in this ThinkPool Code room — YOUR lane to use, not a sibling that is already working. Use it to fan work out: give it an initial `task` and it runs in parallel in its own lane; collect its result later with read_terminal, and close it with close_terminal when done. ALWAYS prefer spawning a fresh lane over post_to_terminal into one that is already busy. Bounded by the room terminal cap and a per-turn limit.',
+        {
+          name: z.string().max(80).optional().describe('a short label for the new lane so the room (and you) can find it, e.g. "Research: topologies"'),
+          task: z.string().optional().describe('an initial task to hand the new lane immediately; omit to open it idle'),
+          model: z.string().optional().describe('optional model for the lane, e.g. opus / sonnet / haiku'),
+        },
+        async (args) => {
+          const okText = (t) => ({ content: [{ type: 'text', text: t }] })
+          const gate = spawnDecision({ hop: entry.hop || 0, spawnCount: entry.spawnCount || 0, liveCount: sessions.size + terms.size, disabled: process.env.TP_SPAWN_OFF === '1' })
+          if (!gate.ok) return okText(gate.reason)
+          entry.spawnCount = (entry.spawnCount || 0) + 1
+          const newId = randomUUID()
+          const newRef = String(newId).slice(0, 8)
+          const fromRef = String(id).slice(0, 8)
+          // Name BEFORE opening so openStructured's own announce already carries the label.
+          if (args?.name) { termNames[newId] = String(args.name).slice(0, 80); saveNames(room, termNames) }
+          openStructured({ id: newId, model: args?.model })
+          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.spawnedBy = id   // ownership: only the spawner may close_terminal it
+          announce()          // (defensive) ensure the web renders the new tab live
+          if (args?.task) {
+            // One hop deep: the spawned lane cannot spawn/post onward until a person
+            // speaks to it (code-turn resets hop to 0). Mirrors the Tier C injection.
+            ne.hop = 1; ne.peekCount = 0; ne.postCount = 0; ne.spawnCount = 0
+            const msg = `[Task from terminal ${fromRef}'s agent — relayed via ThinkPool cross-terminal; you are a fresh lane it opened for you]\n${args.task}`
+            const evt = { kind: 'you', text: msg, by: `terminal ${fromRef} (agent)`, crosspost: true }
+            stampEvent(evt); pushLog(ne, evt); bcast('code-event', { term: newId, evt })
+            try { ne.session.sendTurn(msg) } catch { return okText(`Opened lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — could not hand off the task. Try post_to_terminal shortly.`) }
+            return okText(`Opened agent lane ${newRef}${args?.name ? ` ("${args.name}")` : ''} and handed it the task. It runs in its own lane — check back with read_terminal, then close_terminal when done.`)
+          }
+          return okText(`Opened idle agent lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}. Hand it work with post_to_terminal, or a person can type into it.`)
+        },
+      ),
+      // Tier C+ — CLOSE a lane the caller spawned. Restricted to self-spawned agent
+      // lanes (spawnedBy === this id): an agent must never be able to kill a sibling
+      // someone else is working in, nor the host/attached terminal. The fan-out
+      // cleanup half of spawn_terminal. Routes through endStructured (same path as
+      // the web's code-close), which no-ops if the id isn't a live session.
+      tool(
+        'close_terminal',
+        'Close an agent lane that YOU opened with spawn_terminal (identified by ref/id/name). You can only close lanes you spawned yourself — never a sibling someone else is working in, and never the main terminal. Use it to clean up after a fan-out once you have collected the results with read_terminal.',
+        {
+          terminal: z.string().describe('ref, id, or name of the lane you spawned (from read_terminal)'),
+        },
+        async (args) => {
+          const okText = (t) => ({ content: [{ type: 'text', text: t }] })
+          const sib = siblingsOf({ selfId: id, sessions, terms, names: termNames })
+          const target = resolveSibling(sib, args?.terminal)
+          if (!target) return okText(`No terminal matches "${args?.terminal}". Call read_terminal with no argument to list the open terminals.`)
+          const te = sessions.get(target.id)
+          if (!te) return okText(`Terminal ${target.ref} is not an agent lane (or already closed) — only spawned agent lanes can be closed this way.`)
+          if (te.spawnedBy !== id) return okText(`Terminal ${target.ref} was not opened by you — you can only close lanes you spawned yourself. Leave it to the person running it.`)
+          endStructured(target.id)
+          return okText(`Closed agent lane ${target.ref}${target.name ? ` ("${target.name}")` : ''}.`)
+        },
+      ),
     ],
   })
   entry.session = startClaudeSession({
     cwd: process.cwd(), model, resume, mode,
     mcpServers: { thinkpool: peekServer },
+    // Tier C precheck — the PreToolUse gate calls this BEFORE raising a card, so a
+    // disabled/looping/over-cap post never bothers a person. Closes over `entry`.
+    crossPostGate: () => crossPostDecision({ hop: entry.hop || 0, postCount: entry.postCount || 0, disabled: process.env.TP_CROSSPOST_OFF === '1' }),
     env: { ...process.env, TP_MOCKUP_OUTBOX: mockupOutbox },
     onEvent: (evt) => {
       // Self-heal a stale resume — the saved SDK session expired. Reopen fresh,
@@ -1216,7 +1327,13 @@ channel
     const s = payload?.term && sessions.get(payload.term)
     if (!s || payload.text == null) return
     markActivity()
-    s.peekCount = 0   // B2: fresh cross-terminal read budget per user turn
+    // B2/C: a real human turn is hop 0 with fresh cross-terminal budgets. This is
+    // the loop-breaker reset point — an injected (cross-posted) turn does NOT come
+    // through here, so its deeper hop level + spent budget stick until a person
+    // speaks again.
+    s.peekCount = 0
+    s.postCount = 0
+    s.hop = 0
     const text = String(payload.text)
     // Echo the turn so BOTH readers (and late joiners, via the log) show who
     // said what — UNLESS silent (an @pool fire, which renders its own line).

package/claude-session.mjs

@@ -120,7 +120,7 @@ const simplifyBlocks = (blocks = []) => blocks.map((b) => {
  */
 const MODES = new Set(['default', 'acceptEdits', 'plan', 'bypassPermissions'])
 
-export function startClaudeSession({ cwd, model, resume, env, mode: initialMode = 'default', onEvent, requestPermission, mcpServers }) {
+export function startClaudeSession({ cwd, model, resume, env, mode: initialMode = 'default', onEvent, requestPermission, mcpServers, crossPostGate }) {
   const ac = new AbortController()
   let input = makeInputStream()   // `let`: auto-restart swaps in a fresh stream
   let sessionId = resume || null
@@ -248,12 +248,36 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
     // Surface it to the room when it changes; absent on models without effort.
     const lvl = hookInput.effort?.level
     if (lvl && lvl !== effort) { effort = lvl; emit({ kind: 'effort', level: effort }) }
-    // ThinkPool's own in-process tools (B2 cross-terminal read) are read-only and
-    // within-room — never prompt for them, in any mode. They still surface as
-    // tool_use/tool_result cards so the room sees the peek.
-    if (typeof toolName === 'string' && toolName.startsWith('mcp__thinkpool__')) {
+    // ThinkPool cross-terminal READ (B2) is read-only + within-room — never
+    // prompt, in any mode. It still surfaces as a tool card so the room sees the peek.
+    if (toolName === 'mcp__thinkpool__read_terminal') {
       return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: 'Auto-approved (read-only ThinkPool cross-terminal read).' } }
     }
+    // ThinkPool cross-terminal SPAWN / CLOSE (Tier C+) — lane management the agent
+    // OWNS. Unlike post_to_terminal (which WRITES into someone else's working lane,
+    // so it's human-gated every time), these only ever open a FRESH lane or close a
+    // lane the agent itself spawned — they never touch a sibling's work. Auto-allow
+    // (surfaced as a card for visibility); the bridge-side handler enforces the real
+    // bounds (hop-0-only, per-turn cap, the 8-terminal cap, TP_SPAWN_OFF) and can
+    // only close self-spawned lanes. This is the "you open them yourself" path.
+    if (toolName === 'mcp__thinkpool__spawn_terminal' || toolName === 'mcp__thinkpool__close_terminal') {
+      return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: 'Auto-approved (ThinkPool cross-terminal lane management — bounded by the room caps; closes only self-spawned lanes).' } }
+    }
+    // ThinkPool cross-terminal POST (Tier C) WRITES into a sibling agent's lane —
+    // human-gated EVERY time, never remembered. First a bridge-side precheck
+    // (kill-switch / loop-breaker / per-turn cap) so a blocked or runaway post
+    // never even raises a card; then the standard permission round-trip at 'high'
+    // risk (card offers Deny / Allow-once only — no "always"). Spec INV-4.
+    if (toolName === 'mcp__thinkpool__post_to_terminal') {
+      const gate = crossPostGate ? crossPostGate() : { ok: true }
+      if (!gate.ok) {
+        return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: gate.reason || 'Cross-terminal post not allowed right now.' } }
+      }
+      let decision = 'deny'
+      try { decision = await requestPermission?.({ id: randomUUID(), toolName, input: toolInput, risk: 'high' }) ?? 'deny' } catch { decision = 'deny' }
+      const allowed = decision === 'allow'
+      return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: allowed ? 'allow' : 'deny', permissionDecisionReason: allowed ? 'Cross-terminal post approved in the ThinkPool room.' : 'Cross-terminal post denied in the room — do not retry; ask what to do instead.' } }
+    }
     // ── Plan approval — ExitPlanMode is how the agent presents its plan in
     // plan mode. Render a dedicated plan card (not the generic perm card) with
     // three outcomes: run (exit → default), accept (exit → acceptEdits), keep
@@ -370,7 +394,9 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
       'SHOW YOUR WORK, do not just describe it: the room is watched live from a phone, where a wall of text is painful to read. Whenever you build, change, or fix anything visual — a UI, a page, an HTML artifact, a chart, a diagram, a rendered result — capture a screenshot and surface the PNG (for example, read the image file into your turn) so it appears inline in the room. The room auto-uploads any image you surface. Default to showing a picture of the result over narrating it; err toward more screenshots, not fewer.',
       'HTML PREVIEWS: for any HTML you produce, give the room something it can actually open, by whichever path is available. (a) IN-ROOM PREVIEW: if a mockup render helper is present — one that writes a manifest into the directory named by $TP_MOCKUP_OUTBOX, such as the mockup-iterate render.sh script when the bridge was launched from the thinkpool repo — use it; it surfaces an inline card with desktop and mobile views that the room can expand. (b) SHAREABLE LINK: additionally or otherwise, publish the HTML to a GitHub Pages URL per the LINKS & ARTIFACTS rule above and post the link. Never leave an HTML artifact viewable only as a local path.',
       'RUN IT, DO NOT ASK: verify your own work before calling it done. Actually run or serve what you changed, observe that it behaves correctly, and show the evidence in the room — a screenshot of the running result, the passing test output, or the real response — rather than telling the user "this should work, go test it." If you could not verify something, say exactly what is unverified. This room follows verify-before-claiming: runtime evidence you produced, not assertion.',
-      '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.',
+      '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 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.',
+      'CROSS-TERMINAL SPAWN: when a person asks you to fan work out across multiple agents — research lanes, parallel sub-tasks, a swarm — open YOUR OWN fresh lanes with spawn_terminal(name?, task?, model?); do NOT dump the work into siblings that are already busy (a sibling is mid-task unless read_terminal shows it idle, and hijacking it derails their work). spawn_terminal opens a brand-new Claude lane and, if you pass `task`, hands it that task immediately; it appears as a new terminal in the room. Collect each lane\'s result later with read_terminal (a spawned lane cannot post back to you), and tidy up with close_terminal once you have what you need — you may only close lanes you spawned yourself. You are bounded: at most a few new lanes per turn and 8 terminals total in the room, and a lane you were spawned/cross-posted into cannot itself spawn (so no runaway). This is how you "open the terminals yourself" instead of asking a person to.',
       '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(' '),
     // Needed for live thinking-token progress (SDKThinkingTokensMessage) to

package/cross-terminal.mjs

@@ -59,36 +59,77 @@ export const cleanPtyTail = (buf, n) => {
 // Build the tool's text reply. `selfId` is excluded. `sessions` (structured) and
 // `terms` (PTY) are the bridge's module-scope Maps (id → entry). With no
 // `terminal`, returns the roster; with one, returns that lane's recent output.
-export const formatPeek = ({ selfId, sessions, terms, terminal, lines } = {}) => {
-  const n = Math.min(PEEK.maxLines, Math.max(1, Number(lines) || PEEK.defaultLines))
+// ── shared sibling resolution (used by formatPeek + the cross-post handler) ──
+export const siblingRef = (id) => String(id).slice(0, 8)
+
+// Every terminal in the room except `selfId`, normalized. Structured sessions →
+// kind 'agent' (carry `log`); PTY terminals → kind 'shell' (carry `buf`). `names`
+// is the bridge's id→label map (termNames) — the HUMAN names people actually use
+// ("Pivot", "Grug"); without it the roster is just hashes and an agent can't map
+// "what is Pivot doing" to a lane.
+export const siblingsOf = ({ selfId, sessions, terms, names = {} } = {}) => {
+  const nm = (id) => (names && names[id]) || ''
   const sib = []
   for (const [id, s] of (sessions || new Map())) {
     if (id === selfId) continue
-    sib.push({ id, kind: 'agent', cmd: s?.cmd || 'claude', log: Array.isArray(s?.log) ? s.log : [] })
+    sib.push({ id, ref: siblingRef(id), name: nm(id), kind: 'agent', cmd: s?.cmd || 'claude', log: Array.isArray(s?.log) ? s.log : [] })
   }
   for (const [id, t] of (terms || new Map())) {
     if (id === selfId) continue
-    sib.push({ id, kind: 'shell', cmd: t?.cmd || 'shell', buf: t?.buf || '' })
+    sib.push({ id, ref: siblingRef(id), name: nm(id), kind: 'shell', cmd: t?.cmd || 'shell', buf: t?.buf || '' })
   }
-  if (!sib.length) return 'No other terminals are open in this room right now.'
+  return sib
+}
+
+// True for a POSITIONAL on-screen label ("Terminal 2", "t3", bare "2"). These
+// renumber when a sibling closes (Terminal 3 → Terminal 2 after a delete), so the
+// bridge — which only ever knows stable UUIDs — must NEVER resolve them, or a
+// delete could silently re-point a cross-post at the wrong lane. We refuse them
+// explicitly (safe miss) instead. The stable handles are the UUID/ref and the
+// custom name (both bound to the UUID, immune to renumbering).
+export const isOrdinalRef = (q) => /^(terminal\s*)?\d+$/i.test(q) || /^t\d+$/i.test(q)
 
-  const ref = (x) => String(x.id).slice(0, 8)
+// Resolve an agent-supplied reference to one sibling, or null. Match priority:
+// exact id → exact name → exact short-ref → id-prefix (≥4 chars) → name substring
+// → command substring. Name matching is what makes "Pivot" / "Grug" resolvable;
+// positional ordinals are refused (see isOrdinalRef).
+export const resolveSibling = (siblings, terminal) => {
+  const q = String(terminal || '').toLowerCase().trim()
+  if (!q || isOrdinalRef(q)) return null
+  const list = Array.isArray(siblings) ? siblings : []
+  return list.find(x => String(x.id).toLowerCase() === q)
+    || list.find(x => String(x.name || '').toLowerCase() === q)
+    || list.find(x => String(x.ref).toLowerCase() === q)
+    || list.find(x => q.length >= 4 && String(x.id).toLowerCase().startsWith(q))
+    || list.find(x => x.name && String(x.name).toLowerCase().includes(q))
+    || list.find(x => String(x.cmd).toLowerCase().includes(q))
+    || null
+}
+
+const label = (x) => `${x.ref}${x.name ? ` · "${x.name}"` : ''}`
+
+export const formatPeek = ({ selfId, sessions, terms, names = {}, terminal, lines } = {}) => {
+  const n = Math.min(PEEK.maxLines, Math.max(1, Number(lines) || PEEK.defaultLines))
+  const sib = siblingsOf({ selfId, sessions, terms, names })
+  if (!sib.length) return 'No other terminals are open in this room right now.'
 
   if (!terminal) {
     const rows = sib.map(x => {
       let preview
       if (x.kind === 'agent') { const ls = x.log.map(e => digestLogEvent(e, PEEK.rosterPreview)).filter(Boolean); preview = ls[ls.length - 1] || '(no activity yet)' }
       else { preview = cleanPtyTail(x.buf, 1)[0] || '(no output yet)' }
-      return `- ${ref(x)} · ${x.kind} · ${x.cmd} — ${clip(preview, PEEK.rosterPreview)}`
+      return `- ${label(x)} · ${x.kind} · ${x.cmd} — ${clip(preview, PEEK.rosterPreview)}`
     })
-    return `Other terminals in this room (call read_terminal with one of these refs to read it):\n${rows.join('\n')}`
+    return `Other terminals in this room (call read_terminal with a ref or name to read one):\n${rows.join('\n')}`
   }
 
-  const q = String(terminal).toLowerCase().trim()
-  const hit = sib.find(x => String(x.id).toLowerCase() === q)
-    || sib.find(x => ref(x).toLowerCase() === q || String(x.id).toLowerCase().startsWith(q))
-    || sib.find(x => String(x.cmd).toLowerCase().includes(q))
-  if (!hit) return `No terminal matches "${terminal}". Call read_terminal with no argument to list the open terminals.`
+  const hit = resolveSibling(sib, terminal)
+  if (!hit) {
+    const extra = isOrdinalRef(String(terminal || '').toLowerCase().trim())
+      ? ` On-screen numbers like "Terminal N" shift when a terminal closes, so they can't identify a lane — use a terminal's name or ref instead.`
+      : ''
+    return `No terminal matches "${terminal}". Call read_terminal with no argument to list the open terminals (refer to one by its name or ref).${extra}`
+  }
 
   let body
   if (hit.kind === 'agent') {
@@ -96,5 +137,52 @@ export const formatPeek = ({ selfId, sessions, terms, terminal, lines } = {}) =>
   } else {
     body = cleanPtyTail(hit.buf, n).join('\n') || '(no output yet)'
   }
-  return `Terminal ${ref(hit)} (${hit.kind} · ${hit.cmd}) — last ${n} lines:\n${body}`
+  return `Terminal ${label(hit)} (${hit.kind} · ${hit.cmd}) — last ${n} lines:\n${body}`
+}
+
+// ── Tier C: cross-terminal POST (directed, gated cross-lane action) ──────────
+// Pure gate for whether a session may post into a sibling lane on THIS call:
+// kill-switch, loop-breaker (hop), per-turn cap. The routing itself (sendTurn
+// into the target) lives in bridge.mjs — it needs the live session. Spec INV-4:
+// no text reaches a sibling without an approved code-perm; agent-originated turns
+// are hop-capped so two agents can't ping-pong forever.
+export const CROSSPOST = {
+  maxHop: 1,      // human turn = hop 0; an injected turn = hop 1, which CANNOT post onward
+  perTurnCap: 3,  // post_to_terminal calls allowed per turn
+}
+
+export const crossPostDecision = ({ hop = 0, postCount = 0, disabled = false } = {}, limits = CROSSPOST) => {
+  const o = { ...CROSSPOST, ...(limits || {}) }
+  if (disabled) return { ok: false, reason: 'Cross-terminal posting is disabled in this room.' }
+  if (hop >= o.maxHop) return { ok: false, reason: 'Cross-terminal hop limit reached — an agent reached via cross-post cannot itself post onward; a person must direct the next cross-terminal action.' }
+  if (postCount >= o.perTurnCap) return { ok: false, reason: `Cross-terminal post limit reached for this turn (${o.perTurnCap}).` }
+  return { ok: true }
+}
+
+// ── Tier C+: cross-terminal SPAWN (open a FRESH lane the agent owns) ──────────
+// Pure gate for whether a session may open a new terminal on THIS call. The
+// motivating bug: an agent dumped a fan-out into SIBLINGS that were already
+// working (a bridge release lane, a Q&A lane) because it had no way to make its
+// OWN lanes. spawn_terminal gives it fresh lanes; this gate keeps that from
+// becoming a fork bomb. Bounds, in order:
+//   • kill-switch (TP_SPAWN_OFF)
+//   • hop — a lane REACHED via cross-post/spawn (hop ≥ 1) cannot spawn onward, so
+//     a spawned agent can't recursively spawn (the loop breaker, mirrors CROSSPOST)
+//   • maxTerms — the hard live-terminal cap (matches openTerm's cap of 8); the
+//     real backstop, since spawned lanes are bounded by it regardless of turns
+//   • perTurnCap — a per-turn runaway breaker (mirrors PEEK/CROSSPOST)
+// liveCount is the caller's measured sessions.size + terms.size at call time.
+export const SPAWN = {
+  maxHop: 1,       // human turn = hop 0; a spawned/injected lane = hop ≥ 1, which CANNOT spawn onward
+  perTurnCap: 4,   // spawn_terminal calls allowed per turn (total still capped by maxTerms)
+  maxTerms: 8,     // hard cap on live terminals in the room (matches openTerm)
+}
+
+export const spawnDecision = ({ hop = 0, spawnCount = 0, liveCount = 0, disabled = false } = {}, limits = SPAWN) => {
+  const o = { ...SPAWN, ...(limits || {}) }
+  if (disabled) return { ok: false, reason: 'Spawning terminals is disabled in this room.' }
+  if (hop >= o.maxHop) return { ok: false, reason: 'Spawn limit reached — a terminal reached via cross-terminal cannot itself open further terminals; a person must open the next lane.' }
+  if (liveCount >= o.maxTerms) return { ok: false, reason: `Terminal cap (${o.maxTerms}) reached — close a terminal before opening another.` }
+  if (spawnCount >= o.perTurnCap) return { ok: false, reason: `Spawn limit reached for this turn (${o.perTurnCap}).` }
+  return { ok: true }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.83",
+  "version": "0.7.85",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {