thinkpool-pair 0.7.27 → 0.7.29

package/bridge.mjs

@@ -33,10 +33,12 @@ 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 { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames } from './session-store.mjs'
+import { stampEvent } from './event-id.mjs'
 
 // Public client creds (the same anon values the web app ships — safe to embed).
 // Override with TP_SUPABASE_URL / TP_SUPABASE_ANON if you ever need to.
@@ -153,6 +155,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()
@@ -588,11 +626,13 @@ function openStructured({ id, model, resume, log, commands, mode }) {
         openStructured({ id, model, log: entry.log, commands: entry.commands, mode: entry.mode })
         return
       }
-      // Stamp a wall-clock ts on every transcript event so the web client can
-      // sort agent turns chronologically against room chat/whispers on reload
-      // (the client merges the replayed log with persisted human lines). Used
-      // for ordering only — agent timestamps are never displayed.
-      if (typeof evt.ts !== 'number') evt.ts = Date.now()
+      // Stamp a wall-clock ts AND a stable cid on every transcript event before
+      // it's logged + broadcast. ts: lets the web client sort agent turns
+      // chronologically against room chat/whispers on reload. cid: the room's
+      // replay-union dedupes ONLY by cid, and SDK events carry none — without an
+      // id, an event that arrives both live AND in a reconnect replay renders
+      // twice (the 2026-06-19 duplicate-message bug). See event-id.mjs.
+      stampEvent(evt)
       // The init system event carries the session's slash command list. Stash it
       // on the entry so the ANNOUNCE can hand it to clients that connect/reload
       // AFTER init (the one-time code-event would miss them), then re-announce.
@@ -637,10 +677,22 @@ function openStructured({ id, model, resume, log, commands, mode }) {
 // from memory, delete its on-disk record (so a restart can't resurrect it), and tell
 // every client it's gone. Idempotent + id-scoped — no-ops for ids that aren't a
 // structured session, so it's safe to call from the PTY-oriented term-close path too.
+// Resolve any unanswered permission resolvers to 'deny' and clear them. A card
+// that's never answered (both clients gone, tab closed, or an abort) otherwise
+// leaves the SDK's PreToolUse hook (claude-session.mjs) awaiting our promise
+// forever — the structured turn freezes mid-flight. 'deny' is the fail-safe the
+// hook already degrades to, so draining to deny is always safe.
+function drainPending(s) {
+  if (!s?.pending) return
+  for (const [, p] of s.pending) { try { p.resolve('deny') } catch { /* noop */ } }
+  s.pending.clear()
+}
+
 function endStructured(id) {
   if (!id) return
   const s = sessions.get(id)
   if (s) {
+    drainPending(s)
     try { s.session?.end() } catch { /* noop */ }
     try { s.mockupWatcher?.close() } catch { /* noop */ }
     sessions.delete(id)
@@ -843,7 +895,7 @@ channel
   })
   .on('broadcast', { event: 'code-abort' }, ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)
-    if (s) s.session.abort()
+    if (s) { drainPending(s); s.session.abort() }   // settle any open permission card so the hook doesn't hang
   })
   .on('broadcast', { event: 'code-mode' }, ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)
@@ -916,7 +968,7 @@ channel
 setInterval(() => {
   if (!realtimeHealthy && brokenSince && Date.now() - brokenSince > 60000) {
     process.stderr.write('\n  ⚠ realtime wedged >60s — exiting for a clean restart.\n')
-    process.exit(1)
+    shutdown(1)   // reap PTYs + attempt presence-leave (was a raw exit → orphaned children)
   }
 }, 15000).unref()
 
@@ -960,7 +1012,7 @@ if (process.env.THINKPOOL_PAIR_AUTOUPDATE === '1' && VERSION) {
   const applyIfIdle = () => {
     if (!pendingUpdate || !isIdle()) return
     process.stderr.write(`\n  ◆ thinkpool-pair ${pendingUpdate} ready (running ${VERSION}) — restarting to update; the session resumes.\n`)
-    process.exit(0)   // service restarts with @latest; session-store resumes
+    shutdown(0, false)   // clean teardown (no farewell banner); service reruns @latest, session-store resumes
   }
   const check = async () => {
     const latest = await fetchLatest()
@@ -1010,24 +1062,47 @@ if (process.env.THINKPOOL_PAIR_AUTOUPDATE === '1' && VERSION) {
   }, 60000).unref()
 }
 
