thinkpool-pair 0.7.95 → 0.7.96

package/account.mjs

@@ -17,6 +17,7 @@ import { saveAuth, loadAuth, loadDirs, bindDir, loadServed, rememberServed } fro
 import { isSafeToRestart } from './update-gate.mjs'
 import { makeThrottledTrack } from './presence.mjs'
 import { resolveServeDir } from './serve-dir.mjs'
+import { pairKeyFor, pairTopic, CROSSROOM_BUS } from './cross-terminal.mjs'
 
 const VERSION = (() => { try { return JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version } catch { return null } })()
 
@@ -236,7 +237,21 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
   // target room's child and relays the reply back. roomNames feeds list_sessions; pairPending
   // maps an in-flight peek's reqId → the room that asked, so the target's reply finds its way home.
   const roomNames = new Map()  // room -> display name (for list_sessions)
-  const pairPending = new Map() // reqId -> asking room code (for read_session reply routing)
+  // pairPending: reqId -> { reply, askerRoom }. `reply(m)` delivers a target child's
+  // pair-*-res back to its origin — a local asker child (Tier 1/local Tier 3) OR the
+  // pair bus (a partner's request, Tier 2/3). askerRoom (or null for bus origin) lets
+  // a dead-room cleanup drop only its own in-flight entries.
+  const pairPending = new Map()
+  // ── Tier 2/3 cross-MACHINE pair bus ─────────────────────────────────────────
+  // The supervisor is the IPC↔bus bridge: it joins one per-pair Supabase channel
+  // (tppair:<pairKey>, RLS-gated to the two real partners) per distinct partner, and
+  // relays peek/post requests between a local room child and the partner's supervisor.
+  // Spec: docs/specs/2026-06-30-cross-room-pair-bus.md
+  const roomPartner = new Map()   // room -> the OTHER participant's uid (the pair partner), for 2-person rooms
+  const pairChannels = new Map()  // partnerUid -> { channel, key } (one bus per distinct partner)
+  const busWaiters = new Map()    // nonce -> { mode:'first'|'collect', resolve, timer, acc? } for OUR outbound bus requests
+  const postBucket = new Map()    // partnerUid -> { count, resetAt } inbound cross-room-post rate limit (runaway-cost backstop)
+  const POST_BUCKET = { max: 6, windowMs: 60_000 }   // ≤6 inbound cross-room posts / partner / minute
   let applyRequested = false   // a user clicked "apply" in some room (Slice 3)
   let pendingUpdate = null     // newest published version once the poll sees it
   const warned = new Set()
@@ -361,6 +376,99 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
     }
   }
 
