thinkpool-pair 0.7.154 → 0.7.155

package/bridge.mjs

@@ -57,8 +57,9 @@ function stopFlowPreviews (flowId, laneId = null) {
     if (laneId ? key === `lane:${flowId}:${laneId}` : key.startsWith(`lane:${flowId}:`)) { try { h.stop() } catch { /* noop */ } }
   }
 }
-import { FLOW_REVIEWER_PROMPT, revertLane, parseReviewVerdict } from './flow-review.mjs'
+import { FLOW_REVIEWER_PROMPT, revertLane, parseReviewVerdict, reviewVerdictToReflection } from './flow-review.mjs'
 import { reviewGateDecision } from './flow-review-gate.mjs'
+import { pairAdjudicationPrompt, reviewReflectionDecision, REVIEW_DEFAULTS } from './flow-review-reflect.mjs'
 import { mergeWorktrees, inlineSingleHtml, initRepo } from './flow-assembly.mjs'
 import { canDispatch, FLOW_LIMITS, makeBudget, recordSpend, killSwitchEnv } from './flow-budget.mjs'
 // S4 slice 2 — clean re-dispatch. When a lane is killed mid-tool-call (budget/review/restart)
@@ -84,7 +85,7 @@ const flowBudgets = new Map()
 import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, SPAWN, CROSSROOM, formatPairRoster, crossRoomPostDecision, formatRoomNow } from './cross-terminal.mjs'
 import { turnInFlight } from './update-gate.mjs'
 import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames, appendDurableEvents, seedDurableEvents, readDurablePage, readDurableOldestSeq, loadSummary, saveSummary } from './session-store.mjs'
-import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks } from './event-id.mjs'
+import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks, usageReportLine } from './event-id.mjs'
 import { makeThrottledTrack } from './presence.mjs'
 
 // Public client creds (the same anon values the web app ships — safe to embed).
@@ -1376,14 +1377,71 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
     } catch (e) {
       return { ok: false, message: `Review verdict REJECTED: ${e?.message || e}. Re-Write FLOW_REVIEW.json with {"pass":<boolean>,"reasons":["<specific finding>"],"taskKey":"<the slice you reviewed>"}.` }
     }
