thinkpool-pair 0.7.240 → 0.7.242

package/bridge.mjs

@@ -105,7 +105,7 @@ const flowRedispatch = new Map()
 // wave BEFORE overrun. Lives bridge-side because waves dispatch across separate
 // broadcasts; without persistent state the cap can never bite.
 const flowBudgets = new Map()
-import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, SPAWN, CROSSROOM, formatPairRoster, crossRoomPostDecision, formatRoomNow, formatClosableHint, laneStatusOf } from './cross-terminal.mjs'
+import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, SPAWN, CROSSROOM, formatPairRoster, crossRoomPostDecision, formatRoomNow, formatClosableHint, laneStatusOf, nativeClaudeFallbackHint } from './cross-terminal.mjs'
 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'
@@ -114,7 +114,7 @@ import { SIDE_HANDOFF_PROMPT, SIDE_ROLE_PROMPT, appendSideContext, assistantText
 import { planMeterLine } from './plan-meters.mjs'
 import { makeThrottledTrack } from './presence.mjs'
 import { resolveAnonKey, DEFAULT_SUPABASE_URL } from './supabase-key.mjs'
-import { buildTerminalRolePrompt } from './thinkpool-room-prompt.mjs'
+import { buildTerminalRolePrompt, HERMES_VISIBLE_WORKER_FALLBACK_RULE } from './thinkpool-room-prompt.mjs'
 
 // Public client creds (the same anon values the web app ships — safe to embed).
 // Override with TP_SUPABASE_URL / TP_SUPABASE_ANON if you ever need to.
@@ -2014,10 +2014,19 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
   const resolveAgentOpen = (args, { worker = false } = {}) => {
     const runtime = args?.runtime || entry.runtime || 'claude'
     if (runtime === 'codex' && args?.provider) return { error: 'A Codex terminal uses its Codex/OpenAI login in v1; custom bridge providers are not wired to Codex yet. Omit provider or open a Claude terminal for that provider.' }
-    const catalog = runtime === 'codex' ? readCodexModels() : []
+    if (runtime === 'hermes' && args?.provider) return { error: 'A Hermes terminal uses its isolated Hermes profile and ACP model catalog; bridge provider IDs do not apply. Omit provider and choose an exact Hermes model ID.' }
+    if (runtime === 'hermes' && (!worker || entry.runtime !== 'hermes')) return { error: 'A Hermes worker can only be opened by a top-level Hermes terminal with a live ACP model catalog.' }
+    const catalog = runtime === 'codex' ? readCodexModels() : runtime === 'hermes' ? (entry.models || []) : []
     if (runtime === 'codex' && args?.model && !modelCatalogValues(catalog).has(args.model)) {
       return { error: `Could not open a Codex terminal on ${JSON.stringify(args.model)} — that model is not in this host's visible Codex catalog.` }
     }
+    if (runtime === 'hermes' && !args?.model) return { error: 'Opening a Hermes worker requires an explicit exact model ID from this session\'s ACP catalog.' }
+    if (runtime === 'hermes' && !modelCatalogValues(catalog).has(args.model)) {
+      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.` }
+    }
     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.` }
     }
@@ -2070,7 +2079,11 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           if (entry.peekCount > PEEK.perTurnCap) {
             return { content: [{ type: 'text', text: `Cross-terminal read limit reached for this turn (${PEEK.perTurnCap}). Continue with what you have, or ask the people in the room.` }] }
           }
+          const sib = siblingsOf({ selfId: id, sessions, terms, names: termNames })
+          const target = args?.terminal ? resolveSibling(sib, args.terminal) : null
+          const targetEntry = target?.kind === 'agent' ? sessions.get(target.id) : null
           const text = formatPeek({ selfId: id, sessions, terms, names: termNames, terminal: args?.terminal, lines: args?.lines })
+            + nativeClaudeFallbackHint({ parentRuntime: entry.runtime, parentModels: entry.models, targetRuntime: targetEntry?.runtime, targetLog: targetEntry?.log })
           return { content: [{ type: 'text', text }] }
         },
       ),
