thinkpool-pair 0.7.26 → 0.7.28

package/README.md

@@ -100,35 +100,33 @@ npx thinkpool-pair@latest <ROOM> -- claude           # structured Claude, no TTY
 
 ## Alternative LLM Providers
 
-The bridge supports using alternative LLM providers that are compatible with the Anthropic API:
+The bridge can run on **any Anthropic-compatible endpoint** instead of Anthropic
+directly — Z.ai GLM, OpenRouter, your own proxy, etc. **CLI-agent-compatible
+only:** the bridge spawns the `claude` CLI, which talks the Anthropic Messages
+API, so the base url must be a root the SDK can append `/v1/messages` to (an
+OpenAI-style `/v1/chat/completions` endpoint will not work).
 
-### OpenRouter
-To use OpenRouter instead of Anthropic directly:
 ```bash
-npx thinkpool-pair provider openrouter --token sk-or-... [--model anthropic/claude-3.5-sonnet]
+npx thinkpool-pair provider custom --base <url> --token <key> [--model <name>]
 ```
 
-This will configure the bridge to use OpenRouter's API endpoint with your provided token. You can optionally specify a model.
+Common base urls (the SDK appends `/v1/messages`):
 
-### GLM (Z.ai)
-To use GLM via Z.ai's Anthropic-compatible endpoint:
-```bash
-npx thinkpool-pair provider glm --token zai_...
-```
+| Provider      | Base url                          |
+|---------------|-----------------------------------|
+| Z.ai GLM      | `https://api.z.ai/api/anthropic`  |
+| OpenRouter    | `https://openrouter.ai/api`       |
 
-### Custom Provider
-For any other Anthropic-compatible endpoint:
-```bash
-npx thinkpool-pair provider custom --base https://your-endpoint.com --token your-token [--model model-name]
-```
+Show the current provider (`npx thinkpool-pair provider`), or reset back to your
+regular Claude login:
 
-### Reset to Default
-To reset back to using Anthropic directly:
 ```bash
 npx thinkpool-pair provider anthropic
 ```
 
-Provider configurations are stored in `~/.thinkpool-pair/provider.json` and apply to all bridges on the machine.
+Provider config is stored in `~/.thinkpool-pair/provider.json` (mode 0600) and
+applies to every bridge on the machine. Restart the bridge (or its launchd
+service) after changing it — the choice is read once at startup.
 
 Public anon creds are embedded (the same ones the web app ships). Override with
 `TP_SUPABASE_URL` / `TP_SUPABASE_ANON` if needed. Set `TP_NAME` to label yourself.

package/bridge.mjs

@@ -37,6 +37,7 @@ 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.
@@ -588,11 +589,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 +640,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 +858,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 +931,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 +975,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 +1025,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/claude-session.mjs

@@ -14,6 +14,7 @@
 
 import { randomUUID } from 'node:crypto'
 import { query } from '@anthropic-ai/claude-agent-sdk'
+import { sanitizeSession } from './transcript-sanitize.mjs'
 
 // ── risk classification — the accent/danger tier of the permission card ──
 // low (read-only) · medium (writes/runs) · network (leaves the machine) ·
@@ -290,6 +291,16 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
   if (resume) opts.resume = resume
   if (env) opts.env = env
 
