thinkpool-pair 0.7.160 → 0.7.162

package/account.mjs

@@ -16,6 +16,7 @@ import os from 'node:os'
 import { saveAuth, loadAuth, loadDirs, bindDir, loadServed, rememberServed, loadDefaultDir, saveDefaultDir, claudeRecentProjectDir } from './auth-store.mjs'
 import { isSafeToRestart } from './update-gate.mjs'
 import { makeThrottledTrack } from './presence.mjs'
+import { publicKeyB64, announceProviders, listProviders, addProvider, removeProvider, unseal } from './providers.mjs'
 import { supervisorServes, shouldCooldownOnExit, roomInCooldown } from './serve-consent.mjs'
 import { resolveServeDir } from './serve-dir.mjs'
 import { pairKeyFor, pairTopic, CROSSROOM_BUS } from './cross-terminal.mjs'
@@ -369,7 +370,56 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
   // service (always-on, survives reboot) vs a foreground `npx` run that dies with its
   // terminal. THINKPOOL_PAIR_AUTOUPDATE=1 is set ONLY by the install-service plist/unit
   // (service.mjs), so it's the reliable proxy for "running as the managed service".
-  const pushPresence = () => trackPresence({ name: machine, version: VERSION, rooms: [...children.keys()], refused: [...refused].map(([code, reason]) => ({ code, reason })), service: process.env.THINKPOOL_PAIR_AUTOUPDATE === '1', ts: Date.now() })
+  // providerPubKey: the bridge's RSA-OAEP public key (SPKI base64), generated +
+  // persisted 0600 on first read. The dashboard imports it to SEAL a provider's API
+  // key so it reaches the bridge without ever crossing the wire in the clear. Computed
+  // ONCE (the keypair is stable across restarts). `providers` is the name-only registry
+  // (id+name+model, NEVER the key or baseUrl) so the dashboard can list what's available
+  // to spawn against — re-read each announce so an add/remove reflects immediately.
+  // Both are additive; older clients ignore them (feature: multi-provider BYOK, slice 1).
+  const PROVIDER_PUBKEY = publicKeyB64()
+  const pushPresence = () => trackPresence({ name: machine, version: VERSION, rooms: [...children.keys()], refused: [...refused].map(([code, reason]) => ({ code, reason })), service: process.env.THINKPOOL_PAIR_AUTOUPDATE === '1', providerPubKey: PROVIDER_PUBKEY, providers: announceProviders(), ts: Date.now() })
+
+  // ── Provider registry — the multi-BYOK wire contract (slice 1). ─────────────
+  // AUTH: the account channel `tpacct:<uid>` is created WITHOUT config.private:true,
+  // so it is a PUBLIC realtime channel — NOT RLS-gated (the existing shutdown/restart
+  // handlers ride the same public channel; accepted for those, NOT for key management).
+  // Every provider event therefore carries the sender's `jwt` (session access token);
+  // we verify getUser(jwt).id === the owner uid before ANY registry mutation or read.
+  // Only the owner manages their own keys on their own machine — a partner is refused.
+  const OWNER_UID = session.user.id
+  const isOwner = async (jwt) => {
+    if (!jwt || typeof jwt !== 'string') return false
+    try { const { data } = await sb.auth.getUser(jwt); return !!data?.user && data.user.id === OWNER_UID } catch { return false }
+  }
+  const provReply = (event, payload) => { try { acct.send({ type: 'broadcast', event, payload }) } catch { /* channel down */ } }
+  // provider-add {sealed, nonce, jwt} → decrypt, validate, append, re-announce.
+  acct.on('broadcast', { event: 'provider-add' }, async ({ payload }) => {
+    const nonce = payload?.nonce
+    if (!(await isOwner(payload?.jwt))) return provReply('provider-add-res', { nonce, ok: false, error: 'unauthorized' })
+    let fields
+    // Decrypt failures answer ok:false WITHOUT logging the ciphertext or plaintext
+    // (security invariant d) — a bare boolean, never the sealed blob or the key.
+    try { fields = unseal(payload?.sealed) } catch { return provReply('provider-add-res', { nonce, ok: false, error: 'could not decrypt the sealed payload' }) }
+    const r = addProvider(fields)
+    if (r.ok) { pushPresence(); process.stderr.write(`\n  ◆ provider added (${String(fields?.name || '').slice(0, 40)}) — re-announced.\n`) }
+    provReply('provider-add-res', { nonce, ok: r.ok, error: r.ok ? undefined : r.error, id: r.ok ? r.id : undefined })
+  })
+  // provider-remove {id, nonce, jwt} → remove (built-in refuses), re-announce.
+  acct.on('broadcast', { event: 'provider-remove' }, async ({ payload }) => {
+    const nonce = payload?.nonce
+    if (!(await isOwner(payload?.jwt))) return provReply('provider-remove-res', { nonce, ok: false, error: 'unauthorized' })
+    const r = removeProvider(payload?.id)
+    if (r.ok) { pushPresence(); process.stderr.write('\n  ◆ provider removed — re-announced.\n') }
+    provReply('provider-remove-res', { nonce, ok: r.ok, error: r.ok ? undefined : r.error })
+  })
+  // providers-list-req {nonce, jwt} → the masked list (keyHint = last 4 chars only).
+  acct.on('broadcast', { event: 'providers-list-req' }, async ({ payload }) => {
+    const nonce = payload?.nonce
+    if (!(await isOwner(payload?.jwt))) return provReply('providers-list-res', { nonce, ok: false, error: 'unauthorized', providers: [] })
+    provReply('providers-list-res', { nonce, ok: true, providers: listProviders() })
+  })
+
   // Re-track on EVERY (re)subscribe, not just the first: a realtime reconnect
   // (network blip, or a token swap mid-flight) rejoins the channel and must
   // re-announce, or the dashboard would read "no bridge" until the next restart.

