thinkpool-pair 0.7.314 → 0.7.316

package/bridge.mjs

@@ -1002,6 +1002,38 @@ function advanceStructuredTurn(entry, now = Date.now()) {
   return true
 }
 
+// Every bridge-authored task must cross the same lifecycle boundary as a
+// browser-authored code-turn. Runtime adapters claim `turnActive` synchronously,
+// but the roster deliberately trusts `_busyAnn`; calling sendTurn directly can
+// therefore leave a real turn painted idle until its first provider event.
+// Keep send + revision + visible echo + rejection boundary + announce atomic so
+// cross-posts, spawned tasks and other non-composer ingress cannot drift again.
+function dispatchStructuredTurn(entry, text, {
+  options,
+  visibleEvent,
+  rejectionMessage = 'The agent did not accept this turn; retry after the lane is available.',
+} = {}) {
+  if (!entry?.session) return { accepted: false, error: new Error('session unavailable') }
+  syncStructuredTurn(entry)
+  let accepted = false
+  let error = null
+  try { accepted = entry.session.sendTurn(text, options) !== false }
+  catch (cause) { error = cause }
+  if (accepted) beginStructuredTurn(entry)
+  else syncStructuredTurn(entry)
+  if (visibleEvent) {
+    pushLog(entry, visibleEvent)
+    bcast('code-event', { term: entry.id, evt: visibleEvent })
+  }
+  if (!accepted) {
+    const failed = { kind: 'error', message: rejectionMessage, recoverable: true }
+    pushLog(entry, failed)
+    bcast('code-event', { term: entry.id, evt: failed })
+  }
+  announce()
+  return { accepted, error }
+}
+
 function dispatchPendingSideContexts(entry) {
   if (!entry?.pendingSideContexts?.length || typeof entry.session?.sendTurn !== 'function') return false
   const outcome = dispatchSideContexts({
@@ -1436,8 +1468,13 @@ async function receiveCrossRoomPost({ fromRoom, fromHost, fromTerminalName, text
   const msg = `[From: room ${fromLabel} — relayed via the ThinkPool cross-room Ensemble, approved by a person in this room]\n${body}`
   const evt = { kind: 'you', text: msg, by: `room ${fromRoom}`, crosspost: true, relaySourceName: String(fromTerminalName || '').trim().slice(0, 80) || undefined }
   autoNameTerminal(targetId, body)
-  stampEvent(evt); pushLog(te, evt); bcast('code-event', { term: targetId, evt })
-  try { if (te.session.sendTurn(msg) === false) return { error: `Could not deliver to room ${room} — the lane refused the turn (check its visible host-memory/runtime error).` } } catch { return { error: `Could not deliver to room ${room} — the lane may have just closed.` } }
+  const dispatched = dispatchStructuredTurn(te, msg, {
+    visibleEvent: evt,
+    rejectionMessage: 'The incoming cross-room task was not accepted; retry after the lane is available.',
+  })
+  if (!dispatched.accepted) return { error: dispatched.error
+    ? `Could not deliver to room ${room} — the lane may have just closed.`
+    : `Could not deliver to room ${room} — the lane refused the turn (check its visible host-memory/runtime error).` }
   return { ok: true, ref: String(targetId).slice(0, 8) }
 }
 
@@ -2252,13 +2289,11 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
     // No revert, no verdict broadcast, no markFlowDone — the loop stays open.
     if (!decision.stop) {
       const next = round + 1
-      try {
-        entry.session?.sendTurn(
-          entry.runtime === 'codex'
-            ? `[Flow review — round ${next}/${REVIEW_DEFAULTS.maxRounds}] The happy path held, but you have NOT reported your checks exhausted. Dig one more round, then call submit_flow_review again — pass:false with specific evidence if you break it, or pass:true AND exhausted:true only when nothing remains to check.`
-            : `[Flow review — round ${next}/${REVIEW_DEFAULTS.maxRounds}] The happy path held, but you have NOT reported your checks exhausted and you are under both the round and budget ceilings. Dig one more round: hunt the edge cases, the reload, the second click, concurrent use, the error path — the places the builder didn't. Then re-Write FLOW_REVIEW.json — pass:false with a specific reason if you break it, or pass:true AND exhausted:true if you genuinely have nothing left to check.`,
-        )
-      } catch { /* lane may have closed mid-verdict */ }
+      dispatchStructuredTurn(entry,
+        entry.runtime === 'codex'
+          ? `[Flow review — round ${next}/${REVIEW_DEFAULTS.maxRounds}] The happy path held, but you have NOT reported your checks exhausted. Dig one more round, then call submit_flow_review again — pass:false with specific evidence if you break it, or pass:true AND exhausted:true only when nothing remains to check.`
+          : `[Flow review — round ${next}/${REVIEW_DEFAULTS.maxRounds}] The happy path held, but you have NOT reported your checks exhausted and you are under both the round and budget ceilings. Dig one more round: hunt the edge cases, the reload, the second click, concurrent use, the error path — the places the builder didn't. Then re-Write FLOW_REVIEW.json — pass:false with a specific reason if you break it, or pass:true AND exhausted:true if you genuinely have nothing left to check.`,
+        { rejectionMessage: 'The next Flow review round was not accepted; retry after the lane is available.' })
       process.stderr.write(`\n  ${A.dim}◆ review round ${round} inconclusive — digging again (${next}/${REVIEW_DEFAULTS.maxRounds}) on ${target || entry.flowTaskKey}${A.rst}\n`)
       return { ok: true, message: `Round ${round} recorded (pass, not yet exhausted). Keep hunting — asked you for round ${next}/${REVIEW_DEFAULTS.maxRounds}.` }
     }
@@ -2362,6 +2397,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
   // It remains scoped to this lane's cwd and private mockup outbox.
   entry.viewport = new ViewportManager({
     workspaceRoot: cwd || process.cwd(), ownerId: id, outbox: mockupOutbox,
+    authContext: () => ({ accessToken: codeAuthToken, supabaseUrl: SUPABASE_URL }),
     designContext: () => {
       const active = designActive.get(id)
       if (!active || active.record.sourceKind !== 'preview') return null
@@ -2672,10 +2708,13 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           // arrived (rides the existing code-event 'you' path — no new topic).
           const evt = { kind: 'you', text: msg, by: `terminal ${fromRef} (agent)`, crosspost: true, relaySourceName: termNames[id] || undefined }
           autoNameTerminal(target.id, args.text)
-          stampEvent(evt)
-          pushLog(te, evt)
-          bcast('code-event', { term: target.id, evt })
-          try { if (te.session.sendTurn(msg) === false) return okText(`Could not deliver to terminal ${target.ref} — it refused the turn. Check its visible host-memory/runtime error.`) } catch { return okText(`Could not deliver to terminal ${target.ref} — it may have just closed.`) }
+          const dispatched = dispatchStructuredTurn(te, msg, {
+            visibleEvent: evt,
+            rejectionMessage: 'The cross-terminal task was not accepted; retry after the lane is available.',
+          })
+          if (!dispatched.accepted) return okText(dispatched.error
+            ? `Could not deliver to terminal ${target.ref} — it may have just closed.`
+            : `Could not deliver to terminal ${target.ref} — it refused the turn. Check its visible host-memory/runtime error.`)
           return okText(`Delivered to terminal ${target.ref} (${target.cmd}). It will respond in its own lane; check back with read_terminal.`)
         },
       )] : []),
@@ -2726,9 +2765,13 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           const msg = `[Task from main terminal ${fromRef}'s agent — opened as an independent MAIN CASCADE CONDUCTOR terminal, not an Ensemble child]\n${String(args.task).trim()}`
           const evt = { kind: 'you', text: msg, by: `main terminal ${fromRef} (agent)`, crosspost: true, relaySourceName: termNames[id] || undefined }
           autoNameTerminal(newId, args.task)
-          stampEvent(evt); pushLog(conductor, evt); bcast('code-event', { term: newId, evt })
-          try { if (conductor.session.sendTurn(msg) === false) return okText(`Opened main conductor ${newRef}, but host pressure prevented its runtime from starting. Existing lanes remain connected; free memory and retry the task.`) }
-          catch { return okText(`Opened main conductor ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — the initial task could not be delivered.`) }
+          const dispatched = dispatchStructuredTurn(conductor, msg, {
+            visibleEvent: evt,
+            rejectionMessage: 'The initial conductor task was not accepted; retry after the lane is available.',
+          })
+          if (!dispatched.accepted) return okText(dispatched.error
+            ? `Opened main conductor ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — the initial task could not be delivered.`
+            : `Opened main conductor ${newRef}, but host pressure prevented its runtime from starting. Existing lanes remain connected; free memory and retry the task.`)
           return okText(`Opened independent main Cascade conductor ${newRef}${args?.name ? ` ("${args.name}")` : ''} and handed it the task. It is a main terminal, not an Ensemble lane.`)
         },
       )] : []),
