thinkpool-pair 0.7.98 → 0.7.99

package/bridge.mjs

@@ -40,7 +40,11 @@ import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
 import { z } from 'zod'
 import { startClaudeSession } from './claude-session.mjs'
 import { FLOW_CONDUCTOR_PROMPT, FLOW_LANE_PROMPT, buildConductorEnv } from './flow-conductor.mjs'
-import { createFlowWorktree } from './flow-worktree.mjs'
+import { createFlowWorktree, worktreeSpec } from './flow-worktree.mjs'
+import { startPreview, stopAllPreviews } from './flow-preview.mjs'
+import { FLOW_REVIEWER_PROMPT, revertLane } from './flow-review.mjs'
+import { mergeWorktrees, inlineSingleHtml, initRepo } from './flow-assembly.mjs'
+import { canDispatch, FLOW_LIMITS } from './flow-budget.mjs'
 import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, CROSSROOM, formatPairRoster, crossRoomPostDecision } from './cross-terminal.mjs'
 import { turnInFlight } from './update-gate.mjs'
 import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames, appendDurableEvents, seedDurableEvents, readDurablePage, readDurableOldestSeq } from './session-store.mjs'
@@ -1304,9 +1308,14 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
           if (!entry.flowSessionId || !entry.flowTaskKey) return okText('Not a Flow lane — nothing to mark done.')
           let commitSha = null
           try { commitSha = execFileSync('git', ['-C', entry.cwd || process.cwd(), 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim() } catch { /* no commits yet */ }
-          bcast('flow-task-done', { term: id, flowId: entry.flowSessionId, taskKey: entry.flowTaskKey, laneId: id, commitSha }, flowChannel)
-          process.stderr.write(`\n  ${A.cyan}◆ flow slice done — ${entry.flowTaskKey} (${commitSha ? commitSha.slice(0, 8) : 'no commit'})${A.rst}\n`)
-          return okText(`Slice "${entry.flowTaskKey}" marked done${commitSha ? ` (commit ${commitSha.slice(0, 8)})` : ' (no commit yet — commit, then re-call)'}. The room records it + dispatches any slices that depended on you.`)
+          // Step 3 runtime: serve this lane's worktree so the room can iframe a live
+          // preview. Static serve — works for the no-build single-file artifact; URL
+          // rides the done broadcast.
+          let previewUrl = null
+          try { const pv = await startPreview({ dir: entry.cwd || process.cwd(), id: `lane:${id}` }); previewUrl = pv.url } catch { /* preview best-effort */ }
+          bcast('flow-task-done', { term: id, flowId: entry.flowSessionId, taskKey: entry.flowTaskKey, laneId: id, commitSha, previewUrl }, flowChannel)
+          process.stderr.write(`\n  ${A.cyan}◆ flow slice done — ${entry.flowTaskKey} (${commitSha ? commitSha.slice(0, 8) : 'no commit'})${previewUrl ? ` · preview ${previewUrl}` : ''}${A.rst}\n`)
+          return okText(`Slice "${entry.flowTaskKey}" marked done${commitSha ? ` (commit ${commitSha.slice(0, 8)})` : ' (no commit yet — commit, then re-call)'}${previewUrl ? `. Live preview: ${previewUrl}` : ''}. The room records it + dispatches any slices that depended on you.`)
         },
       ),
     ],
@@ -1816,13 +1825,21 @@ flowChannel
     if (!payload?.flowId || !Array.isArray(payload.tasks)) return
     if (payload.host && payload.host !== name) return
     const assignments = []
