thinkpool-pair 0.7.153 → 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)
@@ -81,10 +82,10 @@ const flowRedispatch = new Map()
 // wave BEFORE overrun. Lives bridge-side because waves dispatch across separate
 // broadcasts; without persistent state the cap can never bite.
 const flowBudgets = new Map()
-import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, CROSSROOM, formatPairRoster, crossRoomPostDecision, formatRoomNow } from './cross-terminal.mjs'
+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
@@ -1593,16 +1651,20 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
         },
         async (args) => {
           const okText = (t) => ({ content: [{ type: 'text', text: t }] })
+          const now = Date.now()
           const gate = spawnDecision({
             hop: entry.hop || 0,
-            spawnCount: entry.spawnCount || 0,
+            spawnTimes: entry.spawnTimes || [],                                     // sliding-window burst breaker (replenishes on wall-clock, not on a human turn)
+            now,
             spawnedLive: [...sessions.values()].filter((s) => s.spawnedBy).length,  // dispatch budget counts ONLY spawned lanes
             totalLive: sessions.size + terms.size,                                  // machine cap counts everything
             plan: ownerPlan,                                                        // Free 3 / Plus 6 dispatch ceiling
             disabled: process.env.TP_SPAWN_OFF === '1',
           })
           if (!gate.ok) return okText(gate.reason)
-          entry.spawnCount = (entry.spawnCount || 0) + 1
+          // Record this spawn, pruning timestamps that have already left the window
+          // (identical predicate to recentSpawnCount) so the array can't grow unbounded.
+          entry.spawnTimes = [...(entry.spawnTimes || []).filter((t) => Number.isFinite(t) && t > now - SPAWN.windowMs), now]
           const newId = randomUUID()
           const newRef = String(newId).slice(0, 8)
           const fromRef = String(id).slice(0, 8)
@@ -1623,7 +1685,7 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
           if (args?.task) {
             // One hop deep: the spawned lane cannot spawn/post onward until a person
             // speaks to it (code-turn resets hop to 0). Mirrors the Tier C injection.
-            ne.hop = 1; ne.peekCount = 0; ne.postCount = 0; ne.spawnCount = 0
+            ne.hop = 1; ne.peekCount = 0; ne.postCount = 0; ne.spawnTimes = []
             const msg = `[Task from terminal ${fromRef}'s agent — relayed via ThinkPool cross-terminal; you are a fresh lane it opened for you]\n${args.task}`
             const evt = { kind: 'you', text: msg, by: `terminal ${fromRef} (agent)`, crosspost: true }
             stampEvent(evt); pushLog(ne, evt); bcast('code-event', { term: newId, evt })
@@ -2266,7 +2328,7 @@ channel
     s.postCount = 0
     s.pairPeekCount = 0   // cross-room read budget resets with the in-room ones (Tier 1)
     s.crossRoomPostCount = 0   // Tier 3 cross-room post budget resets on a real human turn
-    s.spawnCount = 0   // EN-M3 — spawn budget MUST reset too, else turn 2+ can never spawn a lane
+    s.spawnTimes = []  // EN-M3 — a real human turn clears the spawn burst window instantly (the window also self-replenishes on wall-clock for UNATTENDED cascades that never reach this handler)
     s.hop = 0
     s.roomHop = 0   // a human turn is room-hop 0 — clears any injected cross-room hop depth
     const text = String(payload.text)
@@ -2330,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/cross-terminal.mjs

@@ -227,15 +227,25 @@ export const crossPostNeedsCard = ({ mode = 'default', spawnedByMe = false } = {
 //     own terminals, and the human's terminals never eat the dispatch budget. Under
 //     BYOK-only the tokens are the user's, so this is feature-shaping + machine
 //     safety, NOT a ThinkPool-COGS control.
-//   • perTurnCap — a per-turn runaway breaker (mirrors PEEK/CROSSPOST)
+//   • burst window — a SLIDING-window runaway breaker: ≤ perWindowCap spawns per
+//     rolling windowMs. Replaces the old per-HUMAN-turn cap, which starved an
+//     UNATTENDED conductor: agent turns woken by Monitor/task notifications never
+//     traverse the 'code-turn' handler that reset the per-turn counter, so a cascade
+//     that spent its 4 spawns could NEVER spawn again until a person typed. The
+//     window replenishes on wall-clock alone — no turn boundary required — while a
+//     real human turn still clears it instantly (the reset point is unchanged).
 // The caller measures: spawnedLive (live sessions with spawnedBy set), totalLive
-// (sessions.size + terms.size), and resolves `plan` from the room owner.
+// (sessions.size + terms.size), resolves `plan` from the room owner, and passes the
+// lane's recent spawn timestamps (`spawnTimes`) plus the current clock (`now`) — so
+// this stays a PURE function (no Date.now inside; the clock is injected, like
+// spawnCount was before).
 export const SPAWN = {
-  maxHop: 1,            // human turn = hop 0; a spawned/injected lane = hop ≥ 1, CANNOT spawn onward
-  perTurnCap: 4,        // spawn_terminal calls allowed per turn
-  freeMaxSpawned: 3,    // Free plan dispatch ceiling (concurrent spawned lanes)
-  plusMaxSpawned: 6,    // Plus plan dispatch ceiling
-  machineMax: 10,       // hard cap on TOTAL live lanes (the laptop/runaway backstop)
+  maxHop: 1,               // human turn = hop 0; a spawned/injected lane = hop ≥ 1, CANNOT spawn onward
+  perWindowCap: 4,         // spawn_terminal calls allowed per rolling window (burst breaker)
+  windowMs: 10 * 60 * 1000, // sliding window over which perWindowCap applies (10 min)
+  freeMaxSpawned: 3,       // Free plan dispatch ceiling (concurrent spawned lanes)
+  plusMaxSpawned: 6,       // Plus plan dispatch ceiling
+  machineMax: 10,          // hard cap on TOTAL live lanes (the laptop/runaway backstop)
 }
 
 // Plan → dispatch ceiling. Anything not 'plus' is treated as Free (the safe default).
@@ -244,14 +254,24 @@ export const maxSpawnedFor = (plan, limits = SPAWN) => {
   return plan === 'plus' ? o.plusMaxSpawned : o.freeMaxSpawned
 }
 
-export const spawnDecision = ({ hop = 0, spawnCount = 0, spawnedLive = 0, totalLive = 0, plan = 'free', disabled = false } = {}, limits = SPAWN) => {
+// Count spawn timestamps still inside the sliding window ending at `now`. Timestamps
+// strictly older than `now - windowMs` have replenished (fallen out of the window).
+// Non-finite entries are ignored defensively. Exported so the bridge can prune its
+// stored spawnTimes with the identical predicate (no unbounded growth).
+export const recentSpawnCount = (spawnTimes, now, windowMs = SPAWN.windowMs) =>
+  (Array.isArray(spawnTimes) ? spawnTimes : []).filter((t) => Number.isFinite(t) && t > now - windowMs).length
+
+export const spawnDecision = ({ hop = 0, spawnTimes = [], now = 0, spawnedLive = 0, totalLive = 0, plan = 'free', disabled = false } = {}, limits = SPAWN) => {
   const o = { ...SPAWN, ...(limits || {}) }
   if (disabled) return { ok: false, reason: 'Spawning terminals is disabled in this room.' }
   if (hop >= o.maxHop) return { ok: false, reason: 'Spawn limit reached — a terminal reached via cross-terminal cannot itself open further terminals; a person must open the next lane.' }
   if (totalLive >= o.machineMax) return { ok: false, reason: `Room is at the machine cap (${o.machineMax} live lanes) — close one before opening another.` }
   const cap = maxSpawnedFor(plan, o)
   if (spawnedLive >= cap) return { ok: false, reason: `Dispatch ceiling reached (${cap} lane${cap === 1 ? '' : 's'} on the ${plan} plan)${plan !== 'plus' ? ` — Plus raises it to ${o.plusMaxSpawned}.` : '.'} Close a dispatched lane to open another.` }
-  if (spawnCount >= o.perTurnCap) return { ok: false, reason: `Spawn limit reached for this turn (${o.perTurnCap}).` }
+  if (recentSpawnCount(spawnTimes, now, o.windowMs) >= o.perWindowCap) {
+    const mins = Math.round(o.windowMs / 60000)
+    return { ok: false, reason: `Spawn burst limit reached (${o.perWindowCap} in ${mins} min) — this replenishes as the window slides forward, or instantly when a person types into this lane.` }
+  }
   return { ok: true }
 }
 

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.153",
+  "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",