-    if (!v.pass && target) {
+    // E1 A1/A2 — the BOUNDED reviewer loop, live side. Each FLOW_REVIEW.json write is ONE
+    // hunt round; the governor decides continue-vs-stop from the round count + the lane's
+    // REAL budget (flowBudgets ledger). A bare pass:true (happy path held, not yet exhausted)
+    // under both ceilings → dig ONE more round instead of concluding; a concrete failure, an
+    // exhausted pass, or a ceiling (rounds OR budget) → terminal, surfaced to the pair (P3).
+    // Fail-closed: a lane at/over its cap concludes (surface) and is never re-prompted. Held
+    // for live-room verification (bridge is inert until published); the decision logic is
+    // unit-proven in flow-review.loop.test.mjs + flow-review-reflect.test.mjs.
+    const round = (entry.flowReviewRound = (entry.flowReviewRound || 0) + 1)
+    const b = flowBudgets.get(entry.flowSessionId) || null
+    const decision = reviewReflectionDecision({
+      round,
+      maxRounds: REVIEW_DEFAULTS.maxRounds,
+      spentTokens: b ? b.spentTokens : 0,
+      budgetCap: b ? b.capTokens : null,
+      ...reviewVerdictToReflection(v),
+    })
+
+    // Not concluded, under both ceilings → send the reviewer back for another bounded round.
+    // No revert, no verdict broadcast, no markFlowDone — the loop stays open.
+    if (!decision.stop) {
+      const next = round + 1
+      try {
+        entry.session?.sendTurn(
+          `[Flow review — round ${next}/${REVIEW_DEFAULTS.maxRounds}] The happy path held, but you have NOT reported your checks exhausted and you are under both the round and budget ceilings. Dig one more round: hunt the edge cases, the reload, the second click, concurrent use, the error path — the places the builder didn't. Then re-Write FLOW_REVIEW.json — pass:false with a specific reason if you break it, or pass:true AND exhausted:true if you genuinely have nothing left to check.`,
+        )
+      } catch { /* lane may have closed mid-verdict */ }
+      process.stderr.write(`\n  ${A.dim}◆ review round ${round} inconclusive — digging again (${next}/${REVIEW_DEFAULTS.maxRounds}) on ${target || entry.flowTaskKey}${A.rst}\n`)
+      return { ok: true, message: `Round ${round} recorded (pass, not yet exhausted). Keep hunting — asked you for round ${next}/${REVIEW_DEFAULTS.maxRounds}.` }
+    }
+
+    // Terminal outcome. reject → revert the reviewed slice; surface → hand the inconclusive
+    // result to the pair WITHOUT reverting (no failure was reproduced); pass → accept.
+    if (decision.action === 'reject' && target) {
       bcast('flow-revert', { term: id, flowId: entry.flowSessionId, taskKey: target }, flowChannel)
-      process.stderr.write(`\n  ${A.yel}◆ review FAIL — reverting ${target}: ${v.reasons.join('; ').slice(0, 120)}${A.rst}\n`)
+      process.stderr.write(`\n  ${A.yel}◆ review REJECT (round ${round}) — reverting ${target}: ${v.reasons.join('; ').slice(0, 120)}${A.rst}\n`)
     } else {
-      process.stderr.write(`\n  ${A.cyan}◆ review PASS — ${target || entry.flowTaskKey}${A.rst}\n`)
+      process.stderr.write(`\n  ${A.cyan}◆ review ${decision.action.toUpperCase()} (round ${round}) — ${target || entry.flowTaskKey}${A.rst}\n`)
     }
+    // P3 (pair co-adjudication) — surface the TERMINAL verdict into the ROOM as a
+    // challengeable prompt, ALONGSIDE the gate action above. A solo Bugbot's verdict is
+    // final; ours is a prompt for the two humans + Pool to argue. Additive: an extra
+    // broadcast, does NOT change the revert/gate flow.
+    bcast('flow-review-verdict', {
+      term: id, flowId: entry.flowSessionId,
+      taskKey: target || entry.flowTaskKey,
+      pass: v.pass,
+      reasons: v.reasons,
+      action: decision.action,
+      rounds: round,
+      surfaceToPair: decision.surfaceToPair,
+      prompt: pairAdjudicationPrompt({
+        action: decision.action,
+        reason: decision.reason,
+        taskKey: target || entry.flowTaskKey,
+        findings: v.reasons,
+      }),
+    }, flowChannel)
     const doneMsg = await markFlowDone()
-    return { ok: true, message: `Review verdict recorded: ${v.pass ? 'PASS' : `FAIL — reverting ${target || '(no target)'} (${v.reasons.join('; ').slice(0, 160)})`}. ${doneMsg}` }
+    const label = decision.action === 'reject'
+      ? `REJECT (round ${round}) — reverting ${target || '(no target)'} (${v.reasons.join('; ').slice(0, 140)})`
+      : decision.action === 'surface'
+        ? `SURFACED to the pair after ${round} round${round === 1 ? '' : 's'} — ${decision.reason}`
+        : `PASS (round ${round})`
+    return { ok: true, message: `Review verdict recorded: ${label}. ${doneMsg}` }
   }
   // Identity for the durable archive — pushLog appends every new transcript event to
   // <room>/<id>.events.jsonl keyed off these. Seed the archive once from the restored
@@ -2334,6 +2392,13 @@ 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 ◆
+    // control lines (like /model) so both members AND late-joiners see it. Scope is honest —
+    // the Agent SDK exposes tokens + cost, not plan/rate-limit meters, and the card says so.
+    if (/^\/usage\s*$/.test(text)) { ctlLine(usageReportLine(s.model, s.log)); return }
     // Pre-flight budget gate (room scope) — refuse the billable agent turn if the room hit
     // its cap. The slash controls above (/model, /clear, /compact) are intentionally exempt:
     // they let a user manage or REDUCE spend even when capped. Legible refusal, no silent stall.

package/event-id.mjs

@@ -191,3 +191,60 @@ export function inlineImageBlocks(evt) {
   })
   return out
 }