package/bridge.mjs

@@ -38,6 +38,11 @@ import { createRequire } from 'node:module'
 import { randomUUID } from 'node:crypto'
 import { createClient } from '@supabase/supabase-js'
 import { serveDecision, amGrantee, standDownOnPeerAnnounce, standDownOnGrantChange, fetchServeRow, refusalMessage, gateFailAction, GRANT_RECLAIM_EXIT } from './serve-consent.mjs'
+import { reapTerminalRow as _reapTerminalRow } from './reap-terminal.mjs'
+// resolveProviderEnv(id) → {ANTHROPIC_BASE_URL,ANTHROPIC_AUTH_TOKEN,ANTHROPIC_MODEL} for a
+// registered custom provider, or null for the built-in/unknown (leave the default env intact).
+// Multi-provider BYOK slice 1: a lane spawned with a `provider` id runs on that endpoint.
+import { resolveProviderEnv } from './providers.mjs'
 import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
 import { z } from 'zod'
 import { startClaudeSession } from './claude-session.mjs'
@@ -570,6 +575,28 @@ async function refreshOwnerPlan() {
     if (rows?.[0]?.plan) ownerPlan = rows[0].plan === 'plus' ? 'plus' : 'free'
   } catch { /* DNS-flaky / offline — keep the safe default; the next token refresh retries */ }
 }
+
+// ── Bridge-side row reap (Contract §Bridge-side reap, 2026-07-04) ───────────────
+// A cleanly-closed structured lane's code_terminals row must be gone within seconds
+// REGARDLESS of any client tab being open. The client-side reap (#205, room.jsx's
+// `term-exit` handler) only runs in whichever browser tab happens to catch the transient
+// broadcast — close a lane while no fresh tab is listening (stale/asleep) and the broadcast
+// evaporates, leaving a permanent dormant ghost row (three hand-deleted 2026-07-04/05).
+// The bridge is the ONE authoritative witness of a clean structured close, so it reaps the
+// row itself. RLS: code_terminals_member_delete permits DELETE to any parent-session member;
+// this bridge serves as the room owner or an authed grantee (codeAuthToken), so it qualifies.
+// Anon bridges (no token) skip — the client reap covers them, as it does old bridges (#205
+// is kept as-is). Idempotent: a fast client tab may reap first (204 / 0 rows is fine).
+// Best-effort: any failure is swallowed and the client reap remains the fallback.
+// Suppressed while shuttingDown — a late cleanupFlowLanes timer firing during teardown /
+// stand-down / restart must NOT delete rows: dormant lanes across a restart are the feature.
+// Thin wrapper: close over the bridge's LIVE state (codeAuthToken + shuttingDown are
+// reassigned over the process life, so read them at call time) and delegate to the
+// unit-tested reap-terminal.mjs. Fire-and-forget from endStructured — the module never
+// throws (best-effort), so an unawaited promise can't reject.
+function reapTerminalRow(id) {
+  return _reapTerminalRow({ id, token: codeAuthToken, supabaseUrl: SUPABASE_URL, anonKey: SUPABASE_ANON, shuttingDown })
+}
 // ── Room-serve owner consent (Contract C-CODE-3) ──────────────────────────────
 // A room is served by its OWNER's bridge; a non-owner may serve only with the
 // owner's explicit grant (code_sessions.serve_grant_uid). Enforced HERE — before the
