thinkpool-pair 0.7.206 → 0.7.208

package/README.md

@@ -56,6 +56,25 @@ every byte mirrors to the web. The web's **"+ New terminal"** spawns additional
 **headless** terminals here (same directory, same env), driven entirely from
 the room. One bridge, many terminals.
 
+### Built-in viewport capture
+
+Structured Claude and Codex lanes have bridge-owned visual QA tools, even when
+their own sandbox cannot bind localhost or launch Chrome:
+
+- `preview_start` serves a built directory inside that lane's workspace
+  (`dist` by default; it must contain `index.html`).
+- `preview_capture` returns exact desktop (1440×900) and mobile (390×844)
+  screenshots to the agent and surfaces them in the room.
+- `preview_inspect` returns rendered DOM text, document size, and optional
+  selector geometry at either viewport.
+- `preview_stop` releases the preview port.
+
+The bridge launches the host's Chrome/Chromium lazily. Set `TP_BROWSER_PATH`
+if it is installed somewhere non-standard. Preview files are read-only, roots
+cannot escape the lane workspace (including through symlinks), and page network
+requests are restricted to the preview server's exact loopback origin. The
+tools never execute a caller-supplied command or open an arbitrary URL.
+
 ## Run it in the cloud (remote host / VM / container)
 
 The bridge connects **outbound** to Supabase — no inbound ports, no public IP, no

package/bridge.mjs

@@ -63,6 +63,7 @@ import { normalizePlanOutput, laneModelFor } from './flow-task-graph.mjs'   // F
 import { writeLaneArtifact, digestSlice, appendDigest, resumeLane } from './flow-context-store.mjs'
 import { createFlowWorktree, worktreeSpec } from './flow-worktree.mjs'
 import { startPreview, stopAllPreviews, previews } from './flow-preview.mjs'
+import { ViewportManager, createViewportTools, sharedViewportBrowser } from './viewport.mjs'
 // FL-M9 — per-lane preview servers leak (one per done lane, never stopped until shutdown).
 // Lane previews are keyed `lane:<flowId>:<laneId>`; stop a whole flow's set when it assembles
 // (the assembled preview supersedes them) or when a lane is reverted.
@@ -97,7 +98,7 @@ 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, formatClosableHint } from './cross-terminal.mjs'
+import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, SPAWN, CROSSROOM, formatPairRoster, crossRoomPostDecision, formatRoomNow, formatClosableHint, laneStatusOf } from './cross-terminal.mjs'
 import { armInterruptedResume, sendInterruptedContinue, supersedeInterruptedResume } from './interrupted-resume.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'