@@ -2252,13 +2265,13 @@ 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 WORKER SUB-TERMINAL (Claude or Codex) 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. 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. 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.',
         {
           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'),
-          model: z.string().optional().describe('optional model for the chosen runtime, e.g. opus / sonnet / gpt-5.6-sol'),
+          model: z.string().optional().describe('model for the chosen runtime; Hermes workers require an exact ACP catalog ID such as nous:anthropic/claude-sonnet-4.6'),
           sliceType: z.enum(['scaffold', 'feature', 'fix', 'review']).optional().describe('optional cascade slice tier; omitted preserves normal inheritance/default, explicit model wins'),
-          runtime: z.enum(['claude', 'codex']).optional().describe('agent runtime for the new lane; defaults to inheriting this lane'),
+          runtime: z.enum(['claude', 'codex', 'hermes']).optional().describe('agent runtime for the new lane; Hermes is allowed only from a top-level Hermes parent with an explicit catalog model'),
           provider: z.string().optional().describe('optional registered LLM provider id to run this lane on (from the account\'s provider registry); omit for the default Claude/Anthropic path'),
           mode: z.enum(['default', 'acceptEdits', 'bypassPermissions', 'plan']).optional().describe('permission mode for the new lane; defaults to inheriting YOUR current mode. Raising a lane to bypassPermissions from a non-bypass lane asks the room to confirm once.'),
         },
@@ -2446,13 +2459,13 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
   // on the init `system` event (see onEvent) — a sendTurn before the input stream is consumed
   // is silently lost (the 2026-07-02 auto-resume bug). Empty string → nothing to carry.
   entry.pendingRecap = (typeof carryRecap === 'string' && carryRecap.trim()) ? carryRecap : null