+    // Step 6 — cap concurrent Flow lanes (invariant: ≤ FLOW_LIMITS.maxConcurrentLanes).
+    // Overflow tasks stay pending; the room re-dispatches them in the next wave.
+    let liveLanes = [...sessions.values()].filter(e => typeof e.spawnedBy === 'string' && e.spawnedBy.startsWith('flow:')).length
     for (const t of payload.tasks) {
+      const gate = canDispatch({ mode: payload.mode || 'guide', liveLanes, budget: { capTokens: null, spentTokens: 0, killed: false } })
+      if (!gate.ok) { process.stderr.write(`\n  ${A.yel}◆ flow dispatch held (${gate.reason}, ${liveLanes}/${FLOW_LIMITS.maxConcurrentLanes} lanes) — ${assignments.length} spawned this wave.${A.rst}\n`); break }
       try {
+        // Step 4 — a `review` slice gets the adversarial reviewer prompt (try-to-break),
+        // every other slice gets the builder prompt.
+        const isReview = t.slice_type === 'review'
         const { dir } = createFlowWorktree({ flowId: payload.flowId, taskKey: t.task_key })
         const laneId = randomUUID()
         termNames[laneId] = `Flow · ${t.task_key}`
         saveNames(room, termNames)
-        openStructured({ id: laneId, cwd: dir, mode: 'acceptEdits', rolePrompt: FLOW_LANE_PROMPT, flowSessionId: payload.flowId, flowTaskKey: t.task_key, spawnedBy: `flow:${payload.flowId}` })
+        openStructured({ id: laneId, cwd: dir, mode: 'acceptEdits', rolePrompt: isReview ? FLOW_REVIEWER_PROMPT : FLOW_LANE_PROMPT, flowSessionId: payload.flowId, flowTaskKey: t.task_key, spawnedBy: `flow:${payload.flowId}` })
         const le = sessions.get(laneId)
         if (le?.session) {
           const spec =
@@ -1836,6 +1853,7 @@ flowChannel
           try { le.session.sendTurn(spec) } catch { /* session still starting */ }
         }
         assignments.push({ task_key: t.task_key, laneId })
+        liveLanes++
       } catch (e) {
         process.stderr.write(`\n  ${A.yel}◆ flow dispatch failed for ${t.task_key}: ${e?.message || e}${A.rst}\n`)
       }
@@ -1846,6 +1864,48 @@ flowChannel
       announce()
     }
   })
+  .on('broadcast', { event: 'flow-assemble' }, async ({ payload }) => {
+    // Step 7 — all slices done + reviewed: merge the lane worktrees into one app, inline
+    // to a single self-contained index.html (the no-build artifact), commit a per-Flow
+    // repo, serve a live preview, and broadcast the result. Zip / GitHub-push export is
+    // offered room-side off this committed repo.
+    if (!payload?.flowId || !Array.isArray(payload.tasks)) return
+    if (payload.host && payload.host !== name) return
+    try {
+      const short = String(payload.flowId).replace(/-/g, '').slice(0, 8)
+      const dirs = payload.tasks
+        .map(t => worktreeSpec({ flowId: payload.flowId, taskKey: t.task_key }).dir)
+        .filter(d => fs.existsSync(d))
+      if (!dirs.length) { process.stderr.write(`\n  ${A.yel}◆ flow assemble: no lane worktrees for ${short}.${A.rst}\n`); return }
+      const outDir = path.join(process.cwd(), '.claude', 'worktrees', `flow-${short}-assembled`)
+      fs.rmSync(outDir, { recursive: true, force: true })
+      const merged = mergeWorktrees({ dirs, outDir })
+      const htmlPath = path.join(outDir, 'index.html')
+      if (fs.existsSync(htmlPath)) {
+        try { fs.writeFileSync(htmlPath, inlineSingleHtml({ htmlPath, root: outDir })) } catch (e) { process.stderr.write(`\n  ${A.yel}◆ inline failed: ${e?.message || e}${A.rst}\n`) }
+      }
+      try { initRepo({ dir: outDir }) } catch { /* best-effort */ }
+      let previewUrl = null
+      try { const pv = await startPreview({ dir: outDir, id: `assembled:${payload.flowId}` }); previewUrl = pv.url } catch { /* best-effort */ }
+      bcast('flow-assembled', { term: 'flow', flowId: payload.flowId, previewUrl, outDir, files: merged.files, conflicts: merged.conflicts }, flowChannel)
+      process.stderr.write(`\n  ${A.mag}◆ flow assembled — ${merged.files.length} file(s)${merged.conflicts.length ? `, ${merged.conflicts.length} conflict(s)` : ''}${previewUrl ? ` · preview ${previewUrl}` : ''} (flow ${short}).${A.rst}\n`)
+      announce()
+    } catch (e) {
+      process.stderr.write(`\n  ${A.yel}◆ flow assemble failed: ${e?.message || e}${A.rst}\n`)
+    }
+  })
+  .on('broadcast', { event: 'flow-revert' }, ({ payload }) => {
+    // Step 4 — atomic per-lane revert: roll back ONE slice (remove its worktree +
+    // branch) without touching the others, when adversarial review rejects it. The
+    // room re-dispatches the reverted task on the next wave.
+    if (!payload?.flowId || !payload?.taskKey) return
+    if (payload.host && payload.host !== name) return
+    try {
+      const { branch } = revertLane({ flowId: payload.flowId, taskKey: payload.taskKey })
+      bcast('flow-reverted', { term: 'flow', flowId: payload.flowId, taskKey: payload.taskKey, branch }, flowChannel)
+      process.stderr.write(`\n  ${A.yel}◆ flow slice reverted — ${payload.taskKey} (${branch}).${A.rst}\n`)
+    } catch (e) { process.stderr.write(`\n  ${A.yel}◆ flow revert failed: ${e?.message || e}${A.rst}\n`) }
+  })
   .subscribe()
 
 // Watchdog — if the realtime channel is stuck (never connected, or dropped and