+  // ── pair-bus plumbing (function declarations hoist, so order here is free) ──
+  // Resolve one of OUR outbound bus requests. 'first' resolves on the first reply
+  // (peek/post — a single partner answers); 'collect' accumulates every reply within
+  // the window (list — several partners may each answer) and resolves when it closes.
+  const resolveBus = (payload) => {
+    if (!payload?.nonce) return
+    const w = busWaiters.get(payload.nonce)
+    if (!w) return
+    if (w.mode === 'collect') { w.acc.push(payload); return }
+    clearTimeout(w.timer); busWaiters.delete(payload.nonce); w.resolve(payload)
+  }
+  const busSendAll = (event, payload) => {
+    let sent = 0
+    for (const { channel } of pairChannels.values()) { try { channel.send({ type: 'broadcast', event, payload }); sent++ } catch { /* channel down */ } }
+    return sent
+  }
+  const busRequestFirst = (event, payload, timeoutMs) => new Promise((resolve) => {
+    const nonce = randomUUID()
+    if (!busSendAll(event, { ...payload, nonce })) return resolve(null)
+    const timer = setTimeout(() => { busWaiters.delete(nonce); resolve(null) }, timeoutMs); timer.unref?.()
+    busWaiters.set(nonce, { mode: 'first', resolve, timer })
+  })
+  const busRequestCollect = (event, payload, windowMs) => new Promise((resolve) => {
+    const nonce = randomUUID()
+    if (!busSendAll(event, { ...payload, nonce })) return resolve([])
+    const acc = []
+    const timer = setTimeout(() => { busWaiters.delete(nonce); resolve(acc) }, windowMs); timer.unref?.()
+    busWaiters.set(nonce, { mode: 'collect', acc, resolve, timer })
+  })
+  // Inbound cross-room-post rate limit, per partner (a partner's agent posting into
+  // MY rooms spends MY tokens — the runaway-cost backstop, on top of the per-turn cap).
+  const allowInboundPost = (partnerUid) => {
+    const now = Date.now()
+    let b = postBucket.get(partnerUid)
+    if (!b || now >= b.resetAt) { b = { count: 0, resetAt: now + POST_BUCKET.windowMs }; postBucket.set(partnerUid, b) }
+    if (b.count >= POST_BUCKET.max) return false
+    b.count++; return true
+  }
+
+  // ── bus REQUEST handlers (a partner's supervisor → me). partnerUid is bound per
+  // channel, so a request arriving on partner P's bus is trusted as from P (the
+  // channel is RLS-gated to {me, P}); I only ever answer for rooms I serve AND share
+  // with P (roomPartner === P) — defense in depth behind the channel firewall.
+  const onPeerListReq = (partnerUid, ch, payload) => {
+    if (process.env.TP_PAIRBUS_OFF === '1') return
+    const rooms = [...children.keys()].filter((r) => roomPartner.get(r) === partnerUid).map((r) => ({ code: r, name: roomNames.get(r) || null, host: machine }))
+    try { ch.send({ type: 'broadcast', event: 'peer-list-res', payload: { nonce: payload?.nonce, rooms } }) } catch { /* channel down */ }
+  }
+  const onPeerPeekReq = (partnerUid, ch, payload) => {
+    const reply = (extra) => { try { ch.send({ type: 'broadcast', event: 'peer-peek-res', payload: { nonce: payload?.nonce, ...extra } }) } catch { /* channel down */ } }
+    if (process.env.TP_PAIRBUS_OFF === '1') return reply({ error: 'Cross-session reach is off on this device.' })
+    const target = String(payload?.targetRoom || '').toUpperCase().trim()
+    const tc = children.get(target)
+    if (!tc || roomPartner.get(target) !== partnerUid) return reply({ error: `Room ${target} is not a room this device shares with you.` })
+    const reqId = randomUUID()
+    pairPending.set(reqId, { reply: (mm) => reply({ text: mm.text, error: mm.error }), askerRoom: null })
+    try { tc.send({ t: 'pair-peek-local', reqId, terminal: payload.terminal, lines: payload.lines }) }
+    catch { pairPending.delete(reqId); reply({ error: `Could not reach room ${target}.` }) }
+  }
+  const onPeerPostReq = (partnerUid, ch, payload) => {
+    const reply = (extra) => { try { ch.send({ type: 'broadcast', event: 'peer-post-res', payload: { nonce: payload?.nonce, ...extra } }) } catch { /* channel down */ } }
+    if (process.env.TP_PAIRBUS_OFF === '1') return reply({ error: 'Cross-room posting is off on this device.' })
+    if (!allowInboundPost(partnerUid)) return reply({ error: 'Too many cross-room posts to this device right now — try again shortly.' })
+    const target = String(payload?.targetRoom || '').toUpperCase().trim()
+    const tc = children.get(target)
+    if (!tc || roomPartner.get(target) !== partnerUid) return reply({ error: `Room ${target} is not a room this device shares with you.` })
+    const reqId = randomUUID()
+    pairPending.set(reqId, { reply: (mm) => reply({ ok: mm.ok, ref: mm.ref, error: mm.error }), askerRoom: null })
+    try { tc.send({ t: 'pair-post-local', reqId, fromRoom: payload.fromRoom, fromHost: payload.fromHost, text: payload.text, terminal: payload.terminal }) }
+    catch { pairPending.delete(reqId); reply({ error: `Could not reach room ${target}.` }) }
+  }
+  // Join the per-pair bus for `partnerUid` (idempotent). The channel is PRIVATE so
+  // Realtime Authorization (RLS on realtime.messages, migration 20260630120000) gates
+  // both join and broadcast to the two real partners — a stranger never joins.
+  const subscribePairBus = (partnerUid, key) => {
+    if (!partnerUid || pairChannels.has(partnerUid)) return
+    const topic = pairTopic(key); if (!topic) return
+    const ch = sb.channel(topic, { config: { private: true, broadcast: { self: false } } })
+    ch.on('broadcast', { event: 'peer-list-req' }, ({ payload }) => onPeerListReq(partnerUid, ch, payload))
+      .on('broadcast', { event: 'peer-list-res' }, ({ payload }) => resolveBus(payload))
+      .on('broadcast', { event: 'peer-peek-req' }, ({ payload }) => onPeerPeekReq(partnerUid, ch, payload))
+      .on('broadcast', { event: 'peer-peek-res' }, ({ payload }) => resolveBus(payload))
+      .on('broadcast', { event: 'peer-post-req' }, ({ payload }) => onPeerPostReq(partnerUid, ch, payload))
+      .on('broadcast', { event: 'peer-post-res' }, ({ payload }) => resolveBus(payload))
+      .subscribe()
+    pairChannels.set(partnerUid, { channel: ch, key })
+    process.stderr.write(`\n  ◆ pair bus open — cross-machine Ensemble reach with your partner.\n`)
+  }
+  // Forward a local child's cross-room request to the bus (Tier 2 peek / Tier 3 post)
+  // when the target room is NOT served on this machine. Used inside the child handler.
+  const busPeek = (targetRoom, terminal, lines) => busRequestFirst('peer-peek-req', { targetRoom, terminal, lines }, CROSSROOM_BUS.busTimeoutMs)
+  const busPost = (targetRoom, terminal, text, fromRoom) => busRequestFirst('peer-post-req', { targetRoom, terminal, text, fromRoom, fromHost: machine }, 180_000)
+
   const tick = async () => {
     // Hold the account claim before serving anything (cross-machine guard). When
     // standing by, make sure we're serving nothing and wait for the next tick.
@@ -377,7 +485,7 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
       // as a guest — spawning your machine into another owner's session that already
       // runs its own bridge. The web watches tpacct:<session-owner>, so a
       // participant's bridge is duplication the UI never even looks at.
-      const { data } = await sb.from('code_sessions').select('code,name,last_active_at,owner_id').eq('owner_id', session.user.id).order('last_active_at', { ascending: false }).limit(20)
+      const { data } = await sb.from('code_sessions').select('code,name,last_active_at,owner_id,participants').eq('owner_id', session.user.id).order('last_active_at', { ascending: false }).limit(20)
       rooms = data || []
     } catch { /* transient — keep existing children, retry next tick */ }
     const dirs = loadDirs()
