thinkpool-pair 0.7.28 → 0.7.30

package/account.mjs

@@ -14,6 +14,7 @@ import fs from 'node:fs'
 import { createClient } from '@supabase/supabase-js'
 import os from 'node:os'
 import { saveAuth, loadAuth, loadDirs, bindDir } from './auth-store.mjs'
+import { isSafeToRestart } from './update-gate.mjs'
 
 const VERSION = (() => { try { return JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version } catch { return null } })()
 
@@ -208,6 +209,9 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
 
   const children = new Map()   // room -> child process
   const childIdle = new Map()  // room -> bool (last idle report; unknown = not idle)
+  const childPeer = new Map()  // room -> bool (a web client is watching this room)
+  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()
 
   // Account presence — so the web dashboard can show "● Bridge active" for this
@@ -277,8 +281,17 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
       delete env.THINKPOOL_PAIR_AUTOUPDATE
       const child = spawn(process.execPath, [BRIDGE, room, '--headless', '--auto=claude'], { cwd: dir, stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })
       children.set(room, child)
-      child.on('message', (m) => { if (m && m.t === 'idle') childIdle.set(room, !!m.idle) })
-      child.on('exit', () => { children.delete(room); childIdle.delete(room) })   // re-served on the next tick
+      childIdle.set(room, false)   // unknown until it reports → never restart a fresh child
+      childPeer.set(room, false)
+      child.on('message', (m) => {
+        if (!m) return
+        if (m.t === 'idle') { childIdle.set(room, !!m.idle); childPeer.set(room, !!m.webPeer) }
+        else if (m.t === 'apply-update') { applyRequested = true; applyIfIdle() }   // user clicked the chip
+      })
+      child.on('exit', () => { children.delete(room); childIdle.delete(room); childPeer.delete(room) })   // re-served on the next tick
+      // 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 */ } }
     }
     pushPresence()
   }
@@ -299,6 +312,16 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
   }
   for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => stop(sig))
 
+  // ── Slice 3 apply-gate (function scope so the child-IPC handler can call it) ──
+  // Restart the account bridge to apply a pending update ONLY when it's safe: every
+  // child idle (between turns) AND either a user clicked apply OR nobody's watching
+  // (unattended fallback). The predicate is unit-tested (tests/update-gate.test.mjs).
+  const applyIfIdle = () => {
+    if (!isSafeToRestart({ pendingUpdate, stopping, childIdle, childPeer, requested: applyRequested })) return
+    process.stderr.write(`\n  ◆ thinkpool-pair ${pendingUpdate} ready (running ${VERSION}) — restarting account bridge to update; sessions resume.\n`)
+    stop('SIGTERM')   // graceful: children persist + leave presence; exit 0 → service reruns @latest
+  }
+
   // ── auto-update (account-service tier only) ───────────────────────────────
   // launchd (KeepAlive) / systemd (Restart=always) re-run `npx -y
   // thinkpool-pair@latest` (no room) on every restart, so a clean exit here
@@ -312,7 +335,6 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
   //   THINKPOOL_PAIR_UPDATE_IDLE      child idle seconds before a restart (default 90)
   if (process.env.THINKPOOL_PAIR_AUTOUPDATE === '1' && VERSION) {
     const POLL_MS = Math.max(60, parseInt(process.env.THINKPOOL_PAIR_UPDATE_INTERVAL, 10) || 1800) * 1000
-    let pendingUpdate = null
     // Strictly-newer x.y.z core; ignore prerelease tails (never downgrade/churn).
     const isNewer = (latest, cur) => {
       const core = (v) => String(v).split('-')[0].split('.').map((n) => parseInt(n, 10) || 0)
@@ -330,20 +352,15 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
         return typeof j?.version === 'string' ? j.version : null
       } catch { return null } finally { clearTimeout(to) }
     }
-    // Idle iff every served child has reported idle. No children → trivially idle.
-    // Unknown (no report yet) counts as NOT idle, so we never cycle a fresh child.
-    const allIdle = () => { for (const room of children.keys()) if (!childIdle.get(room)) return false; return true }
-    const applyIfIdle = () => {
-      if (!pendingUpdate || stopping || !allIdle()) return
-      process.stderr.write(`\n  ◆ thinkpool-pair ${pendingUpdate} ready (running ${VERSION}) — restarting account bridge to update; sessions resume.\n`)
-      stop('SIGTERM')   // graceful: children persist + leave presence; exit 0 → service reruns @latest
-    }
     const check = async () => {
       const latest = await fetchLatest()
       if (latest && isNewer(latest, VERSION)) {
-        if (!pendingUpdate) process.stderr.write(`\n  ◆ thinkpool-pair ${latest} published — will restart at the next idle moment (all sessions quiet).\n`)
+        if (!pendingUpdate) process.stderr.write(`\n  ◆ thinkpool-pair ${latest} published — "update ready" surfaced to each room; applies between turns.\n`)
         pendingUpdate = latest
-        applyIfIdle()
+        // Tell every served child so its room shows the chip (children never self-update;
+        // only this supervisor restart re-resolves @latest). Slice 3 nudge.
+        for (const c of children.values()) { try { c.send({ t: 'update-available', version: latest }) } catch { /* child not ready */ } }
+        applyIfIdle()   // unattended fallback fires here when no room has a web peer
       }
     }
     setInterval(check, POLL_MS).unref()

