thinkpool-pair 0.7.187 → 0.7.189

package/bridge.mjs

@@ -92,18 +92,33 @@ const flowRedispatch = new Map()
 // wave BEFORE overrun. Lives bridge-side because waves dispatch across separate
 // broadcasts; without persistent state the cap can never bite.
 const flowBudgets = new Map()
-import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, SPAWN, CROSSROOM, formatPairRoster, crossRoomPostDecision, formatRoomNow } from './cross-terminal.mjs'
+import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, SPAWN, CROSSROOM, formatPairRoster, crossRoomPostDecision, formatRoomNow, formatClosableHint } from './cross-terminal.mjs'
 import { turnInFlight } from './update-gate.mjs'
 import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames, appendDurableEvents, seedDurableEvents, readDurablePage, readDurableOldestSeq, hasDurableArchive, servesHistoryPage } from './session-store.mjs'
 import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks, usageReportLine, buildRecapFromLog, RECAP_CAP, trimmedBeforeSeq, firstSeq } from './event-id.mjs'
 import { planMeterLine } from './plan-meters.mjs'
 import { makeThrottledTrack } from './presence.mjs'
+import { resolveAnonKey, DEFAULT_SUPABASE_URL } from './supabase-key.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.
-const SUPABASE_URL  = process.env.TP_SUPABASE_URL  || 'https://daytvtakmlixpfbbqzjd.supabase.co'
+const SUPABASE_URL  = process.env.TP_SUPABASE_URL  || DEFAULT_SUPABASE_URL
 const WEB_BASE      = process.env.TP_WEB_BASE      || 'https://thinkpool.io'
-const SUPABASE_ANON = process.env.TP_SUPABASE_ANON || 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImRheXR2dGFrbWxpeHBmYmJxempkIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzgwNTMxNzEsImV4cCI6MjA5MzYyOTE3MX0.zYmz8bHUNEY4STUr2JuXChAsKwxNwkwFHe1Hd0Betqo'
+
+// The anon key is RESOLVED, not baked. It used to be a string literal here, and
+// that literal now sits in 224 published tarballs on 224 users' laptops: disable
+// the key and every one of them dies at once, unfixable from our side. So we ask
+// thinkpool.io/api/config for it (cached on disk, 6h), and keep the literal only
+// as the offline fallback. A key rotation now repairs itself server-side, even
+// for a bridge that never updates. Order: env → cache → network → stale → baked.
+// See bridge/supabase-key.mjs and docs/specs/2026-07-10-supabase-key-migration.md §5.1.
+const { key: SUPABASE_ANON, source: ANON_KEY_SOURCE } = await resolveAnonKey({
+  supabaseUrl: SUPABASE_URL,
+  webBase: WEB_BASE,
+  log: (m) => { if (process.env.TP_DEBUG) console.error(`  ◇ ${m}`) },
+})
+// The SOURCE is diagnostic and safe to print; the KEY never is (C16).
+if (process.env.TP_DEBUG) console.error(`  ◇ supabase anon key source: ${ANON_KEY_SOURCE}`)
 
 // Owner access token for AUTHED web writes (currently /api/code-mockup, whip L16).
 // The room-bridge is anon by design; the account supervisor (account.mjs) owns the
@@ -1920,7 +1935,7 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
       // fork-bomb breaker, now one level deeper (2026-07-10 cascade-spawn-depth spec).
       tool(
         'spawn_terminal',
-        'Open a NEW agent terminal (a fresh Claude lane) in this ThinkPool Code room — YOUR lane to use, not a sibling that is already working. Use it to fan work out: give it an initial `task` and it runs in parallel in its own lane; collect its result later with read_terminal, and close it with close_terminal when done. By default the new lane INHERITS your current permission mode — so if you are in bypass, it runs autonomously with no per-action clicking; pass `mode` to override. ALWAYS prefer spawning a fresh lane over post_to_terminal into one that is already busy. Tier guidance: default worker lanes to opus; use sonnet for mechanical work (renames, boilerplate, doc sweeps); reserve your own model for planning/review. Bounded by the room terminal cap and a per-turn limit.',
+        'Open a NEW agent terminal (a fresh Claude lane) in this ThinkPool Code room — YOUR lane to use, not a sibling that is already working. Use it to fan work out: give it an initial `task` and it runs in parallel in its own lane; collect its result later with read_terminal, then ALWAYS close_terminal it — a finished lane left open holds a slot against the room cap and blocks the next fan-out. By default the new lane INHERITS your current permission mode — so if you are in bypass, it runs autonomously with no per-action clicking; pass `mode` to override. ALWAYS prefer spawning a fresh lane over post_to_terminal into one that is already busy. Tier guidance: default worker lanes to opus; use sonnet for mechanical work (renames, boilerplate, doc sweeps); reserve your own model for planning/review. Bounded by the room terminal cap and a per-turn limit.',
         {
           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'),
@@ -1940,7 +1955,15 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
             plan: ownerPlan,                                                        // Free 3 / Plus 6 dispatch ceiling
             disabled: process.env.TP_SPAWN_OFF === '1',
           })