@@ -1033,18 +1034,17 @@ const announce = () => {
     // cols/rows: the PTY's one true size — web viewers render this grid and
     // scale it to their own page instead of voting to reflow it.
     terms: [
-      ...[...terms.entries()].map(([id, t]) => ({ id, cmd: t.cmd, alive: true, cols: t.term.cols, rows: t.term.rows, name: termNames[id] || undefined })),
+      ...[...terms.entries()].map(([id, t]) => ({ id, cmd: t.cmd, alive: true, cols: t.term.cols, rows: t.term.rows, name: termNames[id] || undefined, ...laneStatusOf(t) })),
       // Structured sessions advertise kind:'structured' so the web renders the
       // reader (not xterm) and drives them with code-turn / code-perm. `mode` +
       // `name` ride along so a second device shows the live permission mode and
       // the chosen label instead of defaulting to Normal / unnamed. `spawned` (set
       // when an agent Dispatched this lane via spawn_terminal) lets the client keep
       // it OUT of the top tab strip and show it only in the Ensemble menu.
-      // busy: this structured session is mid-turn right now (the SDK's
-      // turnActive). Authoritative — the bridge owns the turn — so the /code
-      // dashboard reads "N agents working" off the roster instead of sniffing
-      // the live code-event stream (which a passive dashboard channel misses).
-      ...[...sessions.entries()].map(([id, s]) => ({ id, cmd: s.cmd, kind: 'structured', runtime: s.runtime || 'claude', alive: true, busy: s.session?.turnActive ?? false, hasTranscript: s.log.length > 0, commands: s.commands, mode: s.mode || undefined, effort: s.effort || undefined, name: termNames[id] || undefined, model: s.model || undefined, ...(s.runtime === 'codex' ? { approvalPolicy: codexConfigForMode(s.mode).approvalPolicy, models: s.models || [] } : {}), ...(s.archiveOldestSeq != null ? { oldestSeq: s.archiveOldestSeq } : {}), ...(s.spawnedBy ? { spawned: true, spawnedBy: s.spawnedBy } : {}), ...(s.flowSessionId ? { flowId: s.flowSessionId, flowRole: s.flowTaskKey ? 'lane' : 'conductor' } : {}),
+      // laneStatusOf: authoritative busy/idle + last-action timestamp/age +
+      // STUCK/BLOCKED alert. The bridge owns the turn and permission state, so
+      // every roster consumer reads one status instead of reconstructing it.
+      ...[...sessions.entries()].map(([id, s]) => ({ id, cmd: s.cmd, kind: 'structured', runtime: s.runtime || 'claude', alive: true, ...laneStatusOf(s), hasTranscript: s.log.length > 0, commands: s.commands, mode: s.mode || undefined, effort: s.effort || undefined, name: termNames[id] || undefined, model: s.model || undefined, ...(s.runtime === 'codex' ? { approvalPolicy: codexConfigForMode(s.mode).approvalPolicy, models: s.models || [] } : {}), ...(s.archiveOldestSeq != null ? { oldestSeq: s.archiveOldestSeq } : {}), ...(s.spawnedBy ? { spawned: true, spawnedBy: s.spawnedBy } : {}), ...(s.flowSessionId ? { flowId: s.flowSessionId, flowRole: s.flowTaskKey ? 'lane' : 'conductor' } : {}),
         // provider: the registered LLM-provider this lane runs on, NAME-ONLY {id,name}
         // (NEVER the key or baseUrl). Additive; older clients ignore it. Omitted for the
         // built-in/default Claude path (no badge). Makes the lane's provider badge +
@@ -1095,6 +1095,7 @@ function raiseCard(entry, req) {
     if (!entry?.pending) return resolve('deny')
     const payload = { term: entry.id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk }
     entry.pending.set(req.id, { resolve, payload })
+    announce()
     bcast('code-perm-req', payload)
     process.stderr.write(`\n  ● incoming cross-room task for ${String(entry.id).slice(0, 8)} — approve in the room.\n`)
   })
@@ -1403,12 +1404,13 @@ function openTerm({ id, cmd, args = [], attached = false, cols, rows }) {
     rows: rows || (attached ? ad.rows : (PIN_ROWS || 32)),
     cwd: process.cwd(), env: { ...process.env, TP_MOCKUP_OUTBOX: mockupOutbox },
   })
-  const entry = { term, cmd, attached, scrollback: '', buf: '', mockupWatcher: watchOutbox(mockupOutbox, () => id) }
+  const entry = { term, cmd, attached, scrollback: '', buf: '', lastActionAt: null, mockupWatcher: watchOutbox(mockupOutbox, () => id) }
   terms.set(id, entry)
   if (attached) attachedId = id
   term.onData(d => {
     if (attached) process.stdout.write(d)
     entry.buf += d
+    entry.lastActionAt = Date.now()
     entry.scrollback = (entry.scrollback + d).slice(-SCROLLBACK_MAX)
   })
   term.onExit(() => {
@@ -1478,6 +1480,8 @@ function pushLog(entry, evt) {
   // A real ts makes ordering wall-clock — immune to eviction AND /clear seq resets.
   // stampEvent is idempotent, so the callers that already stamp are unaffected.
   stampEvent(evt)
+  entry.lastActionAt = evt.ts
+  entry.lastEvent = evt
   // Only TRANSCRIPT events consume a seq (seqable) — replay-chrome kinds the web
   // filters out (system/thinking_tokens/effort) ride the log seq-less so they don't
   // hole the client's applied sequence. See event-id.mjs NO_SEQ_KINDS.
@@ -1747,6 +1751,9 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
   // they land on this session even after other terminals open/close.
   const mockupOutbox = ownerOutbox('sessions', id)
   entry.mockupWatcher = watchOutbox(mockupOutbox, () => id)
+  // Visual QA runs in the bridge process, outside either agent runtime's sandbox.
+  // It remains scoped to this lane's cwd and private mockup outbox.
+  entry.viewport = new ViewportManager({ workspaceRoot: cwd || process.cwd(), ownerId: id, outbox: mockupOutbox })
   if (entry.log.length) process.stderr.write(`\n  ◆ restored ${entry.log.length} prior events (${id.slice(0, 8)})${resume ? ' + resuming live context' : ''}.\n`)
   // Persist the permission mode alongside the transcript so a bridge restart
   // restores the session in the SAME mode (a bypass room stays bypass on resume).
@@ -1776,9 +1783,10 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
     name: 'thinkpool',
     version: '1.0.0',
     tools: [
+      ...createViewportTools({ tool, z, manager: entry.viewport }),
       tool(
         'read_terminal',
-        'Read-only view of ANOTHER terminal in this ThinkPool Code room (a sibling agent or a shell the people are using). Call with no arguments to list the other open terminals; call with `terminal` (a ref, id, or command from that list) to read its recent activity. It never changes another terminal — reading only. Use it when your work depends on what another terminal is doing.',
+        'Read-only view of ANOTHER terminal in this ThinkPool Code room (a sibling agent or a shell the people are using). Call with no arguments to list every open terminal with busy/idle state, last-action age, and any STUCK/BLOCKED flag; call with `terminal` (a ref, id, or command from that list) to read its recent activity. It never changes another terminal — reading only. Use the one-read roster to identify a lane that needs attention before opening its transcript.',
         {
           terminal: z.string().optional().describe('ref, id, or command of the terminal to read; omit to list the open terminals'),
           lines: z.number().int().positive().max(PEEK.maxLines).optional().describe(`how many recent lines to return (default ${PEEK.defaultLines})`),
@@ -2199,6 +2207,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
         process.stderr.write(`\n  ◆ saved session expired — starting fresh (transcript kept).\n`)
         try { entry.session?.end() } catch { /* noop */ }
         try { entry.mockupWatcher?.close() } catch { /* noop */ }
+        try { void entry.viewport?.stop()?.catch(() => {}) } catch { /* noop */ }
         sessions.delete(id)
         openStructured({ id, runtime: entry.runtime, model, log: entry.log, commands: entry.commands, mode: entry.mode })
         return
@@ -2210,6 +2219,10 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
       // id, an event that arrives both live AND in a reconnect replay renders
       // twice (the 2026-06-19 duplicate-message bug). See event-id.mjs.
       stampEvent(evt)
+      const stalledChanged = evt.kind === 'stalled' ? !entry.stalled : !!entry.stalled
+      entry.stalled = evt.kind === 'stalled'
+      entry.lastEvent = evt
+      if (evt.kind !== 'stalled') entry.lastActionAt = evt.ts
       // Re-announce the roster on THIS session's busy EDGE — turn start (turnActive
       // flips true on the turn's first event) and turn end (false on result/error).
       // Edge-triggered: one announce per transition, not per token event. This is what
@@ -2221,7 +2234,9 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
       // bridge sees "this lane just began working". `result`/`error` reads it to decide
       // whether the turn was long enough that nobody was watching (Slice 3).
       { const busyNow = entry.session?.turnActive ?? false
-        if (busyNow !== entry._busyAnn) { if (busyNow) entry._turnStart = Date.now(); entry._busyAnn = busyNow; announce() } }
+        const busyChanged = busyNow !== entry._busyAnn
+        if (busyChanged) { if (busyNow) entry._turnStart = Date.now(); entry._busyAnn = busyNow }
+        if (busyChanged || stalledChanged) announce() }
       // Capture this session's current MODEL (resolved full id, with version — from
       // system/result `model` or usage `ctx.model`) and the SDK's supported-model
       // LIST (from the `models` event) so the announce carries them to EVERY device.
@@ -2410,6 +2425,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
       // (replay-request handler) — pending cards never enter the replayed event log.
       const payload = { term: id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk, plan: req.plan, questions: req.questions }
       entry.pending.set(req.id, { resolve, payload })
+      announce()
       bcast('code-perm-req', payload)
       // Slice 3 — arm the grace timer. Fires a "needs you" push only if the card is
       // STILL unanswered 20s from now (you're not in the room). Every resolve path —
@@ -2544,6 +2560,7 @@ function respawnStructured(id, provider) {
   drainPending(s)
   try { s.session?.end() } catch { /* noop */ }
   try { s.mockupWatcher?.close() } catch { /* noop */ }
+  try { void s.viewport?.stop()?.catch(() => {}) } catch { /* noop */ }
   sessions.delete(id)   // openStructured early-returns if the id is still mapped
   // Re-open under the SAME id with the new provider env. openStructured persists
   // sessionData() (provider included) synchronously on open, so a bridge restart
@@ -2586,6 +2603,7 @@ function endStructured(id) {
     drainPending(s)
     try { s.session?.end() } catch { /* noop */ }
     try { s.mockupWatcher?.close() } catch { /* noop */ }
+    try { void s.viewport?.stop()?.catch(() => {}) } catch { /* noop */ }
     sessions.delete(id)
     bcast('term-exit', { id })
     reapTerminalRow(id)    // bridge-side reap: delete the code_terminals row ourselves — the
@@ -3032,11 +3050,11 @@ channel
     // use run/accept/keep (claude-session interprets). Default deny on missing.
     // Answered from a device → retract the "needs you" banner on every OTHER device
     // (permNotifier.resolve is a no-op unless its grace timer already fired).
-    if (p) { s.pending.delete(payload.id); s.permNotifier?.resolve(payload.id); p.resolve(payload.decision || 'deny') }
+    if (p) { s.pending.delete(payload.id); s.permNotifier?.resolve(payload.id); p.resolve(payload.decision || 'deny'); announce() }
   })
   .on('broadcast', { event: 'code-abort' }, ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)
-    if (s) { drainPending(s); s.session.abort() }   // settle any open permission card so the hook doesn't hang
+    if (s) { drainPending(s); s.session.abort(); announce() }   // settle any open permission card so the hook doesn't hang
   })
   .on('broadcast', { event: 'code-mode' }, ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)
@@ -3059,6 +3077,7 @@ channel
       if (payload.mode === 'bypassPermissions') allowPending(s)
       // Flipping to acceptEdits = "auto-approve writes" — clear the write cards already raised.
       else if (payload.mode === 'acceptEdits') acceptEditsPending(s)
+      announce()
     }
   })
   .on('broadcast', { event: 'code-effort' }, ({ payload }) => {
@@ -3709,6 +3728,7 @@ async function shutdown(code = 0, farewell = true) {
   setTimeout(() => process.exit(code), 1500)
   clearInterval(flushTimer)
   try { stopAllPreviews() } catch { /* Flow preview servers — best-effort close */ }
+  try { void sharedViewportBrowser.close().catch(() => {}) } catch { /* bridge-owned Chrome — best-effort close */ }
   if (farewell) {
     try {
       const bye = Buffer.from('\r\n[ shared session ended ]\r\n', 'utf8').toString('base64')

package/claude-session.mjs

@@ -486,6 +486,11 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
     if (toolName === 'mcp__thinkpool__read_terminal') {
       return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: 'Auto-approved (read-only ThinkPool cross-terminal read).' } }
     }
+    // Bridge-owned visual QA is constrained to the lane cwd + a loopback URL
+    // created by the bridge itself, so it does not need a room permission card.
+    if (/^mcp__thinkpool__preview_(start|capture|inspect|stop)$/.test(toolName)) {
+      return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: 'Auto-approved (contained bridge-owned viewport preview).' } }
+    }
     // FL-B1 — the Flow conductor submits its task-graph through this tool (replaces the
     // deferred/hanging ExitPlanMode). It only broadcasts a plan for HUMAN approval — no FS or
     // system effect — so auto-allow it (the conductor runs in plan mode, which would otherwise
@@ -699,6 +704,7 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
       'Whenever you produce an HTML artifact (a demo, mockup, preview, report, or page) or surface ANY link meant to be opened or shared, NEVER hand the room a local path, a file:// URL, or a localhost/127.0.0.1 address. Publish it to a GitHub-shareable URL that renders in a browser — push the HTML to a GitHub repo and give its GitHub Pages URL (or an equivalent raw-HTML URL that actually renders, not raw.githubusercontent.com which serves HTML as plain text) — so anyone in the room can open it. The same applies to any other link you surface: it must be one the room can reach, not a host-only path.',
       'If you cannot publish a shareable link, say so and ask how to proceed — do not fall back to handing over a local path.',
       'SHOW YOUR WORK, do not just describe it: the room is watched live from a phone, where a wall of text is painful to read. Whenever you build, change, or fix anything visual — a UI, a page, an HTML artifact, a chart, a diagram, a rendered result — capture a screenshot and surface the PNG (for example, read the image file into your turn) so it appears inline in the room. The room auto-uploads any image you surface. Default to showing a picture of the result over narrating it; err toward more screenshots, not fewer.',
+      'BRIDGE VIEWPORTS: for a built web UI, use preview_start (default root: dist), then preview_capture for exact desktop 1440×900 + mobile 390×844 screenshots, and preview_inspect when DOM text or selector geometry helps. These tools run in the bridge, so they work even when your lane sandbox cannot bind localhost or launch Chrome. They only serve built files inside your own lane workspace; run the project build first. Stop the server with preview_stop when you are done.',
       'HTML PREVIEWS: for any HTML you produce, give the room something it can actually open, by whichever path is available. (a) IN-ROOM PREVIEW: if a mockup render helper is present — one that writes a manifest into the directory named by $TP_MOCKUP_OUTBOX, such as the mockup-iterate render.sh script when the bridge was launched from the thinkpool repo — use it; it surfaces an inline card with desktop and mobile views that the room can expand. (b) SHAREABLE LINK: additionally or otherwise, publish the HTML to a GitHub Pages URL per the LINKS & ARTIFACTS rule above and post the link. Never leave an HTML artifact viewable only as a local path.',
       '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.',

package/cross-terminal.mjs

@@ -18,6 +18,76 @@ export const PEEK = {
   rosterPreview: 100, // last-line preview length in the roster listing
 }
 
+// One shared lane-status classifier for every roster consumer: the bridge wire,
+// read_terminal, and ROOM NOW. Timestamps stay absolute on the wire so clients can
+// keep the displayed age current without a broadcast every second.
+export const LANE_STATUS = {
+  stuckAfterMs: 90_000,       // matches the structured-turn stall watchdog
+  repeatedFailureCount: 2,
+  failureWindow: 12,
+}
+
+const failureEvent = (e) => !!e && (
+  e.kind === 'error'
+  || (e.kind === 'tool_result' && e.isError)
+  || (e.kind === 'result' && e.subtype && e.subtype !== 'success')
+)
+
+const recentFailureCount = (log, limits = LANE_STATUS) => {
+  let failures = 0, seen = 0
+  for (let i = (Array.isArray(log) ? log.length : 0) - 1; i >= 0 && seen < limits.failureWindow; i--) {
+    const e = log[i]
+    if (!e || typeof e !== 'object') continue
+    seen++
+    // A clean completion or a fresh human task closes the prior failure streak.
+    if ((e.kind === 'result' && (!e.subtype || e.subtype === 'success')) || e.kind === 'you') break
+    if (failureEvent(e)) failures++
+  }
+  return failures
+}
+
+export const laneStatusOf = (entry = {}, now = Date.now(), limits = LANE_STATUS) => {
+  const baseLog = Array.isArray(entry?.log) ? entry.log : []
+  const log = baseLog.slice(-limits.failureWindow)
+  if (entry?.lastEvent && entry.lastEvent !== baseLog[baseLog.length - 1]
+    && (!entry.lastEvent.cid || entry.lastEvent.cid !== baseLog[baseLog.length - 1]?.cid)) log.push(entry.lastEvent)
+  let lastLogAt = null
+  for (let i = log.length - 1; i >= 0; i--) {
+    if (Number.isFinite(log[i]?.ts)) { lastLogAt = log[i].ts; break }
+  }
+  const lastActionAt = Number.isFinite(entry?.lastActionAt) ? entry.lastActionAt : (lastLogAt ?? null)
+  const lastActionAgeMs = lastActionAt == null ? null : Math.max(0, now - lastActionAt)
+  const busy = typeof entry?.busy === 'boolean' ? entry.busy : (entry?.session?.turnActive ?? false)
+  const pendingCount = entry?.pending instanceof Map
+    ? entry.pending.size
+    : Math.max(0, Number(entry?.pendingCount) || 0)
+  const failures = recentFailureCount(log, limits)
+
+  let statusFlag = null, statusReason = null
+  if (pendingCount > 0) {
+    statusFlag = 'BLOCKED'; statusReason = 'waiting for input'
+  } else if (entry?.stalled || (busy && !entry?.compacting && lastActionAgeMs != null && lastActionAgeMs >= limits.stuckAfterMs)) {
+    statusFlag = 'STUCK'; statusReason = 'no events while busy'
+  } else if (failures >= limits.repeatedFailureCount) {
+    statusFlag = 'BLOCKED'; statusReason = 'repeated errors'
+  }
+
+  return { busy: !!busy, lastActionAt, lastActionAgeMs, statusFlag, statusReason }
+}
+
+export const formatLaneAge = (ageMs) => {
+  if (!Number.isFinite(ageMs)) return 'no activity'
+  const s = Math.max(0, Math.floor(ageMs / 1000))
+  if (s < 60) return `${s}s ago`
+  const m = Math.floor(s / 60)
+  if (m < 60) return `${m}m ago`
+  const h = Math.floor(m / 60)
+  if (h < 24) return `${h}h ago`
+  return `${Math.floor(h / 24)}d ago`
+}
+
+const laneStatusText = (x) => `${x.busy ? 'busy' : 'idle'} · ${formatLaneAge(x.lastActionAgeMs)}${x.statusFlag ? ` · ${x.statusFlag}` : ''}`
+
 const clip = (s, cap) => {
   const t = String(s == null ? '' : s).replace(/\s+/g, ' ').trim()
   return t.length > cap ? t.slice(0, cap - 1) + '…' : t
@@ -67,16 +137,16 @@ export const siblingRef = (id) => String(id).slice(0, 8)
 // is the bridge's id→label map (termNames) — the HUMAN names people actually use
 // ("Pivot", "Grug"); without it the roster is just hashes and an agent can't map
 // "what is Pivot doing" to a lane.
-export const siblingsOf = ({ selfId, sessions, terms, names = {} } = {}) => {
+export const siblingsOf = ({ selfId, sessions, terms, names = {}, now = Date.now() } = {}) => {
   const nm = (id) => (names && names[id]) || ''
   const sib = []
   for (const [id, s] of (sessions || new Map())) {
     if (id === selfId) continue
-    sib.push({ id, ref: siblingRef(id), name: nm(id), kind: 'agent', cmd: s?.cmd || 'claude', log: Array.isArray(s?.log) ? s.log : [] })
+    sib.push({ id, ref: siblingRef(id), name: nm(id), kind: 'agent', cmd: s?.cmd || 'claude', log: Array.isArray(s?.log) ? s.log : [], ...laneStatusOf(s, now) })
   }
   for (const [id, t] of (terms || new Map())) {
     if (id === selfId) continue
-    sib.push({ id, ref: siblingRef(id), name: nm(id), kind: 'shell', cmd: t?.cmd || 'shell', buf: t?.buf || '' })
+    sib.push({ id, ref: siblingRef(id), name: nm(id), kind: 'shell', cmd: t?.cmd || 'shell', buf: t?.buf || '', ...laneStatusOf(t, now) })
   }
   return sib
 }
@@ -121,9 +191,9 @@ export const resolveSibling = (siblings, terminal) => {
 
 const label = (x) => `${x.ref}${x.name ? ` · "${x.name}"` : ''}`
 
-export const formatPeek = ({ selfId, sessions, terms, names = {}, terminal, lines } = {}) => {
+export const formatPeek = ({ selfId, sessions, terms, names = {}, terminal, lines, now = Date.now() } = {}) => {
   const n = Math.min(PEEK.maxLines, Math.max(1, Number(lines) || PEEK.defaultLines))
-  const sib = siblingsOf({ selfId, sessions, terms, names })
+  const sib = siblingsOf({ selfId, sessions, terms, names, now })
   if (!sib.length) return 'No other terminals are open in this room right now.'
 
   if (!terminal) {
@@ -131,7 +201,7 @@ export const formatPeek = ({ selfId, sessions, terms, names = {}, terminal, line
       let preview
       if (x.kind === 'agent') { const ls = x.log.map(e => digestLogEvent(e, PEEK.rosterPreview)).filter(Boolean); preview = ls[ls.length - 1] || '(no activity yet)' }
       else { preview = cleanPtyTail(x.buf, 1)[0] || '(no output yet)' }
-      return `- ${label(x)} · ${x.kind} · ${x.cmd} — ${clip(preview, PEEK.rosterPreview)}`
+      return `- ${label(x)} · ${x.kind} · ${x.cmd} · ${laneStatusText(x)} — ${clip(preview, PEEK.rosterPreview)}`
     })
     return `Other terminals in this room (call read_terminal with a ref or name to read one):\n${rows.join('\n')}`
   }
@@ -162,8 +232,8 @@ export const formatPeek = ({ selfId, sessions, terms, names = {}, terminal, line
 // when there is nothing to show (the reminder then carries no tail at all).
 // Spec ask (2026-07-02): "terminals need to be completely aware of the session."
 export const ROOMNOW = { laneCap: 8, previewLen: 70, wtCap: 10 }
-export const formatRoomNow = ({ selfId, sessions, terms, names = {}, worktrees = [] } = {}, limits = ROOMNOW) => {
-  const sib = siblingsOf({ selfId, sessions, terms, names })
+export const formatRoomNow = ({ selfId, sessions, terms, names = {}, worktrees = [], now = Date.now() } = {}, limits = ROOMNOW) => {
+  const sib = siblingsOf({ selfId, sessions, terms, names, now })
   const out = []
   if (sib.length) {
     const shown = sib.slice(0, limits.laneCap)
@@ -171,7 +241,7 @@ export const formatRoomNow = ({ selfId, sessions, terms, names = {}, worktrees =
       let preview
       if (x.kind === 'agent') { const ls = x.log.map(e => digestLogEvent(e, limits.previewLen)).filter(Boolean); preview = ls[ls.length - 1] || '(no activity yet)' }
       else preview = cleanPtyTail(x.buf, 1)[0] || '(no output yet)'
-      return `- ${label(x)} · ${x.kind} — ${clip(preview, limits.previewLen)}`
+      return `- ${label(x)} · ${x.kind} · ${laneStatusText(x)} — ${clip(preview, limits.previewLen)}`
     })
     if (sib.length > shown.length) rows.push(`- … +${sib.length - shown.length} more (read_terminal lists all)`)
     out.push(`Other lanes in this room right now (read_terminal for detail):\n${rows.join('\n')}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.206",
+  "version": "0.7.208",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -33,6 +33,7 @@
     "flow-worktree.mjs",
     "flow-task-graph.mjs",
     "flow-preview.mjs",
+    "viewport.mjs",
     "flow-review.mjs",
     "flow-review-gate.mjs",
     "flow-review-reflect.mjs",

package/viewport.mjs

@@ -0,0 +1,445 @@
+// Bridge-owned visual QA for ThinkPool Code lanes.
+//
+// Agent sandboxes should not need permission to bind localhost or launch a GUI
+// process. The bridge already owns a contained static preview server
+// (flow-preview.mjs), so this module adds the missing half: an exact-viewport,
+// dependency-free Chrome DevTools Protocol capture worker plus per-lane tools.
+//
+// Security boundary:
+//   - preview roots must resolve inside the lane's own cwd (symlinks included)
+//   - the browser only opens the loopback URL created by startPreview()
+//   - no caller-supplied commands, executables, ports, hosts, or arbitrary URLs
+
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { previews, startPreview } from './flow-preview.mjs'
+
+export const DEFAULT_VIEWPORTS = Object.freeze({
+  desktop: Object.freeze({ width: 1440, height: 900 }),
+  mobile: Object.freeze({ width: 390, height: 844 }),
+})
+
+const MAX_CAPTURE_HEIGHT = 20000
+const MAX_SETTLE_MS = 5000
+const CDP_TIMEOUT_MS = 12000
+
+const isInside = (parent, child) => {
+  const rel = path.relative(parent, child)
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
+}
+
+export async function resolveContainedRoot(workspaceRoot, requested = 'dist') {
+  if (!workspaceRoot) throw new Error('A lane workspace is required.')
+  if (path.isAbsolute(requested)) throw new Error('Preview root must be relative to the lane workspace.')
+  const workspace = await fsp.realpath(path.resolve(workspaceRoot))
+  const candidate = path.resolve(workspace, requested || 'dist')
+  let resolved
+  try { resolved = await fsp.realpath(candidate) }
+  catch { throw new Error(`Preview root does not exist: ${requested || 'dist'}. Build the app first, or choose a directory containing index.html.`) }
+  if (!isInside(workspace, resolved)) throw new Error('Preview root escapes the lane workspace.')
+  const stat = await fsp.stat(resolved)
+  if (!stat.isDirectory()) throw new Error('Preview root must be a directory.')
+  if (!fs.existsSync(path.join(resolved, 'index.html'))) throw new Error(`No index.html found in preview root: ${requested || 'dist'}.`)
+  return resolved
+}
+
+export function normalizeRoute(value = '/') {
+  const route = String(value || '/').trim()
+  if (!route.startsWith('/') || route.startsWith('//')) throw new Error('Preview path must start with one "/" and cannot be a URL.')
+  const parsed = new URL(route, 'http://127.0.0.1')
+  if (parsed.origin !== 'http://127.0.0.1') throw new Error('Preview path cannot change the preview origin.')
+  return `${parsed.pathname}${parsed.search}${parsed.hash}`
+}
+
+export function safeSlug(value = 'viewport') {
+  return String(value || 'viewport')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 56) || 'viewport'
+}
+
+export function findBrowserExecutable({ env = process.env, platform = process.platform, exists = fs.existsSync } = {}) {
+  const candidates = [
+    env.TP_BROWSER_PATH,
+    platform === 'darwin' && '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    platform === 'darwin' && '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    platform === 'win32' && env.PROGRAMFILES && path.join(env.PROGRAMFILES, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+    platform === 'win32' && env['PROGRAMFILES(X86)'] && path.join(env['PROGRAMFILES(X86)'], 'Google', 'Chrome', 'Application', 'chrome.exe'),
+    platform === 'linux' && '/usr/bin/google-chrome',
+    platform === 'linux' && '/usr/bin/google-chrome-stable',
+    platform === 'linux' && '/usr/bin/chromium',
+    platform === 'linux' && '/usr/bin/chromium-browser',
+  ].filter(Boolean)
+  return candidates.find((candidate) => {
+    try { return exists(candidate) } catch { return false }
+  }) || null
+}
+
+class CdpPipe {
+  constructor(child, timeoutMs = CDP_TIMEOUT_MS) {
+    this.child = child
+    this.timeoutMs = timeoutMs
+    this.nextId = 1
+    this.buffer = Buffer.alloc(0)
+    this.pending = new Map()
+    this.waiters = new Set()
+    this.subscribers = new Set()
+    child.stdio[4].on('data', (chunk) => this.onData(chunk))
+    child.once('exit', (code, signal) => this.failAll(new Error(`Chrome exited (${signal || code || 'unknown'}).`)))
+    child.once('error', (error) => this.failAll(error))
+  }
+
+  onData(chunk) {
+    this.buffer = Buffer.concat([this.buffer, chunk])
+    for (;;) {
+      const end = this.buffer.indexOf(0)
+      if (end < 0) break
+      const raw = this.buffer.subarray(0, end).toString('utf8')
+      this.buffer = this.buffer.subarray(end + 1)
+      if (!raw) continue
+      let message
+      try { message = JSON.parse(raw) } catch { continue }
+      if (message.id) {
+        const pending = this.pending.get(message.id)
+        if (!pending) continue
+        clearTimeout(pending.timer)
+        this.pending.delete(message.id)
+        if (message.error) pending.reject(new Error(message.error.message || 'Chrome DevTools error'))
+        else pending.resolve(message.result || {})
+        continue
+      }
+      for (const waiter of [...this.waiters]) {
+        if (waiter.method !== message.method) continue
+        if (waiter.sessionId && waiter.sessionId !== message.sessionId) continue
+        if (waiter.predicate && !waiter.predicate(message.params || {})) continue
+        clearTimeout(waiter.timer)
+        this.waiters.delete(waiter)
+        waiter.resolve(message.params || {})
+      }
+      for (const subscriber of [...this.subscribers]) {
+        if (subscriber.method !== message.method) continue
+        if (subscriber.sessionId && subscriber.sessionId !== message.sessionId) continue
+        try { subscriber.handler(message.params || {}) } catch { /* subscriber owns recovery */ }
+      }
+    }
+  }
+
+  failAll(error) {
+    for (const pending of this.pending.values()) { clearTimeout(pending.timer); pending.reject(error) }
+    this.pending.clear()
+    for (const waiter of this.waiters) { clearTimeout(waiter.timer); waiter.reject(error) }
+    this.waiters.clear()
+    this.subscribers.clear()
+  }
+
+  send(method, params = {}, sessionId) {
+    const id = this.nextId++
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error(`Chrome timed out running ${method}.`))
+      }, this.timeoutMs)
+      this.pending.set(id, { resolve, reject, timer })
+      const message = { id, method, params, ...(sessionId ? { sessionId } : {}) }
+      this.child.stdio[3].write(`${JSON.stringify(message)}\0`)
+    })
+  }
+
+  waitFor(method, sessionId, predicate) {
+    return new Promise((resolve, reject) => {
+      const waiter = { method, sessionId, predicate, resolve, reject, timer: null }
+      waiter.timer = setTimeout(() => {
+        this.waiters.delete(waiter)
+        reject(new Error(`Chrome timed out waiting for ${method}.`))
+      }, this.timeoutMs)
+      this.waiters.add(waiter)
+    })
+  }
+
+  subscribe(method, sessionId, handler) {
+    const subscriber = { method, sessionId, handler }
+    this.subscribers.add(subscriber)
+    return () => this.subscribers.delete(subscriber)
+  }
+}
+
+export class CdpBrowser {
+  constructor({ executable, spawnImpl = spawn, timeoutMs = CDP_TIMEOUT_MS } = {}) {
+    this.executable = executable || null
+    this.spawnImpl = spawnImpl
+    this.timeoutMs = timeoutMs
+    this.child = null
+    this.pipe = null
+    this.profileDir = null
+    this.starting = null
+    this.stderr = ''
+  }
+
+  async ensureStarted() {
+    if (this.child && this.pipe) return
+    if (this.starting) return this.starting
+    this.starting = this.start().finally(() => { this.starting = null })
+    return this.starting
+  }
+
+  async start() {
+    const executable = this.executable || findBrowserExecutable()
+    if (!executable) throw new Error('No supported Chrome/Chromium executable found. Install Google Chrome or set TP_BROWSER_PATH on the bridge host.')
+    this.profileDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'thinkpool-viewport-'))
+    const args = [
+      '--headless=new', '--remote-debugging-pipe', '--no-first-run', '--no-default-browser-check',
+      '--disable-background-networking', '--disable-component-update', '--disable-sync',
+      '--disable-extensions', '--disable-default-apps',
+      '--metrics-recording-only', '--mute-audio', '--hide-scrollbars',
+      `--user-data-dir=${this.profileDir}`, 'about:blank',
+    ]
+    const child = this.spawnImpl(executable, args, { stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'] })
+    this.child = child
+    child.stderr?.on('data', (chunk) => { this.stderr = (this.stderr + chunk.toString('utf8')).slice(-4000) })
+    this.pipe = new CdpPipe(child, this.timeoutMs)
+    try { await this.pipe.send('Browser.getVersion') }
+    catch (error) {
+      await this.close()
+      const detail = this.stderr.trim().split('\n').slice(-2).join(' ')
+      throw new Error(`Could not start Chrome for viewport capture: ${detail || error.message}`)
+    }
+  }
+
+  async withPage({ url, viewport, waitMs = 300 }, 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
+    try {
+      await this.pipe.send('Page.enable', {}, sessionId)
+      await this.pipe.send('Runtime.enable', {}, 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.
+      const allowedOrigin = new URL(url).origin
+      unsubscribeRequests = this.pipe.subscribe('Fetch.requestPaused', sessionId, (params) => {
+        let allowed = false
+        try { allowed = new URL(params.request?.url || '').origin === allowedOrigin } catch { allowed = false }
+        const method = allowed ? 'Fetch.continueRequest' : 'Fetch.failRequest'
+        const request = allowed
+          ? { requestId: params.requestId }
+          : { requestId: params.requestId, errorReason: 'BlockedByClient' }
+        void this.pipe.send(method, request, sessionId).catch(() => {})
+      })
+      await this.pipe.send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] }, sessionId)
+      await this.pipe.send('Network.setBypassServiceWorker', { bypass: true }, sessionId).catch(() => {})
+      await this.pipe.send('Emulation.setDeviceMetricsOverride', {
+        width: viewport.width, height: viewport.height, deviceScaleFactor: 1, mobile: false,
+        screenWidth: viewport.width, screenHeight: viewport.height,
+      }, sessionId)
+      const loaded = this.pipe.waitFor('Page.loadEventFired', sessionId)
+      const nav = await this.pipe.send('Page.navigate', { url }, sessionId)
+      if (nav.errorText) throw new Error(`Preview navigation failed: ${nav.errorText}`)
+      await loaded
+      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 (settle) await new Promise((resolve) => setTimeout(resolve, settle))
+      return await fn({ pipe: this.pipe, sessionId })
+    } finally {
+      unsubscribeRequests?.()
+      await this.pipe.send('Target.closeTarget', { targetId }).catch(() => {})
+    }
+  }
+
+  async capture({ url, viewport, fullPage = true, waitMs = 300 }) {
+    return this.withPage({ url, viewport, waitMs }, async ({ pipe, sessionId }) => {
+      const metrics = await pipe.send('Page.getLayoutMetrics', {}, sessionId)
+      const contentHeight = Math.ceil(metrics.cssContentSize?.height || viewport.height)
+      const height = fullPage ? Math.min(MAX_CAPTURE_HEIGHT, Math.max(viewport.height, contentHeight)) : viewport.height
+      const result = await pipe.send('Page.captureScreenshot', {
+        format: 'png', fromSurface: true, captureBeyondViewport: true,
+        clip: { x: 0, y: 0, width: viewport.width, height, scale: 1 },
+      }, sessionId)
+      return { png: Buffer.from(result.data, 'base64'), width: viewport.width, height, contentHeight, capped: contentHeight > MAX_CAPTURE_HEIGHT }
+    })
+  }
+
+  async inspect({ url, viewport = DEFAULT_VIEWPORTS.mobile, selector, waitMs = 300 }) {
+    return this.withPage({ url, viewport, waitMs }, async ({ pipe, sessionId }) => {
+      const expression = `(() => {
+        const selector = ${JSON.stringify(selector || null)};
+        const el = selector ? document.querySelector(selector) : null;
+        const r = el && el.getBoundingClientRect();
+        return {
+          title: document.title, url: location.href,
+          viewport: { width: innerWidth, height: innerHeight, dpr: devicePixelRatio },
+          document: { width: Math.max(document.documentElement.scrollWidth, document.body?.scrollWidth || 0), height: Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight || 0) },
+          selector: selector ? { query: selector, found: !!el, tag: el?.tagName || null, text: el?.innerText?.slice(0, 2000) || '', rect: r ? { x:r.x, y:r.y, width:r.width, height:r.height } : null } : null,
+          text: document.body?.innerText?.slice(0, 12000) || ''
+        };
+      })()`
+      const result = await pipe.send('Runtime.evaluate', { expression, returnByValue: true }, sessionId)
+      if (result.exceptionDetails) throw new Error('DOM inspection failed in the preview page.')
+      return result.result?.value || {}
+    })
+  }
+
+  async close() {
+    const child = this.child
+    const pipe = this.pipe
+    this.child = null
+    this.pipe = null
+    if (pipe) await pipe.send('Browser.close').catch(() => {})
+    if (child && child.exitCode == null) { try { child.kill('SIGTERM') } catch { /* already gone */ } }
+    if (this.profileDir) await fsp.rm(this.profileDir, { recursive: true, force: true }).catch(() => {})
+    this.profileDir = null
+  }
+}
+
+export const sharedViewportBrowser = new CdpBrowser()
+
+export class ViewportManager {
+  constructor({ workspaceRoot, ownerId, outbox, browser = sharedViewportBrowser, startPreviewImpl = startPreview } = {}) {
+    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.previewId = `viewport:${this.ownerId}`
+    this.preview = null
+    this.root = null
+  }
+
+  async start({ root = 'dist' } = {}) {
+    const resolved = await resolveContainedRoot(this.workspaceRoot, root)
+    await this.stop()
+    const preview = await this.startPreviewImpl({ dir: resolved, host: '127.0.0.1', port: 0, id: this.previewId })
+    const parsed = new URL(preview.url)
+    if (parsed.hostname !== '127.0.0.1' && parsed.hostname !== 'localhost') {
+      await preview.stop?.()
+      throw new Error('Preview server did not bind to loopback.')
+    }
+    this.preview = preview
+    this.root = resolved
+    return { url: preview.url, root: resolved }
+  }
+
+  requirePreview() {
+    if (!this.preview?.url) throw new Error('No preview is running. Call preview_start after building the app.')
+    return this.preview
+  }
+
+  pageUrl(route) {
+    const preview = this.requirePreview()
+    return new URL(normalizeRoute(route), preview.url).href
+  }
+
+  async capture({ route = '/', viewports = 'both', title = 'Viewport capture', fullPage = true, waitMs = 300 } = {}) {
+    const url = this.pageUrl(route)
+    const names = viewports === 'both' ? ['desktop', 'mobile'] : [viewports]
+    if (names.some((name) => !DEFAULT_VIEWPORTS[name])) throw new Error('viewports must be "both", "desktop", or "mobile".')
+    await fsp.mkdir(this.outbox, { recursive: true })
+    const slug = `${safeSlug(title)}-${Date.now().toString(36)}`
+    const captures = {}
+    for (const name of names) {
+      const result = await this.browser.capture({ url, viewport: DEFAULT_VIEWPORTS[name], fullPage, waitMs })
+      const file = path.join(this.outbox, `${slug}--${name}.png`)
+      await fsp.writeFile(file, result.png)
+      captures[name] = { ...result, file }
+    }
+    const html = this.root && fs.existsSync(path.join(this.root, 'index.html')) ? path.join(this.root, 'index.html') : null
+    const manifest = {
+      slug, title: String(title || 'Viewport capture').slice(0, 120), html,
+      desktop: captures.desktop?.file || '', mobile: captures.mobile?.file || '', ts: Date.now(),
+    }
+    const manifestPath = path.join(this.outbox, `${slug}.json`)
+    const tmp = `${manifestPath}.tmp`
+    await fsp.writeFile(tmp, JSON.stringify(manifest))
+    await fsp.rename(tmp, manifestPath)
+    return { url, slug, manifestPath, captures }
+  }
+
+  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 })
+  }
+
+  async stop() {
+    const preview = this.preview || previews.get(this.previewId)
+    this.preview = null
+    this.root = null
+    if (preview?.stop) await preview.stop()
+  }
+}
+
+const textResult = (text) => ({ content: [{ type: 'text', text }] })
+const errorResult = (error) => textResult(`Viewport error: ${error?.message || error}`)
+
+export function createViewportTools({ tool, z, manager }) {
+  return [
+    tool(
+      'preview_start',
+      'Start a bridge-owned, read-only localhost preview for built files inside this lane workspace. Run the project build first. The default root is dist; pass another relative directory only when its index.html is the intended preview.',
+      { root: z.string().max(240).optional().describe('relative directory inside this lane workspace; default: dist') },
+      async (args) => {
+        try {
+          const started = await manager.start({ root: args?.root || 'dist' })
+          return textResult(`Preview ready from ${path.relative(manager.workspaceRoot, started.root) || '.'}. Use preview_capture to see desktop/mobile, or preview_inspect for DOM text and geometry.`)
+        } catch (error) { return errorResult(error) }
+      },
+    ),
+    tool(
+      'preview_capture',
+      'Capture this lane preview at exact desktop (1440×900) and mobile (390×844) CSS viewports. Defaults to both and full-page. Returns the PNGs to your vision context and also surfaces a mockup card in the ThinkPool room.',
+      {
+        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(),
+        title: z.string().max(120).optional(),
+        fullPage: z.boolean().optional(),
+        waitMs: z.number().int().min(0).max(MAX_SETTLE_MS).optional().describe('settle time after load, max 5000ms'),
+      },
+      async (args) => {
+        try {
+          const result = await manager.capture({
+            route: args?.path || '/', viewports: args?.viewports || 'both', title: args?.title || 'Viewport capture',
+            fullPage: args?.fullPage !== false, waitMs: args?.waitMs ?? 300,
+          })
+          const content = [{ type: 'text', text: `Captured ${Object.keys(result.captures).join(' + ')} for ${args?.path || '/'}. A room preview card is being delivered.` }]
+          for (const [name, capture] of Object.entries(result.captures)) {
+            content.push({ type: 'text', text: `${name}: ${capture.width}×${capture.height}${capture.capped ? ' (height capped)' : ''}` })
+            content.push({ type: 'image', data: capture.png.toString('base64'), mimeType: 'image/png' })
+          }
+          return { content }
+        } catch (error) { return errorResult(error) }
+      },
+    ),
+    tool(
+      'preview_inspect',
+      'Inspect rendered DOM state in this lane preview at an exact desktop or mobile viewport. Returns page text, document dimensions, and optional selector text/geometry without changing the page.',
+      {
+        path: z.string().max(500).optional().describe('route within the preview; never a full URL'),
+        viewport: z.enum(['desktop', 'mobile']).optional(),
+        selector: z.string().max(500).optional(),
+        waitMs: z.number().int().min(0).max(MAX_SETTLE_MS).optional(),
+      },
+      async (args) => {
+        try {
+          const result = await manager.inspect({ route: args?.path || '/', viewport: args?.viewport || 'mobile', selector: args?.selector, waitMs: args?.waitMs ?? 300 })
+          return textResult(JSON.stringify(result, null, 2))
+        } catch (error) { return errorResult(error) }
+      },
+    ),
+    tool(
+      'preview_stop',
+      'Stop this lane\'s bridge-owned preview server and release its port.',
+      {},
+      async () => {
+        try { await manager.stop(); return textResult('Preview stopped.') }
+        catch (error) { return errorResult(error) }
+      },
+    ),
+  ]
+}