thinkpool-pair 0.7.232 → 0.7.234

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' },
@@ -437,12 +440,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 +1063,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 +1657,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 +1679,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 +1702,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)
@@ -1962,6 +1964,49 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
   // 1.5s saveSession debounce window) and on shutdown (so events since the last
   // debounced write aren't lost). Contract #2: restart resumes, no lost messages.
   entry.flush = () => flushSession(room, id, sessionData())
+  // Main-terminal creation and Ensemble dispatch are different capabilities.
+  // A main terminal (human-opened or agent-opened via open_main_terminal) may
+  // dispatch workers. A spawned/Side/Flow lane can never elevate itself or a
+  // child into a conductor merely by wording its task that way.
+  const isIndependentMain = !entry.spawnedBy && !entry.sideParent && !entry.flowRole && (entry.spawnDepth || 0) === 0
+  const canOpenMainConductor = isIndependentMain && entry.cascadeRole !== 'conductor'
+  const canSpawnWorkers = isIndependentMain
+  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 === '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 === '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.` }
+    }
+    return {
+      runtime,
+      model: args?.model || (worker && args?.sliceType
+        ? spawnedLaneModelFor({ sliceType: args.sliceType, runtime, catalog })
+        : undefined),
+      mode: args?.mode || (entry.mode === 'plan' ? 'default' : entry.mode),
+      provider: args?.provider,
+    }
+  }
+  const consumeTerminalOpenBudget = () => {
+    const now = Date.now()
+    const gate = spawnDecision({
+      hop: 0,
+      spawnTimes: entry.spawnTimes || [],
+      now,
+      // Main terminals do not consume the Ensemble plan ceiling. The pure
+      // gate still supplies the shared kill-switch, machine cap, and burst cap.
+      spawnedLive: 0,
+      totalLive: sessions.size + terms.size,
+      plan: ownerPlan,
+      disabled: process.env.TP_SPAWN_OFF === '1',
+    })
+    if (!gate.ok) return gate
+    entry.spawnTimes = [...(entry.spawnTimes || []).filter((t) => Number.isFinite(t) && t > now - SPAWN.windowMs), now]
+    return gate
+  }
   // B2 cross-terminal peek — an in-process, READ-ONLY tool the agent can call to
   // see a SIBLING terminal's recent output (vs B1's always-on @pool digest). The
   // handler closes over the module-scope `sessions`/`terms` Maps + this session's
@@ -2106,43 +2151,81 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
           return okText(`Delivered to terminal ${target.ref} (${target.cmd}). It will respond in its own lane; check back with read_terminal.`)
         },
       )] : []),
-      // Tier C+ — SPAWN a fresh agent lane the caller OWNS. The motivating bug:
+      // MAIN CONDUCTOR — create the same independent structured terminal the web
+      // "+ New terminal" path creates: no spawnedBy marker, no Ensemble ownership,
+      // depth 0. Only an ordinary independent main terminal receives this tool;
+      // conductor mains, spawned workers, Side lanes, and Flow lanes cannot use it.
+      ...(canOpenMainConductor ? [tool(
+        'open_main_terminal',
+        'Open a separate independent MAIN terminal to conduct a Cascade. Use this whenever a person explicitly asks to open, launch, start, or spawn a new Cascade/conductor terminal. This is the top-level room lifecycle, NOT Ensemble dispatch: the new terminal has no spawnedBy owner and appears as a main terminal. Never substitute spawn_terminal, which creates worker sub-terminals only. Give the conductor its full initial task; it will use spawn_terminal for its workers.',
+        {
+          name: z.string().max(80).optional().describe('short label for the main conductor, e.g. "Cascade · Multi-device chaos"'),
+          task: z.string().min(1).describe('complete initial Cascade brief for the conductor'),
+          model: z.string().optional().describe('optional conductor model, e.g. opus / gpt-5.6-sol'),
+          runtime: z.enum(['claude', 'codex']).optional().describe('agent runtime; defaults to inheriting this main terminal'),
+          provider: z.string().optional().describe('optional registered LLM provider id for a Claude conductor'),
+          mode: z.enum(['default', 'acceptEdits', 'bypassPermissions', 'plan']).optional().describe('permission mode; defaults to inheriting this main terminal, except plan falls back to default'),
+        },
+        async (args) => {
+          const okText = (t) => ({ content: [{ type: 'text', text: t }] })
+          const resolved = resolveAgentOpen(args)
+          if (resolved.error) return okText(resolved.error)
+          const gate = consumeTerminalOpenBudget()
+          if (!gate.ok) return okText(gate.reason)
+          const newId = randomUUID()
+          const newRef = String(newId).slice(0, 8)
+          const fromRef = String(id).slice(0, 8)
+          if (args?.name) { termNames[newId] = String(args.name).slice(0, 80); saveNames(room, termNames) }
+          openStructured({
+            id: newId,
+            runtime: resolved.runtime,
+            model: resolved.model,
+            provider: resolved.provider,
+            mode: resolved.mode,
+            spawnDepth: 0,
+            cascadeRole: 'conductor',
+            hop: 0,
+          })
+          const conductor = sessions.get(newId)
+          if (!conductor) {
+            if (args?.name) { delete termNames[newId]; saveNames(room, termNames) }
+            return okText('Could not open the main conductor terminal — the machine terminal cap may have just been reached.')
+          }
+          conductor.peekCount = 0; conductor.postCount = 0; conductor.spawnTimes = []
+          announce()
+          const msg = `[Task from main terminal ${fromRef}'s agent — opened as an independent MAIN CASCADE CONDUCTOR terminal, not an Ensemble child]\n${String(args.task).trim()}`
+          const evt = { kind: 'you', text: msg, by: `main terminal ${fromRef} (agent)`, crosspost: true, relaySourceName: termNames[id] || undefined }
+          stampEvent(evt); pushLog(conductor, evt); bcast('code-event', { term: newId, evt })
+          try { conductor.session.sendTurn(msg) }
+          catch { return okText(`Opened main conductor ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — the initial task could not be delivered.`) }
+          return okText(`Opened independent main Cascade conductor ${newRef}${args?.name ? ` ("${args.name}")` : ''} and handed it the task. It is a main terminal, not an Ensemble lane.`)
+        },
+      )] : []),
+      // Tier C+ — SPAWN a fresh WORKER lane the caller OWNS. The motivating bug:
       // an agent fanned a research task into SIBLINGS that were already busy (a
       // release lane, a Q&A lane) because it had no way to make its own lanes.
       // This opens a brand-new structured session server-side (the same path the
       // web's "+ New terminal" and the restore loop use), so announce() surfaces
       // its tab in the open web UI live. Auto-allowed by the PreToolUse gate but
