thinkpool-pair 0.7.245 → 0.7.247

package/bridge.mjs

@@ -54,9 +54,11 @@ import { withMcpSessionFactory } from './codex-mcp-http.mjs'
 import { startStructuredSession } from './runtime-session.mjs'
 import { defaultStructuredMode, shouldDeferStructuredRuntime, structuredRuntimeForCommand, structuredRuntimeMetadata, structuredRuntimeSupportsMode } from './runtime-registry.mjs'
 import { probeHermesRuntime } from './hermes-probe.mjs'
+import { hermesRequiredMcpTools, hermesRoleFor } from './hermes-policy.mjs'
 import { canonicalRoomFilePath, waitForNativeImages } from './codex-images.mjs'
 import { createManagedLaneWorktree, removeManagedLaneWorktree } from './lane-worktree.mjs'
 import { commandOnPath } from './agent-detect.mjs'
+import { requiresSdkAdmission, sdkSmokePassed } from './sdk-admission.mjs'
 
 const STRUCTURED_MODES = new Set(['default', 'acceptEdits', 'plan', 'review', 'bypassPermissions'])
 import { FLOW_CONDUCTOR_PROMPT, FLOW_LANE_PROMPT, FLOW_CODEX_CONDUCTOR_PROMPT, FLOW_CODEX_LANE_PROMPT, buildConductorEnv, assembleCrossWaveContext, buildLanePrompt } from './flow-conductor.mjs'
@@ -81,6 +83,7 @@ function stopFlowPreviews (flowId, laneId = null) {
 }
 import { FLOW_REVIEWER_PROMPT, FLOW_CODEX_REVIEWER_PROMPT, revertLane, parseReviewVerdict, reviewVerdictToReflection } from './flow-review.mjs'
 import { reviewGateDecision } from './flow-review-gate.mjs'
+import { readReviewFile, runReviewCheck } from './review-check.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'
@@ -109,7 +112,7 @@ import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSP
 import { dispatchPendingRecap, recoverInterruptedTurn, recoverMissingResumeOnce, sendInterruptedContinue, shouldAttemptNativeResume, supersedeInterruptedResume } from './interrupted-resume.mjs'
 import { turnInFlight } from './update-gate.mjs'
 import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames, appendDurableEvents, seedDurableEvents, readDurablePage, readDurableOldestSeq, hasDurableArchive, servesHistoryPage } from './session-store.mjs'
-import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks, usageReportLine, codexUsageReportLine, buildRecapFromLog, RECAP_CAP, trimmedBeforeSeq, firstSeq } from './event-id.mjs'
+import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks, ImageEventQueue, imageQueueConfig, uploadCodeImage as uploadCodeImageRequest, usageReportLine, codexUsageReportLine, buildRecapFromLog, RECAP_CAP, trimmedBeforeSeq, firstSeq } from './event-id.mjs'
 import { classifyCodeEvent, unknownCodeEventNotice } from './code-event-contract.mjs'
 import { fetchPairControlDeliveryAuthority } from './pair-control-authority.mjs'
 import { SIDE_HANDOFF_PROMPT, SIDE_ROLE_PROMPT, appendSideContext, assistantTextSince, sideContextBlock, sideSnapshot } from './side-lane.mjs'
@@ -122,6 +125,7 @@ import { buildTerminalRolePrompt, HERMES_VISIBLE_WORKER_FALLBACK_RULE } from './
 // Override with TP_SUPABASE_URL / TP_SUPABASE_ANON if you ever need to.
 const SUPABASE_URL  = process.env.TP_SUPABASE_URL  || DEFAULT_SUPABASE_URL
 const WEB_BASE      = process.env.TP_WEB_BASE      || 'https://thinkpool.io'
+const IMAGE_QUEUE_CONFIG = imageQueueConfig()
 
 // The anon key is RESOLVED, not baked. It used to be a string literal here, and
 // that literal now sits in 224 published tarballs on 224 users' laptops: disable