-          if (!gate.ok) return okText(gate.reason)
+          // A refusal that says "close one" without saying WHICH one sends the caller
+          // hunting. Adapt the live roster to the pure helper: only lanes THIS caller
+          // spawned and that aren't mid-turn — the exact set close_terminal accepts.
+          if (!gate.ok) return okText(gate.reason + formatClosableHint(id, [...sessions.entries()].map(([sid, s]) => ({
+            ref: String(sid).slice(0, 8),
+            name: termNames[sid] || undefined,
+            spawnedBy: s.spawnedBy,
+            busy: s.session?.turnActive ?? false,
+          }))))
           // Record this spawn, pruning timestamps that have already left the window
           // (identical predicate to recentSpawnCount) so the array can't grow unbounded.
           entry.spawnTimes = [...(entry.spawnTimes || []).filter((t) => Number.isFinite(t) && t > now - SPAWN.windowMs), now]

package/claude-session.mjs

@@ -700,7 +700,7 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
       'RUN IT, DO NOT ASK: verify your own work before calling it done. Actually run or serve what you changed, observe that it behaves correctly, and show the evidence in the room — a screenshot of the running result, the passing test output, or the real response — rather than telling the user "this should work, go test it." If you could not verify something, say exactly what is unverified. This room follows verify-before-claiming: runtime evidence you produced, not assertion.',
       'CROSS-TERMINAL AWARENESS: this room may have other terminals open alongside yours — other agents working, or shells the people are driving. You have a READ-ONLY tool, read_terminal: call it with no arguments to list the other open terminals, or with a terminal ref/id/command to read that terminal\'s recent activity. Reach for it when your work depends on what another terminal is doing (e.g. someone says "see what the other terminal hit", or you need to coordinate with a sibling agent before acting). It only ever reads — it never changes another terminal. Identify a terminal by its NAME or its ref/id from the roster, never by an on-screen number like "Terminal 2" — those positional labels renumber when a terminal is closed, so they do not reliably point at a lane.',
       'CROSS-TERMINAL HAND-OFF: you also have post_to_terminal(terminal, text) to send a message or task to ANOTHER AGENT terminal in this room (not a plain shell). Use it sparingly and only when the people clearly want the lanes to coordinate — e.g. "tell the backend terminal the API is ready", or to hand a sibling agent a concrete task. Every post requires a person in the room to approve a card before it is delivered, and an agent that was itself reached via a cross-post cannot post onward — so do not rely on it for chit-chat or loops. Prefer read_terminal to understand a sibling before you ever post to it.',
