thinkpool-pair 0.7.95 → 0.7.97

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

@@ -32,14 +32,16 @@ import os from 'node:os'
 import fs from 'node:fs'
 import path from 'node:path'
 import readline from 'node:readline'
-import { spawn, execSync } from 'node:child_process'
+import { spawn, execSync, execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { randomUUID } from 'node:crypto'
 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 { FLOW_CONDUCTOR_PROMPT, FLOW_LANE_PROMPT, buildConductorEnv } from './flow-conductor.mjs'
+import { createFlowWorktree } from './flow-worktree.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 +611,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 +687,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
     }
   })
 }
@@ -953,12 +1017,12 @@ function restoredTurnOpen(log) {
 // relay STRUCTURED events. onEvent → broadcast `code-event` + print locally +
 // persist to the host file; tool calls round-trip through the perm card; the
 // rolling log replays to joiners and survives bridge restarts (session-store).
-function openStructured({ id, model, resume, log, commands, mode, spawnedBy }) {
+function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rolePrompt, flowSessionId, flowTaskKey, cwd }) {
   if (sessions.has(id)) return
   // spawnedBy: set when this lane was Dispatched (spawn_terminal). Restored from the
   // session store so the Ensemble flag survives a bridge restart (else a respin
   // stripped it and the lane reverted to a plain tab — the t6 "no chip" bug).
-  const entry = { cmd: 'claude', kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: Array.isArray(commands) ? commands : undefined, mode, spawnedBy: spawnedBy || undefined }
+  const entry = { cmd: 'claude', kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: Array.isArray(commands) ? commands : undefined, mode, spawnedBy: spawnedBy || undefined, flowSessionId: flowSessionId || null, flowTaskKey: flowTaskKey || null, cwd: cwd || null }
   // C1 (RT-2): per-term contiguous seq counter. Seeded from the restored log's max
   // so a bridge restart resumes ABOVE every persisted seq — fresh events never reuse
   // an old seq, which is what keeps the between-turns restart dup-free (see
@@ -1063,6 +1127,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
@@ -1183,15 +1282,36 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy }) {
           return okText(`Closed agent lane ${target.ref}${target.name ? ` ("${target.name}")` : ''}.`)
         },
       ),
+      // Flow lane → mark this slice done (lane-done return path). Reads the lane's
+      // worktree HEAD as commit_sha (the atomic-revert target) + broadcasts
+      // flow-task-done → the room flips the task done + dispatches the next wave
+      // (slices whose deps just got satisfied).
+      tool(
+        'mark_flow_done',
+        "ThinkPool Flow ONLY — call this ONCE when your slice is built, RUNS, and meets its acceptance criteria. Records your latest commit as the slice's atomic-revert target and signals the room that this slice is done (which unblocks slices that depended on you). No arguments: your commit is read from your worktree. Do not call before your slice actually runs + meets acceptance.",
+        {},
+        async () => {
+          const okText = (t) => ({ content: [{ type: 'text', text: t }] })
+          if (!entry.flowSessionId || !entry.flowTaskKey) return okText('Not a Flow lane — nothing to mark done.')
+          let commitSha = null
+          try { commitSha = execFileSync('git', ['-C', entry.cwd || process.cwd(), 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim() } catch { /* no commits yet */ }
+          bcast('flow-task-done', { term: id, flowId: entry.flowSessionId, taskKey: entry.flowTaskKey, laneId: id, commitSha })
+          process.stderr.write(`\n  ${A.cyan}◆ flow slice done — ${entry.flowTaskKey} (${commitSha ? commitSha.slice(0, 8) : 'no commit'})${A.rst}\n`)
+          return okText(`Slice "${entry.flowTaskKey}" marked done${commitSha ? ` (commit ${commitSha.slice(0, 8)})` : ' (no commit yet — commit, then re-call)'}. The room records it + dispatches any slices that depended on you.`)
+        },
+      ),
     ],
   })
   entry.session = startClaudeSession({
-    cwd: process.cwd(), model, resume, mode,
+    cwd: cwd || process.cwd(), model, resume, mode, rolePrompt,
     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 },
+    // 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, ...buildConductorEnv({ flowSessionId, mode }), TP_MOCKUP_OUTBOX: mockupOutbox },
     onEvent: (evt) => {
       // Self-heal a stale resume — the saved SDK session expired. Reopen fresh,
       // keeping the transcript (scrollback survives; live context is gone).
@@ -1249,6 +1369,16 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy }) {
       emitTail(evt)
     },
     requestPermission: (req) => new Promise((resolve) => {
+      // FLOW conductor plan → intercept (no generic card). The plan JSON rides
+      // ExitPlanMode's `plan` arg. Broadcast to the room; its useFlow persists the
+      // task-graph + flips status → awaiting_approval → FlowPlanCard renders. Park
+      // the conductor ('keep' = stay in plan mode, idle; lane dispatch is Step 2).
+      if (entry.flowSessionId && req.risk === 'plan') {
+        bcast('flow-plan', { term: id, flowId: entry.flowSessionId, plan: req.plan || '' })
+        process.stderr.write(`\n  ${A.mag}◆ flow plan ready — flow ${String(entry.flowSessionId).slice(0, 8)}.${A.rst}\n`)
+        resolve('keep')
+        return
+      }
       // Keep the broadcast payload with the resolver so a reconnect can re-send it
       // (replay-request handler) — pending cards never enter the replayed event log.
       const payload = { term: id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk, plan: req.plan, questions: req.questions }
@@ -1364,6 +1494,63 @@ channel
     }
     shutdown()
   })
