thinkpool-pair 0.7.268 → 0.7.270

package/bridge.mjs

@@ -51,10 +51,11 @@ import { validateProviderSwitch, providerSwitchPlan, BUILTIN_PROVIDER } from './
 import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
 import { z } from 'zod'
 import { readCodexDefaultModel, readCodexModels, codexConfigForMode, codexThreadCanResume } from './codex-session.mjs'
+import { codexAccountUsageLine, codexCreditsReportLine, codexLimitReportLine } from './codex-commands.mjs'
 import { withMcpSessionFactory } from './codex-mcp-http.mjs'
 import { startStructuredSession } from './runtime-session.mjs'
-import { defaultStructuredMode, normalizeStructuredEffort, shouldDeferStructuredRuntime, structuredRuntimeForCommand, structuredRuntimeMetadata, structuredRuntimeSupportsMode } from './runtime-registry.mjs'
-import { reconcileCommandCatalog } from './command-catalog.mjs'
+import { defaultStructuredMode, normalizeStructuredEffort, shouldDeferStructuredRuntime, structuredModeForSlice, structuredModeLocked, structuredModesForLane, structuredRuntimeForCommand, structuredRuntimeMetadata, structuredRuntimeSupportsMode } from './runtime-registry.mjs'
+import { commandCatalogForRuntime, commandHelpLine, reconcileCommandCatalog } from './command-catalog.mjs'
 import { probeHermesRuntime } from './hermes-probe.mjs'
 import { hermesRequiredMcpTools, hermesRoleFor } from './hermes-policy.mjs'
 import { canonicalRoomFilePath, waitForNativeImages } from './codex-images.mjs'
