thinkpool-pair 0.7.159 → 0.7.161

package/account.mjs

@@ -16,7 +16,8 @@ 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 { supervisorServes } from './serve-consent.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'
 
@@ -231,6 +232,13 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
   process.stderr.write(`\n  ◆ thinkpool-pair — account mode · ${email}\n    New sessions auto-serve from ${_effDefault}${loadDefaultDir() ? ' (your default)' : (claudeRecentProjectDir() ? ' (your most-recent Claude Code project)' : '')}\n    (change it: npx thinkpool-pair set-default-dir <dir>  ·  one room: npx thinkpool-pair bind <code> <dir>)\n${svcHint}`)
 
   const children = new Map()   // room -> child process
+  // grantCooldown: room -> wall-clock ms deadline. A grantee child that yielded to the
+  // owner's returning bridge (exit 75) parks its room here so discovery does NOT re-spawn a
+  // child that would only yield again — the owner-serves/grantee-stands-by coexistence state
+  // must not thrash-churn every 15s tick (DEFECT 2, 2026-07-05). Expires after TP_GRANT_COOLDOWN_MS;
+  // after that discovery retries once — serving normally if the owner has since gone.
+  const grantCooldown = new Map()
+  const GRANT_COOLDOWN_MS = Math.max(15_000, parseInt(process.env.TP_GRANT_COOLDOWN_MS, 10) || 120_000)
   const childIdle = new Map()    // room -> bool (last idle report: in the quiet window)
   const childBetween = new Map() // room -> bool (between turns now — safe to restart per Contract #1)
   const childPeer = new Map()  // room -> bool (a web client is watching this room)
@@ -362,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.
@@ -554,6 +611,13 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
     for (const r of rooms) {
       const room = r.code
       if (!room || children.has(room)) { if (room) refused.delete(room); continue }   // served → not refused
+      // Grant-reclaim cooldown (DEFECT 2): this room's grantee child recently yielded to the
+      // owner's bridge (exit 75). Skip re-serving it until the window elapses so we don't
+      // thrash-respawn a child that will only yield again. refused already reads 'owner-serves'
+      // (set on that exit below), so presence stays honest while we stand by.
+      const cdUntil = grantCooldown.get(room)
+      if (roomInCooldown(cdUntil, Date.now())) continue
+      if (cdUntil) grantCooldown.delete(room)   // window elapsed — allow one fresh attempt (owner may have gone)
       // Defense-in-depth behind the .or above: serve iff we OWN the room or hold its grant.
       if (!supervisorServes({ ownerId: r.owner_id, grantUid: r.serve_grant_uid, myUid: me })) continue
       // Resolve the serve dir: explicit bind > last-served memory > launch dir. REFUSE
@@ -673,13 +737,22 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
           try { w.reply(m) } catch { /* reply path gone */ }
         }
       })