package/bridge.mjs

@@ -33,9 +33,11 @@ import fs from 'node:fs'
 import path from 'node:path'
 import readline from 'node:readline'
 import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
 import { randomUUID } from 'node:crypto'
 import { createClient } from '@supabase/supabase-js'
 import { startClaudeSession } from './claude-session.mjs'
+import { turnInFlight } from './update-gate.mjs'
 import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames } from './session-store.mjs'
 import { stampEvent } from './event-id.mjs'
 
@@ -154,6 +156,42 @@ applyProviderEnv()
 if (argv[0] === 'login') { const { runLogin } = await import('./account.mjs'); await runLogin(SUPABASE_URL, SUPABASE_ANON, WEB_BASE) }
 if (argv[0] === 'bind')  { const { runBind }  = await import('./account.mjs'); runBind(argv[1], argv[2]) }
 if (argv[0] === 'provider') { const { runProvider } = await import('./provider.mjs'); await runProvider(argv.slice(1)); process.exit(0) }
+
+// One-command launcher: a bare invocation on a TTY (or the `setup` alias) opens the
+// interactive menu instead of going straight to account mode. The menu only ASSEMBLES
+// existing commands — it re-execs `<ROOM>`, or calls installService / runLogin /
+// runProvider / runAccount directly. Non-TTY bare stays account-mode (the line below),
+// so launchd / systemd / CI / pipes are byte-for-byte unchanged.
+// Spec: docs/specs/2026-06-19-bridge-unified-launcher.md (Part 1).
+if ((!argv[0] || argv[0] === 'setup') && process.stdin.isTTY) {
+  const { runLauncher } = await import('./launcher.mjs')
+  const svc = await import('./service.mjs')
+  const BRIDGE = fileURLToPath(import.meta.url)
+  const io = {
+    print: (s) => process.stderr.write(s + '\n'),
+    ask: (q) => new Promise((res) => {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stderr })
+      rl.question(q, (a) => { rl.close(); res(String(a).trim()) })
+    }),
+  }
+  const actions = {
+    // Re-exec the bridge with the assembled argv; the child owns the terminal and the
+    // parent waits, exiting with the child's code (so Ctrl-C / exit behave normally).
+    pairRoom: ({ room, agentCmd, resumeArgs = [], headless }) => new Promise(() => {
+      const args = [BRIDGE, room, ...(headless ? ['--headless'] : []), '--', agentCmd, ...resumeArgs]
+      const child = spawn(process.execPath, args, { stdio: 'inherit' })
+      child.on('exit', (code) => process.exit(code == null ? 0 : code))
+    }),
+    serveAccountForeground: async () => { const { runAccount } = await import('./account.mjs'); await runAccount(SUPABASE_URL, SUPABASE_ANON) },
+    installService: ({ room = null, agentCmd } = {}) => { svc.installService(room, agentCmd ? [agentCmd] : []); process.exit(0) },
+    uninstallService: ({ room = null } = {}) => { svc.uninstallService(room); process.exit(0) },
+    login: async () => { const { runLogin } = await import('./account.mjs'); await runLogin(SUPABASE_URL, SUPABASE_ANON, WEB_BASE) },
+    setProvider: async ({ kind, base, token }) => { const { runProvider } = await import('./provider.mjs'); await runProvider(kind === 'custom' ? ['custom', '--base', base, '--token', token] : ['anthropic']); process.exit(0) },
+  }
+  await runLauncher({ actions, io })
+  process.exit(0)
+}
+
 if (!argv[0] || argv[0].startsWith('-')) { const { runAccount } = await import('./account.mjs'); await runAccount(SUPABASE_URL, SUPABASE_ANON) }
 
 const room = (argv[0] || '').toUpperCase().trim()
@@ -329,6 +367,23 @@ let shuttingDown = false
 let lastActivity = Date.now()
 const markActivity = () => { lastActivity = Date.now() }
 
