thinkpool-pair 0.7.246 → 0.7.247

package/bridge.mjs

@@ -54,6 +54,7 @@ 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'
@@ -82,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'
@@ -1727,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)
@@ -1744,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):
@@ -1797,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,
@@ -2046,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
@@ -2074,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.` }
@@ -2342,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'),
@@ -2438,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 = []
@@ -2449,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.`) }
@@ -2564,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)
@@ -2663,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' }),
@@ -2717,9 +2750,9 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
             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,
@@ -3155,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
@@ -3174,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
 }
 
@@ -3988,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).
@@ -4103,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)}`
@@ -4115,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`)
@@ -4136,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.
@@ -4166,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 })
@@ -4194,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).
@@ -4204,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
@@ -4236,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` +
@@ -4251,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 */ }
           }
         }

package/flow-models.mjs

@@ -11,10 +11,11 @@ const CLAUDE_TIERS = {
 
 const CODEX_SCAFFOLD = ['gpt-5.6-luna', 'gpt-5.4-mini', 'gpt-5.3-codex-spark']
 const CODEX_BALANCED = ['gpt-5.6-terra', 'gpt-5.4']
+const HERMES_REVIEW = ['nous:anthropic/claude-sonnet-4.6', 'nous:anthropic/claude-sonnet-4.5', 'nous:anthropic/claude-sonnet-4']
 
 export function normalizeFlowRuntime(runtime, fallback = null) {
-  if (runtime === 'claude' || runtime === 'codex') return runtime
-  return fallback === 'claude' || fallback === 'codex' ? fallback : null
+  if (runtime === 'claude' || runtime === 'codex' || runtime === 'hermes') return runtime
+  return fallback === 'claude' || fallback === 'codex' || fallback === 'hermes' ? fallback : null
 }
 
 export function modelCatalogValues(catalog = []) {
@@ -32,6 +33,12 @@ function firstVisible(candidates, catalog) {
   return undefined
 }
 
+function firstVisibleMatching(catalog, patterns) {
+  const visible = modelCatalogValues(catalog)
+  for (const pattern of patterns) for (const model of visible) if (pattern.test(model)) return model
+  return undefined
+}
+
 export function flowLaneModelFor({ sliceType, runtime = 'claude', catalog = [], env = process.env } = {}) {
   if (normalizeFlowRuntime(runtime, 'claude') === 'codex') {
     const override = env.TP_FLOW_CODEX_LANE_MODEL
@@ -39,6 +46,16 @@ export function flowLaneModelFor({ sliceType, runtime = 'claude', catalog = [],
     if (override) return modelCatalogValues(catalog).has(override) ? override : undefined
     return firstVisible(sliceType === 'scaffold' ? CODEX_SCAFFOLD : CODEX_BALANCED, catalog)
   }
+  if (normalizeFlowRuntime(runtime, 'claude') === 'hermes') {
+    const override = env.TP_FLOW_HERMES_LANE_MODEL
+    const visible = modelCatalogValues(catalog)
+    if (override === 'inherit') return undefined
+    if (override) return visible.has(override) ? override : undefined
+    if (sliceType === 'review') return firstVisible(HERMES_REVIEW, catalog)
+      || firstVisibleMatching(catalog, [/terra/i, /sonnet/i, /balanced/i])
+    if (sliceType === 'scaffold') return firstVisibleMatching(catalog, [/(?:luna|mini)/i])
+    return firstVisibleMatching(catalog, [/terra/i, /(?:luna|mini)/i])
+  }
   const override = env.TP_FLOW_CLAUDE_LANE_MODEL || env.TP_FLOW_LANE_MODEL
   if (override === 'inherit') return undefined
   if (override) return override
@@ -53,6 +70,13 @@ export function flowConductorModelFor({ runtime = 'claude', originModel, catalog
     if (override) return visible.has(override) ? override : undefined
     return originModel && visible.has(originModel) ? originModel : undefined
   }
+  if (normalizeFlowRuntime(runtime, 'claude') === 'hermes') {
+    const override = env.TP_FLOW_HERMES_CONDUCTOR_MODEL
+    const visible = modelCatalogValues(catalog)
+    if (override === 'inherit') return undefined
+    if (override) return visible.has(override) ? override : undefined
+    return originModel && visible.has(originModel) ? originModel : undefined
+  }
   const override = env.TP_FLOW_CLAUDE_CONDUCTOR_MODEL || env.TP_FLOW_CONDUCTOR_MODEL
   if (override === 'inherit') return undefined
   // Claude non-regression: the conductor historically inherited the host default,

package/flow-task-graph.mjs

@@ -176,10 +176,10 @@ export function normalizePlanOutput (raw) {
 // Codex review protocol deliberately maps one reviewer lane to one builder target.
 // Claude's legacy Flow plans may review several deps and remain unchanged.
 export function validatePlanForRuntime (plan, runtime = 'claude') {
-  if (runtime !== 'codex') return plan
+  if (runtime !== 'codex' && runtime !== 'hermes') return plan
   for (const task of plan?.tasks || []) {
     if (task.sliceType === SLICE_TYPE.review && task.deps.length !== 1) {
-      throw new Error(`Codex review task "${task.key}" must depend on exactly one builder task`)
+      throw new Error(`${runtime === 'hermes' ? 'Hermes' : 'Codex'} review task "${task.key}" must depend on exactly one builder task`)
     }
   }
   return plan
@@ -187,7 +187,7 @@ export function validatePlanForRuntime (plan, runtime = 'claude') {
 
 export function validReviewTargetShape (task, runtime = 'claude') {
   if (!task || task.slice_type !== SLICE_TYPE.review) return true
-  return runtime !== 'codex' || (Array.isArray(task.deps) && task.deps.length === 1)
+  return (runtime !== 'codex' && runtime !== 'hermes') || (Array.isArray(task.deps) && task.deps.length === 1)
 }
 
 export function legacyBuilderCompletionAllowed ({ runtime, flowRole, eventKind, eventSubtype, interrupted = false } = {}) {

package/hermes-acp-bootstrap.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Process-local ThinkPool Hermes ACP tool policy.
+
+Never import this through the user profile. The bridge starts this file with
+Hermes' installed venv interpreter and passes a validated role policy in env.
+"""
+import json
+import os
+import sys
+
+POLICY_ENV = "THINKPOOL_HERMES_ACP_POLICY"
+
+CODING_TOOLS = frozenset({
+    "web_search", "web_extract", "terminal", "process", "read_file", "write_file",
+    "patch", "search_files", "vision_analyze", "skills_list", "skill_view",
+    "skill_manage", "browser_navigate", "browser_snapshot", "browser_click",
+    "browser_type", "browser_scroll", "browser_back", "browser_press",
+    "browser_get_images", "browser_vision", "browser_console", "browser_cdp",
+    "browser_dialog", "todo", "memory", "execute_code",
+})
+READ_ONLY_TOOLS = frozenset({"read_file", "search_files"})
+ESSENTIAL_CODING_TOOLS = frozenset({
+    "terminal", "process", "read_file", "write_file", "patch", "search_files",
+})
+
+def die(message):
+    print("ThinkPool Hermes ACP policy error: " + message, file=sys.stderr)
+    raise SystemExit(78)
+
+def policy():
+    raw = os.environ.get(POLICY_ENV)
+    try:
+        value = json.loads(raw)
+    except Exception:
+        die("missing or malformed policy")
+    if not isinstance(value, dict) or value.get("version") != 1:
+        die("unsupported policy")
+    role = value.get("role")
+    builtin = value.get("builtinTools")
+    required_builtin = value.get("requiredBuiltinTools")
+    tools = value.get("mcpTools")
+    if role not in {"ordinary", "builder", "conductor", "reviewer", "manual-review"}:
+        die("unknown role")
+    if value.get("mcpServer") != "thinkpool" or not isinstance(builtin, list) or not isinstance(required_builtin, list) or not isinstance(tools, list):
+        die("invalid tool policy")
+    if not all(isinstance(x, str) and x and x.replace("_", "").isalnum() for x in builtin + required_builtin + tools):
+        die("invalid tool name")
+    forbidden = {"delegate_task", "session_search"}
+    if forbidden.intersection(builtin) or forbidden.intersection(required_builtin) or forbidden.intersection(tools):
+        die("delegation and session search are forbidden")
+    required_mcp = {
+        "ordinary": {"read_terminal"}, "builder": {"mark_flow_done"},
+        "conductor": {"submit_flow_plan"},
+        "reviewer": {"submit_flow_review", "run_review_check", "read_review_file"},
+        "manual-review": {"run_review_check", "read_review_file"},
+    }
+    if not required_mcp[role].issubset(tools):
+        die("incomplete role MCP policy")
+    restricted = role in {"conductor", "reviewer", "manual-review"}
+    allowed_builtin = READ_ONLY_TOOLS if restricted else CODING_TOOLS
+    required = READ_ONLY_TOOLS if restricted else ESSENTIAL_CODING_TOOLS
+    if set(builtin) != allowed_builtin:
+        die("restricted role requires exact read-only builtins" if restricted else "coding role requires the full approved builtin allowlist")
+    if set(required_builtin) != required:
+        die("invalid required builtin policy")
+    return role, tuple(dict.fromkeys(builtin)), tuple(dict.fromkeys(required_builtin)), tuple(dict.fromkeys(tools))
+
+ROLE, BUILTIN, REQUIRED_BUILTIN, MCP_TOOLS = policy()
+ALLOWED = frozenset(BUILTIN) | frozenset("mcp__thinkpool__" + x for x in MCP_TOOLS) | frozenset("mcp_thinkpool_" + x for x in MCP_TOOLS)
+
+def name_of(schema):
+    if not isinstance(schema, dict): return ""
+    fn = schema.get("function")
+    return fn.get("name", "") if isinstance(fn, dict) else schema.get("name", "")
+
+def filter_schemas(items):
+    return [item for item in (items or []) if name_of(item) in ALLOWED]
+
+def assert_exact_inventory(agent):
+    """Reject an ACP lifecycle that lost the bridge-owned MCP surface.
+
+    Hermes treats registration errors as non-fatal.  That is acceptable for a
+    standalone CLI, but never for a ThinkPool role: the bridge must not let a
+    reconstructed agent accept a prompt with a partial policy.
+    """
+    tools = list(getattr(agent, "tools", []) or [])
+    names = {name_of(item) for item in tools}
+    # Allowed is deliberately broader than required for ordinary/builder:
+    # browser/provider/vision integrations are availability-gated upstream.
+    missing_builtin = set(REQUIRED_BUILTIN) - names
+    missing_mcp = [name for name in MCP_TOOLS if not ({"mcp__thinkpool__" + name, "mcp_thinkpool_" + name} & names)]
+    extras = names - ALLOWED
+    if missing_builtin or missing_mcp or extras:
+        details = []
+        if missing_builtin: details.append("missing builtins " + ", ".join(sorted(missing_builtin)))
+        if missing_mcp: details.append("missing MCP " + ", ".join(sorted(missing_mcp)))
+        if extras: details.append("forbidden extras " + ", ".join(sorted(extras)))
+        raise RuntimeError("ThinkPool exact inventory is incomplete: " + "; ".join(details))
+    agent.tools = tools
+    agent.valid_tool_names = names
+
+# Patch before importing ACP server. Each new/resumed/reset ACP process reloads
+# this exact policy; no mutable shell alias or profile config participates.
+import toolsets
+toolsets.TOOLSETS["hermes-acp"] = {
+    "description": "ThinkPool process-local ACP policy",
+    "tools": list(BUILTIN), "includes": []
+}
+
+# entry.main() normally discovers profile-configured MCP servers before it
+# creates the ACP server. ThinkPool ACP never inherits those profile servers;
+# the only permitted registration is the bridge's per-session `thinkpool` one.
+import tools.mcp_tool
+tools.mcp_tool.discover_mcp_tools = lambda *args, **kwargs: []
+
+import model_tools
+_get_definitions = model_tools.get_tool_definitions
+def constrained_definitions(*args, **kwargs):
+    return filter_schemas(_get_definitions(*args, **kwargs))
+model_tools.get_tool_definitions = constrained_definitions
+
+import agent.memory_manager
+_inject_memory = agent.memory_manager.inject_memory_provider_tools
+def constrained_memory(agent):
+    result = _inject_memory(agent)
+    if hasattr(agent, "tools"):
+        agent.tools = filter_schemas(agent.tools)
+        agent.valid_tool_names = {name_of(x) for x in agent.tools}
+    return result
+agent.memory_manager.inject_memory_provider_tools = constrained_memory
+
+import acp_adapter.session
+_expand = acp_adapter.session._expand_acp_enabled_toolsets
+def constrained_expand(toolsets_arg=None, mcp_server_names=None):
+    requested = list(toolsets_arg or ["hermes-acp"])
+    if any(name not in {"hermes-acp", "mcp-thinkpool"} for name in requested):
+        raise RuntimeError("ThinkPool ACP only permits hermes-acp and mcp-thinkpool toolsets")
+    names = list(mcp_server_names or [])
+    if any(name != "thinkpool" for name in names):
+        raise RuntimeError("ThinkPool ACP only permits dynamic MCP server thinkpool")
+    # Hermes 0.18.2 calls this from /tools with an already-expanded
+    # ["hermes-acp", "mcp-thinkpool"] list and no mcp_server_names.  Preserve
+    # that exact legal expansion; otherwise /tools silently omits ThinkPool.
+    return ["hermes-acp"] + (["mcp-thinkpool"] if names or "mcp-thinkpool" in requested else [])
+acp_adapter.session._expand_acp_enabled_toolsets = constrained_expand
+
+import acp_adapter.server
+_register = acp_adapter.server.HermesACPAgent._register_session_mcp_servers
+async def constrained_register(self, state, mcp_servers):
+    if any(getattr(server, "name", None) != "thinkpool" for server in (mcp_servers or [])):
+        raise RuntimeError("ThinkPool ACP only permits dynamic MCP server thinkpool")
+    if mcp_servers:
+        # SessionState is process-local.  Keep only the validated descriptors so
+        # a subsequent set_model reconstruction can re-register the same MCP.
+        state._thinkpool_mcp_servers = tuple(mcp_servers)
+    await _register(self, state, mcp_servers)
+    assert_exact_inventory(state.agent)
+acp_adapter.server.HermesACPAgent._register_session_mcp_servers = constrained_register
+
+# Hermes 0.18.2's session/set_model creates a fresh state.agent.  Upstream
+# does not re-run ACP MCP registration, so the new agent can expose only its
+# built-ins while the request still returns success.  Keep the old state until
+# the replacement has re-registered and passed the same exact policy check.
+_set_model = acp_adapter.server.HermesACPAgent.set_session_model
+async def constrained_set_model(self, model_id, session_id, **kwargs):
+    state = self.session_manager.get_session(session_id)
+    if state is None:
+        return await _set_model(self, model_id, session_id, **kwargs)
+    old_agent, old_model = state.agent, getattr(state, "model", None)
+    try:
+        result = await _set_model(self, model_id, session_id, **kwargs)
+        if result is None:
+            raise RuntimeError("Hermes did not acknowledge model switch")
+        servers = getattr(state, "_thinkpool_mcp_servers", ())
+        if MCP_TOOLS and not servers:
+            raise RuntimeError("ThinkPool MCP registration is unavailable after model switch")
+        await constrained_register(self, state, list(servers))
+        assert_exact_inventory(state.agent)
+        self.session_manager.save_session(session_id)
+        return result
+    except Exception:
+        # Fail closed and restore the prior usable agent/model.  A later bridge
+        # /tools probe is the external acknowledgement before UI persistence.
+        state.agent, state.model = old_agent, old_model
+        try:
+            servers = getattr(state, "_thinkpool_mcp_servers", ())
+            if servers:
+                await constrained_register(self, state, list(servers))
+            self.session_manager.save_session(session_id)
+        except Exception:
+            pass
+        raise
+acp_adapter.server.HermesACPAgent.set_session_model = constrained_set_model
+
+from acp_adapter.entry import main
+main()

package/hermes-policy.mjs

@@ -0,0 +1,85 @@
+// Bridge-owned Hermes ACP schema policy. This is intentionally a small, pure
+// contract: Python receives only this JSON and fails closed for anything else.
+export const HERMES_POLICY_VERSION = 1
+
+export const CODING_TOOLS = Object.freeze([
+  'web_search', 'web_extract', 'terminal', 'process', 'read_file', 'write_file',
+  'patch', 'search_files', 'vision_analyze', 'skills_list', 'skill_view',
+  'skill_manage', 'browser_navigate', 'browser_snapshot', 'browser_click',
+  'browser_type', 'browser_scroll', 'browser_back', 'browser_press',
+  'browser_get_images', 'browser_vision', 'browser_console', 'browser_cdp',
+  'browser_dialog', 'todo', 'memory', 'execute_code',
+])
+
+const READ_ONLY_TOOLS = Object.freeze(['read_file', 'search_files'])
+// Hermes providers advertise capabilities conditionally (for example browser
+// CDP/dialog support depends on the installed browser integration).  These are
+// the only builtins an ordinary or builder lane must have to do useful coding
+// work; the complete coding allowlist above remains permitted when available.
+export const ESSENTIAL_CODING_TOOLS = Object.freeze([
+  'terminal', 'process', 'read_file', 'write_file', 'patch', 'search_files',
+])
+const ROLE_REQUIRED = Object.freeze({
+  ordinary: ['read_terminal', 'spawn_terminal', 'close_terminal'],
+  conductor: ['submit_flow_plan'],
+  builder: ['mark_flow_done'],
+  reviewer: ['submit_flow_review', 'run_review_check', 'read_review_file'],
+  'manual-review': ['run_review_check', 'read_review_file'],
+})
+
+export function hermesRoleFor({ flowRole, sliceType } = {}) {
+  if (flowRole === 'conductor') return 'conductor'
+  if (flowRole === 'reviewer') return 'reviewer'
+  if (sliceType === 'review') return 'manual-review'
+  if (flowRole === 'builder') return 'builder'
+  return 'ordinary'
+}
+
+export function hermesPolicyForRole(role, { mcpTools } = {}) {
+  if (!Object.hasOwn(ROLE_REQUIRED, role)) throw new Error(`Unknown Hermes role policy: ${role}`)
+  const supplied = Array.isArray(mcpTools) ? mcpTools.map(String).filter(Boolean) : ROLE_REQUIRED[role]
+  const required = ROLE_REQUIRED[role]
+  // Ordinary worker leaves deliberately lack spawn/close. Main-lane proof is
+  // enforced by requiredMcpTools at dispatch; keep this schema usable for a
+  // non-delegating ordinary child without widening it.
+  const minimum = role === 'ordinary' ? ['read_terminal'] : required
+  for (const tool of minimum) if (!supplied.includes(tool)) throw new Error(`Hermes ${role} policy is missing required ThinkPool tool ${tool}`)
+  const restricted = role === 'conductor' || role === 'reviewer' || role === 'manual-review'
+  const builtinTools = restricted ? READ_ONLY_TOOLS : CODING_TOOLS
+  const requiredBuiltinTools = restricted ? READ_ONLY_TOOLS : ESSENTIAL_CODING_TOOLS
+  return Object.freeze({
+    version: HERMES_POLICY_VERSION,
+    role,
+    // `builtinTools` is the role's complete approved surface, not a promise
+    // that an availability-gated upstream provider implements every tool.
+    builtinTools,
+    requiredBuiltinTools,
+    mcpServer: 'thinkpool',
+    mcpTools: [...new Set(supplied)].sort(),
+  })
+}
+
+export function hermesRequiredMcpTools(role, { canSpawnWorkers = false } = {}) {
+  if (role === 'ordinary') return ['read_terminal', ...(canSpawnWorkers ? ['spawn_terminal', 'close_terminal'] : [])]
+  return [...ROLE_REQUIRED[role]]
+}
+
+// Keep the bridge's local /tools proof on the same canonical inventory as the
+// process-local Python bootstrap.  `allBuiltinTools` lets that proof reject a
+// known built-in which is not part of this role, rather than merely looking
+// for a couple of required MCP names.
+export function hermesExactInventory(role, options = {}) {
+  const policy = hermesPolicyForRole(role, options)
+  return Object.freeze({
+    builtinTools: [...policy.builtinTools].sort(),
+    requiredBuiltinTools: [...policy.requiredBuiltinTools].sort(),
+    mcpTools: [...policy.mcpTools].sort(),
+    // The two excluded upstream capabilities must be checked as forbidden too;
+    // they are intentionally absent from CODING_TOOLS, not unknown to policy.
+    allBuiltinTools: [...CODING_TOOLS, 'delegate_task', 'session_search'].sort(),
+  })
+}
+
+export function hermesPolicyEnv(role, options = {}) {
+  return JSON.stringify(hermesPolicyForRole(role, options))
+}

package/hermes-probe.mjs

@@ -1,8 +1,36 @@
 import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
 
 const clean = (value) => String(value || '').replace(/[\r\n]+/g, ' ').trim()
 
-export function probeHermesRuntime({ command = 'thinkpool', prefixArgs = [], execFile = execFileSync, env = process.env } = {}) {
+const INSTALL = /Install directory:\s*(.+?)(?:\r?\n|$)/i
+const PROFILE = /Config:\s*(.+?)(?:\r?\n|$)/i
+
+// Resolve the installed venv and isolated profile once, then launch ACP through
+// bridge-owned code. `thinkpool` is only queried for inventory; it is never the
+// executable that serves an ACP lane.
+export function resolveHermesAcpRuntime({ command = 'thinkpool', execFile = execFileSync, exists = fs.existsSync, bootstrap = new URL('./hermes-acp-bootstrap.py', import.meta.url) } = {}) {
+  try {
+    const versionOutput = execFile(command, ['--version'], { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] })
+    const install = clean(String(versionOutput).match(INSTALL)?.[1])
+    if (!install || !path.isAbsolute(install)) throw new Error('Hermes did not report an absolute install directory')
+    const python = path.join(install, 'venv', 'bin', 'python')
+    const bootstrapPath = bootstrap instanceof URL ? bootstrap.pathname : String(bootstrap)
+    if (!exists(python) || !exists(bootstrapPath)) throw new Error('Hermes venv Python or ThinkPool ACP bootstrap is missing')
+    // `thinkpool` is the dedicated profile wrapper on supported installs. Its
+    // config output is evidence, not the ACP launch path.
+    const configOutput = execFile(command, ['config', 'show'], { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] })
+    const config = clean(String(configOutput).match(PROFILE)?.[1])
+    const profile = config ? path.dirname(config) : ''
+    if (!profile || !path.isAbsolute(profile) || path.basename(profile) !== 'thinkpool') throw new Error('Hermes did not report the isolated thinkpool profile')
+    return { python, bootstrap: bootstrapPath, profile, install }
+  } catch (error) {
+    return { error: clean(error?.stderr || error?.message || error) || 'could not resolve Hermes ACP runtime' }
+  }
+}
+
+export function probeHermesRuntime({ command = 'thinkpool', prefixArgs = [], execFile = execFileSync, env = process.env, strictBootstrap = false, exists = fs.existsSync } = {}) {
   try {
     const versionOutput = execFile(command, [...prefixArgs, '--version'], { encoding: 'utf8', env, timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] })
     const version = clean(versionOutput).match(/Hermes Agent v([^\s]+)/i)?.[1] || null
@@ -16,7 +44,9 @@ export function probeHermesRuntime({ command = 'thinkpool', prefixArgs = [], exe
       && /ThinkPool blocks hidden Hermes delegation/i.test(guardOutput)
       && /pre_tool_call[\s\S]*delegate_task[\s\S]*(?:✓ allowed|allowed)/i.test(hooksOutput)
     if (!doctorHealthy || !delegationBlocked) return { available: false, version, reason: 'delegate_task guard is not healthy, unchanged, allowlisted, and structurally blocking in the dedicated Hermes profile' }
-    return { available: true, version, acpProtocol: 1, delegationBlocked: true }
+    const runtime = strictBootstrap ? resolveHermesAcpRuntime({ command, execFile, exists }) : null
+    if (runtime?.error) return { available: false, version, reason: `Hermes ACP bootstrap unavailable: ${runtime.error}` }
+    return { available: true, version, acpProtocol: 1, delegationBlocked: true, ...(runtime || {}) }
   } catch (error) {
     return { available: false, version: null, reason: clean(error?.stderr || error?.message || error) }
   }

package/hermes-session.mjs

@@ -6,6 +6,7 @@ import { randomUUID } from 'node:crypto'
 import { AcpClient } from './acp-client.mjs'
 import { HermesEventMapper, hermesToolFor } from './hermes-event-mapper.mjs'
 import { probeHermesRuntime } from './hermes-probe.mjs'
+import { hermesExactInventory, hermesPolicyEnv, hermesRoleFor } from './hermes-policy.mjs'
 import { startCodexMcpHttp } from './codex-mcp-http.mjs'
 import { classifyRisk } from './claude-session.mjs'
 
@@ -44,7 +45,7 @@ export function startHermesSession({
   cwd, model, resume, env = process.env, mode = 'default', onEvent, requestPermission,
   roomContext, terminalRolePrompt, rolePrompt, mcpServers, requiredMcpTools = [], prepareCwd = null,
   command = HERMES_COMMAND, args = ['acp'], clientFactory = createAcpClient,
-  mcpHttpFactory = startCodexMcpHttp, lazy = false,
+  mcpHttpFactory = startCodexMcpHttp, lazy = false, hermesRole = null,
 } = {}) {
   let activeCwd = cwd
   const requestedModel = model || null
@@ -68,6 +69,7 @@ export function startHermesSession({
   let resuming = false
   let inventoryProbe = null
   let modelSwitchPending = false
+  const policyRole = hermesRole || hermesRoleFor({})
 
   const emit = (event) => { try { onEvent?.(event) } catch { /* consumer isolation */ } }
 
@@ -101,7 +103,14 @@ export function startHermesSession({
   async function probeMcpTools() {
     const required = [...new Set((Array.isArray(requiredMcpTools) ? requiredMcpTools : [])
       .map((name) => String(name || '').trim()).filter(Boolean))]
-    if (!required.length) return []
+    // Direct runtime tests and unscoped upstream callers have no bridge role
+    // contract to prove. Every bridge-created Hermes lane supplies its required
+    // MCP list; only those lanes enter the exact-inventory transaction.
+    if (!required.length) return { inventory: '', missing: [], forbidden: [] }
+    const exact = hermesExactInventory(policyRole, { mcpTools: required })
+    const allowedBuiltins = exact.builtinTools
+    const requiredBuiltins = exact.requiredBuiltinTools
+    const expectedMcp = exact.mcpTools
     const chunks = []
     inventoryProbe = chunks
     try {
@@ -112,7 +121,32 @@ export function startHermesSession({
       }, 30_000)
     } finally { inventoryProbe = null }
     const inventory = chunks.join('')
-    return required.filter((name) => !inventory.includes(`mcp__thinkpool__${name}`))
+    const has = (name) => new RegExp(`(?:^|[^a-z0-9_])${name}(?:$|[^a-z0-9_])`, 'i').test(inventory)
+    const mcpNames = [...inventory.matchAll(/\bmcp(?:__|_)[a-z0-9_]+/gi)].map((item) => item[0])
+    const expectedMcpNames = new Set(expectedMcp.flatMap((name) => [`mcp__thinkpool__${name}`, `mcp_thinkpool_${name}`]))
+    const unexpectedMcp = [...new Set(mcpNames.filter((name) => !expectedMcpNames.has(name)))]
+    // This is a zero-inference ACP inventory command. It proves the complete
+    // role schema (required built-ins plus exactly this lane's ThinkPool MCP
+    // set). Optional provider/browser capabilities may be absent, but any
+    // presented builtin outside the role allowlist is still a hard failure.
+    return {
+      inventory,
+      missing: [
+        ...requiredBuiltins.filter((name) => !has(name)),
+        ...expectedMcp.filter((name) => !has(`mcp__thinkpool__${name}`) && !has(`mcp_thinkpool_${name}`)),
+      ],
+      forbidden: [
+        ...exact.allBuiltinTools.filter((name) => !allowedBuiltins.includes(name) && has(name)),
+        ...unexpectedMcp,
+      ],
+    }
+  }
+
+  async function assertMcpReadiness() {
+    const probe = await probeMcpTools()
+    if (!probe.missing.length && !probe.forbidden.length) return probe
+    const details = [probe.missing.length ? `missing ${probe.missing.join(', ')}` : '', probe.forbidden.length ? `forbidden ${probe.forbidden.join(', ')}` : ''].filter(Boolean).join('; ')
+    throw new Error(`Hermes ThinkPool MCP readiness failed; ${details}`)
   }
 
   async function boot() {
@@ -126,18 +160,25 @@ export function startHermesSession({
       }
       const thinkpool = mcpServers?.thinkpool
       if (thinkpool && !mcpHttp) mcpHttp = await mcpHttpFactory({ sdkServer: thinkpool })
-      const childEnv = hermesChildEnv(env)
+      let childEnv = hermesChildEnv(env)
+      let launchCommand = command
+      let launchArgs = args
       // The bridge advertises Hermes only after this probe, but lazy lanes may
       // boot much later. Re-check immediately before every real ACP process so
       // a removed/changed delegation hook cannot ride a stale startup verdict.
       if (command === HERMES_COMMAND && clientFactory === createAcpClient) {
-        const profile = probeHermesRuntime({ command, env: childEnv })
+        const profile = probeHermesRuntime({ command, env: childEnv, strictBootstrap: true })
         if (!profile.available) throw new Error(`Hermes profile safety check failed: ${profile.reason || 'runtime unavailable'}`)
+        // The executable is the installed venv Python, never the mutable
+        // profile wrapper. HERMES_HOME is the probe-verified isolated profile.
+        launchCommand = profile.python
+        launchArgs = [profile.bootstrap]
+        childEnv = { ...childEnv, HERMES_HOME: profile.profile, THINKPOOL_HERMES_ACP_POLICY: hermesPolicyEnv(policyRole, { mcpTools: requiredMcpTools }) }
       }
       let retired = false
       retireClient = () => { retired = true }
       client = clientFactory({
-        command, args, cwd: activeCwd, env: childEnv,
+        command: launchCommand, args: launchArgs, cwd: activeCwd, env: childEnv,
         onNotification,
         onRequest,
         onStderr: (text) => { stderrTail = (stderrTail + text).slice(-2000) },
@@ -175,7 +216,8 @@ export function startHermesSession({
       } else state = await client.request('session/new', params, 30_000)
       if (!sessionId) sessionId = state?.sessionId || null
       if (!sessionId) throw new Error('Hermes ACP did not return a session id')
-      let missingMcpTools = await probeMcpTools()
+      let toolProbe = await probeMcpTools()
+      let missingMcpTools = toolProbe.missing
       // Hermes treats ACP-provided MCP registration as non-fatal. A transient
       // first connection can therefore leave an otherwise healthy session with
       // only built-in tools. Re-running the released resume lifecycle retries
@@ -186,10 +228,12 @@ export function startHermesSession({
           resuming = true
           state = await client.request('session/resume', { ...params, sessionId }, 30_000)
         } finally { resuming = false }
-        missingMcpTools = await probeMcpTools()
+        toolProbe = await probeMcpTools()
+        missingMcpTools = toolProbe.missing
       }
-      if (missingMcpTools.length) {
-        throw new Error(`Hermes ThinkPool MCP readiness failed; missing ${missingMcpTools.join(', ')}`)
+      if (missingMcpTools.length || toolProbe.forbidden.length) {
+        const details = [missingMcpTools.length ? `missing ${missingMcpTools.join(', ')}` : '', toolProbe.forbidden.length ? `forbidden ${toolProbe.forbidden.join(', ')}` : ''].filter(Boolean).join('; ')
+        throw new Error(`Hermes ThinkPool MCP readiness failed; ${details}`)
       }
       const serverModel = state?.models?.currentModelId || null
       activeModel = requestedModel || serverModel || activeModel
@@ -197,8 +241,9 @@ export function startHermesSession({
       // ACP catalog. Acknowledge that model BEFORE publishing the initial system/
       // models events; otherwise the worker runs the requested model while the UI
       // and persisted resume record lie that it still uses the profile default.
-      if (requestedModel && requestedModel !== serverModel) {
+      if (requestedModel) {
         await client.request('session/set_model', { sessionId, modelId: activeModel })
+        await assertMcpReadiness()
       }
       const publishedModels = state?.models
         ? { ...state.models, currentModelId: activeModel }
@@ -209,7 +254,7 @@ export function startHermesSession({
       if (state?.modes?.availableModes?.some((item) => item.id === acpMode) && state.modes.currentModeId !== acpMode) {
         await client.request('session/set_mode', { sessionId, modeId: acpMode })
       }
-      emit({ kind: 'capabilities', runtime: 'hermes', protocol: 'acp', protocolVersion: initialized?.protocolVersion, capabilities: initialized?.agentCapabilities || {}, models: modelList(state?.models), flow: false })
+      emit({ kind: 'capabilities', runtime: 'hermes', protocol: 'acp', protocolVersion: initialized?.protocolVersion, capabilities: initialized?.agentCapabilities || {}, models: modelList(state?.models), flow: command === HERMES_COMMAND && clientFactory === createAcpClient })
     })().catch((error) => {
       crashed = true
       client?.end()
@@ -328,7 +373,11 @@ export function startHermesSession({
       if (!nextModel || turnActive || modelSwitchPending) return false
       const requested = String(nextModel)
       modelSwitchPending = true
-      void boot().then(() => client.request('session/set_model', { sessionId, modelId: requested })).then(() => {
+      void boot().then(() => client.request('session/set_model', { sessionId, modelId: requested })).then(async () => {
+        // 0.18.2 reconstructs state.agent during set_model.  The bootstrap
+        // re-registers its MCP; this independent zero-inference /tools check is
+        // the transaction's acknowledgement boundary.
+        await assertMcpReadiness()
         if (ended) return
         activeModel = requested
         if (mapper) mapper.model = activeModel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.246",
+  "version": "0.7.247",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -24,6 +24,8 @@
     "codex-event-mapper.mjs",
     "acp-client.mjs",
     "hermes-session.mjs",
+    "hermes-policy.mjs",
+    "hermes-acp-bootstrap.py",
     "hermes-event-mapper.mjs",
     "hermes-probe.mjs",
     "hermes-setup.mjs",
@@ -56,6 +58,7 @@
     "viewport.mjs",
     "design-edit.mjs",
     "flow-review.mjs",
+    "review-check.mjs",
     "flow-review-gate.mjs",
     "flow-review-reflect.mjs",
     "flow-assembly.mjs",

package/review-check.mjs

@@ -0,0 +1,155 @@
+// Fixed, bridge-owned review checks. Models receive only { target, checkId }.
+// This is host execution parity with Claude/Codex Flow, not a malicious-code sandbox.
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+const CHECKS = Object.freeze({
+  'node-test': ['node', ['--test']], 'npm-test': ['npm', ['test']],
+  'npm-build': ['npm', ['run', 'build']], pytest: ['pytest', []],
+  'cargo-test': ['cargo', ['test']], 'go-test': ['go', ['test', './...']],
+})
+const OUTPUT_CAP = 512 * 1024
+
+export function reviewCheckCommand(checkId) {
+  if (!Object.hasOwn(CHECKS, checkId)) throw new Error('unapproved review check')
+  const [command, args] = CHECKS[checkId]
+  return { command, args: [...args] }
+}
+
+export async function reviewCheckEnv(env = process.env, root = null) {
+  root ||= await fsp.mkdtemp(path.join(os.tmpdir(), 'tp-review-env-'))
+  const keptPath = env.PATH || process.env.PATH || ''
+  const home = path.join(root, 'home')
+  const npmCache = path.join(root, 'npm-cache')
+  const tmp = path.join(root, 'tmp')
+  await Promise.all([fsp.mkdir(home, { recursive: true }), fsp.mkdir(npmCache, { recursive: true }), fsp.mkdir(tmp, { recursive: true })])
+  return { PATH: keptPath, HOME: home, TMPDIR: path.join(root, 'tmp'), npm_config_cache: npmCache, npm_config_userconfig: path.join(home, '.npmrc'), GIT_CONFIG_NOSYSTEM: '1' }
+}
+
+export function validateReviewTarget(target, snapshots) {
+  if (typeof target !== 'string' || !/^[a-z0-9-]{1,64}$/.test(target)) throw new Error('invalid reviewed target')
+  const snapshot = (Array.isArray(snapshots) ? snapshots : []).find((item) => item?.taskKey === target)
+  if (!snapshot || !/^[0-9a-f]{40}$/i.test(snapshot.sha) || !path.isAbsolute(snapshot.cwd || '')) throw new Error('reviewed target is not pinned')
+  return snapshot
+}
+
+export function validateReviewPath(filePath) {
+  if (typeof filePath !== 'string' || !filePath || filePath.length > 512 || path.posix.isAbsolute(filePath)) throw new Error('invalid review path')
+  const normalized = path.posix.normalize(filePath)
+  if (normalized === '.' || normalized === '..' || normalized.startsWith('../') || normalized.split('/').some((part) => !part || part === '.')) throw new Error('invalid review path')
+  return normalized
+}
+
+// Read the pinned Git blob, never the reviewer worktree.  git ls-tree refuses
+// directories and symlinks before git show is allowed to materialize bytes.
+export async function readReviewFile({ target, filePath, snapshots, maxBytes = 512 * 1024 } = {}) {
+  const snapshot = validateReviewTarget(target, snapshots)
+  const normalized = validateReviewPath(filePath)
+  const cap = Number.isInteger(maxBytes) && maxBytes > 0 && maxBytes <= 512 * 1024 ? maxBytes : 512 * 1024
+  const listed = await execFileAsync('git', ['-C', snapshot.cwd, 'ls-tree', '-z', snapshot.sha, '--', normalized], { encoding: 'buffer', maxBuffer: 1024 * 1024 })
+  const record = Buffer.from(listed.stdout).toString('utf8').split('\0').filter(Boolean)[0] || ''
+  const match = /^(100[0-7]{3}) blob ([0-9a-f]{40})\t(.+)$/.exec(record)
+  if (!match || match[3] !== normalized) throw new Error('review file is not a pinned regular file')
+  const shown = await execFileAsync('git', ['-C', snapshot.cwd, 'show', `${snapshot.sha}:${normalized}`], { encoding: 'buffer', maxBuffer: cap + 1 })
+  const bytes = Buffer.from(shown.stdout)
+  if (bytes.length > cap) throw new Error('review file exceeds byte limit')
+  return { target, sha: snapshot.sha, path: normalized, content: bytes.toString('utf8'), bytes: bytes.length }
+}
+
+function boundedPush(parts, value) {
+  const text = String(value || '')
+  parts.push(text)
+  let total = parts.reduce((n, part) => n + part.length, 0)
+  while (total > OUTPUT_CAP && parts.length) total -= parts.shift().length
+}
+
+export async function killTree(child, signal = 'SIGTERM', { platform = process.platform, spawnImpl = spawn, taskkillTimeoutMs = 1_000 } = {}) {
+  if (!child?.pid) return true
+  if (platform === 'win32' && signal === 'SIGKILL') {
+    // Windows has no process-group equivalent.  This is trusted-host parity,
+    // not unescapable process-tree isolation. taskkill itself can hang on a
+    // hostile/broken host, so race it: cleanup remains best-effort and the
+    // review request always settles.
+    return await new Promise((resolve) => {
+      let done = false
+      let timer = null
+      const finish = (ok) => {
+        if (done) return
+        done = true
+        if (timer) clearTimeout(timer)
+        resolve(ok)
+      }
+      try {
+        const taskkill = spawnImpl('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true })
+        taskkill.once('close', (code) => finish(code === 0))
+        taskkill.once('error', () => finish(false))
+        timer = setTimeout(() => { try { taskkill.kill?.() } catch {} finish(false) }, taskkillTimeoutMs)
+      } catch { finish(false) }
+    })
+  }
+  try { platform === 'win32' ? child.kill(signal) : process.kill(-child.pid, signal); return true } catch { try { return child.kill(signal) } catch { return false } }
+}
+
+export function runProcess(command, args, { cwd, env, timeoutMs = 120_000, killGraceMs = 250 } = {}) {
+  return new Promise((resolve) => {
+    const stdout = [], stderr = []
+    let timedOut = false
+    let settled = false
+    let child
+    let timer = null
+    let forceTimer = null
+    let settleTimer = null
+    const settle = (code) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      if (forceTimer) clearTimeout(forceTimer)
+      if (settleTimer) clearTimeout(settleTimer)
+      resolve({ exitCode: Number.isInteger(code) ? code : null, stdout: stdout.join('').slice(-OUTPUT_CAP), stderr: stderr.join('').slice(-OUTPUT_CAP), timedOut })
+    }
+    try { child = spawn(command, args, { cwd, env, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] }) }
+    catch (error) { stderr.push(String(error?.message || error)); settle(null); return }
+    child.stdout.on('data', (value) => boundedPush(stdout, value))
+    child.stderr.on('data', (value) => boundedPush(stderr, value))
+    timer = setTimeout(() => {
+      timedOut = true; void killTree(child)
+      forceTimer = setTimeout(async () => {
+        if (!await killTree(child, 'SIGKILL')) boundedPush(stderr, 'review check cleanup could not confirm process-tree termination')
+        // SIGKILL is unconditional on POSIX, but a platform/process failure must
+        // not leave the MCP call pending forever. A second best-effort kill then
+        // settles the caller; the scratch finally block can run.
+        settleTimer = setTimeout(() => {
+          void killTree(child, 'SIGKILL')
+          boundedPush(stderr, 'review check process did not report close after forced termination')
+          settle(null)
+        }, 1_000)
+      }, killGraceMs)
+    }, timeoutMs)
+    child.once('error', (error) => boundedPush(stderr, error?.message || error))
+    child.once('close', (code) => settle(code))
+  })
+}
+
+export async function runReviewCheck({ target, checkId, snapshots, env = process.env, tmpdir = os.tmpdir(), timeoutMs } = {}) {
+  const snapshot = validateReviewTarget(target, snapshots)
+  const archiveDir = await fsp.mkdtemp(path.join(tmpdir, 'tp-review-'))
+  const archive = path.join(archiveDir, 'source.tar')
+  const scratch = path.join(archiveDir, 'tree')
+  try {
+    await fsp.mkdir(scratch)
+    const archiveResult = await runProcess('git', ['-C', snapshot.cwd, 'archive', '--format=tar', `--output=${archive}`, snapshot.sha], { env: await reviewCheckEnv(env, archiveDir), timeoutMs: 15_000 })
+    if (archiveResult.exitCode !== 0 || archiveResult.timedOut) return { pass: false, target, sha: snapshot.sha, command: ['git', 'archive'], exitCode: archiveResult.exitCode, ...archiveResult }
+    const extract = await runProcess('tar', ['-xf', archive, '-C', scratch], { env: await reviewCheckEnv(env, archiveDir), timeoutMs: 15_000 })
+    if (extract.exitCode !== 0 || extract.timedOut) return { pass: false, target, sha: snapshot.sha, command: ['tar', '-xf'], exitCode: extract.exitCode, ...extract }
+    const spec = reviewCheckCommand(checkId)
+    const result = await runProcess(spec.command, spec.args, { cwd: scratch, env: await reviewCheckEnv(env, archiveDir), timeoutMs })
+    return { pass: result.exitCode === 0 && !result.timedOut, target, sha: snapshot.sha, command: [spec.command, ...spec.args], ...result }
+  } finally { await fsp.rm(archiveDir, { recursive: true, force: true }) }
+}

package/runtime-registry.mjs

@@ -13,7 +13,7 @@ const RUNTIMES = Object.freeze({
   }),
   hermes: Object.freeze({
     id: 'hermes', command: 'thinkpool', label: 'Hermes Agent', protocol: 'acp',
-    structured: true, flow: false, canSteer: true, images: true, nativeModelCatalog: true, catalogRequiresSession: true, effortControl: false, defaultMode: 'default',
+    structured: true, flow: true, canSteer: true, images: true, nativeModelCatalog: true, catalogRequiresSession: true, effortControl: false, defaultMode: 'default',
     modes: Object.freeze(['default', 'acceptEdits']),
     beta: true,
   }),