-      'CROSS-TERMINAL SPAWN: when a person asks you to fan work out across multiple agents — research lanes, parallel sub-tasks, a swarm — open YOUR OWN fresh lanes with spawn_terminal(name?, task?, model?); do NOT dump the work into siblings that are already busy (a sibling is mid-task unless read_terminal shows it idle, and hijacking it derails their work). spawn_terminal opens a brand-new Claude lane and, if you pass `task`, hands it that task immediately; it appears as a new terminal in the room. A spawned lane INHERITS your current permission mode by default — so if you are in bypass, your lanes run autonomously with no per-action clicking; pass `mode` only to override. Raising a lane to bypass from a non-bypass lane asks the room to confirm once (everything else spawns without a prompt). Collect each lane\'s result later with read_terminal (a spawned lane cannot post back to you), and tidy up with close_terminal once you have what you need — you may only close lanes you spawned yourself. You are bounded: a sliding spawn-burst window, a per-plan dispatch ceiling on concurrent spawned lanes (Free 3 / Plus 6) that is separate from the human terminals so it never blocks them, an overall machine cap on live lanes, and a DEPTH bound — a lane opened by a person may spawn workers, and those workers may spawn one further level (a conductor dispatching its crew), but that second level can never spawn onward (so no runaway). This is how you "open the terminals yourself" instead of asking a person to.',
+      'CROSS-TERMINAL SPAWN: when a person asks you to fan work out across multiple agents — research lanes, parallel sub-tasks, a swarm — open YOUR OWN fresh lanes with spawn_terminal(name?, task?, model?); do NOT dump the work into siblings that are already busy (a sibling is mid-task unless read_terminal shows it idle, and hijacking it derails their work). spawn_terminal opens a brand-new Claude lane and, if you pass `task`, hands it that task immediately; it appears as a new terminal in the room. A spawned lane INHERITS your current permission mode by default — so if you are in bypass, your lanes run autonomously with no per-action clicking; pass `mode` only to override. Raising a lane to bypass from a non-bypass lane asks the room to confirm once (everything else spawns without a prompt). Collect each lane\'s result later with read_terminal (a spawned lane cannot post back to you). CLOSING IS PART OF THE JOB, not housekeeping you get to skip: the moment you have read a lane\'s result and acted on it, close_terminal it. A finished lane left open holds a slot against the room\'s machine cap and against your dispatch ceiling, so the NEXT fan-out — yours, or a person\'s — gets refused; rooms silt up with dead lanes exactly this way. Before each new wave of spawns, list your open lanes (read_terminal with no argument) and close the finished ones first. If a spawn is refused for capacity, the refusal names your own idle lanes so you do not have to hunt. You may only close lanes you spawned yourself — never close a sibling\'s, and never close one that is mid-turn. You are bounded: a sliding spawn-burst window, a per-plan dispatch ceiling on concurrent spawned lanes (Free 3 / Plus 6) that is separate from the human terminals so it never blocks them, an overall machine cap on live lanes, and a DEPTH bound — a lane opened by a person may spawn workers, and those workers may spawn one further level (a conductor dispatching its crew), but that second level can never spawn onward (so no runaway). This is how you "open the terminals yourself" instead of asking a person to.',
       'CROSS-SESSION AWARENESS: the Ensemble reaches across your SESSIONS, not just the terminals in this room. list_sessions() lists your OTHER ThinkPool Code rooms — both your own rooms running on this machine AND your partner\'s rooms in the same pair, reachable over the per-pair bus (a room on the partner\'s machine shows its host). read_session(session, terminal?) reads recent activity inside one (omit `terminal` to list that room\'s terminals, or pass a ref/name to read that lane). Both are READ-ONLY — they never change another session, and they reach ONLY your own rooms and rooms you share with your partner, never a stranger\'s. Reach for them when work spans rooms — "what\'s the other project up to", "pick up where the other session left off", or to check a long-running task elsewhere before you act here.',
       'CROSS-SESSION HAND-OFF: post_to_session(session, text, terminal?) sends a task or message to an agent in ANOTHER of your rooms — your own, or your partner\'s over the pair bus. Use it sparingly and only when the people clearly want the rooms to coordinate — e.g. hand the API room\'s agent a concrete follow-up once the frontend is ready. It is dual-consent: a person in YOUR room approves sending, and a person in the TARGET room approves receiving, before anything is delivered — so never rely on it for chit-chat or loops, and an agent that was itself reached via a cross-room post cannot post onward to a third room. It spends real model tokens in the other room (maybe on the other person\'s machine), so prefer read_session to understand a room before you ever post into it, and only post one concrete hand-off at a time. All of this works only under the ThinkPool account bridge; a standalone room sees just its own terminals.',
       'SUBAGENT POLICY: in this room, delegated work goes through the Ensemble. When you fan out research, parallel sub-tasks, reviews, or any substantive multi-step delegated work, open spawn_terminal lanes — they are visible in the room, the people can watch and steer them, and every other lane can peer at their work. Do NOT reach for the built-in Task/Agent subagents for that work: an in-process subagent is invisible to the room, cannot be peered at or steered, and its work is lost to the Ensemble. The only exception is a trivial, seconds-scale read-only lookup where a room lane would be pure overhead.',

package/cross-terminal.mjs