+// ── Slice 3: update-ready nudge state ──────────────────────────────
+// The newest published version once the update poll (service tier) or the account
+// supervisor (via IPC) reports one is out. Surfaced to the room as the "update
+// ready" chip; the restart is gated to between turns (never mid-turn, Contract #1).
+let pendingUpdate = null
+let applyRequested = false   // a user clicked "apply" in the room
+// A web client (not another bridge) is present — checks presence metas for a
+// non-bridge role. Gates the unattended auto-restart: when someone's watching we
+// wait for their apply click instead of restarting under them.
+const webPeerPresent = () => {
+  try {
+    const st = channel.presenceState() || {}
+    for (const metas of Object.values(st)) for (const m of (metas || [])) if (m && m.role !== 'bridge') return true
+  } catch { /* noop */ }
+  return false
+}
+
 const bcast = (event, payload) => {
   if (event === 'pty-out' || event === 'code-event') lastActivity = Date.now()
   try {
@@ -351,6 +406,9 @@ const announce = () =>
     // cwd + version: the host's working dir + thinkpool-pair version, shown in
     // the room's welcome banner. Re-sent per announce so late joiners get them.
     cwd, version: VERSION,
+    // pendingUpdate: a newer thinkpool-pair is out — drives the room's "update ready"
+    // chip; re-sent per announce so reloads/late-joiners see it (Slice 3).
+    pendingUpdate,
     // updir: where room file-drops land (forward-slash normalised — the web
     // client string-joins host paths onto it; Node accepts `/` on Windows).
     updir: UPDIR.split(path.sep).join('/'),
@@ -602,7 +660,10 @@ function openStructured({ id, model, resume, log, commands, mode }) {
       if (evt.kind === 'system' && Array.isArray(evt.commands) && evt.commands.length && !entry.commands) { entry.commands = evt.commands; announce(); persist() }
       // Chrome events (mode / usage / clear / compact) are transient state, not
       // transcript — broadcast + print them but keep out of the persisted/replayed log.
-      const chrome = evt.kind === 'mode' || evt.kind === 'usage' || evt.kind === 'clear' || evt.kind === 'compact'
+      // 'stalled' is transient turn-liveness state (would replay as a stale frozen
+      // banner if persisted); 'compaction' is a real transcript milestone (the recap
+      // card) and is intentionally NOT chrome, so it persists + replays.
+      const chrome = evt.kind === 'mode' || evt.kind === 'usage' || evt.kind === 'clear' || evt.kind === 'compact' || evt.kind === 'stalled'
       // compact turn finished (or errored) → clear the pulsing indicator.
       // No "done" ctl line — the SDK's own output in the transcript is the
       // signal (compact summary on success, AbortError text on abort/too-small).
@@ -665,6 +726,16 @@ function endStructured(id) {
   if (s) announce()
 }
 
+// Slice 3 — surface a pending update to the room as the "update ready" chip:
+// broadcast a chrome code-event per structured term + stash it on the announce so
+// reloads/late-joiners see it too. The restart itself is gated to between turns.
+function surfaceUpdate(version) {
+  if (!version || pendingUpdate === version) return
+  pendingUpdate = version
+  for (const id of sessions.keys()) bcast('code-event', { term: id, evt: { kind: 'update-available', version } })
+  announce()
+}
+
 // After the attached CLI exits, the host's stdin stops feeding a PTY —
 // restore the cooked terminal so Ctrl-C reaches the bridge itself.
 const detachLocal = () => {
@@ -867,6 +938,18 @@ channel
   .on('broadcast', { event: 'code-close' }, ({ payload }) => {
     endStructured(payload?.id)
   })
+  // Slice 3 — the user clicked "apply" on the update chip. Mark it requested; the
+  // actual restart is gated to between turns. Account-child: forward to the
+  // supervisor (it owns the restart, applied only when every child is idle).
+  // Standalone service tier: its applyIfIdle loop lands it at the next idle. Either
+  // way it never interrupts a turn (Contract #1).
+  .on('broadcast', { event: 'apply-update' }, () => {
+    if (!pendingUpdate) return
+    applyRequested = true
+    if (process.send && process.env.THINKPOOL_PAIR_ACCOUNT_CHILD === '1') {
+      try { process.send({ t: 'apply-update' }) } catch { /* parent gone */ }
+    }
+  })
   // Persist + re-announce terminal renames. The web also echoes term-rename to
   // online peers directly; storing it here is what reaches a device that joins
   // LATER (or a second machine) — those only ever see the announce.
@@ -948,9 +1031,9 @@ setInterval(() => {
 if (process.env.THINKPOOL_PAIR_AUTOUPDATE === '1' && VERSION) {
   const POLL_MS = Math.max(60, parseInt(process.env.THINKPOOL_PAIR_UPDATE_INTERVAL, 10) || 1800) * 1000
   const IDLE_MS = Math.max(10, parseInt(process.env.THINKPOOL_PAIR_UPDATE_IDLE, 10) || 90) * 1000
-  let pendingUpdate = null   // the newer version string, once seen
-
+  // pendingUpdate is module-level now (shared with surfaceUpdate + the room chip).
   const isIdle = () => {
+    if (turnInFlight(sessions)) return false                  // a structured turn is live
     if (Date.now() - lastActivity < IDLE_MS) return false
     for (const t of terms.values()) if (t.buf) return false   // bytes mid-flush
     return true
@@ -974,14 +1057,18 @@ if (process.env.THINKPOOL_PAIR_AUTOUPDATE === '1' && VERSION) {
   }
   const applyIfIdle = () => {
     if (!pendingUpdate || !isIdle()) return
+    // Slice 3: when a web client is watching, wait for their "apply" click instead
+    // of restarting under them. With nobody present (cloud VM / closed tab) the
+    // unattended fallback still auto-applies at idle so headless boxes self-heal.
+    if (!applyRequested && webPeerPresent()) return
     process.stderr.write(`\n  ◆ thinkpool-pair ${pendingUpdate} ready (running ${VERSION}) — restarting to update; the session resumes.\n`)
     shutdown(0, false)   // clean teardown (no farewell banner); service reruns @latest, session-store resumes
   }
   const check = async () => {
     const latest = await fetchLatest()
     if (latest && isNewer(latest, VERSION)) {
-      if (!pendingUpdate) process.stderr.write(`\n  ◆ thinkpool-pair ${latest} published — will restart at the next idle moment.\n`)
-      pendingUpdate = latest
+      if (!pendingUpdate) process.stderr.write(`\n  ◆ thinkpool-pair ${latest} published — "update ready" in the room; applies between turns.\n`)
+      surfaceUpdate(latest)   // sets pendingUpdate + broadcasts the chip + re-announces
       applyIfIdle()
     }
   }
@@ -995,11 +1082,16 @@ if (process.env.THINKPOOL_PAIR_AUTOUPDATE === '1' && VERSION) {
   // the supervisor can pick a moment when EVERY child is idle to restart-update.
   const IDLE_MS = Math.max(10, parseInt(process.env.THINKPOOL_PAIR_UPDATE_IDLE, 10) || 90) * 1000
   const idleNow = () => {
+    if (turnInFlight(sessions)) return false                  // a structured turn is live
     if (Date.now() - lastActivity < IDLE_MS) return false
     for (const t of terms.values()) if (t.buf) return false   // bytes mid-flush
     return true
   }
-  setInterval(() => { try { process.send({ t: 'idle', idle: idleNow() }) } catch { /* parent gone */ } }, 5000).unref()
+  // The supervisor owns updates (children never self-update). It IPCs us when a newer
+  // version is out → surface the chip; we report idle + whether a web peer is present
+  // so it restarts only between turns and only when nobody is mid-click (Slice 3).
+  process.on('message', (m) => { if (m && m.t === 'update-available') surfaceUpdate(m.version) })
+  setInterval(() => { try { process.send({ t: 'idle', idle: idleNow(), webPeer: webPeerPresent() }) } catch { /* parent gone */ } }, 5000).unref()
 } else if (VERSION) {
   // Foreground run (not the supervised service): it can't self-restart, but
   // nudge once if a newer version is out so a relaunch with @latest picks it up.

package/claude-session.mjs

@@ -141,8 +141,24 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
   // per turn on `result`.
   let turnBaseOut = 0             // output tokens from completed messages this turn
   let curMsgOut = 0               // latest output_tokens for the in-flight message
+  // ── stall watchdog (C2) — stream silence ≠ done; a turn can stall (deltas pause
+  // 3+ min) or abort silently with no `result`. Track turn liveness + last event
+  // time; if an active turn goes quiet past STALL_MS, emit one `stalled` chrome
+  // event so the room can stop showing a frozen "working" forever. Cleared on the
+  // next event / `result`. Refs: TS SDK #44, claude-code #38905.
+  const STALL_MS = Math.max(30000, parseInt(process.env.TP_STALL_MS, 10) || 120000)
+  let turnActive = false          // true between a sent turn and its `result`
+  let lastEvtTs = Date.now()      // wall-clock of the most recent emitted event
+  let stalledSent = false         // one `stalled` per stall, not a storm
 
-  const emit = (evt) => { try { onEvent?.(evt) } catch { /* never let a consumer throw into the loop */ } }
+  const emit = (evt) => { lastEvtTs = Date.now(); if (evt && evt.kind !== 'stalled') stalledSent = false; try { onEvent?.(evt) } catch { /* never let a consumer throw into the loop */ } }
+  const stallTimer = setInterval(() => {
+    if (turnActive && !stalledSent && Date.now() - lastEvtTs > STALL_MS) {
+      stalledSent = true
+      emit({ kind: 'stalled', sinceMs: Date.now() - lastEvtTs })
+    }
+  }, 5000)
+  stallTimer.unref?.()
 
   // Apply a permission-mode change to the live SDK *outside* any hook callback.
   // setPermissionMode is a streaming control request; awaiting it from INSIDE the
@@ -319,6 +335,13 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
               if (turnBaseOut + curMsgOut === 0) emit({ kind: 'thinking_tokens', tokens: m.estimated_tokens, delta: m.estimated_tokens_delta })
               break
             }
+            // compact_boundary — the authoritative compaction event (replaces the
+            // old heuristic): trigger ('manual' for /compact vs 'auto') + the token
+            // count before compaction. Emit a real recap card the room can pin.
+            if (m.subtype === 'compact_boundary') {
+              emit({ kind: 'compaction', trigger: m.compact_metadata?.trigger || 'auto', preTokens: m.compact_metadata?.pre_tokens ?? null })
+              break
+            }
             if (m.session_id) sessionId = m.session_id
             // m.slash_commands (init message) — the commands this session really
             // supports: built-ins + the host's custom .claude/commands. Surfaced
@@ -330,7 +353,10 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
             for (const b of (m.message?.content || [])) {
               if (b?.type === 'tool_use' && b.id) toolStart.set(b.id, Date.now())
             }
-            emit({ kind: 'assistant', blocks: simplifyBlocks(m.message?.content) })
+            // parentToolUseId: non-null when this assistant message comes from a
+            // sub-agent (Task tool) — the universal nesting spine. Thread it so the
+            // room can group sub-agent activity under its parent Task card.
+            emit({ kind: 'assistant', blocks: simplifyBlocks(m.message?.content), parentToolUseId: m.parent_tool_use_id || null })
             break
           case 'user':
             // tool_result blocks arrive on the user-role echo
@@ -338,7 +364,7 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
               if (b?.type === 'tool_result') {
                 const start = toolStart.get(b.tool_use_id)
                 if (start != null) toolStart.delete(b.tool_use_id)
-                emit({ kind: 'tool_result', toolUseId: b.tool_use_id, content: b.content, isError: !!b.is_error, durationMs: start != null ? Date.now() - start : undefined })
+                emit({ kind: 'tool_result', toolUseId: b.tool_use_id, content: b.content, isError: !!b.is_error, durationMs: start != null ? Date.now() - start : undefined, parentToolUseId: m.parent_tool_use_id || null })
               }
             }
             break
@@ -361,7 +387,8 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
           case 'result':
             if (m.session_id) sessionId = m.session_id
             turnBaseOut = 0; curMsgOut = 0   // reset the live token count for the next turn
-            emit({ kind: 'result', subtype: m.subtype, sessionId, costUsd: m.total_cost_usd, usage: m.usage, numTurns: m.num_turns })
+            turnActive = false               // turn settled → stall watchdog stands down
+            emit({ kind: 'result', subtype: m.subtype, sessionId, costUsd: m.total_cost_usd, usage: m.usage, numTurns: m.num_turns, durationMs: m.duration_ms ?? null, denials: Array.isArray(m.permission_denials) ? m.permission_denials.length : 0 })
             // Surface a usage/context meter (chrome, not a transcript line). The
             // context window % comes from the control request; cost is cumulative.
             ;(async () => {
@@ -384,7 +411,7 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
   })()
 
   return {
-    sendTurn(text) { if (!closed) input.push(String(text)) },
+    sendTurn(text) { if (!closed) { turnActive = true; lastEvtTs = Date.now(); stalledSent = false; input.push(String(text)) } },
     // Set the permission mode — Claude Code's ⇧⇥ cycle. setPermissionMode is a
     // streaming control request (drives plan-mode behaviour SDK-side); the local
     // `mode` drives our PreToolUse auto-approve policy. Echo so the room syncs.
@@ -412,8 +439,9 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
     // Graceful interrupt (Esc / Stop) — stops the current turn but keeps the
     // session alive for the next one. ac.abort() is teardown only (end()).
     async abort() { try { await q?.interrupt?.() } catch { /* noop */ } },
-    end() { closed = true; input.end(); try { ac.abort() } catch { /* noop */ } },
+    end() { closed = true; clearInterval(stallTimer); input.end(); try { ac.abort() } catch { /* noop */ } },
     get sessionId() { return sessionId },
     get mode() { return mode },
+    get turnActive() { return turnActive },   // a turn is in flight (gates between-turns update restart — Slice 3 Contract #1)
   }
 }

package/launcher.mjs

@@ -0,0 +1,184 @@
+/* launcher.mjs — the one-command interactive menu for `thinkpool-pair`.
+   Spec: docs/specs/2026-06-19-bridge-unified-launcher.md (Part 1).
+
+   ONE implementation, three callers, via dependency injection:
+     • bridge.mjs       → real `actions` (spawn a room bridge / installService / runLogin / …)
+     • setup-prototype  → dry-run `actions` (print the command instead of running it)
+     • test-launcher    → mock `actions` + scripted `io` (assert menu choice → action + args)
+
+   detectState() is real + read-only (auth.json / provider.json / PATH agents / service
+   artifact presence). runLauncher() renders the menu and calls actions.* — it NEVER runs
+   anything itself, so it is safe to unit-test and safe to dry-run. */
+
+import os from 'node:os'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const HOME = os.homedir()
+const CFG_DIR = path.join(HOME, '.thinkpool-pair')
+
+export const KNOWN_AGENTS = [
+  { label: 'Claude Code', cmd: 'claude', resume: ['--continue'] },
+  { label: 'Codex CLI',   cmd: 'codex' },
+  { label: 'Gemini CLI',  cmd: 'gemini' },
+  { label: 'Aider',       cmd: 'aider' },
+  { label: 'Cursor CLI',  cmd: 'cursor-agent' },
+  { label: 'opencode',    cmd: 'opencode' },
+  { label: 'Copilot CLI', cmd: 'copilot' },
+  { label: 'Goose',       cmd: 'goose' },
+  { label: 'Crush',       cmd: 'crush' },
+  { label: 'Qwen Code',   cmd: 'qwen' },
+]
+
+function onPath(c) {
+  const exts = process.platform === 'win32' ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';') : ['']
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue
+    for (const ext of exts) { try { if (fs.existsSync(path.join(dir, c + ext))) return true } catch { /* noop */ } }
+  }
+  return false
+}
+function readJson(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')) } catch { return null } }
+
+function serviceFile(room) {
+  const label = room ? `io.thinkpool.pair.${room.toLowerCase()}` : 'io.thinkpool.pair.account'
+  if (process.platform === 'darwin') return path.join(HOME, 'Library', 'LaunchAgents', `${label}.plist`)
+  if (process.platform === 'linux')  return path.join(HOME, '.config', 'systemd', 'user', `${label}.service`)
+  const startup = path.join(process.env.APPDATA || path.join(HOME, 'AppData', 'Roaming'), 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup')
+  return path.join(startup, `thinkpool-pair-${room || 'account'}.cmd`)
+}
+
+export function detectState() {
+  const auth = readJson(path.join(CFG_DIR, 'auth.json'))
+  const provider = readJson(path.join(CFG_DIR, 'provider.json'))
+  return {
+    loggedIn: !!auth?.refresh_token,
+    email: auth?.email || auth?.user?.email || null,
+    provider: provider?.kind === 'custom' ? `Custom (${provider.base || 'endpoint'})` : 'Anthropic (default)',
+    agents: KNOWN_AGENTS.filter(a => onPath(a.cmd)),
+    accountSvc: fs.existsSync(serviceFile(null)),
+    cwd: process.cwd(),
+  }
+}
+
+// ── colors ──
+const C = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`, bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`, green: (s) => `\x1b[32m${s}\x1b[0m`, yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+}
+
+// io: { ask(prompt)->Promise<string>, print(s) }. actions: real | dry-run | mock.
+export async function runLauncher({ actions, io, state = detectState() }) {
+  const askChoice = async (prompt, options, def = 1) => {
+    options.forEach((o, i) => io.print(`    ${C.cyan(String(i + 1))})  ${o.label}${o.hint ? '  ' + C.dim(o.hint) : ''}`))
+    const a = await io.ask(`\n  ${prompt} ${C.dim(`[${def}]`)} ${C.cyan('▸')} `)
+    const n = parseInt(a, 10)
+    return Number.isInteger(n) && n >= 1 && n <= options.length ? n - 1 : def - 1
+  }
+  const askYesNo = async (q, def = true) => {
+    const a = (await io.ask(`  ${q} ${C.dim(def ? '[Y/n]' : '[y/N]')} ${C.cyan('▸')} `)).toLowerCase()
+    return a ? a[0] === 'y' : def
+  }
+
+  const header = () => {
+    io.print('')
+    io.print('  ' + C.dim('┌ ') + C.bold('thinkpool-pair') + C.dim(' ' + '─'.repeat(40)))
+    io.print(`  ${C.dim('│ account  ')} ${state.loggedIn ? C.green((state.email || 'linked') + ' ✓') : C.yellow('not linked')}`)
+    io.print(`  ${C.dim('│ provider ')} ${state.provider}`)
+    io.print(`  ${C.dim('│ agents   ')} ${state.agents.length ? state.agents.map(a => a.label).join(', ') : C.yellow('none on PATH')}`)
+    io.print(`  ${C.dim('│ directory')} ${C.dim(state.cwd)}`)
+    io.print(`  ${C.dim('│ service  ')} ${state.accountSvc ? C.green('account service installed') : 'none'}`)
+    io.print('  ' + C.dim('└' + '─'.repeat(54)) + '\n')
+  }
+
+  const pairRoom = async () => {
+    const room = (await io.ask(`\n  Room code ${C.dim('(from /code in the web app)')} ${C.cyan('▸')} `)).toUpperCase().trim()
+    if (!room) { io.print('  ' + C.yellow('no room — back to menu')); return }
+    if (!state.agents.length) { io.print('\n  ' + C.yellow('No coding-agent CLI on your PATH (claude / codex / gemini / aider …).')); return }
+    let agent = state.agents[0]
+    if (state.agents.length > 1) { io.print('\n  Share which agent?'); agent = state.agents[await askChoice('agent', state.agents.map(a => ({ label: a.label })))] }
+    io.print('\n  Run mode?')
+    const headless = (await askChoice('mode', [
+      { label: 'Attached', hint: 'use it like your own terminal, mirrored to the web' },
+      { label: 'Headless', hint: 'pure relay, drive entirely from the web' },
+    ])) === 1
+    let cont = false
+    if (!headless && agent.resume) cont = await askYesNo(`\n  Continue your latest ${agent.label} session in this directory?`, true)
+    await actions.pairRoom({ room, agentCmd: agent.cmd, resumeArgs: cont ? agent.resume : [], headless })
+  }
+
+  const serveAccount = async () => {
+    if (!state.loggedIn) {
+      io.print('\n  ' + C.yellow('You are not linked to a ThinkPool account yet.'))
+      if (await askYesNo('  Link this device now?', true)) await actions.login()
+      return
+    }
+    io.print(`\n  Serving every session you host, from ${C.dim(state.cwd)}.\n`)
+    const how = await askChoice('run it', [
+      { label: 'As an always-on background service', hint: 'recommended — survives reboot, auto-updates' },
+      { label: 'Here in this terminal (foreground)', hint: 'stops when you close it' },
+    ])
+    if (how === 0) await actions.installService({ room: null })
+    else await actions.serveAccountForeground()
+  }
+
+  const serviceMenu = async () => {
+    const what = await askChoice('install for', [
+      { label: 'All my sessions (account)', hint: state.loggedIn ? '' : 'needs login first' },
+      { label: 'One specific room', hint: 'no login needed' },
+    ])
+    if (what === 0) {
+      if (!state.loggedIn) { io.print('\n  ' + C.yellow('Account service needs a login first (pick “Serve all my sessions”).')); return }
+      await actions.installService({ room: null }); return
+    }
+    const room = (await io.ask(`\n  Room code ${C.cyan('▸')} `)).toUpperCase().trim()
+    if (!room) { io.print('  ' + C.yellow('no room — back to menu')); return }
+    const agent = state.agents[0] || { cmd: 'claude' }
+    await actions.installService({ room, agentCmd: agent.cmd })
+  }
+
+  const settingsMenu = async () => {
+    const pick = await askChoice('\n  change', [
+      { label: 'LLM provider', hint: `current: ${state.provider}` },
+      { label: 'Account', hint: state.loggedIn ? `linked: ${state.email || 'yes'}` : 'not linked' },
+      { label: 'Remove the background service', hint: state.accountSvc ? '' : 'none installed' },
+    ])
+    if (pick === 0) {
+      const p = await askChoice('\n  provider', [{ label: 'Anthropic (default)' }, { label: 'Custom endpoint', hint: 'Z.ai GLM, OpenRouter, your own proxy' }])
+      if (p === 0) await actions.setProvider({ kind: 'anthropic' })
+      else {
+        const base = (await io.ask(`\n  Base url ${C.dim('(SDK appends /v1/messages)')} ${C.cyan('▸')} `)).trim()
+        const token = (await io.ask(`  API token ${C.cyan('▸')} `)).trim()
+        await actions.setProvider({ kind: 'custom', base, token })
+      }
+    } else if (pick === 1) {
+      await actions.login()
+    } else {
+      if (state.accountSvc) await actions.uninstallService({ room: null })
+      else io.print('  ' + C.yellow('no background service installed'))
+    }
+  }
+
+  // ── menu loop ──
+  // Real actions either replace the process (pairRoom re-execs + waits; serve/install
+  // call process.exit) or run forever (account foreground), so a real "do something"
+  // choice never returns here. Dry-run/mock actions just print + return → the loop
+  // re-renders. The "press Enter" only lands on a no-op / back-out path.
+  for (;;) {
+    header()
+    io.print('  ' + C.bold('What do you want to do?') + '\n')
+    const choice = await askChoice('choose', [
+      { label: 'Pair one room now', hint: 'run here, Ctrl-C stops it' },
+      { label: 'Serve all my sessions', hint: 'account mode — needs login' },
+      { label: 'Always-on background service', hint: 'survives reboot, auto-updates' },
+      { label: 'Settings', hint: 'provider · account · remove service' },
+      { label: 'Quit', hint: '' },
+    ])
+    if (choice === 4) return  // Quit
+    if (choice === 0) await pairRoom()
+    else if (choice === 1) await serveAccount()
+    else if (choice === 2) await serviceMenu()
+    else if (choice === 3) await settingsMenu()
+    await io.ask('\n  ' + C.dim('press Enter to return to the menu…'))
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.28",
+  "version": "0.7.30",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -8,7 +8,9 @@
   },
   "files": [
     "bridge.mjs",
+    "launcher.mjs",
     "claude-session.mjs",
+    "update-gate.mjs",
     "event-id.mjs",
     "transcript-sanitize.mjs",
     "session-store.mjs",

package/service.mjs

@@ -120,9 +120,13 @@ export function installService(room, cmdArgs = []) {
   for (const cmd of a.post) {
     try { execSync(cmd, { stdio: 'inherit' }) } catch (e) { process.stderr.write(`  ⚠ "${cmd}" failed: ${e.message}\n`) }
   }
+  // Be honest about the cadence — it is NOT instant. The supervisor polls npm
+  // roughly every 30 min (THINKPOOL_PAIR_UPDATE_INTERVAL) and only restarts once
+  // every served session is idle, so a just-published version can take a while.
+  const idleSecs = Math.max(10, parseInt(process.env.THINKPOOL_PAIR_UPDATE_IDLE, 10) || 90)
   const autoUpdate = process.platform === 'win32'
-    ? 'tracks thinkpool-pair@latest — new versions apply on next login/restart.'
-    : 'tracks thinkpool-pair@latest — checks for new versions and self-restarts at the next idle moment (sessions resume), no re-install.'
+    ? 'auto-update: a new thinkpool-pair@latest applies on the next login/restart (Windows has no in-process self-update).'
+    : `auto-update: checks npm ~every 30 min and restarts to apply a new version once sessions are idle (≥${idleSecs}s quiet; they resume in place). Not instant — to update now, restart it (re-run install-service, or 'launchctl kickstart -k gui/$(id -u)/io.thinkpool.pair.${slug(room)}' on macOS).`
   const removeArg = room ? ` ${room}` : ''
   const what = room ? `room ${room}` : 'your account (auto-serves every session)'
   process.stderr.write(`  ◆ ${what}\n  ◆ ${a.note}\n  ◆ ${autoUpdate}\n  ◆ logs: ${path.join(a.logDir, `${slug(room)}.log`)}\n  ◆ remove with: thinkpool-pair uninstall-service${removeArg}\n\n`)

package/update-gate.mjs

@@ -0,0 +1,31 @@
+/* update-gate.mjs — pure predicates for the between-turns update apply (Slice 3
+   nudge protocol, spec docs/specs/2026-06-19-bridge-unified-launcher.md Part 2).
+
+   Extracted import-safe so the "safe to restart now" rule is unit-tested and can't
+   drift. Contract #1: an update only applies at idle / between turns — never mid-turn.
+   bridge.mjs runs the bridge on import (can't be imported by a test), so the gate
+   lives here. */
+
+// Supervisor side: is it safe to restart the account bridge to apply a pending
+// update? True iff a pending update exists, we're not already stopping, EVERY served
+// child is idle (a child reports idle=false while a turn is in flight — that's what
+// keeps Contract #1), AND either a user requested apply (clicked the chip) OR — the
+// unattended fallback — no child has a web peer present (nobody is there to click).
+export function isSafeToRestart({ pendingUpdate, stopping = false, childIdle, childPeer, requested = false }) {
+  if (!pendingUpdate || stopping) return false
+  for (const idle of childIdle.values()) if (!idle) return false      // any busy child → wait (between-turns)
+  if (requested) return true                                          // user clicked apply + all idle → go
+  for (const present of childPeer.values()) if (present) return false // someone's watching, no click → wait
+  return true                                                         // unattended: idle + nobody watching → auto-apply
+}
+
+// Child/standalone side: is any structured session mid-turn? Used both to gate a
+// local apply and to make the idle heartbeat honest (idle=false while a turn runs).
+// Accepts a sessions Map whose entries expose turnActive directly or via .session.
+export function turnInFlight(sessions) {
+  for (const s of (sessions?.values?.() || [])) {
+    const ta = s && (typeof s.session?.turnActive === 'boolean' ? s.session.turnActive : s.turnActive)
+    if (ta) return true
+  }
+  return false
+}