@@ -429,46 +537,98 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
         if (!m) return
         if (m.t === 'idle') { childIdle.set(room, !!m.idle); childBetween.set(room, m.between != null ? !!m.between : !!m.idle); childPeer.set(room, !!m.webPeer) }
         else if (m.t === 'apply-update') { applyRequested = true; applyIfIdle() }   // user clicked the chip
-        // ── Thinkpool Ensemble cross-ROOM routing (Tier 1, read-only) ──────────
+        // ── Thinkpool Ensemble cross-ROOM routing ──────────────────────────────
         // `room` here is the room that sent the message (this closure is per-child).
+        // A target room may be LOCAL (another child on this machine — Tier 1 peek /
+        // local Tier 3 post) or REMOTE (the partner's machine, over the pair bus —
+        // Tier 2 peek / cross-machine Tier 3 post). list merges both.
         else if (m.t === 'pair-list-req') {
-          // The asking room's OTHER sessions on this machine (same account = "your other rooms").
-          const off = process.env.TP_CROSSROOM_OFF === '1'
-          const others = off ? [] : [...children.keys()].filter((r) => r !== room).map((r) => ({ code: r, name: roomNames.get(r) || null }))
-          try { child.send({ t: 'pair-list-res', reqId: m.reqId, rooms: others, ...(off ? { error: 'Cross-session reach is turned off on this bridge.' } : {}) }) } catch { /* child gone */ }
+          ;(async () => {
+            if (process.env.TP_CROSSROOM_OFF === '1') { try { child.send({ t: 'pair-list-res', reqId: m.reqId, rooms: [], error: 'Cross-session reach is turned off on this bridge.' }) } catch { /* child gone */ } return }
+            const local = [...children.keys()].filter((r) => r !== room).map((r) => ({ code: r, name: roomNames.get(r) || null }))
+            let remote = []
+            if (process.env.TP_PAIRBUS_OFF !== '1' && pairChannels.size) {
+              const replies = await busRequestCollect('peer-list-req', {}, 1200)
+              remote = replies.flatMap((p) => (Array.isArray(p?.rooms) ? p.rooms : []))
+            }
+            try { child.send({ t: 'pair-list-res', reqId: m.reqId, rooms: [...local, ...remote] }) } catch { /* child gone */ }
+          })()
         }
         else if (m.t === 'pair-peek-req') {
-          const reply = (extra) => { try { child.send({ t: 'pair-peek-res', reqId: m.reqId, ...extra }) } catch { /* child gone */ } }
-          if (process.env.TP_CROSSROOM_OFF === '1') return reply({ error: 'Cross-session reach is turned off on this bridge.' })
-          const target = String(m.targetRoom || '').toUpperCase().trim()
-          if (!target || target === room) return reply({ error: `${target || 'That'} is not another of your active sessions on this machine.` })
-          const tc = children.get(target)
-          if (!tc) return reply({ error: `Session ${target} is not running on this machine right now (only sessions this account is actively serving here are reachable).` })
-          pairPending.set(m.reqId, room)   // remember who asked so the reply routes home
-          try { tc.send({ t: 'pair-peek-local', reqId: m.reqId, fromRoom: room, terminal: m.terminal, lines: m.lines }) }
-          catch { pairPending.delete(m.reqId); reply({ error: `Could not reach session ${target}.` }) }
+          ;(async () => {
+            const reply = (extra) => { try { child.send({ t: 'pair-peek-res', reqId: m.reqId, ...extra }) } catch { /* child gone */ } }
+            if (process.env.TP_CROSSROOM_OFF === '1') return reply({ error: 'Cross-session reach is turned off on this bridge.' })
+            const target = String(m.targetRoom || '').toUpperCase().trim()
+            if (!target || target === room) return reply({ error: `${target || 'That'} is not another of your active sessions.` })
+            const tc = children.get(target)
+            if (tc) {   // LOCAL target — forward to that child; route its reply home
+              const reqId = randomUUID()
+              pairPending.set(reqId, { reply: (mm) => reply({ text: mm.text, error: mm.error }), askerRoom: room })
+              try { tc.send({ t: 'pair-peek-local', reqId, terminal: m.terminal, lines: m.lines }) }
+              catch { pairPending.delete(reqId); reply({ error: `Could not reach session ${target}.` }) }
+              return
+            }
+            // REMOTE target — ask the pair bus(es).
+            if (process.env.TP_PAIRBUS_OFF === '1' || !pairChannels.size) return reply({ error: `Session ${target} is not running on this machine, and no pair bus is open to reach it.` })
+            const res = await busPeek(target, m.terminal, m.lines)
+            if (!res) return reply({ error: `Room ${target} did not respond — it may be offline, or not shared with you.` })
+            reply({ text: res.text, error: res.error })
+          })()
+        }
+        else if (m.t === 'pair-post-req') {   // Tier 3 cross-room post (sender card already approved)
+          ;(async () => {
+            const reply = (extra) => { try { child.send({ t: 'pair-post-res', reqId: m.reqId, ...extra }) } catch { /* child gone */ } }
+            if (process.env.TP_PAIRBUS_OFF === '1') return reply({ error: 'Cross-room posting is turned off on this bridge.' })
+            const target = String(m.targetRoom || '').toUpperCase().trim()
+            if (!target || target === room) return reply({ error: `${target || 'That'} is not another of your sessions.` })
+            const tc = children.get(target)
+            if (tc) {   // LOCAL target — the target child raises its own receipt card
+              const reqId = randomUUID()
+              pairPending.set(reqId, { reply: (mm) => reply({ ok: mm.ok, ref: mm.ref, error: mm.error }), askerRoom: room })
+              try { tc.send({ t: 'pair-post-local', reqId, fromRoom: room, fromHost: machine, text: m.text, terminal: m.terminal }) }
+              catch { pairPending.delete(reqId); reply({ error: `Could not reach session ${target}.` }) }
+              return
+            }
+            // REMOTE target — over the pair bus.
+            if (!pairChannels.size) return reply({ error: `Room ${target} is not on this machine, and no pair bus is open to reach it.` })
+            const res = await busPost(target, m.terminal, m.text, room)
+            if (!res) return reply({ error: `Room ${target} did not respond to the hand-off in time.` })
+            reply({ ok: res.ok, ref: res.ref, error: res.error })
+          })()
         }