-      // bounded by spawnDecision (depth-2 hop bound, burst window, the live terminal
-      // cap, TP_SPAWN_OFF kill-switch). A person's lane (hop 0) may spawn conductors
-      // (hop 1) which may spawn workers (hop 2); hop 2 can never spawn onward — the
-      // fork-bomb breaker, now one level deeper (2026-07-10 cascade-spawn-depth spec).
-      ...(!entry.flowRole ? [tool(
+      // bounded by spawnDecision (one-worker-tier hop bound, burst window, the live terminal
+      // cap, TP_SPAWN_OFF kill-switch). Spawned lanes are always workers and do
+      // not receive this tool, so the hierarchy is capability-enforced.
+      ...(canSpawnWorkers ? [tool(
         'spawn_terminal',
-        'Open a NEW agent terminal (Claude or Codex) in this ThinkPool Code room — YOUR lane to use, not a sibling that is already working. ALWAYS declare cascadeRole="conductor" when this new terminal must decompose and spawn its own worker sub-terminals; declare cascadeRole="worker" for an assigned slice that must work directly. The bridge injects that identity into the child\'s first system preamble. The runtime defaults to inheriting this lane, or pass `runtime` to dispatch across runtimes. Choose `model` explicitly from advertised metadata when practical: for Codex use Luna/Mini for mechanical work, Terra for ordinary feature/fix work, and Sol only for repeated-failure, architecture/conductor, or adversarial final-review work; never inherit Sol by default, and omit `model` for runtime fallback when the named tier is unavailable. For cascades, pass sliceType=scaffold for mechanical work, feature/fix for builders, and review for adversarial verification (review never routes to the cheap tier); an explicit model overrides slice tiering. Omit sliceType to preserve ordinary model inheritance/default behavior. Give the lane an initial `task`, collect its result with read_terminal, then ALWAYS close_terminal it — a finished lane left open holds a slot against the room cap and blocks the next fan-out. By default the new lane INHERITS your current permission mode. ALWAYS prefer spawning a fresh lane over post_to_terminal into one that is already busy. Bounded by cascade depth, the room terminal cap, and per-turn limits.',
+        '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.',
         {
           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'),
           sliceType: z.enum(['scaffold', 'feature', 'fix', 'review']).optional().describe('optional cascade slice tier; omitted preserves normal inheritance/default, explicit model wins'),
-          cascadeRole: z.enum(['conductor', 'worker']).optional().describe('structural Cascade identity injected into the child system preamble: conductor may dispatch one worker tier; worker does the assigned slice directly'),
           runtime: z.enum(['claude', 'codex']).optional().describe('agent runtime for the new lane; defaults to inheriting this lane'),
           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.'),
         },
         async (args) => {
           const okText = (t) => ({ content: [{ type: 'text', text: t }] })
-          const childRuntime = args?.runtime || entry.runtime || 'claude'
-          if (childRuntime === 'codex' && args?.provider) return okText('A Codex lane uses its Codex/OpenAI login in v1; custom bridge providers are not wired to Codex yet. Omit provider or spawn a Claude lane for that provider.')
-          const childCatalog = childRuntime === 'codex' ? readCodexModels() : []
-          if (childRuntime === 'codex' && args?.model && !modelCatalogValues(childCatalog).has(args.model)) {
-            return okText(`Could not open a Codex lane on ${JSON.stringify(args.model)} — that model is not in this host's visible Codex catalog.`)
-          }
-          if (childRuntime === 'claude' && !args?.provider && args?.model && /^gpt-/i.test(args.model)) {
-            return okText(`Could not open a Claude lane on Codex model ${JSON.stringify(args.model)}. Choose runtime="codex" or a Claude model.`)
-          }
-          const childModel = args?.model || (args?.sliceType
-            ? spawnedLaneModelFor({ sliceType: args.sliceType, runtime: childRuntime, catalog: childCatalog })
-            : undefined)
+          const resolved = resolveAgentOpen(args, { worker: true })
+          if (resolved.error) return okText(resolved.error)
           const now = Date.now()
           const gate = spawnDecision({
             hop: entry.hop || 0,
@@ -2176,13 +2259,12 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
           // PM-m1 — never INHERIT plan mode into a spawned worker lane: a lane spawned from a
           // plan-mode lane would stall on ExitPlanMode cards. An explicit args.mode still wins;
           // otherwise inherit, but fall plan → default (an autonomous worker doesn't plan-gate).
-          const childMode = args?.mode || (entry.mode === 'plan' ? 'default' : entry.mode)
           const childSpawnDepth = (entry.spawnDepth || 0) + 1
           const childHop = (entry.hop || 0) + 1
           // Stamp ownership/depth BEFORE the runtime starts so its first system
           // preamble is truthful. Mutating ne.spawnedBy after openStructured was
           // too late: Codex/Claude had already booted with the top-level wording.
-          openStructured({ id: newId, runtime: childRuntime, model: childModel, provider: args?.provider, mode: childMode, spawnedBy: id, spawnDepth: childSpawnDepth, cascadeRole: args?.cascadeRole, hop: childHop })
+          openStructured({ id: newId, runtime: resolved.runtime, model: resolved.model, provider: resolved.provider, mode: resolved.mode, spawnedBy: id, spawnDepth: childSpawnDepth, cascadeRole: 'worker', hop: childHop })
           const ne = sessions.get(newId)
           if (!ne) { if (args?.name) { delete termNames[newId]; saveNames(room, termNames) } return okText('Could not open a new lane — the terminal cap may have just been reached. Close one and retry.') }
           ne.peekCount = 0; ne.postCount = 0; ne.spawnTimes = []
@@ -2190,10 +2272,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
           if (args?.task) {
             // The user-visible relay reinforces (but never defines) the structural
             // role already injected by the system preamble above.
-            const roleRelay = args?.cascadeRole === 'conductor'
-              ? 'you are its Cascade conductor terminal, responsible for worker sub-terminals'
-              : 'you are its worker sub-terminal, not a top-level room terminal'
-            const msg = `[Task from terminal ${fromRef}'s agent — relayed via ThinkPool cross-terminal; ${roleRelay}]\n${args.task}`
+            const msg = `[Task from terminal ${fromRef}'s agent — relayed via ThinkPool Ensemble; you are its WORKER SUB-TERMINAL, never a main terminal or Cascade conductor]\n${args.task}`
             const evt = { kind: 'you', text: msg, by: `terminal ${fromRef} (agent)`, crosspost: true, relaySourceName: termNames[id] || undefined }
             stampEvent(evt); pushLog(ne, evt); bcast('code-event', { term: newId, evt })
             try { ne.session.sendTurn(msg) } catch { return okText(`Opened lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — could not hand off the task. Try post_to_terminal shortly.`) }
@@ -2333,7 +2412,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.
@@ -2479,7 +2558,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
@@ -2496,13 +2575,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.
@@ -2718,7 +2798,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) {
@@ -2753,7 +2833,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
 }
 
@@ -3063,7 +3143,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,
@@ -3241,7 +3321,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)
@@ -3310,7 +3390,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
@@ -3333,7 +3413,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
@@ -3417,7 +3497,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)
@@ -3458,9 +3538,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()
@@ -3658,13 +3738,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).