thinkpool-pair 0.7.205 → 0.7.207

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.
@@ -101,7 +102,7 @@ import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSP
 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'
-import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks, usageReportLine, buildRecapFromLog, RECAP_CAP, trimmedBeforeSeq, firstSeq } from './event-id.mjs'
+import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks, usageReportLine, codexUsageReportLine, 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'
@@ -1747,6 +1748,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,6 +1780,7 @@ 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.',
@@ -2199,6 +2204,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
@@ -2425,6 +2431,20 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
           : `\n  ${A.yel}● permission: ${req.toolName}${argStr(req.input)} — approve in the room.${A.rst}\n`)
     }),
   })
+  // A restored Codex lane may have a stale pre-0.7.206 meter persisted from the
+  // cumulative `turn.completed` bug. Replace it synchronously from the native
+  // rollout before announce/replay, so a reload is truthful even before the next
+  // human turn completes.
+  if (runtime === 'codex' && entry.session?.usageSnapshot?.context) {
+    const { used, max } = entry.session.usageSnapshot.context
+    entry.lastUsage = { kind: 'usage', ctx: {
+      used,
+      max,
+      pct: Math.min(100, Math.max(0, Math.round((used / max) * 100))),
+      over: used > max,
+      model: entry.model,
+    } }
+  }
   // Brand-new session (no restored log): write its record now so a restart that lands
   // before the first debounced save still restores this id instead of dropping it (the
   // room would otherwise show a fresh empty terminal + strand the transcript).
@@ -2530,6 +2550,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
@@ -2572,6 +2593,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
@@ -2973,17 +2995,19 @@ channel
       s.session.sendTurn(text)
       return
     }
-    // /usage → report this session's token + cost totals WITHOUT burning an agent turn.
-    // Computed by REPLAYING the session's own retained result events (each completed turn
-    // persists kind:'result' with usage + costUsd + model — see onEvent). No new accumulator
-    // state: the log is durable, so this survives a bridge restart for free. Reported as ◆
+    // /usage → report token totals WITHOUT burning an agent turn. Claude folds
+    // retained per-turn result events; Codex reads its native rollout snapshot
+    // because the CLI's public completion counters are lifetime thread totals.
+    // Reported as ◆
     // control lines (like /model) so both members AND late-joiners see it. Two lines: the
     // token/cost report (instant, from the retained log), then the plan meters (5h + weekly
     // utilization + server-authoritative resets) once the OAuth usage endpoint answers. The
     // meter line is fired-and-forgotten so a slow/unreachable endpoint never stalls /usage;
     // it degrades to "plan meters unavailable" rather than printing an inferred reset.
     if (/^\/usage\s*$/.test(text)) {
-      ctlLine(usageReportLine(s.model, s.log))
+      ctlLine(s.runtime === 'codex'
+        ? codexUsageReportLine(s.model, s.session?.usageSnapshot)
+        : usageReportLine(s.model, s.log))
       if (s.runtime !== 'codex') planMeterLine().then((l) => { if (l) ctlLine(l) }).catch(() => { /* meters are never load-bearing */ })
       return
     }
@@ -3693,6 +3717,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/codex-event-mapper.mjs