-        else if (m.t === 'pair-peek-res') {
-          // A target child answered — route its reply back to the room that asked.
-          const askerRoom = pairPending.get(m.reqId)
-          if (askerRoom == null) return
+        else if (m.t === 'pair-peek-res' || m.t === 'pair-post-res') {
+          // A target child answered — deliver via the stored reply fn (to a local
+          // asker child, or back onto the pair bus for a partner's request).
+          const w = pairPending.get(m.reqId)
+          if (!w) return
           pairPending.delete(m.reqId)
-          const asker = children.get(askerRoom)
-          if (asker) { try { asker.send({ t: 'pair-peek-res', reqId: m.reqId, text: m.text, error: m.error, fromRoom: room }) } catch { /* asker gone */ } }
+          try { w.reply(m) } catch { /* reply path gone */ }
         }
       })
       child.on('exit', () => {
-        children.delete(room); childIdle.delete(room); childBetween.delete(room); childPeer.delete(room); roomNames.delete(room)   // re-served on the next tick
-        // Fail any in-flight cross-room peeks waiting on (or asked by) this dead room.
-        for (const [reqId, askerRoom] of pairPending) {
-          if (askerRoom !== room) continue
-          pairPending.delete(reqId)
-        }
+        children.delete(room); childIdle.delete(room); childBetween.delete(room); childPeer.delete(room); roomNames.delete(room); roomPartner.delete(room)   // re-served on the next tick
+        // Fail any in-flight cross-room peeks/posts this dead room had ASKED (bus-origin
+        // entries have askerRoom null and just time out on their own).
+        for (const [reqId, w] of pairPending) { if (w?.askerRoom === room) pairPending.delete(reqId) }
       })
       // If an update is already pending, tell the freshly-served child immediately so
       // its room shows the "update ready" chip without waiting for the next poll.
       if (pendingUpdate) { try { child.send({ t: 'update-available', version: pendingUpdate }) } catch { /* child not ready */ } }
     }