-async function shutdown() {
+// code: process exit code. farewell: print the "[ shared session ended ]" banner
+// (suppressed for an auto-update restart, which is meant to be invisible in-room).
+async function shutdown(code = 0, farewell = true) {
   if (shuttingDown) return
   shuttingDown = true
+  // Hard exit backstop, armed FIRST and independent of every await below — a wedged
+  // realtime socket (the watchdog path) or a hung untrack must NEVER leave the
+  // process alive with orphaned PTY children + stale "live" presence.
+  setTimeout(() => process.exit(code), 1500)
   clearInterval(flushTimer)
-  try {
-    const bye = Buffer.from('\r\n[ shared session ended ]\r\n', 'utf8').toString('base64')
-    for (const id of terms.keys()) bcast('pty-out', { term: id, b64: bye })
-  } catch { /* noop */ }
-  // Leave presence EXPLICITLY before exiting so the web room flips to dormant
-  // immediately. Previously we removeChannel()'d and process.exit()'d on the next
-  // line — the leave frame never flushed, so the web only noticed via the realtime
-  // heartbeat timeout (tens of seconds later) and looked stuck "live".
-  try { await channel.untrack() } catch { /* noop */ }
-  try { await supabase.removeChannel(channel) } catch { /* noop */ }
+  if (farewell) {
+    try {
+      const bye = Buffer.from('\r\n[ shared session ended ]\r\n', 'utf8').toString('base64')
+      for (const id of terms.keys()) bcast('pty-out', { term: id, b64: bye })
+    } catch { /* noop */ }
+  }
+  // Reap children FIRST — killing PTYs / ending SDK sessions is unconditionally
+  // correct and must not hang on the (possibly dead) realtime socket. This is the
+  // bug behind the watchdog/auto-update raw process.exit() paths, which skipped
+  // teardown entirely and orphaned agent processes + left stale presence.
   for (const t of terms.values()) { try { t.term.kill() } catch { /* noop */ } }
   for (const s of sessions.values()) { try { s.session.end() } catch { /* noop */ } }
   detachLocal()
-  setTimeout(() => process.exit(0), 250)   // small grace for the leave/close frames to flush over the socket
+  // Best-effort presence leave so the room flips to dormant immediately (when the
+  // socket is alive; on a wedge it won't flush and the hard backstop above wins).
+  try { await channel.untrack() } catch { /* noop */ }
+  try { await supabase.removeChannel(channel) } catch { /* noop */ }
+  setTimeout(() => process.exit(code), 250)   // grace for the leave/close frames to flush
 }
-process.on('SIGINT', shutdown)
-process.on('SIGTERM', shutdown)
+process.on('SIGINT', () => shutdown(0))
+process.on('SIGTERM', () => shutdown(0))
+// A throw escaping any async callback (an onEvent consumer, a JSON-serialize on a
+// circular payload, a node-pty native error) would otherwise terminate the process
+// with PTYs orphaned and presence stuck "live" (Node terminates on both since v15).
+// Route both through shutdown() so children are reaped + presence left, then the
+// supervisor / launchd / systemd respawns a clean process.
+process.on('uncaughtException', (err) => {
+  try { process.stderr.write(`\n  ⚠ uncaughtException: ${err?.stack || err}\n  ◆ shutting down cleanly for a fresh respawn.\n`) } catch { /* noop */ }
+  shutdown(1)
+})
+process.on('unhandledRejection', (reason) => {
+  try { process.stderr.write(`\n  ⚠ unhandledRejection: ${reason?.stack || reason}\n  ◆ shutting down cleanly for a fresh respawn.\n`) } catch { /* noop */ }
+  shutdown(1)
+})

package/event-id.mjs

@@ -0,0 +1,29 @@
+import { randomUUID } from 'node:crypto'
+
+/* event-id.mjs — stamp a structured event with a stable identity + timestamp
+   BEFORE it is logged + broadcast.
+
+   WHY (the duplicate-message bug, 2026-06-19): structured transcript events
+   (assistant / tool_result / thinking / result) carry NO id from the Claude
+   Agent SDK. The web room's replay-union (src/pages/code/room.jsx, the
+   `code-replay` handler) dedupes ONLY by `cid`: an event with a cid is merged
+   once; an event WITHOUT a cid is appended unconditionally. So an id-less event
+   that arrives both LIVE (`code-event`) and again in a reconnect REPLAY
+   (`code-replay`, which re-sends the whole rolling log) is rendered TWICE.
+   On mobile a background/foreground or network blip routinely triggers that
+   replay — which is exactly when the duplicates appeared.
+
+   Fix at the source: give every structured event a stable `cid` here, once, so
+   the live copy and every replayed copy share an id and the room's existing
+   cid-union collapses them. Idempotent — never overwrites a cid the client
+   already set (chat / whisper / pool / propose carry their own).
+
+   Kept as its own import-safe module so it can be unit-tested
+   (bridge/test-structured-cid.mjs); bridge.mjs runs the bridge on import and
+   cannot be imported by a test. */
+export function stampEvent(evt, gen = randomUUID) {
+  if (!evt || typeof evt !== 'object') return evt
+  if (typeof evt.ts !== 'number') evt.ts = Date.now()
+  if (!evt.cid) evt.cid = gen()
+  return evt
+}

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.27",
+  "version": "0.7.29",
   "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",
+    "event-id.mjs",
     "transcript-sanitize.mjs",
     "session-store.mjs",
     "service.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`)