thinkpool-pair 0.7.256 → 0.7.258

package/bridge.mjs

@@ -119,6 +119,7 @@ import { classifyCodeEvent, unknownCodeEventNotice } from './code-event-contract
 import { fetchPairControlDeliveryAuthority } from './pair-control-authority.mjs'
 import { SIDE_HANDOFF_PROMPT, SIDE_ROLE_PROMPT, appendSideContext, assistantTextSince, sideContextBlock, sideSnapshot } from './side-lane.mjs'
 import { planMeterLine } from './plan-meters.mjs'
+import { priceForModel } from './model-prices.mjs'
 import { makeThrottledTrack } from './presence.mjs'
 import { resolveAnonKey, DEFAULT_SUPABASE_URL } from './supabase-key.mjs'
 import { buildTerminalRolePrompt, HERMES_VISIBLE_WORKER_FALLBACK_RULE } from './thinkpool-room-prompt.mjs'
@@ -869,15 +870,24 @@ function recordRoomSpend (tokens) {
 // TP_BUDGET_OFF (that only governs the cap ledger; usage accounting should still
 // run). input = full input incl. cache; cached = cache-read slice; both mapped to
 // pricing.js's rowCostEur formula. No model → skip (can't price/label it).
-function recordCodeUsage (model, usage) {
+function recordCodeUsage (model, usage, provider) {
   if (!codeAuthToken || !room || !model) return
   const u = usage || {}
   const input  = (u.input_tokens || 0) + (u.cache_creation_input_tokens || 0) + (u.cache_read_input_tokens || 0)
   const output = u.output_tokens || 0
   const cached = u.cache_read_input_tokens || 0
   if (!input && !output) return
-  budgetRpc('record_code_usage', { p_room: room, p_model: model, p_input: input, p_output: output, p_cached: cached })
-    .catch(() => { /* best-effort — usage accounting is not load-bearing for the turn */ })
+  // Persist the public rate resolved for this exact runtime model. A private
+  // model can lack a public rate; its token row is still written and Settings
+  // marks only the estimate as pending rather than making one up.
+  priceForModel(model).then((rate) => budgetRpc('record_code_usage', {
+    p_room: room, p_model: model, p_input: input, p_output: output, p_cached: cached,
+    p_provider: provider || 'unknown',
+    p_input_usd_per_mtok: rate?.input ?? null,
+    p_output_usd_per_mtok: rate?.output ?? null,
+    p_cached_input_usd_per_mtok: rate?.cached ?? null,
+    p_rate_source: rate?.source ?? null,
+  })).catch(() => { /* usage accounting is never load-bearing for a turn */ })
 }
 // Throttled presence track() (presence.mjs) — a reconnect storm re-fires SUBSCRIBED and
 // the handler re-track()s; without throttle that spirals into the per-client presence
@@ -2862,7 +2872,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       // Fold EVERY completed turn's output tokens into the room's durable monthly ledger
       // (lanes + normal turns) — powers the Session-info "Session tokens" stat. (The cap that
       // consumed this ledger was removed; the accounting stays.)
-      if (evt.kind === 'result' && evt.usage) { recordRoomSpend(evt.usage.output_tokens || 0); recordCodeUsage(evt.model, evt.usage) }
+      if (evt.kind === 'result' && evt.usage) { recordRoomSpend(evt.usage.output_tokens || 0); recordCodeUsage(evt.model, evt.usage, entry.provider) }
       // FL-B1 (lane) — a flow lane that ENDS ITS TURN is done: a bypass lane runs its slice
       // to completion in one turn, then narrates "done" and stops. Models often skip the
       // explicit signal (FLOW_DONE / mark_flow_done), which left the slice stuck 'dispatched'

package/claude-session.mjs

@@ -21,7 +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 { THINKPOOL_DESIGN_DELIVERY_RULE, THINKPOOL_REMOTE_DELIVERY_RULES } from './thinkpool-room-prompt.mjs'
+import { THINKPOOL_REMOTE_DELIVERY_RULES, THINKPOOL_RUNTIME_TURN_REMINDER } from './thinkpool-room-prompt.mjs'
 import { stallDecision, stallEvent, isCompactTurn } from './turn-stall.mjs'
 
 // The caret-pulled SDK's real version (^0.3.x auto-upgrades on restart). Resolved
@@ -191,20 +191,17 @@ const MODES = new Set(['default', 'acceptEdits', 'plan', 'bypassPermissions'])
 // or narrates instead of showing, forgetting it's driven from a phone. So we re-state
 // the highest-drift rules as a compact <system-reminder> appended to EVERY user turn,
 // adjacent to where the model's attention actually is — the same trick the host
-// harness uses to keep CLAUDE.md alive. ~250 tokens/turn; changes nothing but salience.
+// harness uses to keep CLAUDE.md alive. The shared capability router deliberately
+// costs ~900 tokens/turn so a fresh user never needs to know the room's tool names.
 // A live "ROOM NOW" tail (sibling lanes + active worktrees) is appended per turn by
 // the bridge's roomContext callback — see roomReminder() inside startClaudeSession.
 const TP_ROOM_REMINDER = [
   'You are Claude in a ThinkPool Code room, driven live from a phone or browser — NOT a local terminal. Keep using the room\'s features.',
-  'ARTIFACTS: never hand the room a local path, a file:// URL, a localhost address, an `open …`/Preview reference, or "it\'s in ~/claude-shots/" — the room cannot see the host. Surface every image by reading the PNG into your turn so it renders inline.',
-  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.',
+  THINKPOOL_RUNTIME_TURN_REMINDER,
   '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 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, terminalRolePrompt, rolePrompt, blockSubagents = false, onSubmitPlan = null, onLaneDone = null, onReviewVerdict = null, reviewGate = null, lazy = false, roomContext = null, suggest = true, prepareCwd = null }) {

package/codex-session.mjs

@@ -30,7 +30,7 @@ import readline from 'node:readline'
 import { buildCodexAppServerArgs, codexAppServerGate, createCodexAppServer } from './codex-app-server.mjs'
 import { CodexEventMapper } from './codex-event-mapper.mjs'
 import { startCodexMcpHttp } from './codex-mcp-http.mjs'
-import { CODEX_THINKPOOL_FIRST_TURN_PREAMBLE } from './thinkpool-room-prompt.mjs'
+import { CODEX_THINKPOOL_FIRST_TURN_PREAMBLE, THINKPOOL_RUNTIME_TURN_REMINDER } from './thinkpool-room-prompt.mjs'
 
 const DEFAULT_SANDBOX = 'workspace-write'
 const SAFE_SANDBOXES = new Set(['read-only', 'workspace-write', 'danger-full-access'])
@@ -219,6 +219,7 @@ export function buildCodexPrompt({ text, terminalRolePrompt, rolePrompt, roomCon
   const additions = [
     firstTurn ? CODEX_THINKPOOL_FIRST_TURN_PREAMBLE : '',
     terminalRolePrompt,
+    THINKPOOL_RUNTIME_TURN_REMINDER,
     rolePrompt || CODEX_ROOM_CASCADE_REMINDER,
     context,
   ].map((v) => String(v || '').trim()).filter(Boolean)

package/hermes-acp-bootstrap.py

@@ -145,6 +145,57 @@ def constrained_expand(toolsets_arg=None, mcp_server_names=None):
 acp_adapter.session._expand_acp_enabled_toolsets = constrained_expand
 
 import acp_adapter.server
+
+# Hermes 0.18.2 emits the real result through ``tool.completed`` immediately,
+# but its ACP callback ignores that event and waits for the next model-step
+# summary.  Parallel Read/search calls are not always present in that summary,
+# leaving clients with a ToolCallStart and no ToolCallUpdate forever.  Complete
+# from the authoritative execution callback and consume the same per-name FIFO;
+# the later step callback then sees an empty queue and cannot double-emit.  If a
+# future Hermes release handles completion itself, it consumes the queue before
+# this wrapper runs and this compatibility branch becomes a no-op.
+from collections import deque
+import acp_adapter.events
+import acp_adapter.tools
+
+_tool_progress_factory = acp_adapter.server.make_tool_progress_cb
+def completion_aware_tool_progress_factory(
+    conn, session_id, loop, tool_call_ids, tool_call_meta,
+    edit_approval_policy_getter=None,
+):
+    upstream = _tool_progress_factory(
+        conn, session_id, loop, tool_call_ids, tool_call_meta,
+        edit_approval_policy_getter=edit_approval_policy_getter,
+    )
+
+    def progress(event_type, name=None, preview=None, args=None, **kwargs):
+        upstream(event_type, name, preview, args, **kwargs)
+        if event_type != "tool.completed" or not name:
+            return
+        queue = tool_call_ids.get(name)
+        if isinstance(queue, str):
+            queue = deque([queue])
+            tool_call_ids[name] = queue
+        if not queue:
+            return
+        tool_call_id = queue.popleft()
+        meta = tool_call_meta.pop(tool_call_id, {})
+        result = kwargs.get("result")
+        update = acp_adapter.tools.build_tool_complete(
+            tool_call_id,
+            name,
+            result=str(result) if result is not None else None,
+            function_args=meta.get("args"),
+            snapshot=meta.get("snapshot"),
+        )
+        acp_adapter.events._send_update(conn, session_id, loop, update)
+        if not queue:
+            tool_call_ids.pop(name, None)
+
+    return progress
+
+acp_adapter.server.make_tool_progress_cb = completion_aware_tool_progress_factory
+
 _register = acp_adapter.server.HermesACPAgent._register_session_mcp_servers
 async def constrained_register(self, state, mcp_servers):
     if any(getattr(server, "name", None) != "thinkpool" for server in (mcp_servers or [])):

package/hermes-event-mapper.mjs

@@ -128,16 +128,17 @@ export class HermesEventMapper {
   }
 
   finishTurn({ stopReason = 'end_turn', usage = null } = {}) {
-    if (stopReason === 'cancelled') {
-      for (const [toolCallId, tool] of this.tools) {
-        this._emit({
-          kind: 'tool_result', toolUseId: toolCallId,
-          content: [{ type: 'text', text: '[cancelled]' }],
-          isError: false,
-          durationMs: tool.startedAt ? Date.now() - tool.startedAt : undefined,
-          parentToolUseId: null,
-        })
-      }
+    for (const [toolCallId, tool] of this.tools) {
+      const cancelled = stopReason === 'cancelled'
+      this._emit({
+        kind: 'tool_result', toolUseId: toolCallId,
+        content: [{ type: 'text', text: cancelled ? '[cancelled]' : 'Hermes ended the turn without reporting this tool result.' }],
+        toolInput: tool.input || undefined,
+        isError: !cancelled && stopReason !== 'end_turn',
+        missing: !cancelled,
+        durationMs: tool.startedAt ? Date.now() - tool.startedAt : undefined,
+        parentToolUseId: null,
+      })
     }
     this.tools.clear()
     const blocks = []

package/hermes-session.mjs

@@ -10,6 +10,7 @@ import { HERMES_PLAN_SAFE_MCP_TOOLS, HERMES_QUESTION_MCP_TOOL, hermesExactInvent
 import { startCodexMcpHttp } from './codex-mcp-http.mjs'
 import { autoAllow, classifyRisk } from './claude-session.mjs'
 import { crossPostNeedsCard } from './cross-terminal.mjs'
+import { THINKPOOL_RUNTIME_TURN_REMINDER } from './thinkpool-room-prompt.mjs'
 
 export const HERMES_COMMAND = 'thinkpool'
 export const HERMES_ACP_PROTOCOL_VERSION = 1
@@ -34,6 +35,19 @@ const modelList = (state) => (state?.availableModels || []).map((item) => ({ val
 const mcpDescriptor = (url) => ({ type: 'http', name: 'thinkpool', url, headers: [] })
 const createAcpClient = (options) => new AcpClient(options)
 
+export function buildHermesPromptText({ text, firstTurn = false, terminalRolePrompt, rolePrompt, roomContext } = {}) {
+  const context = typeof roomContext === 'function' ? roomContext() : roomContext
+  const inThinkPoolRoom = !!(terminalRolePrompt || rolePrompt || context)
+  const preamble = [
+    firstTurn ? terminalRolePrompt : '',
+    inThinkPoolRoom ? THINKPOOL_RUNTIME_TURN_REMINDER : '',
+    firstTurn ? rolePrompt : '',
+    context,
+  ].filter(Boolean).join('\n\n')
+  const body = String(text ?? '')
+  return preamble ? `${preamble}\n\n${body}` : body
+}
+
 const permissionOutcome = (decision, options = []) => {
   if (decision === 'deny' || !decision) return { outcome: 'cancelled' }
   const preferred = decision === 'always'
@@ -384,9 +398,7 @@ export function startHermesSession({
     // Hermes handles /steer, /queue, /compact and /reset only when the slash is
     // the first character of a pure-text prompt.
     if (/^\s*\//.test(rawText)) return [{ type: 'text', text: rawText }]
-    const context = typeof roomContext === 'function' ? roomContext() : roomContext
-    const preamble = firstTurn ? [terminalRolePrompt, rolePrompt, context].filter(Boolean).join('\n\n') : context
-    const blocks = [{ type: 'text', text: preamble ? `${preamble}\n\n${rawText}` : rawText }]
+    const blocks = [{ type: 'text', text: buildHermesPromptText({ text: rawText, firstTurn, terminalRolePrompt, rolePrompt, roomContext }) }]
     for (const imagePath of (Array.isArray(options.images) ? options.images : [])) {
       try { blocks.push(imageBlock(imagePath)) } catch { /* quoted host path remains in text */ }
     }

package/model-prices.mjs

@@ -0,0 +1,113 @@
+// Public model-price resolver for the bridge's usage ledger.
+// Runtime model catalogs tell us what ran, but not what a provider bills for
+// it. LiteLLM maintains a public catalog; cache its validated data locally and
+// persist the resolved rate beside each turn. A failed refresh never blocks a
+// turn or drops token accounting.
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const CATALOG_URL = 'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json'
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000
+const CACHE_MAX_BYTES = 4 * 1024 * 1024
+const cachePath = () => process.env.TP_MODEL_PRICE_CACHE || path.join(process.env.TP_PAIR_ROOT || path.join(os.homedir(), '.thinkpool-pair'), 'model-prices.json')
+
+// First-party runtimes remain priced while offline or before the catalog loads.
+const FALLBACKS = Object.freeze({
+  'gpt-5.6-sol': { input: 5, cached: 0.5, output: 30 },
+  'gpt-5.6-terra': { input: 2.5, cached: 0.25, output: 15 },
+  'gpt-5.6-luna': { input: 1, cached: 0.1, output: 6 },
+  'gpt-5.4': { input: 2.5, cached: 0.25, output: 15 },
+  'gpt-5.4-mini': { input: 0.75, cached: 0.075, output: 4.5 },
+  'gpt-5.4-nano': { input: 0.2, cached: 0.02, output: 1.25 },
+  'claude-opus-4-8': { input: 5, cached: 0.5, output: 25 },
+  'claude-fable-5': { input: 10, cached: 1, output: 50 },
+  'claude-sonnet-5': { input: 2, cached: 0.2, output: 10 },
+  'claude-haiku-4-5': { input: 1, cached: 0.1, output: 5 },
+  'glm-5.2': { input: 1.4, cached: 0.26, output: 4.4 },
+  'glm-4.6': { input: 0.6, cached: 0.11, output: 2.2 },
+})
+
+function cleanRate(raw) {
+  // Catalog rates are per token; normalize at the persistence boundary so a
+  // decimal like 0.0000001 does not become 0.09999999999999999 in Settings.
+  const perMillion = (value) => Math.round(Number(value) * 1_000_000 * 1_000_000) / 1_000_000
+  const input = perMillion(raw?.input_cost_per_token)
+  const output = perMillion(raw?.output_cost_per_token)
+  const cached = perMillion(raw?.cache_read_input_token_cost ?? raw?.cache_read_input_tokens_cost)
+  if (!Number.isFinite(input) || input < 0 || !Number.isFinite(output) || output < 0) return null
+  return { input, output, cached: Number.isFinite(cached) && cached >= 0 ? cached : null }
+}
+
+export function modelPriceKeys(model) {
+  const raw = String(model || '').trim()
+  if (!raw) return []
+  const withoutMarker = raw.replace(/\[[^\]]+\]/g, '')
+  const withoutPrefix = withoutMarker.replace(/^[^:/]+:/, '')
+  const tail = withoutPrefix.includes('/') ? withoutPrefix.slice(withoutPrefix.lastIndexOf('/') + 1) : withoutPrefix
+  return [...new Set([raw, withoutMarker, withoutPrefix, tail].filter(Boolean))]
+}
+
+function readCache() {
+  try {
+    const file = cachePath()
+    if ((Number(fs.statSync(file).size) || 0) > CACHE_MAX_BYTES) return null
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return parsed?.models && typeof parsed.models === 'object' ? parsed : null
+  } catch { return null }
+}
+
+function writeCache(models) {
+  try {
+    const file = cachePath()
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, JSON.stringify({ fetchedAt: Date.now(), models }), { mode: 0o600 })
+  } catch { /* cache is opportunistic */ }
+}
+
+export function rateFromCatalog(model, models) {
+  for (const key of modelPriceKeys(model)) {
+    const rate = cleanRate(models?.[key])
+    if (rate) return rate
+  }
+  for (const key of modelPriceKeys(model)) {
+    const fallback = FALLBACKS[key.toLowerCase()]
+    if (fallback) return fallback
+  }
+  return null
+}
+
+export function createModelPriceResolver({ fetchImpl = globalThis.fetch } = {}) {
+  let cached = readCache()
+  let refresh = null
+  const refreshCatalog = async () => {
+    if (refresh) return refresh
+    refresh = (async () => {
+      let timer
+      try {
+        const controller = new AbortController()
+        timer = setTimeout(() => controller.abort(), 4_000)
+        const response = await fetchImpl(CATALOG_URL, { signal: controller.signal })
+        if (!response?.ok) return cached?.models || null
+        const models = await response.json()
+        if (!models || typeof models !== 'object') return cached?.models || null
+        cached = { fetchedAt: Date.now(), models }
+        writeCache(models)
+        return models
+      } catch { return cached?.models || null }
+      finally { clearTimeout(timer); refresh = null }
+    })()
+    return refresh
+  }
+  return async (model) => {
+    const current = rateFromCatalog(model, cached?.models)
+    if (current) return { ...current, source: cached?.models ? 'litellm-cache' : 'bridge-fallback' }
+    const stale = !cached || (Date.now() - Number(cached.fetchedAt || 0)) > CACHE_TTL_MS
+    const models = stale ? await refreshCatalog() : cached?.models
+    const rate = rateFromCatalog(model, models)
+    return rate ? { ...rate, source: models ? 'litellm' : 'bridge-fallback' } : null
+  }
+}
+
+export const priceForModel = createModelPriceResolver()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.256",
+  "version": "0.7.258",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -80,6 +80,7 @@
     "supabase-key.mjs",
     "provider.mjs",
     "providers.mjs",
+    "model-prices.mjs",
     "README.md"
   ],
   "scripts": {

package/thinkpool-room-prompt.mjs

@@ -1,21 +1,96 @@
 // Shared delivery contract for structured agents running inside ThinkPool Code.
-// Claude receives this as part of its system prompt; Codex receives it ahead of
-// the first human turn in each fresh native thread. Keep the runtime-specific
+// Claude receives this in its system prompt plus a per-turn reminder; Codex and
+// Hermes receive it adjacent to normal room turns. Keep runtime-specific
 // orchestration rules in their own drivers — these are the cross-runtime truths
-// about where the people are and how finished work must reach them.
-export const THINKPOOL_DESIGN_DELIVERY_RULE = 'THINKPOOL DESIGN (mandatory for HTML): save the editable HTML source in the workspace, then use the $TP_MOCKUP_OUTBOX render helper so the room receives a Thinkpool Design card with both desktop (1440×900) and mobile (390×844) previews. When the requested Design surface is an existing product page or route, first build and capture the actual route at both viewports, then read its current source, styles, copy, fonts, and assets. Derive the editable Design artifact from that evidence and compare both artifact captures against the real route before delivery. Preserve the real page faithfully except for explicitly proposed edits—never hand-recreate it from memory, simplify it, replace it with generic mockup content, or label an approximation as the product. If a faithful editable artifact cannot be produced, surface the actual route captures and say that Design editing is unavailable for that surface. Never paste raw HTML into chat, send an .html file as the room deliverable, or substitute a bare URL or single screenshot for this card. A shareable browser URL may accompany the card, but never replaces it.'
+// about available capabilities and how finished work reaches the people.
+// One canonical intent → capability router for every structured runtime. Tool
+// schemas still carry their detailed argument contracts; this compact registry
+// tells a fresh agent WHEN ThinkPool expects each capability without requiring
+// the people in the room to know a tool name or summon word.
+export const THINKPOOL_CAPABILITY_ROUTES = Object.freeze([
+  Object.freeze({
+    id: 'room-awareness',
+    tools: Object.freeze(['read_terminal']),
+    rule: 'When the request depends on another lane, a sibling may overlap the work, or a person refers to another terminal, inspect it with read_terminal before acting.',
+  }),
+  Object.freeze({
+    id: 'cross-room-awareness',
+    tools: Object.freeze(['list_sessions', 'read_session']),
+    rule: 'When work depends on another ThinkPool room, use list_sessions then read_session instead of asking the people to relay host-side state.',
+  }),
+  Object.freeze({
+    id: 'visible-handoff',
+    tools: Object.freeze(['post_to_terminal', 'post_to_session']),
+    rule: 'When the people want a handoff, read the target first, then use post_to_terminal or post_to_session; let the room approval contract handle consent.',
+  }),
+  Object.freeze({
+    id: 'work-routing',
+    tools: Object.freeze(['spawn_terminal', 'open_main_terminal', 'close_terminal']),
+    rule: '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.',
+  }),
+  Object.freeze({
+    id: 'room-question',
+    tools: Object.freeze(['request_user_input']),
+    rule: 'When a missing choice genuinely blocks useful progress, use request_user_input so the question is answerable in the room; otherwise make a safe in-scope assumption and continue.',
+  }),
+  Object.freeze({
+    id: 'visual-proof',
+    tools: Object.freeze(['preview_start', 'preview_capture', 'preview_inspect', 'preview_stop']),
+    rule: 'For built visual work, run the build, use preview_start, preview_capture at desktop and mobile, preview_inspect when rendered state matters, and preview_stop when finished. Surface PNG evidence only when no interactive source-backed Design card/popup is displayed.',
+  }),
+  Object.freeze({
+    id: 'external-research',
+    tools: Object.freeze(['research']),
+    rule: 'For current external facts that materially benefit from multi-source verification, offer the metered research lane and call research only after the people agree.',
+  }),
+  Object.freeze({
+    id: 'flow-completion',
+    tools: Object.freeze(['submit_flow_plan', 'mark_flow_done', 'submit_flow_review', 'read_review_file', 'run_review_check']),
+    rule: 'Managed Flow roles use only their exposed completion and immutable-review tools: submit_flow_plan, mark_flow_done, submit_flow_review, read_review_file, and run_review_check.',
+  }),
+])
+
+export const THINKPOOL_ROUTED_TOOLS = Object.freeze([
+  ...new Set(THINKPOOL_CAPABILITY_ROUTES.flatMap((route) => route.tools)),
+])
+
+export function renderThinkPoolCapabilityRoutes(routes = THINKPOOL_CAPABILITY_ROUTES) {
+  return routes.map((route) => `${route.id}: ${route.rule}`).join(' ')
+}
+
+export const THINKPOOL_AGENT_CONTRACT = [
+  'THINKPOOL-FIRST OPERATING CONTRACT (authoritative): ThinkPool room capabilities are your normal operating surface, not optional enrichment. Before acting on every request, infer which exposed ThinkPool capabilities materially improve room visibility, coordination, delivery, or verification and use them without waiting for the people to know a tool name, magic word, or workflow.',
+  `DEFAULT ROUTING: ${renderThinkPoolCapabilityRoutes()}`,
+  'DEFAULT DOES NOT MEAN GRATUITOUS: use only capabilities exposed to your current role and only when relevant. Honor explicit steering such as single-lane, no research, do not contact another room, or do not use a named ThinkPool feature. Metered and side-effecting capabilities still obey their stated offer, approval, and consent contracts.',
+].join(' ')
+
+export const THINKPOOL_DESIGN_INTERACTION_RULE = 'DESIGN EDITING MODEL: the user edits through a source-backed mockup card\'s Work on design action, which opens the fullscreen mockup/Design popup; never ask them to locate or edit HTML. Popup edits are optimistic drafts only. Apply sends the bounded batch to the producing lane, that lane edits the canonical authored HTML, and a successful desktop+mobile render publishes the next verified revision back into the popup. Never call an in-popup draft saved or live. A preview_capture card is visual evidence, not an editable Design artifact.'
+
+export const THINKPOOL_DESIGN_DELIVERY_RULE = `THINKPOOL DESIGN (mandatory for authored HTML): save the editable HTML source in the workspace, then use the $TP_MOCKUP_OUTBOX render helper so the room receives a source-backed Thinkpool Design card with both desktop (1440×900) and mobile (390×844) previews. The interactive Design card/popup is the visible result: the renders remain required verification inputs, but when that card is displayed do not also surface duplicate inline PNGs. Surface desktop/mobile PNGs only when no interactive source-backed Design artifact is available. ${THINKPOOL_DESIGN_INTERACTION_RULE} When the requested Design surface is an existing product page or route, first build and capture the actual route at both viewports, then read its current source, styles, copy, fonts, and assets. Derive the editable Design artifact from that evidence and compare both artifact captures against the real route before delivery. Preserve the real page faithfully except for explicitly proposed edits—never hand-recreate it from memory, simplify it, replace it with generic mockup content, or label an approximation as the product. If a faithful editable artifact cannot be produced, surface the actual route captures and say that Design editing is unavailable for that surface. Never paste raw HTML into chat, send an .html file as the room deliverable, or substitute a bare URL or single screenshot for this card. A shareable browser URL may accompany the card, but never replaces it.`
 
 export const THINKPOOL_REMOTE_DELIVERY_RULES = Object.freeze([
   'REMOTE USER (authoritative default for ThinkPool Code rooms): unless a person explicitly says they are at the host machine, assume everyone driving this room is remote — possibly on a phone — with no terminal and no access to the host filesystem. Never ask them to run a local command, open a local file, or "go check" something on the machine. Anything host-side, you run yourself and show the result in the room. Only suggest actions they can actually do from the room UI or a browser.',
   'LINKS & ARTIFACTS: a local filesystem path, file:// URL, localhost/127.0.0.1 address, or host-only preview is useless to a remote room. Every link you surface must be reachable by the people in the room.',
   'Whenever you produce HTML or shareable markup — a demo, mockup, preview, report, or page — publish it to a browser-renderable GitHub-shareable URL, normally GitHub Pages (or an equivalent URL that actually renders; raw.githubusercontent.com serves HTML as plain text). Give the room that shareable URL in addition to the Thinkpool Design card, never instead of it and never only as a local path. If you cannot publish it, say so instead of falling back to a host-only path.',
-  'SHOW VISUAL WORK: whenever you build, change, or fix anything visual — UI, page, HTML artifact, chart, diagram, or rendered result — capture a PNG and surface the image in your turn so it appears inline in the room; the room auto-uploads surfaced images. Prefer showing the result over describing it.',
+  'SHOW VISUAL WORK: whenever you build, change, or fix anything visual, show the result in the room. A source-backed Thinkpool Design card/popup is already the interactive visible result, so do not additionally surface duplicate PNGs. When no interactive Design artifact is available, capture and surface desktop/mobile PNG evidence inline.',
   'BRIDGE PREVIEWS: for a built web UI, use preview_start (default root: dist), then preview_capture for exact desktop 1440x900 and mobile 390x844 PNGs, and preview_inspect when DOM text or selector geometry helps. Run the project build first and stop the preview server with preview_stop when done.',
   THINKPOOL_DESIGN_DELIVERY_RULE,
   '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.
+// Compact enough to repeat adjacent to every normal user turn. The full remote
+// delivery contract is still installed at session boot where the runtime offers
+// a durable system channel; this reminder keeps the high-drift decisions salient
+// after long tool runs, resumes, and compaction without duplicating the manual.
+export const THINKPOOL_RUNTIME_TURN_REMINDER = [
+  THINKPOOL_AGENT_CONTRACT,
+  'REMOTE DELIVERY: assume the people are remote unless they explicitly say otherwise. Run host-side work yourself; never hand them a local path, file:// or localhost URL, or ask them to use the host terminal. Surface reachable links and inline evidence in the room.',
+  'VISUAL DELIVERY: build first and verify exact desktop and mobile renders. If a source-backed Thinkpool Design card/popup is displayed, do not separately surface its PNGs; if no interactive Design artifact is available, surface the desktop/mobile PNG evidence inline. Stop bridge previews when finished.',
+  THINKPOOL_DESIGN_INTERACTION_RULE,
+  'VERIFY BEFORE CLAIMING: run or serve what changed and show the real response, passing output, or rendered evidence; state exactly what remains unverified.',
+].join(' ')
+
+// One authoritative terminal-identity preamble for every structured runtime.
 // 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