@@ -2846,8 +2889,13 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
             const msg = `[Task from terminal ${fromRef}'s agent — relayed via ThinkPool Ensemble; you are its WORKER SUB-TERMINAL, never a main terminal or Cascade conductor]\n${args.task}${reviewTarget}`
             const evt = { kind: 'you', text: msg, by: `terminal ${fromRef} (agent)`, crosspost: true, relaySourceName: termNames[id] || undefined }
             autoNameTerminal(newId, args.task)
-            stampEvent(evt); pushLog(ne, evt); bcast('code-event', { term: newId, evt })
-            try { if (ne.session.sendTurn(msg) === false) return okText(`Opened lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but host pressure prevented its runtime from accepting the task. Existing lanes remain connected; free memory and retry.`) } catch { return okText(`Opened lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — could not hand off the task. Try post_to_terminal shortly.`) }
+            const dispatched = dispatchStructuredTurn(ne, msg, {
+              visibleEvent: evt,
+              rejectionMessage: 'The initial worker task was not accepted; retry after the lane is available.',
+            })
+            if (!dispatched.accepted) return okText(dispatched.error
+              ? `Opened lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — could not hand off the task. Try post_to_terminal shortly.`
+              : `Opened lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but host pressure prevented its runtime from accepting the task. Existing lanes remain connected; free memory and retry.`)
             return okText(`Opened agent lane ${newRef}${args?.name ? ` ("${args.name}")` : ''} and handed it the task. It runs in its own lane — check back with read_terminal, then close_terminal when done.`)
           }
           return okText(`Opened idle agent lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}. Hand it work with post_to_terminal, or a person can type into it.`)