+    // ── reconcile pair buses (Tier 2/3) — derive each served 2-person room's partner
+    // and join that pair's bus. One channel per DISTINCT partner (many shared rooms →
+    // one bus). roomPartner feeds the bus handlers' "is this room shared with P" check.
+    if (process.env.TP_PAIRBUS_OFF !== '1') {
+      for (const r of rooms) {
+        if (!r?.code || !children.has(r.code)) continue   // only rooms we actually serve
+        const parts = Array.isArray(r.participants) ? r.participants : []
+        const partner = parts.length === 2 ? parts.find((p) => p && p !== session.user.id) : null
+        if (!partner) { roomPartner.delete(r.code); continue }
+        roomPartner.set(r.code, partner)
+        const key = pairKeyFor(session.user.id, partner)
+        if (key) subscribePairBus(partner, key)
+      }
+    }
     pushPresence()
   }
 
@@ -484,6 +644,7 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
     keepFresh.cancel()
     releaseSingleton()
     for (const c of children.values()) { try { c.kill(sig || 'SIGTERM') } catch { /* noop */ } }
+    for (const { channel } of pairChannels.values()) { try { sb.removeChannel(channel) } catch { /* noop */ } }   // tear down pair buses (Tier 2/3)
     // Flush the presence LEAVE before exiting so the dashboard flips to
     // "not connected" in realtime (don't fire-and-forget the untrack).
     ;(async () => { try { if (claimHeld) await sb.rpc('release_bridge', { p_bridge_id: BRIDGE_ID }) } catch { /* noop */ } try { await acct.untrack() } catch { /* noop */ } try { await sb.removeChannel(acct) } catch { /* noop */ } process.exit(code) })()

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, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, CROSSROOM, formatPairRoster } from './cross-terminal.mjs'
+import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, CROSSROOM, formatPairRoster, crossRoomPostDecision } from './cross-terminal.mjs'
 import { turnInFlight } from './update-gate.mjs'
 import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames, appendDurableEvents, seedDurableEvents, readDurablePage, readDurableOldestSeq } from './session-store.mjs'
 import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks } from './event-id.mjs'
@@ -609,13 +609,68 @@ function pairRequest(type, payload = {}, timeoutMs = 4000) {
     catch { clearTimeout(timer); pairWaiters.delete(reqId); resolve({ error: 'Could not reach the account bridge.' }) }
   })
 }
+// ── Tier 3 — raise a standalone permission card on a target session ──────────
+// The cross-ROOM post lands here on the RECEIVING side: a person in THIS room must
+// approve the incoming task before it injects (the second half of dual consent —
+// the sender's room already approved sending). Reuses the exact pending/code-perm
+// plumbing the SDK uses for tool cards, so the existing code-perm broadcast resolves
+// it and drainPending() fails it safe to 'deny' if the room closes. Module-scope so
+// the IPC listener (which is not inside openStructured's closure) can call it.
+function raiseCard(entry, req) {
+  return new Promise((resolve) => {
+    if (!entry?.pending) return resolve('deny')
+    const payload = { term: entry.id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk }
+    entry.pending.set(req.id, { resolve, payload })
+    bcast('code-perm-req', payload)
+    process.stderr.write(`\n  ● incoming cross-room task for ${String(entry.id).slice(0, 8)} — approve in the room.\n`)
+  })
+}
+
+// Receive a cross-ROOM post (Tier 3) routed to THIS room by the supervisor. Resolve
+// the target agent lane, raise the receipt card, and on approval inject the turn one
+// room-hop deep (so the reached agent can read/peek but cannot post onward to a third
+// room — crossRoomPostDecision blocks roomHop≥1). Returns { ok, ref } or { error }.
+async function receiveCrossRoomPost({ fromRoom, fromHost, text, terminal }) {
+  if (process.env.TP_PAIRBUS_OFF === '1') return { error: 'Cross-room posting is turned off in this room.' }
+  const body = String(text || '').trim()
+  if (!body) return { error: 'Empty cross-room post ignored.' }
+  const sib = siblingsOf({ selfId: null, sessions, terms, names: termNames })
+  let targetId = null
+  if (terminal) {
+    const hit = resolveSibling(sib, terminal)
+    if (hit && hit.kind !== 'agent') return { error: `Terminal ${hit.ref} in room ${room} is a shell, not an agent — cross-room posts go to agents only.` }
+    targetId = hit?.id || null
+  } else {
+    const agentIds = [...sessions.keys()]
+    if (agentIds.length === 1) targetId = agentIds[0]   // unambiguous → no need to name a lane
+  }
+  if (!targetId) {
+    const agents = sib.filter((x) => x.kind === 'agent')
+    return { error: agents.length ? `Name which agent lane in room ${room} to deliver to (${agents.map((a) => a.ref).join(', ')}).` : `No agent terminal is open in room ${room} to receive this.` }
+  }
+  const te = sessions.get(targetId)
+  if (!te?.session) return { error: `That terminal in room ${room} is no longer live.` }
+  const fromLabel = `${fromRoom}${fromHost ? ` on ${fromHost}` : ''}`
+  let decision = 'deny'
+  try { decision = await raiseCard(te, { id: randomUUID(), toolName: 'mcp__thinkpool__post_to_session', input: { session: fromRoom, host: fromHost, text: body, incoming: true }, risk: 'high' }) } catch { decision = 'deny' }
+  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
+  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 }
+  stampEvent(evt); pushLog(te, evt); bcast('code-event', { term: targetId, evt })
+  try { te.session.sendTurn(msg) } catch { return { error: `Could not deliver to room ${room} — the lane may have just closed.` } }
+  return { ok: true, ref: String(targetId).slice(0, 8) }
+}
+
 if (IS_ACCOUNT_CHILD) {
   // A SECOND message listener (Node allows many) dedicated to pair traffic — leaves
   // the account-child idle/token listener (bottom of file) untouched.
   process.on('message', (m) => {
     if (!m || !m.t) return
     // Reply to one of OUR outbound cross-room requests → resolve the waiter.
-    if (m.t === 'pair-list-res' || m.t === 'pair-peek-res') {
+    if (m.t === 'pair-list-res' || m.t === 'pair-peek-res' || m.t === 'pair-post-res') {
       const w = pairWaiters.get(m.reqId)
       if (!w) return
       clearTimeout(w.timer); pairWaiters.delete(m.reqId)
@@ -630,6 +685,13 @@ if (IS_ACCOUNT_CHILD) {
       try { text = formatPeek({ selfId: null, sessions, terms, names: termNames, terminal: m.terminal, lines: m.lines }) }
       catch { error = 'Could not read that session.' }
       try { process.send({ t: 'pair-peek-res', reqId: m.reqId, text, error }) } catch { /* parent gone */ }
+      return
+    }
+    // We are the TARGET of a cross-ROOM post (Tier 3) — raise the receipt card and,
+    // if a person approves, inject the task. Async: the human may take a while.
+    if (m.t === 'pair-post-local') {
+      receiveCrossRoomPost(m).then((res) => { try { process.send({ t: 'pair-post-res', reqId: m.reqId, ...res }) } catch { /* parent gone */ } })
+      return
     }
   })
 }
@@ -1063,6 +1125,41 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy }) {
           return okText(res?.text || `Room ${target} returned nothing.`)
         },
       ),
