thinkpool-pair 0.6.8 → 0.6.10

package/README.md

@@ -18,6 +18,31 @@ node bridge.mjs <ROOM>    # picks an installed agent, shared into room <ROOM>
 - Share a specific CLI: `node bridge.mjs <ROOM> -- aider`  /  `… -- bash`.
 - Pure relay (no local terminal): `node bridge.mjs <ROOM> --headless`.
 
+## Keep it stable (auto-restart)
+
+The bridge self-heals at three levels — all cross-platform (macOS / Linux / Windows):
+
+- **`--supervise`** — wrap it so a crash respawns automatically (exponential
+  backoff). Zero-dependency. Combined with session restore (below), a crash is
+  invisible — the room reconnects and the Claude session resumes where it left off.
+  ```bash
+  npx thinkpool-pair <ROOM> --supervise -- claude
+  ```
+- **Boot-persistent service** — survive reboot/logout too. Installs the right
+  native service for your OS (launchd on macOS, systemd `--user` on Linux, a
+  Startup-folder script on Windows):
+  ```bash
+  npx thinkpool-pair install-service <ROOM> -- claude   # set and forget
+  npx thinkpool-pair uninstall-service <ROOM>           # remove it
+  ```
+- **Watchdog** — if the realtime channel wedges for >60s, the bridge exits so the
+  supervisor/service restarts a clean process. Brief network blips reconnect on
+  their own.
+
+Structured Claude sessions persist their scrollback + session id to
+`~/.thinkpool-pair/<ROOM>/` and **resume on restart** (live context if recent),
+so none of the above loses your place.
+
 Your first agent runs **attached** — use it exactly like your normal terminal,
 every byte mirrors to the web. The web's **"+ New terminal"** spawns additional
 **headless** terminals here (same directory, same env), driven entirely from

package/bridge.mjs

@@ -32,6 +32,7 @@ import os from 'node:os'
 import fs from 'node:fs'
 import path from 'node:path'
 import readline from 'node:readline'
+import { spawn } from 'node:child_process'
 import { randomUUID } from 'node:crypto'
 import { createClient } from '@supabase/supabase-js'
 import { startClaudeSession } from './claude-session.mjs'
@@ -48,11 +49,13 @@ const SCROLLBACK_MAX = 120_000
 
 // node-pty is a native module — loaded lazily so a friendly message shows
 // if it isn't built yet.
-let pty
+// Structured Claude (the default) runs through the Agent SDK and needs NO PTY,
+// so a failed node-pty build must not block the bridge — it only disables the
+// raw-PTY path (other CLIs / TP_PTY=1), which we flag clearly if it's used.
+let pty = null
 try { pty = (await import('node-pty')).default ?? (await import('node-pty')) }
 catch {
-  console.error('\n  node-pty isn\'t installed. From the bridge folder run:\n    npm i\n  then re-run.  (it needs a C toolchain — Xcode CLT on mac, build-essential on linux)\n')
-  process.exit(1)
+  console.error('\n  ⚠ node-pty not built — raw terminal sharing is off (structured Claude still works).\n    For PTY mode (bash / aider / codex / TP_PTY=1): install a C toolchain, then `npm i` in the bridge.\n    (Xcode CLT on mac · build-essential on linux · VS Build Tools on Windows.)\n')
 }
 
 // ── Known coding-agent CLIs we feature in the picker ──────────────
@@ -117,8 +120,51 @@ const pickAgent = (installed) => new Promise((resolve) => {
 })
 
 const argv = process.argv.slice(2)