+  // Before the SDK replays this transcript, heal any cross-provider tool blocks
+  // it left behind (e.g. a room that ran on Z.ai GLM, now back on anthropic).
+  // Anthropic 400s on a `server_tool_use` block carrying a foreign id/name, which
+  // wedges the room on every send. Reclassifying those to plain `tool_use` clears
+  // it; idempotent + no-op on clean transcripts. See transcript-sanitize.mjs.
+  if (resume) {
+    const healed = sanitizeSession(cwd || process.cwd(), resume)
+    if (healed.blocks) process.stderr.write(`\n  ◆ healed ${healed.blocks} cross-provider tool block(s) in the transcript before resume.\n`)
+  }
+
   ;(async () => {
     try {
       q = query({ prompt: input.stream, options: opts })

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/package.json

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

package/provider.mjs

@@ -1,12 +1,12 @@
 /* ─────────────────────────────────────────────────────────────
    provider.mjs — per-machine LLM provider choice for the ThinkPool
-   bridge. Lets a Code room run on GLM (Z.ai's Anthropic-compatible
-   endpoint) instead of plain Anthropic, INDEPENDENT of the launching
-   shell. Why this exists: the launchd service does NOT source ~/.zshrc,
-   so a shell `export ANTHROPIC_*` can never reach a serviced bridge —
-   its spawned Claude children fall back to the host's claude.ai login
-   and hit the Anthropic spend wall. provider.json is the bridge's OWN
-   source of truth.
+   bridge. Lets a Code room run on ANY Anthropic-compatible endpoint
+   (Z.ai GLM, OpenRouter, a local proxy, …) instead of plain Anthropic,
+   INDEPENDENT of the launching shell. Why this exists: the launchd
+   service does NOT source ~/.zshrc, so a shell `export ANTHROPIC_*` can
+   never reach a serviced bridge — its spawned Claude children fall back
+   to the host's claude.ai login and hit the Anthropic spend wall.
+   provider.json is the bridge's OWN source of truth.
 
    applyProviderEnv() runs once at the top of bridge.mjs (the universal
    entry point), BEFORE any child is spawned. It sets ANTHROPIC_BASE_URL
@@ -16,12 +16,17 @@
    every code session with no other change. Default (no file, or
    provider:"anthropic") = the host's regular Claude login, untouched.
 
+   CLI-agent-compatible ONLY. The bridge spawns the `claude` CLI, which
+   talks the Anthropic Messages API — so the base url MUST be an
+   Anthropic-compatible root (the SDK appends /v1/messages). An OpenAI-
+   style /v1/chat/completions endpoint will NOT work. Common roots:
+     Z.ai GLM    → https://api.z.ai/api/anthropic
+     OpenRouter  → https://openrouter.ai/api
+
    CLI (dispatched from bridge.mjs):
-     npx thinkpool-pair provider                         # show current
-     npx thinkpool-pair provider glm --token <zai_…>     # use GLM (Z.ai)
-     npx thinkpool-pair provider openrouter --token <sk-or-…> [--model <model>]
-     npx thinkpool-pair provider custom --base <url> --token <key>
-     npx thinkpool-pair provider anthropic               # reset to Claude
+     npx thinkpool-pair provider                                            # show current
+     npx thinkpool-pair provider custom --base <url> --token <key> [--model <m>]   # any Anthropic-compatible endpoint
+     npx thinkpool-pair provider anthropic                                  # reset to Claude
    ───────────────────────────────────────────────────────────── */
 import os from 'node:os'
 import fs from 'node:fs'
@@ -30,13 +35,6 @@ import path from 'node:path'
 const DIR = path.join(os.homedir(), '.thinkpool-pair')
 const FILE = path.join(DIR, 'provider.json')
 
-// The pre-baked GLM/Z.ai preset. --token is always required (never bake a key
-// into source); --base / --model override these if the endpoint ever moves.
-const GLM = { baseUrl: 'https://api.z.ai/api/anthropic', model: 'glm-5.2' }
-
-// The pre-baked OpenRouter preset. --token is always required.
-const OPENROUTER = { baseUrl: 'https://openrouter.ai/api/v1', model: 'anthropic/claude-3.5-sonnet' }
-
 function ensureDir() { try { fs.mkdirSync(DIR, { recursive: true }) } catch { /* noop */ } }
 function opt(args, flag) { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined }
 
@@ -50,11 +48,15 @@ export function saveProvider(p) {
 }
 
 /**
- * Merge the persisted provider choice (or TP_PROVIDER* env overrides) into
+ * Merge the persisted provider choice (or TP_* env overrides) into
  * process.env. Call once at startup, before spawning any child. Idempotent.
- * A no-op for the default Anthropic provider — we only ever SET the GLM/custom
+ * A no-op for the default Anthropic provider — we only ever SET the custom
  * vars, never clobber a host's real Claude login env. Env vars win over the
  * file so a one-off launch can flip providers without writing anything.
+ *
+ * Provider-name-agnostic: any provider saved to provider.json (glm, custom,
+ * a leftover openrouter file, …) is handled by one branch that only cares
+ * that baseUrl/authToken are present.
  * @returns {{provider:string,baseUrl?:string,model?:string,source:string}}
  */
 export function applyProviderEnv() {
@@ -62,28 +64,11 @@ export function applyProviderEnv() {
   const provider = (process.env.TP_PROVIDER || cfg.provider || 'anthropic').toLowerCase()
   if (provider === 'anthropic' || !provider) return { provider: 'anthropic', source: 'default' }
 
-  // Handle OpenRouter specifically
-  if (provider === 'openrouter') {
-    const baseUrl = process.env.TP_ANTHROPIC_BASE_URL || cfg.baseUrl || OPENROUTER.baseUrl
-    const authToken = process.env.TP_ANTHROPIC_AUTH_TOKEN || cfg.authToken
-    const model = process.env.TP_ANTHROPIC_MODEL || cfg.model || OPENROUTER.model
-
-    if (!authToken) {
-      process.stderr.write(`\n  ◇ provider "${provider}" is set but is missing authToken.\n    Finish setup:  npx thinkpool-pair provider ${provider} --token <key>\n    Falling back to regular Claude for now.\n`)
-      return { provider: 'anthropic', source: 'incomplete' }
-    }
-
-    process.env.ANTHROPIC_BASE_URL = baseUrl
-    process.env.ANTHROPIC_AUTH_TOKEN = authToken
-    if (model) process.env.ANTHROPIC_MODEL = model
-    return { provider, baseUrl, model, source: cfg.provider ? 'file' : 'env' }
-  }
-
-  const baseUrl = process.env.TP_ANTHROPIC_BASE_URL || cfg.baseUrl
+  const baseUrl   = process.env.TP_ANTHROPIC_BASE_URL   || cfg.baseUrl
   const authToken = process.env.TP_ANTHROPIC_AUTH_TOKEN || cfg.authToken
-  const model = process.env.TP_ANTHROPIC_MODEL || cfg.model
+  const model     = process.env.TP_ANTHROPIC_MODEL      || cfg.model
   if (!baseUrl || !authToken) {
-    process.stderr.write(`\n  ◇ provider "${provider}" is set but is missing baseUrl/authToken.\n    Finish setup:  npx thinkpool-pair provider ${provider} --token <key>\n    Falling back to regular Claude for now.\n`)
+    process.stderr.write(`\n  ◇ provider "${provider}" is set but is missing baseUrl/authToken.\n    Finish setup:  npx thinkpool-pair provider custom --base <url> --token <key>\n    Falling back to regular Claude for now.\n`)
     return { provider: 'anthropic', source: 'incomplete' }
   }
   process.env.ANTHROPIC_BASE_URL = baseUrl
@@ -114,39 +99,34 @@ export async function runProvider(args) {
     return
   }
 
-  // ── GLM (Z.ai) preset ──
-  if (sub === 'glm') {
-    const token = opt(args, '--token') || opt(args, '--key')
-    const baseUrl = opt(args, '--base') || opt(args, '--base-url') || GLM.baseUrl
-    const model = opt(args, '--model') || GLM.model
-    if (!token) { console.error('\n  ✗ glm needs --token <zai_…>. Get one at https://z.ai/\n'); process.exit(1) }
-    saveProvider({ provider: 'glm', baseUrl, authToken: token, model, savedAt: Date.now() })
-    console.error(`\n  ✓ provider set to glm (Z.ai).\n    base url: ${baseUrl}\n    model:    ${model}\n    token:    ${token.slice(0, 8)}…\n    Restart the bridge (or its launchd service) to apply.\n`)
-    return
-  }
-
-  // ── OpenRouter preset ──
-  if (sub === 'openrouter') {
-    const token = opt(args, '--token') || opt(args, '--key')
-    const baseUrl = opt(args, '--base') || opt(args, '--base-url') || OPENROUTER.baseUrl
-    const model = opt(args, '--model') || OPENROUTER.model
-    if (!token) { console.error('\n  ✗ openrouter needs --token <sk-or-…>. Get one at https://openrouter.ai/\n'); process.exit(1) }
-    saveProvider({ provider: 'openrouter', baseUrl, authToken: token, model, savedAt: Date.now() })
-    console.error(`\n  ✓ provider set to openrouter.\n    base url: ${baseUrl}\n    model:    ${model}\n    token:    ${token.slice(0, 8)}…\n    Restart the bridge (or its launchd service) to apply.\n`)
-    return
-  }
-
-  // ── arbitrary Anthropic-compatible endpoint ──
+  // ── any Anthropic-compatible endpoint ──
   if (sub === 'custom') {
-    const token = opt(args, '--token') || opt(args, '--key')
-    const baseUrl = opt(args, '--base') || opt(args, '--base-url')
-    const model = opt(args, '--model')
-    if (!token || !baseUrl) { console.error('\n  ✗ custom needs --base <url> and --token <key>.\n'); process.exit(1) }
+    const token   = opt(args, '--token') || opt(args, '--key')
+    const baseUrl = opt(args, '--base')  || opt(args, '--base-url')
+    const model   = opt(args, '--model')
+    if (!token || !baseUrl) {
+      console.error(
+        '\n  ✗ custom needs --base <url> and --token <key>. [--model <name>] is optional.\n' +
+        '    The base url is the Anthropic-compatible root the SDK appends /v1/messages to:\n' +
+        '      Z.ai GLM    → https://api.z.ai/api/anthropic\n' +
+        '      OpenRouter  → https://openrouter.ai/api\n' +
+        '    Restart the bridge (or its launchd service) to apply.\n'
+      )
+      process.exit(1)
+    }
     saveProvider({ provider: 'custom', baseUrl, authToken: token, model: model || undefined, savedAt: Date.now() })
-    console.error(`\n  ✓ provider set to custom (${baseUrl}).\n    Restart the bridge to apply.\n`)
+    console.error(`\n  ✓ provider set to custom.\n    base url: ${baseUrl}\n    model:    ${model || '(default)'}\n    token:    ${token.slice(0, 8)}…\n    Restart the bridge (or its launchd service) to apply.\n`)
     return
   }
 
-  console.error('\n  usage:\n    npx thinkpool-pair provider                              # show current\n    npx thinkpool-pair provider glm --token <zai_…> [--model glm-5.2]\n    npx thinkpool-pair provider openrouter --token <sk-or-…> [--model <model>]\n    npx thinkpool-pair provider custom --base <url> --token <key> [--model <m>]\n    npx thinkpool-pair provider anthropic                      # reset to Claude\n')
+  console.error(
+    '\n  usage:\n' +
+    '    npx thinkpool-pair provider                                            # show current\n' +
+    '    npx thinkpool-pair provider custom --base <url> --token <key> [--model <m>]   # any Anthropic-compatible endpoint\n' +
+    '    npx thinkpool-pair provider anthropic                                  # reset to Claude\n\n' +
+    '  common base urls (SDK appends /v1/messages):\n' +
+    '    Z.ai GLM    → https://api.z.ai/api/anthropic\n' +
+    '    OpenRouter  → https://openrouter.ai/api\n'
+  )
   process.exit(1)
 }

package/transcript-sanitize.mjs

@@ -0,0 +1,132 @@
+/* ─────────────────────────────────────────────────────────────
+   transcript-sanitize.mjs — heal cross-provider tool blocks in a
+   Claude Code transcript before the SDK replays it.
+
+   THE BUG IT PREVENTS (failure: feedback_bridge_provider_swap_srvtoolu):
+   When a room runs on a non-Anthropic provider (Z.ai GLM, any
+   OpenAI-compatible endpoint), Claude Code persists that provider's
+   custom server-side tools into the transcript as `server_tool_use`
+   blocks — but with that provider's tool ids/names (e.g. an OpenAI
+   `call_<hex>` id, a name like `webReader` / `analyze_image`). Swap the
+   provider back to `anthropic` and the next turn replays the whole
+   transcript; Anthropic STRICTLY validates server_tool_use blocks and
+   400s on the first illegal one:
+     messages.N.content.M.server_tool_use.id:   String should match '^srvtoolu_…'
+     messages.N.content.M.server_tool_use.name: Input should be 'web_search', …
+   The room is then wedged — every send re-hits message N and fails.
+
+   THE FIX: reclassify each illegal block from `server_tool_use` to a
+   plain `tool_use`. Anthropic only enforces the id-pattern and the
+   name-enum on SERVER tools; a regular tool_use replays with ANY id and
+   ANY name (the transcript's own `call_*` client tools — Bash, Edit,
+   WebSearch — prove this; they never error). The block keeps its id, so
+   it stays paired with its existing tool_result. This clears BOTH the
+   id and the name error in one move and is the universally-valid form,
+   so it's safe to run regardless of which provider wrote the history.
+
+   NB: do NOT "fix" this by renaming the id to `srvtoolu_…` — that leaves
+   the bogus tool NAME, so the name-enum error survives and the room
+   stays stuck. (That half-fix is the documented trap.)
+
+   Idempotent, crash-safe (atomic rename), and a cheap string pre-check
+   means it's a no-op on clean transcripts. Never throws into the caller.
+   ───────────────────────────────────────────────────────────── */
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+// Anthropic's real server-tool names. A `server_tool_use` block whose name
+// is NOT in this set came from another provider and must be reclassified.
+const ANTHROPIC_SERVER_TOOLS = new Set([
+  'web_search',
+  'web_fetch',
+  'code_execution',
+  'bash_code_execution',
+  'text_editor_code_execution',
+  'tool_search_tool_regex',
+  'tool_search_tool_bm25',
+])
+
+const MARKER = '"server_tool_use"'
+
+/**
+ * Resolve a session's transcript path the same way Claude Code names it:
+ * ~/.claude/projects/<cwd with [/\.:] → '-'>/<sessionId>.jsonl
+ */
+export function transcriptPath(cwd, sessionId) {
+  const slug = path.resolve(cwd || process.cwd()).replace(/[/\\.:]/g, '-')
+  return path.join(os.homedir(), '.claude', 'projects', slug, `${sessionId}.jsonl`)
+}
+
+// Flip illegal server_tool_use blocks in one content array. Returns count flipped.
+function fixContent(content) {
+  if (!Array.isArray(content)) return 0
+  let n = 0
+  for (const b of content) {
+    if (b && b.type === 'server_tool_use' && !ANTHROPIC_SERVER_TOOLS.has(b.name)) {
+      b.type = 'tool_use'
+      n++
+    }
+  }
+  return n
+}
+
+/**
+ * Sanitize one transcript file in place. Returns { lines, blocks } counting the
+ * transcript lines rewritten and the individual blocks flipped. A missing,
+ * unreadable, or already-clean file is a silent no-op ({ lines: 0, blocks: 0 }).
+ */
+export function sanitizeTranscript(file) {
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf8')
+  } catch {
+    return { lines: 0, blocks: 0 } // no transcript yet (fresh session) — nothing to do
+  }
+  if (!raw.includes(MARKER)) return { lines: 0, blocks: 0 } // fast path: nothing illegal possible
+
+  const rows = raw.split('\n')
+  let lines = 0
+  let blocks = 0
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i]
+    if (!row || !row.includes(MARKER)) continue
+    let obj
+    try {
+      obj = JSON.parse(row)
+    } catch {
+      continue // never touch a line we can't parse — leave it byte-identical
+    }
+    let n = 0
+    if (obj.message && typeof obj.message === 'object') n += fixContent(obj.message.content)
+    n += fixContent(obj.content)
+    if (n > 0) {
+      rows[i] = JSON.stringify(obj)
+      lines++
+      blocks += n
+    }
+  }
+
+  if (!blocks) return { lines: 0, blocks: 0 } // every server_tool_use was already a legal Anthropic one
+
+  // Atomic write — a crash mid-write must never leave a truncated transcript.
+  const tmp = `${file}.tp-sanitize.tmp`
+  fs.writeFileSync(tmp, rows.join('\n'))
+  fs.renameSync(tmp, file)
+  return { lines, blocks }
+}
+
+/**
+ * Resolve cwd+sessionId to a path and sanitize. Wrapped so a sanitize failure
+ * can never block session start — worst case the room behaves as it did before.
+ * Returns the same shape as sanitizeTranscript.
+ */
+export function sanitizeSession(cwd, sessionId) {
+  if (!sessionId) return { lines: 0, blocks: 0 }
+  try {
+    return sanitizeTranscript(transcriptPath(cwd, sessionId))
+  } catch {
+    return { lines: 0, blocks: 0 }
+  }
+}