thinkpool-pair 0.7.233 → 0.7.235

package/acp-client.mjs

@@ -0,0 +1,140 @@
+// Runtime-neutral supervised ACP stdio client. Protocol framing, JSON-RPC,
+// cancellation, typed client handlers, and schemas come from the official ACP
+// SDK. ThinkPool owns only subprocess supervision and its stricter stdout rule.
+import { spawn } from 'node:child_process'
+import { Readable, Transform, Writable } from 'node:stream'
+import * as acp from '@agentclientprotocol/sdk'
+
+const closedError = (value, fallback = 'ACP process closed') => value instanceof Error
+  ? value
+  : new Error(String(value || fallback))
+
+function strictProtocolGate(onError) {
+  let buffered = ''
+  const validate = (line) => {
+    if (!line.trim()) return
+    let message
+    try { message = JSON.parse(line) } catch { throw new Error('ACP stdout contained non-JSON protocol data') }
+    if (!message || typeof message !== 'object' || Array.isArray(message)) {
+      throw new Error('ACP stdout contained invalid JSON-RPC protocol data')
+    }
+    const hasId = Object.prototype.hasOwnProperty.call(message, 'id')
+    const hasMethod = typeof message.method === 'string' && message.method.length > 0
+    const hasResult = Object.prototype.hasOwnProperty.call(message, 'result')
+    const hasError = Object.prototype.hasOwnProperty.call(message, 'error')
+    const isCall = hasMethod && !(hasResult || hasError)
+    const isResponse = hasId && !hasMethod && hasResult !== hasError
+    if (message.jsonrpc !== '2.0' || (!isCall && !isResponse)) {
+      throw new Error('ACP stdout contained invalid JSON-RPC protocol data')
+    }
+  }
+  const gate = new Transform({
+    transform(chunk, _encoding, callback) {
+      try {
+        buffered += String(chunk)
+        const lines = buffered.split('\n')
+        buffered = lines.pop() || ''
+        for (const line of lines) validate(line)
+        callback(null, chunk)
+      } catch (error) { callback(error) }
+    },
+    flush(callback) {
+      try { validate(buffered); callback(null, buffered || undefined) }
+      catch (error) { callback(error) }
+    },
+  })
+  gate.on('error', onError)
+  return gate
+}
+
+export class AcpClient {
+  constructor({ command, args = ['acp'], cwd, env = process.env, spawnImpl = spawn, onNotification, onRequest, onStderr, onClose, timeoutMs = 10_000 } = {}) {
+    this.command = command
+    this.args = args
+    this.cwd = cwd
+    this.env = env
+    this.spawnImpl = spawnImpl
+    this.onNotification = onNotification
+    this.onRequest = onRequest
+    this.onStderr = onStderr
+    this.onClose = onClose
+    this.timeoutMs = timeoutMs
+    this.child = null
+    this.connection = null
+    this.closedError = null
+    this.stderrTail = ''
+  }
+
+  get alive() { return !!this.child && !!this.connection && !this.closedError }
+
+  start() {
+    if (this.child) return
+    const child = this.spawnImpl(this.command, this.args, { cwd: this.cwd, env: this.env, stdio: ['pipe', 'pipe', 'pipe'] })
+    this.child = child
+    child.stderr?.on?.('data', (chunk) => {
+      const text = String(chunk)
+      this.stderrTail = (this.stderrTail + text).slice(-2000)
+      try { this.onStderr?.(text) } catch { /* consumer isolation */ }
+    })
+
+    const failProtocol = (error) => {
+      const failure = closedError(error, 'ACP protocol stream failed')
+      this.connection?.close(failure)
+      this._close(failure)
+      try { child.kill('SIGTERM') } catch { /* noop */ }
+    }
+    const protocolOutput = strictProtocolGate(failProtocol)
+    child.stdout.pipe(protocolOutput)
+    const stream = acp.ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(protocolOutput))
+    const app = acp.client({ name: 'thinkpool-pair' })
+      .onRequest(acp.methods.client.session.requestPermission, ({ params, requestId }) => {
+        if (!this.onRequest) throw Object.assign(new Error('Unsupported ACP client method: session/request_permission'), { code: -32601 })
+        return this.onRequest(acp.methods.client.session.requestPermission, params, requestId)
+      })
+      .onNotification(acp.methods.client.session.update, ({ params }) => {
+        try { this.onNotification?.(acp.methods.client.session.update, params) } catch { /* consumer isolation */ }
+      })
+    this.connection = app.connect(stream)
+    void this.connection.closed.then(() => {
+      if (!this.closedError) this._close(closedError(this.connection?.signal?.reason))
+    })
+
+    child.stdin?.on?.('error', (error) => this._close(error))
+    child.on('error', (error) => this._close(error))
+    child.on('close', (code, signal) => this._close(new Error(`ACP process exited ${code ?? signal ?? 'unknown'}${this.stderrTail ? `: ${this.stderrTail.trim().slice(-300)}` : ''}`)))
+  }
+
+  request(method, params = {}, timeoutMs = this.timeoutMs) {
+    if (!this.connection || this.closedError) return Promise.reject(this.closedError || new Error('ACP process is not running'))
+    const controller = new AbortController()
+    const request = this.connection.agent.request(method, params, { cancellationSignal: controller.signal })
+    if (!(timeoutMs > 0)) return request
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        controller.abort(new Error(`${method} timed out after ${timeoutMs}ms`))
+        reject(new Error(`${method} timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
+      timer.unref?.()
+      request.then(resolve, reject).finally(() => clearTimeout(timer))
+    })
+  }
+
+  notify(method, params) {
+    if (!this.connection || this.closedError) return Promise.reject(this.closedError || new Error('ACP process is not running'))
+    return this.connection.agent.notify(method, params)
+  }
+
+  _close(error) {
+    if (this.closedError) return
+    this.closedError = closedError(error)
+    this.child = null
+    this.connection?.close(this.closedError)
+    try { this.onClose?.(this.closedError) } catch { /* consumer isolation */ }
+  }
+
+  end() {
+    const child = this.child
+    this._close(new Error('ACP client ended'))
+    if (child) { try { child.kill('SIGTERM') } catch { /* noop */ } }
+  }
+}

package/agent-detect.mjs

@@ -5,7 +5,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 
 export const KNOWN_AGENT_COMMANDS = [
-  'claude', 'codex', 'gemini', 'aider', 'cursor-agent',
+  'claude', 'codex', 'thinkpool', 'gemini', 'aider', 'cursor-agent',
   'opencode', 'copilot', 'goose', 'crush', 'qwen',
 ]
 

package/bridge.mjs

@@ -49,8 +49,10 @@ import { resolveProviderEnv, providerNameMap, publicKeyB64, announceProviders, l
 import { validateProviderSwitch, providerSwitchPlan, BUILTIN_PROVIDER } from './switch-provider.mjs'
 import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
 import { z } from 'zod'
-import { startClaudeSession } from './claude-session.mjs'
-import { startCodexSession, readCodexDefaultModel, readCodexModels, codexConfigForMode, codexThreadCanResume, defaultModeForRuntime } from './codex-session.mjs'
+import { readCodexDefaultModel, readCodexModels, codexConfigForMode, codexThreadCanResume } from './codex-session.mjs'
+import { startStructuredSession } from './runtime-session.mjs'
+import { defaultStructuredMode, structuredRuntimeForCommand, structuredRuntimeMetadata, structuredRuntimeSupportsMode } from './runtime-registry.mjs'
+import { probeHermesRuntime } from './hermes-probe.mjs'
 import { canonicalRoomFilePath, waitForNativeImages } from './codex-images.mjs'
 import { createManagedLaneWorktree, removeManagedLaneWorktree } from './lane-worktree.mjs'
 import { commandOnPath } from './agent-detect.mjs'
@@ -103,7 +105,7 @@ const flowRedispatch = new Map()
 // 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 { dispatchPendingRecap, recoverInterruptedTurn, recoverMissingResumeOnce, sendInterruptedContinue, supersedeInterruptedResume } from './interrupted-resume.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'
 import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks, usageReportLine, codexUsageReportLine, buildRecapFromLog, RECAP_CAP, trimmedBeforeSeq, firstSeq } from './event-id.mjs'
@@ -167,6 +169,7 @@ catch {
 const KNOWN_AGENTS = [
   { label: 'Claude Code', cmd: 'claude', resume: { args: ['--continue'], probe: claudeHasSession } },
   { label: 'Codex CLI',   cmd: 'codex' },
+  { label: 'Hermes Agent', cmd: 'thinkpool', availability: () => probeHermesRuntime().available },
   { label: 'Gemini CLI',  cmd: 'gemini' },
   { label: 'Aider',       cmd: 'aider' },
   { label: 'Cursor CLI',  cmd: 'cursor-agent' },
@@ -261,6 +264,39 @@ if (argv[0] === 'set-default-dir') {
   process.exit(0)
 }
 if (argv[0] === 'provider') { const { runProvider } = await import('./provider.mjs'); await runProvider(argv.slice(1)); process.exit(0) }
+if (argv[0] === 'setup-hermes') {
+  const clone = argv.includes('--clone')
+  const clean = argv.includes('--clean')
+  if (clone && clean) { console.error('  choose one Hermes setup mode: --clone or --clean'); process.exit(1) }
+  let mode = clone ? 'clone' : clean ? 'clean' : undefined
+  if (!mode && process.stdin.isTTY) {
+    const answer = await new Promise((resolve) => {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stderr })
+      rl.question('\n  Clone your active Hermes provider/config into an isolated thinkpool profile? [Y/n] ', (value) => { rl.close(); resolve(String(value).trim()) })
+    })
+    mode = /^n/i.test(answer) ? 'clean' : 'clone'
+  }
+  try {
+    const { setupHermesRuntime } = await import('./hermes-setup.mjs')
+    const result = setupHermesRuntime({ mode })
+    process.stderr.write(`\n  ◆ Hermes ${result.version || ''} is ready for ThinkPool ordinary lanes.\n    profile: ${result.profile} (${result.created ? `${result.mode} created` : 'existing'})\n    hidden delegation: blocked\n${result.created && result.mode === 'clean' ? '    provider: run `thinkpool setup` before the first model turn\n' : ''}\n`)
+    process.exit(0)
+  } catch (error) {
+    console.error(`\n  ◇ Hermes setup failed: ${error?.message || error}\n    New profile: npx thinkpool-pair@latest setup-hermes --clone\n    Clean profile: npx thinkpool-pair@latest setup-hermes --clean\n`)
+    process.exit(1)
+  }
+}
+if (argv[0] === 'verify-hermes-isolation') {
+  try {
+    const { verifyHermesMcpIsolation } = await import('./hermes-isolation.mjs')
+    const evidence = await verifyHermesMcpIsolation({ rounds: 2 })
+    process.stderr.write(`\n  ◆ Hermes MCP isolation HELD for ${evidence.length} consecutive two-lane rounds.\n    Each ACP session advertised only its lane-bound marker endpoint.\n    No model inference was used.\n\n`)
+    process.exit(0)
+  } catch (error) {
+    console.error(`\n  ◇ Hermes MCP isolation VIOLATED or unproven: ${error?.message || error}\n`)
+    process.exit(1)
+  }
+}
 
 // One-command launcher: a bare invocation on a TTY (or the `setup` alias) opens the
 // interactive menu instead of going straight to account mode. The menu only ASSEMBLES
@@ -307,6 +343,12 @@ if ((!argv[0] || argv[0] === 'setup') && process.stdin.isTTY) {
         : ['anthropic']
       await runProvider(args)
     },
+    setupHermes: async ({ mode }) => {
+      const { setupHermesRuntime } = await import('./hermes-setup.mjs')
+      const result = setupHermesRuntime({ mode })
+      io.print(`\n  ✓ Hermes ${result.version || ''} ready — isolated profile, ACP healthy, hidden delegation blocked.`)
+      if (result.created && result.mode === 'clean') io.print('    Run `thinkpool setup` once to choose a provider before the first model turn.')
+    },
   }
   await runLauncher({ actions, io, refresh: detectState })
   process.exit(0)
@@ -437,12 +479,9 @@ const STRUCTURED = process.env.TP_STRUCTURED === '1' || argv.includes('--structu
 // Claude Code runs as a STRUCTURED Agent-SDK session by default now (the picked
 // design — structured reader, risk-tiered permissions). Other CLIs keep the PTY
 // relay. TP_PTY=1 forces claude back to the raw PTY if ever needed.
-const structuredRuntime = (cmd) => {
-  const bin = path.basename(String(cmd || '')).toLowerCase()
-  return bin === 'codex' ? 'codex' : bin === 'claude' ? 'claude' : null
-}
+const structuredRuntime = structuredRuntimeForCommand
 const wantStructured = (cmd) => !!structuredRuntime(cmd) && process.env.TP_PTY !== '1'
-const installedAgents = KNOWN_AGENTS.filter(a => onPath(a.cmd))
+const installedAgents = KNOWN_AGENTS.filter(a => onPath(a.cmd) && (!a.availability || a.availability()))
 const dashIdx = argv.indexOf('--')
 // Own flags are only read from BEFORE `--`; after it, every token belongs
 // to the shared command (`-- claude --continue` must not trip these).
@@ -1063,7 +1102,7 @@ const announce = () => {
       // laneStatusOf: authoritative busy/idle + last-action timestamp/age +
       // STUCK/BLOCKED alert. The bridge owns the turn and permission state, so
       // every roster consumer reads one status instead of reconstructing it.
-      ...[...sessions.entries()].map(([id, s]) => ({ id, cmd: s.cmd, kind: 'structured', runtime: s.runtime || 'claude', alive: true, ...laneStatusOf(s), hasTranscript: s.log.length > 0, commands: s.commands, mode: s.mode || undefined, effort: s.effort || undefined, name: termNames[id] || undefined, model: s.model || undefined, ...(s.runtime === 'codex' ? { approvalPolicy: codexConfigForMode(s.mode).approvalPolicy, models: s.models || [], canSteer: s.session?.canSteer ?? false } : {}), ...(s.archiveOldestSeq != null ? { oldestSeq: s.archiveOldestSeq } : {}), ...(s.spawnedBy ? { spawned: true, spawnedBy: s.spawnedBy } : {}), ...(s.sideParent ? { sideParent: s.sideParent, sideTask: s.sideTask || undefined, sideHandback: !!s.sideHandback } : {}), ...(s.flowSessionId ? { flowId: s.flowSessionId, flowRole: s.flowTaskKey ? 'lane' : 'conductor' } : {}),
+      ...[...sessions.entries()].map(([id, s]) => ({ id, cmd: s.cmd, kind: 'structured', runtime: s.runtime || 'claude', alive: true, ...laneStatusOf(s), hasTranscript: s.log.length > 0, commands: s.commands, mode: s.mode || undefined, effort: s.effort || undefined, name: termNames[id] || undefined, model: s.model || undefined, capabilities: structuredRuntimeMetadata(s.runtime || 'claude'), ...(s.runtime === 'codex' ? { approvalPolicy: codexConfigForMode(s.mode).approvalPolicy, models: s.models || [], canSteer: s.session?.canSteer ?? false } : s.runtime === 'hermes' ? { models: s.models || [], canSteer: s.session?.canSteer ?? false } : {}), ...(s.archiveOldestSeq != null ? { oldestSeq: s.archiveOldestSeq } : {}), ...(s.spawnedBy ? { spawned: true, spawnedBy: s.spawnedBy } : {}), ...(s.sideParent ? { sideParent: s.sideParent, sideTask: s.sideTask || undefined, sideHandback: !!s.sideHandback } : {}), ...(s.flowSessionId ? { flowId: s.flowSessionId, flowRole: s.flowTaskKey ? 'lane' : 'conductor' } : {}),
         // provider: the registered LLM-provider this lane runs on, NAME-ONLY {id,name}
         // (NEVER the key or baseUrl). Additive; older clients ignore it. Omitted for the
         // built-in/default Claude path (no badge). Makes the lane's provider badge +
@@ -1657,14 +1696,14 @@ function worktreeSnapshot(cwd) {
 // rolling log replays to joiners and survives bridge restarts (session-store).
 function openStructured({ id, runtime = 'claude', model, 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 }) {
   if (sessions.has(id)) return
-  runtime = runtime === 'codex' ? 'codex' : 'claude'
+  runtime = structuredRuntimeMetadata(runtime) ? runtime : 'claude'
   // No explicit mode → a sensible default per runtime (see defaultModeForRuntime):
   // codex → bypassPermissions, so a freshly-opened codex terminal can fetch /
   // advance / ship instead of hitting the no-network wall; claude → default.
   // Only fires when no mode was passed — a person's pick, a resume (persisted
   // entry.mode), a flow lane, and spawn_terminal (inherits the parent's mode +
   // its own bypass-escalation gate) all pass an explicit mode and skip this.
-  mode = STRUCTURED_MODES.has(mode) ? mode : defaultModeForRuntime(runtime)
+  mode = STRUCTURED_MODES.has(mode) && structuredRuntimeSupportsMode(runtime, mode) ? mode : defaultStructuredMode(runtime)
   assertRuntimeModelCompatible({ runtime, provider, model })
   // The lane's EFFECTIVE model — computed ONCE and used for BOTH the truthful display
   // label (entry.model) and the SDK's `model` option below. These used to be computed
@@ -1679,6 +1718,8 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
     ? (codexRequestedModel
       ? resolveCodexModel(codexRequestedModel, codexModels)
       : flowLaneModelFor({ sliceType: 'feature', runtime: 'codex', catalog: codexModels }))
+    : runtime === 'hermes'
+      ? (model || undefined)
     : effectiveLaneModel({ provider, model, configuredModel: resolveProviderEnv(provider)?.ANTHROPIC_MODEL })
   // spawnedBy: set when this lane was Dispatched (spawn_terminal). Restored from the
   // session store so the Ensemble flag survives a bridge restart (else a respin
@@ -1700,7 +1741,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
     // No configured model → the provider's NAME, never a false Claude id (an inherited
     // claudeish id was dropped upstream by effectiveLaneModel; it must not sneak back in as a
     // label fallback here). Built-in Anthropic keeps the passed model.
-    model: runtime === 'codex'
+    model: runtime === 'codex' || runtime === 'hermes'
       ? (laneModel || null)
       : (!provider || provider === 'anthropic')
       ? (laneModel || null)
@@ -2410,7 +2451,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
     flowRole: entry.flowRole,
     sideParent: entry.sideParent,
   })
-  entry.session = (runtime === 'codex' ? startCodexSession : startClaudeSession)({
+  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
     // Claude id here defeats the whole per-provider env. undefined → option omitted.
@@ -2556,7 +2597,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
       // App Server steering is opt-in and can fall back to exec at runtime. Keep
       // the roster capability authoritative so the browser never immediate-sends
       // into an exec-only turn and loses its shared queue.
-      { const canSteerNow = entry.runtime === 'codex' && (entry.session?.canSteer ?? false)
+      { const canSteerNow = structuredRuntimeMetadata(entry.runtime)?.canSteer === true && (entry.session?.canSteer ?? false)
         if (canSteerNow !== entry._canSteerAnn) { entry._canSteerAnn = canSteerNow; announce() } }
       // Capture this session's current MODEL (resolved full id, with version — from
       // system/result `model` or usage `ctx.model`) and the SDK's supported-model
@@ -2573,13 +2614,14 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
       // SDK id overwrite it. Only trust the SDK's model on the built-in Anthropic path.
       // Keyed on the LANE's provider (entry.provider), not the bridge default — lanes can
       // run on different registered providers. (bridge-truth slice.)
-      { const onBuiltin = !entry.provider || entry.provider === 'anthropic'
-        const m = onBuiltin ? (evt.model || evt.ctx?.model) : null
+      { const onBuiltin = entry.runtime !== 'hermes' && (!entry.provider || entry.provider === 'anthropic')
+        const m = (entry.runtime === 'hermes' || onBuiltin) ? (evt.model || evt.ctx?.model) : null
         if (m && m !== entry.model) { entry.model = m; announce() }
         // A custom Anthropic-compatible endpoint may expose its own catalog through the
         // same SDK method. Never publish that as the ROOM's Claude catalog: its models
         // already render in the provider group and otherwise leak under ANTHROPIC.
-        if (onBuiltin && evt.kind === 'models' && Array.isArray(evt.models) && evt.models.length) { roomModels = evt.models; announce() } }
+        if (entry.runtime === 'hermes' && evt.kind === 'models' && Array.isArray(evt.models) && evt.models.length) { entry.models = evt.models; announce() }
+        else if (onBuiltin && evt.kind === 'models' && Array.isArray(evt.models) && evt.models.length) { roomModels = evt.models; announce() } }
       // Cache the last usage/ctx meter on the entry (persisted + replayed — see
       // openStructured). Chrome events bypass pushLog/persist in emitTail below, so
       // usage needs an explicit persist() here to survive a bridge restart.
@@ -2795,7 +2837,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
       process.stderr.write(req.risk === 'plan'
         ? `\n  ${A.mag}◆ plan ready — approve in the room.${A.rst}\n`
         : req.risk === 'ask'
-          ? `\n  ${A.cyan}● ${req.asker || (runtime === 'codex' ? 'Codex' : 'Claude')} is asking: ${(req.questions || []).map((q) => q.question).join(' / ').slice(0, 100)} — answer in the room.${A.rst}\n`
+          ? `\n  ${A.cyan}● ${req.asker || structuredRuntimeMetadata(runtime)?.label || 'Agent'} is asking: ${(req.questions || []).map((q) => q.question).join(' / ').slice(0, 100)} — answer in the room.${A.rst}\n`
           : `\n  ${A.yel}● permission: ${req.toolName}${argStr(req.input)} — approve in the room.${A.rst}\n`)
       const autoResolutionMs = Number(req.autoResolutionMs)
       if (req.risk === 'ask' && Number.isFinite(autoResolutionMs) && autoResolutionMs > 0) {
@@ -2830,7 +2872,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
   // room would otherwise show a fresh empty terminal + strand the transcript).
   if (!entry.log.length) entry.flush()
   announce()
-  if (!entry.log.length) process.stderr.write(`\n  ◆ structured Claude session (${id.slice(0, 8)}) — driven from the room.\n`)
+  if (!entry.log.length) process.stderr.write(`\n  ◆ structured ${structuredRuntimeMetadata(runtime)?.label || 'agent'} session (${id.slice(0, 8)}) — driven from the room.\n`)
   return entry
 }
 
@@ -3140,7 +3182,7 @@ channel
         runtime,
         mode: parent?.mode || payload.mode,
         model: parent?.model || payload.model || undefined,
-        provider: runtime === 'codex' ? undefined : (parent?.provider || payload.provider || undefined),
+        provider: runtime === 'claude' ? (parent?.provider || payload.provider || undefined) : undefined,
         cwd: parent ? (parent.cwd || process.cwd()) : undefined,
         sideParent: sideParent || undefined,
         sideTask: sideParent ? String(payload.sideTask).trim() : undefined,
@@ -3318,7 +3360,7 @@ channel
   // ── structured-session control (Phase 2) ──
   .on('broadcast', { event: 'code-open' }, ({ payload }) => {
     if (payload?.host && payload.host !== name) return
-    openStructured({ id: payload?.id || randomUUID(), runtime: payload?.runtime, model: payload?.model, provider: payload?.runtime === 'codex' ? undefined : payload?.provider, resume: payload?.resume, mode: payload?.mode, defer: true })
+    openStructured({ id: payload?.id || randomUUID(), runtime: payload?.runtime, model: payload?.model, provider: payload?.runtime === 'claude' ? payload?.provider : undefined, resume: payload?.resume, mode: payload?.mode, defer: true })
   })
   .on('broadcast', { event: 'side-handback-request' }, ({ payload }) => {
     const side = payload?.term && sessions.get(payload.term)
@@ -3387,7 +3429,7 @@ channel
     if (mm) {
       if (mm[1]) {
         if (s.session.setModel(mm[1]) === false) {
-          ctlLine(s.runtime === 'codex' ? 'finish or stop the current Codex turn before switching models' : 'model switch unavailable right now')
+          ctlLine(`finish or stop the current ${structuredRuntimeMetadata(s.runtime)?.label || 'agent'} turn before switching models`)
           return
         }
         // Reflect the switch in the announce IMMEDIATELY (before any turn). The SDK
@@ -3410,7 +3452,7 @@ channel
     }
     if (/^\/clear\s*$/.test(text)) {
       s.pendingRecap = null   // /clear means forget context — drop any un-fired carry recap
-      if (s.runtime === 'codex') s.session.clearContext?.()
+      if (s.runtime === 'codex' || s.runtime === 'hermes') s.session.clearContext?.()
       else s.session.sendTurn(text)
       // The seq reset is load-bearing on BOTH ends: the client's clear handler sets
       // seqHi = 0 (room.jsx), so the counter must restart with it. The durable archive
@@ -3494,7 +3536,7 @@ channel
     // image paths from the bridge-owned UPDIR + deterministic attachment fields,
     // then cover the separate file-put/code-turn download race with a bounded
     // readiness wait. A late image remains available through its quoted text path.
-    const nativeImages = s.runtime === 'codex'
+    const nativeImages = s.runtime === 'codex' || s.runtime === 'hermes'
       ? await waitForNativeImages(payload.files, { updir: UPDIR })
       : []
     s.session.sendTurn(sendText, nativeImages.length ? { images: nativeImages } : undefined)
@@ -3535,9 +3577,9 @@ channel
   .on('broadcast', { event: 'code-mode' }, ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)
     if (s && STRUCTURED_MODES.has(payload.mode)) {
-      if (s.runtime === 'codex') {
+      if (s.runtime === 'codex' || s.runtime === 'hermes') {
         if (!s.session.setMode(payload.mode)) {
-          const evt = { kind: 'control', text: 'finish or stop the current Codex turn before switching permissions' }
+          const evt = { kind: 'control', text: `finish or stop the current ${structuredRuntimeMetadata(s.runtime)?.label || 'agent'} turn before switching permissions` }
           pushLog(s, evt)
           bcast('code-event', { term: payload.term, evt })
           announce()
@@ -3735,13 +3777,12 @@ channel
             // leaves that file at zero bytes; both App Server and exec reject
             // it. Treat only that provably-empty case as non-resumable so the
             // existing fresh-thread recap recovery handles it.
-            const resumable = canResume(rec)
-              && (rec.runtime !== 'codex' || codexThreadCanResume(rec.sessionId))
+            const resumable = shouldAttemptNativeResume(rec, { canResume, codexThreadCanResume })
             const recoveryRecap = wasInterrupted ? buildRecapFromLog(rec.log || [], RECAP_CAP) : ''
             // 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, effort: rec.effort, provider: rec.runtime === 'codex' ? undefined : rec.provider || 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, 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,
               // 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).

package/hermes-delegation-guard.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Hermes shell hook: the ACP toolset currently includes delegate_task and ACP
+// has no per-session tool exclusion. Block it before execution so all delegated
+// work remains a visible ThinkPool lane.
+let input = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (chunk) => { input += chunk })
+process.stdin.on('end', () => {
+  let payload = null
+  try { payload = JSON.parse(input) } catch { /* malformed hook input fails closed below */ }
+  const blocking = !payload || payload.tool_name === 'delegate_task'
+  process.stdout.write(JSON.stringify(blocking
+    ? { action: 'block', message: 'ThinkPool blocks hidden Hermes delegation. Open visible ThinkPool lanes instead.' }
+    : {}) + '\n')
+})

package/hermes-event-mapper.mjs

@@ -0,0 +1,131 @@
+const textOf = (content) => {
+  if (typeof content === 'string') return content
+  if (content?.type === 'text') return String(content.text || '')
+  if (content?.type === 'content') return textOf(content.content)
+  return ''
+}
+const outputText = (update) => {
+  if (typeof update?.rawOutput === 'string') return update.rawOutput
+  const text = (update?.content || []).map(textOf).filter(Boolean).join('\n')
+  if (text) return text
+  if (update?.rawOutput != null) {
+    try { return JSON.stringify(update.rawOutput) } catch { return String(update.rawOutput) }
+  }
+  return ''
+}
+
+export function hermesToolFor(update = {}) {
+  const kind = String(update.kind || '').toLowerCase()
+  const title = String(update.title || '')
+  const raw = update.rawInput && typeof update.rawInput === 'object' ? update.rawInput : {}
+  const terminal = (update.content || []).find((part) => part?.type === 'terminal')
+  const shellText = (update.content || []).map(textOf).find((text) => text.trim().startsWith('$ '))
+  const location = update.locations?.[0]?.path
+  if (kind === 'execute' || terminal || shellText) return { name: 'Bash', input: { ...raw, command: raw.command || shellText?.trim().slice(2) || title } }
+  if (kind === 'edit') return { name: title.toLowerCase().includes('write') ? 'Write' : 'Edit', input: { ...raw, file_path: raw.path || location || '', path: raw.path || location || '' } }
+  if (kind === 'read') return { name: 'Read', input: { ...raw, file_path: raw.path || location || '', path: raw.path || location || '' } }
+  if (kind === 'search') return { name: 'Grep', input: raw }
+  if (kind === 'fetch') return { name: 'WebFetch', input: raw }
+  return { name: title || 'HermesTool', input: raw }
+}
+
+export class HermesEventMapper {
+  constructor({ onEvent, sessionId = null, model = null } = {}) {
+    this.onEvent = onEvent
+    this.sessionId = sessionId
+    this.model = model
+    this.tools = new Map()
+    this.text = ''
+    this.thought = ''
+    this.textCid = null
+  }
+
+  _emit(event) { try { this.onEvent?.(event) } catch { /* consumer isolation */ } }
+
+  startSession({ sessionId, models, modes, commands = [] } = {}) {
+    this.sessionId = sessionId || this.sessionId
+    this.model = models?.currentModelId || this.model
+    const list = (models?.availableModels || []).map((item) => ({ value: item.modelId, displayName: item.name || item.modelId, description: item.description || '' }))
+    this._emit({ kind: 'system', sessionId: this.sessionId, model: this.model, commands, models: list, modes })
+    if (list.length) this._emit({ kind: 'models', models: list, model: this.model })
+  }
+
+  push(params = {}) {
+    if (params.sessionId && this.sessionId && params.sessionId !== this.sessionId) return
+    const update = params.update || params
+    switch (update.sessionUpdate) {
+      case 'agent_message_chunk': {
+        const chunk = textOf(update.content)
+        if (!chunk) return
+        this.text += chunk
+        this.textCid ||= `hermes-stream:${this.sessionId || 'session'}:${Date.now()}`
+        this._emit({ kind: 'assistant_stream', cid: this.textCid, text: this.text, streaming: true })
+        return
+      }
+      case 'agent_thought_chunk':
+        this.thought += textOf(update.content)
+        return
+      case 'tool_call': {
+        const tool = hermesToolFor(update)
+        this.tools.set(update.toolCallId, { ...update, ...tool, startedAt: Date.now() })
+        this._emit({ kind: 'assistant', blocks: [{ type: 'tool_use', id: update.toolCallId, name: tool.name, input: tool.input }], parentToolUseId: null })
+        return
+      }
+      case 'tool_call_update': {
+        const prior = this.tools.get(update.toolCallId) || {}
+        const merged = { ...prior, ...update }
+        this.tools.set(update.toolCallId, merged)
+        if (!['completed', 'failed'].includes(update.status)) return
+        this._emit({
+          kind: 'tool_result', toolUseId: update.toolCallId,
+          content: [{ type: 'text', text: outputText(merged) }],
+          isError: update.status === 'failed',
+          durationMs: prior.startedAt ? Date.now() - prior.startedAt : undefined,
+          parentToolUseId: null,
+        })
+        this.tools.delete(update.toolCallId)
+        return
+      }
+      case 'usage_update': {
+        const used = Number(update.used) || 0
+        const max = Number(update.size) || 0
+        this._emit({ kind: 'usage', ctx: { used, max, pct: max ? Math.min(100, Math.round((used / max) * 100)) : 0, over: max > 0 && used > max, model: this.model } })
+        return
+      }
+      case 'available_commands_update':
+        this._emit({ kind: 'system', sessionId: this.sessionId, model: this.model, commands: (update.availableCommands || []).map((command) => `/${command.name}`) })
+        return
+      case 'current_mode_update':
+        this._emit({ kind: 'mode', mode: update.currentModeId })
+        return
+      case 'plan': {
+        const todos = (update.entries || []).map((entry) => ({ content: entry.content || '', activeForm: entry.content || '', status: entry.status === 'in_progress' ? 'in_progress' : entry.status === 'completed' ? 'completed' : 'pending' }))
+        this._emit({ kind: 'assistant', blocks: [{ type: 'tool_use', id: `hermes-plan:${this.sessionId}`, name: 'TodoWrite', input: { todos } }], parentToolUseId: null })
+        return
+      }
+      default:
+        return
+    }
+  }
+
+  finishTurn({ stopReason = 'end_turn', usage = null } = {}) {
+    const blocks = []
+    if (this.thought) blocks.push({ type: 'thinking', text: this.thought })
+    if (this.text) blocks.push({ type: 'text', text: this.text })
+    if (blocks.length) this._emit({ kind: 'assistant', blocks, parentToolUseId: null, ...(this.textCid ? { replacesCid: this.textCid } : {}) })
+    this._emit({
+      kind: 'result', subtype: stopReason === 'cancelled' ? 'aborted' : stopReason === 'end_turn' ? 'success' : 'error_during_execution',
+      sessionId: this.sessionId, model: this.model, costUsd: null,
+      usage: usage ? {
+        input_tokens: Number(usage.inputTokens) || 0,
+        cache_read_input_tokens: Number(usage.cachedReadTokens) || 0,
+        cache_creation_input_tokens: 0,
+        output_tokens: (Number(usage.outputTokens) || 0) + (Number(usage.thoughtTokens) || 0),
+      } : null,
+      numTurns: 1, durationMs: undefined, denials: 0, resultText: this.text || null,
+    })
+    this.text = ''
+    this.thought = ''
+    this.textCid = null
+  }
+}

package/hermes-isolation.mjs

@@ -0,0 +1,59 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
+import { startHermesSession } from './hermes-session.mjs'
+
+const waitFor = (predicate, timeoutMs = 25_000) => new Promise((resolve, reject) => {
+  const started = Date.now()
+  const timer = setInterval(() => {
+    if (predicate()) { clearInterval(timer); resolve() }
+    else if (Date.now() - started > timeoutMs) { clearInterval(timer); reject(new Error('Hermes MCP isolation probe timed out')) }
+  }, 50)
+})
+
+export function assertHermesIsolation(outputs, markers) {
+  if (!Array.isArray(outputs) || outputs.length !== 2 || !Array.isArray(markers) || markers.length !== 2) {
+    throw new TypeError('Hermes MCP isolation requires exactly two session outputs and markers')
+  }
+  for (let i = 0; i < 2; i++) {
+    if (!outputs[i].includes(`mcp__thinkpool__${markers[i]}`)) throw new Error(`Hermes lane ${i + 1} did not advertise its own MCP marker`)
+    if (outputs[i].includes(`mcp__thinkpool__${markers[1 - i]}`)) throw new Error(`Hermes lane ${i + 1} advertised the other lane's MCP marker`)
+  }
+  return true
+}
+
+export async function verifyHermesMcpIsolation({ rounds = 2, sessionFactory = startHermesSession } = {}) {
+  const evidence = []
+  for (let round = 0; round < rounds; round++) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'tp-hermes-mcp-isolation-'))
+    const suffix = randomUUID().replaceAll('-', '').slice(0, 10)
+    const markers = [`lane_alpha_${suffix}`, `lane_beta_${suffix}`]
+    const events = [[], []]
+    const sessions = []
+    try {
+      for (let i = 0; i < 2; i++) {
+        const cwd = path.join(root, i === 0 ? 'alpha' : 'beta')
+        fs.mkdirSync(cwd)
+        const sdkServer = createSdkMcpServer({
+          name: 'thinkpool', version: '1.0.0',
+          tools: [tool(markers[i], 'Synthetic ThinkPool lane-isolation marker.', {}, async () => ({ content: [{ type: 'text', text: markers[i] }] }))],
+        })
+        sessions.push(sessionFactory({ cwd, lazy: true, mcpServers: { thinkpool: sdkServer }, onEvent: (event) => events[i].push(event) }))
+      }
+      sessions.forEach((session) => session.sendTurn('/tools'))
+      await waitFor(() => events.every((list) => list.some((event) => event.kind === 'result') || list.some((event) => event.kind === 'error')))
+      const errors = events.flatMap((list) => list.filter((event) => event.kind === 'error'))
+      if (errors.length) throw new Error(`Hermes MCP isolation probe failed: ${errors.map((event) => event.message).join('; ')}`)
+      const outputs = events.map((list) => list.filter((event) => event.kind === 'assistant_stream').map((event) => event.text).join(''))
+      assertHermesIsolation(outputs, markers)
+      evidence.push({ round: round + 1, markers, sessionIds: sessions.map((session) => session.sessionId) })
+    } finally {
+      sessions.forEach((session) => session.end())
+      await new Promise((resolve) => setTimeout(resolve, 250))
+      fs.rmSync(root, { recursive: true, force: true })
+    }
+  }
+  return evidence
+}