+
+// Boot-persistent service install (cross-platform: launchd / systemd / Windows
+// Startup). Subcommand form: `thinkpool-pair install-service <ROOM> [-- <cmd>]`.
+if (argv[0] === 'install-service' || argv[0] === 'uninstall-service') {
+  const svcRoom = (argv[1] || '').toUpperCase().trim()
+  if (!svcRoom || svcRoom.startsWith('-')) { console.error('usage: thinkpool-pair install-service <ROOM> [-- <command…>]'); process.exit(1) }
+  const sd = argv.indexOf('--')
+  const svcCmd = sd >= 0 ? argv.slice(sd + 1) : []
+  const svc = await import('./service.mjs')
+  if (argv[0] === 'install-service') svc.installService(svcRoom, svcCmd)
+  else svc.uninstallService(svcRoom)
+  process.exit(0)
+}
+
 const room = (argv[0] || '').toUpperCase().trim()
 if (!room || room.startsWith('-')) { console.error('usage: npx thinkpool-pair <ROOM> [--headless] [--continue|--fresh] [-- <command…>]'); process.exit(1) }
+// ── Supervisor mode (--supervise / --keep-alive): keep the bridge alive across
+// crashes. We re-exec ourselves without the flag and respawn the child on any
+// non-clean exit with exponential backoff. Zero-dependency, cross-platform. With
+// the crash-resume in session-store, a respawn restores the session invisibly.
+// (Boot persistence — surviving reboot/logout — is the launchd/systemd tier.)
+const _superDash = argv.indexOf('--')
+const _superOwn = _superDash >= 0 ? argv.slice(0, _superDash) : argv
+if (_superOwn.includes('--supervise') || _superOwn.includes('--keep-alive')) {
+  const childArgs = process.argv.slice(1).filter((a) => a !== '--supervise' && a !== '--keep-alive')
+  let backoff = 1000, stopping = false, child = null
+  const spawnChild = () => {
+    const t0 = Date.now()
+    child = spawn(process.execPath, childArgs, { stdio: 'inherit' })
+    child.on('exit', (code, signal) => {
+      if (stopping || code === 0) process.exit(code || 0)   // clean stop → stop supervising
+      const ranLong = Date.now() - t0 > 60000
+      const wait = ranLong ? 1000 : backoff
+      backoff = ranLong ? 1000 : Math.min(backoff * 2, 30000)
+      process.stderr.write(`\n  ⚠ bridge exited (${signal || `code ${code}`}); restarting in ${Math.round(wait / 1000)}s…\n`)
+      setTimeout(spawnChild, wait)
+    })
+    child.on('error', () => { /* spawn failure → exit handler retries */ })
+  }
+  for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => { stopping = true; try { child?.kill(sig) } catch { /* noop */ } setTimeout(() => process.exit(0), 400) })
+  process.stderr.write(`\n  ◆ supervisor up — keeping the bridge for room ${room} alive (auto-restart on crash).\n`)
+  spawnChild()
+  await new Promise(() => {})   // block forever; the child IS the bridge
+}
+
 const headless = argv.includes('--headless')
 // Structured mode (Phase 2, opt-in): Claude Code runs through the Agent SDK
 // (structured events + risk-tiered permission gate) instead of the PTY byte