+      // Tier 3 cross-ROOM POST — directed, DUAL-CONSENT hand-off into another of
+      // your rooms (your own on this machine, or your partner's over the pair bus).
+      // Strictly bounded because it spends real model tokens in another room, maybe
+      // on another person's machine (the runaway-cost class): the SENDER's room
+      // approves sending (PreToolUse card, claude-session.mjs), the SUPERVISOR routes
+      // it (locally over IPC or across the pair bus), and the TARGET room raises its
+      // OWN receipt card — no text reaches the other agent without a person at BOTH
+      // ends. crossRoomPostDecision caps it at one per turn and blocks a room reached
+      // via cross-room post from posting onward. Kill-switch: TP_PAIRBUS_OFF.
+      tool(
+        'post_to_session',
+        'Hand a task or message to an agent in ANOTHER of your ThinkPool Code sessions — your own room on this machine, or your partner\'s room reachable through the pair (a room code from list_sessions). Pass `session` (the room code), `text` (what to send), and optionally `terminal` (which agent lane in that room). A person in YOUR room approves sending AND a person in the TARGET room approves receiving before it is delivered. An agent reached this way cannot post onward to a third room. Read the target with read_session first, and use this sparingly — only when the people clearly want the rooms to coordinate.',
+        {
+          session: z.string().describe('the room code of the other session (from list_sessions)'),
+          text: z.string().describe('the message or task to deliver to that room\'s agent'),
+          terminal: z.string().optional().describe('ref/name of the agent lane in that room; omit if it has a single agent'),
+        },
+        async (args) => {
+          const okText = (t) => ({ content: [{ type: 'text', text: t }] })
+          // Defensive re-check (the sender card already passed in PreToolUse).
+          const gate = crossRoomPostDecision({ roomHop: entry.roomHop || 0, postCount: entry.crossRoomPostCount || 0, disabled: process.env.TP_PAIRBUS_OFF === '1' })
+          if (!gate.ok) return okText(gate.reason)
+          const target = String(args?.session || '').toUpperCase().trim()
+          if (!target) return okText('Name a room code to post to (call list_sessions to see your rooms).')
+          if (target === room) return okText('That is this room — use post_to_terminal for an agent in your own room.')
+          const text = String(args?.text || '').trim()
+          if (!text) return okText('Nothing to send — provide the task or message text.')
+          entry.crossRoomPostCount = (entry.crossRoomPostCount || 0) + 1
+          // Generous timeout: the TARGET room's person must approve a receipt card,
+          // which can take a while. Fails soft (never hangs the turn) past the window.
+          const res = await pairRequest('pair-post-req', { targetRoom: target, terminal: args?.terminal, text, fromRoom: room }, 180_000)
+          if (res?.error) return okText(res.error)
+          return okText(res?.ok ? `Delivered to room ${target}${res.ref ? ` (lane ${res.ref})` : ''} — it will respond in its own room; check back with read_session.` : `Room ${target} did not accept the message.`)
+        },
+      ),
       // 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