@@ -3896,12 +3944,15 @@ channel
         }
         child.hop = 0
         const childEvent = { kind: 'you', text: task, by }
-        stampEvent(childEvent); pushLog(child, childEvent); bcast('code-event', { term: payload.id, evt: childEvent })
         const parentEvent = { kind: 'side-started', sideId: payload.id, sideName, task, by }
-        stampEvent(parentEvent); pushLog(parent, parentEvent); bcast('code-event', { term: sideParent, evt: parentEvent })
+        pushLog(parent, parentEvent); bcast('code-event', { term: sideParent, evt: parentEvent })
         const snapshot = sideSnapshot(parent.log.filter((event) => event.cid !== parentEvent.cid))
         const prompt = snapshot ? `${snapshot}\n\n--- side task ---\n${task}` : task
-        try { if (child.session.sendTurn(prompt) === false) throw new Error('runtime refused the turn') } catch {
+        const dispatched = dispatchStructuredTurn(child, prompt, {
+          visibleEvent: childEvent,
+          rejectionMessage: 'The side-lane task was not accepted; retry after the lane is available.',
+        })
+        if (!dispatched.accepted) {
           bcast('side-open-failed', { id: payload.id, parent: sideParent, message: 'The side agent could not start.' })
           endStructured(payload.id)
           return
@@ -4083,8 +4134,10 @@ channel
     const preparing = { kind: 'control', text: 'Preparing a compact handoff for main…', by }
     stampEvent(preparing); pushLog(side, preparing); bcast('code-event', { term: payload.term, evt: preparing })
     side.flush?.(); announce()
-    try { side.session.sendTurn(SIDE_HANDOFF_PROMPT) }
-    catch {
+    const dispatched = dispatchStructuredTurn(side, SIDE_HANDOFF_PROMPT, {
+      rejectionMessage: 'The side-lane handoff was not accepted; retry after the lane is available.',
+    })
+    if (!dispatched.accepted) {
       side.sideHandback = null
       const failed = { kind: 'control', text: 'Couldn’t start the handoff — try again.', by }
       stampEvent(failed); pushLog(side, failed); bcast('code-event', { term: payload.term, evt: failed })
@@ -4805,7 +4858,9 @@ flowChannel
     // to pin a cheaper/smarter conductor. Lanes get tiered below via laneModelFor.
     openStructured({ id: cid, runtime: flowRuntime, model: conductorModel, mode: flowRuntime === 'codex' ? 'plan' : 'default', rolePrompt: flowRuntime === 'claude' ? FLOW_CONDUCTOR_PROMPT : FLOW_CODEX_CONDUCTOR_PROMPT, flowSessionId: payload.flowId, flowRole: 'conductor', spawnedBy: `flow:${payload.flowId}` })
     const ce = sessions.get(cid)
-    if (ce?.session) { try { ce.session.sendTurn(payload.prompt || '') } catch { /* session still starting */ } }
+    if (ce?.session) dispatchStructuredTurn(ce, payload.prompt || '', {
+      rejectionMessage: 'The Flow conductor task was not accepted; retry after the lane is available.',
+    })
     process.stderr.write(`\n  ${A.mag}◆ flow conductor launched — flow ${String(payload.flowId).slice(0, 8)} (plan mode).${A.rst}\n`)
     announce()
   })
@@ -4952,7 +5007,9 @@ flowChannel
                 `\nProject (context): ${payload.flowPrompt || ''}\n\n` +
                 `Build your slice. Own only your files. Done = it runs + meets acceptance. Commit when done.` +
                 (flowRuntime === 'codex' || flowRuntime === 'hermes' ? ` Then call the ThinkPool mark_flow_done MCP tool; do not write FLOW_DONE.` : '')
-            try { le.session.sendTurn(spec) } catch { /* session still starting */ }
+            dispatchStructuredTurn(le, spec, {
+              rejectionMessage: `Flow slice ${t.task_key} was not accepted; retry after the lane is available.`,
+            })
           }
         }
         assignments.push({ task_key: t.task_key, laneId })

package/flow-worktree.mjs

@@ -11,6 +11,7 @@
 import { execFileSync } from 'node:child_process'
 import path from 'node:path'
 import fs from 'node:fs'
+import { linkLocalEnvIntoWorktree } from './lane-worktree.mjs'
 
 const ROOT = process.cwd()   // the bridge's checkout (the shared main repo root)
 