@@ -42,7 +42,7 @@ export class CodexEventMapper {
   /**
    * @param {{onEvent:(evt)=>void, model?:string|null, sessionId?:string|null}} opts
    */
-  constructor({ onEvent, model = null, sessionId = null, fsImpl = fs, contextWindowForModel = () => null }) {
+  constructor({ onEvent, model = null, sessionId = null, fsImpl = fs, usageSnapshotForSession = () => null }) {
     this._onEvent = onEvent
     this._model = model || null
     this._sessionId = sessionId || null
@@ -50,7 +50,8 @@ export class CodexEventMapper {
     this._fileBefore = new Map() // item.id → [{ path, kind, content }]
     this._fs = fsImpl
     this._systemSent = false
-    this._contextWindowForModel = contextWindowForModel
+    this._usageSnapshotForSession = usageSnapshotForSession
+    this._usageBaseline = null
   }
 
   /** Emit a room-event; never let a consumer throw into the stream. */
@@ -58,6 +59,8 @@ export class CodexEventMapper {
 
   setModel(model) { this._model = model || null }
 
+  setUsageBaseline(snapshot) { this._usageBaseline = snapshot || null }
+
   /** Process one parsed Codex JSONL event. */
   push(ev) {
     if (!ev || typeof ev !== 'object') return
@@ -142,17 +145,22 @@ export class CodexEventMapper {
 
       case 'turn.completed': {
         const u = ev.usage || {}
-        // Map Codex usage → Claude-shape usage (what event-id.mjs folds into cost).
-        // reasoning_output_tokens are billed as output → fold in (conservative).
-        const out = (Number(u.output_tokens) || 0) + (Number(u.reasoning_output_tokens) || 0)
-        const totalInput = Number(u.input_tokens) || 0
-        const cachedInput = Math.min(totalInput, Number(u.cached_input_tokens) || 0)
-        let max = null
-        try { max = Number(this._contextWindowForModel(this._model)) } catch { /* unknown catalog → omit meter */ }
-        if (Number.isFinite(max) && max > 0) {
-          const used = totalInput + out
+        let snapshot = null
+        try { snapshot = this._usageSnapshotForSession(this._sessionId) } catch { /* unreadable rollout → omit meter */ }
+        const used = Number(snapshot?.context?.used)
+        const max = Number(snapshot?.context?.max)
+        if (Number.isFinite(used) && used >= 0 && Number.isFinite(max) && max > 0) {
           this._emit({ kind: 'usage', ctx: { used, max, pct: Math.min(100, Math.max(0, Math.round((used / max) * 100))), over: used > max, model: this._model } })
         }
+        // Codex's turn.completed values are lifetime thread totals, not turn
+        // deltas. Prefer the native rollout totals and subtract the pre-turn
+        // baseline. A fresh thread has no baseline, so its totals equal turn 1.
+        const totals = snapshot?.total || u
+        const before = this._usageBaseline?.total || {}
+        const totalInput = Math.max(0, (Number(totals.input_tokens) || 0) - (Number(before.input_tokens) || 0))
+        const cachedInput = Math.min(totalInput, Math.max(0, (Number(totals.cached_input_tokens) || 0) - (Number(before.cached_input_tokens) || 0)))
+        const out = Math.max(0, (Number(totals.output_tokens) || 0) - (Number(before.output_tokens) || 0))
+        this._usageBaseline = snapshot || null
         this._emit({
           kind: 'result',
           subtype: 'success',
@@ -161,8 +169,7 @@ export class CodexEventMapper {
           costUsd: null,
           usage: {
             // Claude-shape fields are mutually exclusive buckets. Codex reports
-            // cached_input_tokens as a subset of input_tokens, so subtract it here;
-            // usageReportLine adds the buckets and must not double-count cache hits.
+            // cached_input_tokens as a subset of input_tokens, so subtract it.
             input_tokens: totalInput - cachedInput,
             cache_read_input_tokens: cachedInput,
             cache_creation_input_tokens: 0,

package/codex-session.mjs

@@ -65,17 +65,68 @@ export function readCodexModels({ home = process.env.CODEX_HOME || path.join(os.
   } catch { return [] }
 }
 
-// The CLI's current model catalog is the authority for the runtime's usable model
-// window. Keep this separate from readCodexModels so the public announce shape stays
-// stable while the driver can emit a truthful context meter for every Codex model.
-export function readCodexContextWindow(model, { home = process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), fsImpl = fs } = {}) {
-  if (!model) return null
+const rolloutPathCache = new Map()
+
+function codexRolloutPath(sessionId, { home, fsImpl }) {
+  if (!sessionId) return null
+  const cacheKey = `${home}\0${sessionId}`
+  const cached = rolloutPathCache.get(cacheKey)
+  if (cached) return cached
+  const root = path.join(home, 'sessions')
   try {
-    const data = JSON.parse(fsImpl.readFileSync(path.join(home, 'models_cache.json'), 'utf8'))
-    const hit = (Array.isArray(data?.models) ? data.models : []).find((m) => m?.slug === model)
-    const max = Number(hit?.context_window)
-    return Number.isFinite(max) && max > 0 ? Math.floor(max) : null
+    const suffix = `${sessionId}.jsonl`
+    const hit = fsImpl.readdirSync(root, { recursive: true, withFileTypes: true })
+      .find((entry) => entry.isFile() && entry.name.endsWith(suffix))
+    if (!hit) return null
+    const found = path.join(hit.parentPath || hit.path || root, hit.name)
+    rolloutPathCache.set(cacheKey, found)
+    return found
+  } catch { return null }
+}
+
+// `codex exec --json` exposes lifetime thread totals on `turn.completed`. Those
+// totals are useful for billing, but they are NOT context occupancy: an agentic
+// turn can make hundreds of cached model calls and process many context windows.
+// The native rollout's final token_count record carries both the exact last
+// request and Codex's usable window, so read only a bounded tail of that file.
+export function readCodexThreadUsage(sessionId, {
+  home = process.env.CODEX_HOME || path.join(os.homedir(), '.codex'),
+  fsImpl = fs,
+  tailBytes = 4 * 1024 * 1024,
+} = {}) {
+  const file = codexRolloutPath(sessionId, { home, fsImpl })
+  if (!file) return null
+  let fd
+  try {
+    const size = Number(fsImpl.statSync(file).size) || 0
+    const length = Math.min(size, Math.max(64 * 1024, tailBytes))
+    const buf = Buffer.alloc(length)
+    fd = fsImpl.openSync(file, 'r')
+    fsImpl.readSync(fd, buf, 0, length, size - length)
+    const lines = buf.toString('utf8').split('\n')
+    for (let i = lines.length - 1; i >= 0; i--) {
+      let row
+      try { row = JSON.parse(lines[i]) } catch { continue }
+      if (row?.payload?.type !== 'token_count' || !row.payload.info) continue
+      const info = row.payload.info
+      const last = info.last_token_usage || {}
+      const total = info.total_token_usage || {}
+      const used = Number(last.total_tokens)
+      const max = Number(info.model_context_window)
+      if (!Number.isFinite(used) || used < 0 || !Number.isFinite(max) || max <= 0) return null
+      return {
+        context: { used: Math.floor(used), max: Math.floor(max) },
+        total: {
+          input_tokens: Math.max(0, Number(total.input_tokens) || 0),
+          cached_input_tokens: Math.max(0, Number(total.cached_input_tokens) || 0),
+          output_tokens: Math.max(0, Number(total.output_tokens) || 0),
+        },
+        rateLimits: row.payload.rate_limits || null,
+      }
+    }
   } catch { return null }
+  finally { if (fd != null) { try { fsImpl.closeSync(fd) } catch { /* noop */ } } }
+  return null
 }
 
 export function normalizeCodexSandbox(value) {
@@ -158,6 +209,7 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
   let turnActive = false
   let activeModel = model || null
   let activeEffort = EFFORT_LEVELS.has(initialEffort) ? initialEffort : 'high'
+  let latestUsageSnapshot = sessionId ? readCodexThreadUsage(sessionId) : null
   let mcpHttpPromise = null
   // serialize turns: one exec at a time
   let chain = Promise.resolve()
@@ -166,7 +218,11 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
   const mapper = new CodexEventMapper({
     onEvent,
     model: model || null,
-    contextWindowForModel: (id) => readCodexContextWindow(id),
+    usageSnapshotForSession: (id) => {
+      const snapshot = readCodexThreadUsage(id)
+      if (snapshot) latestUsageSnapshot = snapshot
+      return snapshot
+    },
   })
 
   const note = (text) => { try { onEvent?.({ kind: 'note', text }) } catch { /* noop */ } }
@@ -197,6 +253,10 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
       prompt,
     })
 
+    // Snapshot lifetime totals before the turn. The mapper subtracts this from
+    // the post-turn totals so result/accounting events contain this turn only.
+    mapper.setUsageBaseline(sessionId ? readCodexThreadUsage(sessionId) : null)
+
     return new Promise((resolve) => {
       // stdin: /dev/null (spike gotcha — codex blocks on stdin otherwise)
       let stdinFd
@@ -267,6 +327,7 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
 
   return {
     get sessionId() { return sessionId },
+    get usageSnapshot() { return latestUsageSnapshot },
     get turnActive() { return turnActive },
     get started() { return turnNo > 0 || turnActive },
     sendTurn(text) {
@@ -305,6 +366,7 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
       // next turn so the selected mode is real, while ThinkPool keeps the lane log.
       sessionId = null
       turnNo = 0
+      latestUsageSnapshot = null
       return true
     },
     setEffort(nextEffort) {
@@ -317,6 +379,7 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
       if (turnActive) return false
       sessionId = null
       turnNo = 0
+      latestUsageSnapshot = null
       return true
     },
   }

package/event-id.mjs

@@ -284,6 +284,24 @@ export function usageReportLine (sessionModel, logEvents) {
   return `usage · ${turns} · ${perStr}${total}${cost}`
 }
 
+// Codex exposes exact current-context and lifetime-thread counters in its native
+// rollout telemetry. Keep this separate from usageReportLine: Claude result
+// events are per turn, while Codex's public turn.completed counters are lifetime
+// totals and cannot safely be folded from the retained log.
+export function codexUsageReportLine (sessionModel, snapshot) {
+  const ctx = snapshot?.context
+  const total = snapshot?.total
+  if (!ctx || !total) return 'usage · no completed Codex turn yet'
+  const fmtTok = (n) => n >= 1e6 ? (n / 1e6).toFixed(1) + 'M' : n >= 1e3 ? (n / 1e3).toFixed(1) + 'k' : String(Math.round(n || 0))
+  const used = Math.max(0, Number(ctx.used) || 0)
+  const max = Math.max(0, Number(ctx.max) || 0)
+  const pct = max > 0 ? Math.min(100, Math.max(0, Math.round((used / max) * 100))) : 0
+  const input = Math.max(0, Number(total.input_tokens) || 0)
+  const cached = Math.min(input, Math.max(0, Number(total.cached_input_tokens) || 0))
+  const output = Math.max(0, Number(total.output_tokens) || 0)
+  return `usage · ${prettyModelId(sessionModel)} · context ${fmtTok(used)}/${fmtTok(max)} (${pct}%) · thread ${fmtTok(input)} processed (${fmtTok(cached)} cached) / ${fmtTok(output)} out`
+}
+
 /* The context-carry recap moved to ./recap.mjs (ADR-0010 / S4, 2026-07-09).
  *
  * Why: the WEB CLIENT needs buildRecapFromLog to carry a lane's bridgeless

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.205",
+  "version": "0.7.207",
   "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) }
+      },
+    ),
+  ]
+}