@@ -281,6 +327,11 @@ const attachedDims = () => ({
 
 function openTerm({ id, cmd, args = [], attached = false, cols, rows }) {
   if (terms.has(id)) return
+  if (!pty) {   // raw-PTY path needs node-pty; structured Claude never lands here
+    process.stderr.write(`\n  ⚠ can't open "${cmd}" — node-pty isn't built (PTY mode disabled).\n`)
+    bcast('term-exit', { id })
+    return
+  }
   const ad = attached ? attachedDims() : null
   const term = pty.spawn(cmd, args, {
     name: 'xterm-256color',
@@ -421,6 +472,11 @@ process.stdout.on('resize', () => {
   try { t.term.resize(cols, rows); announce() } catch { /* noop */ }
 })
 
+// Realtime health, read by the subscribe handler + watchdog (declared before
+// the channel chain so the async subscribe callback closes over live bindings).
+let realtimeHealthy = false
+let brokenSince = Date.now()
+
 channel
   .on('broadcast', { event: 'pty-in' }, ({ payload }) => {
     if (!payload?.data) return
@@ -553,6 +609,7 @@ channel
   .on('broadcast', { event: 'who' }, announce)
   .subscribe(status => {
     if (status === 'SUBSCRIBED') {
+      realtimeHealthy = true; brokenSince = 0
       channel.track({ name, role: 'bridge' })
       if (attachedCmd && !terms.size && !sessions.size) {
         // Claude + structured mode → Agent SDK session; everything else → PTY.
@@ -569,9 +626,26 @@ channel
       process.stderr.write(headless
         ? `\n  ◆ thinkpool — relaying room ${room} (headless). Open terminals from the web UI.\n\n`
         : `\n  ◆ thinkpool — sharing "${attachedCmd}"${continuing ? ' (continuing your latest session)' : ''} into room ${room}.  Open the web UI and you're both in.\n\n`)
+    } else if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT' || status === 'CLOSED') {
+      // supabase-js retries the socket itself; we just track health for the
+      // watchdog. A blip self-heals (next SUBSCRIBED re-announces); a wedge that
+      // never recovers trips the watchdog → exit → supervisor respawns clean.
+      if (realtimeHealthy || !brokenSince) brokenSince = Date.now()
+      realtimeHealthy = false
+      process.stderr.write(`\n  ⚠ realtime ${status} — reconnecting…\n`)
     }
   })
 
+// Watchdog — if the realtime channel is stuck (never connected, or dropped and
+// not recovered) for >60s, exit non-zero so a supervisor/launchd restarts a
+// clean process. Healthy long-lived connections never trip this (brokenSince=0).
+setInterval(() => {
+  if (!realtimeHealthy && brokenSince && Date.now() - brokenSince > 60000) {
+    process.stderr.write('\n  ⚠ realtime wedged >60s — exiting for a clean restart.\n')
+    process.exit(1)
+  }
+}, 15000).unref()
+
 function shutdown() {
   if (shuttingDown) return
   shuttingDown = true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "bridge.mjs",
     "claude-session.mjs",
     "session-store.mjs",
+    "service.mjs",
     "README.md"
   ],
   "scripts": {
@@ -20,7 +21,9 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.173",
-    "@supabase/supabase-js": "^2.45.0",
+    "@supabase/supabase-js": "^2.45.0"
+  },
+  "optionalDependencies": {
     "node-pty": "^1.2.0-beta.13"
   }
 }

package/service.mjs

@@ -0,0 +1,103 @@
+/* ─────────────────────────────────────────────────────────────
+   service.mjs — install the bridge as a boot-persistent OS service
+   so a customer's bridge survives reboot/logout and auto-restarts
+   on crash, on every platform:
+     • macOS   → launchd LaunchAgent (KeepAlive)
+     • Linux   → systemd --user unit (Restart=always)
+     • Windows → Startup-folder .cmd running --supervise
+   `--supervise` (in bridge.mjs) is the cross-platform crash-restart
+   baseline that needs no install; this adds boot persistence.
+   ───────────────────────────────────────────────────────────── */
+
+import os from 'node:os'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execSync } from 'node:child_process'
+
+const BRIDGE = fileURLToPath(new URL('./bridge.mjs', import.meta.url))
+const label = (room) => `io.thinkpool.pair.${room.toLowerCase()}`
+const xml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+
+// Pure artifact builder — returned shape is testable without side effects.
+// `mode:'service'` lets the OS supervise (no --supervise); 'supervise' wraps it.
+export function buildArtifact(platform, { room, cmdArgs = [] }) {
+  const node = process.execPath
+  const cwd = process.cwd()
+  const logDir = path.join(os.homedir(), '.thinkpool-pair')
+  const log = path.join(logDir, `${room}.log`)
+  const tail = cmdArgs.length ? ['--', ...cmdArgs] : []
+
+  if (platform === 'darwin') {
+    const args = [node, BRIDGE, room, ...tail]   // launchd KeepAlive supervises
+    const file = path.join(os.homedir(), 'Library', 'LaunchAgents', `${label(room)}.plist`)
+    const content = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${label(room)}</string>
+  <key>ProgramArguments</key><array>${args.map((a) => `<string>${xml(a)}</string>`).join('')}</array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>WorkingDirectory</key><string>${xml(cwd)}</string>
+  <key>StandardOutPath</key><string>${xml(log)}</string>
+  <key>StandardErrorPath</key><string>${xml(log)}</string>
+  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(process.env.PATH || '')}</string></dict>
+</dict></plist>\n`
+    return { file, content, logDir, post: [`launchctl unload "${file}" 2>/dev/null; launchctl load "${file}"`], note: 'Loaded as a LaunchAgent — starts at login, restarts on crash.' }
+  }
+
+  if (platform === 'linux') {
+    const args = [node, BRIDGE, room, ...tail]   // systemd Restart=always supervises
+    const file = path.join(os.homedir(), '.config', 'systemd', 'user', `${label(room)}.service`)
+    const content = `[Unit]
+Description=ThinkPool Code bridge (${room})
+After=network-online.target
+
+[Service]
+ExecStart=${args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}
+Restart=always
+RestartSec=2
+WorkingDirectory=${cwd}
+Environment=PATH=${process.env.PATH || ''}
+StandardOutput=append:${log}
+StandardError=append:${log}
+
+[Install]
+WantedBy=default.target
+`
+    return { file, content, logDir, post: ['systemctl --user daemon-reload', `systemctl --user enable --now ${label(room)}.service`], note: 'Enabled as a systemd --user service. Run `loginctl enable-linger $USER` once to keep it running after logout.' }
+  }
+
+  if (platform === 'win32') {
+    // No native per-user daemon without extra tooling — a Startup-folder script
+    // running --supervise gives login-persistence + crash-restart, dependency-free.
+    const startup = path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup')
+    const file = path.join(startup, `thinkpool-pair-${room}.cmd`)
+    const inner = [`"${node}"`, `"${BRIDGE}"`, room, '--supervise', ...tail].join(' ')
+    const content = `@echo off\r\ntitle thinkpool-pair ${room}\r\n${inner}\r\n`
+    return { file, content, logDir, post: [], note: 'Installed to the Startup folder — runs at login with --supervise (auto-restart on crash). Start it now without rebooting by double-clicking the .cmd, or run it from a terminal.' }
+  }
+
+  throw new Error(`unsupported platform: ${platform}`)
+}
+
+export function installService(room, cmdArgs = []) {
+  const a = buildArtifact(process.platform, { room, cmdArgs })
+  fs.mkdirSync(a.logDir, { recursive: true })
+  fs.mkdirSync(path.dirname(a.file), { recursive: true })
+  fs.writeFileSync(a.file, a.content)
+  process.stderr.write(`\n  ◆ wrote ${a.file}\n`)
+  for (const cmd of a.post) {
+    try { execSync(cmd, { stdio: 'inherit' }) } catch (e) { process.stderr.write(`  ⚠ "${cmd}" failed: ${e.message}\n`) }
+  }
+  process.stderr.write(`  ◆ ${a.note}\n  ◆ logs: ${path.join(a.logDir, `${room}.log`)}\n  ◆ remove with: thinkpool-pair uninstall-service ${room}\n\n`)
+}
+
+export function uninstallService(room) {
+  const plat = process.platform
+  let a
+  try { a = buildArtifact(plat, { room }) } catch (e) { process.stderr.write(`  ⚠ ${e.message}\n`); return }
+  if (plat === 'darwin') { try { execSync(`launchctl unload "${a.file}" 2>/dev/null`) } catch { /* noop */ } }
+  if (plat === 'linux') { try { execSync(`systemctl --user disable --now ${label(room)}.service 2>/dev/null`) } catch { /* noop */ } }
+  try { fs.rmSync(a.file, { force: true }); process.stderr.write(`  ◆ removed ${a.file}\n`) } catch (e) { process.stderr.write(`  ⚠ ${e.message}\n`) }
+}