package/hermes-probe.mjs

@@ -0,0 +1,20 @@
+import { execFileSync } from 'node:child_process'
+
+const clean = (value) => String(value || '').replace(/[\r\n]+/g, ' ').trim()
+
+export function probeHermesRuntime({ command = 'thinkpool', prefixArgs = [], execFile = execFileSync, env = process.env } = {}) {
+  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
+    execFile(command, [...prefixArgs, 'acp', '--check'], { encoding: 'utf8', env, timeout: 15_000, stdio: ['ignore', 'pipe', 'pipe'] })
+    const hooksOutput = execFile(command, [...prefixArgs, 'hooks', 'list'], { encoding: 'utf8', env, timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] })
+    const guardOutput = execFile(command, [...prefixArgs, 'hooks', 'test', 'pre_tool_call', '--for-tool', 'delegate_task'], { encoding: 'utf8', env, timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] })
+    const delegationBlocked = /(?:action|decision)["']?\s*[:=]\s*["']block/i.test(guardOutput)
+      && /ThinkPool blocks hidden Hermes delegation/i.test(guardOutput)
+      && /pre_tool_call[\s\S]*delegate_task[\s\S]*(?:✓ allowed|allowed)/i.test(hooksOutput)
+    if (!delegationBlocked) return { available: false, version, reason: 'delegate_task is not structurally blocked by the dedicated Hermes profile' }
+    return { available: true, version, acpProtocol: 1, delegationBlocked: true }
+  } catch (error) {
+    return { available: false, version: null, reason: clean(error?.stderr || error?.message || error) }
+  }
+}