+
+// Pure aggregation for the /usage report — replay a session's retained log events and
+// fold every completed turn (kind:'result' with usage) into per-model + total token/cost
+// sums. No side effects, import-safe (bridge/test-usage-summary.mjs exercises it), so the
+// bridge computes /usage by replaying its own durable log — no separate accumulator that a
+// restart would drop. `costUsd` is the SDK's total_cost_usd per turn (BYOK estimate).
+export function summarizeUsage(logEvents) {
+  const results = (Array.isArray(logEvents) ? logEvents : []).filter((e) => e && e.kind === 'result' && e.usage)
+  const per = new Map()
+  let totalIn = 0, totalOut = 0, totalCost = 0, haveCost = false
+  for (const e of results) {
+    const u = e.usage || {}
+    const inTok = (u.input_tokens || 0) + (u.cache_creation_input_tokens || 0) + (u.cache_read_input_tokens || 0)
+    const out = u.output_tokens || 0
+    const cached = u.cache_read_input_tokens || 0
+    const mid = e.model || 'unknown'
+    const r = per.get(mid) || { model: mid, in: 0, out: 0, cached: 0 }
+    r.in += inTok; r.out += out; r.cached += cached; per.set(mid, r)
+    totalIn += inTok; totalOut += out
+    if (typeof e.costUsd === 'number') { totalCost += e.costUsd; haveCost = true }
+  }
+  return { turns: results.length, per: [...per.values()], totalIn, totalOut, totalCost, haveCost }
+}
+
+// model id → friendly label for the /usage report: claude-opus-4-8 → "Opus 4.8".
+// Bridge-local twin of the web's prettyModel (structured.jsx); falls back to the raw id.
+export function prettyModelId (m) {
+  if (!m) return 'unknown'
+  const mm = String(m).match(/(opus|sonnet|haiku|fable)-(\d+)(?:-(\d+))?/i)
+  return mm ? `${mm[1][0].toUpperCase()}${mm[1].slice(1)} ${mm[2]}${mm[3] ? '.' + mm[3] : ''}` : String(m)
+}
+
+// Build the ONE ◆ control line the /usage command emits, from the session's model +
+// retained log. Pure so the whole command — gate, empty-state, and per-model/total/cost
+// formatting — is exercised deterministically (bridge/test-usage-summary.mjs). The bridge
+// handler is a thin wrapper: ctlLine(usageReportLine(s.model, s.log)). `sessionModel` is
+// the resolved model id the /model state tracks; `logEvents` the session's retained log.
+export function usageReportLine (sessionModel, logEvents) {
+  const claudeish = (m) => /claude|anthropic|opus|sonnet|haiku|fable/i.test(String(m || ''))
+  const sum = summarizeUsage(logEvents)
+  // Gate (Max's ask: "make /usage work if users bridge is on claude llms"). The Code bridge
+  // runs the Claude Agent SDK, so a normal lane IS a Claude model — but a session pointed at a
+  // non-Claude base URL/model gets a legible line, not a bogus token report. Only assert this
+  // when we actually know a model (else a fresh empty session would wrongly trip the gate).
+  const anyClaude = claudeish(sessionModel) || sum.per.some((r) => claudeish(r.model))
+  if (!anyClaude && (sessionModel || sum.turns)) return 'usage reporting is available on Claude models only'
+  if (!sum.turns) return 'usage · no completed turns yet this session'
+  const fmtTok = (n) => n >= 1e6 ? (n / 1e6).toFixed(1) + 'M' : n >= 1e3 ? (n / 1e3).toFixed(1) + 'k' : String(n)
+  const perStr = sum.per.map((r) => {
+    const cch = r.cached ? ` (${fmtTok(r.cached)} cached)` : ''
+    return `${prettyModelId(r.model)}: ${fmtTok(r.in)} in${cch} / ${fmtTok(r.out)} out`
+  }).join(' · ')
+  const total = sum.per.length > 1 ? ` · total ${fmtTok(sum.totalIn)} in / ${fmtTok(sum.totalOut)} out` : ''
+  const cost = sum.haveCost ? ` · ~$${sum.totalCost.toFixed(2)} est` : ''
+  const turns = `${sum.turns} turn${sum.turns === 1 ? '' : 's'}`
+  return `usage · ${turns} · ${perStr}${total}${cost} · tokens + cost only (no plan/rate-limit meters)`
+}

package/flow-review-reflect.mjs