-      const dropRoom = () => {
+      const dropRoom = (code) => {
         children.delete(room); childIdle.delete(room); childBetween.delete(room); childPeer.delete(room); roomNames.delete(room); roomPartner.delete(room)   // re-served on the next tick
+        // Owner-reclaim SENTINEL (75): the grantee child stood down because the owner's bridge
+        // returned. Park the room on a cooldown so discovery doesn't respawn it into another
+        // immediate yield (DEFECT 2), and mark refused 'owner-serves' so presence is honest.
+        // A revoke-yield exits 0 (discovery drops a revoked room anyway); owner-owned rooms
+        // never yield, so neither cools down. `code` is undefined on the 'error' path — fine.
+        if (shouldCooldownOnExit(code)) {
+          grantCooldown.set(room, Date.now() + GRANT_COOLDOWN_MS)
+          refused.set(room, 'owner-serves')
+        }
         // Fail any in-flight cross-room peeks/posts this dead room had ASKED (bus-origin
         // entries have askerRoom null and just time out on their own).
         for (const [reqId, w] of pairPending) { if (w?.askerRoom === room) pairPending.delete(reqId) }
       }
-      child.on('exit', dropRoom)
+      child.on('exit', (code) => dropRoom(code))
       // A spawn that never starts (execPath/cwd vanished between the existsSync check and
       // spawn) emits 'error', NOT 'exit'. Without this handler the stale children-map entry
       // would block re-serving forever AND an unhandled 'error' would crash the supervisor.

package/bridge.mjs

@@ -37,7 +37,11 @@ import { fileURLToPath } from 'node:url'
 import { createRequire } from 'node:module'
 import { randomUUID } from 'node:crypto'
 import { createClient } from '@supabase/supabase-js'
-import { serveDecision, amGrantee, standDownOnPeerAnnounce, standDownOnGrantChange, fetchServeRow, refusalMessage } from './serve-consent.mjs'
+import { serveDecision, amGrantee, standDownOnPeerAnnounce, standDownOnGrantChange, fetchServeRow, refusalMessage, gateFailAction, GRANT_RECLAIM_EXIT } from './serve-consent.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'
@@ -586,8 +590,33 @@ let yielding = false         // set once when standing down, so reclaim + revoke
   // Standalone room mode ran anon unless TP_ACCESS_TOKEN was in env; load the stored
   // login so `npx thinkpool-pair <CODE>` authenticates AS the signed-in user (the
   // identity the consent check needs). Account children already carry the env token.
+  // Refresh the stored access token BEFORE the gate (DEFECT 1, 2026-07-05). A stored
+  // access token is minted at login and Supabase access tokens expire ~1h; a long-lived
+  // standalone bridge — or a service relaunched from a stale store — would otherwise hit
+  // the RLS-gated gate with a DEAD token: fetchServeRow → 401, which (old behavior) masked
+  // as a network error and FAILED OPEN → the consent gate was bypassed in the common case.
+  // authedClient exchanges the rotated refresh token for a live pair and persists it via
+  // saveAuth (refresh-token rotation: the used token is now dead, so the store must never be
+  // left on the stale pair). Only refresh when the token came from the STORE — an env token
+  // (TP_ACCESS_TOKEN, from a supervisor that already keeps it fresh) is left untouched.
+  let tokenFromStore = false
   if (!codeAuthToken) {
-    try { const { loadAuth } = await import('./auth-store.mjs'); codeAuthToken = loadAuth()?.access_token || null } catch { /* no store — stays anon */ }
+    try {
+      const { loadAuth } = await import('./auth-store.mjs')
+      codeAuthToken = loadAuth()?.access_token || null
+      if (codeAuthToken) tokenFromStore = true
+    } catch { /* no store — stays anon */ }
+  }
+  if (tokenFromStore) {
+    try {
+      const { authedClient } = await import('./account.mjs')
+      const refreshed = await authedClient(SUPABASE_URL, SUPABASE_ANON)
+      if (refreshed?.session?.access_token) codeAuthToken = refreshed.session.access_token
+      // If the refresh FAILS (dead refresh token / offline), keep the stale token: an
+      // offline refresh must not strand a legit owner. A dead refresh token then yields a
+      // 401 at fetchServeRow → refuse (correct: the login is genuinely gone); a transient
+      // offline refresh yields a fetch reject → fail-open (correct: availability).
+    } catch { /* account module / refresh failed — proceed with the stored token */ }
   }
   try {
     if (codeAuthToken) {
@@ -606,8 +635,15 @@ let yielding = false         // set once when standing down, so reclaim + revoke
     iServeAsGrantee = amGrantee({ ownerId, grantUid, myUid: myServeUid })
     if (iServeAsGrantee) process.stderr.write(`\n  ◆ serving room ${room} by the owner's grant — will yield if the owner's bridge returns or the grant is revoked.\n`)
   } catch (e) {
-    // Fail OPEN on a network/transport error ONLY (spec: never strand a user on a
-    // flaky fetch). A clean "no row / not granted" is a decision above, not a throw.
+    // A THROWN fetchServeRow error is either a definitively-bad auth (401/403) or an
+    // availability failure (5xx / transport reject). Only the latter fails OPEN — a stale
+    // 401 must NEVER serve, or the gate is bypassed (DEFECT 1). gateFailAction classifies.
+    if (gateFailAction(e) === 'refuse') {
+      process.stderr.write(refusalMessage({ room, name: null, reason: 'no-identity' }))
+      process.stderr.write(`\n  ◇ (serve-consent: auth rejected at the gate — ${e.message}; the stored login is expired or revoked. Re-run: npx thinkpool-pair login)\n`)
+      process.exit(0)
+    }
+    // Availability failure → fail OPEN (spec: never strand a user on a flaky fetch).
     process.stderr.write(`\n  ◇ serve-consent check degraded (${e.message}); proceeding without it.\n`)
   }
 }
@@ -902,7 +938,13 @@ function onPeerBridgeAnnounce (payload) {
   if (!standDownOnPeerAnnounce({ myUid: myServeUid, ownerId: roomOwnerId, peerUid: payload?.uid })) return
   yielding = true
   process.stderr.write(`\n  ◆ owner's bridge reconnected — yielding room ${room}.\n`)
-  shutdown(0)
+  // Exit with the grant-reclaim SENTINEL (not a clean 0). A supervisor that spawned this
+  // grantee child reads the code and puts the room on a cooldown, so it does NOT respawn a
+  // child that will only yield again — the owner-serves/grantee-stands-by coexistence state
+  // must not thrash-churn every discovery tick (DEFECT 2, 2026-07-05). shutdown() still sets
+  // shuttingDown FIRST, so the term-exit broadcast stays suppressed and structured terminal
+  // rows survive the stand-down (#205/#208 durability — a handover must not delete rows).
+  shutdown(GRANT_RECLAIM_EXIT)
 }
 
 // ── Thinkpool Ensemble — cross-ROOM reach (Tier 1: same-machine pair peek) ────
@@ -1374,12 +1416,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.
@@ -1557,7 +1599,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
@@ -1723,6 +1765,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) => {
@@ -1753,7 +1796,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
@@ -1937,7 +1980,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).
@@ -2282,7 +2330,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
     }