@@ -1128,7 +1129,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, 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' } : {}),
+      ...[...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'), modes: structuredModesForLane(s.runtime || 'claude', s) }, ...(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 +
@@ -1747,6 +1748,7 @@ function worktreeSnapshot(cwd) {
 function openStructured({ id, runtime = 'claude', model, models, effort, resume, log, commands, mode, spawnedBy, spawnDepth, cascadeRole, hop, sideParent, sideTask, pendingSideContexts, rolePrompt, sliceType, flowSessionId, flowTaskKey, flowRole, flowReviewTarget, flowReviewTargets, flowReviewSnapshots, flowReviewRound, dispatchBaseSha, revertTarget, cwd, managedWorktree, reviewSliceRoots, openedAt, defer, provider, carryRecap, lastUsage }) {
   if (sessions.has(id)) return
   runtime = structuredRuntimeMetadata(runtime) ? runtime : 'claude'
+  mode = structuredModeForSlice(runtime, { mode, sliceType, flowRole })
   // 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.
@@ -1783,7 +1785,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
     ? 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 : runtime === 'hermes' && Array.isArray(models) ? models : undefined,
+  const entry = { cmd: runtime, runtime, kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: commandCatalogForRuntime(runtime, commands), mode, effort, models: runtime === 'codex' ? codexModels : runtime === 'hermes' && Array.isArray(models) ? models : 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)
     // registered provider the SDK id is impersonated (see the onEvent guard below), so
@@ -2427,7 +2429,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
             runtime: resolved.runtime,
             model: resolved.model,
             provider: resolved.provider,
-            mode: resolved.mode,
+            mode: structuredModeForSlice(resolved.runtime, { mode: resolved.mode, sliceType: args?.sliceType }),
           }
           let preview
           try {
@@ -2483,7 +2485,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           // 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, sliceType: args?.sliceType, flowReviewTargets: manualReviewSnapshots.map((item) => item.taskKey), flowReviewSnapshots: manualReviewSnapshots, spawnedBy: id, spawnDepth: childSpawnDepth, cascadeRole: 'worker', hop: childHop })
+          openStructured({ id: newId, runtime: resolved.runtime, model: resolved.model, provider: resolved.provider, mode: effectiveArgs.mode, sliceType: args?.sliceType, flowReviewTargets: manualReviewSnapshots.map((item) => item.taskKey), flowReviewSnapshots: manualReviewSnapshots, spawnedBy: id, spawnDepth: childSpawnDepth, cascadeRole: 'worker', hop: childHop })
           const ne = sessions.get(newId)
           if (!ne) { if (args?.name) { delete termNames[newId]; saveNames(room, termNames) } return okText('Could not open a new lane — the terminal cap may have just been reached. Close one and retry.') }
           ne.peekCount = 0; ne.postCount = 0; ne.spawnTimes = []
@@ -2663,10 +2665,16 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
     // turn (human prompt, dispatch, or cascade task), the runtime calls this
     // while still cold; subsequent turns reuse the persisted worktree.
     prepareCwd: (!cwd && !flowSessionId && !flowTaskKey) ? () => {
-      if (entry.managedWorktree?.dir) return entry.managedWorktree.dir
       try {
-        entry.managedWorktree = createManagedLaneWorktree({ terminalId: id, cwd: process.cwd() })
+        if (!entry.managedWorktree?.dir) {
+          entry.managedWorktree = createManagedLaneWorktree({ terminalId: id, cwd: process.cwd() })
+        }
         entry.cwd = entry.managedWorktree.dir
+        // ViewportManager is created while an ordinary terminal is still cold,
+        // before this lazy worktree exists. Rebind it in the same handoff that
+        // moves the agent runtime, or preview_start serves the bridge checkout's
+        // stale dist instead of this lane's build.
+        entry.viewport.setWorkspaceRoot(entry.cwd)
         try { entry.flush?.() } catch { /* first turn may precede flush wiring */ }
         return entry.cwd
       } catch (error) {
@@ -2767,7 +2775,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       const duplicateCommandCatalog = evt.kind === 'system'
         ? reconcileCommandCatalog({
           current: entry.commands,
-          incoming: evt.commands,
+          incoming: commandCatalogForRuntime(runtime, evt.commands),
           onChanged: (commands) => { entry.commands = commands; announce(); persist() },
         })
         : false
@@ -3698,6 +3706,41 @@ channel
       pushLog(s, evt)
       bcast('code-event', { term: payload.term, evt })
     }
+    if (/^\/help\s*$/.test(text) && s.runtime !== 'hermes') {
+      ctlLine(`Available commands \u00b7 ${commandHelpLine(s.commands)}`)
+      return
+    }
+    if (/^\/status\s*$/.test(text) && s.runtime !== 'hermes') {
+      const label = structuredRuntimeMetadata(s.runtime)?.label || s.runtime
+      const state = s.session?.turnActive ? 'working' : 'idle'
+      ctlLine(`${label} \u00b7 ${state} \u00b7 model ${s.model || 'default'} \u00b7 ${s.mode || 'default'} permissions \u00b7 effort ${s.effort || 'default'}`)
+      return
+    }
+    if (/^\/context\s*$/.test(text) && s.runtime !== 'hermes') {
+      const ctx = s.lastUsage?.ctx
+      ctlLine(ctx?.max
+        ? `Context \u00b7 ${Number(ctx.used || 0).toLocaleString('en-US')} / ${Number(ctx.max).toLocaleString('en-US')} tokens (${ctx.pct ?? Math.round((Number(ctx.used || 0) / Number(ctx.max)) * 100)}%)`
+        : 'Context usage unavailable until the runtime reports a completed turn')
+      return
+    }
+    if (/^\/diff\s*$/.test(text)) {
+      try {
+        const cwd = s.cwd || process.cwd()
+        const summary = execFileSync('git', ['-C', cwd, 'status', '--short'], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+        ctlLine(summary ? `Working tree changes\n${summary.slice(0, 1600)}` : 'Working tree clean')
+      } catch { ctlLine('Working-tree diff unavailable outside a readable Git checkout') }
+      return
+    }
+    if (/^\/credits\s*$/.test(text) && s.runtime !== 'hermes') {
+      if (s.runtime !== 'codex' || typeof s.session?.accountUsage !== 'function') {
+        ctlLine('Credit balance is unavailable for this runtime; use /usage for provider limits')
+        return
+      }
+      Promise.resolve(s.session.accountUsage()).then((report) => {
+        ctlLine(codexCreditsReportLine(report?.limits))
+      }).catch(() => ctlLine('Codex credits unavailable for this account'))
+      return
+    }
     const mm = text.match(/^\/model\b\s*(\S+)?/)
     if (mm) {
       if (mm[1]) {
@@ -3752,7 +3795,7 @@ channel
     // /compact → show the ephemeral "Compacting…" indicator (the compact-start event),
     // track so onEvent clears it + attributes the recap card when the SDK turn finishes.
     // No persisted ctl line — the live indicator + the CompactionCard are the record.
-    if (/^\/compact\b/.test(text)) {
+    if (/^\/compact\s*$/.test(text)) {
       if (s.runtime === 'codex') {
         if (s.session.turnActive) {
           ctlLine('finish or stop the current Codex turn before compacting context')
@@ -3763,6 +3806,15 @@ channel
           ctlLine('nothing to compact — context unchanged')
           return
         }
+        const nativeCompacted = await s.session.compactContext?.()
+        if (nativeCompacted) {
+          const ce = { kind: 'compaction', trigger: 'manual', preTokens: s.lastUsage?.ctx?.used || null, by: payload.by, native: true }
+          pushLog(s, ce)
+          bcast('code-event', { term: payload.term, evt: ce })
+          s.lastUsage = null
+          s.flush?.()
+          return
+        }
         if (s.session.clearContext?.() === false) {
           ctlLine('Codex context compaction unavailable right now')
           return
@@ -3802,7 +3854,17 @@ channel
       ctlLine(s.runtime === 'codex'
         ? codexUsageReportLine(s.model, s.session?.usageSnapshot)
         : usageReportLine(s.model, s.log))
-      if (s.runtime !== 'codex') planMeterLine().then((l) => { if (l) ctlLine(l) }).catch(() => { /* meters are never load-bearing */ })
+      if (s.runtime === 'codex') {
+        Promise.resolve(s.session?.accountUsage?.()).then((report) => {
+          const usage = codexAccountUsageLine(report?.usage)
+          if (usage) ctlLine(usage)
+          ctlLine(codexLimitReportLine(report?.limits))
+        }).catch(() => ctlLine('Codex provider limits unavailable'))
+      } else planMeterLine().then((l) => { if (l) ctlLine(l) }).catch(() => { /* meters are never load-bearing */ })
+      return
+    }
+    if (s.runtime === 'codex' && /^\/review(?:\s|$)/.test(text) && (s.flowSessionId || s.flowRole || s.sliceType === 'review')) {
+      ctlLine('Native /review is unavailable in Flow and reviewer lanes; their immutable review contract already owns scope and authority')
       return
     }
     // Context-carry (2026-07-08) point 4: a real human turn arrived BEFORE the post-switch/
@@ -3880,6 +3942,13 @@ channel
   .on('broadcast', { event: 'code-mode' }, ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)
     if (s && STRUCTURED_MODES.has(payload.mode)) {
+      if (structuredModeLocked(s) && payload.mode !== s.mode) {
+        const evt = { kind: 'control', text: `This ${s.flowRole || 'review'} lane is structurally locked to ${s.mode}; Flow and reviewer restrictions take precedence.` }
+        pushLog(s, evt)
+        bcast('code-event', { term: payload.term, evt })
+        announce()
+        return
+      }
       if (s.runtime === 'codex' || s.runtime === 'hermes') {
         if (!s.session.setMode(payload.mode)) {
           const evt = { kind: 'control', text: `finish or stop the current ${structuredRuntimeMetadata(s.runtime)?.label || 'agent'} turn before switching permissions` }
@@ -4322,7 +4391,7 @@ flowChannel
         // Model tiers (2026-07-03-flow-lane-model-tiers): pick the lane's brain by slice_type
         // (scaffold→sonnet, feature/fix/review→opus; env can blanket-override or `inherit` to
         // restore today's exact behavior). undefined → no model key passed (openStructured default).
-        openStructured({ id: laneId, runtime: flowRuntime, cwd: dir, model: flowLaneModelFor({ sliceType: t.slice_type, runtime: flowRuntime, catalog: flowCatalog }), mode: flowRuntime === 'codex' && isReview ? 'review' : 'bypassPermissions', rolePrompt: laneRolePrompt, flowSessionId: payload.flowId, flowTaskKey: t.task_key, flowRole: isReview ? 'reviewer' : 'builder', flowReviewTargets: isReview ? (t.deps || []) : [], flowReviewSnapshots, dispatchBaseSha, revertTarget: redispatch?.revertTarget || null, spawnedBy: `flow:${payload.flowId}`, resume: redispatch?.resumeSessionId || undefined, reviewSliceRoots })
+        openStructured({ id: laneId, runtime: flowRuntime, cwd: dir, model: flowLaneModelFor({ sliceType: t.slice_type, runtime: flowRuntime, catalog: flowCatalog }), mode: structuredModeForSlice(flowRuntime, { mode: 'bypassPermissions', flowRole: isReview ? 'reviewer' : 'builder' }), rolePrompt: laneRolePrompt, flowSessionId: payload.flowId, flowTaskKey: t.task_key, flowRole: isReview ? 'reviewer' : 'builder', flowReviewTargets: isReview ? (t.deps || []) : [], flowReviewSnapshots, dispatchBaseSha, revertTarget: redispatch?.revertTarget || null, spawnedBy: `flow:${payload.flowId}`, resume: redispatch?.resumeSessionId || undefined, reviewSliceRoots })
         const le = sessions.get(laneId)
         if (le) {
           // S4 — stamp the surviving revert target on the resumed lane so a later reviewer still

package/claude-command-catalog.mjs

@@ -0,0 +1,91 @@
+// Claude Code's SDK init payload is an *advertisement*, not a headless command
+// contract.  In particular, 2.1.206 advertises TUI/profile commands (`/agents`,
+// `/config`, `/doctor`, …) which are not safe or meaningful in a shared room.
+// Keep the room catalog deliberately small and evidence-based:
+//
+//   1. bridge-owned controls work through the existing room controls;
+//   2. `/compact` is the one native lifecycle command proven on the streaming
+//      Agent SDK path; and
+//   3. a discovered slash name is exposed only when the same init event calls it
+//      an installed Skill.  Skills are structured prompt invocations, unlike
+//      Claude Code's interactive/profile command palette.
+//
+// This is also an explicit command matrix for the 2.1.206 probe.  Everything
+// outside the allow path is intentionally omitted; `CLAUDE_COMMAND_EXCLUSIONS`
+// records the high-risk/interactive families so a later SDK change cannot turn
+// discovery into accidental exposure.
+
+const cleanName = (value) => {
+  const name = String(typeof value === 'object' ? value?.name : value || '')
+    .trim()
+    .replace(/^\/+/, '')
+  return /^[A-Za-z0-9][A-Za-z0-9:_-]*$/.test(name) ? name : ''
+}
+
+const stringMeta = (value) => {
+  if (!value || typeof value !== 'object') return {}
+  const description = String(value.description || '').trim()
+  const inputHint = String(value.inputHint || value.input_hint || value.input?.hint || '').trim()
+  return {
+    ...(description ? { description } : {}),
+    ...(inputHint ? { inputHint } : {}),
+  }
+}
+
+export const CLAUDE_COMMAND_MATRIX = Object.freeze({
+  '/clear': Object.freeze({ description: 'clear context · confirms', owner: 'bridge-control' }),
+  '/compact': Object.freeze({ description: 'compact context', owner: 'sdk-lifecycle' }),
+  '/model': Object.freeze({ description: 'pick model — opens selector', owner: 'bridge-control' }),
+  '/usage': Object.freeze({ description: 'session usage and provider limits', owner: 'bridge-control' }),
+  '<installed-skill>': Object.freeze({ description: 'run an installed Claude skill', owner: 'sdk-skill' }),
+})
+
+// Exclusions are grouped by why the room cannot safely implement them.  This
+// is intentionally a deny-list *and* a default-deny catalog: unknown future
+// slash names stay hidden until they have an explicit structured contract.
+export const CLAUDE_COMMAND_EXCLUSIONS = Object.freeze({
+  profileOrIdentity: Object.freeze(['agents', 'color', 'config', 'rename', 'team-onboarding']),
+  credentialsOrUpdates: Object.freeze(['claude-api', 'mcp', 'update-config']),
+  diagnosticsOrUpload: Object.freeze(['debug', 'doctor', 'heapdump', 'insights']),
+  hiddenAgentOrAutomation: Object.freeze(['__remote-workflow', 'batch', 'code-review', 'loop', 'review', 'schedule', 'security-review']),
+  unsafeInteractive: Object.freeze(['design', 'design-consent', 'design-revoke', 'fast', 'fewer-permission-prompts', 'goal', 'init', 'recap', 'reload-skills', 'run']),
+})
+
+const EXCLUDED = new Set(Object.values(CLAUDE_COMMAND_EXCLUSIONS).flat())
+const BRIDGE_CONTROLS = new Set(['clear', 'compact', 'model', 'usage'])
+
+// Convert Claude's string-only 2.1.206 payload (and a future object-shaped
+// payload) into the metadata contract shared by all structured runtimes.  An
+// argument-bearing future skill retains its description and input hint; no
+// argument command is silently advertised as a one-tap action.
+export function normalizeClaudeCommandCatalog({ slashCommands, skills } = {}) {
+  const advertised = Array.isArray(slashCommands) ? slashCommands : []
+  const installedSkills = new Set((Array.isArray(skills) ? skills : []).map(cleanName).filter(Boolean))
+  const byName = new Map()
+
+  for (const command of advertised) {
+    const name = cleanName(command)
+    if (!name || EXCLUDED.has(name)) continue
+    const allowed = BRIDGE_CONTROLS.has(name) || installedSkills.has(name)
+    if (!allowed || byName.has(name)) continue
+    const canonical = CLAUDE_COMMAND_MATRIX[`/${name}`]
+    const supplied = stringMeta(command)
+    byName.set(name, {
+      name: `/${name}`,
+      description: supplied.description || canonical?.description || `Run installed Claude skill: /${name}`,
+      ...(supplied.inputHint ? { inputHint: supplied.inputHint } : {}),
+    })
+  }
+
+  // Room controls remain available on older SDK init shapes that omit the raw
+  // slash list.  They are ordered first because they have bridge support.
+  const controls = ['clear', 'compact', 'model', 'usage'].map((name) => byName.get(name) || ({
+    name: `/${name}`,
+    description: CLAUDE_COMMAND_MATRIX[`/${name}`].description,
+  }))
+  const skillsOnly = [...byName.entries()]
+    .filter(([name]) => !BRIDGE_CONTROLS.has(name))
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([, command]) => command)
+  return [...controls, ...skillsOnly]
+}

package/claude-session.mjs

@@ -21,6 +21,7 @@ import { sanitizeSession } from './transcript-sanitize.mjs'
 import { reviewGatePreToolDecision } from './flow-review-gate.mjs'
 import { crossPostNeedsCard } from './cross-terminal.mjs'
 import { correctContext } from './context-windows.mjs'
+import { normalizeClaudeCommandCatalog } from './claude-command-catalog.mjs'
 import { THINKPOOL_CASCADE_RULE, THINKPOOL_REMOTE_DELIVERY_RULES, THINKPOOL_RUNTIME_AUTHORITY_RULE, THINKPOOL_RUNTIME_TURN_REMINDER, buildThinkPoolTurnGuidance, createRoomContextSelector, usesFullThinkPoolReminder } from './thinkpool-room-prompt.mjs'
 import { stallDecision, stallEvent, isCompactTurn } from './turn-stall.mjs'
 
@@ -878,9 +879,10 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
               readyLogged = true
               process.stderr.write(`\n  ◆ session ready in ${Date.now() - spawnT0}ms — MCP ${process.env.TP_MCP_STRICT === '1' ? 'OFF' : 'on'}${resume ? ', resume' : ', fresh'}.\n`)
             }
-            // m.slash_commands (init message) — the commands this session really
-            // supports: built-ins + the host's custom .claude/commands. Surfaced
-            // so the room composer's autocomplete lists what ACTUALLY exists.
+            // The init advertises both real Skills and Claude Code's TUI/profile
+            // palette.  Normalise it to the structured room contract: supported
+            // bridge controls plus installed Skills, never unsafe interactive or
+            // profile-global commands (see claude-command-catalog.mjs).
             // Prefer the INTENDED model (opts.model — set at open and on every /model switch)
             // over the message's own `m.model`. A RESUMED session REPLAYS the transcript's old
             // init messages, all carrying the PRE-switch model, and each one used to reset the
@@ -888,7 +890,7 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
             // "init model=claude-opus-4-8" dragged the chip back to Opus with no result yet to
             // correct it). opts.model reflects what the session will actually run, so trust it.
             curModel = opts.model || m.model || model || curModel
-            emit({ kind: 'system', sessionId, model: opts.model || m.model || model || null, commands: Array.isArray(m.slash_commands) ? m.slash_commands : undefined })
+            emit({ kind: 'system', sessionId, model: opts.model || m.model || model || null, commands: normalizeClaudeCommandCatalog({ slashCommands: m.slash_commands, skills: m.skills }) })
             // AskUserQuestion regression guard — the init message carries the session's
             // real tool list. If a caret SDK bump silently dropped AskUserQuestion from
             // it (the 2026-07-08 outage), surface it loudly instead of a dead card. One-

package/codex-app-server.mjs

@@ -257,6 +257,26 @@ export class CodexAppServerClient {
     return this.request('turn/interrupt', { threadId, turnId }, this.controlTimeoutMs)
   }
 
+  compact({ threadId } = {}) {
+    return this.request('thread/compact/start', { threadId }, this.controlTimeoutMs)
+  }
+
+  accountUsage() {
+    return this.request('account/usage/read', null, this.controlTimeoutMs)
+  }
+
+  accountRateLimits() {
+    return this.request('account/rateLimits/read', null, this.controlTimeoutMs)
+  }
+
+  startReview({ threadId, target } = {}) {
+    return this.request('review/start', {
+      threadId,
+      target: target || { type: 'uncommittedChanges' },
+      delivery: 'inline',
+    }, this.turnStartTimeoutMs)
+  }
+
   end() {
     const child = this.child
     this._close(new Error('codex app-server ended'))

package/codex-commands.mjs

@@ -0,0 +1,83 @@
+// Codex Code-room command policy.
+//
+// This is intentionally NOT a transcription of the interactive `codex` TUI
+// palette. Codex CLI 0.144.1's App Server schema has no slash-command catalog
+// endpoint. Keep only a command which the room can actually execute, and keep
+// bridge-wide controls in bridge.mjs where their shared state semantics live.
+
+/**
+ * Commands surfaced from the Codex runtime's system catalog.
+ *
+ * /compact is bridge-executed today: bridge.mjs clears the native Codex context
+ * and carries a bounded room recap into the next fresh thread. App Server also
+ * exposes thread/compact/start in 0.144.1, but the bridge path is the supported
+ * cross-transport implementation, including exec fallback and the room's
+ * durable recap semantics.
+ */
+export const CODEX_COMMAND_CATALOG = Object.freeze([])
+
+/**
+ * Evidence-backed command matrix for the installed Codex CLI (0.144.1).
+ * `surface` means what ThinkPool intentionally advertises; it is not a claim
+ * that an interactive terminal palette command works through App Server.
+ */
+export const CODEX_COMMAND_MATRIX = Object.freeze([
+  Object.freeze({ name: '/compact', surface: true, runtime: 'native', api: 'thread/compact/start', reason: 'Native App Server compaction; bounded-recap reset remains the exec fallback.' }),
+  Object.freeze({ name: '/model', surface: true, runtime: 'bridge', api: 'model/list', reason: 'Shared picker owns the model argument.' }),
+  Object.freeze({ name: '/clear', surface: true, runtime: 'bridge', api: null, reason: 'Shared reset clears visible lane history and starts a fresh native thread.' }),
+  Object.freeze({ name: '/usage', surface: true, runtime: 'bridge+native', api: 'account/usage/read + account/rateLimits/read', reason: 'Reports lane usage plus redacted provider totals and limits.' }),
+  Object.freeze({ name: '/credits', surface: true, runtime: 'native', api: 'account/rateLimits/read', reason: 'Reports balance/availability only; never account identity.' }),
+  Object.freeze({ name: '/review', surface: true, runtime: 'native', api: 'review/start', reason: 'Ordinary lanes only; Flow and reviewer structural restrictions win.' }),
+])
+
+/**
+ * Explicit exclusions: present in an interactive CLI or App Server protocol,
+ * but not safe/meaningful Code-room commands. Never add these by inference.
+ */
+export const CODEX_COMMAND_EXCLUSIONS = Object.freeze([
+  'profile-global configuration, skills, plugins, marketplaces, and experimental features',
+  'updates, diagnostics/feedback upload, and external-agent import',
+  'credentials, login/logout, identity, and account mutation',
+  'thread archive/delete/fork/name/goal/rollback and hidden-agent controls',
+  'MCP OAuth, filesystem, shell, and interactive command-exec protocol methods',
+  'detached review and review from Flow/reviewer lanes, because visible structural restrictions win',
+])
+
+export function isCodexCompactCommand(text) {
+  return /^\s*\/compact\s*$/i.test(String(text || ''))
+}
+
+export function codexReviewTarget(text) {
+  const body = String(text || '').replace(/^\s*\/review\b/i, '').trim()
+  if (!body) return { type: 'uncommittedChanges' }
+  const base = body.match(/^base\s*:\s*(\S+)$/i)
+  if (base) return { type: 'baseBranch', branch: base[1] }
+  const commit = body.match(/^commit\s*:\s*([a-f0-9]{7,64})$/i)
+  if (commit) return { type: 'commit', sha: commit[1] }
+  return { type: 'custom', instructions: body }
+}
+
+const pct = (value) => Number.isFinite(Number(value)) ? `${Math.round(Number(value))}%` : null
+const reset = (value) => Number.isFinite(Number(value)) ? new Date(Number(value) * 1000).toISOString().replace('T', ' ').slice(0, 16) + 'Z' : null
+
+export function codexLimitReportLine(snapshot) {
+  const limits = snapshot?.rateLimits || null
+  if (!limits) return 'Codex provider limits unavailable'
+  const parts = []
+  if (limits.primary?.usedPercent != null) parts.push(`primary ${pct(limits.primary.usedPercent)}${reset(limits.primary.resetsAt) ? ` · resets ${reset(limits.primary.resetsAt)}` : ''}`)
+  if (limits.secondary?.usedPercent != null) parts.push(`secondary ${pct(limits.secondary.usedPercent)}${reset(limits.secondary.resetsAt) ? ` · resets ${reset(limits.secondary.resetsAt)}` : ''}`)
+  return parts.length ? `Codex limits · ${parts.join(' · ')}` : 'Codex provider limits unavailable'
+}
+
+export function codexCreditsReportLine(snapshot) {
+  const credits = snapshot?.rateLimits?.credits
+  if (!credits) return 'Codex credits unavailable for this account'
+  if (credits.unlimited) return 'Codex credits · unlimited'
+  if (credits.balance != null) return `Codex credits · balance ${String(credits.balance)}`
+  return `Codex credits · ${credits.hasCredits ? 'available' : 'none available'}`
+}
+
+export function codexAccountUsageLine(snapshot) {
+  const total = snapshot?.summary?.lifetimeTokens
+  return Number.isFinite(Number(total)) ? `Codex account usage · ${Number(total).toLocaleString('en-US')} lifetime tokens` : null
+}

package/codex-event-mapper.mjs

@@ -29,6 +29,7 @@
 // apply unchanged. The stable exec path is observe-only; the opt-in App Server
 // path routes command/file approval requests through the shared room cards.
 import fs from 'node:fs'
+import { CODEX_COMMAND_CATALOG } from './codex-commands.mjs'
 
 const safeMcpPart = (value) => String(value || 'unknown').replace(/[^a-zA-Z0-9_-]/g, '_')
 const mcpToolName = (item) => `mcp__${safeMcpPart(item?.server)}__${safeMcpPart(item?.tool)}`
@@ -80,7 +81,10 @@ export class CodexEventMapper {
         this._sessionId = ev.thread_id || this._sessionId || null
         if (!this._systemSent) {
           this._systemSent = true
-          this._emit({ kind: 'system', sessionId: this._sessionId, model: this._model, commands: [] })
+          // Codex App Server 0.144.1 has no slash-command discovery endpoint.
+          // Advertise only the explicit room-supported catalog, never guessed
+          // interactive-TUI commands.
+          this._emit({ kind: 'system', sessionId: this._sessionId, model: this._model, commands: CODEX_COMMAND_CATALOG })
         }
         return
       }

package/codex-session.mjs

@@ -32,6 +32,7 @@ import { CodexEventMapper } from './codex-event-mapper.mjs'
 import { startCodexMcpHttp } from './codex-mcp-http.mjs'
 import { CODEX_THINKPOOL_FIRST_TURN_PREAMBLE, buildThinkPoolTurnGuidance, createRoomContextSelector, usesFullThinkPoolReminder } from './thinkpool-room-prompt.mjs'
 import { questionAnswerResponse } from './question-response.mjs'
+import { codexReviewTarget, isCodexCompactCommand } from './codex-commands.mjs'
 
 const DEFAULT_SANDBOX = 'workspace-write'
 const SAFE_SANDBOXES = new Set(['read-only', 'workspace-write', 'danger-full-access'])
@@ -40,7 +41,10 @@ export const CODEX_MODE_CONFIG = {
   default:           { sandbox: 'workspace-write', approvalPolicy: 'untrusted' },
   acceptEdits:       { sandbox: 'workspace-write', approvalPolicy: 'on-request' },
   plan:              { sandbox: 'read-only',       approvalPolicy: 'never' },
-  review:            { sandbox: 'workspace-write', approvalPolicy: 'never' },
+  // Reviewer authority is structural, not a prompt convention. It may inspect
+  // the pinned snapshot and call the bridge-owned verdict/check tools, but it
+  // cannot mutate even its own worktree as an escape hatch.
+  review:            { sandbox: 'read-only',       approvalPolicy: 'never' },
   bypassPermissions: { sandbox: 'danger-full-access', approvalPolicy: 'never' },
 }
 
@@ -586,6 +590,43 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
     return true
   }
 
+  async function runAppServerReview(commandText) {
+    if (!await ensureAppServer()) return false
+    mapper.setUsageBaseline(sessionId ? readCodexThreadUsage(sessionId) : null)
+    aborted = false
+    turnActive = true
+    try {
+      const started = await appServer.startReview({ threadId: sessionId, target: codexReviewTarget(commandText) })
+      activeTurnId = started?.turn?.id || started?.turnId
+      if (!activeTurnId) throw new Error('Codex review/start returned no turn id')
+      const completed = await appServer.waitForTurn(activeTurnId)
+      const status = completed?.turn?.status
+      if (aborted || status === 'interrupted') {
+        emitTurnBoundary({ kind: 'result', subtype: 'aborted', sessionId, model: activeModel, costUsd: null, usage: null, numTurns: 1, durationMs: completed?.turn?.durationMs, denials: 0, resultText: null })
+      } else if (status === 'failed') {
+        pushMappedEvent({ type: 'turn.failed', message: completed?.turn?.error?.message || 'codex review failed' })
+      } else {
+        pushMappedEvent({ type: 'turn.completed' })
+      }
+    } catch (error) {
+      appServerDisabled = true
+      appServerThreadReady = false
+      try { appServer?.end() } catch { /* noop */ }
+      appServer = null
+      if (!ended) pushMappedEvent({ type: 'turn.failed', message: `codex review failed: ${error?.message || error}` })
+    } finally {
+      for (const state of streamedAgentItems.values()) {
+        if (!state.text) continue
+        try { onEvent?.({ kind: 'assistant', blocks: [{ type: 'text', text: state.text }], parentToolUseId: null, replacesCid: state.cid }) } catch { /* noop */ }
+      }
+      activeTurnId = null
+      turnActive = false
+      appServerItems.clear()
+      streamedAgentItems.clear()
+    }
+    return true
+  }
+
   async function runExec(prompt, options = {}) {
     // First turn: fresh exec. Later turns: resume THIS lane's captured thread.
     // `--last` is process-global and can cross-wire two concurrently-active Codex
@@ -681,8 +722,15 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
         promptIndex: next.promptIndex,
         forceFullReminder: next.forceFullReminder,
       })
-      const usedAppServer = await runAppServer(prompt, next.options)
-      if (!usedAppServer) await runExec(prompt, next.options)
+      const review = /^\s*\/review(?:\s|$)/i.test(String(next.text || ''))
+      const usedAppServer = review
+        ? await runAppServerReview(next.text)
+        : await runAppServer(prompt, next.options)
+      if (!usedAppServer) {
+        if (review) {
+          emitTurnBoundary({ kind: 'error', message: 'Codex review is unavailable without the tested App Server runtime.', recoverable: true })
+        } else await runExec(prompt, next.options)
+      }
       turnNo++
       pump()
     })
@@ -698,7 +746,7 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
       if (ended) return false
       const promptIndex = userPromptNo++
       const thisTurnForceFull = forceFullReminder
-      forceFullReminder = /^\s*\/(?:compact|reset|clear)\b/i.test(String(text || ''))
+      forceFullReminder = isCodexCompactCommand(text) || /^\s*\/(?:reset|clear)\b/i.test(String(text || ''))
       if (!turnActive && turnNo === 0 && prepareCwd) {
         try { cwd = prepareCwd() || cwd } catch { /* keep original cwd */ }
       }
@@ -779,5 +827,23 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
       appServerThreadReady = false
       return true
     },
+    async compactContext() {
+      if (turnActive || !await ensureAppServer()) return false
+      try {
+        await appServer.compact({ threadId: sessionId })
+        return true
+      } catch (error) {
+        note(`Native Codex compaction unavailable; using bounded recap fallback: ${error?.message || error}`)
+        return false
+      }
+    },
+    async accountUsage() {
+      if (!await ensureAppServer()) return null
+      const [usage, limits] = await Promise.all([
+        appServer.accountUsage().catch(() => null),
+        appServer.accountRateLimits().catch(() => null),
+      ])
+      return { usage, limits }
+    },
   }
 }

package/command-catalog.mjs

@@ -1,5 +1,101 @@
+// Runtime-neutral Code-room command catalog. Native runtimes publish very
+// different surfaces: Claude mixes skills with TUI commands, Codex App Server
+// publishes no slash catalog, and Hermes publishes ACP metadata. Keep the safe
+// room controls here so all three runtimes share names, descriptions, hints,
+// and routing while runtime-owned commands remain evidence-gated.
+
+const command = (name, description, route, inputHint, runtimes = ['claude', 'codex', 'hermes']) => Object.freeze({
+  name,
+  description,
+  route,
+  ...(inputHint ? { inputHint } : {}),
+  runtimes: Object.freeze(runtimes),
+})
+
+export const CODE_ROOM_COMMANDS = Object.freeze([
+  command('/side', 'investigate beside this terminal', 'side', 'task'),
+  command('/flow', 'open an explicit visible Cascade', 'flow', 'task [--mode guide|steer|autopilot]'),
+  command('/help', 'list commands available in this lane', 'control'),
+  command('/status', 'runtime, model, permissions, and busy state', 'control'),
+  command('/usage', 'session usage and provider limits', 'control'),
+  command('/context', 'current context-window usage', 'control'),
+  command('/diff', 'working-tree change summary', 'control'),
+  command('/compact', 'compact context', 'runtime'),
+  command('/clear', 'clear context · confirms', 'clear'),
+  command('/model', 'pick model — opens selector', 'model'),
+  command('/mode', 'set permission mode', 'mode', 'normal | auto-accept | plan | bypass'),
+  command('/effort', 'set reasoning effort', 'effort', 'low | medium | high | xhigh | max'),
+  command('/queue', 'run a prompt after the active turn', 'queue', 'prompt'),
+  command('/steer', 'guide the active turn', 'steer', 'prompt', ['codex', 'hermes']),
+  command('/credits', 'provider credit balance', 'credits', null, ['codex', 'hermes']),
+  command('/reasoning', 'Hermes reasoning effort', 'runtime', 'low | medium | high | xhigh | max | none | reset', ['hermes']),
+  command('/review', 'review uncommitted changes', 'runtime', null, ['codex']),
+])
+
+const cleanRuntime = (runtime) => runtime === 'thinkpool' ? 'hermes' : runtime
+const cleanName = (value) => {
+  const raw = typeof value === 'string' ? value : value?.name
+  const name = `/${String(raw || '').trim().replace(/^\/+/, '')}`
+  return /^\/[A-Za-z0-9][A-Za-z0-9:_-]*$/.test(name) ? name : ''
+}
+
+const normalizeNative = (value) => {
+  const name = cleanName(value)
+  if (!name) return null
+  if (typeof value === 'string') return { name, description: 'runtime command', route: 'runtime' }
+  const description = String(value?.description || '').trim() || 'runtime command'
+  const inputHint = String(value?.inputHint || value?.input_hint || value?.input?.hint || '').trim()
+  const route = String(value?.route || '').trim() || 'runtime'
+  return { name, description, route, ...(inputHint ? { inputHint } : {}) }
+}
+
+// Merge native metadata into the shared catalog without allowing a runtime to
+// redefine the routing of a bridge-owned control. Unknown native commands are
+// retained only after the runtime-specific adapter has already allowlisted them.
+export function commandCatalogForRuntime(runtime, nativeCommands = []) {
+  const id = cleanRuntime(runtime)
+  const byName = new Map()
+  for (const item of CODE_ROOM_COMMANDS) {
+    if (!item.runtimes.includes(id)) continue
+    byName.set(item.name, {
+      name: item.name,
+      description: item.description,
+      route: item.route,
+      ...(item.inputHint ? { inputHint: item.inputHint } : {}),
+    })
+  }
+  for (const raw of (Array.isArray(nativeCommands) ? nativeCommands : [])) {
+    const item = normalizeNative(raw)
+    if (!item) continue
+    const shared = byName.get(item.name)
+    const hermesNativeControl = id === 'hermes' && ['/help', '/status', '/context', '/credits'].includes(item.name)
+    byName.set(item.name, shared
+      ? { ...item, ...shared, description: item.description === 'runtime command' ? shared.description : item.description, ...(item.inputHint ? { inputHint: item.inputHint } : {}), ...(hermesNativeControl ? { route: 'runtime' } : {}) }
+      : item)
+  }
+  return [...byName.values()]
+}
+
+export const commandNeedsInput = (item) => !!String(item?.inputHint || '').trim()
+export const commandRoute = (item) => String(item?.route || 'runtime')
+
+export function commandHelpLine(commands) {
+  return (Array.isArray(commands) ? commands : [])
+    .map((item) => `${item.name}${item.inputHint ? ` <${item.inputHint}>` : ''}`)
+    .join('  ')
+}
+
+export function normalizePermissionMode(value) {
+  const mode = String(value || '').trim().toLowerCase().replace(/[\s_-]+/g, '')
+  if (['normal', 'default', 'manual'].includes(mode)) return 'default'
+  if (['auto', 'autoaccept', 'autoacceptedits', 'acceptedits'].includes(mode)) return 'acceptEdits'
+  if (mode === 'plan') return 'plan'
+  if (['bypass', 'bypasspermissions', 'fullauto'].includes(mode)) return 'bypassPermissions'
+  return null
+}
+
 // Command catalogs are session chrome, but their ACP system event is also the
-// lifecycle-ready signal.  Keep those two concerns separate so a reconstructed
+// lifecycle-ready signal. Keep those concerns separate so a reconstructed
 // identical catalog cannot swallow warm/recap/auto-resume work.
 export function reconcileCommandCatalog({ current, incoming, onChanged, onLifecycle } = {}) {
   const hasIncoming = Array.isArray(incoming) && incoming.length > 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.268",
+  "version": "0.7.270",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "byok-detect.mjs",
     "context-windows.mjs",
     "claude-session.mjs",
+    "claude-command-catalog.mjs",
     "codex-session.mjs",
     "question-response.mjs",
     "thinkpool-room-prompt.mjs",
@@ -25,6 +26,7 @@
     "codex-mcp-http.mjs",
     "lane-worktree.mjs",
     "codex-event-mapper.mjs",
+    "codex-commands.mjs",
     "acp-client.mjs",
     "hermes-session.mjs",
     "hermes-policy.mjs",

package/runtime-registry.mjs

@@ -28,6 +28,19 @@ export const structuredRuntimeForCommand = (command) => {
 export const defaultStructuredMode = (runtime) => structuredRuntimeMetadata(runtime)?.defaultMode || 'default'
 export const structuredRuntimeSupportsMode = (runtime, mode) => structuredRuntimeMetadata(runtime)?.modes?.includes(mode) === true
 export const structuredRuntimeSupportsFlow = (runtime) => structuredRuntimeMetadata(runtime)?.flow === true
+export const structuredModeLocked = ({ flowRole, sliceType } = {}) => (
+  flowRole === 'conductor' || flowRole === 'reviewer' || sliceType === 'review'
+)
+export const structuredModeForSlice = (runtime, lane = {}) => {
+  if (lane.flowRole !== 'reviewer' && lane.sliceType !== 'review') return lane.mode
+  if (structuredRuntimeSupportsMode(runtime, 'review')) return 'review'
+  if (structuredRuntimeSupportsMode(runtime, 'plan')) return 'plan'
+  return lane.mode
+}
+export const structuredModesForLane = (runtime, lane = {}) => {
+  const modes = structuredRuntimeMetadata(runtime)?.modes || []
+  return structuredModeLocked(lane) && modes.includes(lane.mode) ? [lane.mode] : modes
+}
 const STRUCTURED_EFFORTS = new Set(['low', 'medium', 'high', 'xhigh', 'max'])
 export const normalizeStructuredEffort = (runtime, effort) => {
   if (effort === null) return null

package/thinkpool-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": 1,
+  "bundleVersion": 2,
   "contracts": [
     {
       "id": "room-coordination",
@@ -37,16 +37,16 @@
     },
     {
       "id": "work-routing",
-      "version": 1,
+      "version": 2,
       "routes": [
         {
           "id": "work-routing",
           "tools": ["spawn_terminal", "open_main_terminal", "close_terminal"],
           "trigger": "\\b(parallel|delegate|worker|sub[- ]?terminal|conductor|cascade|spawn_terminal|open_main_terminal|close_terminal)\\b",
-          "prompt": "For genuinely decomposable work in a conductor-capable role, open visible worker slices with spawn_terminal, collect and verify them, then close_terminal. An explicitly requested separate Cascade/conductor uses open_main_terminal, never spawn_terminal."
+          "prompt": "For genuinely decomposable work in a conductor-capable role, open visible worker slices with spawn_terminal, collect and verify them, then close_terminal. An explicitly requested separate Cascade/conductor uses open_main_terminal, never spawn_terminal. Review slices are structurally read-only and must use the review slice type; they never inherit autonomous bypass authority."
         }
       ],
-      "expandedPrompt": "CASCADE WORKFLOW (default for non-trivial work that genuinely decomposes; mandatory when the people ask for Cascade, tiered lanes, one-shot flow, or unattended multi-slice execution): first investigate enough to name evidence-backed slices and their dependencies, then post a short plan in the room. The current top-level/conductor terminal keeps decomposition, integration, and final judgment; use spawn_terminal only for bounded worker slices, while an explicitly requested separate conductor uses open_main_terminal. Parallelize only disjoint slices and encode dependencies instead of holding them in your head. Choose sliceType=scaffold for mechanical/search work, feature or fix for implementation, and review with a balanced capable tier for adversarial verification. Every worker brief names the evidence/diagnosis, exact scope, observable acceptance proof, relevant repo gates, whether merge/publish is required, and a safe-skip escape hatch. After dispatch, remain responsible: use read_terminal to collect each owned lane, verify its claim, close_terminal immediately, and dispatch newly unblocked work; never declare the Cascade done or yield a final result while owned workers remain uncollected. Check origin/main CI before merge-bearing waves, coordinate shared fixtures/publishers, and treat sibling pushes as context rather than proof. Run an adversarial review after builders (or pipeline review behind completed phases), finish with production-condition evidence, verify every reported SHA/version, and close every worker you opened.",
+      "expandedPrompt": "CASCADE WORKFLOW (default for non-trivial work that genuinely decomposes; mandatory when the people ask for Cascade, tiered lanes, one-shot flow, or unattended multi-slice execution): first investigate enough to name evidence-backed slices and their dependencies, then post a short plan in the room. The current top-level/conductor terminal keeps decomposition, integration, and final judgment; use spawn_terminal only for bounded worker slices, while an explicitly requested separate conductor uses open_main_terminal. Parallelize only disjoint slices and encode dependencies instead of holding them in your head. Choose sliceType=scaffold for mechanical/search work, feature or fix for implementation, and review with a balanced capable tier for adversarial verification. Review slices are structurally read-only: they resolve to a native review/Plan mode before launch and can never inherit autonomous bypass authority. Every worker brief names the evidence/diagnosis, exact scope, observable acceptance proof, relevant repo gates, whether merge/publish is required, and a safe-skip escape hatch. After dispatch, remain responsible: use read_terminal to collect each owned lane, verify its claim, close_terminal immediately, and dispatch newly unblocked work; never declare the Cascade done or yield a final result while owned workers remain uncollected. Check origin/main CI before merge-bearing waves, coordinate shared fixtures/publishers, and treat sibling pushes as context rather than proof. Run an adversarial review after builders (or pipeline review behind completed phases), finish with production-condition evidence, verify every reported SHA/version, and close every worker you opened.",
       "impact": [
         {"path": "bridge/bridge.mjs", "diffPattern": "spawn_terminal|open_main_terminal|close_terminal|cascadeRole|spawnDepth"},
         {"path": "bridge/lane-lifecycle.mjs"},

package/viewport.mjs

@@ -313,6 +313,12 @@ export class ViewportManager {
     this.root = null
   }
 
+  setWorkspaceRoot(workspaceRoot) {
+    if (!workspaceRoot) throw new Error('A lane workspace is required.')
+    this.workspaceRoot = path.resolve(workspaceRoot)
+    return this.workspaceRoot
+  }
+
   async start({ root = 'dist' } = {}) {
     const resolved = await resolveContainedRoot(this.workspaceRoot, root)
     await this.stop()