@@ -0,0 +1,115 @@
+/* ─────────────────────────────────────────────────────────────
+   flow-review-reflect.mjs — the BOUNDED reflection governor for the
+   verifying reviewer lane (heist E1 + P3).
+   Spec: docs/specs/2026-07-02-e1p3-verifying-reviewer.md
+   Parents: Emergent steal E1 (self-test loop) + Cursor steal P3 (Bugbot).
+
+   The existing adversarial reviewer (bridge/flow-review.mjs) runs the slice
+   once and emits a verdict. E1 makes that a bounded, budget-capped SELF-TEST
+   loop: the reviewer may dig across several rounds (re-run, hit edge cases,
+   reproduce the acceptance proof harder) — but it MUST stop at a hard ceiling
+   and hand off to the humans, never loop unbounded. That unbounded self-heal
+   loop is exactly Emergent's most-hated wound (billing a runaway fix-loop back
+   to the user); this governor is the structural guarantee we never have it.
+
+   Two independent stop conditions, both enforced here (not prompted):
+     • ROUND ceiling  — never more than maxRounds hunt rounds (anti-Emergent).
+     • BUDGET ceiling — never spend past the room/lane cap (nexos steal #1 /
+       cost-guard; the review lane SPENDS inference, so it inherits N1).
+
+   Pure + deterministic — the whole loop-control decision in one function so it
+   is unit-testable without a live Flow room (the reviewable seam; the live
+   wiring into flow-review.mjs + bridge.mjs is the held integration slice,
+   same split that shipped S5's reviewGateDecision).
+
+   P3 (pair co-adjudication): when the loop stops, the outcome is not the end —
+   `surfaceToPair` says the verdict/findings must go to the ROOM for the two
+   humans + Pool to challenge, rather than silently auto-driving the gate. A
+   solo Bugbot's verdict is final; ours is a prompt for the pair to argue.
+   ───────────────────────────────────────────────────────────── */
+
+export const REVIEW_DEFAULTS = Object.freeze({
+  maxRounds: 3,          // hard hunt ceiling — bounded, never unbounded (anti-Emergent)
+})
+
+/**
+ * Decide whether the reviewer's self-test loop continues or stops, and why.
+ *
+ * @param {object}  s
+ * @param {number}  s.round            1-based current hunt round (1 = first pass)
+ * @param {number} [s.maxRounds]       hard ceiling (default REVIEW_DEFAULTS.maxRounds)
+ * @param {number} [s.spentTokens]     tokens the review lane has spent so far
+ * @param {number|null} [s.budgetCap]  the room/lane token cap (null = uncapped)
+ * @param {boolean} s.foundFailure     this round produced a CONCRETE, reproduced failure
+ * @param {boolean} [s.exhausted]      the reviewer reports it has nothing left to check
+ * @returns {{ stop: boolean, action: 'reject'|'pass'|'surface'|'continue',
+ *             surfaceToPair: boolean, reason: string }}
+ *   action:
+ *     'reject'   — a concrete failure was found; stop, verdict = REJECT
+ *     'pass'     — checks exhausted with no failure; stop, verdict = PASS
+ *     'surface'  — a ceiling (budget or rounds) was hit inconclusively; stop,
+ *                  hand the partial findings to the humans (no guess, no loop)
+ *     'continue' — keep hunting (still under both ceilings, not yet concluded)
+ *   surfaceToPair — true whenever the loop STOPS (P3: every terminal outcome is
+ *                   a prompt for the pair, not an automatic gate action).
+ */
+export function reviewReflectionDecision ({
+  round,
+  maxRounds = REVIEW_DEFAULTS.maxRounds,
+  spentTokens = 0,
+  budgetCap = null,
+  foundFailure = false,
+  exhausted = false,
+} = {}) {
+  const r = Number.isFinite(round) ? round : 1
+  const cap = Number.isFinite(maxRounds) && maxRounds > 0 ? maxRounds : REVIEW_DEFAULTS.maxRounds
+
+  // 1. A concrete, reproduced failure ends the hunt immediately — default-to-
+  //    reject is the whole point; no value in more rounds once it's broken.
+  if (foundFailure) {
+    return { stop: true, action: 'reject', surfaceToPair: true,
+      reason: 'concrete failure reproduced — verdict REJECT' }
+  }
+
+  // 2. BUDGET ceiling (nexos #1 / cost-guard). Fail-closed: the moment spend
+  //    reaches the cap, STOP and hand off — never spend the next unit. Checked
+  //    before the round ceiling because money is the harder limit.
+  if (budgetCap != null && Number.isFinite(budgetCap) && spentTokens >= budgetCap) {
+    return { stop: true, action: 'surface', surfaceToPair: true,
+      reason: `review budget cap reached (${spentTokens}/${budgetCap} tokens) — surfacing partial findings to the pair` }
+  }
+
+  // 3. Reviewer says it has checked everything and found nothing — verdict PASS.
+  if (exhausted) {
+    return { stop: true, action: 'pass', surfaceToPair: true,
+      reason: 'checks exhausted, no failure reproduced — verdict PASS' }
+  }
+
+  // 4. ROUND ceiling (anti-Emergent). Reached the last allowed round without a
+  //    conclusion → surface to the humans rather than guess or loop forever.
+  if (r >= cap) {
+    return { stop: true, action: 'surface', surfaceToPair: true,
+      reason: `reached the ${cap}-round hunt ceiling without a conclusion — surfacing to the pair (not looping)` }
+  }
+
+  // 5. Under both ceilings, not yet concluded → dig another round.
+  return { stop: false, action: 'continue', surfaceToPair: false,
+    reason: `round ${r}/${cap}, under budget — continue hunting` }
+}
+
+/**
+ * Format a stopped review outcome as the room-facing co-adjudication prompt
+ * (P3). Not the gate action itself — a message that invites the two humans +
+ * Pool to challenge the reviewer before the verdict is treated as final.
+ */
+export function pairAdjudicationPrompt ({ action, reason, findings = [], taskKey = '' } = {}) {
+  const head = {
+    reject:  `The reviewer REJECTED ${taskKey || 'this slice'}.`,
+    pass:    `The reviewer PASSED ${taskKey || 'this slice'}.`,
+    surface: `The reviewer could not conclude on ${taskKey || 'this slice'}.`,
+  }[action] || `Review outcome for ${taskKey || 'this slice'}.`
+  const body = findings.length
+    ? '\n' + findings.map((f) => `  • ${f}`).join('\n')
+    : (reason ? `\n  ${reason}` : '')
+  return `${head}${body}\n\nYou two decide — do you agree? Challenge it, or accept.`
+}