@@ -284,6 +284,29 @@ export const spawnDecision = ({ hop = 0, spawnTimes = [], now = 0, spawnedLive =
   return { ok: true }
 }
 
+// When a spawn is refused, "close one before opening another" is useless advice if the
+// caller has to go hunting for WHICH one. Rooms fill up with finished lanes nobody
+// closed (Max, 2026-07-10: "clean up the finished ensemble terminals there's a lot"),
+// because the old preamble asked politely and nothing named the cost. So the refusal
+// now names the caller's OWN idle spawned lanes — the exact ones close_terminal will
+// accept — newest last, capped so a long list can't drown the reason above it.
+//
+// Pure: takes the roster, returns a string. `lanes` = [{ ref, name, spawnedBy, busy }].
+// Only lanes this caller spawned are suggested: close_terminal refuses the others, and
+// suggesting a sibling's lane is how you get an agent killing someone else's work.
+export const CLOSABLE_HINT_MAX = 6
+export const closableLanes = (callerId, lanes = []) =>
+  (Array.isArray(lanes) ? lanes : []).filter((l) => l && l.spawnedBy === callerId && !l.busy)
+
+export const formatClosableHint = (callerId, lanes = [], max = CLOSABLE_HINT_MAX) => {
+  const idle = closableLanes(callerId, lanes)
+  if (!idle.length) return ''
+  const shown = idle.slice(0, max)
+  const list = shown.map((l) => `${l.ref}${l.name ? ` ("${l.name}")` : ''}`).join(', ')
+  const more = idle.length > shown.length ? ` (+${idle.length - shown.length} more)` : ''
+  return `\n\nYou have ${idle.length} finished lane${idle.length === 1 ? '' : 's'} of your own still open — collect ${idle.length === 1 ? 'it' : 'them'} with read_terminal, then close_terminal: ${list}${more}`
+}
+
 // ── Tier 1 cross-ROOM peek (read-only, same-machine) ─────────────────────────
 // Thinkpool Ensemble expanded from cross-TERMINAL (sibling lanes in one room) to
 // cross-SESSION (the account's OTHER rooms served by the same account supervisor).

package/key-shape.mjs

@@ -0,0 +1,49 @@
+/* key-shape.mjs — classify a Supabase API key by its SHAPE, and decide whether
+   it is safe to hand to a client.
+
+   Deliberately dependency-free (not even node: builtins beyond Buffer) so it can
+   be imported from BOTH sides of the tarball boundary: the published
+   `thinkpool-pair` bridge and the Vercel serverless function api/config.js.
+
+   Supabase runs two key generations side by side (see
+   docs/specs/2026-07-10-supabase-key-migration.md §1a):
+
+     legacy   a JWT — `eyJ…` — whose `role` payload claim is `anon` or `service_role`
+     new      an opaque string — `sb_publishable_…` or `sb_secret_…`
+
+   Exactly two of those four are client-safe. The other two bypass RLS. Nothing
+   here VERIFIES a signature — that is Supabase's job, over the network, and we
+   have no key material to verify with (§4: nothing in this repo verifies a JWT).
+   We are reading a shape to answer one question: "could this possibly be a
+   secret?" A false "yes" costs a fallback. A false "no" costs the database. */
+
+/** @returns {'publishable'|'secret'|'anon-jwt'|'service-jwt'|'invalid'} */
+export function classifyKey(key) {
+  if (typeof key !== 'string') return 'invalid'
+  const k = key.trim()
+  if (!k) return 'invalid'
+
+  // New-generation keys are self-describing. Check `secret` first: a prefix
+  // test that fails open is exactly the bug this module exists to prevent.
+  if (k.startsWith('sb_secret_')) return 'secret'
+  if (k.startsWith('sb_publishable_')) return 'publishable'
+
+  // Legacy keys are unsigned-to-us JWTs; the role lives in the payload.
+  if (k.startsWith('eyJ')) {
+    const parts = k.split('.')
+    if (parts.length !== 3) return 'invalid'
+    try {
+      const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'))
+      if (payload.role === 'anon') return 'anon-jwt'
+      if (payload.role === 'service_role') return 'service-jwt'
+      return 'invalid' // an unknown role is not a role we will trust
+    } catch { return 'invalid' }
+  }
+  return 'invalid'
+}
+
+/** Only a publishable key or a legacy anon JWT may ever reach a client. */
+export function isClientSafeKey(key) {
+  const c = classifyKey(key)
+  return c === 'publishable' || c === 'anon-jwt'
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.187",
+  "version": "0.7.189",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -42,6 +42,8 @@
     "presence.mjs",
     "account.mjs",
     "auth-store.mjs",
+    "key-shape.mjs",
+    "supabase-key.mjs",
     "provider.mjs",
     "providers.mjs",
     "README.md"

package/supabase-key.mjs

@@ -0,0 +1,176 @@
+/* supabase-key.mjs — resolve the bridge's client-safe Supabase key at RUNTIME.
+
+   THE PROBLEM THIS SOLVES (docs/specs/2026-07-10-supabase-key-migration.md §5.1)
+
+   `bridge.mjs` used to carry the legacy anon key as a string literal:
+
+       const SUPABASE_ANON = process.env.TP_SUPABASE_ANON || 'eyJhbGci…'
+
+   and 224 published `thinkpool-pair` versions shipped with it. The comment above
+   it said "safe to embed" — true about CONFIDENTIALITY (the web bundle ships the
+   same value), silent about LIFECYCLE. Disable that key in the Supabase dashboard
+   and every installed bridge, on every user's laptop, dies at the same instant —
+   and no server-side change repairs it, because Vercel env vars do not reach a
+   program running on someone else's machine. It is the one failure in the repo
+   our deploy pipeline cannot fix.
+
+   THE FIX. The key becomes a value the SERVER controls. The bridge asks
+   thinkpool.io for it at boot, caches it on disk, and keeps the literal only as
+   a last resort. A rotation then repairs itself for bridges that never update.
+
+   RESOLUTION ORDER — each step exists for a reason:
+
+     1 env        TP_SUPABASE_ANON — the operator's explicit override. Always wins.
+     2 cache      A fresh (< TTL) on-disk record. Keeps boot fast and works offline.
+     3 network    GET {WEB_BASE}/api/config. The rotation-repair path.
+     4 stale      An expired cache beats the literal: it is strictly newer.
+     5 baked      The legacy literal. First-ever boot with no network. Never fails.
+
+   TWO INVARIANTS, both tested in supabase-key.test.mjs:
+
+     · A service-shaped key is NEVER adopted, from any source. The network is an
+       input we do not control; a compromised or misconfigured config surface
+       must not be able to hand a user's laptop an RLS-bypassing client.
+     · No key material is ever logged. We log the SOURCE and the SHAPE. (C16.) */
+
+import os from 'node:os'
+import fs from 'node:fs'
+import path from 'node:path'
+import { classifyKey, isClientSafeKey } from './key-shape.mjs'
+
+export { classifyKey, isClientSafeKey }
+
+/* The legacy anon key. Public by design (the web bundle ships it), but now a
+   FALLBACK rather than the source of truth. Do not add new readers. */
+export const BAKED_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImRheXR2dGFrbWxpeHBmYmJxempkIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzgwNTMxNzEsImV4cCI6MjA5MzYyOTE3MX0.zYmz8bHUNEY4STUr2JuXChAsKwxNwkwFHe1Hd0Betqo'
+
+export const DEFAULT_SUPABASE_URL = 'https://daytvtakmlixpfbbqzjd.supabase.co'
+export const DEFAULT_WEB_BASE = 'https://thinkpool.io'
+
+const CACHE_FILE = path.join(os.homedir(), '.thinkpool-pair', 'supabase-key.json')
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000 // 6h — a rotation reaches a rebooting bridge same-day
+const FETCH_TIMEOUT_MS = 2000            // boot latency budget; the literal is right there
+
+// ── the on-disk cache ──────────────────────────────────────────────────────
+// Sits beside auth.json / dirs.json / served.json in ~/.thinkpool-pair.
+// Contains no secret (a publishable key), so no chmod dance — unlike auth.json.
+export function readCacheFile() {
+  try {
+    const rec = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'))
+    if (!rec || typeof rec.key !== 'string' || typeof rec.url !== 'string') return null
+    return { key: rec.key, url: rec.url, at: Number(rec.at) || 0 }
+  } catch { return null }
+}
+
+export function writeCacheFile(rec) {
+  // Atomic, for the same reason auth-store.mjs is: a kill mid-write must never
+  // leave a truncated file that reads as "no cache" — or worse, as half a key.
+  try {
+    fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true })
+    const tmp = `${CACHE_FILE}.${process.pid}.tmp`
+    fs.writeFileSync(tmp, JSON.stringify(rec))
+    fs.renameSync(tmp, CACHE_FILE)
+  } catch { /* a cache we cannot write is a cache we do without */ }
+}
+
+// ── the network step ───────────────────────────────────────────────────────
+// Returns a validated client-safe key, or null. NEVER throws: a bridge must
+// boot on a train. Never logs the value.
+async function fetchConfigKey({ webBase, supabaseUrl, fetchImpl, timeoutMs, log }) {
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(), timeoutMs)
+  try {
+    const r = await fetchImpl(`${webBase}/api/config`, {
+      signal: ac.signal,
+      headers: { accept: 'application/json' },
+    })
+    if (!r || !r.ok) { log(`config: HTTP ${r?.status ?? '?'} — keeping current key`); return null }
+
+    // Until this endpoint is deployed, the SPA catch-all answers /api/config with
+    // 200 + index.html. That must read as "no config", not as a network outage —
+    // every bridge in the wild takes this path on the day before the deploy.
+    let body
+    try { body = await r.json() }
+    catch { log('config: response was not JSON (endpoint not deployed?) — keeping current key'); return null }
+
+    const key = body?.supabaseAnonKey
+
+    // The served key must be for OUR project. A config surface pointing at a
+    // different Supabase project would authenticate against the wrong database.
+    if (body?.supabaseUrl && body.supabaseUrl !== supabaseUrl) {
+      log('config: served a key for a different project — refused')
+      return null
+    }
+    // The invariant. A service-shaped key from the network is never adopted.
+    if (!isClientSafeKey(key)) {
+      log(`config: served a ${classifyKey(key)} key — refused`)
+      return null
+    }
+    return key
+  } catch (e) {
+    log(`config: unreachable (${e.name === 'AbortError' ? 'timeout' : 'network'}) — keeping current key`)
+    return null
+  } finally { clearTimeout(timer) }
+}
+
+// ── the resolver ───────────────────────────────────────────────────────────
+/**
+ * @returns {Promise<{key: string, source: 'env'|'cache'|'network'|'stale-cache'|'baked'}>}
+ * @throws if TP_SUPABASE_ANON is set to something that is not client-safe.
+ */
+export async function resolveAnonKey(opts = {}) {
+  const {
+    env = process.env,
+    supabaseUrl = env.TP_SUPABASE_URL || DEFAULT_SUPABASE_URL,
+    webBase = env.TP_WEB_BASE || DEFAULT_WEB_BASE,
+    fetchImpl = globalThis.fetch,
+    readCache = readCacheFile,
+    writeCache = writeCacheFile,
+    now = Date.now,
+    ttlMs = CACHE_TTL_MS,
+    timeoutMs = FETCH_TIMEOUT_MS,
+    log = () => {},
+  } = opts
+
+  // 1 · env — the operator said so. But an operator who exports a SECRET key
+  //     here would silently run an RLS-bypassing bridge, so this one throws
+  //     rather than falling through: a wrong explicit answer is worse than none.
+  const fromEnv = String(env.TP_SUPABASE_ANON || '').trim()
+  if (fromEnv) {
+    if (!isClientSafeKey(fromEnv)) {
+      throw new Error(
+        `TP_SUPABASE_ANON is not a client-safe key (looks like: ${classifyKey(fromEnv)}). ` +
+        'Use the project\'s publishable/anon key — never a secret or service_role key.',
+      )
+    }
+    log('key: source=env')
+    return { key: fromEnv, source: 'env' }
+  }
+
+  const cached = readCache()
+  const cacheUsable = !!cached && cached.url === supabaseUrl && isClientSafeKey(cached.key)
+
+  // 2 · a fresh cache — skip the network entirely
+  if (cacheUsable && (now() - cached.at) < ttlMs) {
+    log('key: source=cache')
+    return { key: cached.key, source: 'cache' }
+  }
+
+  // 3 · the network — the whole point of this module
+  const fetched = await fetchConfigKey({ webBase, supabaseUrl, fetchImpl, timeoutMs, log })
+  if (fetched) {
+    writeCache({ key: fetched, url: supabaseUrl, at: now() })
+    log(`key: source=network shape=${classifyKey(fetched)}`)
+    return { key: fetched, source: 'network' }
+  }
+
+  // 4 · a stale cache still beats the literal — it is strictly more recent
+  if (cacheUsable) {
+    log('key: source=stale-cache')
+    return { key: cached.key, source: 'stale-cache' }
+  }
+
+  // 5 · the literal. Offline first boot. Always works, until the day it doesn't.
+  log('key: source=baked')
+  return { key: BAKED_ANON_KEY, source: 'baked' }
+}