@@ -2390,7 +2438,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)
@@ -2573,7 +2621,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.159",
+  "version": "0.7.161",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -37,6 +37,7 @@
     "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/serve-consent.mjs

@@ -74,9 +74,16 @@ export function standDownOnGrantChange ({ myUid, ownerId, grantUid }) {
 
 // fetchServeRow — read the room's consent columns with whatever identity the bridge
 // holds (authed token → RLS returns the row if the user is a member; anon → empty).
-// THROWS on a network/transport error so the caller can fail OPEN (never strand a
-// user on a flaky fetch). A clean HTTP response that simply yields no row is NOT a
-// throw — it returns { ownerId: null } and the caller refuses (unknown room).
+// THROWS on a non-OK response or a transport error. The thrown error carries `.authHard`
+// so the caller can tell the two apart (Contract C-CODE-3 invariant 2, hardened 2026-07-05):
+//   - 401/403 (authHard === true) → auth is DEFINITIVELY bad (dead/expired token). The
+//     caller REFUSES: a stale access token must never fail OPEN into serving, or the gate
+//     is bypassed in the common case (stored tokens expire ~1h). The caller refreshes the
+//     token BEFORE the gate, so a 401 here means the refresh also failed → genuinely unauthed.
+//   - 5xx / genuine fetch() reject (authHard === false) → availability failure. The caller
+//     fails OPEN (never strand a user on a flaky network / a Supabase blip).
+// A clean HTTP response that simply yields no row is NOT a throw — it returns
+// { ownerId: null } and the caller refuses (unknown room).
 export async function fetchServeRow ({ supabaseUrl, anonKey, token, room }) {
   const headers = { apikey: anonKey }
   if (token) headers.Authorization = `Bearer ${token}`
@@ -84,7 +91,12 @@ export async function fetchServeRow ({ supabaseUrl, anonKey, token, room }) {
     `${supabaseUrl}/rest/v1/code_sessions?select=owner_id,serve_grant_uid,name&code=eq.${encodeURIComponent(room)}`,
     { headers },
   )
-  if (!r.ok) throw new Error(`code_sessions fetch ${r.status}`)
+  if (!r.ok) {
+    const err = new Error(`code_sessions fetch ${r.status}`)
+    err.status = r.status
+    err.authHard = r.status === 401 || r.status === 403
+    throw err
+  }
   const rows = await r.json()
   const row = Array.isArray(rows) ? rows[0] : null
   return {
@@ -94,6 +106,36 @@ export async function fetchServeRow ({ supabaseUrl, anonKey, token, room }) {
   }
 }
 
+// gateFailAction — pure classifier for a THROWN fetchServeRow error at the boot gate.
+// 'refuse'    — auth is definitively bad (401/403 after a token refresh); do NOT fail open.
+// 'fail-open' — an availability error (5xx, offline, transport reject); serve rather than
+//               strand a user on a flaky fetch. This is the ONLY fail-open path.
+export function gateFailAction (err) {
+  return err?.authHard ? 'refuse' : 'fail-open'
+}
+
+// ── supervisor grant-reclaim cooldown (DEFECT 2, 2026-07-05) ──────────────────
+// A grantee child that yields to the owner's returning bridge exits with this SENTINEL
+// code (distinct from a clean 0 / a crash 1). The supervisor reads the exit code and puts
+// the room on a cooldown so it does NOT thrash-respawn a child that will only yield again —
+// the feature's INTENDED coexistence state (owner serves, grantee stands by) must not churn.
+// A revoke-yield keeps exit 0 (discovery drops a revoked room anyway); owner-owned rooms
+// never yield, so they never cool down.
+export const GRANT_RECLAIM_EXIT = 75
+
+// shouldCooldownOnExit — did this child exit BECAUSE the owner reclaimed the room (75)?
+// Only that exit arms the cooldown; a clean stop (0), a crash (1), or a signal (null) do not.
+export function shouldCooldownOnExit (code) {
+  return code === GRANT_RECLAIM_EXIT
+}
+
+// roomInCooldown — is a room still inside its grant-reclaim cooldown window? The supervisor
+// discovery tick skips re-serving while this is true. `until` is a wall-clock ms deadline
+// (Date.now() + window); a null/expired deadline means serve again (owner may have gone).
+export function roomInCooldown (until, now) {
+  return !!(until && now < until)
+}
+
 // refusalMessage — the human-facing stderr line when a bridge refuses to serve.
 export function refusalMessage ({ room, name, reason }) {
   const label = name ? `"${name}"` : '(unnamed)'