@@ -1191,6 +1288,9 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy }) {
     // 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' }),
+    // Tier 3 — the SENDER-side gate for post_to_session (the receipt card lives in
+    // the target room). roomHop/crossRoomPostCount reset on a real human turn (code-turn).
+    crossRoomPostGate: () => crossRoomPostDecision({ roomHop: entry.roomHop || 0, postCount: entry.crossRoomPostCount || 0, disabled: process.env.TP_PAIRBUS_OFF === '1' }),
     env: { ...process.env, TP_MOCKUP_OUTBOX: mockupOutbox },
     onEvent: (evt) => {
       // Self-heal a stale resume — the saved SDK session expired. Reopen fresh,
@@ -1500,7 +1600,9 @@ channel
     s.peekCount = 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
     s.hop = 0
+    s.roomHop = 0   // a human turn is room-hop 0 — clears any injected cross-room hop depth
     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, crossPostGate }) {
+export function startClaudeSession({ cwd, model, resume, env, mode: initialMode = 'default', onEvent, requestPermission, mcpServers, crossPostGate, crossRoomPostGate }) {
   const ac = new AbortController()
   let input = makeInputStream()   // `let`: auto-restart swaps in a fresh stream
   let sessionId = resume || null
@@ -253,10 +253,12 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
     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-ROOM READ (Tier 1: list_sessions / read_session) is read-only and
-    // reaches ONLY the account's own other rooms on this machine (the supervisor only
-    // serves owned rooms) — same trust class as read_terminal, so auto-allow. Posting
-    // across rooms is a later tier and will gate on a card at both ends.
+    // ThinkPool cross-ROOM READ (list_sessions / read_session) is read-only. It reaches
+    // the account's own other rooms on this machine (Tier 1) and the partner's rooms on
+    // the pair bus (Tier 2) — both firewalled server-side (the supervisor only serves
+    // owned rooms; the pair channel is RLS-gated to the two real partners), so it is the
+    // same trust class as read_terminal → auto-allow. POSTING across rooms
+    // (post_to_session) is NOT read-only — it gates on a card at both ends below.
     if (toolName === 'mcp__thinkpool__list_sessions' || toolName === 'mcp__thinkpool__read_session') {
       return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: 'Auto-approved (read-only ThinkPool cross-session read — your own rooms).' } }
     }
@@ -301,6 +303,21 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
       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.' } }
     }