@@ -1980,6 +2040,7 @@ async function shutdown(code = 0, farewell = true) {
   // process alive with orphaned PTY children + stale "live" presence.
   setTimeout(() => process.exit(code), 1500)
   clearInterval(flushTimer)
+  try { stopAllPreviews() } catch { /* Flow preview servers — best-effort close */ }
   if (farewell) {
     try {
       const bye = Buffer.from('\r\n[ shared session ended ]\r\n', 'utf8').toString('base64')

package/flow-assembly.mjs

@@ -0,0 +1,183 @@
+// Thinkpool Flow — Step 7: assembly + delivery.
+//
+// Lanes each built a DISJOINT slice in its own git worktree (flow-worktree.mjs).
+// Assembly collects those slices into one final app, then delivers it. The MVP
+// artifact ("BLEAK SWORD") is a SINGLE self-contained index.html — no build step,
+// no external assets — but lanes own separate module files (audio.js, sprites.js,
+// combat.js, render.js + an index.html shell that imports them). So assembly must
+// INLINE those modules back into one index.html.
+//
+// Export-destination decision (locked with the spec): a finished Flow ships as a
+// per-Flow git repo (initRepo) + a zip Buffer (zipDir) + an OPTIONAL best-effort
+// GitHub push (pushToGithub). The git repo is the source of truth; zip is the
+// download; GitHub push is opt-in and never blocks delivery.
+//
+// Node built-ins ONLY (fs, path, child_process, zlib) — bridge ships as npm
+// thinkpool-pair with no new deps. Pure over injected fs/git/gh/readFile so the
+// whole step is unit-testable against temp dirs.
+// Spec: docs/specs/2026-06-29-thinkpool-flow.md (Step 7).
+
+import { readFileSync as fsReadFile } from 'node:fs'
+import nodeFs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+// ── inlineSingleHtml ─────────────────────────────────────────────────────────
+// Read an index.html and fold its LOCAL relative deps into the document:
+//   <script type="module" src="./x.js"> / <script src="./x.js">  → <script>…</script>
+//   <link rel="stylesheet" href="./x.css">                       → <style>…</style>
+// Only local relative refs are inlined; http(s):// and protocol-relative (//) are
+// left alone. readFile is injected for testability.
+//
+// LIMITATION (documented, on purpose): this is NOT a real ES-module bundler — no
+// dependency resolution, no tree-shaking, no scope isolation. If any inlined script
+// uses `import `/`export `, we concatenate ALL module scripts, in document order,
+// into ONE <script type="module"> block. That only works because Flow's single-file
+// artifacts are written to be concatenation-safe (no cross-file import statements
+// between the lanes' own modules — each lane writes a self-contained module; shared
+// symbols are globals on window, not imported). Bare specifiers / npm imports are
+// out of scope for the single-file deliverable.
+export function inlineSingleHtml ({ htmlPath, root, readFile = fsReadFile }) {
+  const baseDir = root || path.dirname(htmlPath)
+  let html = String(readFile(htmlPath, 'utf8'))
+
+  const isLocal = (ref) => ref && !/^[a-z]+:\/\//i.test(ref) && !ref.startsWith('//')
+  const resolve = (ref) => path.join(baseDir, ref.replace(/^\.\//, ''))
+
+  // Collected module-script bodies (import/export users) get merged into one block.
+  const moduleBodies = []
+
+  // <link rel="stylesheet" href="…"> → <style>…</style>
+  html = html.replace(
+    /<link\b[^>]*\brel=["']stylesheet["'][^>]*>/gi,
+    (tag) => {
+      const m = tag.match(/\bhref=["']([^"']+)["']/i)
+      if (!m || !isLocal(m[1])) return tag
+      const css = String(readFile(resolve(m[1]), 'utf8'))
+      return `<style>\n${css}\n</style>`
+    }
+  )
+
+  // <script … src="…"></script> → inline. Module scripts that import/export are
+  // deferred into moduleBodies; everything else inlines in place.
+  html = html.replace(
+    /<script\b([^>]*)\bsrc=["']([^"']+)["']([^>]*)>\s*<\/script>/gi,
+    (tag, pre, src, post) => {
+      if (!isLocal(src)) return tag
+      const attrs = `${pre} ${post}`
+      const isModule = /\btype=["']module["']/i.test(attrs)
+      const body = String(readFile(resolve(src), 'utf8'))
+      const usesEsm = /(^|[\s;{(])(import|export)\s/.test(body)
+      if (isModule && usesEsm) {
+        moduleBodies.push(`/* inlined: ${src} */\n${body}`)
+        return ''   // collected; emitted as one merged module block below
+      }
+      // Plain script (or module with no import/export): inline directly. Drop
+      // type=module when it carries no ESM syntax — a bare inline module is fine
+      // either way, but stripping keeps the single file maximally portable.
+      return `<script>\n${body}\n</script>`
+    }
+  )
+
+  if (moduleBodies.length) {
+    const merged = `<script type="module">\n${moduleBodies.join('\n')}\n</script>`
+    // Re-attach the merged block where the </body> is (or append if no body tag).
+    if (/<\/body>/i.test(html)) html = html.replace(/<\/body>/i, `${merged}\n</body>`)
+    else html += `\n${merged}\n`
+  }
+
+  return html
+}
+
+// ── mergeWorktrees ───────────────────────────────────────────────────────────
+// Union the files from each lane worktree dir into outDir. Later dirs win on a
+// path conflict (and every conflict is logged). Skips .git, node_modules, .claude.
+// Returns { files, conflicts } — both arrays of outDir-relative paths.
+export function mergeWorktrees ({ dirs, outDir, fs = nodeFs }) {
+  const SKIP = new Set(['.git', 'node_modules', '.claude'])
+  const seen = new Set()
+  const files = []
+  const conflicts = []
+
+  fs.mkdirSync(outDir, { recursive: true })
+
+  const walk = (srcRoot, rel = '') => {
+    const abs = path.join(srcRoot, rel)
+    for (const ent of fs.readdirSync(abs, { withFileTypes: true })) {
+      if (SKIP.has(ent.name)) continue
+      const childRel = rel ? path.join(rel, ent.name) : ent.name
+      if (ent.isDirectory()) {
+        walk(srcRoot, childRel)
+      } else if (ent.isFile()) {
+        const dest = path.join(outDir, childRel)
+        if (seen.has(childRel)) conflicts.push(childRel)
+        else { seen.add(childRel); files.push(childRel) }
+        fs.mkdirSync(path.dirname(dest), { recursive: true })
+        fs.copyFileSync(path.join(srcRoot, childRel), dest)   // later dir wins
+      }
+    }
+  }
+
+  for (const d of dirs) walk(d)
+  return { files, conflicts }
+}
+
+// ── zipDir ───────────────────────────────────────────────────────────────────
+// Produce a zip Buffer of dir. PATH USED: shells out to the system `zip` via
+// child_process (`zip -q -r - .` from inside dir → captured to a Buffer) — robust,
+// produces a standards-compliant archive, no hand-rolled ZIP central directory.
+// We do NOT hand-build a zlib-deflate container: a correct ZIP needs the local
+// headers + central directory + CRC32 + end-of-central-directory record, which is
+// a lot of fiddly bytes to get right for no gain when `zip` is on every dev box.
+// Falls back gracefully — if `zip` is missing, throws a clear, catchable error so
+// callers (and the test) can skip rather than crash the bridge.
+export function zipDir ({ dir }) {
+  try {
+    return execFileSync('zip', ['-q', '-r', '-', '.'], {
+      cwd: dir,
+      maxBuffer: 256 * 1024 * 1024
+    })
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      const e = new Error('zipDir: system `zip` not available')
+      e.code = 'NO_ZIP'
+      throw e
+    }
+    throw err
+  }
+}
+
+// ── initRepo ─────────────────────────────────────────────────────────────────
+// git init + add -A + commit in dir. Injectable git for tests. Returns
+// { committed } — false when there was nothing to commit (empty tree).
+export function initRepo ({ dir, git = runGit }) {
+  git(['init', '-q', '-b', 'main'], dir)
+  git(['add', '-A'], dir)
+  try {
+    git(['commit', '-q', '-m', 'Assembled by Thinkpool Flow'], dir)
+    return { committed: true }
+  } catch {
+    return { committed: false }   // nothing staged / nothing to commit
+  }
+}
+
+// ── pushToGithub ─────────────────────────────────────────────────────────────
+// Best-effort, OPTIONAL. Create a private repo from dir and push via the gh CLI.
+// Never throws — if gh is absent / unauthed / errors, returns { pushed:false,
+// reason } so delivery (repo + zip) still succeeds. Injectable gh for tests.
+export async function pushToGithub ({ dir, repoName, gh = ghCli }) {
+  try {
+    gh(['repo', 'create', repoName, '--private', '--source=.', '--push'], dir)
+    return { pushed: true }
+  } catch (err) {
+    return { pushed: false, reason: err && err.message ? err.message : String(err) }
+  }
+}
+
+// ── injected defaults ─────────────────────────────────────────────────────────
+function runGit (args, cwd) {
+  return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' })
+}
+function ghCli (args, cwd) {
+  return execFileSync('gh', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' })
+}

package/flow-budget.mjs

@@ -0,0 +1,84 @@
+// Thinkpool Flow — autonomy modes' budget cap, kill-switch, and adaptive escalation.
+//
+// Steps 5+6 of the Flow build (docs/specs/2026-06-29-thinkpool-flow.md). Step 5 is
+// the autonomy ladder (Steer / Guide / Autopilot) + adaptive escalation — Autopilot
+// pulls the human back in when a task keeps failing. Step 6 is the HARD budget cap +
+// kill-switch — the run stops BEFORE it overruns, never after. Pure module (no IO,
+// no deps), shared by the bridge (conductor) and the client (room UI), exactly like
+// taskGraph.js — except killSwitchEnv(), the single deliberately-impure fn that reads
+// process.env for the operator override.
+//
+// Enforces spec invariants:
+//   (b) maxHop:1 — lanes never recursively spawn lanes.
+//   (c) Autopilot budget cap is HARD — the kill-switch fires before overrun.
+
+// Concurrency / recursion / escalation limits — mirrored by the dispatcher and the
+// bridge. One source of truth for the numbers the spec locks.
+export const FLOW_LIMITS = {
+  maxConcurrentLanes: 8,   // invariant: ≤8 live Flow lanes at once
+  maxHop: 1,               // invariant (b): no recursive spawning (a lane can't spawn lanes)
+  escalateAfterFails: 2,   // adaptive escalation: pull the human in once failCount hits this
+}
+
+// A budget ledger. capTokens null = uncapped (steer/guide); a number = Autopilot's
+// HARD cap. `killed` latches true once the cap is hit and never flips back.
+export function makeBudget ({ capTokens = null } = {}) {
+  return { capTokens, spentTokens: 0, killed: false }
+}
+
+// Immutable spend update — returns a NEW budget (never mutates). If the cap is set
+// and spend reaches it, `killed` latches true: invariant (c), stop before overrun.
+export function recordSpend (budget, tokens) {
+  const spentTokens = budget.spentTokens + tokens
+  const killed = budget.capTokens != null
+    ? (budget.killed || spentTokens >= budget.capTokens)
+    : budget.killed
+  return { ...budget, spentTokens, killed }
+}
+
+// Has the cap been reached? Uncapped budgets never exceed.
+export function budgetExceeded (budget) {
+  return budget.capTokens != null && budget.spentTokens >= budget.capTokens
+}
+
+// Tokens left before the cap. Uncapped → Infinity. Never negative.
+export function remainingBudget (budget) {
+  if (budget.capTokens == null) return Infinity
+  return Math.max(0, budget.capTokens - budget.spentTokens)
+}
+
+// Gate a dispatch. Lane cap applies in EVERY mode (invariant: ≤8). The budget cap
+// only bites in Autopilot — steer/guide keep a human in the loop, so they ignore the
+// cap (no auto-spend to runaway-protect against). { ok, reason } — reason is '' when ok.
+export function canDispatch ({ mode, liveLanes, budget }) {
+  if (liveLanes >= FLOW_LIMITS.maxConcurrentLanes) {
+    return { ok: false, reason: 'lane cap' }
+  }
+  if (mode === FLOW_MODE_AUTOPILOT && (budget.killed || budgetExceeded(budget))) {
+    return { ok: false, reason: 'budget cap' }
+  }
+  return { ok: true, reason: '' }
+}
+
+// Should this fail surface to the human? In Autopilot the human is OUT of the loop,
+// so we only escalate (auto-pull-human) once a task has failed escalateAfterFails
+// times — adaptive escalation, not on the first hiccup. In guide/steer the human is
+// ALREADY watching, so any fail surfaces immediately — escalation is always true.
+export function shouldEscalate ({ mode, failCount }) {
+  if (mode === FLOW_MODE_AUTOPILOT) return failCount >= FLOW_LIMITS.escalateAfterFails
+  return true
+}
+
+// THE ONLY IMPURE FN — reads process.env for the operator kill-switch / cap override.
+// TP_FLOW_OFF=1 disables Flow dispatch entirely; TP_FLOW_BUDGET_CAP sets the Autopilot
+// token cap from the environment. Kept isolated + flagged so the rest stays pure.
+export function killSwitchEnv () {
+  return {
+    disabled: process.env.TP_FLOW_OFF === '1',
+    capFromEnv: process.env.TP_FLOW_BUDGET_CAP ? Number(process.env.TP_FLOW_BUDGET_CAP) : null,
+  }
+}
+
+// Local mirror of the mode literal (taskGraph.js owns FLOW_MODE; this keeps the
+// budget module dependency-free — it only ever needs the one value).
+const FLOW_MODE_AUTOPILOT = 'autopilot'

package/flow-preview.mjs

@@ -0,0 +1,144 @@
+// Thinkpool Flow — per-lane preview runtime.
+//
+// Each Flow lane builds its slice in its own git worktree (flow-worktree.mjs).
+// The room UI iframes a LIVE preview of that slice, so the worktree dir needs to be
+// reachable over localhost. The MVP artifact is a self-contained index.html (no build
+// step), so a static file server is the universal case — Node http + fs + path, no deps
+// (this is published as the `thinkpool-pair` npm package; new deps are not on the table).
+//
+// Spec: docs/specs/2026-06-29-thinkpool-flow.md (Step 3).
+
+import http from 'node:http'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+
+// Module-level registry of live previews so cleanup (flow cancel / shutdown) can sweep
+// every server without each caller tracking handles. id → { server, url, stop }.
+export const previews = new Map()
+
+// Minimal extension → MIME map. Covers the self-contained-app surface + common assets.
+// Unknown extensions fall back to application/octet-stream (the browser downloads it).
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.svg': 'image/svg+xml',
+  '.wav': 'audio/wav',
+  '.mp3': 'audio/mpeg',
+  '.ico': 'image/x-icon'
+}
+
+function contentType (filePath) {
+  return MIME[path.extname(filePath).toLowerCase()] || 'application/octet-stream'
+}
+
+// Map a request URL path to a real file under `root`, or null if it would escape `root`
+// (path traversal). Decode + strip query/hash, normalize, then verify the resolved path
+// is still inside root — the relative path between them must not climb out with `..`.
+function resolveUnderRoot (root, urlPath) {
+  let pathname
+  try {
+    pathname = decodeURIComponent(new URL(urlPath, 'http://x').pathname)
+  } catch {
+    return null // malformed percent-encoding
+  }
+  const resolved = path.resolve(root, '.' + pathname) // leading '.' keeps it relative to root
+  const rel = path.relative(root, resolved)
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return null
+  return resolved
+}
+
+// Is this path a regular file we can read? (false for dirs / missing / errors)
+async function isFile (p) {
+  try {
+    return (await fsp.stat(p)).isFile()
+  } catch {
+    return false
+  }
+}
+
+async function send (res, status, type, body) {
+  res.writeHead(status, {
+    'Content-Type': type,
+    'Access-Control-Allow-Origin': '*' // local preview only; deliberately NO COOP/COEP
+  })
+  res.end(body)
+}
+
+// Build the request handler bound to a worktree dir. Routing:
+//   - traversal outside dir       → 403
+//   - existing file               → that file
+//   - '/' or a directory          → index.html
+//   - unknown path                → index.html if present (SPA fallback), else 404
+function makeHandler (dir) {
+  const indexPath = path.join(dir, 'index.html')
+  return async (req, res) => {
+    const resolved = resolveUnderRoot(dir, req.url || '/')
+    if (resolved === null) return send(res, 403, 'text/plain; charset=utf-8', 'Forbidden')
+
+    // A concrete file hit (and still a real file, not a dir) → serve it.
+    if (await isFile(resolved)) {
+      try {
+        return send(res, 200, contentType(resolved), await fsp.readFile(resolved))
+      } catch {
+        return send(res, 500, 'text/plain; charset=utf-8', 'Read error')
+      }
+    }
+
+    // Directory, root, or unknown path → fall back to index.html (SPA-friendly).
+    if (await isFile(indexPath)) {
+      try {
+        return send(res, 200, contentType(indexPath), await fsp.readFile(indexPath))
+      } catch {
+        return send(res, 500, 'text/plain; charset=utf-8', 'Read error')
+      }
+    }
+
+    return send(res, 404, 'text/plain; charset=utf-8', 'Not found')
+  }
+}
+
+// Start a static preview server rooted at `dir`. port 0 → OS assigns a free port; the
+// actual bound port is read back from server.address(). Resolves once listening.
+// Returns { url, port, stop } — stop() is idempotent and async-safe.
+export function startPreview ({ dir, port = 0, host = '127.0.0.1', id } = {}) {
+  if (!dir) throw new Error('startPreview: dir is required')
+
+  const server = http.createServer(makeHandler(dir))
+
+  // Idempotent stop: close once, no-op on subsequent calls; resolve when fully closed.
+  let stopped = false
+  const stop = () =>
+    new Promise((resolve) => {
+      if (id !== undefined) previews.delete(id)
+      if (stopped) return resolve()
+      stopped = true
+      server.close(() => resolve())
+    })
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(port, host, () => {
+      server.removeListener('error', reject)
+      const bound = server.address().port
+      const url = `http://${host}:${bound}/`
+      const handle = { server, url, stop, dir }
+      if (id !== undefined) previews.set(id, handle)
+      resolve({ url, port: bound, stop })
+    })
+  })
+}
+
+// Stop + deregister every live preview. Best-effort; awaits all closes.
+export async function stopAllPreviews () {
+  const handles = [...previews.values()]
+  previews.clear()
+  await Promise.all(handles.map((h) => h.stop()))
+}

package/flow-review.mjs

@@ -0,0 +1,92 @@
+// Thinkpool Flow — Step 4: adversarial review + per-lane atomic revert.
+//
+// After a lane commits its slice (commit_sha on flow_tasks = the revert target), an
+// ADVERSARIAL reviewer lane tries to BREAK it: run it, find where acceptance isn't
+// actually met, find regressions/edge cases. Its verdict drives the gate — accept iff
+// every reviewer passed; any fail → revert THIS lane only. The atomic-revert invariant:
+// one lane rolls back (its worktree + branch gone) without touching any other lane's
+// work (disjoint worktrees, M57). Spec: docs/specs/2026-06-29-thinkpool-flow.md (Step 4).
+//
+// Pure over injected git/removeWorktree so it's unit-testable against a temp repo.
+
+import { execFileSync } from 'node:child_process'
+import { TASK_STATUS } from './flow-task-graph.mjs'
+import { removeFlowWorktree } from './flow-worktree.mjs'
+
+// The reviewer lane's rolePrompt (via startClaudeSession). Mirrors FLOW_LANE_PROMPT's
+// join('  ') style. This lane is ADVERSARIAL — its job is to disprove "done", not to build.
+export const FLOW_REVIEWER_PROMPT = [
+  'THINKPOOL FLOW — you are an ADVERSARIAL REVIEWER in an ensemble build. You did NOT build this slice. Another lane did, and claims it is done. Your job is to TRY TO BREAK IT — independently verify whether its acceptance criteria are ACTUALLY met. The slice you are reviewing (its scope, its acceptance criteria, and its worktree/branch) arrives as your first message.',
+
+  'RUN IT, DON\'T TRUST IT. Check out the lane\'s worktree/branch and RUN the slice yourself. "It compiles" is not "it works". Reproduce the acceptance proof with your own hands — run the command, hit the endpoint, submit the form, reload the page. If you cannot independently reproduce the acceptance criteria, that is a REJECT.',
+
+  'HUNT FOR FAILURE. Look where the builder didn\'t: edge cases, empty/malformed input, the second click, the reload, concurrent use, the error path. Check the slice didn\'t regress anything outside its acceptance line. A green happy-path is the floor, not the bar.',
+
+  'DEFAULT TO REJECT. If you cannot independently verify EVERY acceptance criterion — reject. Ambiguity, "probably fine", "looks right", an untestable claim, a flaky run — all REJECT. The cost of a false pass (a broken slice merged into the assembly) is far higher than a re-run.',
+
+  'BE SPECIFIC. Your reasons must name exactly WHAT failed and HOW you found it — the command you ran, the output you got, the acceptance criterion it violated. "Doesn\'t work" is useless. "GET /api/todos returned 500 with `column todos.user_id does not exist`; acceptance required 200 + []" is a usable verdict.',
+
+  'EMIT A VERDICT, NOT A mark_flow_done. You do NOT call mark_flow_done — that is the builder\'s path. You emit a REVIEW VERDICT: a single JSON object `{ "pass": <boolean>, "reasons": ["<specific finding>", ...], "taskKey": "<the slice you reviewed>" }`. `pass: false` means revert this lane. Put ONLY that JSON object in your verdict (no surrounding prose, no markdown fences). Do not edit the slice — you review, you do not fix.',
+].join('  ')
+
+// Parse a reviewer's raw verdict. Accepts an object OR a JSON string (optionally
+// ```json-fenced). Tolerant of the fence the model sometimes wraps; throws on garbage.
+// Returns { pass, reasons } — pass coerced to boolean, reasons normalized to string[].
+export function parseReviewVerdict (raw) {
+  let obj = raw
+  if (typeof raw === 'string') {
+    let s = raw.trim()
+    const fence = s.match(/```(?:json)?\s*([\s\S]*?)```/i)
+    if (fence) s = fence[1].trim()
+    obj = JSON.parse(s) // throws on unparseable
+  }
+  if (!obj || typeof obj !== 'object') throw new Error('review verdict is not an object')
+  if (typeof obj.pass !== 'boolean') throw new Error('review verdict missing boolean `pass`')
+  const reasons = Array.isArray(obj.reasons) ? obj.reasons.map(String) : []
+  return { pass: obj.pass, reasons }
+}
+
+// Gate decision over a task's verdicts (≥1 reviewer). Accept iff EVERY verdict passes;
+// any fail → mustRevert. reasons collects the failing verdicts' reasons (the why).
+export function reviewDecision ({ verdicts }) {
+  const list = Array.isArray(verdicts) ? verdicts : []
+  if (list.length === 0) {
+    // No reviewer ran — cannot independently verify, so default to reject (the prompt's stance).
+    return { accept: false, mustRevert: true, reasons: ['no review verdict produced'] }
+  }
+  const accept = list.every(v => v.pass === true)
+  const reasons = list.filter(v => !v.pass).flatMap(v => Array.isArray(v.reasons) ? v.reasons : [])
+  return { accept, mustRevert: !accept, reasons }
+}
+
+// Atomic per-lane revert: tear down ONE lane's worktree + branch, nothing else.
+// Delegates to the injected removeWorktree (defaults to removeFlowWorktree). Best-effort
+// — never throws on an already-gone worktree/branch. Returns { reverted, branch }.
+export function revertLane ({ flowId, taskKey, root, git = defaultGit, removeWorktree = removeFlowWorktree }) {
+  const { branch } = worktreeBranch({ flowId, taskKey, root })
+  try {
+    removeWorktree({ flowId, taskKey, root, git })
+  } catch { /* best-effort: worktree/branch already gone */ }
+  return { reverted: true, branch }
+}
+
+// Status a task moves to after the review gate resolves.
+export function nextTaskStatusAfterReview ({ accept }) {
+  return accept ? TASK_STATUS.done : TASK_STATUS.reverted
+}
+
+// ── internals ───────────────────────────────────────────────────────────────
+// Resolve the lane's branch name without importing worktreeSpec's full surface here;
+// keeps revertLane's return honest even when the injected removeWorktree is a spy.
+function worktreeBranch ({ flowId, taskKey, root }) {
+  const short = String(flowId).replace(/-/g, '').slice(0, 8)
+  const safeKey = String(taskKey).toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 40).replace(/^-+|-+$/g, '') || 'task'
+  void root
+  return { branch: `flow/${short}/${safeKey}` }
+}
+
+// Default git runner mirrors flow-worktree's — only used if a caller passes neither
+// git nor a custom removeWorktree (the real removeFlowWorktree supplies its own default).
+function defaultGit (args, cwd) {
+  return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.98",
+  "version": "0.7.99",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -19,6 +19,10 @@
     "flow-conductor.mjs",
     "flow-worktree.mjs",
     "flow-task-graph.mjs",
+    "flow-preview.mjs",
+    "flow-review.mjs",
+    "flow-assembly.mjs",
+    "flow-budget.mjs",
     "serve-dir.mjs",
     "service.mjs",
     "presence.mjs",