@@ -361,10 +365,9 @@ if ((!argv[0] || argv[0] === 'setup') && process.stdin.isTTY) {
 // The SDK tracks a caret (^0.3.x), so a restart can auto-pull a NEW SDK, and its
 // interrupt/turn API has broken between 0.3.x minors before. Smoke-test the API
 // surface (offline, no tokens) the FIRST time a given SDK version is seen, so a
-// bad one is caught + surfaced loudly (stderr + the announce banner) instead of
-// silently breaking turns. sdkStatus feeds the announce. Fully guarded — a check
-// error never blocks serving.
-const SMOKE_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), 'sdk-smoke.mjs')
+// bad one is caught before a room can serve turns. Account/service commands remain
+// available so the operator can repair the installation.
+const SMOKE_PATH = process.env.TP_SDK_SMOKE_PATH || path.join(path.dirname(fileURLToPath(import.meta.url)), 'sdk-smoke.mjs')
 let sdkStatus = { ok: null, version: 'unknown', reason: '' }
 function currentSdkVersion() {
   try {
@@ -382,7 +385,7 @@ function runSmoke() {
   catch (e) { return (e.stdout || '').toString().trim() || `SMOKE:FAIL:${currentSdkVersion()}:${e.code === 'ETIMEDOUT' ? 'timeout' : (e.message || 'run error').slice(0, 80)}` }
 }
 if (argv[0] === 'verify-sdk') {
-  const out = runSmoke(); console.log(out); process.exit(/^SMOKE:PASS/.test(out) ? 0 : 1)
+  const out = runSmoke(); console.log(out); process.exit(sdkSmokePassed(out) ? 0 : 1)
 }
 function checkSdkCompat() {
   const dir = path.join(os.homedir(), '.thinkpool-pair'); const okFile = path.join(dir, 'sdk-ok')
@@ -397,10 +400,9 @@ function checkSdkCompat() {
   } else {
     sdkStatus = { ok: false, version: (m && m[2]) || version, reason: (m && m[3]) || 'unknown' }
     try { fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(path.join(dir, 'sdk-bad'), `${sdkStatus.version}: ${sdkStatus.reason}`) } catch { /* noop */ }
-    process.stderr.write(`\n  ⚠⚠ agent SDK v${sdkStatus.version} FAILED the compatibility smoke test — ${sdkStatus.reason}.\n  ⚠⚠ turns may misbehave. Pin a known-good SDK + restart:\n     bridge/package.json → "@anthropic-ai/claude-agent-sdk": "<good version>", then republish + Restart & update.\n`)
+    process.stderr.write(`\n  ⛔ agent SDK v${sdkStatus.version} FAILED the compatibility smoke test — ${sdkStatus.reason}.\n  ⛔ refusing to serve agent turns. Repair or pin a known-good SDK, then restart.\n`)
   }
 }
-try { checkSdkCompat() } catch (e) { process.stderr.write(`  ⚠ SDK smoke check skipped: ${e.message}\n`) }
 
 if (!argv[0] || argv[0].startsWith('-')) { const { runAccount } = await import('./account.mjs'); await runAccount(SUPABASE_URL, SUPABASE_ANON) }
 
@@ -418,6 +420,10 @@ if (!/^[A-Z0-9_-]{2,32}$/.test(room)) {
   console.error(`refused: invalid room code ${JSON.stringify(room)} (expected 2–32 alphanumerics, dash, or underscore)`)
   process.exit(1)
 }
+if (requiresSdkAdmission(argv)) {
+  checkSdkCompat()
+  if (!sdkStatus.ok) process.exit(1)
+}
 // ── Supervisor mode (--supervise / --keep-alive): keep the bridge alive across
 // crashes. We re-exec ourselves without the flag and respawn the child on any
 // non-clean exit with exponential backoff. Zero-dependency, cross-platform. With
@@ -1503,38 +1509,30 @@ watchOutbox(MOCKUP_OUTBOX, () => [...sessions.keys()][0] || attachedId || [...te
 // { type:'image', path } ref. The persisted log + every replay then carry the path,
 // never base64; the web client mints a signed URL on render (structured.jsx, same
 // as the mockup thumbs). Spec: docs/specs/2026-06-26-code-agent-images.md
-async function uploadCodeImage(term, cid, im) {
-  const headers = { 'Content-Type': 'application/json' }
-  if (codeAuthToken) headers.Authorization = `Bearer ${codeAuthToken}`
-  const res = await fetch(`${WEB_BASE}/api/code-image`, {
-    method: 'POST',
-    headers,
-    body: JSON.stringify({ code: room, term, cid, idx: im.idx, mediaType: im.mediaType, b64: im.b64 }),
+async function uploadCodeImage(term, cid, im, activeUploads) {
+  return uploadCodeImageRequest({
+    webBase: WEB_BASE,
+    room,
+    authToken: codeAuthToken,
+    term,
+    cid,
+    image: im,
+    timeoutMs: IMAGE_QUEUE_CONFIG.uploadTimeoutMs,
+    activeUploads,
   })
-  if (!res.ok) throw new Error(`code-image ${res.status}`)
-  const { path } = await res.json()
-  if (!path) throw new Error('code-image: no path')
-  return path
 }
-// Defer an image-bearing tool_result behind a per-session upload chain (preserves
-// arrival order among images), then log + broadcast the URL-only event through the
-// normal path. pushLog is the single seq-assignment point, so the deferred event
-// still gets a contiguous seq at chain-resolution time; its ts was stamped at
-// arrival, so it sorts into place. On upload failure the block degrades to the same
-// render-safe text placeholder — base64 is NEVER logged, broadcast, or persisted.
+// Every structured event enters one per-session emission boundary. With no upload in
+// flight the fast path stays synchronous; after an image, later tool/results wait in
+// runtime order. The queue owns timeout, raw-base64 budgets, and teardown degradation.
 function deferImageEvent(entry, id, evt, imgs, emitTail) {
-  entry.imageChain = (entry.imageChain || Promise.resolve()).then(async () => {
-    for (const im of imgs) {
-      try {
-        const path = await uploadCodeImage(id, evt.cid, im)
-        evt.content[im.idx] = { type: 'image', path, mediaType: im.mediaType }
-      } catch (e) {
-        process.stderr.write(`\n  ◇ screenshot upload failed (${e?.message || e}).\n`)
-        evt.content[im.idx] = { type: 'text', text: '[screenshot omitted — upload failed]' }
-      }
-    }
-    emitTail(evt)
-  }).catch(() => {})
+  entry.imageQueue ||= new ImageEventQueue({
+    maxPending: IMAGE_QUEUE_CONFIG.maxPending,
+    maxBytes: IMAGE_QUEUE_CONFIG.maxBytes,
+    upload: (queuedEvt, im, activeUploads) => uploadCodeImage(id, queuedEvt.cid, im, activeUploads),
+    onUploadError: (e) => process.stderr.write(`\n  ◇ screenshot upload failed (${e?.message || e}).\n`),
+    onOverload: ({ maxPending, maxBytes }) => process.stderr.write(`\n  ◇ screenshot omitted (image queue cap: ${maxPending} pending / ${maxBytes} encoded bytes).\n`),
+  })
+  entry.imageQueue.enqueue(evt, imgs, emitTail)
 }
 // Fire-and-forget: drop a closed term's screenshots from Storage so they don't
 // outlive the room (COGS). Per-term scope — never touches a sibling term's images.
@@ -1731,6 +1729,12 @@ function restoredTurnOpen(log) {
 // minutes-scale. Plain `git worktree list` output (path · sha · [branch]) is the
 // readable shape an agent acts on. Fail-quiet [] — a snapshot must never break a turn.
 const _wtCache = new Map() // cwd → { at, list }
+function immutableReviewSnapshot(cwd, taskKey = 'parent') {
+  const source = path.resolve(cwd || process.cwd())
+  const sha = execFileSync('git', ['-C', source, 'rev-parse', '--verify', 'HEAD^{commit}'], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+  if (!/^[0-9a-f]{40}$/i.test(sha)) throw new Error('parent review source has no immutable HEAD')
+  return { taskKey, cwd: source, sha }
+}
 function worktreeSnapshot(cwd) {
   const key = cwd || process.cwd()
   const hit = _wtCache.get(key)
@@ -1748,7 +1752,7 @@ function worktreeSnapshot(cwd) {
 // relay STRUCTURED events. onEvent → broadcast `code-event` + print locally +
 // persist to the host file; tool calls round-trip through the perm card; the
 // rolling log replays to joiners and survives bridge restarts (session-store).
-function openStructured({ id, runtime = 'claude', model, models, effort, resume, log, commands, mode, spawnedBy, spawnDepth, cascadeRole, hop, sideParent, sideTask, pendingSideContexts, rolePrompt, flowSessionId, flowTaskKey, flowRole, flowReviewTarget, flowReviewTargets, flowReviewRound, dispatchBaseSha, revertTarget, cwd, managedWorktree, reviewSliceRoots, openedAt, defer, provider, carryRecap, lastUsage }) {
+function openStructured({ id, runtime = 'claude', model, models, effort, resume, log, commands, mode, spawnedBy, spawnDepth, cascadeRole, hop, sideParent, sideTask, pendingSideContexts, rolePrompt, sliceType, flowSessionId, flowTaskKey, flowRole, flowReviewTarget, flowReviewTargets, flowReviewSnapshots, flowReviewRound, dispatchBaseSha, revertTarget, cwd, managedWorktree, reviewSliceRoots, openedAt, defer, provider, carryRecap, lastUsage }) {
   if (sessions.has(id)) return
   runtime = structuredRuntimeMetadata(runtime) ? runtime : 'claude'
   // No explicit mode → a sensible default per runtime (see defaultModeForRuntime):
@@ -1801,9 +1805,11 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       ? (laneModel || null)
       : (laneModel || providerNameMap()[provider] || provider),
     provider: provider || null, spawnedBy: spawnedBy || undefined, spawnDepth: structuralDepth, cascadeRole: cascadeRole === 'conductor' || cascadeRole === 'worker' ? cascadeRole : null, hop: initialHop, sideParent: sideParent || undefined, sideTask: sideTask || undefined, pendingSideContexts: Array.isArray(pendingSideContexts) ? pendingSideContexts.filter(Boolean).slice(-4) : [], flowSessionId: flowSessionId || null, flowTaskKey: flowTaskKey || null, cwd: cwd || null, managedWorktree: managedWorktree || null,
+    sliceType: sliceType === 'review' ? 'review' : null,
     flowRole: flowRole || (flowSessionId ? (flowTaskKey ? ((flowReviewTargets?.length || reviewSliceRoots?.length) ? 'reviewer' : 'builder') : 'conductor') : null),
     flowReviewTarget: flowReviewTarget || null,
     flowReviewTargets: Array.isArray(flowReviewTargets) && flowReviewTargets.length ? flowReviewTargets.filter(Boolean) : (flowReviewTarget ? [flowReviewTarget] : []),
+    flowReviewSnapshots: Array.isArray(flowReviewSnapshots) ? flowReviewSnapshots.filter((item) => item?.taskKey && item?.sha && item?.cwd) : [],
     flowReviewRound: Number.isInteger(flowReviewRound) && flowReviewRound >= 0 ? flowReviewRound : 0,
     dispatchBaseSha: dispatchBaseSha || null,
     revertTarget: revertTarget || null,
@@ -2050,7 +2056,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
   // restart. Without this, sessionData omitted it → on restart the resumed session
   // re-launched on the host default (Opus) regardless of the last switch, and the
   // switch looked like it "never changed the model" (Max 2026-07-02). Restored below.
-  const sessionData = () => ({ sessionId: entry.session?.sessionId || null, runtime: entry.runtime, log: entry.log, commands: entry.commands, mode: entry.mode, effort: entry.effort, model: entry.model || null, models: entry.runtime === 'hermes' ? (entry.models || []) : undefined, provider: entry.provider || null, spawnedBy: entry.spawnedBy, spawnDepth: entry.spawnDepth || 0, cascadeRole: entry.cascadeRole || null, hop: entry.hop || 0, sideParent: entry.sideParent, sideTask: entry.sideTask, pendingSideContexts: entry.pendingSideContexts, flowSessionId: entry.flowSessionId, flowTaskKey: entry.flowTaskKey, flowRole: entry.flowRole || null, flowReviewTargets: entry.flowReviewTargets || [], flowReviewRound: entry.flowReviewRound || 0, dispatchBaseSha: entry.dispatchBaseSha || null, cwd: entry.cwd, managedWorktree: entry.managedWorktree, rolePrompt: entry.rolePrompt, flowReviewTarget: entry.flowReviewTarget || null, revertTarget: entry.revertTarget || null, reviewSliceRoots: entry.reviewSliceRoots || [], openedAt: entry.openedAt || null, lastUsage: entry.lastUsage || null, carryRecap: entry.pendingRecap || null })
+  const sessionData = () => ({ sessionId: entry.session?.sessionId || null, runtime: entry.runtime, log: entry.log, commands: entry.commands, mode: entry.mode, effort: entry.effort, model: entry.model || null, models: entry.runtime === 'hermes' ? (entry.models || []) : undefined, provider: entry.provider || null, spawnedBy: entry.spawnedBy, spawnDepth: entry.spawnDepth || 0, cascadeRole: entry.cascadeRole || null, hop: entry.hop || 0, sideParent: entry.sideParent, sideTask: entry.sideTask, pendingSideContexts: entry.pendingSideContexts, sliceType: entry.sliceType, flowSessionId: entry.flowSessionId, flowTaskKey: entry.flowTaskKey, flowRole: entry.flowRole || null, flowReviewTargets: entry.flowReviewTargets || [], flowReviewSnapshots: entry.flowReviewSnapshots || [], flowReviewRound: entry.flowReviewRound || 0, dispatchBaseSha: entry.dispatchBaseSha || null, cwd: entry.cwd, managedWorktree: entry.managedWorktree, rolePrompt: entry.rolePrompt, flowReviewTarget: entry.flowReviewTarget || null, revertTarget: entry.revertTarget || null, reviewSliceRoots: entry.reviewSliceRoots || [], openedAt: entry.openedAt || null, lastUsage: entry.lastUsage || null, carryRecap: entry.pendingRecap || null })
   const persist = () => saveSession(room, id, sessionData())
   // Synchronous flush of this session's record. Used on open (so a brand-new session
   // has a file under its id BEFORE its first event — surviving a restart inside the
@@ -2078,7 +2084,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       return { error: `Could not open a Hermes worker on ${JSON.stringify(args.model)} — that exact model is not in this parent session's ACP catalog.` }
     }
     if (runtime === 'hermes' && args?.mode && !['default', 'acceptEdits'].includes(args.mode)) {
-      return { error: `Hermes ACP does not structurally support ${JSON.stringify(args.mode)} mode. Use default or acceptEdits; Flow/plan/review safety remains disabled.` }
+      return { error: `Hermes ACP only exposes default/acceptEdits as user modes; Flow roles use a bridge-owned process-local tool policy.` }
     }
     if (runtime === 'claude' && !args?.provider && args?.model && /^gpt-/i.test(args.model)) {
       return { error: `Could not open a Claude terminal on Codex model ${JSON.stringify(args.model)}. Choose runtime="codex" or a Claude model.` }
@@ -2346,7 +2352,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       // not receive this tool, so the hierarchy is capability-enforced.
       ...(canSpawnWorkers ? [tool(
         'spawn_terminal',
-        'Open a visible WORKER SUB-TERMINAL (Claude, Codex, or—only from a Hermes parent—Hermes) in the ThinkPool Ensemble. spawn_terminal is worker-only: it can never create a Cascade conductor or main terminal. When a person asks for a separate Cascade/conductor terminal, use open_main_terminal instead. The runtime defaults to inheriting this main/conductor terminal, or pass `runtime`. Choose `model` explicitly when practical: Codex Luna/Mini for mechanical work, Terra for ordinary feature/fix work, and a balanced tier for adversarial review; never select Sol for routine workers. A Hermes worker requires an explicit exact model ID from the parent ACP catalog. After a native Claude account/provider failure, do not retry Claude aliases on that provider; follow read_terminal\'s one-time visible Hermes fallback guidance. A Hermes review worker in default mode is permission-gated, not structurally read-only—deny/stop writes and never claim Flow safety. Pass sliceType=scaffold for mechanical work, feature/fix for builders, and review for adversarial verification. Give the worker a bounded initial task, collect its result with read_terminal, then ALWAYS close_terminal it.',
+        'Open a visible WORKER SUB-TERMINAL (Claude, Codex, or—only from a Hermes parent—Hermes) in the ThinkPool Ensemble. spawn_terminal is worker-only: it can never create a Cascade conductor or main terminal. For ordinary workers use an appropriate non-Sol tier: gpt-5.6-luna or gpt-5.4-mini for scaffold/search, gpt-5.6-terra for feature/fix, and a balanced tier for adversarial review; never select Sol for routine workers. A Hermes sliceType=review lane is structurally reviewer-scoped before ACP startup: it can inspect files and use the bridge review-check tool, but has no terminal, write, patch, delegate, browser, skill, memory, or session-history schema. Pass sliceType=scaffold for mechanical work, feature/fix for builders, and review for adversarial verification. Give the worker a bounded initial task, collect its result with read_terminal, then ALWAYS close_terminal it.',
         {
           name: z.string().max(80).optional().describe('a short label for the new lane so the room (and you) can find it, e.g. "Research: topologies"'),
           task: z.string().optional().describe('an initial task to hand the new lane immediately; omit to open it idle'),
@@ -2442,10 +2448,18 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           // otherwise inherit, but fall plan → default (an autonomous worker doesn't plan-gate).
           const childSpawnDepth = (entry.spawnDepth || 0) + 1
           const childHop = (entry.hop || 0) + 1
+          let manualReviewSnapshots = []
+          if (args?.sliceType === 'review') {
+            // A manual reviewer never accepts a model-supplied path/ref.  It
+            // reads this exact parent HEAD through read_review_file and runs
+            // checks only through its archived `parent` target.
+            try { manualReviewSnapshots = [immutableReviewSnapshot(entry.cwd || process.cwd())] }
+            catch (error) { return okText(`Review lane was not opened: could not pin the spawning parent’s HEAD (${error?.message || error}).`) }
+          }
           // Stamp ownership/depth BEFORE the runtime starts so its first system
           // preamble is truthful. Mutating ne.spawnedBy after openStructured was
           // too late: Codex/Claude had already booted with the top-level wording.
-          openStructured({ id: newId, runtime: resolved.runtime, model: resolved.model, provider: resolved.provider, mode: resolved.mode, spawnedBy: id, spawnDepth: childSpawnDepth, cascadeRole: 'worker', hop: childHop })
+          openStructured({ id: newId, runtime: resolved.runtime, model: resolved.model, provider: resolved.provider, mode: resolved.mode, sliceType: args?.sliceType, flowReviewTargets: manualReviewSnapshots.map((item) => item.taskKey), flowReviewSnapshots: manualReviewSnapshots, spawnedBy: id, spawnDepth: childSpawnDepth, cascadeRole: 'worker', hop: childHop })
           const ne = sessions.get(newId)
           if (!ne) { if (args?.name) { delete termNames[newId]; saveNames(room, termNames) } return okText('Could not open a new lane — the terminal cap may have just been reached. Close one and retry.') }
           ne.peekCount = 0; ne.postCount = 0; ne.spawnTimes = []
@@ -2453,7 +2467,10 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           if (args?.task) {
             // The user-visible relay reinforces (but never defines) the structural
             // role already injected by the system preamble above.
-            const msg = `[Task from terminal ${fromRef}'s agent — relayed via ThinkPool Ensemble; you are its WORKER SUB-TERMINAL, never a main terminal or Cascade conductor]\n${args.task}`
+            const reviewTarget = manualReviewSnapshots.length
+              ? `\n\n[Immutable review target: parent at spawn time — target key "parent", pinned HEAD ${manualReviewSnapshots[0].sha}. Use read_review_file with target="parent" for source and run_review_check with target="parent" for fixed checks. Do not infer a target path/ref or mutate anything.]`
+              : ''
+            const msg = `[Task from terminal ${fromRef}'s agent — relayed via ThinkPool Ensemble; you are its WORKER SUB-TERMINAL, never a main terminal or Cascade conductor]\n${args.task}${reviewTarget}`
             const evt = { kind: 'you', text: msg, by: `terminal ${fromRef} (agent)`, crosspost: true, relaySourceName: termNames[id] || undefined }
             stampEvent(evt); pushLog(ne, evt); bcast('code-event', { term: newId, evt })
             try { ne.session.sendTurn(msg) } catch { return okText(`Opened lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — could not hand off the task. Try post_to_terminal shortly.`) }
@@ -2568,6 +2585,17 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           return { content: [{ type: 'text', text: result.message }] }
         },
       )] : []),
+      ...(entry.flowRole === 'reviewer' || entry.sliceType === 'review' ? [tool(
+        'read_review_file',
+        'Read one regular file from the declared immutable review target. This always reads the target’s pinned Git object, never a live worktree; target and path are validated and the response is byte-bounded.',
+        { target: z.string(), path: z.string() },
+        async (args) => ({ content: [{ type: 'text', text: JSON.stringify(await readReviewFile({ target: args?.target, filePath: args?.path, snapshots: entry.flowReviewSnapshots })) }] }),
+      ), tool(
+        'run_review_check',
+        'Run one fixed verification check against an immutable git-archived review target. This accepts only the declared target and a fixed check id; it never accepts a shell command, cwd, environment, executable, or arguments. The check runs in a scratch archive, never in a builder worktree.',
+        { target: z.string(), checkId: z.string() },
+        async (args) => ({ content: [{ type: 'text', text: JSON.stringify(await runReviewCheck({ target: args?.target, checkId: args?.checkId, snapshots: entry.flowReviewSnapshots })) }] }),
+      )] : []),
     ],
   })
   const peekServer = withMcpSessionFactory(createPeekServer)
@@ -2667,8 +2695,9 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
     // role-scoped tools through local /tools before a user turn. Claude/Codex
     // already fail startup when their required MCP handshake fails.
     requiredMcpTools: runtime === 'hermes'
-      ? ['read_terminal', ...(canSpawnWorkers ? ['spawn_terminal', 'close_terminal'] : [])]
+      ? hermesRequiredMcpTools(hermesRoleFor({ flowRole: entry.flowRole, sliceType: entry.sliceType }), { canSpawnWorkers })
       : undefined,
+    hermesRole: runtime === 'hermes' ? hermesRoleFor({ flowRole: entry.flowRole, sliceType: entry.sliceType }) : undefined,
     // Tier C precheck — the PreToolUse gate calls this BEFORE raising a card, so a
     // disabled/looping/over-cap post never bothers a person. Closes over `entry`.
     crossPostGate: () => crossPostDecision({ hop: entry.hop || 0, postCount: entry.postCount || 0, disabled: process.env.TP_CROSSPOST_OFF === '1' }),
@@ -2715,14 +2744,15 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           message: evt.message,
           recap: recoveryRecap,
           reopen: (carryRecap) => {
+            entry.imageQueue?.close()
             try { entry.mockupWatcher?.close() } catch { /* noop */ }
             sessions.delete(id)
             openStructured({
               id, runtime: entry.runtime, model: entry.model || model, effort: entry.effort,
               provider: entry.provider, log: entry.log, commands: entry.commands, mode: entry.mode,
-              spawnedBy: entry.spawnedBy, spawnDepth: entry.spawnDepth, cascadeRole: entry.cascadeRole, hop: entry.hop, sideParent: entry.sideParent, sideTask: entry.sideTask, pendingSideContexts: entry.pendingSideContexts, flowSessionId: entry.flowSessionId,
+              spawnedBy: entry.spawnedBy, spawnDepth: entry.spawnDepth, cascadeRole: entry.cascadeRole, hop: entry.hop, sideParent: entry.sideParent, sideTask: entry.sideTask, pendingSideContexts: entry.pendingSideContexts, sliceType: entry.sliceType, flowSessionId: entry.flowSessionId,
               flowTaskKey: entry.flowTaskKey, flowRole: entry.flowRole, flowReviewTarget: entry.flowReviewTarget,
-              flowReviewTargets: entry.flowReviewTargets, flowReviewRound: entry.flowReviewRound,
+              flowReviewTargets: entry.flowReviewTargets, flowReviewSnapshots: entry.flowReviewSnapshots, flowReviewRound: entry.flowReviewRound,
               dispatchBaseSha: entry.dispatchBaseSha, revertTarget: entry.revertTarget, cwd: entry.cwd,
               managedWorktree: entry.managedWorktree, rolePrompt: entry.rolePrompt,
               reviewSliceRoots: entry.reviewSliceRoots, openedAt: entry.openedAt,
@@ -2988,10 +3018,10 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       // (live OR replay). Lift it to Storage FIRST, then emit the URL-only event —
       // so the persisted log + replay carry a path, never base64. Order/seq stay
       // intact: pushLog (inside emitTail) is the single seq point, called when the
-      // upload resolves. Other kinds emit synchronously, unchanged.
+      // upload resolves. Later events share the same queue; otherwise a closing
+      // result could overtake its delayed tool_result (BH-DATA-003).
       const imgs = inlineImageBlocks(evt)
-      if (imgs.length) { deferImageEvent(entry, id, evt, imgs, emitTail); return }
-      emitTail(evt)
+      deferImageEvent(entry, id, evt, imgs, emitTail)
     },
     requestPermission: (req) => new Promise((resolve) => {
       // FLOW conductor plan → intercept (no generic card). The plan JSON rides
@@ -3147,6 +3177,7 @@ function acceptEditsPending(s) {
 function respawnStructured(id, provider) {
   const s = sessions.get(id)
   if (!s) return false
+  s.imageQueue?.close()
   // Capture the lane's identity for re-open (NOT resume — fresh SDK session).
   // NOTE the deliberate absence of `model`: a respawn crosses a provider boundary,
   // and the old lane's model id means nothing on the new backend. Carrying it sent
@@ -3157,7 +3188,7 @@ function respawnStructured(id, provider) {
   // openStructured seed from the TARGET provider's configured model, which is the
   // only model this lane was ever asked for. A same-env model change never reaches
   // here — that path is an in-place setModel (see provider-switch).
-  const { runtime, log, commands, mode, spawnedBy, spawnDepth, cascadeRole, hop, sideParent, sideTask, pendingSideContexts, flowSessionId, flowTaskKey, flowRole, flowReviewTarget, flowReviewTargets, flowReviewRound, dispatchBaseSha, revertTarget, cwd, managedWorktree, rolePrompt, reviewSliceRoots, openedAt, lastUsage } = s
+  const { runtime, log, commands, mode, spawnedBy, spawnDepth, cascadeRole, hop, sideParent, sideTask, pendingSideContexts, sliceType, flowSessionId, flowTaskKey, flowRole, flowReviewTarget, flowReviewTargets, flowReviewSnapshots, flowReviewRound, dispatchBaseSha, revertTarget, cwd, managedWorktree, rolePrompt, reviewSliceRoots, openedAt, lastUsage } = s
   // Context-carry (2026-07-08): a provider switch is not an SDK resume — the new backend
   // starts blank mid-conversation. Synthesize a plain-text recap from the VISIBLE log NOW
   // (before teardown) and hand it to the fresh session as its first turn so the agent
@@ -3176,7 +3207,7 @@ function respawnStructured(id, provider) {
   // sessionData() (provider included) synchronously on open, so a bridge restart
   // restores the lane on its CURRENT provider, not the original — and its next
   // announce carries the new provider badge (additive {id,name} projection).
-  openStructured({ id, runtime, provider, log, commands, mode, spawnedBy, spawnDepth, cascadeRole, hop, sideParent, sideTask, pendingSideContexts, flowSessionId, flowTaskKey, flowRole, flowReviewTarget, flowReviewTargets, flowReviewRound, dispatchBaseSha, revertTarget, cwd, managedWorktree, rolePrompt, reviewSliceRoots, openedAt, lastUsage, carryRecap })
+  openStructured({ id, runtime, provider, log, commands, mode, spawnedBy, spawnDepth, cascadeRole, hop, sideParent, sideTask, pendingSideContexts, sliceType, flowSessionId, flowTaskKey, flowRole, flowReviewTarget, flowReviewTargets, flowReviewSnapshots, flowReviewRound, dispatchBaseSha, revertTarget, cwd, managedWorktree, rolePrompt, reviewSliceRoots, openedAt, lastUsage, carryRecap })
   return true
 }
 
@@ -3210,6 +3241,7 @@ function endStructured(id) {
   if (!id) return
   const s = sessions.get(id)
   if (s) {
+    s.imageQueue?.close()
     drainPending(s)
     try { s.session?.end() } catch { /* noop */ }
     try { s.mockupWatcher?.close() } catch { /* noop */ }
@@ -3989,7 +4021,7 @@ channel
             // FL-M6 — restore the flow context (id/role/cwd) so an in-flight flow survives a
             // bridge restart: the conductor keeps its subagent-block + plan interception, and
             // lanes keep their worktree cwd + the ability to mark done.
-            openStructured({ id: rec.id, runtime: rec.runtime || 'claude', model: rec.model || undefined, models: rec.models, effort: rec.effort, provider: rec.runtime === 'claude' ? rec.provider || undefined : undefined, resume: resumable ? rec.sessionId : undefined, log: rec.log, commands: rec.commands, mode: rec.mode, spawnedBy: rec.spawnedBy, spawnDepth: rec.spawnDepth, cascadeRole: rec.cascadeRole, hop: rec.hop, sideParent: rec.sideParent, sideTask: rec.sideTask, pendingSideContexts: rec.pendingSideContexts, flowSessionId: rec.flowSessionId, flowTaskKey: rec.flowTaskKey, flowRole: rec.flowRole, flowReviewTarget: rec.flowReviewTarget, flowReviewTargets: rec.flowReviewTargets, flowReviewRound: rec.flowReviewRound, dispatchBaseSha: rec.dispatchBaseSha, revertTarget: rec.revertTarget, cwd: rec.cwd, managedWorktree: rec.managedWorktree, rolePrompt: rec.rolePrompt, reviewSliceRoots: rec.reviewSliceRoots, openedAt: rec.openedAt, lastUsage: rec.lastUsage, carryRecap: wasInterrupted ? recoveryRecap : rec.carryRecap,
+            openStructured({ id: rec.id, runtime: rec.runtime || 'claude', model: rec.model || undefined, models: rec.models, effort: rec.effort, provider: rec.runtime === 'claude' ? rec.provider || undefined : undefined, resume: resumable ? rec.sessionId : undefined, log: rec.log, commands: rec.commands, mode: rec.mode, spawnedBy: rec.spawnedBy, spawnDepth: rec.spawnDepth, cascadeRole: rec.cascadeRole, hop: rec.hop, sideParent: rec.sideParent, sideTask: rec.sideTask, pendingSideContexts: rec.pendingSideContexts, sliceType: rec.sliceType, flowSessionId: rec.flowSessionId, flowTaskKey: rec.flowTaskKey, flowRole: rec.flowRole, flowReviewTarget: rec.flowReviewTarget, flowReviewTargets: rec.flowReviewTargets, flowReviewSnapshots: rec.flowReviewSnapshots, flowReviewRound: rec.flowReviewRound, dispatchBaseSha: rec.dispatchBaseSha, revertTarget: rec.revertTarget, cwd: rec.cwd, managedWorktree: rec.managedWorktree, rolePrompt: rec.rolePrompt, reviewSliceRoots: rec.reviewSliceRoots, openedAt: rec.openedAt, lastUsage: rec.lastUsage, carryRecap: wasInterrupted ? recoveryRecap : rec.carryRecap,
               // Lazy-boot restored terminals that were IDLE + not part of a flow: their transcript
               // shows immediately; the query boots on first turn. Mid-turn + flow terminals boot now
               // (mid-turn needs auto-resume; flow needs its lane live).
@@ -4104,7 +4136,7 @@ flowChannel
     if (payload.originTerm && !origin) return
     const flowRuntime = origin ? normalizeFlowRuntime(origin.runtime, null) : 'claude'
     if (!flowRuntime) return
-    const flowCatalog = flowRuntime === 'codex' ? (origin?.models || readCodexModels()) : []
+    const flowCatalog = flowRuntime === 'codex' ? (origin?.models || readCodexModels()) : flowRuntime === 'hermes' ? (origin?.models || []) : []
     const conductorModel = flowConductorModelFor({ runtime: flowRuntime, originModel: origin?.model, catalog: flowCatalog })
     const cid = randomUUID()
     termNames[cid] = `Flow · ${String(payload.flowId).slice(0, 6)}`
@@ -4116,7 +4148,7 @@ flowChannel
     // Model tiers (2026-07-03-flow-lane-model-tiers): the conductor keeps whatever brain it was
     // given by default (TP_FLOW_CONDUCTOR_MODEL unset → undefined → today's behavior); set the env
     // to pin a cheaper/smarter conductor. Lanes get tiered below via laneModelFor.
-    openStructured({ id: cid, runtime: flowRuntime, model: conductorModel, mode: flowRuntime === 'codex' ? 'plan' : 'default', rolePrompt: flowRuntime === 'codex' ? FLOW_CODEX_CONDUCTOR_PROMPT : FLOW_CONDUCTOR_PROMPT, flowSessionId: payload.flowId, flowRole: 'conductor', spawnedBy: `flow:${payload.flowId}` })
+    openStructured({ id: cid, runtime: flowRuntime, model: conductorModel, mode: flowRuntime === 'codex' ? 'plan' : 'default', rolePrompt: flowRuntime === 'claude' ? FLOW_CONDUCTOR_PROMPT : FLOW_CODEX_CONDUCTOR_PROMPT, flowSessionId: payload.flowId, flowRole: 'conductor', spawnedBy: `flow:${payload.flowId}` })
     const ce = sessions.get(cid)
     if (ce?.session) { try { ce.session.sendTurn(payload.prompt || '') } catch { /* session still starting */ } }
     process.stderr.write(`\n  ${A.mag}◆ flow conductor launched — flow ${String(payload.flowId).slice(0, 8)} (plan mode).${A.rst}\n`)
@@ -4137,7 +4169,7 @@ flowChannel
     }
     const flowRuntime = normalizeFlowRuntime(conductor.runtime, null)
     if (!flowRuntime) return
-    const flowCatalog = flowRuntime === 'codex' ? (conductor.models || readCodexModels()) : []
+    const flowCatalog = flowRuntime === 'codex' ? (conductor.models || readCodexModels()) : flowRuntime === 'hermes' ? (conductor.models || []) : []
     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.
@@ -4167,7 +4199,7 @@ flowChannel
         // every other slice gets the builder prompt.
         const isReview = t.slice_type === 'review'
         if (!validReviewTargetShape(t, flowRuntime)) {
-          process.stderr.write(`\n  ${A.yel}◆ flow dispatch held — Codex review ${t.task_key} must target exactly one dependency.${A.rst}\n`)
+          process.stderr.write(`\n  ${A.yel}◆ flow dispatch held — ${flowRuntime === 'hermes' ? 'Hermes' : 'Codex'} review ${t.task_key} must target exactly one dependency.${A.rst}\n`)
           continue
         }
         const { dir } = createFlowWorktree({ flowId: payload.flowId, taskKey: t.task_key })
@@ -4195,6 +4227,12 @@ flowChannel
         const reviewSliceRoots = isReview
           ? (t.deps || []).map((dep) => worktreeSpec({ flowId: payload.flowId, taskKey: dep }).dir)
           : []
+        const flowReviewSnapshots = isReview ? (t.deps || []).map((dep) => {
+          const cwd = worktreeSpec({ flowId: payload.flowId, taskKey: dep }).dir
+          let sha = null
+          try { sha = execFileSync('git', ['-C', cwd, 'rev-parse', 'HEAD'], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] }).trim() } catch { /* target is not safely reviewable */ }
+          return { taskKey: dep, cwd, sha }
+        }).filter((item) => item.sha) : []
         // Lanes build autonomously in their own worktree — bypassPermissions so they
         // don't stall on a card for every write/bash (matches the user's expectation that
         // a Flow summoned from a bypass terminal runs hands-off).
@@ -4205,14 +4243,14 @@ flowChannel
         // a lane later, on demand, via activateLaneSkill — never the base prompt here.
         // S4 — resume: on a re-dispatch, replay the killed lane's HEALED transcript (Heal-3'd,
         // no dangling tool_use → no 400) instead of a cold start; undefined for a fresh lane.
-        const laneBase = flowRuntime === 'codex'
+        const laneBase = flowRuntime === 'codex' || flowRuntime === 'hermes'
           ? (isReview ? FLOW_CODEX_REVIEWER_PROMPT : FLOW_CODEX_LANE_PROMPT)
           : (isReview ? FLOW_REVIEWER_PROMPT : FLOW_LANE_PROMPT)
         const laneRolePrompt = buildLanePrompt({ base: laneBase })
         // Model tiers (2026-07-03-flow-lane-model-tiers): pick the lane's brain by slice_type
         // (scaffold→sonnet, feature/fix/review→opus; env can blanket-override or `inherit` to
         // restore today's exact behavior). undefined → no model key passed (openStructured default).
-        openStructured({ id: laneId, runtime: flowRuntime, cwd: dir, model: flowLaneModelFor({ sliceType: t.slice_type, runtime: flowRuntime, catalog: flowCatalog }), mode: flowRuntime === 'codex' && isReview ? 'review' : 'bypassPermissions', rolePrompt: laneRolePrompt, flowSessionId: payload.flowId, flowTaskKey: t.task_key, flowRole: isReview ? 'reviewer' : 'builder', flowReviewTargets: isReview ? (t.deps || []) : [], dispatchBaseSha, revertTarget: redispatch?.revertTarget || null, spawnedBy: `flow:${payload.flowId}`, resume: redispatch?.resumeSessionId || undefined, reviewSliceRoots })
+        openStructured({ id: laneId, runtime: flowRuntime, cwd: dir, model: flowLaneModelFor({ sliceType: t.slice_type, runtime: flowRuntime, catalog: flowCatalog }), mode: flowRuntime === 'codex' && isReview ? 'review' : 'bypassPermissions', rolePrompt: laneRolePrompt, flowSessionId: payload.flowId, flowTaskKey: t.task_key, flowRole: isReview ? 'reviewer' : 'builder', flowReviewTargets: isReview ? (t.deps || []) : [], flowReviewSnapshots, dispatchBaseSha, revertTarget: redispatch?.revertTarget || null, spawnedBy: `flow:${payload.flowId}`, resume: redispatch?.resumeSessionId || undefined, reviewSliceRoots })
         const le = sessions.get(laneId)
         if (le) {
           // S4 — stamp the surviving revert target on the resumed lane so a later reviewer still
@@ -4237,7 +4275,7 @@ flowChannel
                   : '') +
                 `ACCEPTANCE to INDEPENDENTLY verify: ${t.acceptance || t.title}\n` +
                 `\nProject (context): ${payload.flowPrompt || ''}\n\n` +
-                (flowRuntime === 'codex'
+                (flowRuntime === 'codex' || flowRuntime === 'hermes'
                   ? `Review it without mutating the builder worktree. For write-producing install/build/test commands, copy its source into scratch under your own current worktree first. Submit the structured verdict with the ThinkPool submit_flow_review MCP tool; never write FLOW_REVIEW.json or call mark_flow_done.`
                   : `Review it — run it, hunt for failure. When done, use the Write tool to write FLOW_REVIEW.json with {"pass":<boolean>,"reasons":["<specific finding>"],"taskKey":"<the slice you reviewed>"}. That Write IS your verdict.`)
               : `[Flow lane — slice "${t.task_key}" of flow ${String(payload.flowId).slice(0, 8)}]\n` +
@@ -4252,7 +4290,7 @@ flowChannel
                   assembleCrossWaveContext(payload.flowId, { baseDir: process.cwd(), deps: t.deps }).text) +
                 `\nProject (context): ${payload.flowPrompt || ''}\n\n` +
                 `Build your slice. Own only your files. Done = it runs + meets acceptance. Commit when done.` +
-                (flowRuntime === 'codex' ? ` Then call the ThinkPool mark_flow_done MCP tool; do not write FLOW_DONE.` : '')
+                (flowRuntime === 'codex' || flowRuntime === 'hermes' ? ` Then call the ThinkPool mark_flow_done MCP tool; do not write FLOW_DONE.` : '')
             try { le.session.sendTurn(spec) } catch { /* session still starting */ }
           }
         }
@@ -4565,6 +4603,7 @@ async function shutdown(code = 0, farewell = true) {
   // Flush structured session state synchronously BEFORE ending sessions. saveSession
   // debounces ~1.5s, so without this any events since the last write are lost on exit
   // (Contract #2). writeFileSync, well inside the 1500ms hard-exit backstop above.
+  for (const s of sessions.values()) { try { s.imageQueue?.close() } catch { /* noop */ } }
   for (const s of sessions.values()) { try { s.flush?.() } catch { /* noop */ } }
   for (const t of terms.values()) { try { t.term.kill() } catch { /* noop */ } }
   for (const s of sessions.values()) { try { s.session.end() } catch { /* noop */ } }