-  const terminalRolePrompt = buildTerminalRolePrompt({
+  const terminalRolePrompt = [buildTerminalRolePrompt({
     spawnedBy: entry.spawnedBy,
     spawnDepth: entry.spawnDepth,
     cascadeRole: entry.cascadeRole,
     flowRole: entry.flowRole,
     sideParent: entry.sideParent,
-  })
+  }), runtime === 'hermes' && canSpawnWorkers ? HERMES_VISIBLE_WORKER_FALLBACK_RULE : ''].filter(Boolean).join('\n\n')
   entry.session = startStructuredSession(runtime, {
     // laneModel, NOT the raw `model` param: the SDK's `model` option OVERRIDES the
     // ANTHROPIC_MODEL supplied by resolveProviderEnv() in `env` below, so an inherited
@@ -2513,6 +2526,13 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
     // FL-B4 — a review lane records its verdict via FLOW_REVIEW.json (revert-on-fail).
     onReviewVerdict: entry.flowRole === 'reviewer' ? onReviewVerdict : null,
     mcpServers: { thinkpool: peekServer },
+    // Hermes' ACP MCP registration is intentionally non-fatal upstream. Make
+    // ThinkPool's room-tool contract stricter: a lane must prove its actual
+    // 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'] : [])]
+      : 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' }),

package/cross-terminal.mjs

@@ -223,6 +223,47 @@ export const formatPeek = ({ selfId, sessions, terms, names = {}, terminal, line
   return `Terminal ${label(hit)} (${hit.kind} · ${hit.cmd}) — last ${n} lines:\n${body}`
 }
 
+// A native Claude Code account failure is provider-wide, not model-specific. Retrying
+// Sonnet → Opus → Haiku on the same built-in Anthropic path only repeats the same
+// failure and burns orchestration time. Keep this classifier deliberately narrow:
+// transient model/rate/overload errors must not disable the whole provider.
+export const nativeClaudeProviderAccessFailed = (events) => {
+  let text = ''
+  try { text = typeof events === 'string' ? events : JSON.stringify(events || '') }
+  catch { text = String(events || '') }
+  return /organization has disabled (?:claude )?subscription access|(?:claude )?subscription access (?:has been |is )?disabled|invalid anthropic (?:api )?key|invalid x-api-key|not logged in to claude|(?:run|use) \/login[^\n]{0,80}claude|no valid anthropic (?:api )?key/i.test(text)
+}
+
+const HERMES_CLAUDE_REVIEW_PREFERENCE = Object.freeze([
+  'nous:anthropic/claude-sonnet-4.6',
+  'nous:anthropic/claude-sonnet-4.5',
+  'nous:anthropic/claude-sonnet-4',
+])
+
+export const preferredHermesClaudeReviewModel = (models = []) => {
+  const values = new Set((Array.isArray(models) ? models : []).map((model) => (
+    typeof model === 'string' ? model : model?.value || model?.slug
+  )).filter(Boolean))
+  for (const model of HERMES_CLAUDE_REVIEW_PREFERENCE) if (values.has(model)) return model
+  for (const model of values) if (/^nous:anthropic\/claude-sonnet-/i.test(model)) return model
+  for (const model of values) if (/^nous:anthropic\/claude-haiku-/i.test(model)) return model
+  for (const model of values) if (/^nous:anthropic\/claude-opus-/i.test(model)) return model
+  return null
+}
+
+// Returned alongside read_terminal output so the orchestrator gets a structural
+// provider verdict at the exact moment it observes the failed worker. A Hermes
+// fallback is a visible ordinary worker, never hidden delegate_task and never Flow.
+// Hermes ACP 0.18.2 cannot enforce read-only review, so the note states the honest
+// permission-gated boundary instead of pretending mode="default" is structural plan.
+export const nativeClaudeFallbackHint = ({ parentRuntime, parentModels, targetRuntime, targetLog } = {}) => {
+  if (targetRuntime !== 'claude' || !nativeClaudeProviderAccessFailed(targetLog)) return ''
+  const stop = 'ThinkPool provider status: native Claude access failed at the account/provider level. Do not retry Sonnet, Opus, Haiku, or another model alias on the same native Claude provider during this task.'
+  const fallback = parentRuntime === 'hermes' ? preferredHermesClaudeReviewModel(parentModels) : null
+  if (!fallback) return `\n\n${stop} Use a different available runtime/provider once, or report the blocker.`
+  return `\n\n${stop} For a visible manual review fallback, spawn exactly one worker with runtime="hermes", model=${JSON.stringify(fallback)}, mode="default", and sliceType="review". This Hermes lane is permission-gated, not structurally read-only: instruct it not to edit, deny/stop any write request, and do not treat its review as a Flow safety proof. Never use Hermes delegate_task.`
+}
+
 // ── Live per-turn room snapshot ("ROOM NOW") ─────────────────────────────────
 // The compact tail claude-session appends to EVERY user turn's <system-reminder>
 // (via the bridge's roomContext callback), so a lane sees the room's CURRENT

package/hermes-session.mjs

@@ -42,7 +42,7 @@ const permissionOutcome = (decision, options = []) => {
 
 export function startHermesSession({
   cwd, model, resume, env = process.env, mode = 'default', onEvent, requestPermission,
-  roomContext, terminalRolePrompt, rolePrompt, mcpServers, prepareCwd = null,
+  roomContext, terminalRolePrompt, rolePrompt, mcpServers, requiredMcpTools = [], prepareCwd = null,
   command = HERMES_COMMAND, args = ['acp'], clientFactory = createAcpClient,
   mcpHttpFactory = startCodexMcpHttp, lazy = false,
 } = {}) {
@@ -66,6 +66,7 @@ export function startHermesSession({
   const abortedTurns = new Set()
   let retireClient = () => {}
   let resuming = false
+  let inventoryProbe = null
   let modelSwitchPending = false
 
   const emit = (event) => { try { onEvent?.(event) } catch { /* consumer isolation */ } }
@@ -87,10 +88,33 @@ export function startHermesSession({
   function onNotification(method, params) {
     if (method !== 'session/update') return
     const update = params?.update || params
+    if (inventoryProbe) {
+      if (update?.sessionUpdate === 'agent_message_chunk' && update?.content?.type === 'text') {
+        inventoryProbe.push(String(update.content.text || ''))
+      }
+      return
+    }
     if (resuming && HERMES_REPLAY_UPDATES.has(update?.sessionUpdate)) return
     mapper?.push(params)
   }
 
+  async function probeMcpTools() {
+    const required = [...new Set((Array.isArray(requiredMcpTools) ? requiredMcpTools : [])
+      .map((name) => String(name || '').trim()).filter(Boolean))]
+    if (!required.length) return []
+    const chunks = []
+    inventoryProbe = chunks
+    try {
+      await client.request('session/prompt', {
+        sessionId,
+        prompt: [{ type: 'text', text: '/tools' }],
+        messageId: randomUUID(),
+      }, 30_000)
+    } finally { inventoryProbe = null }
+    const inventory = chunks.join('')
+    return required.filter((name) => !inventory.includes(`mcp__thinkpool__${name}`))
+  }
+
   async function boot() {
     if (ended) throw new Error('Hermes session is closed')
     if (crashed) throw new Error('Hermes ACP process crashed; this lane must be restarted before sending another turn')
@@ -151,13 +175,36 @@ 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()
+      // 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
+      // registration without inventing a new native identity. Bound this to one
+      // retry, then fail closed before any user prompt reaches a tool-less lane.
+      if (missingMcpTools.length && initialized?.agentCapabilities?.sessionCapabilities?.resume) {
+        try {
+          resuming = true
+          state = await client.request('session/resume', { ...params, sessionId }, 30_000)
+        } finally { resuming = false }
+        missingMcpTools = await probeMcpTools()
+      }
+      if (missingMcpTools.length) {
+        throw new Error(`Hermes ThinkPool MCP readiness failed; missing ${missingMcpTools.join(', ')}`)
+      }
       const serverModel = state?.models?.currentModelId || null
       activeModel = requestedModel || serverModel || activeModel
-      mapper.startSession({ sessionId, models: state?.models, modes: state?.modes, commands: [] })
-      started = true
-      if (requestedModel && serverModel && requestedModel !== serverModel) {
+      // A spawned Hermes worker may be pinned to an exact model from its parent's
+      // 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) {
         await client.request('session/set_model', { sessionId, modelId: activeModel })
       }
+      const publishedModels = state?.models
+        ? { ...state.models, currentModelId: activeModel }
+        : activeModel ? { currentModelId: activeModel, availableModels: [] } : state?.models
+      mapper.startSession({ sessionId, models: publishedModels, modes: state?.modes, commands: [] })
+      started = true
       const acpMode = activeMode === 'acceptEdits' ? 'accept_edits' : 'default'
       if (state?.modes?.availableModes?.some((item) => item.id === acpMode) && state.modes.currentModeId !== acpMode) {
         await client.request('session/set_mode', { sessionId, modeId: acpMode })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.240",
+  "version": "0.7.242",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {

package/thinkpool-room-prompt.mjs

@@ -57,3 +57,9 @@ export const CODEX_THINKPOOL_FIRST_TURN_PREAMBLE = [
   'MODEL TIERING FOR TERMINALS: When calling open_main_terminal for a genuinely complex Cascade conductor, gpt-5.6-sol may be appropriate. When calling spawn_terminal for worker slices, explicitly choose gpt-5.6-luna or gpt-5.4-mini for mechanical/scaffold/search/formatting work, gpt-5.6-terra for ordinary feature/fix work, and a balanced tier for adversarial review. Never select Sol for routine workers. If a named model is unavailable, use the nearest advertised lower tier or omit model and allow runtime fallback.',
   ...THINKPOOL_REMOTE_DELIVERY_RULES,
 ].join(' ')
+
+// Hermes mains can dispatch visible ordinary workers, including a Claude-family
+// model served through the parent's Nous Portal catalog when native Claude Code
+// account access is unavailable. This is manual orchestration only: ACP 0.18.2
+// does not expose structural read-only review policy, and Flow remains disabled.
+export const HERMES_VISIBLE_WORKER_FALLBACK_RULE = 'HERMES VISIBLE-WORKER FALLBACK: spawn_terminal may open a visible Hermes worker only from a top-level Hermes terminal and only with an explicit exact model ID advertised in this session\'s ACP catalog. If a native Claude Code worker reports an account/provider authentication or subscription-access failure, treat the entire native Claude provider as unavailable for the rest of the task—do not retry Sonnet, Opus, or Haiku aliases on it. For a manual Claude-family review fallback, use runtime="hermes", the exact Nous Claude model suggested by read_terminal, mode="default", and sliceType="review". This fallback is permission-gated, not structurally read-only: instruct it not to edit, stop/deny any write request, and never call it Flow/reviewer safety. Never use hidden Hermes delegate_task.'