package/hermes-session.mjs

@@ -0,0 +1,246 @@
+// Hermes Agent structured runtime over the official ACP stdio transport.
+// Implements the same narrow session contract as claude-session/codex-session.
+import fs from 'node:fs'
+import path from 'node:path'
+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 { startCodexMcpHttp } from './codex-mcp-http.mjs'
+import { classifyRisk } from './claude-session.mjs'
+
+export const HERMES_COMMAND = 'thinkpool'
+export const HERMES_ACP_PROTOCOL_VERSION = 1
+export const HERMES_SUPPORTED_MODES = new Set(['default', 'acceptEdits'])
+
+const HERMES_SECRET_ENV_KEY = /(?:TOKEN|SECRET|PASSWORD|PRIVATE_KEY|API_KEY|ACCESS_KEY|CREDENTIAL)/i
+export const hermesChildEnv = (env = {}) => Object.fromEntries(
+  Object.entries(env).filter(([key]) => !HERMES_SECRET_ENV_KEY.test(key)),
+)
+
+const imageBlock = (imagePath) => {
+  const ext = path.extname(imagePath).toLowerCase()
+  const mimeType = ext === '.png' ? 'image/png' : ext === '.webp' ? 'image/webp' : ext === '.gif' ? 'image/gif' : 'image/jpeg'
+  return { type: 'image', mimeType, data: fs.readFileSync(imagePath).toString('base64') }
+}
+
+const modelList = (state) => (state?.availableModels || []).map((item) => ({ value: item.modelId, displayName: item.name || item.modelId, description: item.description || '' }))
+
+const mcpDescriptor = (url) => ({ type: 'http', name: 'thinkpool', url, headers: [] })
+const createAcpClient = (options) => new AcpClient(options)
+
+const permissionOutcome = (decision, options = []) => {
+  if (decision === 'deny' || !decision) return { outcome: 'cancelled' }
+  const preferred = decision === 'always'
+    ? ['allow_always', 'allow_session', 'allow_once']
+    : ['allow_once', 'allow_session', 'allow_always']
+  const option = preferred.map((kind) => options.find((item) => item.kind === kind || item.optionId === kind)).find(Boolean)
+    || options.find((item) => String(item.kind || '').startsWith('allow'))
+  return option ? { outcome: 'selected', optionId: option.optionId } : { outcome: 'cancelled' }
+}
+
+export function startHermesSession({
+  cwd, model, resume, env = process.env, mode = 'default', onEvent, requestPermission,
+  roomContext, terminalRolePrompt, rolePrompt, mcpServers, prepareCwd = null,
+  command = HERMES_COMMAND, args = ['acp'], clientFactory = createAcpClient,
+  mcpHttpFactory = startCodexMcpHttp, lazy = false,
+} = {}) {
+  let activeCwd = cwd
+  const requestedModel = model || null
+  let activeModel = requestedModel
+  let activeMode = HERMES_SUPPORTED_MODES.has(mode) ? mode : 'default'
+  let sessionId = resume || null
+  let client = null
+  let mapper = null
+  let mcpHttp = null
+  let starting = null
+  let ended = false
+  let turnActive = false
+  let started = false
+  let crashed = false
+  let firstTurn = true
+  let stderrTail = ''
+  let promptChain = Promise.resolve()
+
+  const emit = (event) => { try { onEvent?.(event) } catch { /* consumer isolation */ } }
+
+  async function onRequest(method, params, requestId) {
+    if (method !== 'session/request_permission') throw Object.assign(new Error(`Unsupported ACP client method: ${method}`), { code: -32601 })
+    const tool = hermesToolFor(params.toolCall || mapper?.tools.get(params.toolCallId) || {})
+    const card = {
+      id: `hermes-perm:${requestId}`,
+      toolName: tool.name,
+      input: tool.input,
+      risk: classifyRisk(tool.name, tool.input),
+    }
+    let decision = 'deny'
+    try { decision = await requestPermission?.(card) } catch { /* fail closed */ }
+    return { outcome: permissionOutcome(decision, params.options) }
+  }
+
+  function onNotification(method, params) {
+    if (method === 'session/update') mapper?.push(params)
+  }
+
+  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')
+    if (client?.alive && mapper) return
+    if (starting) return starting
+    starting = (async () => {
+      if (!started && prepareCwd) {
+        try { activeCwd = prepareCwd() || activeCwd } catch { /* retain original cwd */ }
+      }
+      const thinkpool = mcpServers?.thinkpool
+      if (thinkpool && !mcpHttp) mcpHttp = await mcpHttpFactory({ sdkServer: thinkpool })
+      const childEnv = hermesChildEnv(env)
+      // 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 })
+        if (!profile.available) throw new Error(`Hermes profile safety check failed: ${profile.reason || 'runtime unavailable'}`)
+      }
+      client = clientFactory({
+        command, args, cwd: activeCwd, env: childEnv,
+        onNotification,
+        onRequest,
+        onStderr: (text) => { stderrTail = (stderrTail + text).slice(-2000) },
+        onClose: (error) => {
+          if (ended || crashed) return
+          crashed = true
+          turnActive = false
+          emit({ kind: 'error', message: `Hermes ACP closed unexpectedly: ${error?.message || error}`, recoverable: true })
+        },
+      })
+      client.start()
+      const initialized = await client.request('initialize', {
+        protocolVersion: HERMES_ACP_PROTOCOL_VERSION,
+        clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+        clientInfo: { name: 'thinkpool-pair', title: 'ThinkPool Code', version: '1' },
+      })
+      if (initialized?.protocolVersion !== HERMES_ACP_PROTOCOL_VERSION) {
+        throw new Error(`Unsupported Hermes ACP protocol ${initialized?.protocolVersion ?? 'unknown'}; expected ${HERMES_ACP_PROTOCOL_VERSION}`)
+      }
+      const params = { cwd: path.resolve(activeCwd), mcpServers: mcpHttp ? [mcpDescriptor(mcpHttp.url)] : [] }
+      mapper = new HermesEventMapper({ onEvent: emit, sessionId, model: activeModel })
+      let state
+      if (sessionId) {
+        if (!initialized?.agentCapabilities?.sessionCapabilities?.resume) {
+          throw new Error(`Hermes session ${sessionId} cannot be resumed by this ACP release; no fresh session was substituted`)
+        }
+        try { state = await client.request('session/resume', { ...params, sessionId }, 30_000) }
+        catch (error) {
+          throw new Error(`Hermes session ${sessionId} is not available; no fresh session was substituted (${error?.message || error})`)
+        }
+      } 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')
+      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) {
+        await client.request('session/set_model', { sessionId, modelId: activeModel })
+      }
+      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 })
+      }
+      emit({ kind: 'capabilities', runtime: 'hermes', protocol: 'acp', protocolVersion: initialized?.protocolVersion, capabilities: initialized?.agentCapabilities || {}, models: modelList(state?.models), flow: false })
+    })().catch((error) => {
+      crashed = true
+      client?.end()
+      void mcpHttp?.close().catch(() => {})
+      emit({ kind: 'error', message: `Hermes ACP startup failed: ${error?.message || error}${stderrTail ? `: ${stderrTail.trim().slice(-240)}` : ''}`, recoverable: true })
+      throw error
+    }).finally(() => { starting = null })
+    return starting
+  }
+
+  function promptBlocks(text, options = {}) {
+    const rawText = String(text)
+    // Hermes handles /steer, /queue, /compact and /reset only when the slash is
+    // the first character of a pure-text prompt.
+    if (/^\s*\//.test(rawText)) return [{ type: 'text', text: rawText }]
+    const context = typeof roomContext === 'function' ? roomContext() : roomContext
+    const preamble = firstTurn ? [terminalRolePrompt, rolePrompt, context].filter(Boolean).join('\n\n') : context
+    const blocks = [{ type: 'text', text: preamble ? `${preamble}\n\n${rawText}` : rawText }]
+    for (const imagePath of (Array.isArray(options.images) ? options.images : [])) {
+      try { blocks.push(imageBlock(imagePath)) } catch { /* quoted host path remains in text */ }
+    }
+    return blocks
+  }
+
+  async function runPrompt(text, options = {}) {
+    await boot()
+    const steering = turnActive
+    const body = steering ? `/steer ${String(text)}` : String(text)
+    if (!steering) turnActive = true
+    const result = await client.request('session/prompt', {
+      sessionId,
+      prompt: promptBlocks(body, options),
+      messageId: randomUUID(),
+    }, 0)
+    if (!steering) {
+      turnActive = false
+      firstTurn = false
+      mapper.finishTurn({ stopReason: result?.stopReason, usage: result?.usage })
+    }
+    return result
+  }
+
+  if (!lazy) queueMicrotask(() => { void boot().catch(() => {}) })
+
+  return {
+    get sessionId() { return sessionId },
+    get turnActive() { return turnActive },
+    get canSteer() { return !!client?.alive },
+    get started() { return started },
+    get models() { return [] },
+    sendTurn(text, options = {}) {
+      if (ended || crashed) return false
+      // A busy prompt is a genuine ACP /steer call and may run concurrently.
+      if (turnActive) { void runPrompt(text, options).catch((error) => emit({ kind: 'error', message: `Hermes steering failed: ${error?.message || error}`, recoverable: true })); return true }
+      promptChain = promptChain.then(() => runPrompt(text, options)).catch((error) => {
+        turnActive = false
+        emit({ kind: 'error', message: `Hermes turn failed: ${error?.message || error}`, recoverable: true })
+      })
+      return true
+    },
+    abort() {
+      if (!sessionId || !client?.alive) return
+      void client.notify('session/cancel', { sessionId }).catch(() => { /* process already closed */ })
+    },
+    end() {
+      ended = true
+      turnActive = false
+      if (sessionId && client?.alive) void client.request('session/close', { sessionId }, 1500).catch(() => {}).finally(() => client?.end())
+      else client?.end()
+      void mcpHttp?.close().catch(() => {})
+    },
+    setModel(nextModel) {
+      if (!nextModel || turnActive) return false
+      void boot().then(() => client.request('session/set_model', { sessionId, modelId: String(nextModel) })).then(() => {
+        activeModel = String(nextModel)
+        if (mapper) mapper.model = activeModel
+        emit({ kind: 'note', text: `model → ${activeModel}` })
+      }).catch((error) => emit({ kind: 'error', message: `Hermes model switch failed: ${error?.message || error}`, recoverable: true }))
+      return true
+    },
+    setMode(nextMode) {
+      if (turnActive || !HERMES_SUPPORTED_MODES.has(nextMode)) return false
+      void boot().then(() => client.request('session/set_mode', { sessionId, modeId: nextMode === 'acceptEdits' ? 'accept_edits' : 'default' })).then(() => {
+        activeMode = nextMode
+        emit({ kind: 'mode', mode: activeMode })
+      }).catch((error) => emit({ kind: 'error', message: `Hermes mode switch failed: ${error?.message || error}`, recoverable: true }))
+      return true
+    },
+    setEffort() { return false },
+    clearContext() {
+      if (turnActive) return false
+      return this.sendTurn('/reset')
+    },
+    warm() { void boot().catch(() => {}) },
+  }
+}

