thinkpool-pair 0.7.231 → 0.7.233

package/bridge.mjs

@@ -111,6 +111,7 @@ import { SIDE_HANDOFF_PROMPT, SIDE_ROLE_PROMPT, appendSideContext, assistantText
 import { planMeterLine } from './plan-meters.mjs'
 import { makeThrottledTrack } from './presence.mjs'
 import { resolveAnonKey, DEFAULT_SUPABASE_URL } from './supabase-key.mjs'
+import { buildTerminalRolePrompt } from './thinkpool-room-prompt.mjs'
 
 // Public client creds (the same anon values the web app ships — safe to embed).
 // Override with TP_SUPABASE_URL / TP_SUPABASE_ANON if you ever need to.
@@ -1654,7 +1655,7 @@ function worktreeSnapshot(cwd) {
 // relay STRUCTURED events. onEvent → broadcast `code-event` + print locally +
 // persist to the host file; tool calls round-trip through the perm card; the
 // rolling log replays to joiners and survives bridge restarts (session-store).
-function openStructured({ id, runtime = 'claude', model, effort, resume, log, commands, mode, spawnedBy, sideParent, sideTask, pendingSideContexts, rolePrompt, flowSessionId, flowTaskKey, flowRole, flowReviewTarget, flowReviewTargets, flowReviewRound, dispatchBaseSha, revertTarget, cwd, managedWorktree, reviewSliceRoots, openedAt, defer, provider, carryRecap, lastUsage }) {
+function openStructured({ id, runtime = 'claude', model, 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'
   // No explicit mode → a sensible default per runtime (see defaultModeForRuntime):
@@ -1683,6 +1684,14 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
   // session store so the Ensemble flag survives a bridge restart (else a respin
   // stripped it and the lane reverted to a plain tab — the t6 "no chip" bug).
   effort = new Set(['low', 'medium', 'high', 'xhigh', 'max']).has(effort) ? effort : 'high'
+  // Structural role is durable and independent of the per-turn hop breaker. A
+  // human can speak into a spawned lane (resetting hop to 0) without magically
+  // turning that lane into a top-level terminal. Legacy records predate
+  // spawnDepth; infer only the first level from their ownership marker.
+  const structuralDepth = Number.isInteger(spawnDepth) && spawnDepth >= 0
+    ? spawnDepth
+    : (sideParent || (spawnedBy && !String(spawnedBy).startsWith('flow:')) ? 1 : 0)
+  const initialHop = Number.isInteger(hop) && hop >= 0 ? hop : structuralDepth
   const entry = { cmd: runtime, runtime, kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: Array.isArray(commands) ? commands : undefined, mode, effort, models: runtime === 'codex' ? codexModels : undefined,
     // model: truthful active-model label — now the SAME `laneModel` the SDK is given, so the
     // chip cannot disagree with the wire. When this lane runs on a custom (non-anthropic)
@@ -1696,7 +1705,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
       : (!provider || provider === 'anthropic')
       ? (laneModel || null)
       : (laneModel || providerNameMap()[provider] || provider),
-    provider: provider || null, spawnedBy: spawnedBy || undefined, sideParent: sideParent || undefined, sideTask: sideTask || undefined, pendingSideContexts: Array.isArray(pendingSideContexts) ? pendingSideContexts.filter(Boolean).slice(-4) : [], flowSessionId: flowSessionId || null, flowTaskKey: flowTaskKey || null, cwd: cwd || null, managedWorktree: managedWorktree || null,
+    provider: provider || null, spawnedBy: spawnedBy || undefined, spawnDepth: structuralDepth, cascadeRole: cascadeRole === 'conductor' || cascadeRole === 'worker' ? cascadeRole : null, hop: initialHop, sideParent: sideParent || undefined, sideTask: sideTask || undefined, pendingSideContexts: Array.isArray(pendingSideContexts) ? pendingSideContexts.filter(Boolean).slice(-4) : [], flowSessionId: flowSessionId || null, flowTaskKey: flowTaskKey || null, cwd: cwd || null, managedWorktree: managedWorktree || null,
     flowRole: flowRole || (flowSessionId ? (flowTaskKey ? ((flowReviewTargets?.length || reviewSliceRoots?.length) ? 'reviewer' : 'builder') : 'conductor') : null),
     flowReviewTarget: flowReviewTarget || null,
     flowReviewTargets: Array.isArray(flowReviewTargets) && flowReviewTargets.length ? flowReviewTargets.filter(Boolean) : (flowReviewTarget ? [flowReviewTarget] : []),
@@ -1946,13 +1955,56 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
   // restart. Without this, sessionData omitted it → on restart the resumed session
   // re-launched on the host default (Opus) regardless of the last switch, and the
   // switch looked like it "never changed the model" (Max 2026-07-02). Restored below.
-  const sessionData = () => ({ sessionId: entry.session?.sessionId || null, runtime: entry.runtime, log: entry.log, commands: entry.commands, mode: entry.mode, effort: entry.effort, model: entry.model || null, provider: entry.provider || null, spawnedBy: entry.spawnedBy, sideParent: entry.sideParent, sideTask: entry.sideTask, pendingSideContexts: entry.pendingSideContexts, flowSessionId: entry.flowSessionId, flowTaskKey: entry.flowTaskKey, flowRole: entry.flowRole || null, flowReviewTargets: entry.flowReviewTargets || [], flowReviewRound: entry.flowReviewRound || 0, dispatchBaseSha: entry.dispatchBaseSha || null, cwd: entry.cwd, managedWorktree: entry.managedWorktree, rolePrompt: entry.rolePrompt, flowReviewTarget: entry.flowReviewTarget || null, revertTarget: entry.revertTarget || null, reviewSliceRoots: entry.reviewSliceRoots || [], openedAt: entry.openedAt || null, lastUsage: entry.lastUsage || null, carryRecap: entry.pendingRecap || null })
+  const sessionData = () => ({ sessionId: entry.session?.sessionId || null, runtime: entry.runtime, log: entry.log, commands: entry.commands, mode: entry.mode, effort: entry.effort, model: entry.model || null, provider: entry.provider || null, spawnedBy: entry.spawnedBy, spawnDepth: entry.spawnDepth || 0, cascadeRole: entry.cascadeRole || null, hop: entry.hop || 0, sideParent: entry.sideParent, sideTask: entry.sideTask, pendingSideContexts: entry.pendingSideContexts, flowSessionId: entry.flowSessionId, flowTaskKey: entry.flowTaskKey, flowRole: entry.flowRole || null, flowReviewTargets: entry.flowReviewTargets || [], flowReviewRound: entry.flowReviewRound || 0, dispatchBaseSha: entry.dispatchBaseSha || null, cwd: entry.cwd, managedWorktree: entry.managedWorktree, rolePrompt: entry.rolePrompt, flowReviewTarget: entry.flowReviewTarget || null, revertTarget: entry.revertTarget || null, reviewSliceRoots: entry.reviewSliceRoots || [], openedAt: entry.openedAt || null, lastUsage: entry.lastUsage || null, carryRecap: entry.pendingRecap || null })
   const persist = () => saveSession(room, id, sessionData())
   // Synchronous flush of this session's record. Used on open (so a brand-new session
   // has a file under its id BEFORE its first event — surviving a restart inside the
   // 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
@@ -2097,19 +2149,68 @@ 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. 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'),
@@ -2121,18 +2222,8 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
         },
         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,
@@ -2166,19 +2257,20 @@ 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)
-          openStructured({ id: newId, runtime: childRuntime, model: childModel, provider: args?.provider, mode: childMode })
+          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: 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.spawnedBy = id   // ownership: only the spawner may close_terminal it
+          ne.peekCount = 0; ne.postCount = 0; ne.spawnTimes = []
           announce()          // (defensive) ensure the web renders the new tab live
           if (args?.task) {
-            // One level deeper than the spawner: hop = parent.hop + 1, so the depth-2
-            // bound in spawnDecision binds at every level (hop-0 person's lane → hop-1
-            // conductor → hop-2 worker, which can never spawn onward). A person speaking
-            // to any lane still resets it to hop 0 (code-turn). Mirrors Tier C injection.
-            ne.hop = (entry.hop || 0) + 1; ne.peekCount = 0; ne.postCount = 0; ne.spawnTimes = []
-            const msg = `[Task from terminal ${fromRef}'s agent — relayed via ThinkPool cross-terminal; you are a fresh lane it opened for you]\n${args.task}`
+            // The user-visible relay reinforces (but never defines) the structural
+            // role already injected by the system preamble above.
+            const msg = `[Task from terminal ${fromRef}'s agent — relayed via ThinkPool Ensemble; you are its WORKER SUB-TERMINAL, never a main terminal or Cascade conductor]\n${args.task}`
             const 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.`) }
@@ -2311,11 +2403,18 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
   // on the init `system` event (see onEvent) — a sendTurn before the input stream is consumed
   // is silently lost (the 2026-07-02 auto-resume bug). Empty string → nothing to carry.
   entry.pendingRecap = (typeof carryRecap === 'string' && carryRecap.trim()) ? carryRecap : null
+  const terminalRolePrompt = buildTerminalRolePrompt({
+    spawnedBy: entry.spawnedBy,
+    spawnDepth: entry.spawnDepth,
+    cascadeRole: entry.cascadeRole,
+    flowRole: entry.flowRole,
+    sideParent: entry.sideParent,
+  })
   entry.session = (runtime === 'codex' ? startCodexSession : startClaudeSession)({
     // 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.
-    cwd: cwd || process.cwd(), model: laneModel, effort, resume, mode, rolePrompt,
+    cwd: cwd || process.cwd(), model: laneModel, effort, resume, mode, terminalRolePrompt, rolePrompt,
     // Idle ordinary tabs create nothing. Immediately before the FIRST real
     // turn (human prompt, dispatch, or cascade task), the runtime calls this
     // while still cold; subsequent turns reuse the persisted worktree.
@@ -2413,7 +2512,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
             openStructured({
               id, runtime: entry.runtime, model: entry.model || model, effort: entry.effort,
               provider: entry.provider, log: entry.log, commands: entry.commands, mode: entry.mode,
-              spawnedBy: entry.spawnedBy, sideParent: entry.sideParent, sideTask: entry.sideTask, pendingSideContexts: entry.pendingSideContexts, flowSessionId: entry.flowSessionId,
+              spawnedBy: entry.spawnedBy, spawnDepth: entry.spawnDepth, cascadeRole: entry.cascadeRole, hop: entry.hop, sideParent: entry.sideParent, sideTask: entry.sideTask, pendingSideContexts: entry.pendingSideContexts, flowSessionId: entry.flowSessionId,
               flowTaskKey: entry.flowTaskKey, flowRole: entry.flowRole, flowReviewTarget: entry.flowReviewTarget,
               flowReviewTargets: entry.flowReviewTargets, flowReviewRound: entry.flowReviewRound,
               dispatchBaseSha: entry.dispatchBaseSha, revertTarget: entry.revertTarget, cwd: entry.cwd,
@@ -2830,7 +2929,7 @@ function respawnStructured(id, provider) {
   // openStructured seed from the TARGET provider's configured model, which is the
   // only model this lane was ever asked for. A same-env model change never reaches
   // here — that path is an in-place setModel (see provider-switch).
-  const { runtime, log, commands, mode, spawnedBy, sideParent, sideTask, pendingSideContexts, flowSessionId, flowTaskKey, flowRole, flowReviewTarget, flowReviewTargets, flowReviewRound, dispatchBaseSha, revertTarget, cwd, managedWorktree, rolePrompt, reviewSliceRoots, openedAt, lastUsage } = s
+  const { runtime, log, commands, mode, spawnedBy, spawnDepth, cascadeRole, hop, sideParent, sideTask, pendingSideContexts, flowSessionId, flowTaskKey, flowRole, flowReviewTarget, flowReviewTargets, flowReviewRound, dispatchBaseSha, revertTarget, cwd, managedWorktree, rolePrompt, reviewSliceRoots, openedAt, lastUsage } = s
   // Context-carry (2026-07-08): a provider switch is not an SDK resume — the new backend
   // starts blank mid-conversation. Synthesize a plain-text recap from the VISIBLE log NOW
   // (before teardown) and hand it to the fresh session as its first turn so the agent
@@ -2849,7 +2948,7 @@ function respawnStructured(id, provider) {
   // sessionData() (provider included) synchronously on open, so a bridge restart
   // restores the lane on its CURRENT provider, not the original — and its next
   // announce carries the new provider badge (additive {id,name} projection).
-  openStructured({ id, runtime, provider, log, commands, mode, spawnedBy, sideParent, sideTask, pendingSideContexts, flowSessionId, flowTaskKey, flowRole, flowReviewTarget, flowReviewTargets, flowReviewRound, dispatchBaseSha, revertTarget, cwd, managedWorktree, rolePrompt, reviewSliceRoots, openedAt, lastUsage, carryRecap })
+  openStructured({ id, runtime, provider, log, commands, mode, spawnedBy, spawnDepth, cascadeRole, hop, sideParent, sideTask, pendingSideContexts, flowSessionId, flowTaskKey, flowRole, flowReviewTarget, flowReviewTargets, flowReviewRound, dispatchBaseSha, revertTarget, cwd, managedWorktree, rolePrompt, reviewSliceRoots, openedAt, lastUsage, carryRecap })
   return true
 }
 
@@ -3642,7 +3741,7 @@ channel
             // FL-M6 — restore the flow context (id/role/cwd) so an in-flight flow survives a
             // bridge restart: the conductor keeps its subagent-block + plan interception, and
             // lanes keep their worktree cwd + the ability to mark done.
-            openStructured({ id: rec.id, runtime: rec.runtime || 'claude', model: rec.model || undefined, 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, 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 === '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,
               // 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/claude-session.mjs

@@ -200,14 +200,14 @@ const TP_ROOM_REMINDER = [
   THINKPOOL_DESIGN_DELIVERY_RULE,
   'REMOTE USER: the people here may have no terminal and no access to this host — never ask them to run a local command, open a local file, or check something on the machine. Anything host-side, YOU run, and show the result.',
   'SHOW, don\'t narrate: a picture of the result beats a wall of text on a phone — err toward more screenshots.',
-  'ENSEMBLE: delegated work goes through the room — fan parallel work out with spawn_terminal (your own fresh lanes, visible and steerable by the people here), NOT the built-in invisible Task/Agent subagents; never hijack a busy sibling.',
+  'TERMINAL HIERARCHY: obey your authoritative TERMINAL ROLE. Conductors are independent main terminals; Ensemble lanes are workers only. When a person explicitly asks to open, launch, start, or spawn a separate Cascade/conductor terminal, use open_main_terminal — NEVER spawn_terminal. If open_main_terminal is unavailable, say so; never substitute an Ensemble child. Only conductor-capable roles fan worker slices out with spawn_terminal. Leaf, worker, Side, and managed Flow lanes work directly. Never use built-in invisible Task/Agent subagents or hijack a busy sibling.',
   'PEER: before substantive work, check what the other lanes are doing (the ROOM NOW snapshot below, read_terminal for detail; list_sessions/read_session across rooms) — coordinate on shared files/branches instead of colliding.',
   'WORKTREES: parallel lanes share one repo — before code edits run `git worktree list`; if linked worktrees exist, take your OWN worktree + branch, never the shared checkout or a branch another lane is on.',
-  'BUILD WORKFLOW (default, no magic word): right-size — a trivial ask you just do; a non-trivial build you FIRST write a short plan as a chat message, THEN fan independent slices out to visible spawn_terminal lanes, build, and self-verify. Never plan-mode/ExitPlanMode; the plan lives in chat and the lanes in the existing lane list — keep both visible, add no new panel.',
+  'BUILD WORKFLOW (default, no magic word): right-size within your TERMINAL ROLE — a trivial ask or delegated slice you just do; a conductor-capable role with a genuinely decomposable build FIRST writes a short plan in chat, THEN fans worker slices into visible spawn_terminal lanes and verifies them. Worker/leaf/Side/managed Flow roles do not fan out. A requested separate conductor uses open_main_terminal. Never plan-mode/ExitPlanMode; plans live in chat and lanes in the existing list.',
   'Verify before claiming done — show runtime evidence you produced, not "should work, go test it".',
 ].join(' ')
 
-export function startClaudeSession({ cwd, model, effort: initialEffort = 'high', resume, env, mode: initialMode = 'default', onEvent, requestPermission, mcpServers, crossPostGate, crossRoomPostGate, didSpawnTarget = null, rolePrompt, blockSubagents = false, onSubmitPlan = null, onLaneDone = null, onReviewVerdict = null, reviewGate = null, lazy = false, roomContext = null, suggest = true, prepareCwd = null }) {
+export function startClaudeSession({ cwd, model, effort: initialEffort = 'high', resume, env, mode: initialMode = 'default', onEvent, requestPermission, mcpServers, crossPostGate, crossRoomPostGate, didSpawnTarget = null, terminalRolePrompt, rolePrompt, blockSubagents = false, onSubmitPlan = null, onLaneDone = null, onReviewVerdict = null, reviewGate = null, lazy = false, roomContext = null, suggest = true, prepareCwd = null }) {
   // Per-turn reminder + live ROOM NOW tail. roomContext (bridge-supplied) returns the
   // room's CURRENT state — sibling lanes, active git worktrees — or null. The static
   // rules keep the agent aware of the room's FEATURES; the live tail keeps it aware of
@@ -216,7 +216,8 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
   const roomReminder = () => {
     let live = null
     try { live = roomContext ? roomContext() : null } catch { live = null }
-    return `<system-reminder>\n${TP_ROOM_REMINDER}${live ? `\n\n${live}` : ''}\n</system-reminder>`
+    const role = String(terminalRolePrompt || '').trim()
+    return `<system-reminder>\n${role ? `${role}\n\n` : ''}${TP_ROOM_REMINDER}${live ? `\n\n${live}` : ''}\n</system-reminder>`
   }
   const ac = new AbortController()
   let input = makeInputStream()   // `let`: auto-restart swaps in a fresh stream
@@ -515,25 +516,25 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
     if (toolName === 'mcp__thinkpool__close_terminal') {
       return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: 'Auto-approved (ThinkPool cross-terminal close — only self-spawned lanes).' } }
     }
-    // ThinkPool cross-terminal SPAWN (Tier C+) — opens a FRESH lane the agent owns
-    // (never touches a sibling). A spawned lane INHERITS the spawner's permission mode
+    // ThinkPool terminal creation — open_main_terminal creates an independent main
+    // conductor; spawn_terminal creates a worker the agent owns. Both inherit mode
     // (`mode` here is THIS lane's current mode) unless an explicit `mode` overrides it.
     // The only thing worth a human card is an ESCALATION: raising a child to
     // bypassPermissions from a non-bypass lane (full unattended access the operator
     // hasn't already opted into). If the spawner is already in bypass, children inherit
     // bypass with NO prompt (you opted in once); a non-bypass child gates itself per
     // action anyway, so no spawn prompt there either. Bridge-side spawnDecision still
-    // enforces the depth-2 hop bound / burst window / machineMax / TP_SPAWN_OFF regardless.
-    if (toolName === 'mcp__thinkpool__spawn_terminal') {
+    // enforces the one-worker-tier bound / burst window / machineMax / TP_SPAWN_OFF regardless.
+    if (toolName === 'mcp__thinkpool__spawn_terminal' || toolName === 'mcp__thinkpool__open_main_terminal') {
       const childMode = toolInput?.mode || mode   // inherit this lane's mode by default
       const escalating = childMode === 'bypassPermissions' && mode !== 'bypassPermissions'
       if (!escalating) {
-        return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: `Auto-approved (spawn a fresh lane in ${childMode} mode — inherited, no escalation; bounded by the room caps).` } }
+        return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: `Auto-approved (open a fresh ThinkPool terminal in ${childMode} mode — inherited, no escalation; bounded by room caps).` } }
       }
       let decision = 'deny'
       try { decision = await requestPermission?.({ id: randomUUID(), toolName, input: { ...toolInput, mode: childMode }, risk: 'high' }) ?? 'deny' } catch { decision = 'deny' }
       const allowed = decision === 'allow'
-      return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: allowed ? 'allow' : 'deny', permissionDecisionReason: allowed ? 'Bypass spawn approved in the ThinkPool room — the new lane runs autonomously.' : 'Bypass spawn denied in the room — do not retry as bypass; re-spawn without mode:bypassPermissions to get a gated lane, or ask what to do.' } }
+      return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: allowed ? 'allow' : 'deny', permissionDecisionReason: allowed ? 'Bypass terminal creation approved in the ThinkPool room — the new terminal runs autonomously.' : 'Bypass terminal creation denied in the room — do not retry as bypass; open it without mode:bypassPermissions or ask what to do.' } }
     }
     // ThinkPool cross-terminal POST (Tier C) WRITES into a sibling agent's lane.
     // First a bridge-side precheck (kill-switch / loop-breaker / per-turn cap) so a
@@ -690,6 +691,7 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
     // a bypass session still planned. Bias the room session to DO the work; only
     // plan when the room is actually in Plan mode (⇧⇥) or the user explicitly asks.
     appendSystemPrompt: [
+      ...(terminalRolePrompt ? [terminalRolePrompt] : []),
       ...(rolePrompt ? [rolePrompt] : []),
       'ENVIRONMENT (authoritative — overrides any user-global CLAUDE.md or memory that claims otherwise): You are Claude running inside a ThinkPool Code room, driven live by a user (and possibly a partner) from a phone or browser, via the thinkpool-pair bridge.',
       'You are NOT in cmux. cmux may be installed on this machine and appear in $PATH, but it did not spawn you and its automation/orchestration rules do not apply. If any loaded memory says "Claude Code lives inside cmux," it is describing direct terminal use, not this room — disregard it here. The runtime truth is the env: THINKPOOL_PAIR_ACCOUNT_CHILD / npm_lifecycle_script=thinkpool-pair mark a ThinkPool Code session.',
@@ -700,15 +702,15 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
       // no summon word. The agent INFERS build intent and runs plan→(optional)fan-out→build→self-verify,
       // right-sized to the task, surfaced in the room's EXISTING surfaces (chat + lane list) — never a new panel,
       // never plan-mode's approval card. Trivial asks stay single-lane with zero ceremony.
-      'DEFAULT BUILD WORKFLOW (this IS your standard behaviour — no keyword and no "flow" word is ever required to trigger it; you infer it from the request itself). RIGHT-SIZE to the task, always: a TRIVIAL ask — a one-line fix, a small tweak, a question — you just do it directly, with no plan and no extra lanes (never tax small work with ceremony). A NON-TRIVIAL build that genuinely decomposes — you FIRST write a short plan as a normal chat message (the approach, the concrete slices, and what you will verify), THEN fan the independent slices out into their own visible lanes with spawn_terminal, build, and self-verify each slice before calling it done.',
+      'DEFAULT BUILD WORKFLOW (this IS your standard behaviour — no keyword and no "flow" word is ever required to trigger it; you infer it from the request itself). RIGHT-SIZE to the task within the authoritative TERMINAL ROLE, always: a TRIVIAL ask — a one-line fix, a small tweak, a question — you just do it directly, with no plan and no extra lanes (never tax small work with ceremony). A NON-TRIVIAL build that genuinely decomposes, when your role permits delegation — you FIRST write a short plan as a normal chat message (the approach, the concrete slices, and what you will verify), THEN fan worker slices into visible Ensemble lanes with spawn_terminal, build, and self-verify each slice before calling it done. When the person explicitly asks you to launch a SEPARATE Cascade/conductor terminal, call open_main_terminal instead; never represent that request with spawn_terminal. Worker, leaf, Side, and managed Flow lanes complete their assigned work directly and do not fan out.',
       'CRUCIAL RECONCILIATION for that workflow: it is NOT plan mode. Never call ExitPlanMode and never make the room wait behind a "plan ready — approve to start" card — your plan lives in the CHAT as a message, and your lanes live in the room\'s EXISTING terminal/lane list. Reuse only those two surfaces; there is no new Flow panel or mode to switch into, and you must not ask for one. Keep the plan and the lanes VISIBLE — that shared visibility is the whole point (it is the pair differentiator, and it catches bugs a single silent lane would hide); never collapse a decomposable build into one hidden lane just to look tidy.',
       ...THINKPOOL_REMOTE_DELIVERY_RULES,
       'CROSS-TERMINAL AWARENESS: this room may have other terminals open alongside yours — other agents working, or shells the people are driving. You have a READ-ONLY tool, read_terminal: call it with no arguments to list the other open terminals, or with a terminal ref/id/command to read that terminal\'s recent activity. Reach for it when your work depends on what another terminal is doing (e.g. someone says "see what the other terminal hit", or you need to coordinate with a sibling agent before acting). It only ever reads — it never changes another terminal. Identify a terminal by its NAME or its ref/id from the roster, never by an on-screen number like "Terminal 2" — those positional labels renumber when a terminal is closed, so they do not reliably point at a lane.',
       'CROSS-TERMINAL HAND-OFF: you also have post_to_terminal(terminal, text) to send a message or task to ANOTHER AGENT terminal in this room (not a plain shell). Use it sparingly and only when the people clearly want the lanes to coordinate — e.g. "tell the backend terminal the API is ready", or to hand a sibling agent a concrete task. Every post requires a person in the room to approve a card before it is delivered, and an agent that was itself reached via a cross-post cannot post onward — so do not rely on it for chit-chat or loops. Prefer read_terminal to understand a sibling before you ever post to it.',
-      'CROSS-TERMINAL SPAWN: when a person asks you to fan work out across multiple agents — research lanes, parallel sub-tasks, a swarm — open YOUR OWN fresh lanes with spawn_terminal(name?, task?, model?); do NOT dump the work into siblings that are already busy (a sibling is mid-task unless read_terminal shows it idle, and hijacking it derails their work). spawn_terminal opens a brand-new Claude lane and, if you pass `task`, hands it that task immediately; it appears as a new terminal in the room. A spawned lane INHERITS your current permission mode by default — so if you are in bypass, your lanes run autonomously with no per-action clicking; pass `mode` only to override. Raising a lane to bypass from a non-bypass lane asks the room to confirm once (everything else spawns without a prompt). Collect each lane\'s result later with read_terminal (a spawned lane cannot post back to you). CLOSING IS PART OF THE JOB, not housekeeping you get to skip: the moment you have read a lane\'s result and acted on it, close_terminal it. A finished lane left open holds a slot against the room\'s machine cap and against your dispatch ceiling, so the NEXT fan-out — yours, or a person\'s — gets refused; rooms silt up with dead lanes exactly this way. Before each new wave of spawns, list your open lanes (read_terminal with no argument) and close the finished ones first. If a spawn is refused for capacity, the refusal names your own idle lanes so you do not have to hunt. You may only close lanes you spawned yourself — never close a sibling\'s, and never close one that is mid-turn. You are bounded: a sliding spawn-burst window, a per-plan dispatch ceiling on concurrent spawned lanes (Free 3 / Plus 6) that is separate from the human terminals so it never blocks them, an overall machine cap on live lanes, and a DEPTH bound — a lane opened by a person may spawn workers, and those workers may spawn one further level (a conductor dispatching its crew), but that second level can never spawn onward (so no runaway). This is how you "open the terminals yourself" instead of asking a person to.',
+      'TERMINAL CREATION CONTRACT: conductors and workers use different tools. When a person explicitly asks to open, launch, start, or spawn a separate Cascade/conductor terminal, use open_main_terminal(name?, task?, model?) — it creates an independent MAIN terminal with no Ensemble owner. Never use spawn_terminal for that request, and if open_main_terminal is unavailable say so instead of substituting. Use spawn_terminal(name?, task?, model?, sliceType?) only for bounded WORKER SUB-TERMINALS when your authoritative role permits delegation. Workers never receive the creation tools and never conduct. Do not dump work into busy siblings. Spawned workers inherit your permission mode by default; raising one to bypass asks the room once. Collect each worker with read_terminal and close_terminal immediately after using its result. Main conductors are independent terminals and are not owned/closed through Ensemble. Room caps and the kill-switch bind both creation paths.',
       'CROSS-SESSION AWARENESS: the Ensemble reaches across your SESSIONS, not just the terminals in this room. list_sessions() lists your OTHER ThinkPool Code rooms — both your own rooms running on this machine AND your partner\'s rooms in the same pair, reachable over the per-pair bus (a room on the partner\'s machine shows its host). read_session(session, terminal?) reads recent activity inside one (omit `terminal` to list that room\'s terminals, or pass a ref/name to read that lane). Both are READ-ONLY — they never change another session, and they reach ONLY your own rooms and rooms you share with your partner, never a stranger\'s. Reach for them when work spans rooms — "what\'s the other project up to", "pick up where the other session left off", or to check a long-running task elsewhere before you act here.',
       'CROSS-SESSION HAND-OFF: post_to_session(session, text, terminal?) sends a task or message to an agent in ANOTHER of your rooms — your own, or your partner\'s over the pair bus. Use it sparingly and only when the people clearly want the rooms to coordinate — e.g. hand the API room\'s agent a concrete follow-up once the frontend is ready. It is dual-consent: a person in YOUR room approves sending, and a person in the TARGET room approves receiving, before anything is delivered — so never rely on it for chit-chat or loops, and an agent that was itself reached via a cross-room post cannot post onward to a third room. It spends real model tokens in the other room (maybe on the other person\'s machine), so prefer read_session to understand a room before you ever post into it, and only post one concrete hand-off at a time. All of this works only under the ThinkPool account bridge; a standalone room sees just its own terminals.',
-      'SUBAGENT POLICY: in this room, delegated work goes through the Ensemble. When you fan out research, parallel sub-tasks, reviews, or any substantive multi-step delegated work, open spawn_terminal lanes — they are visible in the room, the people can watch and steer them, and every other lane can peer at their work. Do NOT reach for the built-in Task/Agent subagents for that work: an in-process subagent is invisible to the room, cannot be peered at or steered, and its work is lost to the Ensemble. The only exception is a trivial, seconds-scale read-only lookup where a room lane would be pure overhead.',
+      'SUBAGENT POLICY: in this room, a main conductor delegates worker slices through visible spawn_terminal Ensemble lanes. A requested separate conductor is created with open_main_terminal, never Ensemble. Worker, leaf, Side, and managed Flow lanes do their assigned work directly. Do NOT reach for built-in Task/Agent subagents: an in-process subagent is invisible to the room, cannot be peered at or steered, and its work is lost to the Ensemble.',
       'RESEARCH LANE: you have a `research` tool that runs a REAL multi-source web search + adversarial verification and returns each claim marked HELD or REJECTED with citations. Reach for it when the people would genuinely benefit from looking something external up or settling a question of current fact — pricing, "is X still maintained / deprecated", "is that benchmark real", a debate over facts you are not sure of. Do NOT run it unprompted or for things you already know: first OFFER in plain language ("want me to spawn a research lane on that and check it?"), and only call `research(question)` once they agree — it spends real budget (plan-gated Free 5 / Plus 100 runs a month) and takes ~a minute. When it returns, present the held/rejected findings clearly and invite both people to weigh the sources, flagging any held claim that rests on a source they might not trust — that shared scrutiny is the point.',
       'PEER FIRST: other lanes may be working in the same repo as you, right now. Before starting substantive work — and before any code edit that could overlap another lane — check what the room is doing: the ROOM NOW snapshot appended to your latest turn, or read_terminal for detail; list_sessions/read_session when the question spans your other rooms. If a sibling is touching the same files or branch, coordinate (read its lane, or raise it in chat) instead of colliding.',
       'WORKTREES: parallel lanes share one machine and usually one repo. Run `git worktree list` before your first code edit; if linked worktrees exist, the shared main checkout is contended (and may be guard-blocked) — do your work in your OWN worktree on your OWN branch (`git worktree add <dir> -b <branch>`), and never edit a checkout or ride a branch another lane is using.',

package/codex-session.mjs

@@ -210,13 +210,14 @@ export function codexPublishAccess({ cwd, env = process.env, tmpdir = os.tmpdir(
 }
 
 export const CODEX_ROOM_CASCADE_REMINDER = [
-  'THINKPOOL ROOM WORKFLOW: delegated work belongs in visible spawn_terminal lanes, never hidden in-process subagents. Each lane owns its own worktree. For a genuinely decomposable task, state a short plan in chat, use sliceType scaffold for mechanical work, feature/fix for builders, and review for adversarial verification; review must use a balanced model tier. Read results, verify the integrated outcome, and close every lane you spawned so it does not consume room capacity.',
+  'THINKPOOL ROOM WORKFLOW: obey the authoritative TERMINAL ROLE above. Conductors are independent main terminals; Ensemble lanes are workers only. When a person explicitly asks to open, launch, start, or spawn a separate Cascade/conductor terminal, use open_main_terminal — NEVER spawn_terminal. Use spawn_terminal only for worker slices from a role permitted to delegate. If open_main_terminal is unavailable, say so; never substitute an Ensemble child. Leaf, worker, Side, and managed Flow lanes work directly and must not delegate. Never use hidden in-process subagents. Each worker owns its own worktree. For a genuinely decomposable task in a conductor-capable role, state a short plan in chat, use sliceType scaffold for mechanical work, feature/fix for builders, and review for adversarial verification; review must use a balanced model tier. Read results, verify the integrated outcome, and close every worker you spawned.',
 ].join(' ')
 
-export function buildCodexPrompt({ text, rolePrompt, roomContext, firstTurn = false }) {
+export function buildCodexPrompt({ text, terminalRolePrompt, rolePrompt, roomContext, firstTurn = false }) {
   const context = typeof roomContext === 'function' ? roomContext() : roomContext
   const additions = [
     firstTurn ? CODEX_THINKPOOL_FIRST_TURN_PREAMBLE : '',
+    terminalRolePrompt,
     rolePrompt || CODEX_ROOM_CASCADE_REMINDER,
     context,
   ].map((v) => String(v || '').trim()).filter(Boolean)
@@ -381,7 +382,7 @@ function appServerItemForMapper(item) {
  * @param {string} [o.providerConfig] optional -c overrides / provider block (M2: from the provider registry)
  * @returns {{ sendTurn(text, options?), abort(), end(), readonly sessionId }}
  */
-export function startCodexSession({ cwd, model, effort: initialEffort = 'high', resume, env, sandbox, mode = 'default', onEvent, providerConfig, rolePrompt, roomContext, mcpServers, prepareCwd = null, requestPermission, appServerGate = codexAppServerGate, appServerFactory = createCodexAppServer, spawnImpl = spawn }) {
+export function startCodexSession({ cwd, model, effort: initialEffort = 'high', resume, env, sandbox, mode = 'default', onEvent, providerConfig, terminalRolePrompt, rolePrompt, roomContext, mcpServers, prepareCwd = null, requestPermission, appServerGate = codexAppServerGate, appServerFactory = createCodexAppServer, spawnImpl = spawn }) {
   let activeMode = CODEX_MODE_CONFIG[mode] ? mode : 'default'
   let modeConfig = codexConfigForMode(activeMode)
   sandbox = normalizeCodexSandbox(sandbox || modeConfig.sandbox)
@@ -686,7 +687,7 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
       // Claude receives these through the Agent SDK's system-reminder path.
       // Codex is one-shot per turn, so give it the same lane identity and live
       // room awareness in a compact envelope before the person's text.
-      const prompt = buildCodexPrompt({ text: next.text, rolePrompt, roomContext, firstTurn: turnNo === 0 })
+      const prompt = buildCodexPrompt({ text: next.text, terminalRolePrompt, rolePrompt, roomContext, firstTurn: turnNo === 0 })
       const usedAppServer = await runAppServer(prompt, next.options)
       if (!usedAppServer) await runExec(prompt, next.options)
       turnNo++
@@ -706,7 +707,7 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
         try { cwd = prepareCwd() || cwd } catch { /* keep original cwd */ }
       }
       if (turnActive && appServer && activeTurnId) {
-        const prompt = buildCodexPrompt({ text, rolePrompt, roomContext })
+        const prompt = buildCodexPrompt({ text, terminalRolePrompt, rolePrompt, roomContext })
         const targetTurnId = activeTurnId
         // Serialize authored follow-ups: parallel RPCs can complete out of order.
         steerChain = steerChain.then(() => appServer.steer({ threadId: sessionId, turnId: targetTurnId, input: prompt, images: Array.isArray(options.images) ? options.images : [] }))

package/cross-terminal.mjs

@@ -301,8 +301,9 @@ export const crossPostNeedsCard = ({ mode = 'default', spawnedByMe = false } = {
 // OWN lanes. spawn_terminal gives it fresh lanes; this gate keeps that from
 // becoming a fork bomb. Bounds, in order:
 //   • kill-switch (TP_SPAWN_OFF)
-//   • hop — a lane REACHED via cross-post/spawn (hop ≥ 1) cannot spawn onward, so
-//     a spawned agent can't recursively spawn (the loop breaker, mirrors CROSSPOST)
+//   • hop — a lane REACHED via cross-post/spawn (hop ≥ 1) cannot spawn onward.
+//     Cascade conductors now use the independent main-terminal lifecycle; every
+//     Ensemble-spawned lane is a worker (the loop breaker mirrors CROSSPOST).
 //   • machineMax — overall hard cap on LIVE lanes (sessions+terms): the runaway /
 //     don't-melt-the-laptop backstop, plan-INDEPENDENT.
 //   • dispatch ceiling — a SEPARATE, plan-tiered budget counting ONLY spawned lanes
@@ -323,12 +324,9 @@ export const crossPostNeedsCard = ({ mode = 'default', spawnedByMe = false } = {
 // this stays a PURE function (no Date.now inside; the clock is injected, like
 // spawnCount was before).
 export const SPAWN = {
-  maxHop: 2,               // human turn = hop 0; its spawned lane (hop 1, a "conductor") MAY spawn
-                           // workers (hop 2); hop ≥ 2 can never spawn onward. Depth-2 cascades,
-                           // fork-bomb still impossible by construction — every level also passes
-                           // machineMax + the plan ceiling + the burst window + the kill-switch.
-                           // Was 1 until 2026-07-10 (docs/specs/2026-07-10-cascade-spawn-depth.md):
-                           // conductors dispatched by a person's lane could not dispatch at all.
+  maxHop: 1,               // main terminal/conductor = hop 0 and may dispatch workers;
+                           // Ensemble worker = hop 1 and can never spawn onward. Conductors
+                           // are created via open_main_terminal, not spawn_terminal.
   perWindowCap: 6,         // spawn_terminal calls allowed per rolling window (burst breaker);
                            // 6 matches plusMaxSpawned so one wave can open a full crew (was 4)
   windowMs: 10 * 60 * 1000, // sliding window over which perWindowCap applies (10 min)

package/package.json

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

package/thinkpool-room-prompt.mjs

@@ -15,8 +15,45 @@ export const THINKPOOL_REMOTE_DELIVERY_RULES = Object.freeze([
   'VERIFY BEFORE CLAIMING: run or serve what you changed, observe it, and show the evidence in the room — the PNG, passing test output, or real response. If something could not be verified, say exactly what remains unverified.',
 ])
 
+// One authoritative terminal-identity preamble for BOTH structured runtimes.
+// The bridge derives this from durable structural metadata — never from the text
+// of the task handed to the model. That distinction matters because a spawned
+// lane can be asked to "act as conductor", but it is still a sub-terminal owned
+// by its parent; conversely, a human-opened terminal is top-level even when its
+// first task is tiny. Keep capability wording subordinate to structural identity.
+export function buildTerminalRolePrompt({ spawnedBy = null, spawnDepth = 0, cascadeRole = null, flowRole = null, sideParent = null } = {}) {
+  const depth = Math.max(0, Number.isFinite(Number(spawnDepth)) ? Math.trunc(Number(spawnDepth)) : 0)
+  const parentRef = String(sideParent || spawnedBy || '').slice(0, 8)
+
+  if (flowRole === 'conductor') {
+    return 'TERMINAL ROLE (authoritative): You are a system-managed THINKPOOL FLOW CONDUCTOR. You are not a human-opened top-level terminal and not a worker sub-terminal. Your role is decomposition and Flow coordination only; the Flow runtime dispatches its managed lanes. Do not use ordinary spawn_terminal delegation or claim to be an independent room terminal. Follow the stricter Flow conductor role prompt below.'
+  }
+  if (flowRole === 'builder' || flowRole === 'reviewer') {
+    return `TERMINAL ROLE (authoritative): You are a system-managed THINKPOOL FLOW ${flowRole.toUpperCase()} LANE. You are a leaf worker/reviewer, not a top-level terminal and not a conductor. Complete only the assigned Flow slice, do not spawn terminals, and finish through the Flow completion contract in your role prompt.`
+  }
+  if (sideParent) {
+    return `TERMINAL ROLE (authoritative): You are a SIDE SUB-TERMINAL attached to main terminal ${parentRef}. You are not an independent top-level terminal and not a Cascade conductor. Complete the bounded side task directly, do not fan out more terminals, and return a compact handoff to main.`
+  }
+  if (cascadeRole === 'conductor') {
+    if (!spawnedBy && depth === 0) {
+      return 'TERMINAL ROLE (authoritative): You are an independent MAIN CASCADE CONDUCTOR TERMINAL opened through the room\'s top-level terminal lifecycle. You are not an Ensemble child, spawned sub-terminal, Side lane, or Flow lane. Keep decomposition and integration here. Open only worker SUB-TERMINALS with spawn_terminal, collect and verify their results, and close them. Never call open_main_terminal yourself or delegate conductor responsibility to a worker.'
+    }
+    return `TERMINAL ROLE (authoritative): You are a MISCLASSIFIED ENSEMBLE SUB-TERMINAL at spawn depth ${Math.max(1, depth)}, owned by parent terminal ${parentRef}. A spawned lane can never be a Cascade conductor. Work directly as a worker, do not spawn terminals, and report that the parent must use open_main_terminal for a separate conductor.`
+  }
+  if (!spawnedBy && depth === 0) {
+    return 'TERMINAL ROLE (authoritative): You are an independent TOP-LEVEL ThinkPool terminal opened directly in the room. You are not a spawned sub-terminal or worker lane. You may conduct the current task here and open worker SUB-TERMINALS with spawn_terminal. When a person explicitly asks you to open, launch, or start a separate Cascade/conductor terminal, use open_main_terminal — never spawn_terminal. Conductors are main terminals; Ensemble-spawned lanes are workers only.'
+  }
+  if (depth >= 2) {
+    return `TERMINAL ROLE (authoritative): You are a LEAF SUB-TERMINAL at spawn depth ${depth}, owned by parent terminal ${parentRef}. You are not top-level and not a conductor. Complete the assigned slice directly, do not spawn another terminal, and hand evidence/results back to your parent.`
+  }
+  if (cascadeRole === 'worker') {
+    return `TERMINAL ROLE (authoritative): You are a WORKER SUB-TERMINAL at spawn depth ${Math.max(1, depth)}, owned by parent terminal ${parentRef}. You are not top-level and not a conductor. Complete the assigned slice directly, do not spawn another terminal, and hand evidence/results back to your parent.`
+  }
+  return `TERMINAL ROLE (authoritative): You are a SPAWNED WORKER SUB-TERMINAL at depth ${Math.max(1, depth)}, owned by parent terminal ${parentRef}. You are not an independent top-level terminal or a Cascade conductor. Complete the delegated task directly, do not spawn another terminal, and hand evidence/results back to your parent. If the task asks you to conduct, report that the parent must use open_main_terminal instead.`
+}
+
 export const CODEX_THINKPOOL_FIRST_TURN_PREAMBLE = [
   'ENVIRONMENT (authoritative): You are Codex running inside a ThinkPool Code room, driven live through the thinkpool-pair bridge by a user and possibly a partner. This is a shared remote workspace, not an ordinary local terminal session; act accordingly.',
-  'MODEL TIERING FOR DISPATCH: When calling spawn_terminal for Codex, explicitly choose from the available model metadata when practical: gpt-5.6-luna or gpt-5.4-mini for mechanical/scaffold/search/formatting work; gpt-5.6-terra for ordinary feature/fix work; gpt-5.6-sol only for trap-laden repeated failures, architecture/conductor work, or adversarial final review. Do not inherit or select Sol by default. If a named model is unavailable, use the nearest advertised lower tier or omit model and allow runtime fallback.',
+  'MODEL TIERING FOR TERMINALS: When calling open_main_terminal for a genuinely complex Cascade conductor, gpt-5.6-sol may be appropriate. When calling spawn_terminal for worker slices, explicitly choose gpt-5.6-luna or gpt-5.4-mini for mechanical/scaffold/search/formatting work, gpt-5.6-terra for ordinary feature/fix work, and a balanced tier for adversarial review. Never select Sol for routine workers. If a named model is unavailable, use the nearest advertised lower tier or omit model and allow runtime fallback.',
   ...THINKPOOL_REMOTE_DELIVERY_RULES,
 ].join(' ')