+  .on('broadcast', { event: 'flow-start' }, ({ payload }) => {
+    // Ensemble Flow — the room asks this bridge to launch a CONDUCTOR for a Flow run.
+    // The room already created the flow_sessions row (flowId); the conductor opens in
+    // plan mode (so ExitPlanMode is permitted), seeded with the build prompt. It
+    // decomposes → calls ExitPlanMode(planJson) → the requestPermission flow-plan branch
+    // broadcasts flow-plan back. `host` routes to one bridge in multi-machine rooms.
+    if (!payload?.flowId) return
+    if (payload.host && payload.host !== name) return
+    for (const [, e] of sessions) if (e.flowSessionId === payload.flowId) return   // already conducting this flow
+    const cid = randomUUID()
+    termNames[cid] = `Flow · ${String(payload.flowId).slice(0, 6)}`
+    saveNames(room, termNames)
+    openStructured({ id: cid, mode: 'plan', rolePrompt: FLOW_CONDUCTOR_PROMPT, flowSessionId: payload.flowId })
+    const ce = sessions.get(cid)
+    if (ce?.session) { try { ce.session.sendTurn(payload.prompt || '') } catch { /* session still starting */ } }
+    process.stderr.write(`\n  ${A.mag}◆ flow conductor launched — flow ${String(payload.flowId).slice(0, 8)} (plan mode).${A.rst}\n`)
+    announce()
+  })
+  .on('broadcast', { event: 'flow-dispatch' }, ({ payload }) => {
+    // Ensemble Flow — the room approved the plan + sends the READY tasks. Spawn one
+    // worktree-isolated lane per task (FLOW_LANE_PROMPT, its own git tree so lanes
+    // never collide — M57). Seed each lane with its slice spec, then echo the
+    // assignments back so the room marks the tasks dispatched + flips the flow to
+    // building (DB writes stay room-side, member-authed).
+    if (!payload?.flowId || !Array.isArray(payload.tasks)) return
+    if (payload.host && payload.host !== name) return
+    const assignments = []
+    for (const t of payload.tasks) {
+      try {
+        const { dir } = createFlowWorktree({ flowId: payload.flowId, taskKey: t.task_key })
+        const laneId = randomUUID()
+        termNames[laneId] = `Flow · ${t.task_key}`
+        saveNames(room, termNames)
+        openStructured({ id: laneId, cwd: dir, mode: 'acceptEdits', rolePrompt: FLOW_LANE_PROMPT, flowSessionId: payload.flowId, flowTaskKey: t.task_key, spawnedBy: `flow:${payload.flowId}` })
+        const le = sessions.get(laneId)
+        if (le?.session) {
+          const spec =
+            `[Flow lane — slice "${t.task_key}" of flow ${String(payload.flowId).slice(0, 8)}]\n` +
+            `TITLE: ${t.title}\n` +
+            `SCOPE (files you OWN — edit ONLY these): ${t.scope || '(none stated)'}\n` +
+            `ACCEPTANCE (done = this runs + proves it): ${t.acceptance || '(meet the title)'}\n` +
+            (t.deps && t.deps.length ? `DEPENDS ON (already built): ${t.deps.join(', ')}\n` : '') +
+            `\nProject (context): ${payload.flowPrompt || ''}\n\n` +
+            `Build your slice. Own only your files. Done = it runs + meets acceptance. Commit when done.`
+          try { le.session.sendTurn(spec) } catch { /* session still starting */ }
+        }
+        assignments.push({ task_key: t.task_key, laneId })
+      } catch (e) {
+        process.stderr.write(`\n  ${A.yel}◆ flow dispatch failed for ${t.task_key}: ${e?.message || e}${A.rst}\n`)
+      }
+    }
+    if (assignments.length) {
+      bcast('flow-dispatched', { term: 'flow', flowId: payload.flowId, assignments })
+      process.stderr.write(`\n  ${A.mag}◆ flow dispatched ${assignments.length} lane(s) — flow ${String(payload.flowId).slice(0, 8)}.${A.rst}\n`)
+      announce()
+    }
+  })
   .on('broadcast', { event: 'term-open' }, ({ payload }) => {
     if (!payload?.id || !payload?.cmd) return
     // Multi-bridge rooms: a targeted open is for ONE machine. Untargeted
@@ -1500,7 +1687,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, rolePrompt }) {
   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
@@ -406,6 +423,7 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
     // a bypass session still planned. Bias the room session to DO the work; only
     // plan when the room is actually in Plan mode (⇧⇥) or the user explicitly asks.
     appendSystemPrompt: [
+      ...(rolePrompt ? [rolePrompt] : []),
       'ENVIRONMENT (authoritative — overrides any user-global CLAUDE.md or memory that claims otherwise): You are Claude running inside a ThinkPool Code room, driven live by a user (and possibly a partner) from a phone or browser, via the thinkpool-pair bridge.',
       'You are NOT in cmux. cmux may be installed on this machine and appear in $PATH, but it did not spawn you and its automation/orchestration rules do not apply. If any loaded memory says "Claude Code lives inside cmux," it is describing direct terminal use, not this room — disregard it here. The runtime truth is the env: THINKPOOL_PAIR_ACCOUNT_CHILD / npm_lifecycle_script=thinkpool-pair mark a ThinkPool Code session.',
       'Bias strongly toward DOING the work, not planning it. For a normal "add / fix / change / build X" request, just make the change directly.',
@@ -420,7 +438,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/flow-conductor.mjs

@@ -0,0 +1,91 @@
+// Thinkpool Flow — the conductor brain.
+//
+// The conductor is a Claude agent session (run via startClaudeSession with
+// `rolePrompt: FLOW_CONDUCTOR_PROMPT`) whose Step-1 job is to DECOMPOSE a "build me
+// X" prompt into a task-graph of RUNNABLE slices + dependencies, then submit that
+// plan for human approval. It does not build or spawn lanes yet — dispatch is Step 2.
+// The plan lives in the task-graph store (DB), not in the conductor's chat context
+// (research move #1). Spec: docs/specs/2026-06-29-thinkpool-flow.md.
+
+// Bridge-local MIRROR of src/lib/flow/taskGraph.js — NOT a cross-package import.
+// The bridge ships as its own npm package (thinkpool-pair); `../src/...` does not
+// exist in the published tarball, only in a checkout. flow-task-graph.mjs is a
+// byte-identical copy, kept honest by bridge/flow-task-graph.sync.test.js (fails if
+// it drifts from the canonical src module). One logical source, two reachable copies.
+import { FLOW_MODE, FLOW_STATUS, normalizePlanOutput } from './flow-task-graph.mjs'
+
+// Re-export the shared plan normalizer so bridge callers import Flow pieces from one
+// place. The implementation lives in the shared model (src/lib/flow/taskGraph.js).
+export { normalizePlanOutput }
+
+// Prepended to the room's standard appendSystemPrompt for a Flow conductor session.
+// This prompt IS the moat — decomposition intelligence. Grounded in the Flow research
+// (docs/specs/2026-06-29-thinkpool-flow.md §Research sources): runtime-per-lane is the
+// moat, partition by file ownership, plan-in-store-not-context, right-size the slice
+// count (3 focused beats 7 scattered), explicit acyclic deps.
+export const FLOW_CONDUCTOR_PROMPT = [
+  'THINKPOOL FLOW — you are the CONDUCTOR of an ensemble build. Your job RIGHT NOW (Step 1) is to decompose the user\'s build request into a TASK-GRAPH: a set of RUNNABLE slices with explicit dependencies, then submit that plan for human approval. Do NOT start building and do NOT spawn lanes yet — that happens only after the user approves the plan (Step 2+).',
+
+  'DECOMPOSE INTO RUNNABLE SLICES. Each slice must be something ONE lane can build, RUN in its own browser-side WebContainer sandbox, observe, and self-correct INDEPENDENTLY. A slice that cannot run on its own is not a slice — split it or merge it until it is. The runtime (a lane running what it built) is the moat; slices that can\'t run break the whole model.',
+
+  'PARTITION BY FILE OWNERSHIP. Each slice MUST own a disjoint set of files/components — state the exact paths in `scope`. Two lanes editing the same file collide (a branch is NOT isolation when two lanes share a tree). If two slices want the same file, one depends on the other, or you split the file. State ownership precisely.',
+
+  'EXPLICIT ACYCLIC DEPENDENCIES. Every slice lists the keys of slices it depends on. Dependencies must form a DAG. A slice needing another\'s output (an API contract, a shared type, a layout component) depends on it. Minimize coupling — prefer independent slices that build in parallel.',
+
+  'ACCEPTANCE CRITERIA per slice: how does the lane know it is DONE AND RUNNING? A lane is done when its slice runs in its WebContainer and meets the criteria — not when it has merely written code. State the observable, runnable proof (e.g. "GET /api/todos returns 200 + []", "submitting the form adds a row to the list that persists across reload").',
+
+  'RIGHT-SIZE THE SLICE COUNT. Bias to FEW slices that each carry real weight, not many tiny ones. For a small app: 2-3 slices. Concurrent lanes are bounded (a low dispatch ceiling), so a flat fan-out of well-chosen slices beats a sprawling one. Three focused slices outperform seven scattered ones.',
+
+  'SUBMIT VIA ExitPlanMode — when the decomposition is ready, CALL the ExitPlanMode tool, passing your plan as ONE JSON object (a JSON string) in its `plan` argument. The room intercepts that call, validates the plan is a real DAG (acyclic, all deps resolve), persists it to the task-graph store, and shows a plan-approval card. A malformed plan is rejected and you will be asked to re-emit. Do not also narrate the plan in prose. The exact shape:',
+  '{ "summary": "<one line: what we are building>", "tasks": [ { "key": "<short-unique-kebab-key>", "title": "<imperative title>", "scope": "<files/components this lane owns>", "acceptance": "<runnable proof it is done>", "deps": ["<other-task-key>", ...], "sliceType": "feature|scaffold|review|fix" } ] }',
+  '`key` values are stable short kebab-case identifiers. `deps` references other tasks\' keys. Put ONLY the JSON in the ExitPlanMode plan argument (no surrounding prose, no markdown fences).',
+
+  'PLAN LIVES IN THE STORE, NOT THE CHAT. Your JSON plan is the artifact — it gets persisted to the task-graph (flow_sessions / flow_tasks) and rendered as an approval card. Do not ALSO narrate a long plan in prose. You may add 1-2 sentences framing the decomposition choice (why these slices, what was coupled), nothing more.',
+
+  'MODE-AWARE. The user picked a mode — steer (watch every lane live), guide (DEFAULT: approve this plan, then review at phase boundaries), or autopilot (full-auto with a budget cap + adaptive escalation that pulls them in only if a lane stalls). Produce the full plan now regardless; the mode changes how much the human intervenes later, not how you decompose.',
+].join(' ')
+
+// Env vars handed to a conductor session via startClaudeSession({ env }). The conductor
+// reads these to know which Flow run it owns + what mode the human picked.
+export function buildConductorEnv ({ flowSessionId, mode, budgetCapAutopilot = null }) {
+  return {
+    TP_FLOW_SESSION: flowSessionId,
+    TP_FLOW_MODE: mode,
+    ...(mode === FLOW_MODE.autopilot && budgetCapAutopilot != null
+      ? { TP_FLOW_BUDGET_CAP: String(budgetCapAutopilot) }
+      : {}),
+  }
+}
+
+// Status the FlowSession moves to once the conductor emits + the client validates a
+// plan (i.e. the plan-approval card can now be shown). Kept here so bridge + client
+// import the same transition target.
+export const PLAN_READY_STATUS = FLOW_STATUS.awaiting_approval
+
+// ── Lane builder ────────────────────────────────────────────────────────────
+// The conductor DECOMPOSES; a lane BUILDS one slice. Lanes dispatch after the human
+// approves the plan (Step 2). Each lane runs in its own git worktree (disjoint tree,
+// atomic-revert target). This prompt is the lane's rolePrompt (via startClaudeSession).
+export const FLOW_LANE_PROMPT = [
+  'THINKPOOL FLOW — you are ONE LANE in an ensemble build. The conductor already decomposed the project into RUNNABLE slices; you own exactly ONE. Your task (scope + acceptance + deps) arrives as your first message.',
+
+  'OWN YOUR FILES ONLY. The `scope` names the files/components this lane OWNS — they are DISJOINT from every other lane. Edit ONLY those. Touching another lane\'s files is a collision that breaks the merge — never do it. If you genuinely need a file outside your scope, STOP and say so instead of editing it.',
+
+  'DONE MEANS RUNS. You are not done when you\'ve written code — you\'re done when your slice RUNS and meets the `acceptance` criteria (the observable, runnable proof). Verify it yourself before declaring done. State the proof (the command, the output) when you finish.',
+
+  'COMMIT WHEN DONE, THEN SIGNAL. You are in your own git worktree on your own branch. When your slice meets acceptance — it RUNS and you have verified the proof — commit it atomically (one focused commit); that commit is the revert target if review later rejects it. Then call the `mark_flow_done` tool ONCE: it records your commit as this slice\'s revert target and tells the room the slice is done (which unblocks any slices depending on you). Do not push. Do NOT call mark_flow_done before your slice actually runs + meets acceptance.',
+
+  'STAY IN YOUR LANE. Do NOT spawn further lanes (one hop only — the fork-bomb breaker). Do NOT edit other worktrees. If you\'re blocked on a dependency that isn\'t ready, say so + stop — another lane is building it.',
+
+  'BE RIGOROUS, NOT VIBES. Trace the data path, root-cause before fixing, verify before claiming done. A lane that ships a guess costs the whole ensemble.',
+].join(' ')
+
+// Env vars handed to a lane session so it knows its Flow run + which task it owns.
+export function buildLaneEnv ({ flowSessionId, taskKey, laneId }) {
+  return {
+    TP_FLOW_SESSION: flowSessionId,
+    TP_FLOW_TASK_KEY: taskKey,
+    TP_FLOW_LANE_ID: laneId,
+  }
+}
+

package/flow-task-graph.mjs

@@ -0,0 +1,166 @@
+// Thinkpool Flow — task-graph data model.
+//
+// A Flow run = one FlowSession (the "build me X" prompt + mode + status) decomposed
+// by the conductor into FlowTasks (RUNNABLE slices + dependencies). The plan lives
+// HERE, in the store, not in the conductor's chat context — research move #1
+// (docs/specs/2026-06-29-thinkpool-flow.md): "move the plan out of the context
+// window into a task-graph." Pure module — shared by the bridge (conductor) and the
+// client (room UI), and mirrored by CHECK constraints in the
+// 20260629120000_flow_sessions_tasks migration (one source of truth).
+
+export const FLOW_STATUS = {
+  planning: 'planning',                // conductor is decomposing
+  awaiting_approval: 'awaiting_approval', // plan submitted, waiting on the human
+  approved: 'approved',                // human approved; lanes may dispatch (Step 2+)
+  building: 'building',                // lanes are running
+  reviewing: 'reviewing',              // adversarial-review phase
+  assembling: 'assembling',            // merging worktrees
+  done: 'done',
+  failed: 'failed',
+  cancelled: 'cancelled',
+}
+
+export const TASK_STATUS = {
+  pending: 'pending',
+  ready: 'ready',                      // deps satisfied, awaiting dispatch
+  dispatched: 'dispatched',            // a lane is running it
+  reviewing: 'reviewing',              // adversarial-review lane is checking it
+  done: 'done',
+  failed: 'failed',
+  reverted: 'reverted',                // rolled back by the atomic-revert net
+}
+
+export const FLOW_MODE = {
+  steer: 'steer',                      // human watches every lane, live
+  guide: 'guide',                      // phase-gated (DEFAULT): approve plan + phase reviews
+  autopilot: 'autopilot',              // full-auto, adaptive escalation + budget cap
+}
+
+export const SLICE_TYPE = {
+  feature: 'feature',
+  scaffold: 'scaffold',                // project bootstrap / shared foundation
+  review: 'review',                    // adversarial-review lane
+  fix: 'fix',
+}
+
+// A FlowTask slice. Each is RUNNABLE — a lane can build + run + self-correct it in
+// its own WebContainer (research: the runtime is the moat). Partition by file
+// ownership (scope) so two lanes never edit the same file (a branch is NOT isolation).
+export function makeTask ({ key, title, scope = '', acceptance = '', deps = [], sliceType = SLICE_TYPE.feature }) {
+  if (!key || typeof key !== 'string') throw new Error('task key required (string)')
+  if (!title) throw new Error('task title required')
+  if (!Array.isArray(deps)) throw new Error('deps must be an array of task keys')
+  if (!Object.values(SLICE_TYPE).includes(sliceType)) throw new Error(`unknown sliceType: ${sliceType}`)
+  return {
+    key,
+    title,
+    scope,            // files/components this lane OWNS (disjoint from other slices)
+    acceptance,       // runnable proof the lane + reviewer use to call it done
+    deps,             // task keys this depends on (must form a DAG)
+    sliceType,
+    status: TASK_STATUS.pending,
+    laneId: null,     // the spawned lane's terminal id, once dispatched
+    commitSha: null,  // per-lane atomic commit (revert target)
+    failCount: 0,     // adaptive-escalation counter (Autopilot pulls human in at N)
+  }
+}
+
+// Validate that tasks form a real DAG: unique keys, every dep references an existing
+// key, no self-deps, no cycles. Throws on invalid. Returns the tasks (chainable).
+export function validateDag (tasks) {
+  if (!Array.isArray(tasks) || tasks.length === 0) throw new Error('at least one task required')
+  const keys = new Set(tasks.map(t => t.key))
+  if (keys.size !== tasks.length) throw new Error('duplicate task keys')
+  const byKey = new Map(tasks.map(t => [t.key, t]))
+  for (const t of tasks) {
+    if (t.deps.includes(t.key)) throw new Error(`task "${t.key}" depends on itself`)
+    for (const d of t.deps) {
+      if (!keys.has(d)) throw new Error(`task "${t.key}" depends on unknown task "${d}"`)
+    }
+  }
+  // Cycle detection (DFS, three-color). byKey guaranteed complete by the checks above.
+  const WHITE = 0, GRAY = 1, BLACK = 2
+  const color = new Map(tasks.map(t => [t.key, WHITE]))
+  function visit (k) {
+    color.set(k, GRAY)
+    for (const d of byKey.get(k).deps) {
+      const c = color.get(d)
+      if (c === GRAY) throw new Error(`cycle detected at "${k}" → "${d}"`)
+      if (c === WHITE) visit(d)
+    }
+    color.set(k, BLACK)
+  }
+  for (const t of tasks) if (color.get(t.key) === WHITE) visit(t.key)
+  return tasks
+}
+
+// Tasks whose deps are all DONE → ready to dispatch. Pure.
+export function readyTasks (tasks) {
+  const done = new Set(tasks.filter(t => t.status === TASK_STATUS.done).map(t => t.key))
+  return tasks.filter(t =>
+    t.status === TASK_STATUS.pending &&
+    t.deps.every(d => done.has(d))
+  )
+}
+
+// Topological order (Kahn's algorithm). Returns keys. Throws if not a DAG.
+export function topoOrder (tasks) {
+  validateDag(tasks)
+  const indeg = new Map(tasks.map(t => [t.key, t.deps.length]))
+  const dependents = new Map(tasks.map(t => [t.key, []])) // dep-key → keys that depend on it
+  for (const t of tasks) for (const d of t.deps) dependents.get(d).push(t.key)
+  const queue = tasks.filter(t => indeg.get(t.key) === 0).map(t => t.key)
+  const order = []
+  while (queue.length) {
+    const k = queue.shift()
+    order.push(k)
+    for (const m of dependents.get(k)) {
+      indeg.set(m, indeg.get(m) - 1)
+      if (indeg.get(m) === 0) queue.push(m)
+    }
+  }
+  if (order.length !== tasks.length) throw new Error('cycle detected (topo incomplete)')
+  return order
+}
+
+// A FlowSession (the run). `tasks` is the decomposed plan (FlowTask[]).
+export function makeFlowSession ({ prompt, mode = FLOW_MODE.guide, sessionRef = null, budgetCapAutopilot = null }) {
+  if (!prompt) throw new Error('prompt required')
+  if (!Object.values(FLOW_MODE).includes(mode)) throw new Error(`unknown mode: ${mode}`)
+  return {
+    prompt,
+    mode,
+    sessionRef,            // the /code room session id this Flow runs in
+    status: FLOW_STATUS.planning,
+    budgetCapAutopilot,    // token/step cap (Autopilot only); null in guide/steer
+    createdAt: null,       // stamped by the DB
+    tasks: [],
+  }
+}
+
+// Normalize the conductor's raw plan output into a validated { summary, tasks }.
+// Accepts a parsed object OR a JSON string (optionally ```json-fenced). Throws if the
+// tasks don't form a real DAG. Lives in this shared module so neither the bridge nor
+// the client has to import across the bridge↔src boundary.
+export function normalizePlanOutput (raw) {
+  let obj = raw
+  if (typeof raw === 'string') {
+    let s = raw.trim()
+    const fence = s.match(/```(?:json)?\s*([\s\S]*?)```/i)
+    if (fence) s = fence[1].trim()
+    obj = JSON.parse(s)
+  }
+  if (!obj || typeof obj !== 'object') throw new Error('plan output is not an object')
+  const summary = typeof obj.summary === 'string' && obj.summary.trim() ? obj.summary.trim() : ''
+  if (!Array.isArray(obj.tasks) || obj.tasks.length === 0) throw new Error('plan has no tasks')
+  const tasks = obj.tasks.map((t) => makeTask({
+    key: String(t.key),
+    title: String(t.title ?? t.key),
+    scope: String(t.scope ?? ''),
+    acceptance: String(t.acceptance ?? ''),
+    deps: Array.isArray(t.deps) ? t.deps.map(String) : [],
+    sliceType: Object.values(SLICE_TYPE).includes(t.sliceType) ? t.sliceType : SLICE_TYPE.feature,
+  }))
+  validateDag(tasks)
+  return { summary, tasks }
+}

package/flow-worktree.mjs

@@ -0,0 +1,53 @@
+// Thinkpool Flow — per-lane git worktree isolation.
+//
+// A Flow task-lane builds its slice in its OWN worktree. A branch is NOT isolation
+// when ≥2 lanes share one working tree (M57) — two lanes editing files in the shared
+// checkout collide. A worktree gives each lane a disjoint tree + its own branch, and
+// that branch is the atomic-revert target (commit_sha on flow_tasks, Step 4).
+//
+// Pure over injected git/fs so it's unit-testable against a temp repo.
+// Spec: docs/specs/2026-06-29-thinkpool-flow.md (Step 2).
+
+import { execFileSync } from 'node:child_process'
+import path from 'node:path'
+import fs from 'node:fs'
+
+const ROOT = process.cwd()   // the bridge's checkout (the shared main repo root)
+
+// The lane's branch + directory for a (flowId, taskKey). Deterministic so a
+// re-dispatch of the same task reuses the same worktree.
+export function worktreeSpec ({ flowId, taskKey, root = ROOT }) {
+  const wtRoot = path.join(root, '.claude', 'worktrees')
+  const short = String(flowId).replace(/-/g, '').slice(0, 8)
+  const safeKey = String(taskKey).toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 40).replace(/^-+|-+$/g, '') || 'task'
+  const branch = `flow/${short}/${safeKey}`
+  const dir = path.join(wtRoot, `flow-${short}-${safeKey}`)
+  return { branch, dir, wtRoot }
+}
+
+// Create a worktree for a task-lane off `base` (default origin/main). Idempotent: if
+// the dir already holds a worktree, reuse it. Returns { dir, branch, created }.
+export function createFlowWorktree ({ flowId, taskKey, base = 'origin/main', root = ROOT, git = runGit }) {
+  const { branch, dir, wtRoot } = worktreeSpec({ flowId, taskKey, root })
+  if (fs.existsSync(path.join(dir, '.git'))) return { dir, branch, created: false }
+  fs.mkdirSync(wtRoot, { recursive: true })
+  try {
+    git(['worktree', 'add', '-b', branch, dir, base], root)
+  } catch {
+    // Branch already exists (a prior dispatch of this task) — check it out instead.
+    git(['worktree', 'add', dir, branch], root)
+  }
+  return { dir, branch, created: true }
+}
+
+// Remove a lane's worktree + delete its branch (on revert / cancel / flow cancel).
+// Best-effort: missing worktree/branch is not an error.
+export function removeFlowWorktree ({ flowId, taskKey, root = ROOT, git = runGit }) {
+  const { branch, dir } = worktreeSpec({ flowId, taskKey, root })
+  try { git(['worktree', 'remove', dir, '--force'], root) } catch { /* already gone */ }
+  try { git(['branch', '-D', branch], root) } catch { /* already gone */ }
+}
+
+function runGit (args, cwd) {
+  return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.95",
+  "version": "0.7.97",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -16,6 +16,9 @@
     "transcript-sanitize.mjs",
     "session-store.mjs",
     "cross-terminal.mjs",
+    "flow-conductor.mjs",
+    "flow-worktree.mjs",
+    "flow-task-graph.mjs",
     "serve-dir.mjs",
     "service.mjs",
     "presence.mjs",