@@ -33,10 +34,13 @@ export function worktreeSpec ({ flowId, taskKey, root = ROOT }) {
 // fresh `git init` checkout), and the dispatch loop swallowed the throw → NO lane ever
 // spawned. Resolve the first ref that actually exists: caller's base → origin/main →
 // origin/HEAD → main → master → HEAD.
-export function createFlowWorktree ({ flowId, taskKey, base = null, root = ROOT, git = runGit }) {
+export function createFlowWorktree ({ flowId, taskKey, base = null, root = ROOT, git = runGit, fsImpl = fs }) {
   const { branch, dir, wtRoot } = worktreeSpec({ flowId, taskKey, root })
-  if (fs.existsSync(path.join(dir, '.git'))) return { dir, branch, created: false }
-  fs.mkdirSync(wtRoot, { recursive: true })
+  if (fsImpl.existsSync(path.join(dir, '.git'))) {
+    linkLocalEnvIntoWorktree({ root, dir, fsImpl })
+    return { dir, branch, created: false }
+  }
+  fsImpl.mkdirSync(wtRoot, { recursive: true })
   let ref = base
   if (!ref) {
     for (const cand of ['origin/main', 'origin/HEAD', 'main', 'master', 'HEAD']) {
@@ -50,6 +54,7 @@ export function createFlowWorktree ({ flowId, taskKey, base = null, root = ROOT,
     // Branch already exists (a prior dispatch of this task) — check it out instead.
     git(['worktree', 'add', dir, branch], root)
   }
+  linkLocalEnvIntoWorktree({ root, dir, fsImpl })
   return { dir, branch, created: true }
 }
 

package/lane-worktree.mjs

@@ -4,6 +4,27 @@ import { execFileSync } from 'node:child_process'
 import path from 'node:path'
 import fs from 'node:fs'
 
+const LOCAL_ENV_FILES = ['.env.local', '.env.development.local']
+
+// Git deliberately omits local env files from worktrees. That is correct for
+// version control but wrong for an isolated lane that must build/preview the
+// same app as the main checkout: Vite otherwise compiles `undefined` public
+// client config and the preview dies before React mounts. Link, never copy, the
+// main checkout's existing ignored env files. Missing files are a clean no-op.
+export function linkLocalEnvIntoWorktree({ root, dir, fsImpl = fs } = {}) {
+  const linked = []
+  for (const name of LOCAL_ENV_FILES) {
+    const source = path.join(root, name)
+    const target = path.join(dir, name)
+    try {
+      if (!fsImpl.existsSync?.(source) || fsImpl.existsSync?.(target)) continue
+      fsImpl.symlinkSync?.(source, target)
+      linked.push(name)
+    } catch { /* local env is optional; worktree creation must still succeed */ }
+  }
+  return linked
+}
+
 export function createManagedLaneWorktree({ terminalId, cwd = process.cwd(), git = runGit, fsImpl = fs } = {}) {
   const id = String(terminalId || '')
   const short = id.replace(/[^a-zA-Z0-9]/g, '').slice(0, 8)
@@ -15,6 +36,7 @@ export function createManagedLaneWorktree({ terminalId, cwd = process.cwd(), git
   const base = resolveLaneBase({ root, git })
   fsImpl.mkdirSync(path.dirname(dir), { recursive: true })
   git(['worktree', 'add', '-b', branch, dir, base], root)
+  linkLocalEnvIntoWorktree({ root, dir, fsImpl })
   return { terminalId: id, root, dir, branch }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.314",
+  "version": "0.7.316",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {

package/thinkpool-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": 12,
+  "bundleVersion": 13,
   "contracts": [
     {
       "id": "room-coordination",
@@ -41,7 +41,7 @@
     },
     {
       "id": "work-routing",
-      "version": 4,
+      "version": 5,
       "providerRoutingContract": "A Claude lane may select a connected Anthropic-compatible provider by durable id, unique display name, or unique configured model. Unknown or ambiguous references fail closed and must never fall through to built-in Claude.",
       "openerParityContract": "Every top-level terminal may use spawn_terminal or open_main_terminal to open every supported structured runtime: Claude, Codex, or Hermes. Runtime-specific provider/model validation remains authoritative and occurs before inference.",
       "routes": [
@@ -94,7 +94,7 @@
           "id": "visual-proof",
           "tools": ["preview_start", "preview_capture", "preview_inspect", "preview_stop"],
           "trigger": "\\b(ui|ux|visual|design|frontend|html|css|page|route|mockup|screenshot|responsive|desktop|mobile|preview)\\b",
-          "prompt": "For built visual work, run the build, use preview_start, preview_capture at desktop and mobile, preview_inspect when rendered state matters, and preview_stop when finished. preview_capture uses a fresh isolated browser and is inline verification evidence by default; it must not create a transcript card. Set card=true only when the person asked for a mockup/Design artifact or the visual itself is an intentional deliverable that should remain editable in the transcript. A card requires settled meaningful content at both desktop and mobile, rejects loading/public-auth fallback shells, and is delivered after the final agent response. Authenticated app routes require an authenticated visual harness. Surface PNG evidence only when no interactive source-backed Design card is displayed."
+          "prompt": "For built visual work, run the build, use preview_start, preview_capture at desktop and mobile, preview_inspect when rendered state matters, and preview_stop when finished. preview_capture uses a fresh isolated browser and is inline verification evidence by default; it must not create a transcript card. Set card=true only when the person asked for a mockup/Design artifact or the visual itself is an intentional deliverable that should remain editable in the transcript. A card requires settled meaningful content at both desktop and mobile, rejects loading/public-auth fallback shells, and is delivered after the final agent response. Room and protected routes automatically use the bridge account as a read-only authenticated visual harness; external REST writes, presence, ordinary room broadcasts, and refresh-token access are blocked, while non-mutating roster/transcript snapshot requests are allowed. Surface PNG evidence only when no interactive source-backed Design card is displayed."
         }
       ],
       "impact": [

package/viewport.mjs

@@ -25,6 +25,9 @@ export const DEFAULT_VIEWPORTS = Object.freeze({
 
 const MAX_CAPTURE_HEIGHT = 20000
 const MAX_SETTLE_MS = 5000
+const AUTH_READY_TIMEOUT_MS = 15000
+const AUTH_FRESH_MARGIN_SEC = 30
+const PREVIEW_LOCAL_EXPIRY_EXTENSION_SEC = 3600
 const CDP_TIMEOUT_MS = 12000
 const MAX_PORTABLE_SNAPSHOT_BYTES = 1_900_000
 
@@ -88,12 +91,62 @@ export function previewArtifactIssue(route, capture) {
     if (actualRoute && actualRoute !== expectedRoute) return `Preview navigated from ${expectedRoute} to ${actualRoute}.`
     if (state.signedOutInvite) return 'Preview resolved to the signed-out room invitation instead of the authenticated Code room.'
     if (state.visibleBoot) return 'Preview was still showing the application loading shell.'
+    if (state.visibleLoading) return 'Preview was still showing an application loading state.'
     if (protectedRoute && state.prerenderGeo) return 'Preview resolved to the public marketing shell instead of the authenticated Code surface.'
     if (!state.hasBody || (state.textLength < 2 && state.meaningfulVisualCount < 1)) return 'Preview rendered an empty page.'
   }
   return null
 }
 
+export function routeNeedsPreviewAuth(route) {
+  const parsed = new URL(normalizeRoute(route), 'http://127.0.0.1')
+  return !!parsed.searchParams.get('r') || ['/settings', '/contacts', '/code/link'].includes(parsed.pathname)
+}
+
+function decodeJwtPayload(token) {
+  try {
+    const payload = String(token || '').split('.')[1]
+    return payload ? JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) : null
+  } catch { return null }
+}
+
+// Build the minimum Supabase local-storage session needed for a short-lived,
+// read-only visual capture. Never expose the bridge refresh token to Chrome.
+export function previewAuthBootstrap({ accessToken, supabaseUrl, nowSec = Math.floor(Date.now() / 1000), minTtlSec = 0 } = {}) {
+  const claims = decodeJwtPayload(accessToken)
+  let endpoint
+  try { endpoint = new URL(supabaseUrl) } catch { return null }
+  if (!accessToken || endpoint.protocol !== 'https:' || !claims?.sub || !claims?.exp || claims.exp - nowSec <= minTtlSec) return null
+  const projectRef = endpoint.hostname.split('.')[0]
+  if (!projectRef) return null
+  return {
+    storageKey: `sb-${projectRef}-auth-token`,
+    allowedReadOrigins: [endpoint.origin],
+    allowedSocketOrigins: [`wss://${endpoint.host}`],
+    session: {
+      access_token: accessToken,
+      refresh_token: '',
+      // auth-js refreshes 90s early. Extend only its browser-local marker; the
+      // signed JWT keeps its real expiry and is still server-validated per read.
+      expires_in: Math.max(1, claims.exp - nowSec) + PREVIEW_LOCAL_EXPIRY_EXTENSION_SEC,
+      expires_at: claims.exp + PREVIEW_LOCAL_EXPIRY_EXTENSION_SEC,
+      token_type: 'bearer',
+      user: {
+        id: claims.sub,
+        aud: claims.aud || 'authenticated',
+        role: claims.role || 'authenticated',
+        email: claims.email || null,
+        phone: claims.phone || '',
+        app_metadata: claims.app_metadata || {},
+        user_metadata: claims.user_metadata || {},
+        identities: [],
+        created_at: claims.created_at || new Date(nowSec * 1000).toISOString(),
+        updated_at: new Date(nowSec * 1000).toISOString(),
+      },
+    },
+  }
+}
+
 export function findBrowserExecutable({ env = process.env, platform = process.platform, exists = fs.existsSync } = {}) {
   const candidates = [
     env.TP_BROWSER_PATH,
@@ -241,22 +294,51 @@ export class CdpBrowser {
     }
   }
 
-  async withPage({ url, viewport, waitMs = 300 }, fn) {
+  async withPage({ url, viewport, waitMs = 300, auth = null }, fn) {
     await this.ensureStarted()
     const { targetId } = await this.pipe.send('Target.createTarget', { url: 'about:blank' })
     const { sessionId } = await this.pipe.send('Target.attachToTarget', { targetId, flatten: true })
     let unsubscribeRequests = null
+    let unsubscribeResponses = null
+    let unsubscribeExceptions = null
+    const authResponses = []
+    const localResponses = []
+    const runtimeExceptions = []
     try {
       await this.pipe.send('Page.enable', {}, sessionId)
       await this.pipe.send('Runtime.enable', {}, sessionId)
+      await this.pipe.send('Network.enable', {}, sessionId).catch(() => {})
+      if (auth?.storageKey && auth?.session) {
+        const source = `(() => { try { localStorage.setItem(${JSON.stringify(auth.storageKey)}, ${JSON.stringify(JSON.stringify(auth.session))}); window.__TP_READ_ONLY_PREVIEW__ = true; } catch {} })()`
+        await this.pipe.send('Page.addScriptToEvaluateOnNewDocument', { source }, sessionId)
+      }
       // The page is untrusted build output. Keep its network authority narrower
-      // than the lane sandbox: same preview origin only. This blocks internet,
-      // cloud metadata, and other localhost services while still allowing all
-      // JS/CSS/assets served from the selected build directory.
+      // than the lane sandbox: same preview origin plus read-only requests to
+      // the exact Supabase origin provided by the bridge auth context.
       const allowedOrigin = new URL(url).origin
+      const allowedReadOrigins = new Set(auth?.allowedReadOrigins || [])
+      const allowedSocketOrigins = new Set(auth?.allowedSocketOrigins || [])
+      unsubscribeResponses = this.pipe.subscribe('Network.responseReceived', sessionId, (params) => {
+        try {
+          const responseUrl = new URL(params.response?.url || '')
+          if (allowedReadOrigins.has(responseUrl.origin) && authResponses.length < 20) authResponses.push(`${params.response?.status || 0}:${responseUrl.pathname}`)
+          if (responseUrl.origin === allowedOrigin && localResponses.length < 20) localResponses.push(`${params.response?.status || 0}:${responseUrl.pathname}`)
+        } catch { /* diagnostics only */ }
+      })
+      unsubscribeExceptions = this.pipe.subscribe('Runtime.exceptionThrown', sessionId, (params) => {
+        if (runtimeExceptions.length >= 5) return
+        const detail = params.exceptionDetails?.exception?.description || params.exceptionDetails?.text || 'runtime error'
+        runtimeExceptions.push(String(detail).split('\n')[0].slice(0, 180))
+      })
       unsubscribeRequests = this.pipe.subscribe('Fetch.requestPaused', sessionId, (params) => {
         let allowed = false
-        try { allowed = new URL(params.request?.url || '').origin === allowedOrigin } catch { allowed = false }
+        try {
+          const requestUrl = new URL(params.request?.url || '')
+          const requestMethod = String(params.request?.method || 'GET').toUpperCase()
+          allowed = requestUrl.origin === allowedOrigin ||
+            (allowedReadOrigins.has(requestUrl.origin) && ['GET', 'HEAD', 'OPTIONS'].includes(requestMethod)) ||
+            (allowedSocketOrigins.has(requestUrl.origin) && requestMethod === 'GET')
+        } catch { allowed = false }
         const method = allowed ? 'Fetch.continueRequest' : 'Fetch.failRequest'
         const request = allowed
           ? { requestId: params.requestId }
@@ -276,11 +358,57 @@ export class CdpBrowser {
       await this.pipe.send('Runtime.evaluate', {
         expression: 'document.fonts && document.fonts.ready', awaitPromise: true, returnByValue: true,
       }, sessionId).catch(() => {})
-      const settle = Math.min(MAX_SETTLE_MS, Math.max(0, Number(waitMs) || 0))
+      if (auth) {
+        const deadline = Date.now() + AUTH_READY_TIMEOUT_MS
+        let ready = false
+        let readySince = 0
+        while (Date.now() < deadline) {
+          const state = await this.pipe.send('Runtime.evaluate', {
+            expression: `(() => {
+              if (document.querySelector('#invitation-room-title')) return true;
+              if (document.querySelector('#boot, .boot-loader')) return false;
+              const loading = [...document.querySelectorAll('span')].some((node) => /^(loading session|restoring terminals…|connecting(?:…|\.\.\.))$/i.test((node.textContent || '').trim()));
+              return !loading && (document.body?.innerText || '').trim().length > 1;
+            })()`,
+            returnByValue: true,
+          }, sessionId)
+          if (state.result?.value === true) {
+            if (!readySince) readySince = Date.now()
+            if (Date.now() - readySince >= 800) { ready = true; break }
+          } else readySince = 0
+          await new Promise((resolve) => setTimeout(resolve, 100))
+        }
+        if (!ready) {
+          const diagnostic = await this.pipe.send('Runtime.evaluate', {
+            expression: `(async () => {
+              let locks = { held: [], pending: [] };
+              try { locks = await navigator.locks.query(); } catch {}
+              return {
+                sessionPresent: !!localStorage.getItem(${JSON.stringify(auth.storageKey || '')}),
+                inlineBoot: !!document.querySelector('#boot, .boot-loader'),
+                loadingSession: [...document.querySelectorAll('span')].some((node) => (node.textContent || '').trim() === 'Loading session'),
+                connecting: [...document.querySelectorAll('span')].some((node) => (node.textContent || '').trim().toLowerCase() === 'connecting…'),
+                invitation: !!document.querySelector('#invitation-room-title'),
+                heldLocks: locks.held?.length || 0,
+                pendingLocks: locks.pending?.length || 0,
+              };
+            })()`,
+            awaitPromise: true,
+            returnByValue: true,
+          }, sessionId).catch(() => ({ result: { value: {} } }))
+          const d = diagnostic.result?.value || {}
+          throw new Error(`Authenticated preview did not leave its loading state within 15 seconds (session=${d.sessionPresent ? 'present' : 'missing'}, inlineBoot=${d.inlineBoot ? 'yes' : 'no'}, loadingSession=${d.loadingSession ? 'yes' : 'no'}, connecting=${d.connecting ? 'yes' : 'no'}, authLocks=${d.heldLocks || 0}/${d.pendingLocks || 0}, invitation=${d.invitation ? 'yes' : 'no'}, reads=${authResponses.join(',') || 'none'}, local=${localResponses.join(',') || 'none'}, runtime=${runtimeExceptions.join(' | ') || 'none'}); no screenshot was created.`)
+        }
+      }
+      const settle = auth
+        ? Math.min(300, Math.max(0, Number(waitMs) || 0))
+        : Math.min(MAX_SETTLE_MS, Math.max(0, Number(waitMs) || 0))
       if (settle) await new Promise((resolve) => setTimeout(resolve, settle))
       return await fn({ pipe: this.pipe, sessionId })
     } finally {
       unsubscribeRequests?.()
+      unsubscribeResponses?.()
+      unsubscribeExceptions?.()
       await this.pipe.send('Target.closeTarget', { targetId }).catch(() => {})
     }
   }
@@ -302,6 +430,10 @@ export class CdpBrowser {
         textLength: (document.body?.innerText || '').trim().length,
         meaningfulVisualCount: meaningful.length,
         visibleBoot: visible(boot),
+        visibleLoading: [...document.querySelectorAll('span')].some((node) => {
+          const text = (node.textContent || '').trim();
+          return visible(node) && /^(loading session|restoring terminals…|connecting(?:…|\.\.\.))$/i.test(text);
+        }),
         signedOutInvite: !!document.querySelector('#invitation-room-title'),
         prerenderGeo: !!document.querySelector('[data-prerender="geo"]'),
       };
@@ -382,8 +514,8 @@ export class CdpBrowser {
     return html
   }
 
-  async capture({ url, viewport, fullPage = true, waitMs = 300, includeSnapshot = false }) {
-    return this.withPage({ url, viewport, waitMs }, async ({ pipe, sessionId }) => {
+  async capture({ url, viewport, fullPage = true, waitMs = 300, includeSnapshot = false, auth = null }) {
+    return this.withPage({ url, viewport, waitMs, auth }, async ({ pipe, sessionId }) => {
       const beforeState = await this.renderedState(pipe, sessionId)
       const metrics = await pipe.send('Page.getLayoutMetrics', {}, sessionId)
       const contentHeight = Math.ceil(metrics.cssContentSize?.height || viewport.height)
@@ -398,12 +530,12 @@ export class CdpBrowser {
     })
   }
 
-  async snapshot({ url, viewport = DEFAULT_VIEWPORTS.desktop, waitMs = 300 }) {
-    return this.withPage({ url, viewport, waitMs }, ({ pipe, sessionId }) => this.freezeCurrentPage(pipe, sessionId))
+  async snapshot({ url, viewport = DEFAULT_VIEWPORTS.desktop, waitMs = 300, auth = null }) {
+    return this.withPage({ url, viewport, waitMs, auth }, ({ pipe, sessionId }) => this.freezeCurrentPage(pipe, sessionId))
   }
 
-  async inspect({ url, viewport = DEFAULT_VIEWPORTS.mobile, selector, waitMs = 300 }) {
-    return this.withPage({ url, viewport, waitMs }, async ({ pipe, sessionId }) => {
+  async inspect({ url, viewport = DEFAULT_VIEWPORTS.mobile, selector, waitMs = 300, auth = null }) {
+    return this.withPage({ url, viewport, waitMs, auth }, async ({ pipe, sessionId }) => {
       const expression = `(() => {
         const selector = ${JSON.stringify(selector || null)};
         const el = selector ? document.querySelector(selector) : null;
@@ -437,13 +569,14 @@ export class CdpBrowser {
 export const sharedViewportBrowser = new CdpBrowser()
 
 export class ViewportManager {
-  constructor({ workspaceRoot, ownerId, outbox, browser = sharedViewportBrowser, startPreviewImpl = startPreview, designContext = null } = {}) {
+  constructor({ workspaceRoot, ownerId, outbox, browser = sharedViewportBrowser, startPreviewImpl = startPreview, designContext = null, authContext = null } = {}) {
     this.workspaceRoot = path.resolve(workspaceRoot || process.cwd())
     this.ownerId = ownerId || randomUUID()
     this.outbox = outbox || path.join(os.tmpdir(), 'thinkpool-viewport-captures', this.ownerId)
     this.browser = browser
     this.startPreviewImpl = startPreviewImpl
     this.designContext = typeof designContext === 'function' ? designContext : () => null
+    this.authContext = typeof authContext === 'function' ? authContext : () => null
     this.previewId = `viewport:${this.ownerId}`
     this.preview = null
     this.root = null
@@ -479,6 +612,20 @@ export class ViewportManager {
     return new URL(normalizeRoute(route), preview.url).href
   }
 
+  async previewAuth(route) {
+    if (!routeNeedsPreviewAuth(route)) return null
+    let context = this.authContext() || {}
+    if (!context.accessToken) return null
+    const deadline = Date.now() + AUTH_READY_TIMEOUT_MS
+    for (;;) {
+      const auth = previewAuthBootstrap({ ...context, minTtlSec: AUTH_FRESH_MARGIN_SEC })
+      if (auth) return auth
+      if (Date.now() >= deadline) throw new Error('The bridge account token did not refresh in time for an authenticated preview; no screenshot was created.')
+      await new Promise((resolve) => setTimeout(resolve, 250))
+      context = this.authContext() || {}
+    }
+  }
+
   async capture({ route = '/', viewports = 'both', title = 'Viewport capture', fullPage = true, waitMs = 300, card = false } = {}) {
     const normalizedRoute = normalizeRoute(route)
     const url = this.pageUrl(normalizedRoute)
@@ -500,6 +647,7 @@ export class ViewportManager {
       captures[name] = await this.browser.capture({
         url, viewport: DEFAULT_VIEWPORTS[name], fullPage, waitMs,
         includeSnapshot: cardRequested && name === (names.includes('desktop') ? 'desktop' : names[0]),
+        auth: await this.previewAuth(normalizedRoute),
       })
     }
     // The screenshot and readiness state must come from the SAME page. The old
@@ -507,10 +655,10 @@ export class ViewportManager {
     // production proved the preflight could see marketing content while the
     // screenshot caught only the boot spinner.
     const cardReady = cardRequested && !!(captures.desktop && captures.mobile)
-    if (cardReady) {
+    if (cardReady || routeNeedsPreviewAuth(normalizedRoute)) {
       for (const [name, capture] of Object.entries(captures)) {
         const issue = previewArtifactIssue(normalizedRoute, capture)
-        if (issue) throw new Error(`${name} deliverable rejected: ${issue} No mockup card was created.`)
+        if (issue) throw new Error(`${name} preview rejected: ${issue} No screenshot or mockup card was created.`)
       }
     }
     const snapshot = captures.desktop?.snapshot || captures.mobile?.snapshot || null
@@ -541,9 +689,13 @@ export class ViewportManager {
     return { url, slug, manifestPath, captures, snapshotPath, cardReady }
   }
 
-  inspect({ route = '/', viewport = 'mobile', selector, waitMs = 300 } = {}) {
+  async inspect({ route = '/', viewport = 'mobile', selector, waitMs = 300 } = {}) {
     if (!DEFAULT_VIEWPORTS[viewport]) throw new Error('viewport must be "desktop" or "mobile".')
-    return this.browser.inspect({ url: this.pageUrl(route), viewport: DEFAULT_VIEWPORTS[viewport], selector, waitMs })
+    const normalizedRoute = normalizeRoute(route)
+    return this.browser.inspect({
+      url: this.pageUrl(normalizedRoute), viewport: DEFAULT_VIEWPORTS[viewport], selector, waitMs,
+      auth: await this.previewAuth(normalizedRoute),
+    })
   }
 
   async stop() {
@@ -572,7 +724,7 @@ export function createViewportTools({ tool, z, manager }) {
     ),
     tool(
       'preview_capture',
-      'Capture this lane preview in a fresh isolated browser at exact desktop (1440×900) and mobile (390×844) CSS viewports. Defaults to both and full-page. Captures are inline verification evidence by default. Set card=true only for a user-requested mockup or visual deliverable that should remain editable in the transcript; complete desktop+mobile settled content is then required and the card arrives after the final response. Authenticated app routes require an authenticated visual harness.',
+      'Capture this lane preview in a fresh isolated browser at exact desktop (1440×900) and mobile (390×844) CSS viewports. Defaults to both and full-page. Captures are inline verification evidence by default. Room and protected routes automatically use the bridge account as a read-only authenticated visual harness; external REST writes, presence, and room broadcasts are blocked, apart from non-mutating roster/transcript snapshot requests. Set card=true only for a user-requested mockup or visual deliverable that should remain editable in the transcript; complete desktop+mobile settled content is then required and the card arrives after the final response.',
       {
         path: z.string().max(500).optional().describe('route within the preview, e.g. / or /settings; never a full URL'),
         viewports: z.enum(['both', 'desktop', 'mobile']).optional(),