package/hermes-setup.mjs

@@ -0,0 +1,145 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import YAML from 'yaml'
+import { probeHermesRuntime } from './hermes-probe.mjs'
+
+export const HERMES_PROFILE = 'thinkpool'
+export const HERMES_GUARD_FILENAME = 'hermes-delegation-guard.mjs'
+
+const clean = (value) => String(value || '').replace(/[\r\n]+/g, ' ').trim()
+const commandText = (guardPath) => `node ${JSON.stringify(guardPath)}`
+const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+const isThinkPoolGuard = (entry) => isObject(entry)
+  && entry.matcher === '^delegate_task$'
+  && new RegExp(`${HERMES_GUARD_FILENAME.replaceAll('.', '\\.')}$`).test(String(entry.command || '').replace(/["']/g, ''))
+
+export function hermesGuardPath({ homeDir = os.homedir(), env = process.env, platform = process.platform } = {}) {
+  const dataRoot = platform === 'win32'
+    ? (env.LOCALAPPDATA || path.join(homeDir, 'AppData', 'Local'))
+    : (env.XDG_DATA_HOME || path.join(homeDir, '.local', 'share'))
+  return path.join(dataRoot, 'thinkpool-pair', HERMES_GUARD_FILENAME)
+}
+
+function atomicWrite(filePath, content, { fsImpl = fs, mode = 0o600 } = {}) {
+  fsImpl.mkdirSync(path.dirname(filePath), { recursive: true })
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`
+  try {
+    fsImpl.writeFileSync(tempPath, content, { mode })
+    fsImpl.chmodSync?.(tempPath, mode)
+    fsImpl.renameSync(tempPath, filePath)
+  } finally {
+    try { fsImpl.rmSync(tempPath, { force: true }) } catch { /* already renamed */ }
+  }
+}
+
+function snapshotFile(filePath, fsImpl) {
+  if (!fsImpl.existsSync(filePath)) return null
+  return {
+    content: fsImpl.readFileSync(filePath),
+    mode: fsImpl.statSync(filePath).mode & 0o777,
+  }
+}
+
+function restoreFile(filePath, snapshot, fsImpl) {
+  if (snapshot) atomicWrite(filePath, snapshot.content, { fsImpl, mode: snapshot.mode })
+  else fsImpl.rmSync(filePath, { force: true })
+}
+
+function profileAliasReady(output, profile) {
+  const escaped = profile.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`Alias:\\s+${escaped}\\s+.*hermes\\s+-p\\s+${escaped}`, 'i').test(String(output || ''))
+}
+
+export function setupHermesRuntime({
+  mode,
+  profile = HERMES_PROFILE,
+  command = 'hermes',
+  env = process.env,
+  homeDir = os.homedir(),
+  platform = process.platform,
+  execFile = execFileSync,
+  fsImpl = fs,
+  guardSource = fs.readFileSync(new URL('./hermes-delegation-guard.mjs', import.meta.url), 'utf8'),
+} = {}) {
+  if (profile !== HERMES_PROFILE) throw new Error(`ThinkPool only manages the isolated Hermes profile ${HERMES_PROFILE}`)
+  if (mode != null && mode !== 'clone' && mode !== 'clean') throw new Error('Hermes setup mode must be clone or clean')
+
+  const run = (args, options = {}) => execFile(command, args, {
+    encoding: 'utf8', env: options.env || env, timeout: options.timeout || 20_000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  const profileArgs = ['-p', profile]
+  let show = ''
+  let created = false
+  try { show = run(['profile', 'show', profile]) } catch { /* absent */ }
+  if (!/Profile:\s*thinkpool/i.test(show)) {
+    if (!mode) throw new Error('No isolated Hermes thinkpool profile exists; choose --clone or --clean')
+    const createArgs = ['profile', 'create', profile, '--description', 'Isolated ThinkPool Code runtime.']
+    if (mode === 'clone') createArgs.push('--clone')
+    else createArgs.push('--no-skills')
+    run(createArgs, { timeout: 60_000 })
+    created = true
+    show = run(['profile', 'show', profile])
+  }
+
+  if (!profileAliasReady(show, profile)) {
+    run(['profile', 'alias', profile, '--name', profile])
+    show = run(['profile', 'show', profile])
+    if (!profileAliasReady(show, profile)) throw new Error('Hermes did not create the required thinkpool profile alias')
+  }
+
+  const rawConfigPath = clean(run([...profileArgs, 'config', 'path']))
+  if (!rawConfigPath) throw new Error('Hermes did not report the thinkpool profile config path')
+  const configPath = rawConfigPath.startsWith('~') ? path.join(homeDir, rawConfigPath.slice(1).replace(/^[/\\]/, '')) : path.resolve(rawConfigPath)
+  const profilePathMatch = String(show).match(/^Path:\s*(.+)$/mi)
+  if (!profilePathMatch) throw new Error('Hermes did not report the isolated thinkpool profile path')
+  const profilePath = profilePathMatch[1].trim().startsWith('~')
+    ? path.join(homeDir, profilePathMatch[1].trim().slice(1).replace(/^[/\\]/, ''))
+    : path.resolve(profilePathMatch[1].trim())
+  const relativeConfig = path.relative(profilePath, configPath)
+  if (relativeConfig.startsWith('..') || path.isAbsolute(relativeConfig)) throw new Error('Hermes reported a config path outside the isolated thinkpool profile')
+  let config = {}
+  if (fsImpl.existsSync(configPath)) {
+    const parsed = YAML.parse(fsImpl.readFileSync(configPath, 'utf8'))
+    if (parsed != null && !isObject(parsed)) throw new Error('Hermes thinkpool config is not a YAML mapping; refusing to overwrite it')
+    config = parsed || {}
+  }
+  if (config.hooks != null && !isObject(config.hooks)) throw new Error('Hermes thinkpool hooks config is not a mapping; refusing to overwrite it')
+  const hooks = config.hooks ||= {}
+  if (hooks.pre_tool_call != null && !Array.isArray(hooks.pre_tool_call)) throw new Error('Hermes pre_tool_call hooks are not a list; refusing to overwrite them')
+  const prior = hooks.pre_tool_call || []
+  hooks.pre_tool_call = [
+    ...prior.filter((entry) => !isThinkPoolGuard(entry)),
+    { matcher: '^delegate_task$', command: commandText(hermesGuardPath({ homeDir, env, platform })), timeout: 5 },
+  ]
+
+  const guardPath = hermesGuardPath({ homeDir, env, platform })
+  const guardSnapshot = snapshotFile(guardPath, fsImpl)
+  const configSnapshot = snapshotFile(configPath, fsImpl)
+  try {
+    atomicWrite(guardPath, guardSource, { fsImpl, mode: 0o700 })
+    atomicWrite(configPath, YAML.stringify(config, { lineWidth: 0 }), { fsImpl, mode: 0o600 })
+
+    const consentEnv = { ...env, HERMES_ACCEPT_HOOKS: '1' }
+    const testOutput = run([...profileArgs, 'hooks', 'test', 'pre_tool_call', '--for-tool', 'delegate_task'], { env: consentEnv })
+    if (!/(?:action|decision)["']?\s*[:=]\s*["']block/i.test(testOutput)
+      || !/ThinkPool blocks hidden Hermes delegation/i.test(testOutput)) {
+      throw new Error('Hermes ran the ThinkPool delegation guard but did not report an explicit block')
+    }
+    run([...profileArgs, 'hooks', 'doctor'], { env: consentEnv })
+    run([...profileArgs, 'acp', '--check'], { env: consentEnv })
+    const probe = probeHermesRuntime({ command, prefixArgs: profileArgs, execFile, env: consentEnv })
+    if (!probe.available) throw new Error(`Hermes setup did not pass the final runtime probe: ${probe.reason || 'unavailable'}`)
+    return { ...probe, profile, created, mode: created ? mode : 'existing', guardPath, configPath }
+  } catch (error) {
+    try {
+      restoreFile(configPath, configSnapshot, fsImpl)
+      restoreFile(guardPath, guardSnapshot, fsImpl)
+    } catch (rollbackError) {
+      error.message = `${error.message}; rollback also failed: ${clean(rollbackError.message)}`
+    }
+    throw error
+  }
+}

package/interrupted-resume.mjs

@@ -52,12 +52,24 @@ export function isMissingResumeError(message) {
   return /No conversation found|no rollout found for thread id|thread\/resume[^\n]*failed[^\n]*no rollout/i.test(String(message || ''))
 }
 
+export function shouldAttemptNativeResume(record, { canResume = () => false, codexThreadCanResume = () => true } = {}) {
+  if (!record?.sessionId) return false
+  // Hermes has an explicit, non-replaying ACP resume request that fails loudly
+  // when identity is gone. Always ask the runtime instead of silently aging the
+  // identity out under Claude's historical local freshness heuristic.
+  if (record.runtime === 'hermes') return true
+  return canResume(record) && (record.runtime !== 'codex' || codexThreadCanResume(record.sessionId))
+}
+
 // Bound the stale-native-thread self-heal at the ownership seam. The old entry is
 // marked before teardown/reopen so duplicate error delivery can never fork another
 // process. `reopen` returns the new structured entry; Codex consumes the recap
 // immediately because a fresh exec has no idle init event.
 export function recoverMissingResumeOnce(entry, { message, recap = '', reopen } = {}) {
-  if (!entry || entry.recovered || !isMissingResumeError(message)) return { recovered: false, delivery: 'ignored' }
+  // Hermes ACP session identity is part of the lane contract. If native resume
+  // fails, surfacing that failure is safer than silently replacing the session
+  // with a recap-backed fresh identity.
+  if (!entry || entry.runtime === 'hermes' || entry.recovered || !isMissingResumeError(message)) return { recovered: false, delivery: 'ignored' }
   entry.recovered = true
   try { entry.session?.end?.() } catch { /* already dead */ }
   let recovered = null

package/launcher.mjs

@@ -15,6 +15,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { execSync } from 'node:child_process'
 import { detectProvider, fetchModels, ANTHROPIC_COMPATIBLE, gatewayHint } from './byok-detect.mjs'
+import { probeHermesRuntime } from './hermes-probe.mjs'
 
 const HOME = os.homedir()
 const CFG_DIR = path.join(HOME, '.thinkpool-pair')
@@ -27,6 +28,7 @@ const VERSION = (() => { try { return JSON.parse(fs.readFileSync(new URL('./pack
 export const KNOWN_AGENTS = [
   { label: 'Claude Code', cmd: 'claude', resume: ['--continue'] },
   { label: 'Codex CLI',   cmd: 'codex' },
+  { label: 'Hermes Agent', cmd: 'thinkpool' },
   { label: 'Gemini CLI',  cmd: 'gemini' },
   { label: 'Aider',       cmd: 'aider' },
   { label: 'Cursor CLI',  cmd: 'cursor-agent' },
@@ -73,12 +75,16 @@ export function detectState() {
   // provider.json is written with { provider, baseUrl, model } (see provider.mjs).
   // Anything whose `provider` field is set and not "anthropic" is a custom endpoint.
   const isCustom = !!provider?.provider && provider.provider !== 'anthropic'
+  const hermesInstalled = onPath('hermes')
+  const hermesReady = onPath('thinkpool') && probeHermesRuntime().available
   return {
     loggedIn: !!auth?.refresh_token,
     email: auth?.email || auth?.user?.email || null,
     provider: isCustom ? `Custom (${provider.baseUrl || 'endpoint'})` : 'Anthropic (default)',
     providerModel: isCustom ? (provider.model || null) : null,
-    agents: KNOWN_AGENTS.filter(a => onPath(a.cmd)),
+    agents: KNOWN_AGENTS.filter(a => onPath(a.cmd) && (a.cmd !== 'thinkpool' || hermesReady)),
+    hermesInstalled,
+    hermesReady,
     accountSvc: serviceLoaded(null),
     cwd: process.cwd(),
     version: VERSION,
@@ -205,24 +211,34 @@ export async function runLauncher({ actions, io, state = detectState(), refresh
 
   const settingsMenu = async () => {
     for (;;) {
-      const pick = await askChoice('\n  change', [
-        { label: 'LLM provider', hint: `current: ${state.provider}` },
-        { label: 'Account', hint: state.loggedIn ? `linked: ${state.email || 'yes'}` : 'not linked' },
-        { label: 'Restart & update the bridge', hint: state.accountSvc ? 'pull the newest published version, then restart — sessions resume' : 'none installed' },
-        { label: 'Remove the background service', hint: state.accountSvc ? '' : 'none installed' },
-        { label: '← Back to main menu', hint: '' },
-      ], 5)  // Enter = Back
-      if (pick === 4) return
-      if (pick === 0) await providerMenu()
-      else if (pick === 1) { await actions.login(); resync(); return }
-      else if (pick === 2) {
+      const options = [
+        { key: 'provider', label: 'LLM provider', hint: `current: ${state.provider}` },
+        { key: 'account', label: 'Account', hint: state.loggedIn ? `linked: ${state.email || 'yes'}` : 'not linked' },
+        { key: 'restart', label: 'Restart & update the bridge', hint: state.accountSvc ? 'pull the newest published version, then restart — sessions resume' : 'none installed' },
+        { key: 'remove', label: 'Remove the background service', hint: state.accountSvc ? '' : 'none installed' },
+      ]
+      if (state.hermesInstalled) options.push({ key: 'hermes', label: 'Hermes Agent', hint: state.hermesReady ? 'isolated profile ready' : 'set up isolated profile + delegation guard' })
+      options.push({ key: 'back', label: '← Back to main menu', hint: '' })
+      const picked = options[await askChoice('\n  change', options, options.length)]
+      if (picked.key === 'back') return
+      if (picked.key === 'provider') await providerMenu()
+      else if (picked.key === 'account') { await actions.login(); resync(); return }
+      else if (picked.key === 'restart') {
         if (state.accountSvc) { await actions.restartUpdateService({ room: null }); resync() }
         else io.print('  ' + C.yellow('no background service installed'))
       }
-      else {
+      else if (picked.key === 'remove') {
         if (state.accountSvc) { await actions.uninstallService({ room: null }); resync() }
         else io.print('  ' + C.yellow('no background service installed'))
       }
+      else if (picked.key === 'hermes') {
+        const setup = await askChoice('\n  Hermes profile', [
+          { label: 'Clone active profile', hint: 'copies provider/config explicitly; fresh ThinkPool session history' },
+          { label: 'Create clean profile', hint: 'no copied credentials or bundled skills; configure provider afterward' },
+          { label: '← Back', hint: '' },
+        ], 3)
+        if (setup !== 2) { await actions.setupHermes({ mode: setup === 0 ? 'clone' : 'clean' }); resync() }
+      }
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.233",
+  "version": "0.7.235",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -20,6 +20,15 @@
     "codex-mcp-http.mjs",
     "lane-worktree.mjs",
     "codex-event-mapper.mjs",
+    "acp-client.mjs",
+    "hermes-session.mjs",
+    "hermes-event-mapper.mjs",
+    "hermes-probe.mjs",
+    "hermes-setup.mjs",
+    "hermes-isolation.mjs",
+    "hermes-delegation-guard.mjs",
+    "runtime-registry.mjs",
+    "runtime-session.mjs",
     "turn-stall.mjs",
     "update-gate.mjs",
     "agent-notify.mjs",
@@ -70,9 +79,11 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "1.2.1",
     "@anthropic-ai/claude-agent-sdk": "^0.3.198",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@supabase/supabase-js": "^2.45.0",
+    "yaml": "2.9.0",
     "zod": "^4.4.3"
   },
   "optionalDependencies": {

package/runtime-registry.mjs

@@ -0,0 +1,30 @@
+import path from 'node:path'
+
+const RUNTIMES = Object.freeze({
+  claude: Object.freeze({
+    id: 'claude', command: 'claude', label: 'Claude Code', protocol: 'agent-sdk',
+    structured: true, flow: true, canSteer: false, images: true, nativeModelCatalog: false, defaultMode: 'default',
+    modes: Object.freeze(['default', 'acceptEdits', 'plan', 'bypassPermissions']),
+  }),
+  codex: Object.freeze({
+    id: 'codex', command: 'codex', label: 'Codex', protocol: 'codex-app-server',
+    structured: true, flow: true, canSteer: true, images: true, nativeModelCatalog: true, defaultMode: 'bypassPermissions',
+    modes: Object.freeze(['default', 'acceptEdits', 'plan', 'bypassPermissions', 'review']),
+  }),
+  hermes: Object.freeze({
+    id: 'hermes', command: 'thinkpool', label: 'Hermes Agent', protocol: 'acp',
+    structured: true, flow: false, canSteer: true, images: true, nativeModelCatalog: true, defaultMode: 'default',
+    modes: Object.freeze(['default', 'acceptEdits']),
+    beta: true,
+  }),
+})
+
+export const STRUCTURED_RUNTIME_IDS = Object.freeze(Object.keys(RUNTIMES))
+export const structuredRuntimeMetadata = (runtime) => RUNTIMES[runtime] || null
+export const structuredRuntimeForCommand = (command) => {
+  const bin = path.basename(String(command || '')).toLowerCase()
+  return Object.values(RUNTIMES).find((runtime) => runtime.command === bin)?.id || null
+}
+export const defaultStructuredMode = (runtime) => structuredRuntimeMetadata(runtime)?.defaultMode || 'default'
+export const structuredRuntimeSupportsMode = (runtime, mode) => structuredRuntimeMetadata(runtime)?.modes?.includes(mode) === true
+export const structuredRuntimeSupportsFlow = (runtime) => structuredRuntimeMetadata(runtime)?.flow === true

package/runtime-session.mjs

@@ -0,0 +1,15 @@
+import { startClaudeSession } from './claude-session.mjs'
+import { startCodexSession } from './codex-session.mjs'
+import { startHermesSession } from './hermes-session.mjs'
+
+const FACTORIES = Object.freeze({
+  claude: startClaudeSession,
+  codex: startCodexSession,
+  hermes: startHermesSession,
+})
+
+export function startStructuredSession(runtime, options) {
+  const factory = FACTORIES[runtime]
+  if (!factory) throw new Error(`Unsupported structured runtime: ${runtime}`)
+  return factory(options)
+}