@@ -1412,12 +1439,12 @@ function worktreeSnapshot(cwd) {
 // relay STRUCTURED events. onEvent → broadcast `code-event` + print locally +
 // persist to the host file; tool calls round-trip through the perm card; the
 // rolling log replays to joiners and survives bridge restarts (session-store).
-function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rolePrompt, flowSessionId, flowTaskKey, cwd, reviewSliceRoots, openedAt, defer }) {
+function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rolePrompt, flowSessionId, flowTaskKey, cwd, reviewSliceRoots, openedAt, defer, provider }) {
   if (sessions.has(id)) return
   // spawnedBy: set when this lane was Dispatched (spawn_terminal). Restored from the
   // session store so the Ensemble flag survives a bridge restart (else a respin
   // stripped it and the lane reverted to a plain tab — the t6 "no chip" bug).
-  const entry = { cmd: 'claude', kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: Array.isArray(commands) ? commands : undefined, mode, model: model || null, spawnedBy: spawnedBy || undefined, flowSessionId: flowSessionId || null, flowTaskKey: flowTaskKey || null, cwd: cwd || null,
+  const entry = { cmd: 'claude', kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: Array.isArray(commands) ? commands : undefined, mode, model: model || null, provider: provider || null, spawnedBy: spawnedBy || undefined, flowSessionId: flowSessionId || null, flowTaskKey: flowTaskKey || null, cwd: cwd || null,
     // Stable creation order — persisted so a bridge restart restores tabs in the SAME
     // order (not readdir/filesystem order). Legacy recs (no openedAt) derive it from the
     // first transcript event ts, so even the first post-fix restart is ordered right.
@@ -1595,7 +1622,7 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
   // restart. Without this, sessionData omitted it → on restart the resumed session
   // re-launched on the host default (Opus) regardless of the last switch, and the
   // switch looked like it "never changed the model" (Max 2026-07-02). Restored below.
-  const sessionData = () => ({ sessionId: entry.session?.sessionId || resume || null, log: entry.log, commands: entry.commands, mode: entry.mode, model: entry.model || null, spawnedBy: entry.spawnedBy, flowSessionId: entry.flowSessionId, flowTaskKey: entry.flowTaskKey, cwd: entry.cwd, rolePrompt: entry.rolePrompt, flowReviewTarget: entry.flowReviewTarget || null, revertTarget: entry.revertTarget || null, reviewSliceRoots: entry.reviewSliceRoots || [], openedAt: entry.openedAt || null })
+  const sessionData = () => ({ sessionId: entry.session?.sessionId || resume || null, log: entry.log, commands: entry.commands, mode: entry.mode, model: entry.model || null, provider: entry.provider || null, spawnedBy: entry.spawnedBy, flowSessionId: entry.flowSessionId, flowTaskKey: entry.flowTaskKey, cwd: entry.cwd, rolePrompt: entry.rolePrompt, flowReviewTarget: entry.flowReviewTarget || null, revertTarget: entry.revertTarget || null, reviewSliceRoots: entry.reviewSliceRoots || [], openedAt: entry.openedAt || null })
   const persist = () => saveSession(room, id, sessionData())
   // Synchronous flush of this session's record. Used on open (so a brand-new session
   // has a file under its id BEFORE its first event — surviving a restart inside the
@@ -1761,6 +1788,7 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
           name: z.string().max(80).optional().describe('a short label for the new lane so the room (and you) can find it, e.g. "Research: topologies"'),
           task: z.string().optional().describe('an initial task to hand the new lane immediately; omit to open it idle'),
           model: z.string().optional().describe('optional model for the lane, e.g. opus / sonnet / haiku'),
+          provider: z.string().optional().describe('optional registered LLM provider id to run this lane on (from the account\'s provider registry); omit for the default Claude/Anthropic path'),
           mode: z.enum(['default', 'acceptEdits', 'bypassPermissions', 'plan']).optional().describe('permission mode for the new lane; defaults to inheriting YOUR current mode. Raising a lane to bypassPermissions from a non-bypass lane asks the room to confirm once.'),
         },
         async (args) => {
@@ -1791,7 +1819,7 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
           // plan-mode lane would stall on ExitPlanMode cards. An explicit args.mode still wins;
           // otherwise inherit, but fall plan → default (an autonomous worker doesn't plan-gate).
           const childMode = args?.mode || (entry.mode === 'plan' ? 'default' : entry.mode)
-          openStructured({ id: newId, model: args?.model, mode: childMode })
+          openStructured({ id: newId, model: args?.model, provider: args?.provider, mode: childMode })
           const ne = sessions.get(newId)
           if (!ne) { if (args?.name) { delete termNames[newId]; saveNames(room, termNames) } return okText('Could not open a new lane — the terminal cap may have just been reached. Close one and retry.') }
           ne.spawnedBy = id   // ownership: only the spawner may close_terminal it
@@ -1975,7 +2003,12 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
     // Tier 3 — the SENDER-side gate for post_to_session (the receipt card lives in
     // the target room). roomHop/crossRoomPostCount reset on a real human turn (code-turn).
     crossRoomPostGate: () => crossRoomPostDecision({ roomHop: entry.roomHop || 0, postCount: entry.crossRoomPostCount || 0, disabled: process.env.TP_PAIRBUS_OFF === '1' }),
-    env: { ...process.env, ...buildConductorEnv({ flowSessionId, mode }), TP_MOCKUP_OUTBOX: mockupOutbox },
+    // Per-lane provider (multi-BYOK slice 1): a lane opened with a registered `provider`
+    // id runs on THAT Anthropic-compatible endpoint. resolveProviderEnv → {ANTHROPIC_BASE_URL,
+    // ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL}, spread AFTER process.env so it overrides the
+    // per-machine default (provider.mjs/applyProviderEnv). null for built-in/unknown → the
+    // default Claude env is left exactly as-is (unchanged path).
+    env: { ...process.env, ...buildConductorEnv({ flowSessionId, mode }), ...(resolveProviderEnv(provider) || {}), TP_MOCKUP_OUTBOX: mockupOutbox },
     onEvent: (evt) => {
       // Self-heal a stale resume — the saved SDK session expired. Reopen fresh,
       // keeping the transcript (scrollback survives; live context is gone).
@@ -2203,6 +2236,8 @@ function endStructured(id) {
     try { s.mockupWatcher?.close() } catch { /* noop */ }
     sessions.delete(id)
     bcast('term-exit', { id })
+    reapTerminalRow(id)    // bridge-side reap: delete the code_terminals row ourselves — the
+                           // client reap (#205) evaporates if no fresh tab caught the broadcast
     fireImageCleanup(id)   // drop this term's screenshots from Storage (COGS)
     // EN-m3 — closing a spawner ORPHANS the lanes it spawned (only that spawner could
     // close_terminal them; they can never be closed otherwise + keep occupying the caps).
@@ -2320,7 +2355,7 @@ channel
       // previous terminal's model (and the first uses the provider default). Falls
       // through to the SDK default when absent. Stamped on the entry so the announce
       // carries it at open (chip shows the model immediately, not the branch).
-      openStructured({ id: payload.id, mode: payload.mode, model: payload.model || undefined })
+      openStructured({ id: payload.id, mode: payload.mode, model: payload.model || undefined, provider: payload.provider || undefined })
       process.stderr.write(`\n  ◆ web opened a structured "${payload.cmd}" session (${payload.mode || 'default'}${payload.model ? `, model ${payload.model}` : ''}).\n`)
       return
     }
@@ -2428,7 +2463,7 @@ channel
   // ── structured-session control (Phase 2) ──
   .on('broadcast', { event: 'code-open' }, ({ payload }) => {
     if (payload?.host && payload.host !== name) return
-    openStructured({ id: payload?.id || randomUUID(), model: payload?.model, resume: payload?.resume, mode: payload?.mode })
+    openStructured({ id: payload?.id || randomUUID(), model: payload?.model, provider: payload?.provider, resume: payload?.resume, mode: payload?.mode })
   })
   .on('broadcast', { event: 'code-turn' }, async ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)
@@ -2611,7 +2646,7 @@ channel
             // FL-M6 — restore the flow context (id/role/cwd) so an in-flight flow survives a
             // bridge restart: the conductor keeps its subagent-block + plan interception, and
             // lanes keep their worktree cwd + the ability to mark done.
-            openStructured({ id: rec.id, model: rec.model || undefined, resume: canResume(rec) ? rec.sessionId : undefined, log: rec.log, commands: rec.commands, mode: rec.mode, spawnedBy: rec.spawnedBy, flowSessionId: rec.flowSessionId, flowTaskKey: rec.flowTaskKey, cwd: rec.cwd, rolePrompt: rec.rolePrompt, reviewSliceRoots: rec.reviewSliceRoots, openedAt: rec.openedAt,
+            openStructured({ id: rec.id, model: rec.model || undefined, provider: rec.provider || undefined, resume: canResume(rec) ? rec.sessionId : undefined, log: rec.log, commands: rec.commands, mode: rec.mode, spawnedBy: rec.spawnedBy, flowSessionId: rec.flowSessionId, flowTaskKey: rec.flowTaskKey, cwd: rec.cwd, rolePrompt: rec.rolePrompt, reviewSliceRoots: rec.reviewSliceRoots, openedAt: rec.openedAt,
               // Lazy-boot restored terminals that were IDLE + not part of a flow: their transcript
               // shows immediately; the query boots on first turn. Mid-turn + flow terminals boot now
               // (mid-turn needs auto-resume; flow needs its lane live).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.160",
+  "version": "0.7.162",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -32,11 +32,13 @@
     "flow-skill-registry.mjs",
     "serve-dir.mjs",
     "serve-consent.mjs",
+    "reap-terminal.mjs",
     "service.mjs",
     "presence.mjs",
     "account.mjs",
     "auth-store.mjs",
     "provider.mjs",
+    "providers.mjs",
     "README.md"
   ],
   "scripts": {

package/providers.mjs

@@ -0,0 +1,232 @@
+/* ─────────────────────────────────────────────────────────────
+   providers.mjs — the bridge's LLM-provider REGISTRY (multi-BYOK).
+
+   Slice 1 of the multi-provider BYOK feature (spec:
+   docs/specs/2026-07-05-llm-provider-registry.md). Lets a user register
+   extra Anthropic-compatible providers (name + base url + model + API
+   key) on their OWN bridge; a Code lane can then spawn against any
+   registered provider by id. Keys live ONLY on the bridge host — they are
+   never broadcast, never written to the DB, never in an announce.
+
+   This module owns:
+     • providers.json   — the registry ({id,name,baseUrl,model,key,addedAt}[]), 0600
+     • bridge-key.json  — the bridge's RSA keypair, 0600 (host-only)
+     • seal/unseal      — the hybrid envelope the dashboard uses to hand the
+                          bridge a key WITHOUT it ever crossing the wire in the
+                          clear (RSA-OAEP wraps an AES-256-GCM session key).
+     • env resolution   — {ANTHROPIC_BASE_URL,ANTHROPIC_AUTH_TOKEN,ANTHROPIC_MODEL}
+                          for a chosen provider id, matching provider.mjs conventions.
+
+   The built-in `anthropic` provider (the host's regular Claude login) is
+   IMPLICIT: never stored, never removable, always present. A lane with no
+   provider id runs the default Claude path unchanged.
+
+   ── Why HYBRID sealing, not raw RSA ──────────────────────────────────
+   RSA-OAEP-2048/SHA-256 caps plaintext at 190 bytes. A real payload —
+   {name,baseUrl,model,key} with e.g. an OpenAI `sk-proj-…` key (~164 chars)
+   plus JSON overhead — blows past that and RSA encrypt throws. So `sealed`
+   is a hybrid envelope: RSA-OAEP wraps a fresh 32-byte AES key, AES-256-GCM
+   encrypts the payload. Both ends are WebCrypto-native (browser dashboard
+   seals, Node bridge unseals). Envelope shape (base64 of UTF8 JSON):
+     { v:1, ek:base64(RSA-OAEP(aesKeyRaw)), iv:base64(12B), ct:base64(gcmCiphertext||16B-tag) }
+   WebCrypto's subtle.encrypt returns ciphertext||tag concatenated; Node's
+   createDecipheriv wants the tag separately, so unseal splits the last 16.
+
+   ── Auth (see account.mjs handlers) ─────────────────────────────────
+   The account channel `tpacct:<uid>` is a PUBLIC realtime channel (no
+   config.private:true), so it is NOT RLS-gated — the sender is verified at
+   the application layer (getUser(jwt).id === owner uid) before any registry
+   mutation. This module stays transport-agnostic; the caller does auth.
+   ───────────────────────────────────────────────────────────── */
+import os from 'node:os'
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+const DIR       = path.join(os.homedir(), '.thinkpool-pair')
+const REG_FILE  = path.join(DIR, 'providers.json')
+const KEY_FILE  = path.join(DIR, 'bridge-key.json')
+
+// The built-in provider id — always present, never stored, never removable.
+export const BUILTIN_ID = 'anthropic'
+
+function ensureDir() { try { fs.mkdirSync(DIR, { recursive: true, mode: 0o700 }) } catch { /* noop */ } }
+
+// ── registry load / save ───────────────────────────────────────────────
+/** @returns {Array<{id:string,name:string,baseUrl:string,model?:string,key:string,addedAt:number}>} */
+export function loadProviders() {
+  try {
+    const arr = JSON.parse(fs.readFileSync(REG_FILE, 'utf8'))
+    return Array.isArray(arr) ? arr.filter((p) => p && p.id && p.id !== BUILTIN_ID) : []
+  } catch { return [] }
+}
+
+function saveProviders(arr) {
+  ensureDir()
+  fs.writeFileSync(REG_FILE, JSON.stringify(arr, null, 2), { mode: 0o600 })
+  // Writing with { mode } only applies on CREATE; harden an existing file too.
+  try { fs.chmodSync(REG_FILE, 0o600) } catch { /* noop */ }
+}
+
+// ── keypair ─────────────────────────────────────────────────────────────
+// Generate an RSA-OAEP-2048 keypair on first run, persist 0600, return the
+// public key as SPKI base64 (what the dashboard imports) + the private key
+// object (for unseal). Idempotent: a persisted key is reused.
+let _keyCache = null
+export function ensureKeypair() {
+  if (_keyCache) return _keyCache
+  ensureDir()
+  try {
+    const saved = JSON.parse(fs.readFileSync(KEY_FILE, 'utf8'))
+    if (saved?.publicKeyB64 && saved?.privateKeyPem) {
+      _keyCache = {
+        publicKeyB64: saved.publicKeyB64,
+        privateKey: crypto.createPrivateKey({ key: saved.privateKeyPem, format: 'pem' }),
+      }
+      return _keyCache
+    }
+  } catch { /* generate below */ }
+
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('rsa', { modulusLength: 2048 })
+  const publicKeyB64 = publicKey.export({ type: 'spki', format: 'der' }).toString('base64')
+  const privateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' })
+  fs.writeFileSync(KEY_FILE, JSON.stringify({ publicKeyB64, privateKeyPem, createdAt: Date.now() }, null, 2), { mode: 0o600 })
+  try { fs.chmodSync(KEY_FILE, 0o600) } catch { /* noop */ }
+  _keyCache = { publicKeyB64, privateKey }
+  return _keyCache
+}
+
+/** SPKI base64 public key for the announce (`providerPubKey`). */
+export function publicKeyB64() { return ensureKeypair().publicKeyB64 }
+
+// ── seal / unseal (hybrid RSA-OAEP + AES-256-GCM) ───────────────────────
+// seal() is here so the UNIT can drive both ends node-side; the real seal
+// happens in the browser dashboard via WebCrypto against the same envelope.
+/** @param {object} payload  @param {string=} pubKeyB64  → base64(envelope JSON) */
+export function seal(payload, pubKeyB64) {
+  const spkiB64 = pubKeyB64 || publicKeyB64()
+  const publicKey = crypto.createPublicKey({ key: Buffer.from(spkiB64, 'base64'), format: 'der', type: 'spki' })
+  const aesKey = crypto.randomBytes(32)
+  const iv = crypto.randomBytes(12)
+  const cipher = crypto.createCipheriv('aes-256-gcm', aesKey, iv)
+  const enc = Buffer.concat([cipher.update(JSON.stringify(payload), 'utf8'), cipher.final()])
+  const tag = cipher.getAuthTag()
+  const ek = crypto.publicEncrypt(
+    { key: publicKey, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' },
+    aesKey,
+  )
+  const envelope = {
+    v: 1,
+    ek: ek.toString('base64'),
+    iv: iv.toString('base64'),
+    ct: Buffer.concat([enc, tag]).toString('base64'),   // ct||tag, matches WebCrypto
+  }
+  return Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64')
+}
+
+/**
+ * Decrypt a sealed envelope with the bridge private key. Returns the parsed
+ * payload object, or throws. Callers MUST catch and answer ok:false WITHOUT
+ * logging the ciphertext or plaintext (security invariant d).
+ * @param {string} sealedB64  base64(envelope JSON)
+ */
+export function unseal(sealedB64) {
+  const { privateKey } = ensureKeypair()
+  const env = JSON.parse(Buffer.from(String(sealedB64 || ''), 'base64').toString('utf8'))
+  if (!env || env.v !== 1 || !env.ek || !env.iv || !env.ct) throw new Error('bad envelope')
+  const aesKey = crypto.privateDecrypt(
+    { key: privateKey, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' },
+    Buffer.from(env.ek, 'base64'),
+  )
+  const iv = Buffer.from(env.iv, 'base64')
+  const ctTag = Buffer.from(env.ct, 'base64')
+  if (ctTag.length < 16) throw new Error('bad ciphertext')
+  const tag = ctTag.subarray(ctTag.length - 16)
+  const ct = ctTag.subarray(0, ctTag.length - 16)
+  const decipher = crypto.createDecipheriv('aes-256-gcm', aesKey, iv)
+  decipher.setAuthTag(tag)
+  const dec = Buffer.concat([decipher.update(ct), decipher.final()])
+  return JSON.parse(dec.toString('utf8'))
+}
+
+// ── CRUD ────────────────────────────────────────────────────────────────
+function validate({ name, baseUrl, key }) {
+  if (!name || typeof name !== 'string' || !name.trim()) return 'name is required'
+  if (!key || typeof key !== 'string' || !key.trim()) return 'key is required'
+  let u
+  try { u = new URL(String(baseUrl)) } catch { return 'baseUrl must be a valid https url' }
+  if (u.protocol !== 'https:') return 'baseUrl must be https'
+  return null
+}
+
+/**
+ * Append a provider. `fields` = {name, baseUrl, model?, key} (already unsealed).
+ * @returns {{ok:true,id:string} | {ok:false,error:string}}
+ */
+export function addProvider(fields) {
+  const err = validate(fields || {})
+  if (err) return { ok: false, error: err }
+  const arr = loadProviders()
+  const id = crypto.randomUUID()
+  arr.push({
+    id,
+    name: String(fields.name).trim(),
+    baseUrl: String(fields.baseUrl).trim(),
+    model: fields.model ? String(fields.model).trim() : undefined,
+    key: String(fields.key).trim(),
+    addedAt: Date.now(),
+  })
+  saveProviders(arr)
+  return { ok: true, id }
+}
+
+/**
+ * Remove a provider by id. The built-in `anthropic` refuses.
+ * @returns {{ok:true} | {ok:false,error:string}}
+ */
+export function removeProvider(id) {
+  if (!id || id === BUILTIN_ID) return { ok: false, error: 'the built-in Anthropic provider cannot be removed' }
+  const arr = loadProviders()
+  const next = arr.filter((p) => p.id !== id)
+  if (next.length === arr.length) return { ok: false, error: 'no such provider' }
+  saveProviders(next)
+  return { ok: true }
+}
+
+// ── read-only projections (never expose the raw key) ────────────────────
+/** Masked list for the dashboard: keyHint = last 4 chars only. Built-in first. */
+export function listProviders() {
+  const custom = loadProviders().map((p) => ({
+    id: p.id,
+    name: p.name,
+    model: p.model || null,
+    keyHint: keyHint(p.key),
+  }))
+  return [{ id: BUILTIN_ID, name: 'Anthropic (Claude)', model: null, keyHint: null }, ...custom]
+}
+
+/** Name-only projection for the announce/presence payload — NO key, NO baseUrl. */
+export function announceProviders() {
+  const custom = loadProviders().map((p) => ({ id: p.id, name: p.name, model: p.model || null }))
+  return [{ id: BUILTIN_ID, name: 'Anthropic (Claude)', model: null }, ...custom]
+}
+
+function keyHint(key) {
+  const k = String(key || '')
+  return k.length <= 4 ? k : k.slice(-4)
+}
+
+/**
+ * Resolve the spawn env for a provider id, matching provider.mjs conventions
+ * exactly (ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_MODEL).
+ * Built-in / unknown id → null (the caller leaves the default Claude env intact).
+ * @returns {{ANTHROPIC_BASE_URL:string,ANTHROPIC_AUTH_TOKEN:string,ANTHROPIC_MODEL?:string} | null}
+ */
+export function resolveProviderEnv(id) {
+  if (!id || id === BUILTIN_ID) return null
+  const p = loadProviders().find((x) => x.id === id)
+  if (!p) return null
+  const env = { ANTHROPIC_BASE_URL: p.baseUrl, ANTHROPIC_AUTH_TOKEN: p.key }
+  if (p.model) env.ANTHROPIC_MODEL = p.model
+  return env
+}

package/reap-terminal.mjs

@@ -0,0 +1,47 @@
+// Bridge-side reap of a cleanly-closed structured lane's code_terminals row.
+//
+// Spec: docs/specs/2026-07-04-structured-terminal-durability.md §Bridge-side reap.
+//
+// WHY this exists: the row-reap on a clean structured close (endStructured / MCP
+// close_terminal) used to be CLIENT-executed only — it ran in whichever browser tab
+// caught the transient `term-exit` broadcast (room.jsx #205). Close a lane while no fresh
+// tab is listening (stale / asleep) → the broadcast evaporates → a permanent dormant ghost
+// row (three hand-deleted 2026-07-04/05). The bridge is the ONE authoritative witness of a
+// clean structured close, so it reaps the row ITSELF — the client reap is kept as the
+// fallback for old bridges and for the fast-tab case.
+//
+// Extracted from bridge.mjs (which has top-level side effects and can't be unit-imported)
+// so the reap DECISION + REST shape are testable with an injected fetch — same pattern as
+// serve-consent.mjs. bridge.mjs wraps this, closing over its live codeAuthToken /
+// shuttingDown state.
+//
+// RLS: `code_terminals_member_delete` permits DELETE to any member of the parent code
+// session; the bridge serves as the room owner or an authed grantee (codeAuthToken), so it
+// qualifies. Anon bridges (no token) skip — the client reap covers them.
+//
+// Scope guard: NEVER reap while shuttingDown — a late cleanupFlowLanes timer firing during
+// teardown / stand-down / restart must not delete rows. Dormant lanes across a restart are
+// the feature, not the leak.
+
+/**
+ * @returns {Promise<{reaped: boolean, reason: 'ok'|'shutdown'|'anon'|'no-id'|'error', error?: string}>}
+ *   Never throws — best-effort; the client reap (#205) is the fallback.
+ */
+export async function reapTerminalRow ({ id, token, supabaseUrl, anonKey, shuttingDown = false, fetchImpl = fetch }) {
+  if (shuttingDown) return { reaped: false, reason: 'shutdown' }
+  if (!token)       return { reaped: false, reason: 'anon' }
+  if (!id)          return { reaped: false, reason: 'no-id' }
+  try {
+    // Mirror of the client reap: DELETE code_terminals WHERE id = <terminal id>. The
+    // terminal id IS the code_terminals PK (client/bridge-minted uuid). RLS scopes the
+    // delete to this bridge's sessions, so id alone is sufficient + idempotent (a fast
+    // client tab may have reaped first — 204 / 0 rows is fine).
+    await fetchImpl(`${supabaseUrl}/rest/v1/code_terminals?id=eq.${encodeURIComponent(id)}`, {
+      method: 'DELETE',
+      headers: { apikey: anonKey, Authorization: `Bearer ${token}` },
+    })
+    return { reaped: true, reason: 'ok' }
+  } catch (e) {
+    return { reaped: false, reason: 'error', error: e?.message }
+  }
+}