+    // ThinkPool cross-ROOM POST (Tier 3) WRITES into ANOTHER room's agent — possibly
+    // on another person's machine. This is the SENDER-side gate (the recipient room
+    // raises its OWN receipt card before anything injects — dual consent). Same shape
+    // as post_to_terminal: a bridge-side precheck (kill-switch / roomHop / per-turn
+    // cap) so a blocked post never raises a card, then a 'high'-risk human card here.
+    if (toolName === 'mcp__thinkpool__post_to_session') {
+      const gate = crossRoomPostGate ? crossRoomPostGate() : { ok: true }
+      if (!gate.ok) {
+        return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: gate.reason || 'Cross-room 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-room post approved in the sending room — the target room will be asked to accept it.' : 'Cross-room 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
@@ -420,7 +437,8 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
       '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. A spawned lane INHERITS your current permission mode by default — so if you are in bypass, your lanes run autonomously with no per-action clicking; pass `mode` only to override. Raising a lane to bypass from a non-bypass lane asks the room to confirm once (everything else spawns without a prompt). 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: a few new lanes per turn, a per-plan dispatch ceiling on concurrent spawned lanes (Free 3 / Plus 6) that is separate from the human terminals so it never blocks them, an overall room machine cap, 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.',
-      'CROSS-SESSION AWARENESS: the Ensemble reaches across your SESSIONS, not just the terminals in this room. You have two READ-ONLY tools for your OTHER ThinkPool Code rooms running on this machine: list_sessions() lists them (room code + name), and read_session(session, terminal?) reads recent activity inside one (omit `terminal` to list that room\'s terminals, or pass a ref/name from it to read that lane). Reach for them when work spans your rooms — "what\'s the other project up to", "pick up where the other session left off", or to check a long-running task in another room before you act here. They only ever read — they never change another session, and they reach ONLY your own rooms (never a stranger\'s). This works only when your sessions run under the ThinkPool account bridge; a standalone room sees just its own terminals. Posting work INTO another session is not available yet — for now, read across sessions and coordinate with the people in the room.',
+      '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. All of this works only under the ThinkPool account bridge; a standalone room sees just its own terminals.',
       '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

@@ -225,7 +225,62 @@ export const formatPairRoster = (rooms, { thisRoom, error } = {}) => {
     if (!r || !r.code || r.code === thisRoom || seen.has(r.code)) return false
     seen.add(r.code); return true
   })
-  if (!list.length) return 'No other sessions of yours are open on this machine right now. (Cross-session reach is limited to rooms this account is actively running here.)'
-  const rows = list.map((r) => `- ${r.code}${r.name ? ` · "${r.name}"` : ''}`)
-  return `Your other ThinkPool Code sessions on this machine (call read_session with a room code to look inside one):\n${rows.join('\n')}`
+  if (!list.length) return 'No other sessions of yours are open right now. (Cross-session reach is limited to rooms this account is running here, plus your partner\'s rooms in the same pair.)'
+  // `host` is set for a Tier-2 cross-MACHINE room (it lives on a partner's Mac,
+  // reached over the pair bus); a same-machine Tier-1 room has none. Rendering the
+  // host tells the agent (and the people) which rooms are "over there".
+  const rows = list.map((r) => `- ${r.code}${r.name ? ` · "${r.name}"` : ''}${r.host ? ` · on ${r.host}` : ''}`)
+  return `Your other ThinkPool Code sessions (call read_session with a room code to look inside one):\n${rows.join('\n')}`
+}
+
+// ── Tier 2 cross-MACHINE peek — the pair bus ─────────────────────────────────
+// Tier 1 reached the account's OTHER rooms on the SAME machine over Node IPC.
+// Tier 2 reaches a PARTNER's rooms on ANOTHER machine over a per-pair Supabase
+// Broadcast channel, `tppair:<pairKey>`. The firewall IS the channel: only the
+// two people who actually share a 2-person room can join it (RLS on
+// realtime.messages, server-side) — so a supervisor never even hears a stranger's
+// room, and there's no client-side trust to get wrong. pairKeyFor builds the
+// IDENTICAL channel name on both Macs from the two participant UUIDs, so they meet
+// on the same bus without coordinating. Spec: docs/specs/2026-06-30-cross-room-pair-bus.md
+export const CROSSROOM_BUS = {
+  busTimeoutMs: 4000,   // a cross-MACHINE round-trip fails soft after this (never hangs a turn)
+}
+
+// Deterministic, order-INDEPENDENT channel key for the pair {a, b}: lowercased,
+// sorted, dot-joined. Both Macs derive the same string from the shared room's two
+// participants, so they subscribe to the same tppair channel. Returns null unless
+// given two DISTINCT uuids — a self-only "pair" (one participant) has no partner on
+// another machine to reach, so it gets no bus.
+export const pairKeyFor = (a, b) => {
+  const x = String(a == null ? '' : a).toLowerCase().trim()
+  const y = String(b == null ? '' : b).toLowerCase().trim()
+  if (!x || !y || x === y) return null
+  return x < y ? `${x}.${y}` : `${y}.${x}`
+}
+
+// The realtime topic both supervisors subscribe to for a pair. The two UUIDs in the
+// name are not secrets (they're already in tpacct:<uid>), and the RLS policy re-derives
+// + verifies membership server-side; the name is just the rendezvous point.
+export const pairTopic = (key) => key ? `tppair:${key}` : null
+
+// ── Tier 3 cross-ROOM POST — directed, dual-consent, possibly cross-machine ──
+// Posting work INTO another room (yours on this machine, or a partner's over the
+// pair bus). Deliberately TIGHTER than the in-room cross-TERMINAL post (CROSSPOST):
+// it spends real model tokens in another room — maybe on another person's machine —
+// so (a) the per-turn cap starts at ONE, (b) a room reached VIA a cross-room post
+// cannot post onward (roomHop loop-breaker), and (c) BOTH ends gate on a person:
+// the sender's room approves the send, the recipient's room approves the receipt.
+// The bridge enforces (a)+(b) here; the dual cards live in the gate + the web.
+// Kill-switch: TP_PAIRBUS_OFF (the same switch that disables the bus).
+export const CROSSROOM_POST = {
+  maxRoomHop: 1,          // human turn = roomHop 0; a turn injected via cross-room post = 1, which CANNOT post onward
+  crossRoomPostCap: 1,    // post_to_session calls allowed per human turn (tighter than in-room CROSSPOST.perTurnCap)
+}
+
+export const crossRoomPostDecision = ({ roomHop = 0, postCount = 0, disabled = false } = {}, limits = CROSSROOM_POST) => {
+  const o = { ...CROSSROOM_POST, ...(limits || {}) }
+  if (disabled) return { ok: false, reason: 'Cross-room posting is turned off on this bridge.' }
+  if (roomHop >= o.maxRoomHop) return { ok: false, reason: 'Cross-room hop limit reached — a room reached via a cross-room post cannot itself post into another room; a person must direct the next cross-room action.' }
+  if (postCount >= o.crossRoomPostCap) return { ok: false, reason: `Cross-room post limit reached for this turn (${o.crossRoomPostCap}).` }
+  return { ok: true }
 }

package/package.json

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