package/flow-review.mjs

@@ -12,6 +12,7 @@
 import { execFileSync } from 'node:child_process'
 import { TASK_STATUS } from './flow-task-graph.mjs'
 import { removeFlowWorktree } from './flow-worktree.mjs'
+import { reviewReflectionDecision, REVIEW_DEFAULTS } from './flow-review-reflect.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.
@@ -26,7 +27,9 @@ export const FLOW_REVIEWER_PROMPT = [
 
   '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 YOUR VERDICT BY WRITING FLOW_REVIEW.json. Do NOT call mark_flow_done or ExitPlanMode (they hang here). As your LAST action, use the Write tool with file_path "FLOW_REVIEW.json" and content = a single JSON object { "pass": <boolean>, "reasons": ["<specific finding>", ...], "taskKey": "<the slice you reviewed>" }. `pass: false` reverts the reviewed slice so it rebuilds. The content of FLOW_REVIEW.json must be ONLY that JSON object (no prose, no markdown fences). Do not edit the slice — you review, you do not fix.',
+  'YOU GET BOUNDED HUNT ROUNDS, NOT ONE GLANCE. You may be asked to dig again — up to a hard ceiling of rounds. A green happy-path on round 1 is NOT a pass; use the next round to hunt harder (edge cases, the reload, the second click, concurrent use, the error path). You only stop early two ways: you reproduce a concrete FAILURE (emit pass:false — that ends it, the slice reverts), OR you have genuinely EXHAUSTED your checks and found nothing (emit pass:true AND exhausted:true — that ends it, the slice passes). If you still have angles left to try, emit pass:true and leave exhausted false/absent — you will be asked to dig one more round until the ceiling, at which point the inconclusive result is handed to the two humans to decide (never an unbounded self-loop).',
+
+  'EMIT YOUR VERDICT BY WRITING FLOW_REVIEW.json. Do NOT call mark_flow_done or ExitPlanMode (they hang here). As your LAST action, use the Write tool with file_path "FLOW_REVIEW.json" and content = a single JSON object { "pass": <boolean>, "reasons": ["<specific finding>", ...], "taskKey": "<the slice you reviewed>", "exhausted": <boolean, optional — true only when you have nothing left to check> }. `pass: false` reverts the reviewed slice so it rebuilds. The content of FLOW_REVIEW.json must be ONLY that JSON object (no 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
@@ -43,7 +46,57 @@ export function parseReviewVerdict (raw) {
   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 }
+  // E1 (bounded self-test): `exhausted` is an OPTIONAL third signal — true only when the
+  // reviewer reports it has nothing left to check. Absent/non-boolean → false (keep hunting
+  // until the round ceiling). Never throws on its absence; it's additive to the old contract.
+  const exhausted = obj.exhausted === true
+  return { pass: obj.pass, reasons, exhausted }
+}
+
+// E1 — map a parsed review verdict into the two governor inputs. A concrete FAILURE
+// (pass:false) is a reproduced break → foundFailure. A pass is only conclusive when the
+// reviewer says it EXHAUSTED its checks; a bare pass:true means "happy path held, more to
+// hunt" → keep going until the round ceiling. Pure; the seam the loop drives on.
+export function reviewVerdictToReflection (verdict) {
+  const v = verdict || {}
+  return {
+    foundFailure: v.pass === false,
+    exhausted: v.pass === true && v.exhausted === true,
+  }
+}
+
+// E1+A1/A2 — the BOUNDED reviewer loop. Drives the adversarial reviewer across up to
+// `maxRounds` hunt rounds, consulting reviewReflectionDecision between rounds, and stops at
+// the FIRST terminal outcome (reject on a concrete failure, pass on exhaustion, or SURFACE
+// when a ceiling — rounds or budget — is hit inconclusively). Pure over two injected effects
+// so it's unit-testable without a live Flow room (the S5 split):
+//   • runRound(round)  → Promise<parsed verdict {pass,reasons,exhausted}> — spend one round
+//   • getSpent()       → number — the review lane's tokens spent so far (flow-budget ledger)
+// N1 fail-closed: the budget is checked BEFORE each round is spent, so a review lane at/over
+// its cap SURFACES without ever spending the next round (never runs the bill up, anti-Emergent).
+// Returns { action, surfaceToPair, reason, rounds, verdict } — `rounds` = rounds actually run.
+export async function runBoundedReview ({ maxRounds, budgetCap = null, getSpent = () => 0, runRound }) {
+  if (typeof runRound !== 'function') throw new Error('runBoundedReview needs a runRound(round) function')
+  const cap = Number.isFinite(maxRounds) && maxRounds > 0 ? maxRounds : REVIEW_DEFAULTS.maxRounds
+  const capped = budgetCap != null && Number.isFinite(budgetCap)
+  for (let round = 1; ; round++) {
+    // N1 fail-closed pre-gate: never SPEND another review round once the cap is reached.
+    const spentBefore = getSpent()
+    if (capped && spentBefore >= budgetCap) {
+      const d = reviewReflectionDecision({
+        round, maxRounds: cap, spentTokens: spentBefore, budgetCap,
+        foundFailure: false, exhausted: false,
+      })
+      return { ...d, rounds: round - 1, verdict: null }
+    }
+    const verdict = await runRound(round)
+    const decision = reviewReflectionDecision({
+      round, maxRounds: cap, spentTokens: getSpent(), budgetCap,
+      ...reviewVerdictToReflection(verdict),
+    })
+    if (decision.stop) return { ...decision, rounds: round, verdict }
+    // else action==='continue' — under both ceilings, not yet concluded → dig another round.
+  }
 }
 
 // Gate decision over a task's verdicts (≥1 reviewer). Accept iff EVERY verdict passes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.154",
+  "version": "0.7.155",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -23,6 +23,7 @@
     "flow-preview.mjs",
     "flow-review.mjs",
     "flow-review-gate.mjs",
+    "flow-review-reflect.mjs",
     "flow-assembly.mjs",
     "flow-budget.mjs",
     "flow-context-store.mjs",