gui(refactor): unify keybinding ui & types

* fix(docker): optimize image size with .dockerignore, drop dev deps, split build layers

Three changes to reduce the Docker image size and speed up rebuilds:

1. .dockerignore — exclude ~69 MB of files that are never needed inside
   the container: apps/ (desktop Tauri source), tests/, website/
   (Docusaurus), docs/, infographic/, nix/, plans/, packaging/, and
   various dotfiles (.envrc, .hadolint.yaml, .mailmap, etc.).  The
   existing .dockerignore already covered node_modules and .git; these
   additions prevent the remaining non-runtime content from inflating
   both the build context and the final image (COPY . .).

2. pyproject.toml — add a [docker] extra that mirrors [all] but omits
   [dev] (debugpy, pytest, pytest-asyncio, pytest-timeout, ty, ruff,
   setuptools).  The published image doesn't need test/debug tooling.
   Estimated savings: ~30-50 MB of Python packages.

3. Dockerfile — use --extra docker instead of --extra all in the
   uv sync layer.  Also split the COPY + npm run build so that the
   web/ and ui-tui/ frontend builds are cached independently from
   Python source changes (COPY . .).  A Python-only commit no longer
   invalidates the (slower) frontend build layer.

Note: the build-only apt packages (gcc, python3-dev, libffi-dev,
libolm-dev) are still installed in the final image.  Removing them
requires a true multi-stage build (builder → runtime), which is a
larger refactor tracked separately.

* fix(docker): remove redundant [docker] extra, revert to --extra all

The [docker] extra was identical to [all] on main — the PR had added [dev]
to [all] then created [docker] as [all] minus [dev], a no-op round-trip.
Revert [all] to its original form and drop the [docker] extra.

Keep the .dockerignore additions and frontend build layer reordering.

.dockerignore

@@ -63,3 +63,45 @@ data/
 # Compose/profile runtime state (bind-mounted; avoid ownership/secret issues)
 hermes-config/
 runtime/
+
+# ---------- Not needed inside the Docker image ----------
+
+# Desktop app source (Tauri/Electron); never installed in the container
+apps/
+
+# Test suite — not shipped in production images
+tests/
+
+# Documentation site (Docusaurus) and supplementary docs
+website/
+docs/
+
+# Assets only used by the GitHub README
+assets/
+infographic/
+
+# Plugin-level docs (hermes-achievements ships docs/ but the runtime doesn't read them)
+plugins/hermes-achievements/docs/
+
+# Nix / Homebrew / AUR packaging metadata — irrelevant to Docker
+nix/
+flake.nix
+flake.lock
+packaging/
+
+# Design and planning documents
+plans/
+.plans/
+
+# ACP registry manifest (icon + agent.json) — not consumed at runtime
+acp_registry/
+
+# Repo-level dotfiles that are git-only or dev-tooling config
+.env.example
+.envrc
+.gitattributes
+.hadolint.yaml
+.mailmap
+
+# Top-level LICENSE (not matched by *.md); not needed inside the container
+LICENSE

.gitignore

@@ -114,6 +114,12 @@ docs/superpowers/*
 # treat it as a local edit and autostash it on every run (#38529).
 .hermes-bootstrap-complete
 
+# Interrupted-update breadcrumb + recovery lock written next to the shared venv
+# by `hermes update` / launch-time self-heal. Runtime state, never a code change
+# — ignore so `git status` stays clean and update's autostash skips them.
+.update-incomplete
+.update-incomplete.lock
+
 # Tool Search live-test harness output — non-deterministic model transcripts,
 # regenerated by scripts/tool_search_livetest.py. Never an artifact of the repo.
 scripts/out/

Dockerfile

@@ -25,7 +25,7 @@ ENV PLAYWRIGHT_BROWSERS_PATH=/opt/hermes/.playwright
 # hermes process, the dashboard, and per-profile gateways.
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
-    ca-certificates curl iputils-ping python3 python-is-python3 ripgrep ffmpeg gcc python3-dev python3-venv libffi-dev libolm-dev procps git openssh-client docker-cli xz-utils && \
+    ca-certificates curl iputils-ping python3 python-is-python3 ripgrep ffmpeg gcc g++ make cmake python3-dev python3-venv libffi-dev libolm-dev procps git openssh-client docker-cli xz-utils && \
     rm -rf /var/lib/apt/lists/*
 
 # ---------- s6-overlay install ----------
@@ -146,9 +146,9 @@ RUN npm install --prefer-offline --no-audit && \
 #
 # `uv sync --frozen --no-install-project --extra all --extra messaging`
 # installs the deps reachable through the composite `[all]` extra
-# (handpicked set intended for the production image), plus gateway
-# messaging adapters that should work in the published image without a
-# first-boot lazy install.  We do NOT use `--all-extras`:
+# (handpicked set intended for the production image — excludes `[dev]`),
+# plus gateway messaging adapters that should work in the published image
+# without a first-boot lazy install.  We do NOT use `--all-extras`:
 # that would pull in `[rl]` (atroposlib + tinker + torch + wandb from
 # git), `[yc-bench]` (another git dep), and `[termux-all]` (Android
 # redundancy), none of which belong in the published container.
@@ -164,19 +164,30 @@ RUN npm install --prefer-offline --no-audit && \
 # image update and recall/retain then fails with
 # `ModuleNotFoundError: No module named 'hindsight_client'` (#38128).
 #
+# The Matrix gateway's deps ([matrix] extra) are baked in because
+# python-olm (transitive via mautrix[encryption]) builds from source on
+# Python/image combinations without usable wheels.  The Docker image is
+# Linux-only, so keeping the native libolm/build-toolchain packages here
+# avoids the cross-platform failures that kept [matrix] out of [all]
+# while still making Matrix work in the published container. Fixes #30399.
+#
 # The editable link is created after the source copy below.
 COPY pyproject.toml uv.lock ./
 RUN touch ./README.md
-RUN uv sync --frozen --no-install-project --extra all --extra messaging --extra anthropic --extra bedrock --extra azure-identity --extra hindsight
+RUN uv sync --frozen --no-install-project --extra all --extra messaging --extra anthropic --extra bedrock --extra azure-identity --extra hindsight --extra matrix
+
+# ---------- Frontend build (cached independently from Python source) ----------
+# Copy only the frontend source trees first so that Python-only changes don't
+# invalidate the (relatively slow) web + ui-tui build layer.
+COPY web/ web/
+COPY ui-tui/ ui-tui/
+RUN cd web && npm run build && \
+    cd ../ui-tui && npm run build
 
 # ---------- Source code ----------
 # .dockerignore excludes node_modules, so the installs above survive.
 COPY --chown=hermes:hermes . .
 
-# Build browser dashboard and terminal UI assets.
-RUN cd web && npm run build && \
-    cd ../ui-tui && npm run build
-
 # ---------- Permissions ----------
 # Make install dir world-readable so any HERMES_UID can read it at runtime.
 # The venv needs to be traversable too.

agent/auxiliary_client.py

@@ -102,7 +102,7 @@ OpenAI = _OpenAIProxy()  # module-level name, resolves lazily on call/isinstance
 from agent.credential_pool import load_pool
 from hermes_cli.config import get_hermes_home
 from hermes_constants import OPENROUTER_BASE_URL
-from utils import base_url_host_matches, base_url_hostname, normalize_proxy_env_vars
+from utils import base_url_host_matches, base_url_hostname, model_forces_max_completion_tokens, normalize_proxy_env_vars
 
 logger = logging.getLogger(__name__)
 
@@ -4300,13 +4300,15 @@ def get_auxiliary_extra_body() -> dict:
     return _nous_extra_body() if auxiliary_is_nous else {}
 
 
-def auxiliary_max_tokens_param(value: int) -> dict:
+def auxiliary_max_tokens_param(value: int, *, model: Optional[str] = None) -> dict:
     """Return the correct max tokens kwarg for the auxiliary client's provider.
-    
+
     OpenRouter and local models use 'max_tokens'. Direct OpenAI with newer
-    models (gpt-4o, o-series, gpt-5+) requires 'max_completion_tokens'.
+    models (gpt-4o, gpt-4.1, gpt-5+, o-series) requires 'max_completion_tokens'.
     The Codex adapter translates max_tokens internally, so we use max_tokens
-    for it as well.
+    for it as well. Pass ``model`` so third-party OpenAI-compatible endpoints
+    fronting the newer families are also recognised — URL-only detection
+    misses the case where a custom base URL serves e.g. ``gpt-5.4``.
     """
     custom_base = _current_custom_base_url()
     or_key = os.getenv("OPENROUTER_API_KEY")
@@ -4316,6 +4318,9 @@ def auxiliary_max_tokens_param(value: int) -> dict:
             and _read_nous_auth() is None
             and base_url_hostname(custom_base) in {"api.openai.com", "api.githubcopilot.com"}):
         return {"max_completion_tokens": value}
+    # ...and for any caller serving a newer OpenAI-family model by name.
+    if model_forces_max_completion_tokens(model):
+        return {"max_completion_tokens": value}
     return {"max_tokens": value}
 
 

agent/curator.py

@@ -25,7 +25,6 @@ import json
 import logging
 import os
 import re
-import tempfile
 import threading
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
@@ -33,6 +32,7 @@ from typing import Any, Callable, Dict, List, NamedTuple, Optional, Set
 
 from hermes_constants import get_hermes_home
 from tools import skill_usage
+from utils import atomic_json_write
 
 logger = logging.getLogger(__name__)
 
@@ -97,20 +97,7 @@ def load_state() -> Dict[str, Any]:
 def save_state(data: Dict[str, Any]) -> None:
     path = _state_file()
     try:
-        path.parent.mkdir(parents=True, exist_ok=True)
-        fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".curator_state_", suffix=".tmp")
-        try:
-            with os.fdopen(fd, "w", encoding="utf-8") as f:
-                json.dump(data, f, indent=2, sort_keys=True, ensure_ascii=False)
-                f.flush()
-                os.fsync(f.fileno())
-            os.replace(tmp, path)
-        except BaseException:
-            try:
-                os.unlink(tmp)
-            except OSError:
-                pass
-            raise
+        atomic_json_write(path, data, indent=2, sort_keys=True)
     except Exception as e:
         logger.debug("Failed to save curator state: %s", e, exc_info=True)
 

agent/error_classifier.py

@@ -966,6 +966,34 @@ def _classify_400(
             should_fallback=False,
         )
 
+    # Request-validation errors (unsupported / unknown parameter) MUST be
+    # checked BEFORE context_overflow.  A GPT-5 model rejecting max_tokens
+    # returns:
+    #   "Unsupported parameter: 'max_tokens' is not supported with this model.
+    #    Use 'max_completion_tokens' instead."
+    # That string contains the literal substring "max_tokens", which is one of
+    # the _CONTEXT_OVERFLOW_PATTERNS — so without this guard the 400 is
+    # misclassified as context_overflow, routed into the compression loop,
+    # re-sent with the same bad parameter, and ends in "Cannot compress
+    # further".  These errors are deterministic (every retry gets the identical
+    # rejection), so classify as a non-retryable format_error and fall back.
+    #
+    # NOTE: we deliberately do NOT key off the generic ``invalid_request_error``
+    # code here — OpenAI stamps that same code on genuine context-overflow 400s,
+    # so matching it would mis-route real overflows away from compression. The
+    # unambiguous signals are the explicit "unsupported/unknown parameter"
+    # message text and the specific parameter-level error codes.
+    if (
+        any(p in error_msg for p in _REQUEST_VALIDATION_PATTERNS
+            if p != "invalid_request_error")
+        or error_code_lower in {"unknown_parameter", "unsupported_parameter"}
+    ):
+        return result_fn(
+            FailoverReason.format_error,
+            retryable=False,
+            should_fallback=True,
+        )
+
     # Context overflow from 400
     if any(p in error_msg for p in _CONTEXT_OVERFLOW_PATTERNS):
         return result_fn(

agent/model_metadata.py

@@ -1838,6 +1838,17 @@ def get_model_context_length(
         from agent.models_dev import lookup_models_dev_context
         ctx = lookup_models_dev_context(effective_provider, model)
         if ctx:
+            # MiniMax M3: models.dev reports 512K but actual context is 1M.
+            # Prefer hardcoded catalog over stale probe value.
+            if _model_name_suggests_minimax_m3(model):
+                catalog = DEFAULT_CONTEXT_LENGTHS.get("minimax-m3")
+                if catalog and ctx < catalog:
+                    logger.info(
+                        "Rejecting models.dev context=%s for %r "
+                        "(MiniMax-M3 underreport); using hardcoded default %s",
+                        ctx, model, f"{catalog:,}",
+                    )
+                    ctx = catalog
             return ctx
 
     # 6. OpenRouter live API metadata — provider-unaware fallback.

agent/usage_pricing.py

@@ -13,6 +13,7 @@ DEFAULT_PRICING = {"input": 0.0, "output": 0.0}
 
 _ZERO = Decimal("0")
 _ONE_MILLION = Decimal("1000000")
+_NOUS_DEFAULT_BASE_URL = "https://inference-api.nousresearch.com/v1"
 
 CostStatus = Literal["actual", "estimated", "included", "unknown"]
 CostSource = Literal[
@@ -570,6 +571,8 @@ def resolve_billing_route(
         return BillingRoute(provider="openai-codex", model=model, base_url=base_url or "", billing_mode="subscription_included")
     if provider_name == "openrouter" or base_url_host_matches(base_url or "", "openrouter.ai"):
         return BillingRoute(provider="openrouter", model=model, base_url=base_url or "", billing_mode="official_models_api")
+    if provider_name == "nous" or base_url_host_matches(base_url or "", "inference-api.nousresearch.com"):
+        return BillingRoute(provider="nous", model=model, base_url=base_url or _NOUS_DEFAULT_BASE_URL, billing_mode="official_models_api")
     if provider_name == "anthropic":
         return BillingRoute(provider="anthropic", model=model.split("/")[-1], base_url=base_url or "", billing_mode="official_docs_snapshot")
     if provider_name == "openai":

apps/desktop/electron/bootstrap-runner.cjs

@@ -40,6 +40,15 @@ const path = require('node:path')
 const https = require('node:https')
 const { spawn } = require('node:child_process')
 
+const IS_WINDOWS = process.platform === 'win32'
+
+function hiddenWindowsChildOptions(options = {}) {
+  if (!IS_WINDOWS || Object.prototype.hasOwnProperty.call(options, 'windowsHide')) {
+    return options
+  }
+  return { ...options, windowsHide: true }
+}
+
 const STAMP_COMMIT_RE = /^[0-9a-f]{7,40}$/i
 
 // Stages flagged needs_user_input=true in the manifest are skipped by the
@@ -284,7 +293,7 @@ function spawnPowerShell(scriptPath, args, { emit, stageName, abortSignal, herme
     const ps = process.platform === 'win32' ? resolveWindowsPowerShell() : 'pwsh'
     const fullArgs = ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', scriptPath, ...args]
 
-    const child = spawn(ps, fullArgs, {
+    const child = spawn(ps, fullArgs, hiddenWindowsChildOptions({
       stdio: ['ignore', 'pipe', 'pipe'],
       env: {
         ...process.env,
@@ -292,7 +301,7 @@ function spawnPowerShell(scriptPath, args, { emit, stageName, abortSignal, herme
         // choice rather than re-computing the default.
         HERMES_HOME: hermesHome || process.env.HERMES_HOME || ''
       }
-    })
+    }))
 
     let stdout = ''
     let stderr = ''

apps/desktop/electron/main.cjs

@@ -107,6 +107,13 @@ const IS_WINDOWS = process.platform === 'win32'
 const IS_WSL = isWslEnvironment()
 const APP_ROOT = app.getAppPath()
 
+function hiddenWindowsChildOptions(options = {}) {
+  if (!IS_WINDOWS || Object.prototype.hasOwnProperty.call(options, 'windowsHide')) {
+    return options
+  }
+  return { ...options, windowsHide: true }
+}
+
 // Remote displays (SSH X11 forwarding, VNC, RDP) make Chromium's GPU
 // compositor flicker — accelerated layers can't be presented cleanly over the
 // wire, so the window flashes during scroll/streaming/animation. Local
@@ -1106,7 +1113,7 @@ function findSystemPython() {
         const out = execFileSync(
           'reg',
           ['query', `${hive}\\SOFTWARE\\Python\\PythonCore\\${version}\\InstallPath`, '/ve', '/reg:64'],
-          { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+          hiddenWindowsChildOptions({ encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
         )
         // Output format: "    (Default)    REG_SZ    C:\Path\To\Python\"
         const match = out.match(/REG_SZ\s+(.+?)\s*$/m)
@@ -1142,10 +1149,10 @@ function findSystemPython() {
   if (pyExe) {
     for (const version of SUPPORTED_VERSIONS) {
       try {
-        const out = execFileSync(pyExe, [`-${version}`, '-c', 'import sys; print(sys.executable)'], {
+        const out = execFileSync(pyExe, [`-${version}`, '-c', 'import sys; print(sys.executable)'], hiddenWindowsChildOptions({
           encoding: 'utf8',
           stdio: ['ignore', 'pipe', 'ignore']
-        })
+        }))
         const candidate = out.trim()
         if (candidate && fileExists(candidate)) return candidate
       } catch {
@@ -1280,11 +1287,11 @@ function resolveUpdateRoot() {
 
 function runGit(args, options = {}) {
   return new Promise((resolve, reject) => {
-    const child = spawn(resolveGitBinary(), IS_WINDOWS ? ['-c', 'windows.appendAtomically=false', ...args] : args, {
+    const child = spawn(resolveGitBinary(), IS_WINDOWS ? ['-c', 'windows.appendAtomically=false', ...args] : args, hiddenWindowsChildOptions({
       cwd: options.cwd,
       env: { ...process.env, ...(options.env || {}), GIT_TERMINAL_PROMPT: '0' },
       stdio: ['ignore', 'pipe', 'pipe']
-    })
+    }))
 
     let stdout = ''
     let stderr = ''
@@ -1494,7 +1501,7 @@ function forceKillProcessTree(pid) {
   if (!IS_WINDOWS) return
   if (!Number.isInteger(pid) || pid <= 0) return
   try {
-    execFileSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' })
+    execFileSync('taskkill', ['/PID', String(pid), '/T', '/F'], hiddenWindowsChildOptions({ stdio: 'ignore' }))
   } catch {
     // Already gone, or no permission — best effort; the unlock wait below is
     // the real gate.
@@ -1680,11 +1687,11 @@ function runStreamedUpdate(command, args, { cwd, env, stage } = {}) {
   return new Promise(resolve => {
     let child
     try {
-      child = spawn(command, args, {
+      child = spawn(command, args, hiddenWindowsChildOptions({
         cwd,
         env: { ...process.env, ...(env || {}) },
         stdio: ['ignore', 'pipe', 'pipe']
-      })
+      }))
     } catch (err) {
       resolve({ code: 1, error: err.message })
       return
@@ -2671,7 +2678,7 @@ function fetchHtmlTitleWithCurl(rawUrl) {
       '--raw',
       url
     ]
-    const child = spawn('curl', args, { stdio: ['ignore', 'pipe', 'ignore'] })
+    const child = spawn('curl', args, hiddenWindowsChildOptions({ stdio: ['ignore', 'pipe', 'ignore'] }))
     const chunks = []
     let bytes = 0
 
@@ -4491,7 +4498,7 @@ async function spawnPoolBackend(profile, entry) {
 
   rememberLog(`Starting Hermes backend for profile "${profile}" via ${backend.label}`)
 
-  const child = spawn(backend.command, backend.args, {
+  const child = spawn(backend.command, backend.args, hiddenWindowsChildOptions({
     cwd: hermesCwd,
     env: {
       ...process.env,
@@ -4509,7 +4516,7 @@ async function spawnPoolBackend(profile, entry) {
     },
     shell: backend.shell,
     stdio: ['ignore', 'pipe', 'pipe']
-  })
+  }))
   entry.process = child
   entry.port = port
   entry.token = token
@@ -4691,7 +4698,7 @@ async function startHermes() {
     await advanceBootProgress('backend.spawn', `Starting Hermes backend via ${backend.label}`, 84)
     rememberLog(`Starting Hermes backend via ${backend.label}`)
 
-    hermesProcess = spawn(backend.command, backend.args, {
+    hermesProcess = spawn(backend.command, backend.args, hiddenWindowsChildOptions({
       cwd: hermesCwd,
       env: {
         ...process.env,
@@ -4714,7 +4721,7 @@ async function startHermes() {
       },
       shell: backend.shell,
       stdio: ['ignore', 'pipe', 'pipe']
-    })
+    }))
 
     hermesProcess.stdout.on('data', rememberLog)
     hermesProcess.stderr.on('data', rememberLog)
@@ -5986,11 +5993,11 @@ async function getUninstallSummary() {
       resolve(value)
     }
     try {
-      const child = spawn(py, ['-m', 'hermes_cli.main', 'uninstall', '--gui-summary'], {
+      const child = spawn(py, ['-m', 'hermes_cli.main', 'uninstall', '--gui-summary'], hiddenWindowsChildOptions({
         cwd: agentRoot,
         env: { ...process.env, HERMES_HOME, NO_COLOR: '1' },
         stdio: ['ignore', 'pipe', 'ignore']
-      })
+      }))
       child.stdout.on('data', chunk => {
         stdout += chunk.toString()
       })

apps/desktop/electron/windows-child-process.test.cjs

@@ -0,0 +1,54 @@
+'use strict'
+
+const test = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const path = require('node:path')
+
+const ELECTRON_DIR = __dirname
+
+function readElectronFile(name) {
+  return fs.readFileSync(path.join(ELECTRON_DIR, name), 'utf8')
+}
+
+function requireHiddenChildOptions(source, needle) {
+  const index = source.indexOf(needle)
+  assert.notEqual(index, -1, `missing call site: ${needle}`)
+  const snippet = source.slice(index, index + 700)
+  assert.match(
+    snippet,
+    /hiddenWindowsChildOptions\(/,
+    `expected ${needle} to wrap child-process options with hiddenWindowsChildOptions`
+  )
+}
+
+test('desktop background child processes opt into hidden Windows consoles', () => {
+  const source = readElectronFile('main.cjs')
+
+  assert.match(source, /function hiddenWindowsChildOptions\(options = \{\}\)/)
+
+  requireHiddenChildOptions(source, "execFileSync(\n          'reg'")
+  requireHiddenChildOptions(source, 'execFileSync(pyExe')
+  requireHiddenChildOptions(source, 'spawn(resolveGitBinary()')
+  requireHiddenChildOptions(source, "execFileSync('taskkill'")
+  requireHiddenChildOptions(source, 'spawn(command, args')
+  requireHiddenChildOptions(source, "spawn('curl'")
+  requireHiddenChildOptions(source, 'spawn(backend.command, backend.args')
+  requireHiddenChildOptions(source, 'hermesProcess = spawn(backend.command, backend.args')
+  requireHiddenChildOptions(source, "spawn(py, ['-m', 'hermes_cli.main', 'uninstall', '--gui-summary']")
+})
+
+test('intentional or interactive desktop child processes stay documented', () => {
+  const source = readElectronFile('main.cjs')
+
+  assert.match(source, /windowsHide: false/)
+  assert.match(source, /nodePty\.spawn\(command, args/)
+  assert.match(source, /spawn\('cmd\.exe', \['\/c', 'start'/)
+})
+
+test('bootstrap PowerShell runner hides Windows console children', () => {
+  const source = readElectronFile('bootstrap-runner.cjs')
+
+  assert.match(source, /function hiddenWindowsChildOptions\(options = \{\}\)/)
+  requireHiddenChildOptions(source, 'spawn(ps, fullArgs')
+})

apps/desktop/package.json

@@ -35,7 +35,7 @@
     "test:desktop:nsis": "node scripts/test-desktop.mjs nsis",
     "test:desktop:existing": "node scripts/test-desktop.mjs existing",
     "test:desktop:fresh": "node scripts/test-desktop.mjs fresh",
-    "test:desktop:platforms": "node --test electron/bootstrap-platform.test.cjs electron/hardening.test.cjs electron/backend-probes.test.cjs electron/bootstrap-runner.test.cjs electron/connection-config.test.cjs electron/gateway-ws-probe.test.cjs electron/oauth-net-request.test.cjs electron/desktop-uninstall.test.cjs electron/session-windows.test.cjs electron/workspace-cwd.test.cjs",
+    "test:desktop:platforms": "node --test electron/bootstrap-platform.test.cjs electron/hardening.test.cjs electron/backend-probes.test.cjs electron/bootstrap-runner.test.cjs electron/connection-config.test.cjs electron/gateway-ws-probe.test.cjs electron/oauth-net-request.test.cjs electron/desktop-uninstall.test.cjs electron/session-windows.test.cjs electron/workspace-cwd.test.cjs electron/windows-child-process.test.cjs",
     "type-check": "tsc -b",
     "lint": "eslint src/ electron/",
     "lint:fix": "eslint src/ electron/ --fix",

apps/desktop/src/app/chat/sidebar/index.tsx

@@ -38,6 +38,7 @@ import { Skeleton } from '@/components/ui/skeleton'
 import { Tip } from '@/components/ui/tooltip'
 import { searchSessions, type SessionInfo, type SessionSearchResult } from '@/hermes'
 import { useI18n } from '@/i18n'
+import { normalizeCombo } from '@/lib/keybinds/combo'
 import { profileColor } from '@/lib/profile-color'
 import { sessionMatchesSearch } from '@/lib/session-search'
 import { normalizeSessionSource, sessionSourceLabel } from '@/lib/session-source'
@@ -111,8 +112,7 @@ const NON_SESSION_LOAD_STEP = 10
 // Render the modifier key the user actually presses on this platform. The
 // global accelerator is bound to both Cmd+N (macOS) and Ctrl+N (everywhere
 // else) in desktop-controller.tsx, but the hint should match muscle memory.
-const NEW_SESSION_KBD: readonly string[] =
-  typeof navigator !== 'undefined' && navigator.platform.toLowerCase().includes('mac') ? ['⌘', 'N'] : ['Ctrl', 'N']
+const NEW_SESSION_KBD: readonly string[] =normalizeCombo('mod+n')
 
 const SIDEBAR_NAV: SidebarNavItem[] = [
   {

apps/desktop/src/app/chat/sidebar/session-row.tsx

@@ -10,6 +10,7 @@ import type { SessionInfo } from '@/hermes'
 import { type Translations, useI18n } from '@/i18n'
 import { sessionTitle } from '@/lib/chat-runtime'
 import { triggerHaptic } from '@/lib/haptics'
+import { modKey } from '@/lib/keybinds/combo'
 import { handoffOriginSource, sessionSourceLabel } from '@/lib/session-source'
 import { cn } from '@/lib/utils'
 import { $attentionSessionIds } from '@/store/session'
@@ -133,11 +134,11 @@ export function SidebarSessionRow({
               return
             }
 
-            // ⌘-click (mac) / ⌃-click (win/linux) pops the chat into its own
+            // ⌘-click (mac) / Ctrl-click (win/linux) pops the chat into its own
             // window — the universal "open in a new window" gesture. Archive
             // lives in the row's ⋯ and right-click menus. Falls through to a
             // normal resume when standalone windows aren't available (web embed).
-            if ((event.metaKey || event.ctrlKey) && canOpenSessionWindow()) {
+            if (event[modKey] && canOpenSessionWindow()) {
               event.preventDefault()
               event.stopPropagation()
               triggerHaptic('selection')

apps/desktop/src/app/desktop-controller.tsx

@@ -91,6 +91,7 @@ import { CommandPalette } from './command-palette'
 import { useGatewayBoot } from './gateway/hooks/use-gateway-boot'
 import { useGatewayRequest } from './gateway/hooks/use-gateway-request'
 import { useKeybinds } from './hooks/use-keybinds'
+import { modKey } from '@/lib/keybinds/combo'
 import { SIDEBAR_COLLAPSE_MEDIA_QUERY } from './layout-constants'
 import { ModelPickerOverlay } from './model-picker-overlay'
 import { ModelVisibilityOverlay } from './model-visibility-overlay'
@@ -271,7 +272,7 @@ export function DesktopController() {
         return
       }
 
-      if ((event.metaKey || event.ctrlKey) && !event.altKey && !event.shiftKey && event.key.toLowerCase() === 'w') {
+      if (event[modKey] && !event.altKey && !event.shiftKey && event.key.toLowerCase() === 'w') {
         event.preventDefault()
         event.stopPropagation()
         closeActiveRightRailTab()

apps/desktop/src/app/right-sidebar/terminal/index.tsx

@@ -69,7 +69,7 @@ export function TerminalTab({ cwd, onAddSelectionToChat }: TerminalTabProps) {
               variant="secondary"
             >
               {t.rightSidebar.addToChat}
-              <span className="ml-1 text-[0.6rem] text-(--ui-text-tertiary)">{addSelectionShortcutLabel()}</span>
+              <span className="ml-1 text-[0.6rem] text-(--ui-text-tertiary)">{addSelectionShortcutLabel}</span>
             </Button>
           </div>
         )}

apps/desktop/src/app/right-sidebar/terminal/selection.ts

@@ -1,6 +1,7 @@
 import type { ITheme, Terminal } from '@xterm/xterm'
 import type { CSSProperties } from 'react'
 
+import { formatCombo, modKey } from '@/lib/keybinds/combo'
 import type { DesktopTerminalPalette } from '@/themes/types'
 
 // VS Code's default integrated-terminal palette (terminalColorRegistry.ts) — a
@@ -97,12 +98,10 @@ export function resolveSurfaceColor(fallback: string): string {
   return resolved && resolved !== 'rgba(0, 0, 0, 0)' ? resolved : fallback
 }
 
-export const isMacPlatform = () => navigator.platform.toLowerCase().includes('mac')
-
-export const addSelectionShortcutLabel = () => (isMacPlatform() ? '⌘L' : 'Ctrl+L')
+export const addSelectionShortcutLabel = formatCombo('mod+l')
 
 export function isAddSelectionShortcut(event: KeyboardEvent) {
-  const mod = isMacPlatform() ? event.metaKey : event.ctrlKey
+  const mod = event[modKey]
 
   return mod && !event.shiftKey && event.key.toLowerCase() === 'l'
 }

apps/desktop/src/app/shell/keybind-panel.tsx

@@ -14,7 +14,7 @@ import {
   type KeybindActionMeta,
   type KeybindReadonly
 } from '@/lib/keybinds/actions'
-import { formatCombo } from '@/lib/keybinds/combo'
+import { formatCombo, formatFakeCombo } from '@/lib/keybinds/combo'
 import { arraysEqual } from '@/lib/storage'
 import {
   $bindings,
@@ -210,7 +210,7 @@ function ReadonlyRow({ shortcut }: { shortcut: KeybindReadonly }) {
       <div className="flex shrink-0 items-center gap-1">
         {shortcut.keys.map(key => (
           <span className="kbd-cap" key={key}>
-            {formatCombo(key)}
+            {formatFakeCombo(key)}
           </span>
         ))}
       </div>

apps/desktop/src/components/assistant-ui/thread.tsx

@@ -722,8 +722,14 @@ function StickyHumanMessageContainer({ children }: { children: ReactNode }) {
 // edit composer render the same bubble surface (rounded glass card);
 // they only differ in border weight, cursor, and padding-right (the
 // read-only view reserves room for the restore icon).
+//
+// no-drag: sticky bubbles park at --sticky-human-top (~4px), sliding under the
+// titlebar's [-webkit-app-region:drag] strips (app-shell.tsx). Electron resolves
+// drag regions at the compositor level — z-index and pointer-events don't help —
+// so without the carve-out, clicking a stuck bubble drags the window instead of
+// opening the edit composer.
 const USER_BUBBLE_BASE_CLASS =
-  'composer-human-message standalone-glass relative flex w-full min-w-0 max-w-full flex-col gap-1.5 overflow-hidden rounded-xl border bg-(--dt-user-bubble) px-3 py-2 text-left'
+  'composer-human-message standalone-glass relative flex w-full min-w-0 max-w-full flex-col gap-1.5 overflow-hidden rounded-xl border bg-(--dt-user-bubble) px-3 py-2 text-left [-webkit-app-region:no-drag]'
 
 const USER_ACTION_ICON_BUTTON_CLASS =
   'grid place-items-center rounded-md bg-transparent text-(--ui-text-secondary) transition-colors hover:bg-(--ui-control-active-background) hover:text-foreground disabled:cursor-default disabled:text-(--ui-text-quaternary) disabled:opacity-70'

apps/desktop/src/components/assistant-ui/tool-approval.tsx

@@ -16,6 +16,7 @@ import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigge
 import { useI18n } from '@/i18n'
 import { triggerHaptic } from '@/lib/haptics'
 import { ChevronDown, Loader2 } from '@/lib/icons'
+import { formatCombo } from '@/lib/keybinds/combo'
 import { $gateway } from '@/store/gateway'
 import { notifyError } from '@/store/notifications'
 import { $approvalRequest, type ApprovalRequest, clearApprovalRequest } from '@/store/prompts'
@@ -50,8 +51,6 @@ export const PendingToolApproval: FC<{ part: ToolPart }> = ({ part }) => {
   return <ApprovalBar request={request} />
 }
 
-const isMac = typeof navigator !== 'undefined' && /Mac|iP(hone|ad|od)/.test(navigator.platform)
-
 const ApprovalBar: FC<{ request: ApprovalRequest }> = ({ request }) => {
   const { t } = useI18n()
   const copy = t.assistant.approval
@@ -127,7 +126,7 @@ const ApprovalBar: FC<{ request: ApprovalRequest }> = ({ request }) => {
           variant="ghost"
         >
           {submitting === 'once' ? <Loader2 className="size-3 animate-spin" /> : copy.run}
-          {submitting !== 'once' && <span className="text-[0.625rem] text-primary/60">{isMac ? '⌘⏎' : 'Ctrl⏎'}</span>}
+          {submitting !== 'once' && <span className="text-[0.625rem] text-primary/60">{formatCombo('mod+enter')}</span>}
         </Button>
         <span aria-hidden className="w-px self-stretch bg-primary/20" />
         <DropdownMenu>

apps/desktop/src/components/assistant-ui/tool-fallback.tsx

@@ -13,9 +13,9 @@ import { DisclosureRow } from '@/components/chat/disclosure-row'
 import { PreviewAttachment } from '@/components/chat/preview-attachment'
 import { ZoomableImage } from '@/components/chat/zoomable-image'
 import { BrailleSpinner } from '@/components/ui/braille-spinner'
-import { Codicon } from '@/components/ui/codicon'
 import { CopyButton } from '@/components/ui/copy-button'
 import { FadeText } from '@/components/ui/fade-text'
+import { ToolIcon } from '@/components/ui/tool-icon'
 import { useI18n } from '@/i18n'
 import { PrettyLink, LinkifiedText as SharedLinkifiedText, urlSlugTitleLabel } from '@/lib/external-link'
 import { AlertCircle, CheckCircle2 } from '@/lib/icons'
@@ -136,7 +136,7 @@ function ToolGlyph({ copy, icon, status }: { copy: ToolStatusCopy; icon?: string
   const node = status ? (
     statusGlyph(status, copy)
   ) : icon ? (
-    <Codicon className="text-(--ui-text-tertiary)" name={icon} size="0.875rem" />
+    <ToolIcon className="text-(--ui-text-tertiary)" name={icon} size="0.875rem" />
   ) : null
 
   return node ? <span className={TOOL_HEADER_GLYPH_WRAP_CLASS}>{node}</span> : null

apps/desktop/src/components/assistant-ui/user-message-edit.test.tsx

@@ -0,0 +1,141 @@
+import { ExportedMessageRepository } from '@assistant-ui/core/internal'
+// Clicking a user bubble must open the inline edit composer — through the
+// app's incremental external-store runtime (which reimplements capability
+// resolution, incl. `edit: onEdit !== undefined`) and the stock runtime.
+//
+// Note: this covers the React/runtime wiring only. The Electron-level failure
+// mode (titlebar -webkit-app-region:drag swallowing clicks on *stuck* sticky
+// bubbles) is not reproducible in jsdom — see USER_BUBBLE_BASE_CLASS's no-drag
+// carve-out in thread.tsx.
+import { AssistantRuntimeProvider, type ThreadMessage, useExternalStoreRuntime } from '@assistant-ui/react'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+
+import { useIncrementalExternalStoreRuntime } from '@/lib/incremental-external-store-runtime'
+
+import { Thread } from './thread'
+
+const createdAt = new Date('2026-05-01T00:00:00.000Z')
+
+class TestResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+vi.stubGlobal('ResizeObserver', TestResizeObserver)
+vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
+  window.setTimeout(() => callback(performance.now()), 0)
+)
+vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
+
+Element.prototype.scrollTo = function scrollTo() {}
+
+function stubOffsetDimension(
+  prop: 'offsetHeight' | 'offsetWidth',
+  clientProp: 'clientHeight' | 'clientWidth',
+  fallback: number
+) {
+  const previous = Object.getOwnPropertyDescriptor(HTMLElement.prototype, prop)
+
+  Object.defineProperty(HTMLElement.prototype, prop, {
+    configurable: true,
+    get() {
+      return previous?.get?.call(this) || (this as HTMLElement)[clientProp] || fallback
+    }
+  })
+}
+
+stubOffsetDimension('offsetWidth', 'clientWidth', 800)
+stubOffsetDimension('offsetHeight', 'clientHeight', 600)
+
+function userMessage(): ThreadMessage {
+  return {
+    id: 'user-1',
+    role: 'user',
+    content: [{ type: 'text', text: 'edit me please' }],
+    attachments: [],
+    createdAt,
+    metadata: { custom: {} }
+  } as ThreadMessage
+}
+
+function assistantMessage(): ThreadMessage {
+  return {
+    id: 'assistant-1',
+    role: 'assistant',
+    content: [{ type: 'text', text: 'done' }],
+    status: { type: 'complete', reason: 'stop' },
+    createdAt,
+    metadata: {
+      unstable_state: null,
+      unstable_annotations: [],
+      unstable_data: [],
+      steps: [],
+      custom: {}
+    }
+  } as ThreadMessage
+}
+
+// Mirrors chat/index.tsx: incremental runtime + messageRepository + onEdit.
+function IncrementalHarness({ onEdit }: { onEdit: () => Promise<void> }) {
+  const repository = ExportedMessageRepository.fromArray([userMessage(), assistantMessage()])
+
+  const runtime = useIncrementalExternalStoreRuntime<ThreadMessage>({
+    messageRepository: repository,
+    isRunning: false,
+    setMessages: () => {},
+    onNew: async () => {},
+    onEdit,
+    onCancel: async () => {},
+    onReload: async () => {}
+  })
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  )
+}
+
+// Control: stock external store runtime.
+function StockHarness({ onEdit }: { onEdit: () => Promise<void> }) {
+  const runtime = useExternalStoreRuntime<ThreadMessage>({
+    messages: [userMessage(), assistantMessage()],
+    isRunning: false,
+    onNew: async () => {},
+    onEdit
+  })
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  )
+}
+
+describe('click-to-edit user message', () => {
+  it('opens the edit composer with the incremental runtime', async () => {
+    const { container } = render(<IncrementalHarness onEdit={async () => {}} />)
+
+    const bubble = await screen.findByRole('button', { name: 'Edit message' })
+
+    fireEvent.click(bubble)
+
+    await waitFor(() => {
+      expect(container.querySelector('[data-slot="aui_edit-composer-root"]')).toBeTruthy()
+    })
+  })
+
+  it('opens the edit composer with the stock runtime', async () => {
+    const { container } = render(<StockHarness onEdit={async () => {}} />)
+
+    const bubble = await screen.findByRole('button', { name: 'Edit message' })
+
+    fireEvent.click(bubble)
+
+    await waitFor(() => {
+      expect(container.querySelector('[data-slot="aui_edit-composer-root"]')).toBeTruthy()
+    })
+  })
+})

apps/desktop/src/components/ui/tool-icon.tsx

@@ -0,0 +1,65 @@
+import type * as React from 'react'
+
+import { Codicon } from '@/components/ui/codicon'
+import { cn } from '@/lib/utils'
+
+// Solid (filled) glyphs for in-thread tool rows. Codicons are an outline icon
+// *font*, so an outline glyph has no separate fillable region — a filled look
+// can't be derived from it (stroke-thickening just bolds the outline). To get
+// the Cursor-style filled tool icons we render dedicated solid SVG paths,
+// keyed by the same names used in `TOOL_META` (tool-fallback-model.ts).
+//
+// Paths are Phosphor Icons (MIT) "fill" weight, 256×256 viewBox. Inlining the
+// path data mirrors the existing precedent in `directive-text.tsx`.
+const TOOL_ICON_PATHS: Record<string, string> = {
+  diff: 'M118.18,213.08c-.11.14-.24.27-.36.4l-.16.18-.17.15a4.83,4.83,0,0,1-.42.37,3.92,3.92,0,0,1-.32.25l-.3.22-.38.23a2.91,2.91,0,0,1-.3.17l-.37.19-.34.15-.36.13a2.84,2.84,0,0,1-.38.13l-.36.1c-.14,0-.26.07-.4.09l-.42.07-.35.05a7,7,0,0,1-.79,0H64a8,8,0,0,1,0-16H92.69L55,162.34a23.85,23.85,0,0,1-7-17V95a32,32,0,1,1,16,0v50.38A8,8,0,0,0,66.34,151L104,188.69V160a8,8,0,0,1,16,0v48a7,7,0,0,1,0,.8c0,.11,0,.21,0,.32s0,.3-.07.46a2.83,2.83,0,0,1-.09.37c0,.13-.06.26-.1.39s-.08.23-.12.35l-.14.39-.15.31c-.06.13-.12.27-.19.4s-.11.18-.16.28l-.24.39-.21.28ZM208,161V110.63a23.85,23.85,0,0,0-7-17L163.31,56H192a8,8,0,0,0,0-16H143.82l-.6,0c-.14,0-.28,0-.41.06l-.37,0-.43.11-.33.08-.4.14-.34.13-.35.16-.36.18a3.14,3.14,0,0,0-.31.18c-.12.07-.25.14-.36.22a3.55,3.55,0,0,0-.31.23,3.81,3.81,0,0,0-.32.24c-.15.12-.28.24-.42.37l-.17.15-.16.18c-.12.13-.25.26-.36.4l-.26.35-.21.28-.24.39c-.05.1-.11.19-.16.28s-.13.27-.19.4l-.15.31-.14.39c0,.12-.09.23-.12.35s-.07.26-.1.39a2.83,2.83,0,0,0-.09.37c0,.16,0,.31-.07.46s0,.21-.05.32a7,7,0,0,0,0,.8V96a8,8,0,0,0,16,0V67.31L189.66,105a8,8,0,0,1,2.34,5.66V161a32,32,0,1,0,16,0Z',
+  edit: 'M227.31,73.37,182.63,28.68a16,16,0,0,0-22.63,0L36.69,152A15.86,15.86,0,0,0,32,163.31V208a16,16,0,0,0,16,16H92.69A15.86,15.86,0,0,0,104,219.31L227.31,96a16,16,0,0,0,0-22.63ZM192,108.68,147.31,64l24-24L216,84.68Z',
+  eye: 'M247.31,124.76c-.35-.79-8.82-19.58-27.65-38.41C194.57,61.26,162.88,48,128,48S61.43,61.26,36.34,86.35C17.51,105.18,9,124,8.69,124.76a8,8,0,0,0,0,6.5c.35.79,8.82,19.57,27.65,38.4C61.43,194.74,93.12,208,128,208s66.57-13.26,91.66-38.34c18.83-18.83,27.3-37.61,27.65-38.4A8,8,0,0,0,247.31,124.76ZM128,168a40,40,0,1,1,40-40A40,40,0,0,1,128,168Z',
+  file: 'M213.66,82.34l-56-56A8,8,0,0,0,152,24H56A16,16,0,0,0,40,40V216a16,16,0,0,0,16,16H200a16,16,0,0,0,16-16V88A8,8,0,0,0,213.66,82.34ZM152,88V44l44,44Z',
+  'file-media':
+    'M216,40H40A16,16,0,0,0,24,56V200a16,16,0,0,0,16,16H216a16,16,0,0,0,16-16V56A16,16,0,0,0,216,40ZM156,88a12,12,0,1,1-12,12A12,12,0,0,1,156,88Zm60,112H40V160.69l46.34-46.35a8,8,0,0,1,11.32,0h0L165,181.66a8,8,0,0,0,11.32-11.32l-17.66-17.65L173,138.34a8,8,0,0,1,11.31,0L216,170.07V200Z',
+  files:
+    'M213.66,66.34l-40-40A8,8,0,0,0,168,24H88A16,16,0,0,0,72,40V56H56A16,16,0,0,0,40,72V216a16,16,0,0,0,16,16H168a16,16,0,0,0,16-16V200h16a16,16,0,0,0,16-16V72A8,8,0,0,0,213.66,66.34ZM136,192H88a8,8,0,0,1,0-16h48a8,8,0,0,1,0,16Zm0-32H88a8,8,0,0,1,0-16h48a8,8,0,0,1,0,16Zm64,24H184V104a8,8,0,0,0-2.34-5.66l-40-40A8,8,0,0,0,136,56H88V40h76.69L200,75.31Z',
+  globe:
+    'M128,24h0A104,104,0,1,0,232,128,104.12,104.12,0,0,0,128,24Zm78.36,64H170.71a135.28,135.28,0,0,0-22.3-45.6A88.29,88.29,0,0,1,206.37,88ZM216,128a87.61,87.61,0,0,1-3.33,24H174.16a157.44,157.44,0,0,0,0-48h38.51A87.61,87.61,0,0,1,216,128ZM128,43a115.27,115.27,0,0,1,26,45H102A115.11,115.11,0,0,1,128,43ZM102,168H154a115.11,115.11,0,0,1-26,45A115.27,115.27,0,0,1,102,168Zm-3.9-16a140.84,140.84,0,0,1,0-48h59.88a140.84,140.84,0,0,1,0,48Zm50.35,61.6a135.28,135.28,0,0,0,22.3-45.6h35.66A88.29,88.29,0,0,1,148.41,213.6Z',
+  question:
+    'M128,24A104,104,0,1,0,232,128,104.11,104.11,0,0,0,128,24Zm0,168a12,12,0,1,1,12-12A12,12,0,0,1,128,192Zm8-48.72V144a8,8,0,0,1-16,0v-8a8,8,0,0,1,8-8c13.23,0,24-9,24-20s-10.77-20-24-20-24,9-24,20v4a8,8,0,0,1-16,0v-4c0-19.85,17.94-36,40-36s40,16.15,40,36C168,125.38,154.24,139.93,136,143.28Z',
+  search:
+    'M168,112a56,56,0,1,1-56-56A56,56,0,0,1,168,112Zm61.66,117.66a8,8,0,0,1-11.32,0l-50.06-50.07a88,88,0,1,1,11.32-11.31l50.06,50.06A8,8,0,0,1,229.66,229.66ZM112,184a72,72,0,1,0-72-72A72.08,72.08,0,0,0,112,184Z',
+  terminal:
+    'M216,40H40A16,16,0,0,0,24,56V200a16,16,0,0,0,16,16H216a16,16,0,0,0,16-16V56A16,16,0,0,0,216,40Zm-91,94.25-40,32a8,8,0,1,1-10-12.5L107.19,128,75,102.25a8,8,0,1,1,10-12.5l40,32a8,8,0,0,1,0,12.5ZM176,168H136a8,8,0,0,1,0-16h40a8,8,0,0,1,0,16Z',
+  tools:
+    'M232,96a72,72,0,0,1-100.94,66L79,222.22c-.12.14-.26.29-.39.42a32,32,0,0,1-45.26-45.26c.14-.13.28-.27.43-.39L94,124.94a72.07,72.07,0,0,1,83.54-98.78,8,8,0,0,1,3.93,13.19L144,80l5.66,26.35L176,112l40.65-37.52a8,8,0,0,1,13.19,3.93A72.6,72.6,0,0,1,232,96Z',
+  watch:
+    'M128,24A104,104,0,1,0,232,128,104.11,104.11,0,0,0,128,24Zm56,112H128a8,8,0,0,1-8-8V72a8,8,0,0,1,16,0v48h48a8,8,0,0,1,0,16Z'
+}
+
+export interface ToolIconProps {
+  className?: string
+  name: string
+  size?: number | string
+}
+
+/** Filled tool glyph. Falls back to the outline codicon font for any name not
+ *  covered by the solid set so new tools still render an icon. */
+export function ToolIcon({ className, name, size = '0.875rem' }: ToolIconProps) {
+  const path = TOOL_ICON_PATHS[name]
+
+  if (!path) {
+    return <Codicon className={className} name={name} size={size} />
+  }
+
+  const dimension: React.CSSProperties = { height: size, width: size }
+
+  return (
+    <svg
+      aria-hidden="true"
+      className={cn('shrink-0', className)}
+      fill="currentColor"
+      style={dimension}
+      viewBox="0 0 256 256"
+    >
+      <path d={path} />
+    </svg>
+  )
+}

apps/desktop/src/i18n/en.ts

@@ -1,4 +1,5 @@
 import { FIELD_DESCRIPTIONS, FIELD_LABELS } from '@/app/settings/constants'
+import { formatCombo } from '@/lib/keybinds/combo'
 
 import type { Translations } from './types'
 
@@ -518,7 +519,7 @@ export const en: Translations = {
       loading: 'Loading archived sessions…',
       archivedTitle: 'Archived sessions',
       archivedIntro:
-        'Archived chats are hidden from the sidebar but keep all their messages. Ctrl/⌘-click a chat in the sidebar to archive it.',
+        `Archived chats are hidden from the sidebar but keep all their messages. ${formatCombo('mod')}-click a chat in the sidebar to archive it.`,
       emptyArchivedTitle: 'Nothing archived',
       emptyArchivedDesc: 'Archive a chat to hide it here.',
       unarchive: 'Unarchive',
@@ -529,7 +530,7 @@ export const en: Translations = {
       defaultDirTitle: 'Default project directory',
       defaultDirDesc:
         'New sessions start in this folder unless you pick another. Leave it unset to use your home directory.',
-      defaultDirUpdated: 'Default project directory updated — start a new chat (Ctrl/⌘+N) for it to take effect',
+      defaultDirUpdated: `Default project directory updated — start a new chat (${formatCombo('mod+n')}) for it to take effect`,
       defaultsTo: label => `Defaults to ${label}.`,
       change: 'Change',
       choose: 'Choose',
@@ -1677,7 +1678,7 @@ export const en: Translations = {
       loadingQuestion: 'Loading question…',
       other: 'Other (type your answer)',
       placeholder: 'Type your answer…',
-      shortcut: '⌘/Ctrl + Enter to send',
+      shortcut: `${formatCombo('mod+enter')} to send`,
       back: 'Back',
       skip: 'Skip',
       send: 'Send'

apps/desktop/src/i18n/ja.ts

@@ -1,4 +1,5 @@
 import { defineFieldCopy } from '@/app/settings/field-copy'
+import { formatCombo } from '@/lib/keybinds/combo'
 
 import { defineLocale } from './define-locale'
 
@@ -642,7 +643,7 @@ export const ja = defineLocale({
       loading: 'アーカイブ済みセッションを読み込み中…',
       archivedTitle: 'アーカイブ済みセッション',
       archivedIntro:
-        'アーカイブ済みチャットはサイドバーでは非表示になりますが、すべてのメッセージは保持されます。サイドバーのチャットを Ctrl/⌘ クリックするとアーカイブできます。',
+        `アーカイブ済みチャットはサイドバーでは非表示になりますが、すべてのメッセージは保持されます。サイドバーのチャットを ${formatCombo('mod')} クリックするとアーカイブできます。`,
       emptyArchivedTitle: 'アーカイブがありません',
       emptyArchivedDesc: 'チャットをアーカイブするとここに表示されます。',
       unarchive: 'アーカイブを解除',
@@ -1811,7 +1812,7 @@ export const ja = defineLocale({
       loadingQuestion: '質問を読み込み中…',
       other: 'その他（回答を入力）',
       placeholder: '回答を入力…',
-      shortcut: '⌘/Ctrl + Enter で送信',
+      shortcut: `${formatCombo('mod+enter')} で送信`,
       back: '戻る',
       skip: 'スキップ',
       send: '送信'

apps/desktop/src/i18n/zh-hant.ts

@@ -1,4 +1,5 @@
 import { defineFieldCopy } from '@/app/settings/field-copy'
+import { formatCombo } from '@/lib/keybinds/combo'
 
 import { defineLocale } from './define-locale'
 
@@ -627,7 +628,7 @@ export const zhHant = defineLocale({
       loading: '正在載入已封存工作階段…',
       archivedTitle: '已封存工作階段',
       archivedIntro:
-        '已封存的聊天會從側邊欄隱藏，但保留全部訊息。在側邊欄 Ctrl/⌘ 點擊聊天即可封存。',
+        `已封存的聊天會從側邊欄隱藏，但保留全部訊息。在側邊欄 ${formatCombo('mod')} 點擊聊天即可封存。`,
       emptyArchivedTitle: '暫無封存',
       emptyArchivedDesc: '封存一個聊天後會顯示在這裡。',
       unarchive: '取消封存',
@@ -1772,7 +1773,7 @@ export const zhHant = defineLocale({
       loadingQuestion: '正在載入問題…',
       other: '其他（輸入您的答案）',
       placeholder: '輸入您的答案…',
-      shortcut: '⌘/Ctrl + Enter 傳送',
+      shortcut: `${formatCombo('mod+enter')} 傳送`,
       back: '返回',
       skip: '略過',
       send: '傳送'

apps/desktop/src/i18n/zh.ts

@@ -1,4 +1,5 @@
 import { defineFieldCopy } from '@/app/settings/field-copy'
+import { formatCombo } from '@/lib/keybinds/combo'
 
 import type { Translations } from './types'
 
@@ -712,7 +713,7 @@ export const zh: Translations = {
     sessions: {
       loading: '正在加载已归档会话…',
       archivedTitle: '已归档会话',
-      archivedIntro: '已归档对话会从侧边栏隐藏，但会保留全部消息。在侧边栏 Ctrl/⌘ 点击对话即可归档。',
+      archivedIntro: `已归档对话会从侧边栏隐藏，但会保留全部消息。在侧边栏 ${formatCombo('mod')} 点击对话即可归档。`,
       emptyArchivedTitle: '暂无归档',
       emptyArchivedDesc: '归档一个对话后会显示在这里。',
       unarchive: '取消归档',
@@ -1856,7 +1857,7 @@ export const zh: Translations = {
       loadingQuestion: '正在加载问题…',
       other: '其他 (输入你的答案)',
       placeholder: '输入你的答案…',
-      shortcut: '⌘/Ctrl + Enter 发送',
+      shortcut: `${formatCombo('mod+enter')} 发送`,
       back: '返回',
       skip: '跳过',
       send: '发送'

apps/desktop/src/lib/keybinds/actions.ts

@@ -5,6 +5,9 @@
 // like navigate / theme); labels come from i18n (`t.keybinds.actions[id]`). To
 // add a hotkey, add a row here and a handler there — nothing else.
 
+import type { Combo, FakeCombo } from "./combo";
+
+
 export type KeybindCategory = 'composer' | 'profiles' | 'session' | 'navigation' | 'view'
 
 // The self-referential opener — bound + dispatched like any action, but shown in
@@ -27,15 +30,16 @@ export interface KeybindActionMeta {
 // `profile.default`) — ⌘` is macOS-reserved (window cycling) and ⌘0 is reset-zoom.
 export const PROFILE_SLOT_COUNT = 18
 
-function comboForSlot(slot: number): string {
-  return slot <= 9 ? `mod+${slot}` : `mod+alt+${slot - 9}`
-}
+const PROFILE_SWITCH_ACTIONS: KeybindActionMeta[] = Array.from({ length: PROFILE_SLOT_COUNT }, (_, i) => {
+  const slot = i+1
+  const combo = (slot <= 9 ? `mod+${slot}` : `mod+alt+${slot - 9}`) as Combo
 
-const PROFILE_SWITCH_ACTIONS: KeybindActionMeta[] = Array.from({ length: PROFILE_SLOT_COUNT }, (_, i) => ({
-  id: `profile.switch.${i + 1}`,
-  category: 'profiles' as const,
-  defaults: [comboForSlot(i + 1)]
-}))
+  return ({
+    id: `profile.switch.${i + 1}`,
+    category: 'profiles' as const,
+    defaults: [combo]
+  })
+})
 
 // ⌘` on macOS / Ctrl+` elsewhere (the `~` key), plus the Shift/tilde variant.
 // `mod` keeps one binding cross-platform; on macOS this shadows the system
@@ -104,10 +108,12 @@ export function keybindAction(id: string): KeybindActionMeta | undefined {
   return ACTION_BY_ID.get(id)
 }
 
-export type KeybindBindings = Record<string, string[]>
+export type KeybindBindings = Record<string, Combo[]>
 
 export function defaultBindings(): KeybindBindings {
-  return Object.fromEntries(KEYBIND_ACTIONS.map(action => [action.id, [...action.defaults]]))
+  return Object.fromEntries<string, Combo[]>(
+    KEYBIND_ACTIONS.map(action => [action.id, [...action.defaults] as Combo[]])
+  )
 }
 
 // Fixed, non-rebindable shortcuts surfaced read-only in the panel so the map is
@@ -117,7 +123,7 @@ export function defaultBindings(): KeybindBindings {
 export interface KeybindReadonly {
   id: string
   category: KeybindCategory
-  keys: readonly string[]
+  keys: readonly FakeCombo[]
 }
 
 export const KEYBIND_READONLY: readonly KeybindReadonly[] = [

apps/desktop/src/lib/keybinds/combo.ts

@@ -10,11 +10,13 @@
 // Control+Tab. Off macOS, Control already *is* `mod`, so `canonicalizeCombo`
 // folds `ctrl` → `mod`.
 
-export const IS_MAC = typeof navigator !== 'undefined' && /mac/i.test(navigator.platform || navigator.userAgent || '')
+const IS_MAC = typeof navigator !== 'undefined' && /mac/i.test(navigator.platform || navigator.userAgent || '')
+
+export const modKey = IS_MAC ? 'metaKey' as const : 'ctrlKey' as const
 
 // event.code → canonical base token. Letters/digits map to their lowercase
 // character; everything else uses an explicit name so combos read cleanly.
-const CODE_TO_KEY: Record<string, string> = {
+const CODE_TO_KEY = {
   Backquote: '`',
   Backslash: '\\',
   BracketLeft: '[',
@@ -35,8 +37,50 @@ const CODE_TO_KEY: Record<string, string> = {
   ArrowDown: 'down',
   ArrowLeft: 'left',
   ArrowRight: 'right'
+} as const satisfies Record<Capitalize<string>, Lowercase<string>>
+
+type SpecialKey = typeof CODE_TO_KEY[keyof typeof CODE_TO_KEY]
+
+type Alpha = 'a'|'b'|'c'|'d'|'e'|'f'|'g'|'h'|'i'|'j'|'k'|'l'|'m'
+           | 'n'|'o'|'p'|'q'|'r'|'s'|'t'|'u'|'v'|'w'|'x'|'y'|'z'
+
+export type Digit = '0'|'1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9'
+
+
+type FKey =
+| 'f1' | 'f2' | 'f3' | 'f4' | 'f5' | 'f6'
+| 'f7' | 'f8' | 'f9' | 'f10' | 'f11' | 'f12'
+| 'f13' | 'f14' | 'f15' | 'f16' | 'f17' | 'f18'
+| 'f19' | 'f20' | 'f21' | 'f22' | 'f23' | 'f24'
+
+type BaseKey = Alpha | Digit | FKey | SpecialKey
+
+// subset of https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values
+type KeyCode = Uppercase<FKey> | `Digit${Digit}` | `Key${Uppercase<Alpha>}` | keyof typeof CODE_TO_KEY
+
+function baseKeyFromCode(code: KeyCode): BaseKey | null {
+  if (code.startsWith('Key')) {
+    return code.slice(3).toLowerCase() as Alpha
+  }
+
+  if (code.startsWith('Digit')) {
+    return code.slice(5) as Digit
+  }
+
+  if (code.startsWith('Numpad')) {
+    const rest = code.slice(6)
+
+    return /^[0-9]$/.test(rest) ? rest as Digit : null
+  }
+
+  if (code.startsWith('F') && /^F\d{1,2}$/.test(code)) {
+    return code.toLowerCase() as FKey
+  }
+
+  return CODE_TO_KEY[code as keyof typeof CODE_TO_KEY] ?? null
 }
 
+
 const MODIFIER_CODES = new Set([
   'AltLeft',
   'AltRight',
@@ -48,42 +92,20 @@ const MODIFIER_CODES = new Set([
   'ShiftRight'
 ])
 
-function baseKeyFromCode(code: string): string | null {
-  if (code.startsWith('Key')) {
-    return code.slice(3).toLowerCase()
-  }
-
-  if (code.startsWith('Digit')) {
-    return code.slice(5)
-  }
-
-  if (code.startsWith('Numpad')) {
-    const rest = code.slice(6)
-
-    return /^[0-9]$/.test(rest) ? rest : null
-  }
-
-  if (code.startsWith('F') && /^F\d{1,2}$/.test(code)) {
-    return code.toLowerCase()
-  }
-
-  return CODE_TO_KEY[code] ?? null
-}
-
 // Returns the canonical combo for a keydown, or null while only modifiers are
 // held (so capture mode keeps waiting for a real key).
-export function comboFromEvent(event: KeyboardEvent): string | null {
+export function comboFromEvent(event: KeyboardEvent): Combo | null {
   if (MODIFIER_CODES.has(event.code)) {
     return null
   }
 
-  const base = baseKeyFromCode(event.code)
+  const base = baseKeyFromCode(event.code as KeyCode)
 
   if (!base) {
     return null
   }
 
-  const parts: string[] = []
+  const parts: Combo[] = []
 
   // macOS reports Cmd (`mod`) and Control (`ctrl`) separately; elsewhere
   // Control IS the accelerator, so it folds into `mod`.
@@ -105,7 +127,7 @@ export function comboFromEvent(event: KeyboardEvent): string | null {
 
   parts.push(base)
 
-  return parts.join('+')
+  return parts.join('+') as Combo
 }
 
 // Rewrites a binding to the form `comboFromEvent` emits, so it indexes under
@@ -115,7 +137,14 @@ export function canonicalizeCombo(combo: string): string {
   return IS_MAC ? combo : combo.replace(/\bctrl\b/g, 'mod')
 }
 
-const TOKEN_LABELS: Record<string, string> = {
+const MOD_LABELS = {
+  mod: IS_MAC ? '⌘' : 'Ctrl',
+  ctrl: IS_MAC ? '⌃' : 'Ctrl',
+  alt: IS_MAC ? '⌥' : 'Alt',
+  shift: IS_MAC ? '⇧' : 'Shift'
+} as const
+
+const FANCY_KEY_LABELS = {
   enter: '↵',
   escape: 'Esc',
   backspace: '⌫',
@@ -124,39 +153,47 @@ const TOKEN_LABELS: Record<string, string> = {
   up: '↑',
   down: '↓',
   left: '←',
-  right: '→'
+  right: '→',
+} as const
+
+const TOKEN_LABELS: Record<string, string> = {
+  ...MOD_LABELS,
+  ...FANCY_KEY_LABELS
 }
 
-function labelForBase(base: string): string {
-  if (TOKEN_LABELS[base]) {
-    return TOKEN_LABELS[base]
+function labelForToken(token: string): string {
+  if (TOKEN_LABELS[token]) {
+    return TOKEN_LABELS[token]
   }
 
-  if (/^f\d{1,2}$/.test(base)) {
-    return base.toUpperCase()
+  if (/^f\d{1,2}$/.test(token)) {
+    return token.toUpperCase()
   }
 
-  return base.length === 1 ? base.toUpperCase() : base
+  return token.length === 1 ? token.toUpperCase() : token
 }
 
-function labelForMod(mod: string): string {
-  if (mod === 'mod') {
-    return IS_MAC ? '⌘' : 'Ctrl'
-  }
+//
 
-  if (mod === 'ctrl') {
-    return IS_MAC ? '⌃' : 'Ctrl'
-  }
+type ModKey = keyof typeof MOD_LABELS
 
-  if (mod === 'alt') {
-    return IS_MAC ? '⌥' : 'Alt'
-  }
+type ModPrefix = `${'mod+'|''}${'alt+'|''}${'shift+'|''}`
 
-  if (mod === 'shift') {
-    return IS_MAC ? '⇧' : 'Shift'
-  }
+type ModPrefixedCombo<Suffix extends string> =
+  | `${ModPrefix}${Suffix}`
+  | ModKey
+  | 'mod+alt' | 'mod+shift' | 'alt+shift' | 'mod+alt+shift'
+  | 'ctrl+tab' | 'ctrl+shift+tab'
+  | `ctrl+${Digit}`
 
-  return mod
+export type Combo = ModPrefixedCombo<BaseKey>
+export type FakeCombo = ModPrefixedCombo<BaseKey | '@' | '?'>
+
+// Human-readable keys, e.g. "mod+shift+k" returns ["⌘","⇧","K"] on macos, ["Ctrl","Shift","K"] elsewhere.
+export function normalizeCombo(combo: Combo): string[] {
+  const parts = combo.split('+')
+
+  return parts.map(p => labelForToken(p.trim()))
 }
 
 // Per-key display tokens, e.g. ["⌘", "K"] on macOS, ["Ctrl", "K"] elsewhere —
@@ -165,14 +202,18 @@ export function comboTokens(combo: string): string[] {
   const parts = combo.split('+')
   const base = parts.pop() ?? ''
 
-  return [...parts.map(labelForMod), labelForBase(base)]
+  return [...parts.map(labelForToken), labelForToken(base)]
 }
 
-// Human-readable label, e.g. "⌘⇧K" on macOS, "Ctrl+Shift+K" elsewhere.
-export function formatCombo(combo: string): string {
-  const tokens = comboTokens(combo)
+// Human-readable label, e.g. "mod+shift+k" returns "⌘⇧K" on macOS, "Ctrl+Shift+K" elsewhere.
+export function formatCombo(combo: Combo): string {
+  return normalizeCombo(combo).join(IS_MAC ? '' : '+')
+}
 
-  return IS_MAC ? tokens.join('') : tokens.join('+')
+
+// like `formatCombo` but allows any input like `@`
+export function formatFakeCombo(combo: FakeCombo): string {
+  return normalizeCombo(combo as Combo).join(IS_MAC ? '' : '+')
 }
 
 // True when focus is in a text-entry surface, so bare-key shortcuts don't fire
@@ -190,6 +231,6 @@ export function isEditableTarget(target: EventTarget | null): boolean {
 
 // A primary modifier (Cmd/Ctrl/Control) fires even while typing (e.g. ⌘K or
 // ⌃Tab from the composer); bare/Shift-only combos are suppressed in inputs.
-export function comboAllowedInInput(combo: string): boolean {
+export function comboAllowedInInput(combo: Combo): boolean {
   return /^(?:mod|ctrl)(?:\+|$)/.test(combo)
 }

apps/desktop/src/store/keybinds.ts

@@ -7,6 +7,7 @@ import {
   type KeybindBindings
 } from '@/lib/keybinds/actions'
 import { canonicalizeCombo } from '@/lib/keybinds/combo'
+import type { Combo } from '@/lib/keybinds/combo'
 import { arraysEqual, persistString, storedString } from '@/lib/storage'
 
 const STORAGE_KEY = 'hermes.desktop.keybinds'
@@ -28,7 +29,7 @@ function loadBindings(): KeybindBindings {
       const value = parsed[id]
 
       if (Array.isArray(value)) {
-        base[id] = value.filter((combo): combo is string => typeof combo === 'string')
+        base[id] = value.filter((combo): combo is string => typeof combo === 'string') as Combo[]
       }
     }
   } catch {
@@ -78,7 +79,7 @@ export const $comboIndex = computed($bindings, bindings => {
   return index
 })
 
-export function setBinding(actionId: string, combos: string[]): void {
+export function setBinding(actionId: string, combos: Combo[]): void {
   if (!keybindAction(actionId)) {
     return
   }
@@ -101,7 +102,7 @@ export function resetAllBindings(): void {
 }
 
 // Other actions that already use `combo` (excluding `actionId` itself).
-export function conflictsFor(actionId: string, combo: string): string[] {
+export function conflictsFor(actionId: string, combo: Combo): string[] {
   const bindings = $bindings.get()
 
   return KEYBIND_ACTION_IDS.filter(id => id !== actionId && (bindings[id] ?? []).includes(combo))

cli-config.yaml.example

@@ -415,7 +415,8 @@ prompt_caching:
 # Auxiliary Models (Advanced — Experimental)
 # =============================================================================
 # Hermes uses lightweight "auxiliary" models for side tasks: image analysis,
-# browser screenshot analysis, web page summarization, and context compression.
+# browser screenshot analysis, web page summarization, TTS audio-tag insertion,
+# and context compression.
 #
 # By default these use Gemini Flash via OpenRouter or Nous Portal and are
 # auto-detected from your credentials.  You do NOT need to change anything
@@ -460,6 +461,12 @@ prompt_caching:
 #     provider: "auto"
 #     model: ""
 #
+#   # Gemini 3.1 TTS hidden audio-tag insertion
+#   tts_audio_tags:
+#     provider: "auto"       # empty model = your main chat model
+#     model: ""
+#     timeout: 30
+#
 #   # Session search — summarizes matching past sessions
 #   session_search:
 #     provider: "auto"
@@ -835,6 +842,22 @@ platform_toolsets:
 #       max_tool_rounds: 5      # tool loop limit (0 = disable)
 #       log_level: "info"       # audit verbosity
 
+# =============================================================================
+# Text-to-Speech
+# =============================================================================
+# TTS defaults to Edge TTS unless changed in ~/.hermes/config.yaml.
+# Gemini TTS supports persona/director prompt files, and Gemini 3.1 Flash TTS
+# can use a hidden auxiliary rewrite pass to insert expressive square-bracket
+# audio tags into the TTS script without showing tags in chat.
+#
+# tts:
+#   provider: "gemini"
+#   gemini:
+#     model: "gemini-3.1-flash-tts-preview"
+#     voice: "Kore"
+#     audio_tags: false
+#     persona_prompt_file: ""  # e.g. ~/.hermes/tts/radio-host.md
+
 # =============================================================================
 # Voice Transcription (Speech-to-Text)
 # =============================================================================

cli.py

@@ -6516,6 +6516,47 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
         }
         self._invalidate(min_interval=0.0)
 
+    def _confirm_expensive_model_switch(self, result) -> bool:
+        """Ask for explicit confirmation before applying costly model switches."""
+        if not getattr(result, "success", False):
+            return True
+        try:
+            from hermes_cli.model_cost_guard import expensive_model_warning
+
+            warning = expensive_model_warning(
+                result.new_model,
+                provider=result.target_provider,
+                base_url=result.base_url or self.base_url or "",
+                api_key=result.api_key or self.api_key or "",
+                model_info=result.model_info,
+            )
+        except Exception:
+            warning = None
+        if warning is None:
+            return True
+
+        choices = [
+            ("once", "Switch anyway", "Use this model for the current Hermes session."),
+            ("cancel", "Cancel", "Keep the current model."),
+        ]
+        raw = self._prompt_text_input_modal(
+            title="!!! Expensive Model Warning !!!",
+            detail=warning.message,
+            choices=choices,
+            timeout=120,
+        )
+        choice = self._normalize_slash_confirm_choice(raw, choices)
+        return choice == "once"
+
+    def _confirm_and_apply_model_switch_result(self, result, persist_global: bool) -> None:
+        try:
+            if result.success and not self._confirm_expensive_model_switch(result):
+                _cprint("  Model switch cancelled.")
+                return
+            self._apply_model_switch_result(result, persist_global)
+        except Exception as exc:
+            _cprint(f"  ✗ Model selection failed: {exc}")
+
     def _close_model_picker(self) -> None:
         self._model_picker_state = None
         self._restore_modal_input_snapshot()
@@ -6692,7 +6733,14 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
                     custom_providers=state.get("custom_provs"),
                 )
                 self._close_model_picker()
-                self._apply_model_switch_result(result, persist_global)
+                if getattr(self, "_app", None):
+                    threading.Thread(
+                        target=self._confirm_and_apply_model_switch_result,
+                        args=(result, persist_global),
+                        daemon=True,
+                    ).start()
+                else:
+                    self._confirm_and_apply_model_switch_result(result, persist_global)
                 return
             self._close_model_picker()
 
@@ -6793,6 +6841,10 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
             _cprint(f"  ✗ {result.error_message}")
             return
 
+        if not self._confirm_expensive_model_switch(result):
+            _cprint("  Model switch cancelled.")
+            return
+
         # Apply to CLI state.
         # Update requested_provider so _ensure_runtime_credentials() doesn't
         # overwrite the switch on the next turn (it re-resolves from this).

gateway/authz_mixin.py

@@ -207,6 +207,14 @@ class GatewayAuthorizationMixin:
         if platform_allow_all_var and os.getenv(platform_allow_all_var, "").lower() in {"true", "1", "yes"}:
             return True
 
+        # Adapter-verified role auth: the Discord adapter already confirmed the
+        # user holds a role in DISCORD_ALLOWED_ROLES before dispatching the message.
+        # Compare with ``is True`` so the real bool field authorizes while a
+        # MagicMock source (test fixtures using ``object.__new__`` runners with
+        # mock sources) does not auto-truthy through this gate (see pitfall #13).
+        if getattr(source, "role_authorized", False) is True:
+            return True
+
         if getattr(source, "is_bot", False):
             allow_bots_var = platform_allow_bots_map.get(source.platform)
             if allow_bots_var and os.getenv(allow_bots_var, "none").lower().strip() in {"mentions", "all"}:

gateway/platforms/base.py

@@ -33,6 +33,7 @@ _AUDIO_EXTS = frozenset({'.ogg', '.opus', '.mp3', '.wav', '.m4a', '.flac'})
 # delivered as a regular document.
 _TELEGRAM_AUDIO_ATTACHMENT_EXTS = frozenset({'.mp3', '.m4a'})
 _TELEGRAM_VOICE_EXTS = frozenset({'.ogg', '.opus'})
+_POST_DELIVERY_CALLBACK_TIMEOUT_SECONDS = 30.0
 
 
 def _platform_name(platform) -> str:
@@ -1803,6 +1804,18 @@ class BasePlatformAdapter(ABC):
     # preview (see gateway/run.py progress_callback).
     supports_code_blocks: bool = False
 
+    # The command prefix users can always TYPE on this platform to reach
+    # Hermes commands.  Default "/" (most platforms deliver "/approve" etc.
+    # as plain message text).  Platforms where typing a leading "/" is
+    # intercepted or restricted by the client (Slack blocks native slash
+    # commands inside threads; Matrix clients reserve "/" for client-local
+    # commands) ship a "!" alias rewrite in their adapter and set this to
+    # "!" so user-facing instruction text ("Reply `!approve` ...") tells
+    # users the form that actually works everywhere.  Capability flag —
+    # shared prompt builders read it via getattr(adapter,
+    # "typed_command_prefix", "/"); no per-platform branching at call sites.
+    typed_command_prefix: str = "/"
+
     def __init__(self, config: PlatformConfig, platform: Platform):
         self.config = config
         self.platform = platform
@@ -4462,6 +4475,15 @@ class BasePlatformAdapter(ABC):
             except Exception:
                 pass  # Last resort — don't let error reporting crash the handler
         finally:
+            # Stop typing before any deferred callback work.  Post-delivery
+            # callbacks may perform platform I/O; a stuck callback must not
+            # leave the typing refresh task running indefinitely.
+            await _stop_typing_task()
+            try:
+                if hasattr(self, "stop_typing"):
+                    await self.stop_typing(event.source.chat_id)
+            except Exception:
+                pass
             # Fire any one-shot post-delivery callback registered for this
             # session (e.g. deferred background-review notifications).
             #
@@ -4489,11 +4511,12 @@ class BasePlatformAdapter(ABC):
                 try:
                     _post_result = _post_cb()
                     if inspect.isawaitable(_post_result):
-                        await _post_result
-                except Exception:
+                        await asyncio.wait_for(
+                            _post_result,
+                            timeout=_POST_DELIVERY_CALLBACK_TIMEOUT_SECONDS,
+                        )
+                except (asyncio.TimeoutError, Exception):
                     pass
-            # Stop typing indicator
-            await _stop_typing_task()
             # Also cancel any platform-level persistent typing tasks (e.g. Discord)
             # that may have been recreated by _keep_typing after the last stop_typing()
             try:
@@ -4651,6 +4674,7 @@ class BasePlatformAdapter(ABC):
         guild_id: Optional[str] = None,
         parent_chat_id: Optional[str] = None,
         message_id: Optional[str] = None,
+        role_authorized: bool = False,
     ) -> SessionSource:
         """Helper to build a SessionSource for this platform."""
         # Normalize empty topic to None
@@ -4671,6 +4695,7 @@ class BasePlatformAdapter(ABC):
             guild_id=str(guild_id) if guild_id else None,
             parent_chat_id=str(parent_chat_id) if parent_chat_id else None,
             message_id=str(message_id) if message_id else None,
+            role_authorized=role_authorized,
         )
     
     @abstractmethod

gateway/platforms/matrix.py

@@ -422,6 +422,11 @@ class MatrixAdapter(BasePlatformAdapter):
 
     supports_code_blocks = True  # Matrix renders fenced code blocks (HTML/markdown)
 
+    # Matrix clients commonly reserve typed "/" for client-local commands;
+    # the adapter accepts "!command" as the alias that always reaches Hermes
+    # (see _normalize_matrix_bang_command), so instruction text shows "!".
+    typed_command_prefix = "!"
+
     # Threshold for detecting Matrix client-side message splits.
     # When a chunk is near the ~4000-char practical limit, a continuation
     # is almost certain.
@@ -1350,11 +1355,11 @@ class MatrixAdapter(BasePlatformAdapter):
             "⚠️ **Dangerous command requires approval**\n"
             f"```\n{cmd_preview}\n```\n"
             f"Reason: {description}\n\n"
-            "Reply `/approve` to execute, `/approve session` to approve this pattern for the session, "
-            "`/approve always` to approve permanently, or `/deny` to cancel.\n\n"
+            "Reply `!approve` to execute, `!approve session` to approve this pattern for the session, "
+            "`!approve always` to approve permanently, or `!deny` to cancel.\n\n"
             "You can also click the reaction to approve:\n"
-            "✅ = /approve\n"
-            "❎ = /deny"
+            "✅ = approve\n"
+            "❎ = deny"
         )
 
         result = await self.send(chat_id, text, metadata=metadata)

gateway/platforms/slack.py

@@ -318,6 +318,11 @@ class SlackAdapter(BasePlatformAdapter):
 
     MAX_MESSAGE_LENGTH = 39000  # Slack API allows 40,000 chars; leave margin
     supports_code_blocks = True  # Slack mrkdwn renders fenced code blocks
+    # Slack blocks typed native slash commands inside threads ("/approve is
+    # not supported in threads. Sorry!").  The adapter rewrites a leading
+    # "!" to "/" for known commands (see _handle_slack_message), so "!" is
+    # the prefix that works everywhere — instruction text must show it.
+    typed_command_prefix = "!"
 
     def __init__(self, config: PlatformConfig):
         super().__init__(config, Platform.SLACK)
@@ -2692,19 +2697,26 @@ class SlackAdapter(BasePlatformAdapter):
             return SendResult(success=False, error="Not connected")
 
         try:
-            cmd_preview = command[:2900] + "..." if len(command) > 2900 else command
             thread_ts = self._resolve_thread_ts(None, metadata)
 
+            # Slack hard-caps a section block's text at 3000 chars; an
+            # oversized block fails the whole send with ``invalid_blocks``
+            # and the gateway falls back to the plain-text prompt (no
+            # buttons).  execute_code approvals embed the entire script in
+            # ``command``, so budget the preview against the fixed parts
+            # instead of a flat truncation that overflows once the header +
+            # reason are added.
+            header = ":warning: *Command Approval Required*\n"
+            reason = f"Reason: {description[:500]}"
+            budget = 3000 - len(header) - len(reason) - len("``````\n") - len("...")
+            cmd_preview = command[:budget] + "..." if len(command) > budget else command
+
             blocks = [
                 {
                     "type": "section",
                     "text": {
                         "type": "mrkdwn",
-                        "text": (
-                            f":warning: *Command Approval Required*\n"
-                            f"```{cmd_preview}```\n"
-                            f"Reason: {description}"
-                        ),
+                        "text": f"{header}```{cmd_preview}```\n{reason}",
                     },
                 },
                 {
@@ -2772,8 +2784,13 @@ class SlackAdapter(BasePlatformAdapter):
             return SendResult(success=False, error="Not connected")
 
         try:
-            body = message[:2900] + "..." if len(message) > 2900 else message
             thread_ts = self._resolve_thread_ts(None, metadata)
+            # Same 3000-char section-block cap as send_exec_approval: budget
+            # the body against the rendered title so the wrapper never pushes
+            # the block over the limit (overflow → invalid_blocks → no buttons).
+            _title = (title or "Confirm")[:150]
+            budget = 3000 - len(f"*{_title}*\n\n") - len("...")
+            body = message[:budget] + "..." if len(message) > budget else message
             # Encode session_key and confirm_id into the button value so the
             # callback handler can resolve without extra bookkeeping.
             value = f"{session_key}|{confirm_id}"
@@ -2783,7 +2800,7 @@ class SlackAdapter(BasePlatformAdapter):
                     "type": "section",
                     "text": {
                         "type": "mrkdwn",
-                        "text": f"*{title or 'Confirm'}*\n\n{body}",
+                        "text": f"*{_title}*\n\n{body}",
                     },
                 },
                 {

gateway/platforms/telegram.py

@@ -3030,7 +3030,7 @@ class TelegramAdapter(BasePlatformAdapter):
     async def _handle_model_picker_callback(
         self, query, data: str, chat_id: str
     ) -> None:
-        """Handle model picker inline keyboard callbacks (mp:/mm:/mb:/mx:/mg:)."""
+        """Handle model picker inline keyboard callbacks (mp:/mm:/mc:/mb:/mx:/mg:)."""
         state = self._model_picker_state.get(chat_id)
         if not state:
             await query.answer(text="Picker expired — use /model again.")
@@ -3115,6 +3115,55 @@ class TelegramAdapter(BasePlatformAdapter):
             )
             await query.answer()
 
+        elif data.startswith("mc:"):
+            # --- Expensive model confirmed: perform the switch ---
+            try:
+                idx = int(data[3:])
+            except ValueError:
+                await query.answer(text="Invalid selection.")
+                return
+
+            model_list = state.get("model_list", [])
+            if idx < 0 or idx >= len(model_list):
+                await query.answer(text="Invalid model index.")
+                return
+
+            model_id = model_list[idx]
+            provider_slug = state.get("selected_provider", "")
+            callback = state.get("on_model_selected")
+
+            if not callback:
+                await query.answer(text="Picker expired.")
+                return
+
+            switch_failed = False
+            try:
+                result_text = await callback(chat_id, model_id, provider_slug)
+            except Exception as exc:
+                logger.error("Model picker switch failed: %s", exc)
+                result_text = f"Error switching model: {exc}"
+                switch_failed = True
+
+            try:
+                await query.edit_message_text(
+                    text=self.format_message(result_text),
+                    parse_mode=ParseMode.MARKDOWN_V2,
+                    reply_markup=None,
+                )
+            except Exception:
+                try:
+                    await query.edit_message_text(
+                        text=result_text,
+                        parse_mode=None,
+                        reply_markup=None,
+                    )
+                except Exception:
+                    pass
+            await query.answer(
+                text="Switch failed." if switch_failed else "Model switched!"
+            )
+            self._model_picker_state.pop(chat_id, None)
+
         elif data.startswith("mm:"):
             # --- Model selected: perform the switch ---
             try:
@@ -3136,11 +3185,43 @@ class TelegramAdapter(BasePlatformAdapter):
                 await query.answer(text="Picker expired.")
                 return
 
+            try:
+                from hermes_cli.model_cost_guard import expensive_model_warning
+
+                # Pricing lookup can hit models.dev / a /models endpoint on a
+                # cache miss — keep it off the event loop.
+                warning = await asyncio.to_thread(
+                    expensive_model_warning,
+                    model_id,
+                    provider=provider_slug,
+                )
+            except Exception:
+                warning = None
+            if warning is not None:
+                keyboard = InlineKeyboardMarkup([
+                    [InlineKeyboardButton("Switch anyway", callback_data=f"mc:{idx}")],
+                    [
+                        InlineKeyboardButton("◀ Back", callback_data="mb"),
+                        InlineKeyboardButton("✗ Cancel", callback_data="mx"),
+                    ],
+                ])
+                await query.edit_message_text(
+                    text=self.format_message(
+                        f"⚠ *Expensive Model Warning*\n\n{warning.message}"
+                    ),
+                    parse_mode=ParseMode.MARKDOWN_V2,
+                    reply_markup=keyboard,
+                )
+                await query.answer(text="Confirm expensive model")
+                return
+
+            switch_failed = False
             try:
                 result_text = await callback(chat_id, model_id, provider_slug)
             except Exception as exc:
                 logger.error("Model picker switch failed: %s", exc)
                 result_text = f"Error switching model: {exc}"
+                switch_failed = True
 
             # Edit message to show confirmation, remove buttons
             try:
@@ -3159,7 +3240,9 @@ class TelegramAdapter(BasePlatformAdapter):
                     )
                 except Exception:
                     pass
-            await query.answer(text="Model switched!")
+            await query.answer(
+                text="Switch failed." if switch_failed else "Model switched!"
+            )
 
             # Clean up state
             self._model_picker_state.pop(chat_id, None)
@@ -3260,7 +3343,7 @@ class TelegramAdapter(BasePlatformAdapter):
         query_user_name = getattr(query.from_user, "first_name", None)
 
         # --- Model picker callbacks ---
-        if data.startswith(("mp:", "mpg:", "mm:", "mb", "mx", "mg:")):
+        if data.startswith(("mp:", "mpg:", "mm:", "mc:", "mb", "mx", "mg:")):
             chat_id = str(query.message.chat_id) if query.message else None
             if chat_id:
                 await self._handle_model_picker_callback(query, data, chat_id)

gateway/run.py

@@ -6473,6 +6473,12 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             _tool_approval_live = False
         if _pending_confirm and not _tool_approval_live:
             _raw_reply = (event.text or "").strip()
+            # Accept bang-prefixed replies (`!always`, `!cancel`) verbatim.
+            # Slack/Matrix instruction text shows the `!` prefix (typed `/`
+            # is blocked in Slack threads), but the adapters only rewrite
+            # `!<known-command>` — `always`/`cancel` are confirm keywords,
+            # not registered commands, so the `!` survives to here.
+            _norm_reply = _raw_reply.lstrip("!/").lower()
             _cmd_reply = event.get_command()
             _confirm_choice = None
             if _cmd_reply in {"approve", "yes", "ok", "confirm"}:
@@ -6481,11 +6487,11 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 _confirm_choice = "always"
             elif _cmd_reply in {"cancel", "no", "deny", "nevermind"}:
                 _confirm_choice = "cancel"
-            elif _raw_reply.lower() in {"approve", "approve once", "once"}:
+            elif _norm_reply in {"approve", "approve once", "once"}:
                 _confirm_choice = "once"
-            elif _raw_reply.lower() in {"always", "always approve"}:
+            elif _norm_reply in {"always", "always approve"}:
                 _confirm_choice = "always"
-            elif _raw_reply.lower() in {"cancel", "nevermind", "no"}:
+            elif _norm_reply in {"cancel", "nevermind", "no"}:
                 _confirm_choice = "cancel"
             if _confirm_choice is not None:
                 _resolved = await _slash_confirm_mod.resolve(
@@ -7059,6 +7065,9 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         if canonical == "memory":
             return await self._handle_memory_command(event)
 
+        if canonical == "skills":
+            return await self._handle_skills_command(event)
+
         if canonical == "fast":
             return await self._handle_fast_command(event)
 
@@ -9367,6 +9376,12 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             adapter._voice_input_callback = self._handle_voice_channel_input
         if hasattr(adapter, "_on_voice_disconnect"):
             adapter._on_voice_disconnect = self._handle_voice_timeout_cleanup
+        # Let the adapter's inactivity timer see the live voice-reply mode so it
+        # doesn't disconnect a deliberately text-only (/voice off) session.
+        if hasattr(adapter, "_voice_mode_getter"):
+            adapter._voice_mode_getter = lambda chat_id: self._voice_mode.get(
+                self._voice_key(Platform.DISCORD, str(chat_id)), "off"
+            )
 
         try:
             success = await adapter.join_voice_channel(voice_channel)
@@ -10622,6 +10637,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 return result
             return result
 
+        _p = self._typed_command_prefix_for(event.source.platform)
         prompt_message = (
             f"⚠️ **Confirm /{command}**\n\n"
             f"{detail}\n\n"
@@ -10629,7 +10645,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             "• **Approve Once** — proceed this time only\n"
             "• **Always Approve** — proceed and silence this prompt permanently\n"
             "• **Cancel** — keep current conversation\n\n"
-            "_Text fallback: reply `/approve`, `/always`, or `/cancel`._"
+            f"_Text fallback: reply `{_p}approve`, `{_p}always`, or `{_p}cancel`._"
         )
         return await self._request_slash_confirm(
             event=event,
@@ -11024,11 +11040,12 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                                 logger.debug("Button-based update prompt failed: %s", btn_err)
                         if not sent_buttons:
                             default_hint = f" (default: {default})" if default else ""
+                            _p = getattr(adapter, "typed_command_prefix", "/")
                             await adapter.send(
                                 chat_id,
                                 f"⚕ **Update needs your input:**\n\n"
                                 f"{prompt_text}{default_hint}\n\n"
-                                f"Reply `/approve` (yes) or `/deny` (no), "
+                                f"Reply `{_p}approve` (yes) or `{_p}deny` (no), "
                                 f"or type your answer directly.",
                                 metadata=metadata,
                             )
@@ -11538,7 +11555,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             # when we successfully transcribed the audio — it's redundant.
             _placeholder = "(The user sent a message with no text content)"
             if user_text and user_text.strip() == _placeholder:
-                return prefix
+                return prefix, successful_transcripts
             if user_text:
                 return f"{prefix}\n\n{user_text}", successful_transcripts
             return prefix, successful_transcripts
@@ -14095,14 +14112,18 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                             "Button-based approval failed, falling back to text: %s", _e
                         )
 
-                # Fallback: plain text approval prompt
+                # Fallback: plain text approval prompt.  Use the adapter's
+                # typed prefix so Slack/Matrix users are told the form they
+                # can actually type (`!approve`) — typed "/" is blocked in
+                # Slack threads and reserved by Matrix clients.
+                _p = getattr(_status_adapter, "typed_command_prefix", "/")
                 cmd_preview = cmd[:200] + "..." if len(cmd) > 200 else cmd
                 msg = (
                     f"⚠️ **Dangerous command requires approval:**\n"
                     f"```\n{cmd_preview}\n```\n"
                     f"Reason: {desc}\n\n"
-                    f"Reply `/approve` to execute, `/approve session` to approve this pattern "
-                    f"for the session, `/approve always` to approve permanently, or `/deny` to cancel."
+                    f"Reply `{_p}approve` to execute, `{_p}approve session` to approve this pattern "
+                    f"for the session, `{_p}approve always` to approve permanently, or `{_p}deny` to cancel."
                 )
                 try:
                     _approval_send_fut = safe_schedule_threadsafe(

gateway/session.py

@@ -91,6 +91,7 @@ class SessionSource:
     guild_id: Optional[str] = None  # Discord guild / Slack workspace / Matrix server scope
     parent_chat_id: Optional[str] = None  # Parent channel when chat_id refers to a thread
     message_id: Optional[str] = None  # ID of the triggering message (for pin/reply/react)
+    role_authorized: bool = False  # True when adapter granted access via role (not user ID)
     
     @property
     def description(self) -> str:

gateway/slash_commands.py

@@ -47,6 +47,19 @@ logger = logging.getLogger("gateway.run")
 class GatewaySlashCommandsMixin:
     """In-session slash-command handlers for GatewayRunner."""
 
+    def _typed_command_prefix_for(self, platform) -> str:
+        """Return the prefix users can always type to reach Hermes commands.
+
+        Reads the adapter's ``typed_command_prefix`` capability flag
+        (default "/"). Slack and Matrix return "!" because typed "/"
+        commands are blocked in Slack threads / reserved by Matrix clients;
+        their adapters rewrite "!command" to "/command" on receive.
+        Instruction text built for those platforms must show the prefix
+        that actually works when typed.
+        """
+        adapter = self.adapters.get(platform) if getattr(self, "adapters", None) else None
+        return getattr(adapter, "typed_command_prefix", "/") if adapter is not None else "/"
+
     async def _handle_reset_command(self, event: MessageEvent) -> Union[str, EphemeralReply]:
         """Handle /new or /reset command."""
         source = event.source
@@ -1146,149 +1159,198 @@ class GatewaySlashCommandsMixin:
         if not result.success:
             return t("gateway.model.error_prefix", error=result.error_message)
 
-        # If there's a cached agent, update it in-place
-        cached_entry = None
-        _cache_lock = getattr(self, "_agent_cache_lock", None)
-        _cache = getattr(self, "_agent_cache", None)
-        if _cache_lock and _cache is not None:
-            with _cache_lock:
-                cached_entry = _cache.get(session_key)
+        async def _finish_switch() -> str:
+            """Apply the resolved switch (agent, session, config) and build the reply."""
+            # If there's a cached agent, update it in-place
+            cached_entry = None
+            _cache_lock = getattr(self, "_agent_cache_lock", None)
+            _cache = getattr(self, "_agent_cache", None)
+            if _cache_lock and _cache is not None:
+                with _cache_lock:
+                    cached_entry = _cache.get(session_key)
 
-        if cached_entry and cached_entry[0] is not None:
+            if cached_entry and cached_entry[0] is not None:
+                try:
+                    cached_entry[0].switch_model(
+                        new_model=result.new_model,
+                        new_provider=result.target_provider,
+                        api_key=result.api_key,
+                        base_url=result.base_url,
+                        api_mode=result.api_mode,
+                    )
+                except Exception as exc:
+                    logger.warning("In-place model switch failed for cached agent: %s", exc)
+
+            # Persist the new model to the session DB so the dashboard
+            # shows the updated model (#34850).
+            _sess_db = getattr(self, "_session_db", None)
+            if _sess_db is not None:
+                try:
+                    _sess_entry = self.session_store.get_or_create_session(source)
+                    _sess_db.update_session_model(
+                        _sess_entry.session_id, result.new_model
+                    )
+                except Exception as exc:
+                    logger.debug(
+                        "Failed to persist model switch to DB: %s", exc
+                    )
+
+            # Store a note to prepend to the next user message so the model
+            # knows about the switch (avoids system messages mid-history).
+            if not hasattr(self, "_pending_model_notes"):
+                self._pending_model_notes = {}
+            self._pending_model_notes[session_key] = (
+                f"[Note: model was just switched from {current_model} to {result.new_model} "
+                f"via {result.provider_label or result.target_provider}. "
+                f"Adjust your self-identification accordingly.]"
+            )
+
+            # Store session override so next agent creation uses the new model
+            self._session_model_overrides[session_key] = {
+                "model": result.new_model,
+                "provider": result.target_provider,
+                "api_key": result.api_key,
+                "base_url": result.base_url,
+                "api_mode": result.api_mode,
+            }
+
+            # Evict cached agent so the next turn creates a fresh agent from the
+            # override rather than relying on cache signature mismatch detection.
+            self._evict_cached_agent(session_key)
+
+            # Persist to config if --global
+            if persist_global:
+                try:
+                    if config_path.exists():
+                        with open(config_path, encoding="utf-8") as f:
+                            cfg = yaml.safe_load(f) or {}
+                    else:
+                        cfg = {}
+                    # Coerce scalar/None ``model:`` into a dict before mutation —
+                    # otherwise ``cfg.setdefault("model", {})`` returns the existing
+                    # scalar and the next assignment raises
+                    # ``TypeError: 'str' object does not support item assignment``.
+                    # Reproduces when ``config.yaml`` has ``model: <name>`` (flat
+                    # string) instead of the proper nested ``model: {default: ...}``.
+                    raw_model = cfg.get("model")
+                    if isinstance(raw_model, dict):
+                        model_cfg = raw_model
+                    elif isinstance(raw_model, str) and raw_model.strip():
+                        model_cfg = {"default": raw_model.strip()}
+                        cfg["model"] = model_cfg
+                    else:
+                        model_cfg = {}
+                        cfg["model"] = model_cfg
+                    model_cfg["default"] = result.new_model
+                    model_cfg["provider"] = result.target_provider
+                    if result.base_url:
+                        model_cfg["base_url"] = result.base_url
+                    from hermes_cli.config import save_config
+                    save_config(cfg)
+                except Exception as e:
+                    logger.warning("Failed to persist model switch: %s", e)
+
+            # Build confirmation message with full metadata
+            provider_label = result.provider_label or result.target_provider
+            lines = [t("gateway.model.switched", model=result.new_model)]
+            lines.append(t("gateway.model.provider_label", provider=provider_label))
+
+            # Context: always resolve via the provider-aware chain so Codex OAuth,
+            # Copilot, and Nous-enforced caps win over the raw models.dev entry.
+            mi = result.model_info
+            from hermes_cli.model_switch import resolve_display_context_length
+            _sw2_config_ctx = None
             try:
-                cached_entry[0].switch_model(
-                    new_model=result.new_model,
-                    new_provider=result.target_provider,
-                    api_key=result.api_key,
-                    base_url=result.base_url,
-                    api_mode=result.api_mode,
-                )
-            except Exception as exc:
-                logger.warning("In-place model switch failed for cached agent: %s", exc)
+                _sw2_cfg = _load_gateway_config()
+                _sw2_model_cfg = _sw2_cfg.get("model", {})
+                if isinstance(_sw2_model_cfg, dict):
+                    _sw2_raw = _sw2_model_cfg.get("context_length")
+                    if _sw2_raw is not None:
+                        _sw2_config_ctx = int(_sw2_raw)
+            except Exception:
+                pass
+            ctx = resolve_display_context_length(
+                result.new_model,
+                result.target_provider,
+                base_url=result.base_url or current_base_url or "",
+                api_key=result.api_key or current_api_key or "",
+                model_info=mi,
+                custom_providers=custom_provs,
+                config_context_length=_sw2_config_ctx,
+            )
+            if ctx:
+                lines.append(t("gateway.model.context_label", tokens=f"{ctx:,}"))
+            if mi:
+                if mi.max_output:
+                    lines.append(t("gateway.model.max_output_label", tokens=f"{mi.max_output:,}"))
+                if mi.has_cost_data():
+                    lines.append(t("gateway.model.cost_label", cost=mi.format_cost()))
+                lines.append(t("gateway.model.capabilities_label", capabilities=mi.format_capabilities()))
 
-        # Persist the new model to the session DB so the dashboard
-        # shows the updated model (#34850).
-        _sess_db = getattr(self, "_session_db", None)
-        if _sess_db is not None:
-            try:
-                _sess_entry = self.session_store.get_or_create_session(source)
-                _sess_db.update_session_model(
-                    _sess_entry.session_id, result.new_model
-                )
-            except Exception as exc:
-                logger.debug(
-                    "Failed to persist model switch to DB: %s", exc
-                )
+            # Cache notice
+            cache_enabled = (
+                (base_url_host_matches(result.base_url or "", "openrouter.ai") and "claude" in result.new_model.lower())
+                or result.api_mode == "anthropic_messages"
+            )
+            if cache_enabled:
+                lines.append(t("gateway.model.prompt_caching_enabled"))
 
-        # Store a note to prepend to the next user message so the model
-        # knows about the switch (avoids system messages mid-history).
-        if not hasattr(self, "_pending_model_notes"):
-            self._pending_model_notes = {}
-        self._pending_model_notes[session_key] = (
-            f"[Note: model was just switched from {current_model} to {result.new_model} "
-            f"via {result.provider_label or result.target_provider}. "
-            f"Adjust your self-identification accordingly.]"
-        )
+            if result.warning_message:
+                lines.append(t("gateway.model.warning_prefix", warning=result.warning_message))
 
-        # Store session override so next agent creation uses the new model
-        self._session_model_overrides[session_key] = {
-            "model": result.new_model,
-            "provider": result.target_provider,
-            "api_key": result.api_key,
-            "base_url": result.base_url,
-            "api_mode": result.api_mode,
-        }
+            if persist_global:
+                lines.append(t("gateway.model.saved_global"))
+            else:
+                lines.append(t("gateway.model.session_only_hint"))
 
-        # Evict cached agent so the next turn creates a fresh agent from the
-        # override rather than relying on cache signature mismatch detection.
-        self._evict_cached_agent(session_key)
+            return "\n".join(lines)
 
-        # Persist to config if --global
-        if persist_global:
-            try:
-                if config_path.exists():
-                    with open(config_path, encoding="utf-8") as f:
-                        cfg = yaml.safe_load(f) or {}
-                else:
-                    cfg = {}
-                # Coerce scalar/None ``model:`` into a dict before mutation —
-                # otherwise ``cfg.setdefault("model", {})`` returns the existing
-                # scalar and the next assignment raises
-                # ``TypeError: 'str' object does not support item assignment``.
-                # Reproduces when ``config.yaml`` has ``model: <name>`` (flat
-                # string) instead of the proper nested ``model: {default: ...}``.
-                raw_model = cfg.get("model")
-                if isinstance(raw_model, dict):
-                    model_cfg = raw_model
-                elif isinstance(raw_model, str) and raw_model.strip():
-                    model_cfg = {"default": raw_model.strip()}
-                    cfg["model"] = model_cfg
-                else:
-                    model_cfg = {}
-                    cfg["model"] = model_cfg
-                model_cfg["default"] = result.new_model
-                model_cfg["provider"] = result.target_provider
-                if result.base_url:
-                    model_cfg["base_url"] = result.base_url
-                from hermes_cli.config import save_config
-                save_config(cfg)
-            except Exception as e:
-                logger.warning("Failed to persist model switch: %s", e)
-
-        # Build confirmation message with full metadata
-        provider_label = result.provider_label or result.target_provider
-        lines = [t("gateway.model.switched", model=result.new_model)]
-        lines.append(t("gateway.model.provider_label", provider=provider_label))
-
-        # Context: always resolve via the provider-aware chain so Codex OAuth,
-        # Copilot, and Nous-enforced caps win over the raw models.dev entry.
-        mi = result.model_info
-        from hermes_cli.model_switch import resolve_display_context_length
-        _sw2_config_ctx = None
+        # Expensive-model confirmation gate (typed /model <name> path).
+        # The pickers (Telegram/Discord inline keyboards, TUI, dashboard)
+        # already confirm via their own UI affordances; this covers the
+        # direct text command, which previously bypassed the guard.
+        # expensive_model_warning() may hit models.dev or a /models endpoint
+        # on a cache miss, so run it off the event loop.
+        _cost_warning = None
         try:
-            _sw2_cfg = _load_gateway_config()
-            _sw2_model_cfg = _sw2_cfg.get("model", {})
-            if isinstance(_sw2_model_cfg, dict):
-                _sw2_raw = _sw2_model_cfg.get("context_length")
-                if _sw2_raw is not None:
-                    _sw2_config_ctx = int(_sw2_raw)
+            from hermes_cli.model_cost_guard import expensive_model_warning
+
+            _cost_warning = await asyncio.to_thread(
+                expensive_model_warning,
+                result.new_model,
+                provider=result.target_provider,
+                base_url=result.base_url or current_base_url or "",
+                api_key=result.api_key or current_api_key or "",
+                model_info=result.model_info,
+            )
         except Exception:
-            pass
-        ctx = resolve_display_context_length(
-            result.new_model,
-            result.target_provider,
-            base_url=result.base_url or current_base_url or "",
-            api_key=result.api_key or current_api_key or "",
-            model_info=mi,
-            custom_providers=custom_provs,
-            config_context_length=_sw2_config_ctx,
-        )
-        if ctx:
-            lines.append(t("gateway.model.context_label", tokens=f"{ctx:,}"))
-        if mi:
-            if mi.max_output:
-                lines.append(t("gateway.model.max_output_label", tokens=f"{mi.max_output:,}"))
-            if mi.has_cost_data():
-                lines.append(t("gateway.model.cost_label", cost=mi.format_cost()))
-            lines.append(t("gateway.model.capabilities_label", capabilities=mi.format_capabilities()))
+            _cost_warning = None
+        if _cost_warning is not None:
+            async def _on_cost_confirm(choice: str) -> str:
+                if choice == "cancel":
+                    return (
+                        f"🟡 Model switch cancelled. Current model unchanged "
+                        f"({current_model or 'unknown'})."
+                    )
+                # "once" and "always" both proceed — there is no persistent
+                # opt-out for the cost guard (each expensive switch should be
+                # an explicit decision).
+                return await _finish_switch()
 
-        # Cache notice
-        cache_enabled = (
-            (base_url_host_matches(result.base_url or "", "openrouter.ai") and "claude" in result.new_model.lower())
-            or result.api_mode == "anthropic_messages"
-        )
-        if cache_enabled:
-            lines.append(t("gateway.model.prompt_caching_enabled"))
+            _p = self._typed_command_prefix_for(event.source.platform)
+            return await self._request_slash_confirm(
+                event=event,
+                command="model",
+                title="Expensive Model Warning",
+                message=(
+                    f"⚠️ **Expensive Model Warning**\n\n{_cost_warning.message}\n\n"
+                    f"_Text fallback: reply `{_p}approve` to switch or `{_p}cancel` to keep "
+                    "the current model._"
+                ),
+                handler=_on_cost_confirm,
+            )
 
-        if result.warning_message:
-            lines.append(t("gateway.model.warning_prefix", warning=result.warning_message))
-
-        if persist_global:
-            lines.append(t("gateway.model.saved_global"))
-        else:
-            lines.append(t("gateway.model.session_only_hint"))
-
-        return "\n".join(lines)
+        return await _finish_switch()
 
     async def _handle_codex_runtime_command(self, event: MessageEvent) -> str:
         """Handle /codex-runtime command in the gateway.
@@ -1955,12 +2017,12 @@ class GatewaySlashCommandsMixin:
         return t("gateway.reasoning.set_session", effort=effort)
 
     async def _handle_memory_command(self, event: MessageEvent) -> str:
-        """Handle /memory — review pending memory writes + set write mode.
+        """Handle /memory — review pending memory writes + toggle the approval gate.
 
         Memory entries are small enough to review inline in a chat bubble, so
-        the full pending/approve/reject/mode flow works on every platform.
-        Mode changes persist to config.yaml and evict the cached agent so the
-        new write_mode takes effect on the next message.
+        the full pending/approve/reject/approval flow works on every platform.
+        Gate changes persist to config.yaml and evict the cached agent so the
+        new setting takes effect on the next message.
         """
         from gateway.run import _hermes_home
         from hermes_cli.write_approval_commands import handle_pending_subcommand
@@ -1972,15 +2034,15 @@ class GatewaySlashCommandsMixin:
         session_key = self._session_key_for_source(event.source)
         config_path = _hermes_home / "config.yaml"
 
-        def _set_mode(mode: str):
+        def _set_approval(enabled: bool):
             import yaml
             user_config = {}
             if config_path.exists():
                 with open(config_path, encoding="utf-8") as f:
                     user_config = yaml.safe_load(f) or {}
-            user_config.setdefault("memory", {})["write_mode"] = mode
+            user_config.setdefault("memory", {})["write_approval"] = bool(enabled)
             atomic_yaml_write(config_path, user_config)
-            # New write_mode must take effect next message → drop cached agent.
+            # New setting must take effect next message → drop cached agent.
             self._evict_cached_agent(session_key)
 
         # Apply approved writes against a fresh on-disk store (the gateway has
@@ -1989,11 +2051,69 @@ class GatewaySlashCommandsMixin:
         store.load_from_disk()
 
         out = handle_pending_subcommand(
-            wa.MEMORY, args, memory_store=store, set_mode_fn=_set_mode,
+            wa.MEMORY, args, memory_store=store, set_mode_fn=_set_approval,
         )
         if out is None:
             out = ("Unknown /memory subcommand. Use: pending, approve <id>, "
-                   "reject <id>, mode <on|off|approve>.")
+                   "reject <id>, approval <on|off>.")
+        return out
+
+    async def _handle_skills_command(self, event: MessageEvent) -> str:
+        """Handle /skills on the gateway — pending skill-write review only.
+
+        The full skills hub (search/browse/install) stays CLI-only; this
+        handler covers the write-approval review surface (pending / approve /
+        reject / diff / approval) so a skill staged from a gateway session can
+        be reviewed from that same session. Gated by ``skills.write_approval``
+        via the CommandDef's ``gateway_config_gate``; also answers when staged
+        writes still exist after the gate was turned off (so they are never
+        stranded).
+
+        ``diff`` output is truncated for chat bubbles — the full diff lives in
+        the CLI (``/skills diff <id>``) and the pending JSON file.
+        """
+        from gateway.run import _hermes_home
+        from hermes_cli.write_approval_commands import handle_pending_subcommand
+        from tools import write_approval as wa
+
+        raw_args = event.get_command_args().strip()
+        args = raw_args.split() if raw_args else []
+        session_key = self._session_key_for_source(event.source)
+        config_path = _hermes_home / "config.yaml"
+
+        gate_on = wa.write_approval_enabled(wa.SKILLS)
+        wants_toggle = bool(args) and args[0].lower() in {"approval", "mode"}
+        if not gate_on and not wants_toggle and wa.pending_count(wa.SKILLS) == 0:
+            return ("Skill write approval is off (skills.write_approval). "
+                    "Enable it with /skills approval on, then review staged "
+                    "writes here with /skills pending.")
+
+        def _set_approval(enabled: bool):
+            import yaml
+            user_config = {}
+            if config_path.exists():
+                with open(config_path, encoding="utf-8") as f:
+                    user_config = yaml.safe_load(f) or {}
+            user_config.setdefault("skills", {})["write_approval"] = bool(enabled)
+            atomic_yaml_write(config_path, user_config)
+            # New setting must take effect next message → drop cached agent.
+            self._evict_cached_agent(session_key)
+
+        out = handle_pending_subcommand(
+            wa.SKILLS, args, set_mode_fn=_set_approval,
+        )
+        if out is None:
+            return ("Unknown /skills subcommand on this platform. Use: pending, "
+                    "approve <id>, reject <id>, diff <id>, approval <on|off>. "
+                    "(Search/install are CLI-only.)")
+
+        # Chat bubbles can't hold a full skill diff — truncate and point at
+        # the real review surfaces.
+        if args and args[0].lower() == "diff" and len(out) > 3000:
+            pending_id = args[1] if len(args) > 1 else "<id>"
+            out = (out[:3000]
+                   + f"\n… (truncated — full diff: `/skills diff {pending_id}` "
+                     f"on the CLI, or ~/.hermes/pending/skills/{pending_id}.json)")
         return out
 
     async def _handle_fast_command(self, event: MessageEvent) -> str:

hermes_cli/__init__.py

@@ -19,29 +19,74 @@ __release_date__ = "2026.6.5"
 
 
 def _ensure_utf8():
-    """Force UTF-8 stdout/stderr on Windows to prevent UnicodeEncodeError.
+    """Force UTF-8 stdout/stderr to prevent UnicodeEncodeError crashes.
 
-    Windows services and terminals default to cp1252, which cannot encode
-    box-drawing characters used in CLI output. This causes unhandled
-    UnicodeEncodeError crashes on gateway startup.
+    Several environments select a legacy, non-UTF-8 encoding for the standard
+    streams:
+
+    - Windows services and terminals default to cp1252.
+    - Linux hosts with a latin-1 / C / POSIX locale (common on minimal Debian
+      installs and Raspberry Pi) select latin-1 or ASCII.
+
+    The CLI prints box-drawing characters (┌│├└─) and the ⚕ glyph in the setup
+    wizard, doctor, and status banners. Encoding those under a non-UTF-8 codec
+    raises an unhandled UnicodeEncodeError that crashes the command before it
+    can even start — e.g. `hermes setup` on a fresh Pi.
+
+    This runs at import time so it protects every CLI subcommand, on any
+    platform. It re-wraps stdout/stderr as UTF-8 when their encoding is not
+    already UTF-8, preferring TextIOWrapper.reconfigure() so the existing
+    stream object is fixed in place (cached `sys.stdout` references keep
+    working) and falling back to reopening the file descriptor with
+    closefd=False (the CPython-recommended safe variant).
+
+    No-op when the streams are already UTF-8: a healthy UTF-8 system sees no
+    stream change and no environment mutation.
+
+    Note: this is intentionally the earliest, platform-agnostic guard.
+    hermes_cli/stdio.py::configure_windows_stdio() runs later from the entry
+    points and layers on the Windows-only extras (console code-page flip,
+    EDITOR default, PATH augmentation); its stream reconfiguration is a
+    harmless idempotent no-op once we have already repaired the streams here.
     """
-    if sys.platform != "win32":
-        return
-    os.environ.setdefault("PYTHONUTF8", "1")
-    os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+    repaired = False
+
     for stream_name in ("stdout", "stderr"):
         stream = getattr(sys, stream_name, None)
         if stream is None:
             continue
         try:
-            if getattr(stream, "encoding", "").lower().replace("-", "") != "utf8":
-                new_stream = open(
-                    stream.fileno(), "w", encoding="utf-8",
-                    buffering=1, closefd=False,
-                )
-                setattr(sys, stream_name, new_stream)
-        except (AttributeError, OSError):
+            encoding = (getattr(stream, "encoding", "") or "").lower().replace("-", "")
+            if encoding == "utf8":
+                continue
+
+            # Preferred: reconfigure the existing TextIOWrapper in place. This
+            # preserves object identity so any code already holding a reference
+            # to the old sys.stdout benefits from the repair too.
+            reconfigure = getattr(stream, "reconfigure", None)
+            if callable(reconfigure):
+                reconfigure(encoding="utf-8", errors="replace")
+                repaired = True
+                continue
+
+            # Fallback: reopen the underlying file descriptor as UTF-8. Used
+            # for streams that don't expose reconfigure() (e.g. some wrapped
+            # or replaced streams). closefd=False keeps the original fd open.
+            new_stream = open(
+                stream.fileno(), "w", encoding="utf-8",
+                errors="replace", buffering=1, closefd=False,
+            )
+            setattr(sys, stream_name, new_stream)
+            repaired = True
+        except (AttributeError, OSError, ValueError):
             pass
 
+    # Only nudge child processes toward UTF-8 when we actually detected a
+    # non-UTF-8 locale. On a healthy UTF-8 host children inherit UTF-8 from the
+    # locale already, so leave the environment untouched (minimal footprint).
+    if repaired:
+        os.environ.setdefault("PYTHONUTF8", "1")
+        os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+
 
 _ensure_utf8()

hermes_cli/auth.py

@@ -2665,12 +2665,23 @@ def _xai_wait_for_callback(
     result: dict[str, Any],
     *,
     timeout_seconds: float = 180.0,
+    manual_paste_redirect_uri: Optional[str] = None,
 ) -> dict[str, Any]:
     deadline = time.monotonic() + max(5.0, timeout_seconds)
+    if manual_paste_redirect_uri and sys.stdin.isatty():
+        print()
+        print("If xAI shows a Grok Build code instead of redirecting,")
+        print("paste that code here and press Enter.")
     try:
         while time.monotonic() < deadline:
             if result["code"] or result["error"]:
                 return result
+            if manual_paste_redirect_uri:
+                raw_paste = _read_ready_stdin_line()
+                if raw_paste and raw_paste.strip():
+                    pasted = _parse_pasted_callback(raw_paste)
+                    pasted["_manual_paste"] = True
+                    return pasted
             time.sleep(0.1)
     finally:
         server.shutdown()
@@ -2694,6 +2705,21 @@ def _xai_wait_for_callback(
     )
 
 
+def _read_ready_stdin_line() -> Optional[str]:
+    """Return one pending stdin line without blocking, if the terminal has one."""
+    try:
+        if not sys.stdin.isatty():
+            return None
+        import select
+
+        ready, _, _ = select.select([sys.stdin], [], [], 0)
+        if not ready:
+            return None
+        return sys.stdin.readline()
+    except Exception:
+        return None
+
+
 def _spotify_token_payload_to_state(
     token_payload: Dict[str, Any],
     *,
@@ -6149,6 +6175,40 @@ def _reset_config_provider() -> Path:
     return config_path
 
 
+def _confirm_expensive_model_selection(
+    model_id: str,
+    *,
+    provider: str = "",
+    base_url: str = "",
+    api_key: str = "",
+) -> bool:
+    """Prompt before saving a model whose known pricing exceeds guardrails."""
+    try:
+        from hermes_cli.model_cost_guard import expensive_model_warning
+
+        warning = expensive_model_warning(
+            model_id,
+            provider=provider,
+            base_url=base_url,
+            api_key=api_key,
+        )
+    except Exception:
+        warning = None
+    if warning is None:
+        return True
+
+    print()
+    print("=" * 72)
+    print(warning.message)
+    print("=" * 72)
+    try:
+        response = input("Switch anyway? [y/N]: ").strip().lower()
+    except (KeyboardInterrupt, EOFError):
+        print()
+        return False
+    return response in {"y", "yes"}
+
+
 def _prompt_model_selection(
     model_ids: List[str],
     current_model: str = "",
@@ -6156,6 +6216,9 @@ def _prompt_model_selection(
     unavailable_models: Optional[List[str]] = None,
     portal_url: str = "",
     unavailable_message: str = "",
+    confirm_provider: str = "",
+    confirm_base_url: str = "",
+    confirm_api_key: str = "",
 ) -> Optional[str]:
     """Interactive model selection. Puts current_model first with a marker. Returns chosen model ID or None.
 
@@ -6169,6 +6232,18 @@ def _prompt_model_selection(
 
     _unavailable = unavailable_models or []
 
+    def _confirmed_selection(mid: str) -> Optional[str]:
+        if not mid:
+            return None
+        if confirm_provider and not _confirm_expensive_model_selection(
+            mid,
+            provider=confirm_provider,
+            base_url=confirm_base_url,
+            api_key=confirm_api_key,
+        ):
+            return None
+        return mid
+
     # Reorder: current model first, then the rest (deduplicated)
     ordered = []
     if current_model and current_model in model_ids:
@@ -6284,13 +6359,13 @@ def _prompt_model_selection(
             return None
         print()
         if idx < len(ordered):
-            return ordered[idx]
+            return _confirmed_selection(ordered[idx])
         elif idx == len(ordered):
             try:
                 custom = input("Enter model name: ").strip()
             except (EOFError, KeyboardInterrupt):
                 return None
-            return custom if custom else None
+            return _confirmed_selection(custom) if custom else None
         return None
     except (ImportError, NotImplementedError, OSError, subprocess.SubprocessError):
         pass
@@ -6322,10 +6397,10 @@ def _prompt_model_selection(
                 return None
             idx = int(choice)
             if 1 <= idx <= n:
-                return ordered[idx - 1]
+                return _confirmed_selection(ordered[idx - 1])
             elif idx == n + 1:
                 custom = input("Enter model name: ").strip()
-                return custom if custom else None
+                return _confirmed_selection(custom) if custom else None
             elif idx == n + 2:
                 return None
             print(f"Please enter 1-{n + 2}")
@@ -6669,6 +6744,7 @@ def _xai_oauth_loopback_login(
     authorization_endpoint = discovery["authorization_endpoint"]
     token_endpoint = discovery["token_endpoint"]
 
+    allow_missing_state = False
     if manual_paste:
         # No HTTP listener — synthesize a redirect_uri matching what
         # the server would have bound to so the authorize URL the user
@@ -6695,6 +6771,7 @@ def _xai_oauth_loopback_login(
         print("Open this URL to authorize Hermes with xAI:")
         print(authorize_url)
         callback = _prompt_manual_callback_paste(redirect_uri)
+        allow_missing_state = True
     else:
         server, thread, callback_result, redirect_uri = _xai_start_callback_server()
         try:
@@ -6734,6 +6811,7 @@ def _xai_oauth_loopback_login(
                     thread,
                     callback_result,
                     timeout_seconds=max(30.0, timeout_seconds * 9),
+                    manual_paste_redirect_uri=redirect_uri,
                 )
             except AuthError as exc:
                 if (
@@ -6750,6 +6828,7 @@ def _xai_oauth_loopback_login(
                 callback = _prompt_manual_callback_paste(redirect_uri)
                 if callback.get("code") is None and callback.get("error") is None:
                     raise exc
+                allow_missing_state = True
         except Exception:
             try:
                 server.shutdown()
@@ -6770,7 +6849,7 @@ def _xai_oauth_loopback_login(
             code="xai_authorization_failed",
         )
     callback_state = callback.get("state")
-    # Manual-paste bare-code path: when a user pastes only the opaque
+    # Manual bare-code paths: when a user pastes only the opaque
     # authorization code (no ``code=``/``state=`` query parameters),
     # ``_parse_pasted_callback`` returns ``state=None``.  xAI's consent
     # page renders the code in-page rather than redirecting through the
@@ -6778,10 +6857,12 @@ def _xai_oauth_loopback_login(
     # VPS, container consoles) the bare code is the only thing the user
     # can obtain.  PKCE (code_verifier) still binds the exchange to this
     # client, so the local state-equality check is redundant on the
-    # bare-code path — we substitute the locally generated state to keep
+    # bare-code paths — we substitute the locally generated state to keep
     # the rest of the validation chain (and the token exchange) unchanged.
     # See #26923 (AccursedGalaxy comment, 2026-05-20).
-    if callback_state is None and manual_paste:
+    if callback.get("_manual_paste"):
+        allow_missing_state = True
+    if callback_state is None and (manual_paste or allow_missing_state):
         callback_state = state
     if callback_state != state:
         raise AuthError(
@@ -7698,6 +7779,9 @@ def _login_nous(args, pconfig: ProviderConfig) -> None:
                     unavailable_models=unavailable_models,
                     portal_url=_portal,
                     unavailable_message=unavailable_message,
+                    confirm_provider="nous",
+                    confirm_base_url=inference_base_url,
+                    confirm_api_key=runtime_key,
                 )
             elif unavailable_models:
                 _url = (_portal or DEFAULT_NOUS_PORTAL_URL).rstrip("/")

hermes_cli/cli_commands_mixin.py

@@ -1306,12 +1306,12 @@ class CLICommandsMixin:
         parts = cmd.strip().split()
         args = parts[1:] if len(parts) > 1 else []
         if args and args[0].lower() in {"pending", "approve", "apply", "reject",
-                                        "deny", "drop", "diff", "mode"}:
+                                        "deny", "drop", "diff", "approval", "mode"}:
             from hermes_cli.write_approval_commands import handle_pending_subcommand
             from tools import write_approval as wa
             out = handle_pending_subcommand(
                 wa.SKILLS, args,
-                set_mode_fn=lambda m: self._save_write_mode("skills", m),
+                set_mode_fn=lambda enabled: self._save_write_approval("skills", enabled),
             )
             if out is not None:
                 print(out)
@@ -1320,7 +1320,7 @@ class CLICommandsMixin:
         handle_skills_slash(cmd, ChatConsole())
 
     def _handle_memory_command(self, cmd: str):
-        """Handle /memory slash command — pending review + write-mode control."""
+        """Handle /memory slash command — pending review + approval-gate toggle."""
         from hermes_cli.write_approval_commands import handle_pending_subcommand
         from tools import write_approval as wa
         parts = cmd.strip().split()
@@ -1329,17 +1329,17 @@ class CLICommandsMixin:
         out = handle_pending_subcommand(
             wa.MEMORY, args,
             memory_store=store,
-            set_mode_fn=lambda m: self._save_write_mode("memory", m),
+            set_mode_fn=lambda enabled: self._save_write_approval("memory", enabled),
         )
         if out is None:
             out = ("Unknown /memory subcommand. "
-                   "Use: pending, approve <id>, reject <id>, mode <on|off|approve>.")
+                   "Use: pending, approve <id>, reject <id>, approval <on|off>.")
         print(out)
 
-    def _save_write_mode(self, subsystem: str, mode: str):
-        """Persist <subsystem>.write_mode to config (for /memory|/skills mode)."""
+    def _save_write_approval(self, subsystem: str, enabled: bool):
+        """Persist <subsystem>.write_approval to config (for /memory|/skills approval)."""
         from cli import save_config_value
-        save_config_value(f"{subsystem}.write_mode", mode)
+        save_config_value(f"{subsystem}.write_approval", bool(enabled))
 
     def _handle_background_command(self, cmd: str):
         """Handle /background <prompt> — run a prompt in a separate background session.

hermes_cli/commands.py

@@ -167,12 +167,13 @@ COMMAND_REGISTRY: list[CommandDef] = [
                cli_only=True),
     CommandDef("skills", "Search, install, inspect, or manage skills",
                "Tools & Skills", cli_only=True,
+               gateway_config_gate="skills.write_approval",
                subcommands=("search", "browse", "inspect", "install", "audit",
-                            "pending", "approve", "reject", "diff", "mode")),
-    CommandDef("memory", "Review pending memory writes / set write mode",
+                            "pending", "approve", "reject", "diff", "approval")),
+    CommandDef("memory", "Review pending memory writes / toggle the approval gate",
                "Tools & Skills",
-               args_hint="[pending|approve|reject|mode] [id|on|off|approve]",
-               subcommands=("pending", "approve", "reject", "mode")),
+               args_hint="[pending|approve|reject|approval] [id|on|off]",
+               subcommands=("pending", "approve", "reject", "approval")),
     CommandDef("bundles", "List skill bundles (aliases /<name> for multiple skills)",
                "Tools & Skills"),
     CommandDef("cron", "Manage scheduled tasks", "Tools & Skills",

hermes_cli/config.py

@@ -1290,6 +1290,14 @@ DEFAULT_CONFIG = {
             "timeout": 30,
             "extra_body": {},
         },
+        "tts_audio_tags": {
+            "provider": "auto",
+            "model": "",
+            "base_url": "",
+            "api_key": "",
+            "timeout": 30,
+            "extra_body": {},
+        },
         # Triage specifier — flesh out a rough one-liner in the Kanban
         # Triage column into a concrete spec, then promote it to ``todo``.
         # Invoked by ``hermes kanban specify`` (single id or --all). Set a
@@ -1556,7 +1564,7 @@ DEFAULT_CONFIG = {
     # Each provider supports an optional `max_text_length:` override for the
     # per-request input-character cap. Omit it to use the provider's documented
     # limit (OpenAI 4096, xAI 15000, MiniMax 10000, ElevenLabs 5k-40k model-aware,
-    # Gemini 5000, Edge 5000, Mistral 4000, NeuTTS/KittenTTS 2000).
+    # Gemini 32000, Edge 5000, Mistral 4000, NeuTTS/KittenTTS 2000).
     "tts": {
         "provider": "edge",  # "edge" (free) | "elevenlabs" (premium) | "openai" | "xai" | "minimax" | "mistral" | "gemini" | "neutts" (local) | "kittentts" (local) | "piper" (local)
         "edge": {
@@ -1572,6 +1580,19 @@ DEFAULT_CONFIG = {
             "voice": "alloy",
             # Voices: alloy, echo, fable, onyx, nova, shimmer
         },
+        "gemini": {
+            "model": "gemini-2.5-flash-preview-tts",
+            "voice": "Kore",
+            # When true, Gemini 3.1 TTS uses a hidden auxiliary-model rewrite
+            # pass to insert freeform square-bracket audio tags into the TTS
+            # script. Visible chat replies are unchanged.
+            "audio_tags": False,
+            # Optional local Markdown/text file with Gemini TTS performance
+            # direction. It may include AUDIO PROFILE, SCENE, DIRECTOR'S NOTES,
+            # SAMPLE CONTEXT, and either a `{transcript}` placeholder or no
+            # transcript section; Hermes appends the live transcript when absent.
+            "persona_prompt_file": "",
+        },
         "xai": {
             "voice_id": "eve",  # or custom voice ID — see https://docs.x.ai/developers/model-capabilities/audio/custom-voices
             "language": "en",
@@ -1653,18 +1674,19 @@ DEFAULT_CONFIG = {
     "memory": {
         "memory_enabled": True,
         "user_profile_enabled": True,
-        # Write gate for the memory tool (add/replace/remove), applied to BOTH
+        # Approval gate for memory writes (add/replace/remove), applied to BOTH
         # foreground agent turns and the background self-improvement review fork
-        # (the source of unprompted "wrong assumption" saves users reported):
-        #   on      — write freely (default, current behaviour)
-        #   off     — never write; the memory tool returns a clean disabled result
-        #   approve — foreground writes block on an inline approve/deny prompt
-        #             (entries are small enough to review in a chat bubble);
-        #             background-review writes are staged for review instead of
-        #             committed (a daemon thread cannot block on a prompt).
-        #             Pending entries: /memory pending, /memory approve <id>,
-        #             /memory reject <id>.
-        "write_mode": "on",
+        # (the source of unprompted "wrong assumption" saves users reported).
+        #   false (default) — write freely; the gate is off (pre-gate behaviour)
+        #   true            — require approval: foreground writes prompt inline
+        #                     (entries are small enough to review in a chat
+        #                     bubble); background-review writes are staged
+        #                     instead of committed (a daemon thread cannot block
+        #                     on a prompt). Review staged entries with
+        #                     /memory pending, /memory approve <id>,
+        #                     /memory reject <id>.
+        # To disable memory entirely, use memory_enabled: false instead.
+        "write_approval": False,
         "memory_char_limit": 2200,   # ~800 tokens at 2.75 chars/token
         "user_char_limit": 1375,     # ~500 tokens at 2.75 chars/token
         # External memory provider plugin (empty = built-in only).
@@ -1769,17 +1791,18 @@ DEFAULT_CONFIG = {
         # External hub installs (trusted/community sources) are always
         # scanned regardless of this setting.
         "guard_agent_created": False,
-        # Write gate for skill_manage (create/edit/patch/write_file/delete/
+        # Approval gate for skill_manage (create/edit/patch/write_file/delete/
         # remove_file), applied to BOTH foreground agent turns and the
-        # background self-improvement review fork:
-        #   on      — write freely (default, current behaviour)
-        #   off     — never write; skill_manage returns a clean disabled result
-        #   approve — stage the write for review instead of committing.
-        #             Pending skills are listed with /skills pending, reviewed
-        #             with /skills diff <id> (full diff — CLI/dashboard/file,
-        #             never crammed into a chat bubble), and applied with
-        #             /skills approve <id> or dropped with /skills reject <id>.
-        "write_mode": "on",
+        # background self-improvement review fork.
+        #   false (default) — write freely; the gate is off (pre-gate behaviour)
+        #   true            — require approval: stage the write for review
+        #                     instead of committing (a SKILL.md is too large to
+        #                     review inline, so skills always stage rather than
+        #                     prompt). List with /skills pending, inspect with
+        #                     /skills diff <id> (full diff — CLI/dashboard/file,
+        #                     never crammed into a chat bubble), apply with
+        #                     /skills approve <id> or drop with /skills reject <id>.
+        "write_approval": False,
     },
 
     # Curator — background skill maintenance.
@@ -2463,7 +2486,7 @@ DEFAULT_CONFIG = {
 
 
     # Config schema version - bump this when adding new required fields
-    "_config_version": 28,
+    "_config_version": 29,
 }
 
 # =============================================================================
@@ -4734,6 +4757,34 @@ def migrate_config(interactive: bool = True, quiet: bool = False) -> Dict[str, A
             if not quiet:
                 print("  ✓ Lowered model_catalog.ttl_hours to 1 (hourly picker refresh)")
 
+    # ── Version 28 → 29: rename memory/skills write_mode → write_approval ──
+    # The tri-state write_mode (on|off|approve) was replaced by a clear boolean
+    # write_approval (default false = gate off, writes flow freely; true =
+    # require approval). Only an explicit "approve" carried gating intent, so
+    # it maps to true; everything else (on/off/unset) → false. The old
+    # "off = block all writes" mode is dropped — memory_enabled: false disables
+    # memory entirely. Only rewrite a key the user actually persisted; never
+    # invent one.
+    if current_ver < 29:
+        config = read_raw_config()
+        touched = False
+        for subsystem in ("memory", "skills"):
+            sub = config.get(subsystem)
+            if not isinstance(sub, dict) or "write_mode" not in sub:
+                continue
+            old = sub.pop("write_mode")
+            old_norm = old.strip().lower() if isinstance(old, str) else old
+            sub["write_approval"] = (old_norm == "approve")
+            config[subsystem] = sub
+            touched = True
+            results["config_added"].append(
+                f"{subsystem}.write_mode → write_approval={sub['write_approval']}"
+            )
+        if touched:
+            save_config(config)
+            if not quiet:
+                print("  ✓ Renamed write_mode → write_approval (boolean gate)")
+
     if current_ver < latest_ver and not quiet:
         print(f"Config version: {current_ver} → {latest_ver}")
     
@@ -5719,19 +5770,21 @@ def save_env_value(key: str, value: str):
             f.flush()
             os.fsync(f.fileno())
         atomic_replace(tmp_path, env_path)
-        # Restore original permissions before _secure_file may tighten them.
+        # Preserve the original file mode (e.g. 0640 for Docker volume mounts)
+        # instead of letting _secure_file unconditionally tighten to 0600.
         if original_mode is not None:
             try:
                 os.chmod(env_path, original_mode)
             except OSError:
                 pass
+        else:
+            _secure_file(env_path)
     except BaseException:
         try:
             os.unlink(tmp_path)
         except OSError:
             pass
         raise
-    _secure_file(env_path)
 
     os.environ[key] = value
     invalidate_env_cache()
@@ -5776,18 +5829,22 @@ def remove_env_value(key: str) -> bool:
                 f.flush()
                 os.fsync(f.fileno())
             atomic_replace(tmp_path, env_path)
+            # Preserve the original file mode (e.g. 0640 for Docker volume
+            # mounts) instead of letting _secure_file unconditionally tighten
+            # to 0600. Mirrors save_env_value().
             if original_mode is not None:
                 try:
                     os.chmod(env_path, original_mode)
                 except OSError:
                     pass
+            else:
+                _secure_file(env_path)
         except BaseException:
             try:
                 os.unlink(tmp_path)
             except OSError:
                 pass
             raise
-        _secure_file(env_path)
 
     os.environ.pop(key, None)
     invalidate_env_cache()

hermes_cli/main.py

@@ -499,6 +499,7 @@ from hermes_cli import __version__, __release_date__
 # (god-file decomposition Phase 2). Re-imported here so select_provider_and_model and
 # existing test monkeypatches (hermes_cli.main._model_flow_*) keep resolving unchanged.
 from hermes_cli.model_setup_flows import (
+    _prompt_auth_credentials_choice,
     _model_flow_openrouter,
     _model_flow_nous,
     _model_flow_openai_codex,
@@ -2830,7 +2831,12 @@ def select_provider_and_model(args=None):
         member_labels = [
             provider_labels.get(m, m) for m in selected_members
         ]
-        member_idx = _prompt_provider_choice(member_labels, default=member_default)
+        group_label = ordered[provider_idx][1].split(" ▸", 1)[0]
+        member_idx = _prompt_provider_choice(
+            member_labels,
+            default=member_default,
+            title=f"Select {group_label} provider:",
+        )
         if member_idx is None:
             print("No change.")
             return
@@ -2974,6 +2980,7 @@ _AUX_TASKS: list[tuple[str, str, str]] = [
     ("approval", "Approval", "smart command approval"),
     ("mcp", "MCP", "MCP tool reasoning"),
     ("title_generation", "Title generation", "session titles"),
+    ("tts_audio_tags", "TTS audio tags", "Gemini TTS tag insertion"),
     ("skills_hub", "Skills hub", "skills search/install"),
     ("triage_specifier", "Triage specifier", "kanban spec fleshing"),
     ("kanban_decomposer", "Kanban decomposer", "task decomposition"),
@@ -3263,6 +3270,7 @@ def _aux_flow_provider_model(
             model_list,
             current_model=current_model,
             pricing=pricing,
+            confirm_provider=provider_slug,
         )
         if selected is None:
             print("No change.")
@@ -3331,7 +3339,7 @@ def _aux_flow_custom_endpoint(task: str, task_cfg: dict) -> None:
     print(f"{display_name}: custom ({short_url})" + (f" · {model}" if model else ""))
 
 
-def _prompt_provider_choice(choices, *, default=0):
+def _prompt_provider_choice(choices, *, default=0, title="Select provider:"):
     """Show provider selection menu with curses arrow-key navigation.
 
     Falls back to a numbered list when curses is unavailable (e.g. piped
@@ -3341,7 +3349,7 @@ def _prompt_provider_choice(choices, *, default=0):
     try:
         from hermes_cli.setup import _curses_prompt_choice
 
-        idx = _curses_prompt_choice("Select provider:", choices, default)
+        idx = _curses_prompt_choice(title, choices, default)
         if idx >= 0:
             print()
             return idx
@@ -3349,7 +3357,7 @@ def _prompt_provider_choice(choices, *, default=0):
         pass
 
     # Fallback: numbered list
-    print("Select provider:")
+    print(title)
     for i, c in enumerate(choices, 1):
         marker = "→" if i - 1 == default else " "
         print(f"  {marker} {i}. {c}")
@@ -6385,6 +6393,167 @@ def _load_installable_optional_extras(group: str = "all") -> list[str]:
     return referenced
 
 
+# Install-scoped breadcrumb dropped right before ``hermes update`` mutates the
+# venv and cleared only after the dependency install verifies clean.  If a user
+# kills the update mid-install (Ctrl-C, terminal close, WSL OOM), the marker
+# survives and the next ``hermes`` launch finishes the install instead of
+# limping along on a half-built venv (e.g. pip wiped, a core dep like Pillow
+# never landed).  Lives next to the venv (not under $HERMES_HOME) because the
+# venv is shared across all profiles, so a single marker covers every profile.
+def _update_marker_path() -> Path:
+    return PROJECT_ROOT / ".update-incomplete"
+
+
+def _write_update_incomplete_marker() -> None:
+    """Drop the interrupted-install breadcrumb. Never raises."""
+    try:
+        _update_marker_path().write_text(
+            f"started={_time.time()}\npid={os.getpid()}\n", encoding="utf-8"
+        )
+    except OSError as exc:
+        logger.debug("Could not write update-incomplete marker: %s", exc)
+
+
+def _clear_update_incomplete_marker() -> None:
+    """Remove the interrupted-install breadcrumb. Never raises."""
+    try:
+        _update_marker_path().unlink()
+    except FileNotFoundError:
+        pass
+    except OSError as exc:
+        logger.debug("Could not clear update-incomplete marker: %s", exc)
+
+
+def _recover_from_interrupted_install() -> None:
+    """Finish a dependency install that a prior ``hermes update`` left half-done.
+
+    Triggered on launch when ``.update-incomplete`` is present — meaning the
+    code was pulled but the dep install was killed before it verified clean.
+    Unconditionally bootstraps pip via ``ensurepip`` (a killed ``pip install``
+    can wipe pip from the venv entirely, which blocks the venv from recovering
+    on its own), then re-runs the editable ``.[all]`` install + core-dependency
+    verification, then clears the marker.
+
+    Never raises: a recovery failure must not block launch.  If it can't
+    self-heal it prints the one-line manual command and leaves the marker so
+    the next launch tries again.
+
+    Concurrency: the marker lives next to the shared venv, so a gateway start
+    plus a CLI launch (or two profiles starting at once) can both see it.  An
+    ``O_EXCL`` lockfile ensures only one process runs the reinstall; the
+    others skip and let the winner clear the marker.
+
+    Output: everything — our status lines AND the streamed pip/uv install
+    (which inherits fd 1) — is routed to stderr.  Launches whose stdout is a
+    protocol stream (``hermes acp`` speaks JSON-RPC on stdout) must never get
+    install noise on stdout.
+    """
+    if not _update_marker_path().exists():
+        return
+
+    # Skip in managed/Docker installs and on PyPI installs with no git checkout:
+    # those don't run the source-tree update path, so a stray marker is not ours
+    # to act on. Just clear it.
+    if not (PROJECT_ROOT / "pyproject.toml").is_file():
+        _clear_update_incomplete_marker()
+        return
+
+    # Single-flight guard: atomically claim the recovery lock. If another
+    # process holds it, skip — it is running the same reinstall into the same
+    # shared venv right now. A crashed holder leaves a stale lock; break it
+    # after an hour (well past any realistic install) so recovery can't be
+    # wedged forever.
+    lock_path = PROJECT_ROOT / ".update-incomplete.lock"
+    try:
+        fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        os.write(fd, f"{os.getpid()}\n".encode())
+        os.close(fd)
+    except FileExistsError:
+        try:
+            if _time.time() - lock_path.stat().st_mtime > 3600:
+                lock_path.unlink()
+        except OSError:
+            pass
+        return
+    except OSError as exc:
+        # Couldn't create the lock (read-only fs, perms). Proceed unlocked —
+        # the install itself will surface the real problem.
+        logger.debug("Could not create install-recovery lock: %s", exc)
+
+    saved_stdout_fd = None
+    saved_sys_stdout = sys.stdout
+    try:
+        # Route Python-level prints AND subprocess-inherited fd 1 to stderr
+        # for the duration of recovery (see docstring: ACP stdout safety).
+        try:
+            saved_stdout_fd = os.dup(1)
+            os.dup2(2, 1)
+        except OSError:
+            saved_stdout_fd = None
+        sys.stdout = sys.stderr
+
+        print(
+            "⚠ A previous `hermes update` was interrupted mid-install — "
+            "finishing dependency installation now..."
+        )
+
+        try:
+            from hermes_cli.managed_uv import ensure_uv
+
+            # Always bootstrap pip first: a killed install can leave the venv with
+            # no pip module at all, and uv may also be gone. ensurepip restores a
+            # known-good pip so at least the plain-pip path below can proceed.
+            try:
+                subprocess.run(
+                    [sys.executable, "-m", "ensurepip", "--upgrade", "--default-pip"],
+                    cwd=PROJECT_ROOT,
+                    capture_output=True,
+                )
+            except Exception as exc:
+                logger.debug("ensurepip during install recovery failed: %s", exc)
+
+            uv_bin = ensure_uv()
+            if uv_bin:
+                uv_env = {**os.environ, "VIRTUAL_ENV": str(PROJECT_ROOT / "venv")}
+                if _is_termux_env(uv_env):
+                    uv_env.pop("PYTHONPATH", None)
+                    uv_env.pop("PYTHONHOME", None)
+                _install_python_dependencies_with_optional_fallback(
+                    [uv_bin, "pip"],
+                    env=uv_env,
+                    group="termux-all" if _is_termux_env(uv_env) else "all",
+                )
+            else:
+                _install_python_dependencies_with_optional_fallback(
+                    [sys.executable, "-m", "pip"],
+                    group="termux-all" if _is_termux_env() else "all",
+                )
+
+            _clear_update_incomplete_marker()
+            print("✓ Dependency installation recovered — your install is healthy again.")
+        except Exception as exc:
+            # Leave the marker in place so the next launch retries. Give the user
+            # the exact manual recovery command in the meantime.
+            logger.debug("Interrupted-install recovery failed: %s", exc)
+            print("✗ Could not auto-recover the interrupted install.")
+            print("  Recover manually with:")
+            print(f"    cd {PROJECT_ROOT}")
+            print(f"    {sys.executable} -m ensurepip --upgrade")
+            print(f"    {sys.executable} -m pip install -e '.[all]'")
+    finally:
+        sys.stdout = saved_sys_stdout
+        if saved_stdout_fd is not None:
+            try:
+                os.dup2(saved_stdout_fd, 1)
+                os.close(saved_stdout_fd)
+            except OSError:
+                pass
+        try:
+            lock_path.unlink()
+        except OSError:
+            pass
+
+
 def _run_install_with_heartbeat(
     cmd: list[str],
     *,
@@ -8316,6 +8485,13 @@ def _cmd_update_impl(args, gateway_mode: bool):
         # Reinstall Python dependencies. Prefer .[all], but if one optional extra
         # breaks on this machine, keep base deps and reinstall the remaining extras
         # individually so update does not silently strip working capabilities.
+        #
+        # Drop the interrupted-install breadcrumb BEFORE touching the venv. If
+        # the install is killed mid-flight (Ctrl-C, terminal close, WSL OOM),
+        # the marker survives and the next ``hermes`` launch finishes the
+        # install via ``_recover_from_interrupted_install``. Cleared only after
+        # the install + core-dependency verification completes below.
+        _write_update_incomplete_marker()
         print("→ Updating Python dependencies...")
         from hermes_cli.managed_uv import ensure_uv, update_managed_uv
 
@@ -8369,6 +8545,12 @@ def _cmd_update_impl(args, gateway_mode: bool):
                 _install_psutil_android_compat(pip_cmd)
             _install_python_dependencies_with_optional_fallback(pip_cmd, group=install_group)
 
+        # Core Python deps installed AND verified (the fallback helper runs
+        # _verify_core_dependencies_installed). Clear the interrupted-install
+        # breadcrumb now — the remaining steps (lazy refresh, node deps, web
+        # UI, desktop rebuild) are non-core and can't brick the venv.
+        _clear_update_incomplete_marker()
+
         _refresh_active_lazy_features()
 
         _update_node_dependencies()
@@ -10683,6 +10865,22 @@ def main():
     except Exception:
         pass
 
+    # Self-heal a venv left half-built by an interrupted ``hermes update``
+    # (Ctrl-C, terminal close, WSL OOM mid-install). Skip when the user is
+    # *running* update — that flow writes and clears its own marker, and we
+    # don't want a recovery install racing the real one. Never raises.
+    #
+    # The substring match is deliberately loose: argv isn't parsed yet at this
+    # point, and the failure modes are asymmetric. Over-matching (e.g.
+    # ``hermes skills install update``) merely defers recovery one launch;
+    # under-matching (missing ``hermes -p work update``) would race a recovery
+    # install against the real one. Loose wins.
+    try:
+        if "update" not in sys.argv[1:]:
+            _recover_from_interrupted_install()
+    except Exception:
+        pass
+
     if _try_termux_fast_tui_launch():
         return
     if _try_termux_fast_cli_launch():

hermes_cli/model_cost_guard.py

@@ -0,0 +1,134 @@
+"""Expensive-model confirmation helpers for model selection surfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal, InvalidOperation
+from typing import Optional
+
+from agent.models_dev import ModelInfo
+
+
+INPUT_COST_WARNING_THRESHOLD = Decimal("20")
+OUTPUT_COST_WARNING_THRESHOLD = Decimal("100")
+GPT55_PRO_OPENROUTER_ID = "openai/gpt-5.5-pro"
+GPT55_SUGGESTION = "did you mean to select openai/gpt-5.5?"
+
+
+@dataclass(frozen=True)
+class ExpensiveModelWarning:
+    """Confirmation payload for models above Hermes' cost guardrail."""
+
+    model: str
+    provider: str
+    input_cost_per_million: Optional[Decimal]
+    output_cost_per_million: Optional[Decimal]
+    source: str
+    message: str
+
+
+def _to_decimal(value: object) -> Optional[Decimal]:
+    if value is None:
+        return None
+    try:
+        return Decimal(str(value))
+    except (InvalidOperation, ValueError):
+        return None
+
+
+def _format_money(value: Optional[Decimal]) -> str:
+    if value is None:
+        return "unknown"
+    return f"${value:.2f}/M"
+
+
+def _pricing_from_model_info(
+    model_info: Optional[ModelInfo],
+) -> tuple[Optional[Decimal], Optional[Decimal], str]:
+    if model_info is None or not model_info.has_cost_data():
+        return None, None, ""
+    return (
+        _to_decimal(model_info.cost_input),
+        _to_decimal(model_info.cost_output),
+        "models.dev",
+    )
+
+
+def expensive_model_warning(
+    model_name: str,
+    *,
+    provider: Optional[str] = None,
+    base_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    model_info: Optional[ModelInfo] = None,
+) -> Optional[ExpensiveModelWarning]:
+    """Return a warning payload when known pricing exceeds safety thresholds.
+
+    The guard only triggers when pricing is known. Callers should use this after
+    model resolution so aliases and provider-specific model IDs have settled.
+    """
+    model = (model_name or "").strip()
+    if not model:
+        return None
+
+    input_cost, output_cost, source = _pricing_from_model_info(model_info)
+    if input_cost is None and output_cost is None and provider:
+        try:
+            from agent.models_dev import get_model_info
+
+            input_cost, output_cost, source = _pricing_from_model_info(
+                get_model_info(provider, model)
+            )
+        except Exception:
+            pass
+    if input_cost is None and output_cost is None:
+        try:
+            from agent.usage_pricing import get_pricing_entry
+
+            entry = get_pricing_entry(
+                model,
+                provider=provider,
+                base_url=base_url,
+                api_key=api_key,
+            )
+        except Exception:
+            entry = None
+        if entry is not None:
+            input_cost = entry.input_cost_per_million
+            output_cost = entry.output_cost_per_million
+            source = entry.source
+
+    over_input = (
+        input_cost is not None and input_cost > INPUT_COST_WARNING_THRESHOLD
+    )
+    over_output = (
+        output_cost is not None and output_cost > OUTPUT_COST_WARNING_THRESHOLD
+    )
+    if not over_input and not over_output:
+        return None
+
+    lines = [
+        "!!! EXPENSIVE MODEL WARNING !!!",
+        "",
+        f"{model} has known pricing above Hermes' safety threshold.",
+        f"Input tokens: {_format_money(input_cost)}",
+        f"Output tokens: {_format_money(output_cost)}",
+        (
+            "Threshold: more than $20/M input tokens or more than "
+            "$100/M output tokens."
+        ),
+    ]
+    if source:
+        lines.append(f"Pricing source: {source}.")
+    if model.lower() == GPT55_PRO_OPENROUTER_ID:
+        lines.append(GPT55_SUGGESTION)
+    lines.append("Confirm only if you intend to use this model.")
+
+    return ExpensiveModelWarning(
+        model=model,
+        provider=(provider or "").strip(),
+        input_cost_per_million=input_cost,
+        output_cost_per_million=output_cost,
+        source=source or "unknown",
+        message="\n".join(lines),
+    )

hermes_cli/model_setup_flows.py

@@ -25,6 +25,44 @@ import os
 import subprocess
 
 
+def _prompt_auth_credentials_choice(title: str) -> str:
+    """Prompt for reuse / reauthenticate / cancel with the standard radio UI.
+
+    Returns one of ``"use"``, ``"reauth"``, ``"cancel"``. Falls back to a
+    numbered prompt when curses is unavailable (piped stdin, non-TTY).
+    """
+    choices = [
+        "Use existing credentials",
+        "Reauthenticate (new OAuth login)",
+        "Cancel",
+    ]
+    try:
+        from hermes_cli.setup import _curses_prompt_choice
+
+        idx = _curses_prompt_choice(title, choices, 0)
+        if idx >= 0:
+            print()
+            return ("use", "reauth", "cancel")[idx]
+    except Exception:
+        pass
+
+    print(title)
+    for i, label in enumerate(choices, 1):
+        marker = "→" if i == 1 else " "
+        print(f"  {marker} {i}. {label}")
+    print()
+    try:
+        choice = input("  Choice [1/2/3]: ").strip()
+    except (KeyboardInterrupt, EOFError):
+        choice = "1"
+
+    if choice == "2":
+        return "reauth"
+    if choice == "3":
+        return "cancel"
+    return "use"
+
+
 def _model_flow_openrouter(config, current_model=""):
     """OpenRouter provider: ensure API key, then pick model."""
     from hermes_cli.main import _prompt_api_key
@@ -64,7 +102,12 @@ def _model_flow_openrouter(config, current_model=""):
     pricing = get_pricing_for_provider("openrouter", force_refresh=True)
 
     selected = _prompt_model_selection(
-        openrouter_models, current_model=current_model, pricing=pricing
+        openrouter_models,
+        current_model=current_model,
+        pricing=pricing,
+        confirm_provider="openrouter",
+        confirm_base_url=OPENROUTER_BASE_URL,
+        confirm_api_key=_resolved or existing_key,
     )
     if selected:
         _save_model_choice(selected)
@@ -273,6 +316,9 @@ def _model_flow_nous(config, current_model="", args=None):
         unavailable_models=unavailable_models,
         portal_url=_nous_portal_url,
         unavailable_message=unavailable_message,
+        confirm_provider="nous",
+        confirm_base_url=creds.get("base_url", ""),
+        confirm_api_key=creds.get("api_key", ""),
     )
     if selected:
         _save_model_choice(selected)
@@ -321,16 +367,9 @@ def _model_flow_openai_codex(config, current_model=""):
     if status.get("logged_in"):
         print("  OpenAI Codex credentials: ✓")
         print()
-        print("    1. Use existing credentials")
-        print("    2. Reauthenticate (new OAuth login)")
-        print("    3. Cancel")
-        print()
-        try:
-            choice = input("  Choice [1/2/3]: ").strip()
-        except (KeyboardInterrupt, EOFError):
-            choice = "1"
+        choice = _prompt_auth_credentials_choice("OpenAI Codex credentials:")
 
-        if choice == "2":
+        if choice == "reauth":
             print("Starting a fresh OpenAI Codex login...")
             print()
             try:
@@ -350,7 +389,7 @@ def _model_flow_openai_codex(config, current_model=""):
             if not status.get("logged_in"):
                 print("Login failed.")
                 return
-        elif choice == "3":
+        elif choice == "cancel":
             return
     else:
         print("Not logged into OpenAI Codex. Starting login...")
@@ -385,7 +424,13 @@ def _model_flow_openai_codex(config, current_model=""):
 
     codex_models = get_codex_model_ids(access_token=_codex_token)
 
-    selected = _prompt_model_selection(codex_models, current_model=current_model)
+    selected = _prompt_model_selection(
+        codex_models,
+        current_model=current_model,
+        confirm_provider="openai-codex",
+        confirm_base_url=DEFAULT_CODEX_BASE_URL,
+        confirm_api_key=_codex_token or "",
+    )
     if selected:
         _save_model_choice(selected)
         _update_config_for_provider("openai-codex", DEFAULT_CODEX_BASE_URL)
@@ -411,16 +456,11 @@ def _model_flow_xai_oauth(_config, current_model="", *, args=None):
     if status.get("logged_in"):
         print("  xAI Grok OAuth (SuperGrok / Premium+) credentials: ✓")
         print()
-        print("    1. Use existing credentials")
-        print("    2. Reauthenticate (new OAuth login)")
-        print("    3. Cancel")
-        print()
-        try:
-            choice = input("  Choice [1/2/3]: ").strip()
-        except (KeyboardInterrupt, EOFError):
-            choice = "1"
+        choice = _prompt_auth_credentials_choice(
+            "xAI Grok OAuth (SuperGrok / Premium+) credentials:"
+        )
 
-        if choice == "2":
+        if choice == "reauth":
             print("Starting a fresh xAI OAuth login...")
             print()
             try:
@@ -444,7 +484,7 @@ def _model_flow_xai_oauth(_config, current_model="", *, args=None):
             except Exception as exc:
                 print(f"Login failed: {exc}")
                 return
-        elif choice == "3":
+        elif choice == "cancel":
             return
     else:
         print("Not logged into xAI Grok OAuth (SuperGrok / Premium+). Starting login...")
@@ -520,7 +560,12 @@ def _model_flow_qwen_oauth(_config, current_model=""):
         models = list(_DEFAULT_QWEN_PORTAL_MODELS)
 
     default = current_model or (models[0] if models else "qwen3-coder-plus")
-    selected = _prompt_model_selection(models, current_model=default)
+    selected = _prompt_model_selection(
+        models,
+        current_model=default,
+        confirm_provider="qwen-oauth",
+        confirm_base_url=DEFAULT_QWEN_BASE_URL,
+    )
     if selected:
         _save_model_choice(selected)
         _update_config_for_provider("qwen-oauth", DEFAULT_QWEN_BASE_URL)
@@ -569,7 +614,12 @@ def _model_flow_minimax_oauth(config, current_model="", args=None):
     from hermes_cli.models import _PROVIDER_MODELS
 
     model_ids = _PROVIDER_MODELS.get("minimax-oauth", [])
-    selected = _prompt_model_selection(model_ids, current_model)
+    selected = _prompt_model_selection(
+        model_ids,
+        current_model,
+        confirm_provider="minimax-oauth",
+        confirm_base_url=creds["base_url"],
+    )
     if not selected:
         return
     _save_model_choice(selected)
@@ -638,7 +688,12 @@ def _model_flow_google_gemini_cli(_config, current_model=""):
 
     models = list(_PROVIDER_MODELS.get("google-gemini-cli") or [])
     default = current_model or (models[0] if models else "gemini-3-flash-preview")
-    selected = _prompt_model_selection(models, current_model=default)
+    selected = _prompt_model_selection(
+        models,
+        current_model=default,
+        confirm_provider="google-gemini-cli",
+        confirm_base_url=DEFAULT_GEMINI_CLOUDCODE_BASE_URL,
+    )
     if selected:
         _save_model_choice(selected)
         _update_config_for_provider(
@@ -1563,7 +1618,11 @@ def _model_flow_copilot(config, current_model=""):
 
     if model_list:
         selected = _prompt_model_selection(
-            model_list, current_model=normalized_current_model
+            model_list,
+            current_model=normalized_current_model,
+            confirm_provider=provider_id,
+            confirm_base_url=effective_base,
+            confirm_api_key=api_key,
         )
     else:
         try:
@@ -1701,6 +1760,9 @@ def _model_flow_copilot_acp(config, current_model=""):
         selected = _prompt_model_selection(
             model_list,
             current_model=normalized_current_model,
+            confirm_provider=provider_id,
+            confirm_base_url=effective_base,
+            confirm_api_key=catalog_api_key,
         )
     else:
         try:
@@ -1805,7 +1867,13 @@ def _model_flow_kimi(config, current_model=""):
         model_list = _PROVIDER_MODELS.get("moonshot", [])
 
     if model_list:
-        selected = _prompt_model_selection(model_list, current_model=current_model)
+        selected = _prompt_model_selection(
+            model_list,
+            current_model=current_model,
+            confirm_provider=provider_id,
+            confirm_base_url=effective_base,
+            confirm_api_key=existing_key,
+        )
     else:
         try:
             selected = input("Enter model name: ").strip()
@@ -1913,7 +1981,13 @@ def _model_flow_stepfun(config, current_model=""):
             )
 
     if model_list:
-        selected = _prompt_model_selection(model_list, current_model=current_model)
+        selected = _prompt_model_selection(
+            model_list,
+            current_model=current_model,
+            confirm_provider=provider_id,
+            confirm_base_url=effective_base,
+            confirm_api_key=existing_key,
+        )
     else:
         try:
             selected = input("Model name: ").strip()
@@ -1989,7 +2063,13 @@ def _model_flow_bedrock_api_key(config, region, current_model=""):
     print(f"  Showing {len(model_list)} curated models")
 
     if model_list:
-        selected = _prompt_model_selection(model_list, current_model=current_model)
+        selected = _prompt_model_selection(
+            model_list,
+            current_model=current_model,
+            confirm_provider="custom",
+            confirm_base_url=mantle_base_url,
+            confirm_api_key=existing_key,
+        )
     else:
         try:
             selected = input("  Model ID: ").strip()
@@ -2178,7 +2258,12 @@ def _model_flow_bedrock(config, current_model=""):
 
     # 4. Model selection
     if model_list:
-        selected = _prompt_model_selection(model_list, current_model=current_model)
+        selected = _prompt_model_selection(
+            model_list,
+            current_model=current_model,
+            confirm_provider="bedrock",
+            confirm_base_url=f"https://bedrock-runtime.{region}.amazonaws.com",
+        )
     else:
         try:
             selected = input("  Model ID: ").strip()
@@ -2462,7 +2547,13 @@ def _model_flow_api_key_provider(config, provider_id, current_model=""):
         model_list = list(dict.fromkeys(mid for mid in model_list if mid))
 
     if model_list:
-        selected = _prompt_model_selection(model_list, current_model=current_model)
+        selected = _prompt_model_selection(
+            model_list,
+            current_model=current_model,
+            confirm_provider=provider_id,
+            confirm_base_url=effective_base,
+            confirm_api_key=existing_key,
+        )
     else:
         try:
             selected = input("Model name: ").strip()
@@ -2560,20 +2651,13 @@ def _model_flow_anthropic(config, current_model=""):
         elif cc_available:
             print("  Claude Code credentials: ✓ (auto-detected)")
         print()
-        print("    1. Use existing credentials")
-        print("    2. Reauthenticate (new OAuth login)")
-        print("    3. Cancel")
-        print()
-        try:
-            choice = input("  Choice [1/2/3]: ").strip()
-        except (KeyboardInterrupt, EOFError):
-            choice = "1"
+        choice = _prompt_auth_credentials_choice("Anthropic credentials:")
 
-        if choice == "2":
+        if choice == "reauth":
             needs_auth = True
-        elif choice == "3":
+        elif choice == "cancel":
             return
-        # choice == "1" or default: use existing, proceed to model selection
+        # choice == "use" or default: use existing, proceed to model selection
 
     if needs_auth:
         # Show auth method choice
@@ -2619,7 +2703,11 @@ def _model_flow_anthropic(config, current_model=""):
     # Model selection
     model_list = _PROVIDER_MODELS.get("anthropic", [])
     if model_list:
-        selected = _prompt_model_selection(model_list, current_model=current_model)
+        selected = _prompt_model_selection(
+            model_list,
+            current_model=current_model,
+            confirm_provider="anthropic",
+        )
     else:
         try:
             selected = input("Model name (e.g., claude-sonnet-4-20250514): ").strip()

hermes_cli/skills_hub.py

@@ -351,13 +351,29 @@ def do_browse(page: int = 1, page_size: int = 20, source: str = "all",
         "lobehub": 500, "browse-sh": 500,
     }
 
-    with c.status("[bold]Fetching skills from registries..."):
+    with c.status("[bold]Fetching skills from registries...") as status:
+        # Live progress: tick off each source as it resolves so the wait is
+        # visible instead of a frozen spinner. parallel_search_sources invokes
+        # this callback from the collecting thread as each source completes;
+        # the page itself is still rendered once, after the correctly-merged
+        # and trust-sorted result set is final (browse's ordering contract is
+        # computed over the whole set, so we never render a half-sorted page).
+        _done: List[str] = []
+
+        def _on_source_done(sid: str, count: int) -> None:
+            _done.append(f"{sid} ({count})")
+            status.update(
+                "[bold]Fetching skills from registries...[/]  "
+                f"[dim]done: {', '.join(_done)}[/]"
+            )
+
         all_results, source_counts, timed_out = parallel_search_sources(
             sources,
             query="",
             per_source_limits=_PER_SOURCE_LIMIT,
             source_filter=source,
             overall_timeout=30,
+            on_source_done=_on_source_done,
         )
 
     if not all_results:

hermes_cli/web_server.py

@@ -246,7 +246,31 @@ def _has_valid_session_token(request: Request) -> bool:
 
 
 def _require_token(request: Request) -> None:
-    """Validate the ephemeral session token.  Raises 401 on mismatch."""
+    """Authorize a sensitive endpoint, raising 401 if the caller isn't allowed.
+
+    Two auth schemes protect the dashboard, exactly one active per bind:
+
+    * **Loopback / ``--insecure`` mode** (``auth_required`` False): the
+      ephemeral ``_SESSION_TOKEN`` is injected into the SPA HTML and echoed
+      back via ``X-Hermes-Session-Token`` (or the legacy ``Bearer`` header).
+      Validate it here.
+    * **Gated / OAuth mode** (``auth_required`` True): ``_SESSION_TOKEN`` is
+      NOT injected (the SPA authenticates with a session cookie), so there is
+      no token to check. The ``gated_auth_middleware`` has already verified the
+      cookie before the request reached this handler — any non-public ``/api/``
+      route it lets through carries a verified ``request.state.session``. The
+      legacy ``auth_middleware`` likewise short-circuits in this mode. Requiring
+      the (absent) token here would 401 every cookie-authenticated request,
+      making plugin install/enable/disable and the other ``_require_token``
+      endpoints permanently unreachable behind the gate. Defer to the gate.
+    """
+    if getattr(request.app.state, "auth_required", False):
+        # Gate is authoritative. It attaches ``request.state.session`` on
+        # success and 401s otherwise, so a request that reached us is already
+        # authenticated. Belt-and-braces: confirm the session is present.
+        if getattr(request.state, "session", None) is not None:
+            return
+        raise HTTPException(status_code=401, detail="Unauthorized")
     if not _has_valid_session_token(request):
         raise HTTPException(status_code=401, detail="Unauthorized")
 
@@ -633,21 +657,6 @@ class AudioTranscriptionRequest(BaseModel):
     mime_type: Optional[str] = None
 
 
-class ModelAssignment(BaseModel):
-    """Payload for POST /api/model/set — assign a provider/model to a slot.
-
-    scope="main"        → writes model.provider + model.default
-    scope="auxiliary"   → writes auxiliary.<task>.provider + auxiliary.<task>.model
-    scope="auxiliary" with task=""  → applied to every auxiliary.* slot
-    scope="auxiliary" with task="__reset__"  → resets every slot to provider="auto"
-    """
-
-    scope: str
-    provider: str
-    model: str
-    task: str = ""
-
-
 _AUDIO_MIME_EXTENSIONS: Dict[str, str] = {
     "audio/aac": ".aac",
     "audio/flac": ".flac",
@@ -689,6 +698,7 @@ class ModelAssignment(BaseModel):
     # reads model.base_url from config (it ignores OPENAI_BASE_URL), so this is
     # the path that actually wires a local endpoint into resolution.
     base_url: str = ""
+    confirm_expensive_model: bool = False
 
 
 def _apply_main_model_assignment(
@@ -1362,11 +1372,28 @@ def _tail_lines(path: Path, n: int) -> List[str]:
     return lines[-n:] if n > 0 else lines
 
 
+def _spawn_gateway_restart() -> Tuple[subprocess.Popen, bool]:
+    """Spawn ``hermes gateway restart``, reusing an in-flight restart.
+
+    Multiple dashboard paths can request a restart in quick succession
+    (restart button double-click, or a stale cached frontend firing its own
+    restart after the server already auto-restarted post-onboarding). Two
+    concurrent ``hermes gateway restart`` children race each other on the
+    manual kill-and-start path, so reuse the live one instead.
+
+    Returns ``(proc, reused)``.
+    """
+    existing = _ACTION_PROCS.get("gateway-restart")
+    if existing is not None and existing.poll() is None:
+        return existing, True
+    return _spawn_hermes_action(["gateway", "restart"], "gateway-restart"), False
+
+
 @app.post("/api/gateway/restart")
 async def restart_gateway():
     """Kick off a ``hermes gateway restart`` in the background."""
     try:
-        proc = _spawn_hermes_action(["gateway", "restart"], "gateway-restart")
+        proc, _reused = _spawn_gateway_restart()
     except Exception as exc:
         _log.exception("Failed to spawn gateway restart")
         raise HTTPException(status_code=500, detail=f"Failed to restart gateway: {exc}")
@@ -2446,6 +2473,30 @@ async def set_model_assignment(body: ModelAssignment):
     try:
         cfg = load_config()
 
+        if model and not body.confirm_expensive_model:
+            try:
+                from hermes_cli.model_cost_guard import expensive_model_warning
+
+                # Pricing lookup can hit models.dev / a /models endpoint on a
+                # cache miss — keep it off the event loop.
+                warning = await asyncio.to_thread(
+                    expensive_model_warning,
+                    model,
+                    provider=provider,
+                    base_url=base_url,
+                )
+            except Exception:
+                warning = None
+            if warning is not None:
+                return {
+                    "ok": False,
+                    "scope": scope,
+                    "provider": provider,
+                    "model": model,
+                    "confirm_required": True,
+                    "confirm_message": warning.message,
+                }
+
         if scope == "main":
             if not provider or not model:
                 raise HTTPException(status_code=400, detail="provider and model required for main")
@@ -3714,6 +3765,34 @@ async def get_telegram_onboarding_status(pairing_id: str):
     )
 
 
+def _restart_gateway_after_telegram_onboarding() -> dict[str, Any]:
+    """Best-effort gateway restart after saving Telegram QR onboarding.
+
+    The QR flow naturally pulls users into Telegram on another device. If the
+    saved token waits on a separate dashboard restart click, Hermes appears
+    broken from the chat side. Keep the config save authoritative, but report
+    restart failures so the UI can fall back to the existing manual banner.
+    """
+    try:
+        proc, reused = _spawn_gateway_restart()
+    except Exception as exc:
+        _log.exception("Failed to auto-restart gateway after Telegram onboarding")
+        return {
+            "restart_started": False,
+            "restart_error": str(exc),
+        }
+    if reused:
+        _log.info(
+            "Telegram onboarding: reusing in-flight gateway restart (pid %s)",
+            proc.pid,
+        )
+    return {
+        "restart_started": True,
+        "restart_action": "gateway-restart",
+        "restart_pid": proc.pid,
+    }
+
+
 @app.post("/api/messaging/telegram/onboarding/{pairing_id}/apply")
 async def apply_telegram_onboarding(
     pairing_id: str, body: TelegramOnboardingApply
@@ -3768,11 +3847,14 @@ async def apply_telegram_onboarding(
     with _telegram_onboarding_lock:
         _telegram_onboarding_pairings.pop(pairing_id, None)
 
+    restart_result = _restart_gateway_after_telegram_onboarding()
+
     return {
         "ok": True,
         "platform": "telegram",
         "bot_username": bot_username,
-        "needs_restart": True,
+        "needs_restart": not restart_result["restart_started"],
+        **restart_result,
     }
 
 

hermes_cli/write_approval_commands.py

@@ -20,7 +20,10 @@ from typing import List, Optional
 
 from tools import write_approval as wa
 
-_VALID_MODES = (wa.MODE_ON, wa.MODE_OFF, wa.MODE_APPROVE)
+
+def _fmt_state(subsystem: str) -> str:
+    on = wa.write_approval_enabled(subsystem)
+    return f"{subsystem}.write_approval = {'on' if on else 'off'}"
 
 
 # ---------------------------------------------------------------------------
@@ -63,18 +66,17 @@ def handle_pending_subcommand(
         memory_store: live MemoryStore for applying approved memory writes
             (CLI passes ``self.agent._memory_store``; gateway applies against a
             freshly loaded store).
-        set_mode_fn: optional callable ``(mode: str) -> None`` that persists the
-            new write_mode to config (gateway provides this; CLI uses its own
-            ``save_config_value`` and passes a closure).
+        set_mode_fn: optional callable ``(enabled: bool) -> None`` that
+            persists the new write_approval boolean to config (gateway provides
+            this; CLI uses its own ``save_config_value`` and passes a closure).
 
     Returns a text string to show the user. Returns None when the args are not
     a write-approval subcommand (caller falls through to its other handling,
     e.g. /skills search).
     """
     if not args:
-        # Bare /memory or /skills with no sub → show pending + current mode.
-        mode = wa.get_write_mode(subsystem)
-        return f"{subsystem}.write_mode = {mode}\n\n" + _fmt_pending_list(subsystem)
+        # Bare /memory or /skills with no sub → show pending + gate state.
+        return f"{_fmt_state(subsystem)}\n\n" + _fmt_pending_list(subsystem)
 
     sub = args[0].lower()
     rest = args[1:]
@@ -91,8 +93,8 @@ def handle_pending_subcommand(
     if sub == "diff" and subsystem == wa.SKILLS:
         return _diff(rest)
 
-    if sub == "mode":
-        return _set_mode(subsystem, rest, set_mode_fn)
+    if sub in {"approval", "mode"}:  # 'mode' kept as a back-compat alias
+        return _set_approval(subsystem, rest, set_mode_fn)
 
     return None  # not ours — caller handles
 
@@ -179,19 +181,29 @@ def _diff(rest: List[str]) -> str:
     return header + "\n" + diff
 
 
-def _set_mode(subsystem: str, rest: List[str], set_mode_fn) -> str:
+def _set_approval(subsystem: str, rest: List[str], set_mode_fn) -> str:
+    """Turn the approval gate on/off for a subsystem.
+
+    ``set_mode_fn`` (when provided) persists the new boolean to config.
+    """
     if not rest:
-        cur = wa.get_write_mode(subsystem)
-        return (f"{subsystem}.write_mode = {cur}\n"
-                f"Set with: /{subsystem} mode <on|off|approve>")
-    mode = rest[0].lower()
-    if mode not in _VALID_MODES:
-        return f"Invalid mode '{mode}'. Use: on, off, approve."
+        return (f"{_fmt_state(subsystem)}\n"
+                f"Set with: /{subsystem} approval <on|off>")
+    arg = rest[0].strip().lower()
+    truthy = {"on", "true", "yes", "1", "enable", "enabled"}
+    falsey = {"off", "false", "no", "0", "disable", "disabled"}
+    if arg in truthy:
+        enabled = True
+    elif arg in falsey:
+        enabled = False
+    else:
+        return f"Invalid value '{arg}'. Use: on or off."
     if set_mode_fn is None:
-        return (f"To change {subsystem} write mode, run:\n"
-                f"  hermes config set {subsystem}.write_mode {mode}")
+        val = "true" if enabled else "false"
+        return (f"To change the {subsystem} approval gate, run:\n"
+                f"  hermes config set {subsystem}.write_approval {val}")
     try:
-        set_mode_fn(mode)
+        set_mode_fn(enabled)
     except Exception as e:
-        return f"Failed to set {subsystem}.write_mode: {e}"
-    return f"{subsystem}.write_mode set to '{mode}'."
+        return f"Failed to set {subsystem}.write_approval: {e}"
+    return f"{subsystem}.write_approval set to '{'on' if enabled else 'off'}'."

plugins/model-providers/openrouter/__init__.py

@@ -116,6 +116,8 @@ class OpenRouterProfile(ProviderProfile):
         the same backend server across turns.
         """
         extra_body: dict[str, Any] = {}
+        top_level: dict[str, Any] = {}
+        extra_headers: dict[str, Any] = {}
         if supports_reasoning:
             # Reasoning-mandatory Anthropic models (Claude 4.6+ / fable /
             # future named models) use *adaptive* thinking: the model decides
@@ -132,18 +134,36 @@ class OpenRouterProfile(ProviderProfile):
             # The only reliable behavior is to omit ``reasoning`` and let the
             # model default to adaptive. See hermes-agent#42991 (disable case)
             # and the tool-replay follow-up.
+            #
+            # ``reasoning.effort`` being ignored does NOT mean these models have
+            # no effort lever — OpenRouter honors the requested effort on the
+            # top-level ``verbosity`` field instead (it maps to Anthropic's
+            # ``output_config.effort``; ``reasoning.effort`` is accepted but
+            # ignored — confirmed by OpenRouter's Claude migration docs and a
+            # live token-spend probe in hermes-agent#43432). Route the existing
+            # ``reasoning_config["effort"]`` (sourced from
+            # ``agent.reasoning_effort``) onto ``verbosity`` so the knob the user
+            # already sets keeps working for these models. We still send NO
+            # ``reasoning`` field, preserving the #42991 400 fix.
             if _anthropic_reasoning_is_mandatory(model):
-                pass  # omit reasoning entirely → adaptive default
+                cfg = reasoning_config or {}
+                effort = cfg.get("effort")
+                # Only emit when effort is actually requested and reasoning
+                # isn't explicitly disabled. Otherwise omit ``verbosity`` so the
+                # model keeps its own adaptive default (``high``).
+                if cfg.get("enabled", True) is not False and effort and effort != "none":
+                    top_level["verbosity"] = effort
             elif reasoning_config is not None:
                 extra_body["reasoning"] = dict(reasoning_config)
             else:
                 extra_body["reasoning"] = {"enabled": True, "effort": "medium"}
 
-        extra_headers: dict[str, Any] = {}
         if session_id and model and model.startswith(("x-ai/grok-", "xai/grok-")):
             extra_headers["x-grok-conv-id"] = session_id
+        if extra_headers:
+            top_level["extra_headers"] = extra_headers
 
-        return extra_body, {"extra_headers": extra_headers} if extra_headers else {}
+        return extra_body, top_level
 
 
 openrouter = OpenRouterProfile(

plugins/platforms/discord/adapter.py

@@ -602,6 +602,11 @@ class DiscordAdapter(BasePlatformAdapter):
         self._voice_listen_tasks: Dict[int, asyncio.Task] = {}  # guild_id -> listen loop
         self._voice_input_callback: Optional[Callable] = None  # set by run.py
         self._on_voice_disconnect: Optional[Callable] = None  # set by run.py
+        # Resolves the current voice-reply mode ("off"|"voice_only"|"all") for a
+        # linked text-channel id; set by run.py. Lets the inactivity timer leave
+        # the bot in the channel when the user deliberately picked text-only
+        # (/voice off) instead of leaving (/voice leave).
+        self._voice_mode_getter: Optional[Callable] = None  # set by run.py
         # Phase 3: continuous voice mixer (ambient idle bed + ducked speech).
         # Installed once per guild on join; lets acks / TTS / the "thinking"
         # loop overlap in one outgoing stream instead of stop-and-swap.
@@ -789,6 +794,7 @@ class DiscordAdapter(BasePlatformAdapter):
                 # Must run BEFORE the user allowlist check so that bots
                 # permitted by DISCORD_ALLOW_BOTS are not rejected for
                 # not being in DISCORD_ALLOWED_USERS (fixes #4466).
+                _role_authorized = False
                 if getattr(message.author, "bot", False):
                     allow_bots = os.getenv("DISCORD_ALLOW_BOTS", "none").lower().strip()
                     if allow_bots == "none":
@@ -812,6 +818,7 @@ class DiscordAdapter(BasePlatformAdapter):
                         is_dm=_is_dm,
                     ):
                         return
+                    _role_authorized = bool(getattr(self, "_allowed_role_ids", set()))
                 
                 # Multi-agent filtering: if the message mentions specific bots
                 # but NOT this bot, the sender is talking to another agent —
@@ -853,7 +860,7 @@ class DiscordAdapter(BasePlatformAdapter):
                         if "*" not in _free_channels and not (_channel_ids & _free_channels):
                             return
 
-                await self._handle_message(message)
+                await self._handle_message(message, role_authorized=_role_authorized)
 
             @self._client.event
             async def on_voice_state_update(member, before, after):
@@ -2265,6 +2272,20 @@ class DiscordAdapter(BasePlatformAdapter):
         except asyncio.CancelledError:
             return
         text_ch_id = self._voice_text_channels.get(guild_id)
+        # ``/voice off`` mutes spoken replies but deliberately keeps the bot in
+        # the channel (leaving is ``/voice leave``). The inactivity timer only
+        # counts the bot's OWN audio as activity, so under voice-off mode it
+        # fires every VOICE_TIMEOUT seconds, yanks the bot out, and spams the
+        # text channel with "Left voice channel (inactivity timeout)." Honor the
+        # user's choice: skip the auto-disconnect while voice replies are off.
+        # (The timer re-arms when the bot next speaks or hears a user.)
+        _mode_getter = getattr(self, "_voice_mode_getter", None)
+        if text_ch_id is not None and _mode_getter is not None:
+            try:
+                if _mode_getter(str(text_ch_id)) == "off":
+                    return
+            except Exception:
+                pass
         await self.leave_voice_channel(guild_id)
         # Notify the runner so it can clean up voice_mode state
         if self._on_voice_disconnect and text_ch_id:
@@ -2395,6 +2416,11 @@ class DiscordAdapter(BasePlatformAdapter):
                         is_dm=False,
                     ):
                         continue
+                    # A user speaking to the bot is activity too — not just the
+                    # bot's own playback. Reset the inactivity timer so an active
+                    # listener isn't disconnected mid-conversation (this also
+                    # covers voice-on text-only sessions that never play audio).
+                    self._reset_voice_timeout(guild_id)
                     await self._process_voice_input(guild_id, user_id, pcm_data)
         except asyncio.CancelledError:
             pass
@@ -4702,7 +4728,7 @@ class DiscordAdapter(BasePlatformAdapter):
                     raise Exception(f"HTTP {resp.status}")
                 return await resp.read()
 
-    async def _handle_message(self, message: DiscordMessage) -> None:
+    async def _handle_message(self, message: DiscordMessage, role_authorized: bool = False) -> None:
         """Handle incoming Discord messages."""
         # In server channels (not DMs), require the bot to be @mentioned
         # UNLESS the channel is in the free-response list or the message is
@@ -4886,6 +4912,7 @@ class DiscordAdapter(BasePlatformAdapter):
             guild_id=str(guild.id) if guild else None,
             parent_chat_id=parent_channel_id,
             message_id=str(message.id),
+            role_authorized=role_authorized,
         )
 
         # Build media URLs -- download image attachments to local cache so the
@@ -5611,6 +5638,7 @@ def _define_discord_view_classes() -> None:
             self.allowed_role_ids = allowed_role_ids or set()
             self.resolved = False
             self._selected_provider: str = ""
+            self._pending_expensive_model: str = ""
 
             self._build_provider_select()
 
@@ -5693,6 +5721,41 @@ def _define_discord_view_classes() -> None:
             cancel_btn.callback = self._on_cancel
             self.add_item(cancel_btn)
 
+        def _build_expensive_confirm(self, model_id: str):
+            """Build confirmation buttons for unusually expensive models."""
+            self.clear_items()
+            self._pending_expensive_model = model_id
+
+            confirm_btn = discord.ui.Button(
+                label="Switch anyway",
+                style=discord.ButtonStyle.red,
+                custom_id="model_expensive_confirm",
+            )
+            confirm_btn.callback = self._on_expensive_confirm
+            self.add_item(confirm_btn)
+
+            cancel_btn = discord.ui.Button(
+                label="Cancel",
+                style=discord.ButtonStyle.grey,
+                custom_id="model_expensive_cancel",
+            )
+            cancel_btn.callback = self._on_cancel
+            self.add_item(cancel_btn)
+
+        async def _expensive_warning_for(self, model_id: str):
+            try:
+                from hermes_cli.model_cost_guard import expensive_model_warning
+
+                # Pricing lookup can hit models.dev / a /models endpoint on a
+                # cache miss — keep it off the event loop.
+                return await asyncio.to_thread(
+                    expensive_model_warning,
+                    model_id,
+                    provider=self._selected_provider,
+                )
+            except Exception:
+                return None
+
         async def _on_provider_selected(self, interaction: discord.Interaction):
             if not self._check_auth(interaction):
                 await interaction.response.send_message(
@@ -5722,7 +5785,11 @@ def _define_discord_view_classes() -> None:
                 view=self,
             )
 
-        async def _on_model_selected(self, interaction: discord.Interaction):
+        async def _switch_selected_model(
+            self,
+            interaction: discord.Interaction,
+            model_id: str,
+        ):
             if self.resolved:
                 await interaction.response.send_message(
                     "Already resolved~", ephemeral=True
@@ -5735,7 +5802,6 @@ def _define_discord_view_classes() -> None:
                 return
 
             self.resolved = True
-            model_id = interaction.data["values"][0]
             self.clear_items()
             await interaction.response.edit_message(
                 embed=discord.Embed(
@@ -5764,6 +5830,50 @@ def _define_discord_view_classes() -> None:
                 view=None,
             )
 
+        async def _on_model_selected(self, interaction: discord.Interaction):
+            if self.resolved:
+                await interaction.response.send_message(
+                    "Already resolved~", ephemeral=True
+                )
+                return
+            if not self._check_auth(interaction):
+                await interaction.response.send_message(
+                    "You're not authorized~", ephemeral=True
+                )
+                return
+
+            model_id = interaction.data["values"][0]
+            warning = await self._expensive_warning_for(model_id)
+            if warning is not None:
+                self._build_expensive_confirm(model_id)
+                await interaction.response.edit_message(
+                    embed=discord.Embed(
+                        title="⚠ Expensive Model Warning",
+                        description=warning.message,
+                        color=discord.Color.red(),
+                    ),
+                    view=self,
+                )
+                return
+
+            await self._switch_selected_model(interaction, model_id)
+
+        async def _on_expensive_confirm(self, interaction: discord.Interaction):
+            if not self._check_auth(interaction):
+                await interaction.response.send_message(
+                    "You're not authorized~", ephemeral=True
+                )
+                return
+            if not self._pending_expensive_model:
+                await interaction.response.send_message(
+                    "Model selection expired.", ephemeral=True
+                )
+                return
+            await self._switch_selected_model(
+                interaction,
+                self._pending_expensive_model,
+            )
+
         async def _on_back(self, interaction: discord.Interaction):
             if not self._check_auth(interaction):
                 await interaction.response.send_message(

run_agent.py

@@ -196,7 +196,7 @@ from agent.tool_dispatch_helpers import (
     _extract_error_preview,
     _trajectory_normalize_msg,  # noqa: F401  # re-exported for tests that `from run_agent import _trajectory_normalize_msg`
 )
-from utils import atomic_json_write, base_url_host_matches, base_url_hostname, is_truthy_value
+from utils import atomic_json_write, base_url_host_matches, base_url_hostname, is_truthy_value, model_forces_max_completion_tokens
 
 
 
@@ -1253,13 +1253,24 @@ class AIAgent:
     def _max_tokens_param(self, value: int) -> dict:
         """Return the correct max tokens kwarg for the current provider.
 
-        OpenAI's newer models (gpt-4o, o-series, gpt-5+) require
-        'max_completion_tokens'. Azure OpenAI also requires
-        'max_completion_tokens' for gpt-5.x models served via the
-        OpenAI-compatible endpoint. OpenRouter, local models, and older
+        OpenAI's newer models (gpt-4o, gpt-4.1, gpt-5+, o-series) require
+        'max_completion_tokens'. Azure OpenAI and GitHub Copilot also require
+        'max_completion_tokens' for those families served via their
+        OpenAI-compatible endpoints. OpenRouter, local models, and older
         OpenAI models use 'max_tokens'.
+
+        The check is URL-first (api.openai.com / Azure / Copilot all use the
+        new kwarg), then falls back to a model-name check so third-party
+        OpenAI-compatible endpoints fronting those models are recognised —
+        URL-only detection misses that case and silently sends the wrong
+        kwarg, which the upstream model rejects with a 400.
         """
-        if self._is_direct_openai_url() or self._is_azure_openai_url() or self._is_github_copilot_url():
+        if (
+            self._is_direct_openai_url()
+            or self._is_azure_openai_url()
+            or self._is_github_copilot_url()
+            or model_forces_max_completion_tokens(self.model)
+        ):
             return {"max_completion_tokens": value}
         return {"max_tokens": value}
 

scripts/release.py

@@ -45,6 +45,9 @@ ACP_REGISTRY_MANIFEST = REPO_ROOT / "acp_registry" / "agent.json"
 
 # Auto-extracted from noreply emails + manual overrides
 AUTHOR_MAP = {
+    "barronlroth@gmail.com": "barronlroth",
+    "ondrej.drapalik@gmail.com": "OndrejDrapalik",
+    "tomasz.panek@gmail.com": "tomekpanek",
     "philipadsouza@gmail.com": "PhilipAD",
     "zhuhaoyu0909@icloud.com": "underthestars-zhy",
     "raysun12142006@gmail.com": "yanxue06",
@@ -1039,6 +1042,7 @@ AUTHOR_MAP = {
     "zhang9w0v5@qq.com": "zhang9w0v5",
     "fuleinist@outlook.com": "fuleinist",
     "43494187+Llugaes@users.noreply.github.com": "Llugaes",
+    "xiangji.chen@centurygame.com": "Llugaes",
     "fengtianyu88@users.noreply.github.com": "fengtianyu88",
     "l.moncany@gmail.com": "lmoncany",
     "fatinghenji@users.noreply.github.com": "fatinghenji",
@@ -1504,6 +1508,7 @@ AUTHOR_MAP = {
     "singhsanidhya741@gmail.com": "sanidhyasin",  # PR #40403 salvage (model.default_headers for custom OpenAI-compatible providers, #40033)
     "josephjohnson.joel@gmail.com": "JoelJJohnson",  # PR #39913 salvage (Windows ConPTY dashboard chat bridge)
     "andreas@schwarz-ketsch.de": "Nea74",  # PR #40022 co-author credit (same Windows ConPTY bridge design)
+    "chanhokyim@gmail.com": "joel611",  # PR #33958 salvage (DISCORD_ALLOWED_ROLES role_authorized gateway flag)
 }
 
 

tests/agent/test_auxiliary_client.py

@@ -3791,3 +3791,82 @@ class TestAuxUnhealthyCache:
             )
             # After the 402, OpenRouter is in the unhealthy cache.
             assert _is_provider_unhealthy("openrouter") is True
+
+
+# ── auxiliary_max_tokens_param ──────────────────────────────────────────────
+
+
+class TestAuxiliaryMaxTokensParam:
+    """Verify the kwarg emitted by ``auxiliary_max_tokens_param`` across
+    URL / provider / model-name combinations. Regression cover: a custom
+    OpenAI-compatible endpoint serving ``gpt-5.x`` was silently getting
+    ``max_tokens`` and 400-ing on ``unsupported_parameter``."""
+
+    def test_direct_openai_returns_max_completion_tokens(self):
+        with (
+            patch("agent.auxiliary_client._current_custom_base_url",
+                  return_value="https://api.openai.com/v1"),
+            patch("agent.auxiliary_client._read_nous_auth", return_value=None),
+        ):
+            assert auxiliary_max_tokens_param(4096) == {"max_completion_tokens": 4096}
+
+    def test_local_endpoint_without_model_uses_max_tokens(self):
+        with (
+            patch("agent.auxiliary_client._current_custom_base_url",
+                  return_value="http://localhost:11434/v1"),
+            patch("agent.auxiliary_client._read_nous_auth", return_value=None),
+        ):
+            assert auxiliary_max_tokens_param(4096) == {"max_tokens": 4096}
+
+    def test_openrouter_api_key_present_keeps_max_tokens_without_model_hint(self, monkeypatch):
+        monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-v1-test")
+        with (
+            patch("agent.auxiliary_client._current_custom_base_url",
+                  return_value="https://openrouter.ai/api/v1"),
+            patch("agent.auxiliary_client._read_nous_auth", return_value=None),
+        ):
+            assert auxiliary_max_tokens_param(4096) == {"max_tokens": 4096}
+
+    # Model-name fallback — this is the regression guard.
+
+    def test_custom_endpoint_serving_gpt5_uses_max_completion_tokens(self):
+        """Third-party gateway + gpt-5.x: name-based detection must kick in."""
+        with (
+            patch("agent.auxiliary_client._current_custom_base_url",
+                  return_value="https://my-gateway.example.com/v1"),
+            patch("agent.auxiliary_client._read_nous_auth", return_value=None),
+        ):
+            assert auxiliary_max_tokens_param(4096, model="gpt-5.4") == {
+                "max_completion_tokens": 4096
+            }
+
+    def test_openrouter_serving_gpt4o_uses_max_completion_tokens(self, monkeypatch):
+        monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-v1-test")
+        with (
+            patch("agent.auxiliary_client._current_custom_base_url",
+                  return_value="https://openrouter.ai/api/v1"),
+            patch("agent.auxiliary_client._read_nous_auth", return_value=None),
+        ):
+            assert auxiliary_max_tokens_param(4096, model="openai/gpt-4o-mini") == {
+                "max_completion_tokens": 4096
+            }
+
+    def test_custom_endpoint_serving_classic_llama_keeps_max_tokens(self):
+        with (
+            patch("agent.auxiliary_client._current_custom_base_url",
+                  return_value="https://my-gateway.example.com/v1"),
+            patch("agent.auxiliary_client._read_nous_auth", return_value=None),
+        ):
+            assert auxiliary_max_tokens_param(4096, model="llama3-70b") == {
+                "max_tokens": 4096
+            }
+
+    def test_empty_model_falls_back_to_url_only(self):
+        """No model hint → only the URL-based rule applies."""
+        with (
+            patch("agent.auxiliary_client._current_custom_base_url",
+                  return_value="https://my-gateway.example.com/v1"),
+            patch("agent.auxiliary_client._read_nous_auth", return_value=None),
+        ):
+            assert auxiliary_max_tokens_param(4096, model="") == {"max_tokens": 4096}
+            assert auxiliary_max_tokens_param(4096, model=None) == {"max_tokens": 4096}

tests/agent/test_curator.py

@@ -668,8 +668,8 @@ def test_state_atomic_write_no_tmp_leftovers(curator_env):
     c = curator_env["curator"]
     c.save_state({"paused": True})
     parent = c._state_file().parent
-    for p in parent.iterdir():
-        assert not p.name.startswith(".curator_state_"), f"tmp leftover: {p.name}"
+    tmp_files = [p.name for p in parent.iterdir() if p.name.endswith(".tmp")]
+    assert tmp_files == []
 
 
 def test_state_preserves_last_report_path(curator_env):

tests/agent/test_error_classifier.py

@@ -964,6 +964,57 @@ class TestClassifyApiError:
         assert result.reason == FailoverReason.format_error
         assert result.retryable is False
 
+    def test_400_unsupported_max_tokens_param_not_context_overflow(self):
+        """A GPT-5 model rejecting max_tokens must NOT be misclassified as
+        context overflow. The OpenAI error string contains the literal
+        'max_tokens' (a _CONTEXT_OVERFLOW_PATTERNS entry), so without the
+        request-validation guard it was routed into the compression loop,
+        re-sent with the same bad param, and ended in "Cannot compress
+        further". Regression for gpt-5-context-overflow-misclassification."""
+        msg = ("Unsupported parameter: 'max_tokens' is not supported with this "
+               "model. Use 'max_completion_tokens' instead.")
+        e = MockAPIError(
+            msg,
+            status_code=400,
+            body={"error": {"message": msg, "type": "invalid_request_error",
+                            "code": "unsupported_parameter"}},
+        )
+        # Tiny context against a huge window — definitely not a real overflow.
+        result = classify_api_error(e, model="gpt-5.4",
+                                    approx_tokens=6962, context_length=1050000)
+        assert result.reason == FailoverReason.format_error
+        assert result.retryable is False
+        assert result.should_compress is False
+
+    def test_400_unknown_parameter_not_context_overflow(self):
+        """'Unknown parameter' 400s are deterministic request-validation
+        failures, not overflows."""
+        e = MockAPIError(
+            "Unknown parameter: 'foo'.",
+            status_code=400,
+            body={"error": {"message": "Unknown parameter: 'foo'.",
+                            "code": "unknown_parameter"}},
+        )
+        result = classify_api_error(e, approx_tokens=1000)
+        assert result.reason == FailoverReason.format_error
+        assert result.should_compress is False
+
+    def test_400_real_overflow_with_invalid_request_error_code_still_compresses(self):
+        """Guard the guard: OpenAI stamps genuine context-overflow 400s with
+        the generic 'invalid_request_error' code. The request-validation guard
+        must NOT key off that code, or real overflows stop compressing."""
+        msg = ("This model's maximum context length is 128000 tokens, however "
+               "you requested 150000 tokens.")
+        e = MockAPIError(
+            msg,
+            status_code=400,
+            body={"error": {"message": msg, "type": "invalid_request_error"}},
+        )
+        result = classify_api_error(e, model="gpt-5.4",
+                                    approx_tokens=150000, context_length=128000)
+        assert result.reason == FailoverReason.context_overflow
+        assert result.should_compress is True
+
     def test_422_format_error(self):
         e = MockAPIError("Unprocessable Entity", status_code=422)
         result = classify_api_error(e)

tests/agent/test_usage_pricing.py

@@ -192,6 +192,32 @@ def test_custom_endpoint_models_api_pricing_is_supported(monkeypatch):
     assert float(entry.output_cost_per_million) == 2.0
 
 
+def test_nous_portal_pricing_preserves_vendor_prefixed_model_ids(monkeypatch):
+    seen = {}
+
+    def _fake_fetch_endpoint_model_metadata(base_url, api_key=None):
+        seen["base_url"] = base_url
+        return {
+            "openai/gpt-5.5-pro": {
+                "pricing": {
+                    "prompt": "0.000025",
+                    "completion": "0.000125",
+                }
+            }
+        }
+
+    monkeypatch.setattr(
+        "agent.usage_pricing.fetch_endpoint_model_metadata",
+        _fake_fetch_endpoint_model_metadata,
+    )
+
+    entry = get_pricing_entry("openai/gpt-5.5-pro", provider="nous")
+
+    assert seen["base_url"] == "https://inference-api.nousresearch.com/v1"
+    assert float(entry.input_cost_per_million) == 25.0
+    assert float(entry.output_cost_per_million) == 125.0
+
+
 def test_deepseek_v4_pro_pricing_entry_exists():
     """Regression test: deepseek-v4-pro must have a pricing entry.
 

tests/gateway/test_discord_model_picker.py

@@ -80,3 +80,91 @@ async def test_model_picker_clears_controls_before_running_switch_callback():
     interaction.response.edit_message.assert_awaited_once()
     interaction.response.defer.assert_not_called()
     interaction.edit_original_response.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_expensive_model_requires_confirmation(monkeypatch):
+    events: list[object] = []
+
+    async def on_model_selected(chat_id: str, model_id: str, provider_slug: str) -> str:
+        events.append(("switch", chat_id, model_id, provider_slug))
+        return "Model switched"
+
+    async def edit_message(**kwargs):
+        events.append(
+            (
+                "edit",
+                kwargs["embed"].title,
+                kwargs["embed"].description,
+                kwargs["view"],
+            )
+        )
+
+    async def edit_original_response(**kwargs):
+        events.append((
+            "final-edit",
+            kwargs["embed"].title,
+            kwargs["embed"].description,
+            kwargs["view"],
+        ))
+
+    monkeypatch.setattr(
+        "hermes_cli.model_cost_guard.expensive_model_warning",
+        lambda *_args, **_kwargs: SimpleNamespace(
+            message="!!! EXPENSIVE MODEL WARNING !!!\ndid you mean to select openai/gpt-5.5?"
+        ),
+    )
+
+    view = ModelPickerView(
+        providers=[
+            {
+                "slug": "openrouter",
+                "name": "OpenRouter",
+                "models": ["openai/gpt-5.5-pro"],
+                "total_models": 1,
+                "is_current": True,
+            }
+        ],
+        current_model="openai/gpt-5.5",
+        current_provider="openrouter",
+        session_key="session-1",
+        on_model_selected=on_model_selected,
+        allowed_user_ids={"123"},  # matches the interaction user; empty = fail-closed
+    )
+    view._selected_provider = "openrouter"
+
+    interaction = SimpleNamespace(
+        user=SimpleNamespace(id=123),
+        channel_id=456,
+        data={"values": ["openai/gpt-5.5-pro"]},
+        response=SimpleNamespace(
+            send_message=AsyncMock(),
+            edit_message=AsyncMock(side_effect=edit_message),
+        ),
+        edit_original_response=AsyncMock(side_effect=edit_original_response),
+    )
+
+    await view._on_model_selected(interaction)
+
+    assert events == [
+        (
+            "edit",
+            "⚠ Expensive Model Warning",
+            "!!! EXPENSIVE MODEL WARNING !!!\ndid you mean to select openai/gpt-5.5?",
+            view,
+        ),
+    ]
+    assert view.resolved is False
+
+    await view._on_expensive_confirm(interaction)
+
+    assert events[1:] == [
+        (
+            "edit",
+            "⚙ Switching Model",
+            "Switching to `openai/gpt-5.5-pro`...",
+            None,
+        ),
+        ("switch", "456", "openai/gpt-5.5-pro", "openrouter"),
+        ("final-edit", "⚙ Model Switched", "Model switched", None),
+    ]

tests/gateway/test_model_command_expensive_confirm.py

@@ -0,0 +1,186 @@
+"""Gateway typed ``/model <name>`` must route through the expensive-model
+confirmation gate.
+
+The pickers (Telegram/Discord inline keyboards, TUI, dashboard) confirm
+expensive models via their own UI affordances; the typed text command
+previously bypassed the guard entirely — a user typing
+``/model openai/gpt-5.5-pro`` switched silently while the picker warned.
+These tests pin the typed path:
+
+- warning fires → handler returns the slash-confirm prompt, switch NOT applied
+- confirm ("once") → switch applies (session override set)
+- cancel → switch not applied, current model unchanged
+- no warning (cheap model) → switch applies immediately, no prompt
+"""
+
+from types import SimpleNamespace
+
+import pytest
+import yaml
+
+from gateway.config import Platform
+from gateway.platforms.base import MessageEvent, MessageType
+from gateway.run import GatewayRunner
+from gateway.session import SessionSource
+
+
+def _make_runner():
+    runner = object.__new__(GatewayRunner)
+    runner.adapters = {}
+    runner._voice_mode = {}
+    runner._session_model_overrides = {}
+    runner._running_agents = {}
+    return runner
+
+
+def _make_event(text):
+    return MessageEvent(
+        text=text,
+        message_type=MessageType.TEXT,
+        source=SessionSource(platform=Platform.TELEGRAM, chat_id="12345", chat_type="dm"),
+    )
+
+
+def _fake_switch_result():
+    from hermes_cli.model_switch import ModelSwitchResult
+
+    return ModelSwitchResult(
+        success=True,
+        new_model="openai/gpt-5.5-pro",
+        target_provider="openrouter",
+        provider_changed=False,
+        api_key="sk-test",
+        base_url="https://openrouter.ai/api/v1",
+        api_mode="chat_completions",
+        provider_label="OpenRouter",
+    )
+
+
+def _fake_warning():
+    return SimpleNamespace(
+        message=(
+            "!!! EXPENSIVE MODEL WARNING !!!\n"
+            "openai/gpt-5.5-pro has known pricing above Hermes' safety threshold.\n"
+            "did you mean to select openai/gpt-5.5?"
+        ),
+    )
+
+
+def _setup_isolated_home(tmp_path, monkeypatch, *, warn):
+    import gateway.run as gateway_run
+
+    hermes_home = tmp_path / ".hermes"
+    hermes_home.mkdir()
+    cfg_path = hermes_home / "config.yaml"
+    cfg_path.write_text(
+        yaml.safe_dump({"model": {"default": "old-model", "provider": "openrouter"}, "providers": {}}),
+        encoding="utf-8",
+    )
+
+    monkeypatch.setattr(gateway_run, "_hermes_home", hermes_home)
+    monkeypatch.setattr("agent.models_dev.fetch_models_dev", lambda: {})
+    monkeypatch.setattr(
+        "hermes_cli.model_switch.switch_model",
+        lambda **kw: _fake_switch_result(),
+    )
+    monkeypatch.setattr("hermes_constants.get_hermes_home", lambda: hermes_home)
+    monkeypatch.setattr("hermes_cli.config.get_hermes_home", lambda: hermes_home)
+    monkeypatch.setattr(
+        "hermes_cli.model_cost_guard.expensive_model_warning",
+        (lambda *a, **kw: _fake_warning()) if warn else (lambda *a, **kw: None),
+    )
+    return cfg_path
+
+
+@pytest.mark.asyncio
+async def test_typed_model_expensive_prompts_instead_of_switching(tmp_path, monkeypatch):
+    """Expensive model typed directly → confirm prompt, no switch applied."""
+    _setup_isolated_home(tmp_path, monkeypatch, warn=True)
+    runner = _make_runner()
+
+    captured = {}
+
+    async def _fake_request_slash_confirm(**kwargs):
+        captured.update(kwargs)
+        return kwargs["message"]
+
+    runner._request_slash_confirm = _fake_request_slash_confirm
+
+    result = await runner._handle_model_command(_make_event("/model openai/gpt-5.5-pro"))
+
+    assert result is not None
+    assert "EXPENSIVE MODEL WARNING" in result
+    # The switch must NOT have been applied yet.
+    assert runner._session_model_overrides == {}
+    assert captured["command"] == "model"
+
+
+@pytest.mark.asyncio
+async def test_typed_model_expensive_confirm_once_applies_switch(tmp_path, monkeypatch):
+    """Resolving the confirm with "once" applies the switch."""
+    _setup_isolated_home(tmp_path, monkeypatch, warn=True)
+    runner = _make_runner()
+    runner._evict_cached_agent = lambda session_key: None
+
+    captured = {}
+
+    async def _fake_request_slash_confirm(**kwargs):
+        captured.update(kwargs)
+        return None  # buttons rendered
+
+    runner._request_slash_confirm = _fake_request_slash_confirm
+
+    await runner._handle_model_command(_make_event("/model openai/gpt-5.5-pro"))
+    assert runner._session_model_overrides == {}
+
+    reply = await captured["handler"]("once")
+
+    assert "gpt-5.5-pro" in reply
+    overrides = list(runner._session_model_overrides.values())
+    assert len(overrides) == 1
+    assert overrides[0]["model"] == "openai/gpt-5.5-pro"
+
+
+@pytest.mark.asyncio
+async def test_typed_model_expensive_cancel_keeps_current_model(tmp_path, monkeypatch):
+    """Resolving the confirm with "cancel" leaves everything unchanged."""
+    cfg_path = _setup_isolated_home(tmp_path, monkeypatch, warn=True)
+    runner = _make_runner()
+
+    captured = {}
+
+    async def _fake_request_slash_confirm(**kwargs):
+        captured.update(kwargs)
+        return None
+
+    runner._request_slash_confirm = _fake_request_slash_confirm
+
+    await runner._handle_model_command(_make_event("/model openai/gpt-5.5-pro --global"))
+
+    reply = await captured["handler"]("cancel")
+
+    assert "cancelled" in reply.lower()
+    assert runner._session_model_overrides == {}
+    # --global must not have persisted the cancelled switch.
+    written = yaml.safe_load(cfg_path.read_text(encoding="utf-8"))
+    assert written["model"]["default"] == "old-model"
+
+
+@pytest.mark.asyncio
+async def test_typed_model_cheap_switches_without_prompt(tmp_path, monkeypatch):
+    """No warning → switch applies immediately; confirm primitive never invoked."""
+    _setup_isolated_home(tmp_path, monkeypatch, warn=False)
+    runner = _make_runner()
+    runner._evict_cached_agent = lambda session_key: None
+
+    async def _fail_request_slash_confirm(**kwargs):  # pragma: no cover
+        raise AssertionError("confirm should not be requested for cheap models")
+
+    runner._request_slash_confirm = _fail_request_slash_confirm
+
+    result = await runner._handle_model_command(_make_event("/model openai/gpt-5.5-pro"))
+
+    assert result is not None
+    assert "gpt-5.5-pro" in result
+    overrides = list(runner._session_model_overrides.values())
+    assert len(overrides) == 1

tests/gateway/test_run_progress_topics.py

@@ -9,6 +9,7 @@ from types import SimpleNamespace
 
 import pytest
 
+import gateway.platforms.base as base_platform
 from gateway.config import Platform, PlatformConfig, StreamingConfig
 from gateway.platforms.base import BasePlatformAdapter, MessageEvent, MessageType, SendResult
 from gateway.session import SessionSource
@@ -1076,6 +1077,54 @@ async def test_base_processing_releases_post_delivery_callback_after_main_send()
     assert released == [True]
 
 
+@pytest.mark.asyncio
+async def test_base_processing_stops_typing_before_hung_post_delivery_callback(
+    monkeypatch,
+):
+    """A stuck post-delivery callback must not keep the typing task alive."""
+    monkeypatch.setattr(base_platform, "_POST_DELIVERY_CALLBACK_TIMEOUT_SECONDS", 0.01)
+    adapter = ProgressCaptureAdapter()
+    events = []
+
+    async def _handler(event):
+        return "done"
+
+    async def _post_delivery_cb():
+        events.append("callback-start")
+        await asyncio.Event().wait()
+
+    async def _stop_typing(chat_id):
+        events.append("typing-stopped")
+        await ProgressCaptureAdapter.stop_typing(adapter, chat_id)
+
+    adapter.set_message_handler(_handler)
+    adapter.stop_typing = _stop_typing
+
+    source = SessionSource(
+        platform=Platform.TELEGRAM,
+        chat_id="-1001",
+        chat_type="group",
+        thread_id="17585",
+    )
+    event = MessageEvent(
+        text="hello",
+        message_type=MessageType.TEXT,
+        source=source,
+        message_id="msg-1",
+    )
+    session_key = "agent:main:telegram:group:-1001:17585"
+    adapter._active_sessions[session_key] = asyncio.Event()
+    adapter._post_delivery_callbacks[session_key] = _post_delivery_cb
+
+    await asyncio.wait_for(
+        adapter._process_message_background(event, session_key), timeout=1.0
+    )
+
+    assert [call["content"] for call in adapter.sent] == ["done"]
+    assert events[:2] == ["typing-stopped", "callback-start"]
+    assert any(call["metadata"] == {"stopped": True} for call in adapter.typing)
+
+
 @pytest.mark.asyncio
 async def test_run_agent_drops_tool_progress_after_generation_invalidation(monkeypatch, tmp_path):
     import yaml

tests/gateway/test_stt_config.py

@@ -102,6 +102,45 @@ async def test_enrich_message_with_transcription_avoids_bogus_no_provider_messag
     assert transcripts == []
 
 
+@pytest.mark.asyncio
+async def test_enrich_message_with_transcription_returns_tuple_for_empty_content_placeholder():
+    """A successful transcription whose caption is the empty-content placeholder
+    must still return the ``(text, transcripts)`` tuple.
+
+    The Discord adapter delivers a captionless voice note as the literal
+    ``"(The user sent a message with no text content)"`` placeholder. When STT
+    succeeds we strip that redundant placeholder and return just the transcript
+    prefix — but the method's contract (and every caller, which unpacks the
+    result as ``text, transcripts = ...``) requires a 2-tuple. Returning a bare
+    string here raised ``ValueError: too many values to unpack`` and dropped the
+    whole voice message on the floor.
+    """
+    from gateway.run import GatewayRunner
+
+    runner = GatewayRunner.__new__(GatewayRunner)
+    runner.config = GatewayConfig(stt_enabled=True)
+    runner._has_setup_skill = lambda: False
+
+    with patch(
+        "tools.transcription_tools.transcribe_audio",
+        return_value={
+            "success": True,
+            "transcript": "hello from a captionless voice note",
+            "provider": "local_command",
+        },
+    ):
+        result, transcripts = await runner._enrich_message_with_transcription(
+            "(The user sent a message with no text content)",
+            ["/tmp/voice.ogg"],
+        )
+
+    # The redundant placeholder is stripped, leaving only the transcript prefix.
+    assert "hello from a captionless voice note" in result
+    assert "(The user sent a message with no text content)" not in result
+    # Crucially, the transcripts are still surfaced so callers can echo them.
+    assert transcripts == ["hello from a captionless voice note"]
+
+
 @pytest.mark.asyncio
 async def test_prepare_inbound_message_text_transcribes_queued_voice_event():
     from gateway.run import GatewayRunner

tests/gateway/test_telegram_model_picker.py

@@ -91,10 +91,6 @@ class TestTelegramModelPicker:
         query.answer = AsyncMock()
         query.edit_message_text = AsyncMock()
 
-        update = MagicMock()
-        update.callback_query = query
-        context = MagicMock()
-
         await adapter._handle_model_picker_callback(query, "mb", "12345")
 
         edit_kwargs = query.edit_message_text.call_args[1]
@@ -133,17 +129,11 @@ class TestTelegramModelPicker:
 
         await adapter._handle_model_picker_callback(query, "mm:0", "12345")
 
-        # The callback was invoked with the selected model
         callback.assert_awaited_once()
-        # edit_message_text MUST be called on the success path (this is the
-        # regression we're guarding).
         query.edit_message_text.assert_awaited()
         edit_kwargs = query.edit_message_text.call_args[1]
         assert "MARKDOWN_V2" in repr(edit_kwargs["parse_mode"])
-        # The dynamic result text was routed through format_message
-        # (backtick code blocks survive escaping).
         assert "`gpt-5`" in edit_kwargs["text"]
-        # State is cleaned up after a successful switch.
         assert "12345" not in adapter._model_picker_state
 
     @pytest.mark.asyncio
@@ -184,7 +174,7 @@ class TestTelegramModelPicker:
         providers = [
             {"slug": "minimax", "name": "MiniMax", "total_models": 2},
             {"slug": "minimax-cn", "name": "MiniMax (China)", "total_models": 3},
-            {"slug": "xai", "name": "xAI", "total_models": 1},  # lone group member
+            {"slug": "xai", "name": "xAI", "total_models": 1},
         ]
 
         await adapter.send_model_picker(
@@ -197,14 +187,11 @@ class TestTelegramModelPicker:
             metadata=None,
         )
 
-        # Top-level keyboard: MiniMax family folded into one group button;
-        # xai (lone member) degraded to a direct provider button.
         assert "mpg:minimax" in built
         assert "mp:xai" in built
         assert "mp:minimax" not in built
         assert "mp:minimax-cn" not in built
 
-        # Drill into the MiniMax group → members appear as mp: buttons + back.
         built.clear()
         query = AsyncMock()
         query.message = MagicMock()
@@ -216,7 +203,49 @@ class TestTelegramModelPicker:
 
         assert "mp:minimax" in built
         assert "mp:minimax-cn" in built
-        assert "mb" in built  # back-to-providers button present
+        assert "mb" in built
+
+    @pytest.mark.asyncio
+    async def test_expensive_model_requires_confirmation(self, monkeypatch):
+        adapter = _make_adapter()
+        callback = AsyncMock(return_value="Switched to `openai/gpt-5.5-pro`")
+        adapter._model_picker_state["12345"] = {
+            "providers": [
+                {"slug": "openrouter", "name": "OpenRouter", "total_models": 1, "is_current": True}
+            ],
+            "current_model": "model_1",
+            "current_provider": "openrouter",
+            "session_key": "s",
+            "on_model_selected": callback,
+            "selected_provider": "openrouter",
+            "model_list": ["openai/gpt-5.5-pro"],
+            "msg_id": 42,
+        }
+        monkeypatch.setattr(
+            "hermes_cli.model_cost_guard.expensive_model_warning",
+            lambda *_args, **_kwargs: SimpleNamespace(
+                message="!!! EXPENSIVE MODEL WARNING !!!\ndid you mean to select openai/gpt-5.5?"
+            ),
+        )
+
+        query = AsyncMock()
+        query.message = MagicMock()
+        query.message.chat_id = 12345
+        query.answer = AsyncMock()
+        query.edit_message_text = AsyncMock()
+
+        await adapter._handle_model_picker_callback(query, "mm:0", "12345")
+
+        callback.assert_not_awaited()
+        assert "12345" in adapter._model_picker_state
+        first_edit = query.edit_message_text.call_args[1]
+        assert "EXPENSIVE MODEL WARNING" in first_edit["text"]
+        assert first_edit["reply_markup"] is not None
+
+        await adapter._handle_model_picker_callback(query, "mc:0", "12345")
+
+        callback.assert_awaited_once_with("12345", "openai/gpt-5.5-pro", "openrouter")
+        assert "12345" not in adapter._model_picker_state
 
     @pytest.mark.asyncio
     async def test_retries_without_thread_when_thread_not_found(self):

tests/gateway/test_voice_command.py

@@ -415,14 +415,17 @@ class TestSendVoiceReply:
 
     @pytest.mark.asyncio
     async def test_calls_tts_and_send_voice(self, runner):
+        from gateway.config import Platform
+
         mock_adapter = AsyncMock()
         mock_adapter.send_voice = AsyncMock()
         event = _make_event()
+        event.source.platform = Platform.TELEGRAM
         runner.adapters[event.source.platform] = mock_adapter
 
         tts_result = json.dumps({"success": True, "file_path": "/tmp/test.ogg"})
 
-        with patch("tools.tts_tool.text_to_speech_tool", return_value=tts_result), \
+        with patch("tools.tts_tool.text_to_speech_tool", return_value=tts_result) as mock_tts, \
              patch("tools.tts_tool._strip_markdown_for_tts", side_effect=lambda t: t), \
              patch("os.path.isfile", return_value=True), \
              patch("os.unlink"), \
@@ -430,9 +433,32 @@ class TestSendVoiceReply:
             await runner._send_voice_reply(event, "Hello world")
 
         mock_adapter.send_voice.assert_called_once()
+        assert mock_tts.call_args.kwargs["output_path"].endswith(".ogg")
         call_args = mock_adapter.send_voice.call_args
         assert call_args.kwargs.get("chat_id") == "123"
 
+    @pytest.mark.asyncio
+    async def test_non_telegram_auto_voice_reply_uses_mp3(self, runner):
+        from gateway.config import Platform
+
+        mock_adapter = AsyncMock()
+        mock_adapter.send_voice = AsyncMock()
+        event = _make_event()
+        event.source.platform = Platform.SLACK
+        runner.adapters[event.source.platform] = mock_adapter
+
+        tts_result = json.dumps({"success": True, "file_path": "/tmp/test.mp3"})
+
+        with patch("tools.tts_tool.text_to_speech_tool", return_value=tts_result) as mock_tts, \
+             patch("tools.tts_tool._strip_markdown_for_tts", side_effect=lambda t: t), \
+             patch("os.path.isfile", return_value=True), \
+             patch("os.unlink"), \
+             patch("os.makedirs"):
+            await runner._send_voice_reply(event, "Hello world")
+
+        mock_adapter.send_voice.assert_called_once()
+        assert mock_tts.call_args.kwargs["output_path"].endswith(".mp3")
+
     @pytest.mark.asyncio
     async def test_auto_voice_reply_uses_thread_metadata_helper(self, runner):
         from gateway.config import Platform
@@ -1929,6 +1955,49 @@ class TestVoiceTimeoutCleansRunnerState:
 
         assert 111 not in adapter._voice_clients
 
+    @pytest.mark.asyncio
+    async def test_timeout_skips_disconnect_when_voice_mode_off(self, adapter):
+        """Voice-off is deliberate text-only mode, not idle neglect — the
+        inactivity timer must NOT disconnect or spam the channel (#PanBartosz)."""
+        disconnect_calls = []
+        adapter._on_voice_disconnect = lambda chat_id: disconnect_calls.append(chat_id)
+        adapter._voice_mode_getter = lambda chat_id: "off"
+
+        mock_vc = MagicMock()
+        mock_vc.is_connected.return_value = True
+        mock_vc.disconnect = AsyncMock()
+        adapter._voice_clients[111] = mock_vc
+        adapter._voice_text_channels[111] = 999
+        adapter._voice_timeout_tasks[111] = MagicMock()
+
+        with patch("asyncio.sleep", new_callable=AsyncMock):
+            await adapter._voice_timeout_handler(111)
+
+        # Still connected, no disconnect callback, no "inactivity timeout" spam.
+        assert 111 in adapter._voice_clients
+        assert disconnect_calls == []
+        mock_vc.disconnect.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_timeout_still_disconnects_when_voice_mode_active(self, adapter):
+        """A non-off mode still auto-disconnects on genuine inactivity."""
+        disconnect_calls = []
+        adapter._on_voice_disconnect = lambda chat_id: disconnect_calls.append(chat_id)
+        adapter._voice_mode_getter = lambda chat_id: "all"
+
+        mock_vc = MagicMock()
+        mock_vc.is_connected.return_value = True
+        mock_vc.disconnect = AsyncMock()
+        adapter._voice_clients[111] = mock_vc
+        adapter._voice_text_channels[111] = 999
+        adapter._voice_timeout_tasks[111] = MagicMock()
+
+        with patch("asyncio.sleep", new_callable=AsyncMock):
+            await adapter._voice_timeout_handler(111)
+
+        assert 111 not in adapter._voice_clients
+        assert disconnect_calls == ["999"]
+
 
 # =====================================================================
 # Bug 6: play_in_voice_channel has playback timeout

tests/hermes_cli/test_auth_manual_paste.py

@@ -465,7 +465,7 @@ def test_xai_loopback_login_manual_paste_missing_code_raises(monkeypatch):
 
 
 def test_xai_loopback_login_timeout_falls_back_to_manual_paste(monkeypatch):
-    """Loopback timeout should offer the existing manual-paste path."""
+    """Loopback timeout should accept a bare Grok Build code paste."""
     monkeypatch.setattr(
         auth_mod, "_xai_oauth_discovery",
         lambda *_a, **_k: {
@@ -523,7 +523,7 @@ def test_xai_loopback_login_timeout_falls_back_to_manual_paste(monkeypatch):
         captured["prompt_calls"] += 1
         return {
             "code": "manual-auth-code",
-            "state": captured["state"],
+            "state": None,
             "error": None,
             "error_description": None,
         }
@@ -558,6 +558,48 @@ def test_xai_loopback_login_timeout_falls_back_to_manual_paste(monkeypatch):
     assert creds["tokens"]["refresh_token"] == "rt-timeout"
 
 
+def test_xai_wait_for_callback_accepts_ready_stdin_code(monkeypatch):
+    """Users can paste the Grok Build code while Hermes is still waiting."""
+    class _StubServer:
+        shutdown_called = False
+        close_called = False
+
+        def shutdown(self):
+            self.shutdown_called = True
+
+        def server_close(self):
+            self.close_called = True
+
+    class _StubThread:
+        joined = False
+
+        def join(self, timeout=None):
+            self.joined = True
+
+    server = _StubServer()
+    thread = _StubThread()
+    monkeypatch.setattr(
+        auth_mod,
+        "_read_ready_stdin_line",
+        lambda: "ready-grok-build-code\n",
+    )
+
+    out = auth_mod._xai_wait_for_callback(
+        server,
+        thread,
+        {"code": None, "error": None},
+        timeout_seconds=5,
+        manual_paste_redirect_uri="http://127.0.0.1:56121/callback",
+    )
+
+    assert out["code"] == "ready-grok-build-code"
+    assert out["state"] is None
+    assert out["_manual_paste"] is True
+    assert server.shutdown_called is True
+    assert server.close_called is True
+    assert thread.joined is True
+
+
 def test_xai_loopback_login_timeout_noninteractive_reraises(monkeypatch):
     """Non-interactive stdin must keep the original timeout error."""
     monkeypatch.setattr(

tests/hermes_cli/test_codex_models.py

@@ -133,7 +133,7 @@ def test_model_command_uses_runtime_access_token_for_codex_list(monkeypatch):
         captured["access_token"] = access_token
         return ["gpt-5.2-codex", "gpt-5.2"]
 
-    def _fake_prompt_model_selection(model_ids, current_model=""):
+    def _fake_prompt_model_selection(model_ids, current_model="", **_kwargs):
         captured["model_ids"] = list(model_ids)
         captured["current_model"] = current_model
         return None
@@ -181,7 +181,7 @@ def test_model_command_prompts_to_reuse_or_reauthenticate_codex_session(monkeypa
     )
     monkeypatch.setattr(
         "hermes_cli.auth._prompt_model_selection",
-        lambda model_ids, current_model="": None,
+        lambda model_ids, current_model="", **_kwargs: None,
     )
 
     _model_flow_openai_codex({}, current_model="gpt-5.4")
@@ -219,7 +219,7 @@ def test_model_command_uses_existing_codex_session_without_relogin(monkeypatch):
     )
     monkeypatch.setattr(
         "hermes_cli.auth._prompt_model_selection",
-        lambda model_ids, current_model="": None,
+        lambda model_ids, current_model="", **_kwargs: None,
     )
     monkeypatch.setattr(
         "hermes_cli.auth._login_openai_codex",

tests/hermes_cli/test_config.py

@@ -292,6 +292,25 @@ class TestSaveEnvValueSecure:
             env_mode = (tmp_path / ".env").stat().st_mode & 0o777
             assert env_mode == 0o600
 
+    def test_save_env_value_preserves_existing_file_mode_on_posix(self, tmp_path):
+        """Regression for #31518: pre-existing .env mode (e.g. 0640 for a
+        Docker bind-mount that the operator chose) survives subsequent
+        writes. Previously _secure_file ran unconditionally after the
+        mode-restore branch and re-tightened to 0600.
+        """
+        if os.name == "nt":
+            return
+
+        env_path = tmp_path / ".env"
+        env_path.write_text("EXISTING=value\n")
+        os.chmod(env_path, 0o640)
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(tmp_path)}):
+            save_env_value("TENOR_API_KEY", "sk-test-secret")
+
+        env_mode = env_path.stat().st_mode & 0o777
+        assert env_mode == 0o640, f"expected 0o640, got {oct(env_mode)}"
+
 
 class TestRemoveEnvValue:
     def test_removes_key_from_env_file(self, tmp_path):
@@ -335,6 +354,28 @@ class TestRemoveEnvValue:
             remove_env_value("ORPHAN_KEY")
             assert "ORPHAN_KEY" not in os.environ
 
+    def test_remove_env_value_preserves_existing_file_mode_on_posix(self, tmp_path):
+        """Regression: pre-existing .env mode (e.g. 0640 for a Docker
+        bind-mount the operator chose) survives a remove just as it does a
+        save. Previously _secure_file ran unconditionally after the
+        mode-restore branch and re-tightened to 0600 — the same bug fixed
+        in save_env_value (#33699), in the sibling remove path.
+        """
+        if os.name == "nt":
+            return
+
+        env_path = tmp_path / ".env"
+        env_path.write_text("KEEP=value\nDROP=gone\n")
+        os.chmod(env_path, 0o640)
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(tmp_path), "DROP": "gone"}):
+            removed = remove_env_value("DROP")
+
+        assert removed is True
+        assert "DROP" not in env_path.read_text()
+        env_mode = env_path.stat().st_mode & 0o777
+        assert env_mode == 0o640, f"expected 0o640, got {oct(env_mode)}"
+
 
 class TestSaveConfigAtomicity:
     """Verify save_config uses atomic writes (tempfile + os.replace)."""
@@ -1056,3 +1097,50 @@ class TestEnvWriteDenylist:
         # But the write path still refuses to update it
         with pytest.raises(ValueError, match="denylist"):
             save_env_value("LD_PRELOAD", "/tmp/evil.so")
+
+
+class TestWriteApprovalMigration:
+    """Version 28→29 renames memory/skills write_mode → write_approval (bool).
+
+    Only an explicit ``approve`` carried gating intent and maps to ``True``;
+    ``on``/``off``/unset map to ``False`` (gate off). The old ``write_mode`` key
+    is removed. Only a persisted key is rewritten — never invented.
+    """
+
+    def _write(self, tmp_path, body: str):
+        (tmp_path / "config.yaml").write_text(body)
+
+    def test_approve_maps_to_true(self, tmp_path):
+        with patch.dict(os.environ, {"HERMES_HOME": str(tmp_path)}):
+            self._write(tmp_path,
+                        "_config_version: 28\nmemory:\n  write_mode: approve\n"
+                        "skills:\n  write_mode: approve\n")
+            migrate_config(interactive=False, quiet=True)
+            raw = yaml.safe_load((tmp_path / "config.yaml").read_text())
+            assert raw["memory"]["write_approval"] is True
+            assert raw["skills"]["write_approval"] is True
+            assert "write_mode" not in raw["memory"]
+            assert "write_mode" not in raw["skills"]
+
+    def test_on_and_off_map_to_false(self, tmp_path):
+        with patch.dict(os.environ, {"HERMES_HOME": str(tmp_path)}):
+            # YAML 1.1 parses bare on/off as bools — write_mode could be either
+            # the string or the bool; both legacy "not gating" values → False.
+            self._write(tmp_path,
+                        "_config_version: 28\nmemory:\n  write_mode: 'on'\n"
+                        "skills:\n  write_mode: 'off'\n")
+            migrate_config(interactive=False, quiet=True)
+            raw = yaml.safe_load((tmp_path / "config.yaml").read_text())
+            assert raw["memory"]["write_approval"] is False
+            assert raw["skills"]["write_approval"] is False
+
+    def test_unset_key_defaults_to_false(self, tmp_path):
+        with patch.dict(os.environ, {"HERMES_HOME": str(tmp_path)}):
+            self._write(tmp_path, "_config_version: 28\nmemory:\n  memory_enabled: true\n")
+            migrate_config(interactive=False, quiet=True)
+            raw = yaml.safe_load((tmp_path / "config.yaml").read_text())
+            # No write_mode was persisted, so the rename is a no-op; the missing-
+            # field pass then seeds the default (False = gate off). Either way the
+            # gate ends up off and there's no leftover write_mode key.
+            assert raw["memory"].get("write_approval", False) is False
+            assert "write_mode" not in raw.get("memory", {})

tests/hermes_cli/test_dashboard_auth_middleware.py

@@ -191,6 +191,111 @@ def test_full_login_round_trip_unlocks_gated_api(gated_app):
     )
 
 
+def _complete_stub_login(client) -> None:
+    """Walk the stub OAuth round trip so ``client`` carries a valid session.
+
+    TestClient persists Set-Cookie across calls, so after this returns the
+    client's cookie jar holds ``hermes_session_at`` / ``hermes_session_rt``
+    and subsequent gated requests authenticate.
+    """
+    r1 = client.get("/auth/login?provider=stub", follow_redirects=False)
+    assert r1.status_code == 302
+    state = r1.headers["location"].split("state=")[1]
+    r2 = client.get(
+        f"/auth/callback?code=stub_code&state={state}",
+        follow_redirects=False,
+    )
+    assert r2.status_code == 302
+
+
+def test_gated_require_token_endpoint_accepts_cookie_session(gated_app):
+    """Regression: ``_require_token`` endpoints must work under the OAuth gate.
+
+    In gated mode the legacy ``_SESSION_TOKEN`` is NOT injected into the SPA
+    (it authenticates with the session cookie). Endpoints that call
+    ``_require_token`` directly — plugin install/enable/disable,
+    ``/api/dashboard/plugins/hub``, and others — used to re-check the absent
+    token and 401 every cookie-authenticated request, making them permanently
+    unreachable behind the gate (the dashboard surfaced a
+    ``401: {"detail":"Unauthorized"}`` popup on plugin install). The fix makes
+    ``_require_token`` defer to the gate, which has already verified the cookie
+    and attached ``request.state.session`` before the handler runs.
+
+    We POST a deliberately invalid plugin identifier: a passing auth layer
+    lets the request reach the handler, which rejects the identifier with a
+    400. The assertion is simply "not 401" — proving auth succeeded without
+    coupling to the validation message.
+    """
+    _complete_stub_login(gated_app)
+    r = gated_app.post(
+        "/api/dashboard/agent-plugins/install",
+        json={"identifier": "definitely not a valid identifier",
+              "force": False, "enable": False},
+    )
+    assert r.status_code != 401, (
+        "A _require_token endpoint 401'd a cookie-authenticated request under "
+        f"the OAuth gate (the install-popup bug). Body: {r.text}"
+    )
+    # And specifically: it reached the handler's own validation.
+    assert r.status_code == 400, (
+        f"Expected the install handler's 400 (bad identifier), got "
+        f"{r.status_code}: {r.text}"
+    )
+
+
+def test_gated_require_token_endpoint_still_rejects_no_cookie(gated_app):
+    """The gate must still 401 a ``_require_token`` endpoint with no session.
+
+    The fix defers to the gate — it does not make these endpoints public. A
+    request with no cookie is rejected by ``gated_auth_middleware`` before the
+    handler runs, so the install endpoint stays protected.
+    """
+    r = gated_app.post(
+        "/api/dashboard/agent-plugins/install",
+        json={"identifier": "owner/repo", "force": False, "enable": False},
+    )
+    assert r.status_code == 401, (
+        f"Expected 401 for an unauthenticated install POST under the gate, "
+        f"got {r.status_code}: {r.text}"
+    )
+
+
+# A representative spread of the OTHER ``_require_token`` endpoints (there are
+# 14 in total). The install popup was just the reported symptom; the same bug
+# made API-key reveal, provider validation, the OAuth-provider connect flow,
+# and the rest of plugin management unreachable behind the gate. Each entry is
+# (method, path, json_body); we assert only that a logged-in request is NOT
+# 401'd — i.e. it cleared the auth layer and reached the handler. The
+# handler's own status (400/404/429/etc.) is route-specific and not asserted.
+_GATED_REQUIRE_TOKEN_ROUTES = [
+    ("get", "/api/dashboard/plugins/hub", None),
+    ("post", "/api/env/reveal", {"key": "NONEXISTENT_ENV_VAR_FOR_TEST"}),
+    ("post", "/api/providers/validate", {"key": "OPENAI_API_KEY", "value": ""}),
+    ("delete", "/api/providers/oauth/__not_a_real_provider__", None),
+    ("post", "/api/dashboard/agent-plugins/__nope__/enable", None),
+]
+
+
+@pytest.mark.parametrize("method,path,body", _GATED_REQUIRE_TOKEN_ROUTES)
+def test_gated_require_token_routes_accept_cookie_session(
+    gated_app, method, path, body
+):
+    """Every ``_require_token`` route must clear auth for a logged-in caller.
+
+    Same root cause and fix as
+    ``test_gated_require_token_endpoint_accepts_cookie_session`` — this just
+    proves the fix covers the whole class, not only ``agent-plugins/install``.
+    """
+    _complete_stub_login(gated_app)
+    kwargs = {"json": body} if body is not None else {}
+    r = gated_app.request(method.upper(), path, **kwargs)
+    assert r.status_code != 401, (
+        f"{method.upper()} {path} 401'd a cookie-authenticated request under "
+        f"the OAuth gate — _require_token still rejecting a valid session. "
+        f"Body: {r.text}"
+    )
+
+
 def test_login_unknown_provider_returns_404(gated_app):
     r = gated_app.get("/auth/login?provider=nonexistent", follow_redirects=False)
     assert r.status_code == 404

tests/hermes_cli/test_ensure_utf8_locale.py

@@ -0,0 +1,179 @@
+"""Regression tests for hermes_cli._ensure_utf8().
+
+Covers the crash class where the setup wizard (and other banner-printing
+commands) emit box-drawing characters and the ⚕ glyph, which raise
+UnicodeEncodeError when stdout/stderr are bound to a non-UTF-8 codec.
+
+Historically the repair was gated on ``sys.platform == "win32"`` and only
+caught the Windows cp1252 case. Linux hosts with a latin-1 / C / POSIX locale
+(common on minimal Debian installs and Raspberry Pi) hit the identical crash
+in ``hermes setup`` because the repair returned early. See the Raspberry Pi
+report: latin-1 locale → UnicodeEncodeError before the wizard could start.
+"""
+
+import io
+import os
+import sys
+
+import hermes_cli
+
+
+# The exact glyphs the setup wizard / banners print (setup.py ~line 2962+).
+_BANNER = "┌─────┐\n│ ⚕ Hermes │\n└─────┘"
+
+
+class _FakeStream:
+    """Minimal text stream backed by an in-memory byte buffer with a codec.
+
+    Mirrors how CPython binds sys.stdout to the locale encoding: writes that
+    can't be encoded raise UnicodeEncodeError, just like a real latin-1 TTY.
+    """
+
+    def __init__(self, encoding, *, supports_reconfigure=True):
+        self.encoding = encoding
+        self._supports_reconfigure = supports_reconfigure
+        self.errors = "strict"
+        self._buf = io.BytesIO()
+
+    def write(self, s):
+        self._buf.write(s.encode(self.encoding, self.errors))
+        return len(s)
+
+    def flush(self):
+        pass
+
+    def reconfigure(self, *, encoding=None, errors=None):
+        if not self._supports_reconfigure:
+            raise AttributeError("reconfigure")
+        if encoding is not None:
+            self.encoding = encoding
+        if errors is not None:
+            self.errors = errors
+
+    def getvalue(self):
+        return self._buf.getvalue()
+
+
+def _run_with_streams(monkeypatch, out, err):
+    monkeypatch.setattr(sys, "stdout", out, raising=False)
+    monkeypatch.setattr(sys, "stderr", err, raising=False)
+    hermes_cli._ensure_utf8()
+
+
+def test_latin1_stdout_is_repaired_to_utf8(monkeypatch):
+    """A latin-1 stdout (the Raspberry Pi case) becomes UTF-8 capable."""
+    out = _FakeStream("latin-1")
+    err = _FakeStream("latin-1")
+
+    # Sanity: before the fix, the banner cannot be encoded.
+    try:
+        out.write(_BANNER)
+        pre_fix_crashes = False
+    except UnicodeEncodeError:
+        pre_fix_crashes = True
+    assert pre_fix_crashes, "fixture should reproduce the original crash"
+
+    out = _FakeStream("latin-1")
+    err = _FakeStream("latin-1")
+    _run_with_streams(monkeypatch, out, err)
+
+    assert sys.stdout.encoding.lower().replace("-", "") == "utf8"
+    assert sys.stderr.encoding.lower().replace("-", "") == "utf8"
+    # The banner now encodes without raising.
+    sys.stdout.write(_BANNER)
+    assert "⚕".encode("utf-8") in sys.stdout.getvalue()
+
+
+def test_ascii_posix_locale_is_repaired(monkeypatch):
+    """C/POSIX locale resolves to ascii stdout — also must be repaired."""
+    out = _FakeStream("ascii")
+    err = _FakeStream("ascii")
+    _run_with_streams(monkeypatch, out, err)
+    assert sys.stdout.encoding.lower().replace("-", "") == "utf8"
+    sys.stdout.write(_BANNER)  # no raise
+
+
+def test_utf8_stream_left_untouched(monkeypatch):
+    """Already-UTF-8 streams are a no-op: object identity preserved AND the
+    process environment is left untouched (no PYTHONUTF8/PYTHONIOENCODING
+    burned in on a healthy UTF-8 host)."""
+    out = _FakeStream("utf-8")
+    err = _FakeStream("utf-8")
+    sentinel_out, sentinel_err = out, err
+    monkeypatch.delenv("PYTHONUTF8", raising=False)
+    monkeypatch.delenv("PYTHONIOENCODING", raising=False)
+    _run_with_streams(monkeypatch, out, err)
+    assert sys.stdout is sentinel_out
+    assert sys.stderr is sentinel_err
+    # Healthy UTF-8 host: no environment mutation (minimal footprint).
+    assert "PYTHONUTF8" not in os.environ
+    assert "PYTHONIOENCODING" not in os.environ
+
+
+def test_repair_sets_child_process_env(monkeypatch):
+    """When a real repair happens, child-process UTF-8 hints are set."""
+    monkeypatch.delenv("PYTHONUTF8", raising=False)
+    monkeypatch.delenv("PYTHONIOENCODING", raising=False)
+    _run_with_streams(monkeypatch, _FakeStream("latin-1"), _FakeStream("latin-1"))
+    assert os.environ.get("PYTHONUTF8") == "1"
+    assert os.environ.get("PYTHONIOENCODING") == "utf-8"
+
+
+def test_repair_does_not_override_explicit_env(monkeypatch):
+    """A user's explicit PYTHONIOENCODING is respected (setdefault, not set)."""
+    monkeypatch.setenv("PYTHONIOENCODING", "utf-16")
+    monkeypatch.delenv("PYTHONUTF8", raising=False)
+    _run_with_streams(monkeypatch, _FakeStream("latin-1"), _FakeStream("latin-1"))
+    assert os.environ["PYTHONIOENCODING"] == "utf-16"
+
+
+def test_fallback_when_reconfigure_unavailable(monkeypatch, tmp_path):
+    """Streams without reconfigure() fall back to reopening the fd as UTF-8."""
+    real_path = tmp_path / "out.txt"
+    fh = open(real_path, "w", encoding="latin-1")
+
+    class _NoReconfigure:
+        """latin-1 stream exposing a real fileno() but no reconfigure()."""
+
+        encoding = "latin-1"
+
+        def fileno(self):
+            return fh.fileno()
+
+    stream = _NoReconfigure()
+    monkeypatch.setattr(sys, "stdout", stream, raising=False)
+    monkeypatch.setattr(sys, "stderr", stream, raising=False)
+    hermes_cli._ensure_utf8()
+
+    # Replaced with a new UTF-8 stream object (not reconfigured in place).
+    assert sys.stdout is not stream
+    assert sys.stdout.encoding.lower().replace("-", "") == "utf8"
+    sys.stdout.write(_BANNER)
+    sys.stdout.flush()
+    fh.close()
+    assert "⚕".encode("utf-8") in real_path.read_bytes()
+
+
+def test_broken_stream_does_not_raise(monkeypatch):
+    """A stream whose repair raises must be swallowed, never crash import."""
+
+    class _Hostile:
+        encoding = "latin-1"
+
+        def reconfigure(self, *a, **k):
+            raise OSError("nope")
+
+        def fileno(self):
+            raise OSError("no fd")
+
+    monkeypatch.setattr(sys, "stdout", _Hostile(), raising=False)
+    monkeypatch.setattr(sys, "stderr", _Hostile(), raising=False)
+    # Must not propagate.
+    hermes_cli._ensure_utf8()
+
+
+def test_none_streams_do_not_raise(monkeypatch):
+    """pythonw / detached streams (sys.stdout is None) must be tolerated."""
+    monkeypatch.setattr(sys, "stdout", None, raising=False)
+    monkeypatch.setattr(sys, "stderr", None, raising=False)
+    hermes_cli._ensure_utf8()

tests/hermes_cli/test_model_cost_guard.py

@@ -0,0 +1,97 @@
+from decimal import Decimal
+
+from agent.models_dev import ModelInfo
+from agent.usage_pricing import PricingEntry
+from hermes_cli.model_cost_guard import expensive_model_warning
+
+
+def test_no_warning_when_known_prices_are_at_threshold():
+    info = ModelInfo(
+        id="edge/model",
+        name="edge/model",
+        family="",
+        provider_id="test",
+        cost_input=20.0,
+        cost_output=100.0,
+    )
+
+    assert expensive_model_warning("edge/model", provider="test", model_info=info) is None
+
+
+def test_warns_when_models_dev_input_price_exceeds_threshold():
+    info = ModelInfo(
+        id="expensive/input",
+        name="expensive/input",
+        family="",
+        provider_id="test",
+        cost_input=20.01,
+        cost_output=1.0,
+    )
+
+    warning = expensive_model_warning(
+        "expensive/input",
+        provider="test",
+        model_info=info,
+    )
+
+    assert warning is not None
+    assert warning.input_cost_per_million == Decimal("20.01")
+    assert "EXPENSIVE MODEL WARNING" in warning.message
+    assert "$20/M input" in warning.message
+
+
+def test_warns_when_pricing_entry_output_price_exceeds_threshold(monkeypatch):
+    monkeypatch.setattr("agent.models_dev.get_model_info", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr(
+        "agent.usage_pricing.get_pricing_entry",
+        lambda *_args, **_kwargs: PricingEntry(
+            input_cost_per_million=Decimal("1.00"),
+            output_cost_per_million=Decimal("100.01"),
+            source="provider_models_api",
+        ),
+    )
+
+    warning = expensive_model_warning("provider/expensive-output", provider="openrouter")
+
+    assert warning is not None
+    assert warning.output_cost_per_million == Decimal("100.01")
+    assert "$100.01/M" in warning.message
+
+
+def test_openai_gpt55_pro_adds_suggestion(monkeypatch):
+    monkeypatch.setattr("agent.models_dev.get_model_info", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr(
+        "agent.usage_pricing.get_pricing_entry",
+        lambda *_args, **_kwargs: PricingEntry(
+            input_cost_per_million=Decimal("25"),
+            output_cost_per_million=Decimal("125"),
+            source="provider_models_api",
+        ),
+    )
+
+    warning = expensive_model_warning("openai/gpt-5.5-pro", provider="openrouter")
+
+    assert warning is not None
+    assert "did you mean to select openai/gpt-5.5?" in warning.message
+
+
+def test_openai_gpt55_pro_warns_for_nous_portal_pricing(monkeypatch):
+    monkeypatch.setattr("agent.models_dev.get_model_info", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr(
+        "agent.usage_pricing.fetch_endpoint_model_metadata",
+        lambda base_url, api_key="": {
+            "openai/gpt-5.5-pro": {
+                "pricing": {
+                    "prompt": "0.000025",
+                    "completion": "0.000125",
+                }
+            }
+        },
+    )
+
+    warning = expensive_model_warning("openai/gpt-5.5-pro", provider="nous")
+
+    assert warning is not None
+    assert warning.input_cost_per_million == Decimal("25.000000")
+    assert warning.output_cost_per_million == Decimal("125.000000")
+    assert "did you mean to select openai/gpt-5.5?" in warning.message

tests/hermes_cli/test_model_picker_expensive_confirm.py

@@ -0,0 +1,64 @@
+from types import SimpleNamespace
+
+from hermes_cli.model_switch import ModelSwitchResult
+
+
+def _bound(fn, instance):
+    return fn.__get__(instance, type(instance))
+
+
+def test_prompt_toolkit_model_picker_defers_confirmation_off_key_handler(monkeypatch):
+    import cli as cli_mod
+
+    result = ModelSwitchResult(
+        success=True,
+        new_model="openai/gpt-5.5-pro",
+        target_provider="nous",
+    )
+    monkeypatch.setattr(
+        "hermes_cli.model_switch.switch_model",
+        lambda **_kwargs: result,
+    )
+
+    captured = {}
+
+    class _Thread:
+        def __init__(self, *, target, args, daemon):
+            captured["target"] = target
+            captured["args"] = args
+            captured["daemon"] = daemon
+
+        def start(self):
+            captured["started"] = True
+
+    monkeypatch.setattr(cli_mod.threading, "Thread", _Thread)
+
+    self_ = SimpleNamespace(
+        _app=object(),
+        _model_picker_state={
+            "stage": "model",
+            "provider_data": {"slug": "nous"},
+            "model_list": ["openai/gpt-5.5-pro"],
+            "selected": 0,
+            "user_provs": None,
+            "custom_provs": None,
+        },
+        provider="nous",
+        model="openai/gpt-5.5",
+        base_url="",
+        api_key="",
+        _restore_modal_input_snapshot=lambda: None,
+        _invalidate=lambda **_kwargs: None,
+    )
+    self_._close_model_picker = _bound(cli_mod.HermesCLI._close_model_picker, self_)
+    self_._confirm_and_apply_model_switch_result = (
+        lambda *_args: captured.setdefault("ran_inline", True)
+    )
+
+    _bound(cli_mod.HermesCLI._handle_model_picker_selection, self_)()
+
+    assert self_._model_picker_state is None
+    assert captured["started"] is True
+    assert captured["daemon"] is True
+    assert captured["args"] == (result, False)
+    assert "ran_inline" not in captured

tests/hermes_cli/test_skills_hub.py

@@ -653,6 +653,44 @@ def test_browse_skills_dedup_uses_identifier_not_name(monkeypatch):
     )
 
 
+def test_do_browse_reports_live_per_source_progress():
+    """do_browse must pass an on_source_done callback so the status line ticks
+    off each source as it resolves, instead of showing a frozen spinner while
+    a slow source blocks. The page is still rendered once, after the full
+    result set is merged and trust-sorted."""
+    from hermes_cli.skills_hub import do_browse
+    from tools.skills_hub import SkillMeta
+
+    meta = SkillMeta(
+        name="demo", description="d", source="official",
+        identifier="official/demo", trust_level="builtin",
+    )
+
+    captured = {}
+
+    def fake_parallel(sources, query="", per_source_limits=None,
+                      source_filter="all", overall_timeout=30,
+                      on_source_done=None):
+        # Simulate two sources completing — the callback must be wired through.
+        assert on_source_done is not None, "do_browse must pass on_source_done"
+        on_source_done("official", 1)
+        on_source_done("clawhub", 0)
+        captured["called"] = True
+        return [meta], {"official": 1, "clawhub": 0}, []
+
+    sink = StringIO()
+    console = Console(file=sink, force_terminal=False, color_system=None, width=120)
+
+    with patch("tools.skills_hub.create_source_router", return_value=[]), \
+         patch("tools.skills_hub.GitHubAuth"), \
+         patch("tools.skills_hub.parallel_search_sources", side_effect=fake_parallel):
+        do_browse(page=1, page_size=20, console=console)
+
+    assert captured.get("called"), "parallel_search_sources was not invoked"
+    # The rendered page still shows the (single) merged result.
+    assert "demo" in sink.getvalue()
+
+
 # ---------------------------------------------------------------------------
 # Regression: full identifier must be recoverable from `hermes skills search`
 # even when the slug is too long to fit the terminal width (issue #33674).

tests/hermes_cli/test_terminal_menu_fallbacks.py

@@ -2,6 +2,7 @@
 cannot initialize (e.g. non-TTY, curses unavailable, terminal error)."""
 
 import subprocess
+from types import SimpleNamespace
 
 from hermes_cli.config import load_config, save_config
 
@@ -24,6 +25,46 @@ def test_prompt_model_selection_falls_back_on_menu_runtime_error(monkeypatch):
     assert selected == "model-b"
 
 
+def test_prompt_model_selection_requires_expensive_confirmation(monkeypatch, capsys):
+    from hermes_cli.auth import _prompt_model_selection
+
+    monkeypatch.setattr("hermes_cli.curses_ui.curses_radiolist", _raise_menu)
+    monkeypatch.setattr(
+        "hermes_cli.model_cost_guard.expensive_model_warning",
+        lambda *_args, **_kwargs: SimpleNamespace(message="EXPENSIVE MODEL WARNING"),
+    )
+    responses = iter(["1", "n"])
+    monkeypatch.setattr("builtins.input", lambda _prompt="": next(responses))
+
+    selected = _prompt_model_selection(
+        ["openai/gpt-5.5-pro"],
+        confirm_provider="nous",
+    )
+
+    out = capsys.readouterr().out
+    assert selected is None
+    assert "EXPENSIVE MODEL WARNING" in out
+
+
+def test_prompt_model_selection_allows_confirmed_expensive_model(monkeypatch):
+    from hermes_cli.auth import _prompt_model_selection
+
+    monkeypatch.setattr("hermes_cli.curses_ui.curses_radiolist", _raise_menu)
+    monkeypatch.setattr(
+        "hermes_cli.model_cost_guard.expensive_model_warning",
+        lambda *_args, **_kwargs: SimpleNamespace(message="EXPENSIVE MODEL WARNING"),
+    )
+    responses = iter(["1", "y"])
+    monkeypatch.setattr("builtins.input", lambda _prompt="": next(responses))
+
+    selected = _prompt_model_selection(
+        ["openai/gpt-5.5-pro"],
+        confirm_provider="nous",
+    )
+
+    assert selected == "openai/gpt-5.5-pro"
+
+
 def test_prompt_reasoning_effort_falls_back_on_menu_runtime_error(monkeypatch):
     from hermes_cli.main import _prompt_reasoning_effort_selection
 

tests/hermes_cli/test_update_interrupted_recovery.py

@@ -0,0 +1,218 @@
+"""Tests for interrupted-install self-heal (the ``.update-incomplete`` marker).
+
+Covers the breadcrumb lifecycle and the launch-time recovery guard added so a
+``hermes update`` killed mid-install (Ctrl-C, terminal close, WSL OOM) gets
+finished automatically on the next launch instead of leaving a half-built venv.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import hermes_cli.main as m
+
+
+def test_marker_round_trip(tmp_path, monkeypatch):
+    monkeypatch.setattr(m, "PROJECT_ROOT", tmp_path)
+    marker = m._update_marker_path()
+    assert marker == tmp_path / ".update-incomplete"
+    assert not marker.exists()
+
+    m._write_update_incomplete_marker()
+    assert marker.exists()
+    body = marker.read_text()
+    assert "started=" in body
+    assert "pid=" in body
+
+    m._clear_update_incomplete_marker()
+    assert not marker.exists()
+
+
+def test_clear_when_absent_is_noop(tmp_path, monkeypatch):
+    monkeypatch.setattr(m, "PROJECT_ROOT", tmp_path)
+    # Must not raise when the marker was never written.
+    m._clear_update_incomplete_marker()
+    assert not m._update_marker_path().exists()
+
+
+def test_recovery_noop_without_marker(tmp_path, monkeypatch):
+    monkeypatch.setattr(m, "PROJECT_ROOT", tmp_path)
+    called = {"install": False}
+    monkeypatch.setattr(
+        m,
+        "_install_python_dependencies_with_optional_fallback",
+        lambda *a, **k: called.__setitem__("install", True),
+    )
+    m._recover_from_interrupted_install()
+    assert called["install"] is False, "recovery must not install when no marker"
+
+
+def test_recovery_clears_stray_marker_without_pyproject(tmp_path, monkeypatch):
+    # No pyproject.toml (PyPI/Docker install) — a stray marker is not ours to
+    # act on; recovery should just clear it without trying to install.
+    monkeypatch.setattr(m, "PROJECT_ROOT", tmp_path)
+    m._write_update_incomplete_marker()
+    called = {"install": False}
+    monkeypatch.setattr(
+        m,
+        "_install_python_dependencies_with_optional_fallback",
+        lambda *a, **k: called.__setitem__("install", True),
+    )
+    m._recover_from_interrupted_install()
+    assert called["install"] is False
+    assert not m._update_marker_path().exists()
+
+
+def test_recovery_runs_install_and_clears_marker(tmp_path, monkeypatch):
+    # Source-tree install (pyproject present) with marker set → recovery should
+    # run the dep install and clear the marker on success.
+    monkeypatch.setattr(m, "PROJECT_ROOT", tmp_path)
+    (tmp_path / "pyproject.toml").write_text("[project]\nname='x'\n")
+    m._write_update_incomplete_marker()
+
+    seen = {"ensurepip": False, "install": False}
+
+    def fake_run(cmd, *a, **k):
+        if "ensurepip" in cmd:
+            seen["ensurepip"] = True
+
+        class R:
+            returncode = 0
+
+        return R()
+
+    monkeypatch.setattr(m.subprocess, "run", fake_run)
+    monkeypatch.setattr(m, "_is_termux_env", lambda *a, **k: False)
+    monkeypatch.setattr("hermes_cli.managed_uv.ensure_uv", lambda: None)
+    monkeypatch.setattr(
+        m,
+        "_install_python_dependencies_with_optional_fallback",
+        lambda *a, **k: seen.__setitem__("install", True),
+    )
+
+    m._recover_from_interrupted_install()
+
+    assert seen["ensurepip"] is True, "ensurepip must run unconditionally first"
+    assert seen["install"] is True, "dep install must run"
+    assert not m._update_marker_path().exists(), "marker cleared on success"
+
+
+def test_recovery_keeps_marker_on_failure(tmp_path, monkeypatch):
+    # If the install itself blows up, the marker must survive so the next
+    # launch retries — and recovery must not raise.
+    monkeypatch.setattr(m, "PROJECT_ROOT", tmp_path)
+    (tmp_path / "pyproject.toml").write_text("[project]\nname='x'\n")
+    m._write_update_incomplete_marker()
+
+    class R:
+        returncode = 0
+
+    monkeypatch.setattr(m.subprocess, "run", lambda *a, **k: R())
+    monkeypatch.setattr(m, "_is_termux_env", lambda *a, **k: False)
+    monkeypatch.setattr("hermes_cli.managed_uv.ensure_uv", lambda: None)
+
+    def boom(*a, **k):
+        raise RuntimeError("install died")
+
+    monkeypatch.setattr(
+        m, "_install_python_dependencies_with_optional_fallback", boom
+    )
+
+    # Must not raise.
+    m._recover_from_interrupted_install()
+    assert m._update_marker_path().exists(), "marker preserved for retry on failure"
+
+
+def _stub_install_env(monkeypatch, m, seen):
+    """Common stubs so recovery's install path is inert and observable."""
+
+    class R:
+        returncode = 0
+
+    monkeypatch.setattr(m.subprocess, "run", lambda *a, **k: R())
+    monkeypatch.setattr(m, "_is_termux_env", lambda *a, **k: False)
+    monkeypatch.setattr("hermes_cli.managed_uv.ensure_uv", lambda: None)
+    monkeypatch.setattr(
+        m,
+        "_install_python_dependencies_with_optional_fallback",
+        lambda *a, **k: seen.__setitem__("install", True),
+    )
+
+
+def test_recovery_skips_when_lock_held(tmp_path, monkeypatch):
+    # Another process is mid-recovery (fresh lockfile) — this launch must skip
+    # the install entirely and leave both marker and lock untouched.
+    monkeypatch.setattr(m, "PROJECT_ROOT", tmp_path)
+    (tmp_path / "pyproject.toml").write_text("[project]\nname='x'\n")
+    m._write_update_incomplete_marker()
+    lock = tmp_path / ".update-incomplete.lock"
+    lock.write_text("12345\n")
+
+    seen = {"install": False}
+    _stub_install_env(monkeypatch, m, seen)
+
+    m._recover_from_interrupted_install()
+
+    assert seen["install"] is False, "must not install while another holds the lock"
+    assert m._update_marker_path().exists(), "marker left for the lock holder"
+    assert lock.exists(), "fresh lock must not be broken"
+
+
+def test_recovery_breaks_stale_lock(tmp_path, monkeypatch):
+    # A lock older than an hour is from a crashed holder — it gets removed so
+    # the NEXT launch can recover (this launch still skips).
+    import os as _os
+
+    monkeypatch.setattr(m, "PROJECT_ROOT", tmp_path)
+    (tmp_path / "pyproject.toml").write_text("[project]\nname='x'\n")
+    m._write_update_incomplete_marker()
+    lock = tmp_path / ".update-incomplete.lock"
+    lock.write_text("12345\n")
+    stale = m._time.time() - 7200
+    _os.utime(lock, (stale, stale))
+
+    seen = {"install": False}
+    _stub_install_env(monkeypatch, m, seen)
+
+    m._recover_from_interrupted_install()
+
+    assert not lock.exists(), "stale lock must be broken"
+    assert m._update_marker_path().exists()
+
+    # Next launch proceeds normally.
+    m._recover_from_interrupted_install()
+    assert seen["install"] is True
+    assert not m._update_marker_path().exists()
+    assert not lock.exists(), "lock released after recovery"
+
+
+def test_recovery_releases_lock_after_run(tmp_path, monkeypatch):
+    monkeypatch.setattr(m, "PROJECT_ROOT", tmp_path)
+    (tmp_path / "pyproject.toml").write_text("[project]\nname='x'\n")
+    m._write_update_incomplete_marker()
+
+    seen = {"install": False}
+    _stub_install_env(monkeypatch, m, seen)
+
+    m._recover_from_interrupted_install()
+
+    assert seen["install"] is True
+    assert not (tmp_path / ".update-incomplete.lock").exists()
+
+
+def test_recovery_output_goes_to_stderr(tmp_path, monkeypatch, capfd):
+    # ACP speaks JSON-RPC on stdout — recovery output (including the streamed
+    # install, which inherits fd 1) must land on stderr only.
+    monkeypatch.setattr(m, "PROJECT_ROOT", tmp_path)
+    (tmp_path / "pyproject.toml").write_text("[project]\nname='x'\n")
+    m._write_update_incomplete_marker()
+
+    seen = {"install": False}
+    _stub_install_env(monkeypatch, m, seen)
+
+    m._recover_from_interrupted_install()
+
+    out, err = capfd.readouterr()
+    assert "interrupted mid-install" not in out
+    assert "interrupted mid-install" in err
+    assert "recovered" in err

tests/hermes_cli/test_web_server.py

@@ -4,6 +4,7 @@ import os
 import json
 import shutil
 from pathlib import Path
+from types import SimpleNamespace
 from unittest.mock import patch, MagicMock
 
 import pytest
@@ -1069,6 +1070,41 @@ class TestWebServerEndpoints:
         assert "GATEWAY_PROXY_URL" not in managed
         assert "GATEWAY_PROXY_URL" in _MESSAGING_KEYS_PAGE_KEYS
 
+    def test_model_set_requires_confirmation_for_expensive_model(self, monkeypatch):
+        monkeypatch.setattr(
+            "hermes_cli.model_cost_guard.expensive_model_warning",
+            lambda *_args, **_kwargs: SimpleNamespace(message="EXPENSIVE MODEL WARNING"),
+        )
+
+        resp = self.client.post(
+            "/api/model/set",
+            json={
+                "scope": "main",
+                "provider": "nous",
+                "model": "openai/gpt-5.5-pro",
+            },
+        )
+
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["ok"] is False
+        assert data["confirm_required"] is True
+        assert data["confirm_message"] == "EXPENSIVE MODEL WARNING"
+
+        confirmed = self.client.post(
+            "/api/model/set",
+            json={
+                "scope": "main",
+                "provider": "nous",
+                "model": "openai/gpt-5.5-pro",
+                "confirm_expensive_model": True,
+            },
+        )
+
+        assert confirmed.status_code == 200
+        assert confirmed.json()["ok"] is True
+
+
     def test_reveal_env_var(self, tmp_path):
         """POST /api/env/reveal should return the real unredacted value."""
         from hermes_cli.config import save_env_value
@@ -1363,6 +1399,17 @@ class TestWebServerEndpoints:
             }
 
         monkeypatch.setattr(ws, "_telegram_onboarding_request_sync", fake_request)
+        ws._ACTION_PROCS.pop("gateway-restart", None)
+        restart_calls = []
+
+        class FakeRestartProc:
+            pid = 4242
+
+        def fake_spawn_action(subcommand, name):
+            restart_calls.append((subcommand, name))
+            return FakeRestartProc()
+
+        monkeypatch.setattr(ws, "_spawn_hermes_action", fake_spawn_action)
 
         start = self.client.post("/api/messaging/telegram/onboarding/start", json={})
         assert start.status_code == 200
@@ -1384,13 +1431,138 @@ class TestWebServerEndpoints:
             "ok": True,
             "platform": "telegram",
             "bot_username": "hermes_pair_ready_bot",
-            "needs_restart": True,
+            "needs_restart": False,
+            "restart_started": True,
+            "restart_action": "gateway-restart",
+            "restart_pid": 4242,
         }
+        assert restart_calls == [(["gateway", "restart"], "gateway-restart")]
         env = load_env()
         assert env["TELEGRAM_BOT_TOKEN"] == "123456:SECRET"
         assert env["TELEGRAM_ALLOWED_USERS"] == "123456789"
         assert load_config()["platforms"]["telegram"]["enabled"] is True
 
+    def test_telegram_onboarding_apply_reports_restart_failure_after_save(
+        self, monkeypatch
+    ):
+        import hermes_cli.web_server as ws
+        from hermes_cli.config import load_config, load_env
+
+        with ws._telegram_onboarding_lock:
+            ws._telegram_onboarding_pairings.clear()
+
+        def fake_request(method, path, *, body=None, bearer_token=None):
+            if method == "POST":
+                return {
+                    "pairing_id": "pair-restart-fails",
+                    "poll_token": "poll-secret",
+                    "suggested_username": "hermes_pair_restart_fails_bot",
+                    "deep_link": "https://t.me/newbot/HermesSetupBot/hermes_pair_restart_fails_bot",
+                    "qr_payload": "https://t.me/newbot/HermesSetupBot/hermes_pair_restart_fails_bot",
+                    "expires_at": "2027-05-18T00:00:00.000Z",
+                }
+            assert method == "GET"
+            assert path == "/v1/telegram/pairings/pair-restart-fails"
+            assert bearer_token == "poll-secret"
+            return {
+                "status": "ready",
+                "bot_username": "hermes_pair_restart_fails_bot",
+                "owner_user_id": 123456789,
+                "token": "123456:SECRET",
+            }
+
+        monkeypatch.setattr(ws, "_telegram_onboarding_request_sync", fake_request)
+        ws._ACTION_PROCS.pop("gateway-restart", None)
+
+        def fail_spawn_action(subcommand, name):
+            assert subcommand == ["gateway", "restart"]
+            assert name == "gateway-restart"
+            raise RuntimeError("supervisor unavailable")
+
+        monkeypatch.setattr(ws, "_spawn_hermes_action", fail_spawn_action)
+
+        start = self.client.post("/api/messaging/telegram/onboarding/start", json={})
+        assert start.status_code == 200
+        ready = self.client.get("/api/messaging/telegram/onboarding/pair-restart-fails")
+        assert ready.status_code == 200
+        assert ready.json()["status"] == "ready"
+
+        applied = self.client.post(
+            "/api/messaging/telegram/onboarding/pair-restart-fails/apply",
+            json={"allowed_user_ids": ["123456789"]},
+        )
+
+        assert applied.status_code == 200
+        applied_data = applied.json()
+        assert applied_data["ok"] is True
+        assert applied_data["needs_restart"] is True
+        assert applied_data["restart_started"] is False
+        assert "supervisor unavailable" in applied_data["restart_error"]
+        assert "token" not in applied_data
+        env = load_env()
+        assert env["TELEGRAM_BOT_TOKEN"] == "123456:SECRET"
+        assert env["TELEGRAM_ALLOWED_USERS"] == "123456789"
+        assert load_config()["platforms"]["telegram"]["enabled"] is True
+
+    def test_telegram_onboarding_apply_reuses_inflight_gateway_restart(
+        self, monkeypatch
+    ):
+        """A live in-flight gateway restart is reused instead of spawning a
+        second racing ``hermes gateway restart`` child (e.g. when a stale
+        cached frontend also fires its own restart call)."""
+        import hermes_cli.web_server as ws
+
+        with ws._telegram_onboarding_lock:
+            ws._telegram_onboarding_pairings.clear()
+
+        def fake_request(method, path, *, body=None, bearer_token=None):
+            if method == "POST":
+                return {
+                    "pairing_id": "pair-reuse",
+                    "poll_token": "poll-secret",
+                    "suggested_username": "hermes_pair_reuse_bot",
+                    "deep_link": "https://t.me/newbot/HermesSetupBot/hermes_pair_reuse_bot",
+                    "qr_payload": "https://t.me/newbot/HermesSetupBot/hermes_pair_reuse_bot",
+                    "expires_at": "2027-05-18T00:00:00.000Z",
+                }
+            return {
+                "status": "ready",
+                "bot_username": "hermes_pair_reuse_bot",
+                "owner_user_id": 123456789,
+                "token": "123456:SECRET",
+            }
+
+        monkeypatch.setattr(ws, "_telegram_onboarding_request_sync", fake_request)
+
+        class FakeRunningProc:
+            pid = 5151
+
+            def poll(self):
+                return None  # still running
+
+        monkeypatch.setitem(ws._ACTION_PROCS, "gateway-restart", FakeRunningProc())
+
+        def fail_spawn_action(subcommand, name):
+            raise AssertionError("must not spawn a second concurrent restart")
+
+        monkeypatch.setattr(ws, "_spawn_hermes_action", fail_spawn_action)
+
+        start = self.client.post("/api/messaging/telegram/onboarding/start", json={})
+        assert start.status_code == 200
+        ready = self.client.get("/api/messaging/telegram/onboarding/pair-reuse")
+        assert ready.status_code == 200
+
+        applied = self.client.post(
+            "/api/messaging/telegram/onboarding/pair-reuse/apply",
+            json={"allowed_user_ids": ["123456789"]},
+        )
+
+        assert applied.status_code == 200
+        applied_data = applied.json()
+        assert applied_data["needs_restart"] is False
+        assert applied_data["restart_started"] is True
+        assert applied_data["restart_pid"] == 5151
+
     def test_telegram_onboarding_apply_requires_ready_pairing(self, monkeypatch):
         import hermes_cli.web_server as ws
 

tests/hermes_cli/test_xai_model_flow.py

@@ -0,0 +1,78 @@
+import argparse
+
+
+def test_xai_model_flow_reauth_uses_standard_radio_prompt(monkeypatch):
+    from hermes_cli import main as main_mod
+
+    captured = {"login_calls": 0}
+
+    monkeypatch.setattr(
+        "hermes_cli.auth.get_xai_oauth_auth_status",
+        lambda: {"logged_in": True},
+    )
+    monkeypatch.setattr(
+        "hermes_cli.setup._curses_prompt_choice",
+        lambda title, choices, default, description=None: 1,
+    )
+
+    def _fake_login(args, provider, force_new_login=False):
+        captured["login_calls"] += 1
+        captured["force_new_login"] = force_new_login
+        captured["args"] = args
+
+    monkeypatch.setattr("hermes_cli.auth._login_xai_oauth", _fake_login)
+    monkeypatch.setattr(
+        "hermes_cli.auth.resolve_xai_oauth_runtime_credentials",
+        lambda *args, **kwargs: {"base_url": "https://api.x.ai/v1"},
+    )
+    monkeypatch.setattr(
+        "hermes_cli.auth._prompt_model_selection",
+        lambda model_ids, current_model="": None,
+    )
+
+    main_mod._model_flow_xai_oauth(
+        {},
+        current_model="grok-build-0.1",
+        args=argparse.Namespace(manual_paste=True, no_browser=True, timeout=3),
+    )
+
+    assert captured["login_calls"] == 1
+    assert captured["force_new_login"] is True
+    assert captured["args"].manual_paste is True
+    assert captured["args"].no_browser is True
+    assert captured["args"].timeout == 3
+
+
+def test_xai_model_flow_cancel_skips_reauth(monkeypatch):
+    from hermes_cli import main as main_mod
+
+    monkeypatch.setattr(
+        "hermes_cli.auth.get_xai_oauth_auth_status",
+        lambda: {"logged_in": True},
+    )
+    monkeypatch.setattr(
+        "hermes_cli.setup._curses_prompt_choice",
+        lambda title, choices, default, description=None: 2,
+    )
+    monkeypatch.setattr(
+        "hermes_cli.auth._login_xai_oauth",
+        lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("should not reauthenticate")),
+    )
+    monkeypatch.setattr(
+        "hermes_cli.auth._prompt_model_selection",
+        lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("should not pick a model")),
+    )
+
+    main_mod._model_flow_xai_oauth({}, current_model="grok-build-0.1")
+
+
+def test_auth_credentials_choice_falls_back_to_numbered_prompt(monkeypatch):
+    from hermes_cli import main as main_mod
+
+    monkeypatch.setattr(
+        "hermes_cli.setup._curses_prompt_choice",
+        lambda title, choices, default, description=None: -1,
+    )
+    monkeypatch.setattr("builtins.input", lambda prompt="": "2")
+
+    assert main_mod._prompt_auth_credentials_choice("Credentials:") == "reauth"

tests/providers/test_provider_profiles.py

@@ -291,6 +291,121 @@ class TestOpenRouterProfile:
         assert eb["reasoning"] == {"enabled": True, "effort": "high"}
         assert tl["extra_headers"]["x-grok-conv-id"] == "sess-123"
 
+    # --- reasoning-mandatory Anthropic effort → top-level verbosity (#43432) ---
+    #
+    # These models (Claude 4.6+ / fable / mythos-class) ignore
+    # ``reasoning.effort`` and use adaptive thinking. OpenRouter honors the
+    # requested effort on the top-level ``verbosity`` field instead (maps to
+    # Anthropic ``output_config.effort``). The profile must route the existing
+    # ``reasoning_config["effort"]`` there while still NEVER emitting a
+    # ``reasoning`` field (which would 400 — see #42991). Gate every fixture on
+    # the real predicate so this stays a behavior contract, not a name snapshot.
+
+    @staticmethod
+    def _is_mandatory(model):
+        import inspect
+        p = get_provider_profile("openrouter")
+        mod = inspect.getmodule(type(p))
+        return mod._anthropic_reasoning_is_mandatory(model)
+
+    def test_mandatory_anthropic_effort_routes_to_verbosity(self):
+        """effort set + reasoning enabled → top-level verbosity == effort,
+        and NO reasoning field in extra_body.
+
+        Covers the full real config range produced by
+        ``hermes_constants.parse_reasoning_effort`` —
+        ``VALID_REASONING_EFFORTS = (minimal, low, medium, high, xhigh)``.
+        """
+        p = get_provider_profile("openrouter")
+        model = "anthropic/claude-fable-5"
+        assert self._is_mandatory(model)  # fixture really is mandatory
+        for effort in ("minimal", "low", "medium", "high", "xhigh"):
+            eb, tl = p.build_api_kwargs_extras(
+                reasoning_config={"enabled": True, "effort": effort},
+                supports_reasoning=True,
+                model=model,
+            )
+            assert tl["verbosity"] == effort, (effort, tl)
+            assert "reasoning" not in eb, (effort, eb)
+
+    def test_mandatory_anthropic_effort_without_enabled_key_routes(self):
+        """effort present without an explicit ``enabled`` key still routes to
+        verbosity (enabled defaults to True)."""
+        p = get_provider_profile("openrouter")
+        eb, tl = p.build_api_kwargs_extras(
+            reasoning_config={"effort": "xhigh"},
+            supports_reasoning=True,
+            model="anthropic/claude-fable-5",
+        )
+        assert tl["verbosity"] == "xhigh"
+        assert "reasoning" not in eb
+
+    def test_mandatory_anthropic_verbosity_is_value_agnostic_passthrough(self):
+        """The mapping passes the effort value through verbatim — it must NOT
+        clamp or whitelist. ``xhigh`` is a real config value; ``max`` is not
+        producible by ``parse_reasoning_effort`` today but OpenRouter accepts it
+        for Claude (live-proven in #43432), so a forward value must survive
+        rather than be silently dropped. The OpenAI SDK type only literals
+        ``low|medium|high`` but it's a TypedDict (no runtime validation), so the
+        extended scale reaches the wire untouched."""
+        p = get_provider_profile("openrouter")
+        for effort in ("xhigh", "max"):
+            _, tl = p.build_api_kwargs_extras(
+                reasoning_config={"enabled": True, "effort": effort},
+                supports_reasoning=True,
+                model="anthropic/claude-fable-5",
+            )
+            assert tl["verbosity"] == effort
+
+    def test_mandatory_anthropic_no_verbosity_when_effort_absent(self):
+        """No effort / none / disabled → no verbosity emitted, so the model
+        keeps its own adaptive default. Still no reasoning field."""
+        p = get_provider_profile("openrouter")
+        model = "anthropic/claude-fable-5"
+        for cfg in (
+            None,
+            {},
+            {"enabled": True},
+            {"effort": "none"},
+            {"enabled": True, "effort": "none"},
+            {"enabled": False, "effort": "high"},  # explicitly disabled wins
+        ):
+            eb, tl = p.build_api_kwargs_extras(
+                reasoning_config=cfg,
+                supports_reasoning=True,
+                model=model,
+            )
+            assert "verbosity" not in tl, (cfg, tl)
+            assert "reasoning" not in eb, (cfg, eb)
+
+    def test_non_mandatory_reasoning_model_unchanged_no_verbosity(self):
+        """Non-mandatory reasoning models (DeepSeek, Qwen, GPT) keep getting
+        ``reasoning`` in extra_body and never get a ``verbosity`` field — the
+        new path must not touch them."""
+        p = get_provider_profile("openrouter")
+        for model in ("deepseek/deepseek-chat", "qwen/qwen3-max", "openai/gpt-5.4"):
+            assert not self._is_mandatory(model)  # fixture really is non-mandatory
+            eb, tl = p.build_api_kwargs_extras(
+                reasoning_config={"enabled": True, "effort": "high"},
+                supports_reasoning=True,
+                model=model,
+            )
+            assert eb["reasoning"] == {"enabled": True, "effort": "high"}, (model, eb)
+            assert "verbosity" not in tl, (model, tl)
+
+    def test_mandatory_anthropic_verbosity_coexists_with_grok_header(self):
+        """A reasoning-mandatory Anthropic model is never a Grok model, but the
+        top-level dict must remain a single merged dict — verify the verbosity
+        path doesn't clobber the extra_headers slot used by Grok affinity."""
+        p = get_provider_profile("openrouter")
+        # mandatory anthropic + effort → verbosity, no extra_headers
+        _, tl = p.build_api_kwargs_extras(
+            reasoning_config={"enabled": True, "effort": "high"},
+            supports_reasoning=True,
+            model="anthropic/claude-fable-5",
+        )
+        assert tl == {"verbosity": "high"}
+
 
 class TestNousProfile:
     def test_tags(self):

tests/run_agent/test_run_agent.py

@@ -5063,6 +5063,41 @@ class TestMaxTokensParam:
         result = agent._max_tokens_param(4096)
         assert result == {"max_completion_tokens": 4096}
 
+    # ── Model-name fallback for non-openai.com endpoints serving newer families ──
+
+    def test_returns_max_completion_tokens_for_gpt5_on_custom_endpoint(self, agent):
+        """Custom OpenAI-compatible endpoint serving gpt-5.x must also use
+        max_completion_tokens — otherwise the server 400s on max_tokens."""
+        agent.base_url = "https://my-gateway.example.com/v1"
+        agent.model = "gpt-5.4"
+        result = agent._max_tokens_param(4096)
+        assert result == {"max_completion_tokens": 4096}
+
+    def test_returns_max_completion_tokens_for_gpt4o_on_openrouter(self, agent):
+        agent.base_url = "https://openrouter.ai/api/v1"
+        agent.model = "openai/gpt-4o-mini"
+        result = agent._max_tokens_param(4096)
+        assert result == {"max_completion_tokens": 4096}
+
+    def test_returns_max_completion_tokens_for_o1_on_custom_endpoint(self, agent):
+        agent.base_url = "https://custom.example.com/v1"
+        agent.model = "o1-preview"
+        result = agent._max_tokens_param(4096)
+        assert result == {"max_completion_tokens": 4096}
+
+    def test_returns_max_tokens_for_classic_gpt4_on_openrouter(self, agent):
+        """Classic gpt-4 (non-omni) still uses max_tokens. Don't over-match."""
+        agent.base_url = "https://openrouter.ai/api/v1"
+        agent.model = "openai/gpt-4-turbo"
+        result = agent._max_tokens_param(4096)
+        assert result == {"max_tokens": 4096}
+
+    def test_returns_max_tokens_for_llama_on_local(self, agent):
+        agent.base_url = "http://localhost:11434/v1"
+        agent.model = "llama3"
+        result = agent._max_tokens_param(4096)
+        assert result == {"max_tokens": 4096}
+
 
 class TestGpt5ApiModeRouting:
     """Verify provider-specific GPT-5 API-mode routing."""

tests/test_model_forces_max_completion_tokens.py

@@ -0,0 +1,137 @@
+"""Targeted tests for ``utils.model_forces_max_completion_tokens``.
+
+This helper decides whether a given model name requires the newer
+``max_completion_tokens`` kwarg (rather than the legacy ``max_tokens``) on
+``/v1/chat/completions``. It protects against the 400 ``unsupported_parameter``
+error seen when third-party OpenAI-compatible endpoints serve gpt-4o / 4.1 /
+5.x / o-series models by name and the caller only checks the URL host.
+"""
+
+from __future__ import annotations
+
+from utils import model_forces_max_completion_tokens
+
+
+# ─── Positive cases: families that require max_completion_tokens ────────────
+
+
+class TestPositiveCases:
+    def test_gpt_5_bare(self):
+        assert model_forces_max_completion_tokens("gpt-5") is True
+
+    def test_gpt_5_point_release(self):
+        # The case the user actually hit — gpt-5.4 on a custom OpenAI-compatible
+        # endpoint was being sent max_tokens and getting 400 back.
+        assert model_forces_max_completion_tokens("gpt-5.4") is True
+
+    def test_gpt_5_mini(self):
+        assert model_forces_max_completion_tokens("gpt-5-mini") is True
+
+    def test_gpt_5_nano(self):
+        assert model_forces_max_completion_tokens("gpt-5-nano") is True
+
+    def test_gpt_4o(self):
+        assert model_forces_max_completion_tokens("gpt-4o") is True
+
+    def test_gpt_4o_mini(self):
+        assert model_forces_max_completion_tokens("gpt-4o-mini") is True
+
+    def test_gpt_4_1(self):
+        assert model_forces_max_completion_tokens("gpt-4.1") is True
+
+    def test_gpt_4_1_mini(self):
+        assert model_forces_max_completion_tokens("gpt-4.1-mini") is True
+
+    def test_o1(self):
+        assert model_forces_max_completion_tokens("o1") is True
+
+    def test_o1_preview(self):
+        assert model_forces_max_completion_tokens("o1-preview") is True
+
+    def test_o1_mini(self):
+        assert model_forces_max_completion_tokens("o1-mini") is True
+
+    def test_o3(self):
+        assert model_forces_max_completion_tokens("o3") is True
+
+    def test_o3_mini(self):
+        assert model_forces_max_completion_tokens("o3-mini") is True
+
+    def test_o4_mini(self):
+        # Future-proofing — o4 is already listed publicly.
+        assert model_forces_max_completion_tokens("o4-mini") is True
+
+
+# ─── Negative cases: older or non-OpenAI families still use max_tokens ──────
+
+
+class TestNegativeCases:
+    def test_gpt_3_5_turbo(self):
+        assert model_forces_max_completion_tokens("gpt-3.5-turbo") is False
+
+    def test_gpt_4(self):
+        # Classic gpt-4 (non-omni) still uses max_tokens on chat completions.
+        assert model_forces_max_completion_tokens("gpt-4") is False
+
+    def test_gpt_4_turbo(self):
+        assert model_forces_max_completion_tokens("gpt-4-turbo") is False
+
+    def test_claude_family(self):
+        assert model_forces_max_completion_tokens("claude-3-opus") is False
+        assert model_forces_max_completion_tokens("claude-sonnet-4-6") is False
+
+    def test_llama_family(self):
+        assert model_forces_max_completion_tokens("llama3") is False
+        assert model_forces_max_completion_tokens("llama-3-70b-instruct") is False
+
+    def test_mistral_family(self):
+        assert model_forces_max_completion_tokens("mistral-7b-instruct") is False
+
+    def test_qwen_family(self):
+        assert model_forces_max_completion_tokens("qwen2.5-72b") is False
+
+    def test_deepseek_family(self):
+        assert model_forces_max_completion_tokens("deepseek-chat") is False
+
+
+# ─── Edge cases ─────────────────────────────────────────────────────────────
+
+
+class TestEdgeCases:
+    def test_empty_string(self):
+        assert model_forces_max_completion_tokens("") is False
+
+    def test_none(self):
+        assert model_forces_max_completion_tokens(None) is False  # type: ignore[arg-type]
+
+    def test_whitespace_only(self):
+        assert model_forces_max_completion_tokens("   ") is False
+
+    def test_case_insensitive(self):
+        assert model_forces_max_completion_tokens("GPT-5.4") is True
+        assert model_forces_max_completion_tokens("Gpt-4o-Mini") is True
+        assert model_forces_max_completion_tokens("O3-MINI") is True
+
+    def test_leading_trailing_whitespace(self):
+        assert model_forces_max_completion_tokens("  gpt-5  ") is True
+
+    def test_vendor_prefix_stripped(self):
+        # OpenRouter-style "vendor/model" names should match the tail.
+        assert model_forces_max_completion_tokens("openai/gpt-5.4") is True
+        assert model_forces_max_completion_tokens("openai/gpt-4o-mini") is True
+        assert model_forces_max_completion_tokens("openai/o3-mini") is True
+
+    def test_vendor_prefix_with_non_matching_tail(self):
+        assert model_forces_max_completion_tokens("openai/gpt-3.5-turbo") is False
+        assert model_forces_max_completion_tokens("anthropic/claude-3-opus") is False
+
+    def test_fake_prefix_not_matched(self):
+        # "o-series-but-not-really" doesn't start with o1/o3/o4.
+        assert model_forces_max_completion_tokens("omni-chat") is False
+        # "ox" isn't an o-series model, and "olive" / "opus" shouldn't collide.
+        assert model_forces_max_completion_tokens("ox-large") is False
+        assert model_forces_max_completion_tokens("opus-3") is False
+
+    def test_gpt_5_substring_in_middle_not_matched(self):
+        # Only a prefix should match — "local-gpt-5-clone" is a different model.
+        assert model_forces_max_completion_tokens("local-gpt-5-clone") is False

tests/test_tui_gateway_server.py

@@ -2397,7 +2397,7 @@ def test_config_set_model_waits_for_lazy_agent_before_switch(monkeypatch):
         target["agent"] = agent
         agent_ready.set()
 
-    def fake_apply(sid, target, raw):
+    def fake_apply(sid, target, raw, **kwargs):
         calls.append(("apply", sid, target.get("agent"), raw))
         if target.get("agent") is not agent:
             raise AssertionError("model switch ran before lazy agent was ready")
@@ -2424,7 +2424,7 @@ def test_config_set_model_uses_live_switch_path(monkeypatch):
     server._sessions["sid"] = _session()
     seen = {}
 
-    def _fake_apply(sid, session, raw):
+    def _fake_apply(sid, session, raw, **_kwargs):
         seen["args"] = (sid, session["session_key"], raw)
         return {"value": "new/model", "warning": "catalog unreachable"}
 
@@ -2442,6 +2442,74 @@ def test_config_set_model_uses_live_switch_path(monkeypatch):
     assert seen["args"] == ("sid", "session-key", "new/model")
 
 
+def test_config_set_model_requires_confirmation_for_expensive_model(monkeypatch):
+    class _Agent:
+        provider = "openrouter"
+        model = "old/model"
+        base_url = ""
+        api_key = "sk-or"
+        switched = False
+
+        def switch_model(self, **_kwargs):
+            self.switched = True
+
+    result = types.SimpleNamespace(
+        success=True,
+        new_model="openai/gpt-5.5-pro",
+        target_provider="openrouter",
+        api_key="sk-or",
+        base_url="https://openrouter.ai/api/v1",
+        api_mode="chat_completions",
+        warning_message="",
+        model_info=types.SimpleNamespace(
+            has_cost_data=lambda: True,
+            cost_input=25.0,
+            cost_output=125.0,
+        ),
+    )
+
+    agent = _Agent()
+    server._sessions["sid"] = _session(agent=agent)
+    monkeypatch.setattr(
+        "hermes_cli.model_switch.switch_model", lambda **_kwargs: result
+    )
+    monkeypatch.setattr(server, "_restart_slash_worker", lambda sid, session: None)
+    monkeypatch.setattr(server, "_emit", lambda *args, **kwargs: None)
+
+    resp = server.handle_request(
+        {
+            "id": "1",
+            "method": "config.set",
+            "params": {
+                "session_id": "sid",
+                "key": "model",
+                "value": "openai/gpt-5.5-pro --provider openrouter",
+            },
+        }
+    )
+
+    assert resp["result"]["confirm_required"] is True
+    assert "did you mean to select openai/gpt-5.5?" in resp["result"]["confirm_message"]
+    assert agent.switched is False
+
+    confirmed = server.handle_request(
+        {
+            "id": "2",
+            "method": "config.set",
+            "params": {
+                "session_id": "sid",
+                "key": "model",
+                "value": "openai/gpt-5.5-pro --provider openrouter",
+                "confirm_expensive_model": True,
+            },
+        }
+    )
+
+    assert confirmed["result"]["confirm_required"] is False
+    assert confirmed["result"]["value"] == "openai/gpt-5.5-pro"
+    assert agent.switched is True
+
+
 def test_config_set_model_global_persists(monkeypatch):
     class _Agent:
         provider = "openrouter"
@@ -3944,7 +4012,7 @@ def test_config_set_model_rejects_while_running(monkeypatch):
     """/model via config.set must reject during an in-flight turn."""
     seen = {"called": False}
 
-    def _fake_apply(sid, session, raw):
+    def _fake_apply(sid, session, raw, **_kwargs):
         seen["called"] = True
         return {"value": raw, "warning": ""}
 
@@ -3978,7 +4046,7 @@ def test_config_set_model_allowed_when_idle(monkeypatch):
     """Regression guard: idle sessions can still switch models."""
     seen = {"called": False}
 
-    def _fake_apply(sid, session, raw):
+    def _fake_apply(sid, session, raw, **_kwargs):
         seen["called"] = True
         return {"value": "newmodel", "warning": ""}
 

tests/tools/test_computer_use.py

@@ -338,7 +338,7 @@ class TestCaptureResponse:
         from tools.computer_use.backend import CaptureResult
         from tools.computer_use import tool as cu_tool
 
-        fake_png = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
+        fake_png = "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAADUlEQVR4nGNgGAUgAAABCAABgukLHQAAAABJRU5ErkJggg=="
 
         class FakeBackend:
             def start(self): pass
@@ -372,11 +372,41 @@ class TestCaptureResponse:
         assert any(p.get("type") == "image_url" for p in out["content"])
         assert any(p.get("type") == "text" for p in out["content"])
 
+    def test_capture_tiny_image_returns_text_json(self):
+        """Providers can reject <8px images, so placeholders must be omitted."""
+        from tools.computer_use.backend import CaptureResult, UIElement
+        from tools.computer_use import tool as cu_tool
+
+        tiny_png = "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAC0lEQVR4nGNgQAcAABIAAXfx+gAAAAAASUVORK5CYII="
+
+        cap = CaptureResult(
+            mode="som",
+            width=0,
+            height=0,
+            png_b64=tiny_png,
+            elements=[
+                UIElement(index=1, role="AXButton", label="Continue", bounds=(10, 20, 30, 30)),
+            ],
+            app="Safari",
+            window_title="Example",
+            png_bytes_len=68,
+        )
+
+        with patch.object(cu_tool, "_should_route_through_aux_vision",
+                          return_value=False):
+            out = cu_tool._capture_response(cap)
+
+        parsed = json.loads(out)
+        assert parsed["width"] == 2
+        assert parsed["height"] == 2
+        assert "screenshot omitted" in parsed["summary"]
+        assert parsed["elements"][0]["label"] == "Continue"
+
     def test_capture_som_with_elements_formats_index(self):
         from tools.computer_use.backend import CaptureResult, UIElement
         from tools.computer_use import tool as cu_tool
 
-        fake_png = "iVBORw0KGgo="
+        fake_png = "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAADUlEQVR4nGNgGAUgAAABCAABgukLHQAAAABJRU5ErkJggg=="
 
         class FakeBackend:
             def start(self): pass

tests/tools/test_computer_use_capture_routing.py

@@ -33,10 +33,10 @@ import pytest
 # Fixtures / helpers
 # ---------------------------------------------------------------------------
 
-# 1×1 PNG (transparent) — minimal bytes that decode cleanly.
+# 8×8 PNG (transparent) — minimal provider-acceptable bytes that decode cleanly.
 _PNG_B64 = (
-    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42m"
-    "NkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
+    "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAADUlEQVR4nG"
+    "NgGAUgAAABCAABgukLHQAAAABJRU5ErkJggg=="
 )
 
 # 1×1 JPEG — used to verify mime detection works for either stream type.

tests/tools/test_dockerfile_pid1_reaping.py

@@ -172,6 +172,31 @@ def test_dockerfile_preinstalls_gateway_messaging_dependencies(dockerfile_text):
     )
 
 
+def test_dockerfile_preinstalls_matrix_dependencies(dockerfile_text):
+    sync_steps = [
+        step for step in _run_steps(dockerfile_text)
+        if "uv sync" in step and "--no-install-project" in step
+    ]
+
+    assert sync_steps, "Dockerfile must install Python dependencies with uv sync"
+    assert any("--extra matrix" in step for step in sync_steps), (
+        "Published Docker images must preload the [matrix] extra so the "
+        "Matrix gateway has mautrix[encryption]/python-olm available at "
+        "runtime instead of relying on first-boot lazy installation into "
+        "the container venv (#30399)."
+    )
+
+
+def test_dockerfile_installs_matrix_native_build_dependencies(dockerfile_text):
+    instructions = _instruction_text(dockerfile_text)
+
+    for package in ("libolm-dev", "cmake", "g++", "make"):
+        assert package in instructions, (
+            "Docker image must include native build dependencies needed by "
+            f"python-olm when preinstalling the [matrix] extra (#30399): {package}"
+        )
+
+
 def test_dockerfile_preinstalls_hindsight_memory_dependency(dockerfile_text):
     sync_steps = [
         step for step in _run_steps(dockerfile_text)

tests/tools/test_mcp_stability.py

@@ -321,12 +321,19 @@ class TestStdioPgroupReaping:
 
         psutil = pytest.importorskip("psutil")
 
-        # Grandchild: sleep forever, write its pid then wait.
+        # Grandchild: sleep forever, write its pid then wait.  The pid file
+        # is written to a temp path and os.replace()d into place so the
+        # polling reader below can never observe a created-but-empty file
+        # (CI flake: int('') ValueError when the reader won the race between
+        # open('w') creating the file and write() filling it).
         grandchild_pid_file = tmp_path / "grandchild.pid"
         grandchild_script = tmp_path / "grandchild.py"
         grandchild_script.write_text(
             "import os, sys, time\n"
-            f"open({str(grandchild_pid_file)!r}, 'w').write(str(os.getpid()))\n"
+            f"tmp = {str(grandchild_pid_file)!r} + '.tmp'\n"
+            "with open(tmp, 'w') as f:\n"
+            "    f.write(str(os.getpid()))\n"
+            f"os.replace(tmp, {str(grandchild_pid_file)!r})\n"
             "while True:\n"
             "    time.sleep(0.5)\n"
         )

tests/tools/test_skills_hub.py

@@ -1,6 +1,8 @@
 """Tests for tools/skills_hub.py — source adapters, lock file, taps, dedup logic."""
 
 import json
+import time
+from typing import List, Optional
 from unittest.mock import patch, MagicMock
 
 import httpx
@@ -14,13 +16,15 @@ from tools.skills_hub import (
     UrlSource,
     WellKnownSkillSource,
     OptionalSkillSource,
-    SkillMeta,
+    SkillSource,
     SkillBundle,
+    SkillMeta,
     HubLockFile,
     TapsManager,
     bundle_content_hash,
     check_for_skill_updates,
     create_source_router,
+    parallel_search_sources,
     unified_search,
     append_audit_log,
     _skill_meta_to_dict,
@@ -2201,3 +2205,80 @@ class TestInstallPathSafety:
 
         assert not (skills_dir / "bad-skill" / "leak.txt").exists()
         assert secret.read_text() == "data exfiltration payload\n"
+
+
+# ---------------------------------------------------------------------------
+# parallel_search_sources — overall_timeout must be honoured even when a
+# source blocks for far longer than the budget (regression: the executor used
+# `with ... as pool`, whose __exit__ calls shutdown(wait=True) and blocked the
+# caller on the slow worker, making overall_timeout a no-op).
+# ---------------------------------------------------------------------------
+
+
+class _FakeSource(SkillSource):
+    def __init__(self, sid: str, sleep: float = 0.0, results=None):
+        self._sid = sid
+        self._sleep = sleep
+        self._results = results or []
+
+    def source_id(self) -> str:
+        return self._sid
+
+    def search(self, query: str, limit: int = 10) -> List[SkillMeta]:
+        if self._sleep:
+            time.sleep(self._sleep)
+        return list(self._results)
+
+    def fetch(self, identifier: str) -> Optional[SkillBundle]:
+        return None
+
+    def inspect(self, identifier: str) -> Optional[SkillMeta]:
+        return None
+
+
+class TestParallelSearchSourcesTimeout:
+    def _meta(self, sid: str) -> SkillMeta:
+        return SkillMeta(
+            name=f"{sid}-skill",
+            description="x",
+            source=sid,
+            identifier=f"{sid}/x",
+            trust_level="community",
+        )
+
+    def test_slow_source_does_not_block_caller(self):
+        """A source sleeping well past overall_timeout must not stall the
+        return. Before the fix the executor's `with` block waited on the slow
+        worker (~5s); now the call returns promptly and reports the source as
+        timed out."""
+        fast = _FakeSource("fast", sleep=0.0, results=[self._meta("fast")])
+        slow = _FakeSource("slow", sleep=5.0, results=[self._meta("slow")])
+
+        start = time.monotonic()
+        all_results, source_counts, timed_out_ids = parallel_search_sources(
+            [fast, slow], query="q", overall_timeout=0.3,
+        )
+        elapsed = time.monotonic() - start
+
+        # Must return long before the slow source's 5s sleep finishes.
+        assert elapsed < 2.0, f"call blocked for {elapsed:.2f}s (timeout not honoured)"
+        assert "slow" in timed_out_ids
+        # Fast source still delivered its result and is not flagged timed out.
+        assert source_counts.get("fast") == 1
+        assert "fast" not in timed_out_ids
+        assert any(r.source == "fast" for r in all_results)
+
+    def test_all_fast_sources_complete_without_timeout(self):
+        """Happy path: when every source finishes within budget, none are
+        flagged and all results are collected."""
+        a = _FakeSource("a", results=[self._meta("a")])
+        b = _FakeSource("b", results=[self._meta("b")])
+
+        all_results, source_counts, timed_out_ids = parallel_search_sources(
+            [a, b], query="q", overall_timeout=5.0,
+        )
+
+        assert timed_out_ids == []
+        assert source_counts.get("a") == 1
+        assert source_counts.get("b") == 1
+        assert len(all_results) == 2

tests/tools/test_skills_hub_clawhub.py

@@ -350,6 +350,184 @@ class TestClawHubSource(unittest.TestCase):
         self.assertIn("b-skill-199", identifiers)
         self.assertIn("c-skill-49", identifiers)
 
+    @patch("tools.skills_hub._write_index_cache")
+    @patch("tools.skills_hub._read_index_cache", return_value=None)
+    @patch("tools.skills_hub.httpx.get")
+    def test_catalog_walk_aborts_on_budget_and_does_not_poison_cache(
+        self, mock_get, _mock_read_cache, mock_write_cache
+    ):
+        """A walk truncated by the wall-clock budget must stop early and must
+        NOT write the (partial) result to the cache. Before the budget guard
+        the walk ran up to 750 pages and cached unconditionally — a truncated
+        walk poisoned the cache with incomplete catalog data."""
+        page_calls = {"n": 0}
+
+        def side_effect(url, *args, **kwargs):
+            if url.endswith("/skills"):
+                idx = page_calls["n"]
+                page_calls["n"] += 1
+                # Always advertise another page so the walk would never stop
+                # on its own — only the budget can break it.
+                return _MockResponse(
+                    status_code=200,
+                    json_data={
+                        "items": [
+                            {"slug": f"skill-{idx}", "displayName": f"Skill {idx}"}
+                        ],
+                        "nextCursor": f"cursor-{idx + 1}",
+                    },
+                )
+            return _MockResponse(status_code=404, json_data={})
+
+        mock_get.side_effect = side_effect
+
+        # Force the deadline to be in the past immediately.
+        with patch.object(ClawHubSource, "CATALOG_WALK_BUDGET_SECONDS", -1):
+            results = self.src._load_catalog_index()
+
+        # Walk broke well before the 750-page cap.
+        self.assertLess(page_calls["n"], 750)
+        # Truncated walk must not poison the cache.
+        mock_write_cache.assert_not_called()
+        # Whatever was gathered is still returned to the caller.
+        self.assertIsInstance(results, list)
+
+    @patch("tools.skills_hub._write_index_cache")
+    @patch("tools.skills_hub._read_index_cache", return_value=None)
+    @patch("tools.skills_hub.httpx.get")
+    def test_catalog_walk_caches_when_terminating_naturally_within_budget(
+        self, mock_get, _mock_read_cache, mock_write_cache
+    ):
+        """Happy path: a walk that exhausts the cursor within the budget DOES
+        write the cache."""
+
+        def side_effect(url, *args, **kwargs):
+            if url.endswith("/skills"):
+                return _MockResponse(
+                    status_code=200,
+                    json_data={
+                        "items": [
+                            {"slug": "only-skill", "displayName": "Only Skill"}
+                        ],
+                        # No nextCursor -> natural termination.
+                    },
+                )
+            return _MockResponse(status_code=404, json_data={})
+
+        mock_get.side_effect = side_effect
+
+        results = self.src._load_catalog_index()
+
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].identifier, "only-skill")
+        mock_write_cache.assert_called_once()
+
+
+class TestClawHubCatalogWalkBounded(unittest.TestCase):
+    """max_items bounds the walk so browse's cold-start fallback renders one
+    page without walking the entire 50k+ catalog. The offline index builder
+    keeps max_items=0 (unbounded) and walks to exhaustion."""
+
+    def setUp(self):
+        self.src = ClawHubSource()
+        self._safe_patcher = patch("tools.skills_hub.is_safe_url", return_value=True)
+        self._policy_patcher = patch("tools.skills_hub.check_website_access", return_value=None)
+        self._safe_patcher.start()
+        self._policy_patcher.start()
+
+    def tearDown(self):
+        self._policy_patcher.stop()
+        self._safe_patcher.stop()
+
+    def _infinite_pages(self, page_calls):
+        """A side_effect that always advertises another cursor — the walk would
+        never stop on its own, so only max_items / budget can break it."""
+
+        def side_effect(url, *args, **kwargs):
+            if url.endswith("/skills"):
+                idx = page_calls["n"]
+                page_calls["n"] += 1
+                return _MockResponse(
+                    status_code=200,
+                    json_data={
+                        "items": [
+                            {"slug": f"skill-{idx}", "displayName": f"Skill {idx}"}
+                        ],
+                        "nextCursor": f"cursor-{idx + 1}",
+                    },
+                )
+            return _MockResponse(status_code=404, json_data={})
+
+        return side_effect
+
+    @patch("tools.skills_hub._write_index_cache")
+    @patch("tools.skills_hub._read_index_cache", return_value=None)
+    @patch("tools.skills_hub.httpx.get")
+    def test_max_items_stops_walk_early_and_does_not_cache(
+        self, mock_get, _mock_read_cache, mock_write_cache
+    ):
+        """A bounded walk stops as soon as it has >= max_items skills and must
+        NOT poison the shared full-catalog cache with the partial slice."""
+        page_calls = {"n": 0}
+        mock_get.side_effect = self._infinite_pages(page_calls)
+
+        results = self.src._load_catalog_index(max_items=5)
+
+        # Each mocked page yields exactly 1 item, so ~5 pages cover the bound.
+        self.assertGreaterEqual(len(results), 5)
+        self.assertLess(page_calls["n"], 750, "bounded walk should stop well before the cap")
+        self.assertLess(page_calls["n"], 20, "should stop within a few pages of the bound")
+        # Partial (bounded) walk must not be cached.
+        mock_write_cache.assert_not_called()
+
+    @patch("tools.skills_hub._write_index_cache")
+    @patch("tools.skills_hub._read_index_cache", return_value=None)
+    @patch("tools.skills_hub.httpx.get")
+    def test_max_items_zero_is_unbounded_and_caches(
+        self, mock_get, _mock_read_cache, mock_write_cache
+    ):
+        """max_items=0 (the index builder's path) walks to natural termination
+        and DOES cache the complete catalog."""
+
+        def side_effect(url, *args, **kwargs):
+            if url.endswith("/skills"):
+                return _MockResponse(
+                    status_code=200,
+                    json_data={
+                        "items": [
+                            {"slug": "a", "displayName": "A"},
+                            {"slug": "b", "displayName": "B"},
+                            {"slug": "c", "displayName": "C"},
+                        ],
+                        # No nextCursor -> natural termination.
+                    },
+                )
+            return _MockResponse(status_code=404, json_data={})
+
+        mock_get.side_effect = side_effect
+
+        results = self.src._load_catalog_index(max_items=0)
+
+        self.assertEqual(len(results), 3)
+        mock_write_cache.assert_called_once()
+
+    @patch("tools.skills_hub._write_index_cache")
+    @patch("tools.skills_hub._read_index_cache", return_value=None)
+    @patch("tools.skills_hub.httpx.get")
+    def test_empty_query_browse_bounds_walk_to_limit(
+        self, mock_get, _mock_read_cache, _mock_write_cache
+    ):
+        """search("", limit=N) is the browse cold-start path — it must bound the
+        catalog walk to N rather than walking the whole 50k+ catalog."""
+        page_calls = {"n": 0}
+        mock_get.side_effect = self._infinite_pages(page_calls)
+
+        results = self.src.search("", limit=10)
+
+        self.assertEqual(len(results), 10, "browse page should be exactly `limit` items")
+        # Walk stopped near the bound, not at the 750-page cap.
+        self.assertLess(page_calls["n"], 30)
+
 
 if __name__ == "__main__":
     unittest.main()

tests/tools/test_tts_gemini.py

@@ -2,6 +2,7 @@
 
 import base64
 import struct
+from types import SimpleNamespace
 from unittest.mock import MagicMock, patch
 
 import pytest
@@ -255,6 +256,169 @@ class TestGenerateGeminiTts:
 
         assert mock_post.call_args[0][0].startswith("https://custom-gemini.example.com/v1beta/")
 
+    def test_persona_prompt_file_appends_labeled_transcript(
+        self, tmp_path, monkeypatch, mock_gemini_response
+    ):
+        from tools.tts_tool import _generate_gemini_tts
+
+        persona_file = tmp_path / "voice-persona.md"
+        persona_file.write_text(
+            "# AUDIO PROFILE: Dry Butler\n\n### DIRECTOR'S NOTES\nStyle: Understated.",
+            encoding="utf-8",
+        )
+        config = {"gemini": {"persona_prompt_file": str(persona_file)}}
+        monkeypatch.setenv("GEMINI_API_KEY", "test-key")
+
+        with patch("requests.post", return_value=mock_gemini_response) as mock_post:
+            _generate_gemini_tts("Hi", str(tmp_path / "test.wav"), config)
+
+        prompt_text = mock_post.call_args[1]["json"]["contents"][0]["parts"][0]["text"]
+        assert "Synthesize speech from the TRANSCRIPT only" in prompt_text
+        assert "# AUDIO PROFILE: Dry Butler" in prompt_text
+        assert "### DIRECTOR'S NOTES\nStyle: Understated." in prompt_text
+        assert "#### TRANSCRIPT\nHi" in prompt_text
+
+    def test_persona_prompt_file_supports_transcript_placeholder(
+        self, tmp_path, monkeypatch, mock_gemini_response
+    ):
+        from tools.tts_tool import _generate_gemini_tts
+
+        persona_file = tmp_path / "voice-persona.md"
+        persona_file.write_text(
+            "### DIRECTOR'S NOTES\nPacing: Slow.\n\n#### TRANSCRIPT\n{{ transcript }}",
+            encoding="utf-8",
+        )
+        config = {"gemini": {"persona_prompt_file": str(persona_file)}}
+        monkeypatch.setenv("GEMINI_API_KEY", "test-key")
+
+        with patch("requests.post", return_value=mock_gemini_response) as mock_post:
+            _generate_gemini_tts("Read this.", str(tmp_path / "test.wav"), config)
+
+        prompt_text = mock_post.call_args[1]["json"]["contents"][0]["parts"][0]["text"]
+        assert "{{ transcript }}" not in prompt_text
+        assert "#### TRANSCRIPT\nRead this." in prompt_text
+
+    def test_missing_persona_prompt_file_warns_and_continues(
+        self, tmp_path, monkeypatch, caplog, mock_gemini_response
+    ):
+        from tools.tts_tool import _generate_gemini_tts
+
+        config = {"gemini": {"persona_prompt_file": str(tmp_path / "missing.md")}}
+        monkeypatch.setenv("GEMINI_API_KEY", "test-key")
+
+        with patch("requests.post", return_value=mock_gemini_response) as mock_post:
+            _generate_gemini_tts("Hi", str(tmp_path / "test.wav"), config)
+
+        prompt_text = mock_post.call_args[1]["json"]["contents"][0]["parts"][0]["text"]
+        assert prompt_text == "Hi"
+        assert "persona prompt file unavailable" in caplog.text
+
+    def test_audio_tags_disabled_does_not_call_rewriter(
+        self, tmp_path, monkeypatch, mock_gemini_response
+    ):
+        from tools.tts_tool import _generate_gemini_tts
+
+        config = {
+            "gemini": {
+                "model": "gemini-3.1-flash-tts-preview",
+                "audio_tags": False,
+            }
+        }
+        monkeypatch.setenv("GEMINI_API_KEY", "test-key")
+
+        with patch("agent.auxiliary_client.call_llm") as mock_call_llm, \
+             patch("requests.post", return_value=mock_gemini_response) as mock_post:
+            _generate_gemini_tts("Hi there.", str(tmp_path / "test.wav"), config)
+
+        mock_call_llm.assert_not_called()
+        prompt_text = mock_post.call_args[1]["json"]["contents"][0]["parts"][0]["text"]
+        assert prompt_text == "Hi there."
+
+    def test_audio_tags_enabled_rewrites_hidden_tts_script(
+        self, tmp_path, monkeypatch, mock_gemini_response
+    ):
+        from tools.tts_tool import _generate_gemini_tts
+
+        persona_file = tmp_path / "voice-persona.md"
+        persona_file.write_text(
+            "### DIRECTOR'S NOTES\nStyle: Warm and amused.",
+            encoding="utf-8",
+        )
+        response = SimpleNamespace(
+            choices=[
+                SimpleNamespace(
+                    message=SimpleNamespace(content="[warmly] Hi there. [soft laugh]")
+                )
+            ]
+        )
+        config = {
+            "gemini": {
+                "model": "gemini-3.1-flash-tts-preview",
+                "audio_tags": True,
+                "persona_prompt_file": str(persona_file),
+            }
+        }
+        monkeypatch.setenv("GEMINI_API_KEY", "test-key")
+
+        with patch("agent.auxiliary_client.call_llm", return_value=response) as mock_call_llm, \
+             patch("requests.post", return_value=mock_gemini_response) as mock_post:
+            _generate_gemini_tts("Hi there.", str(tmp_path / "test.wav"), config)
+
+        mock_call_llm.assert_called_once()
+        call_kwargs = mock_call_llm.call_args.kwargs
+        assert call_kwargs["task"] == "tts_audio_tags"
+        assert "Audio tags are inline square-bracket modifiers" in call_kwargs["messages"][0]["content"]
+        assert "Style: Warm and amused." in call_kwargs["messages"][1]["content"]
+        assert "Hi there." in call_kwargs["messages"][1]["content"]
+
+        prompt_text = mock_post.call_args[1]["json"]["contents"][0]["parts"][0]["text"]
+        assert "Synthesize speech from the TRANSCRIPT only" in prompt_text
+        assert "### DIRECTOR'S NOTES\nStyle: Warm and amused." in prompt_text
+        assert "#### TRANSCRIPT\n[warmly] Hi there. [soft laugh]" in prompt_text
+
+    def test_audio_tags_enabled_skips_non_tag_capable_model(
+        self, tmp_path, monkeypatch, mock_gemini_response, caplog
+    ):
+        from tools.tts_tool import _generate_gemini_tts
+
+        config = {
+            "gemini": {
+                "model": "gemini-2.5-flash-preview-tts",
+                "audio_tags": True,
+            }
+        }
+        monkeypatch.setenv("GEMINI_API_KEY", "test-key")
+
+        with patch("agent.auxiliary_client.call_llm") as mock_call_llm, \
+             patch("requests.post", return_value=mock_gemini_response) as mock_post:
+            _generate_gemini_tts("Hi there.", str(tmp_path / "test.wav"), config)
+
+        mock_call_llm.assert_not_called()
+        prompt_text = mock_post.call_args[1]["json"]["contents"][0]["parts"][0]["text"]
+        assert prompt_text == "Hi there."
+        assert "not known to support Gemini audio tags" in caplog.text
+
+    def test_audio_tag_rewrite_failure_falls_back_to_original_text(
+        self, tmp_path, monkeypatch, mock_gemini_response, caplog
+    ):
+        from tools.tts_tool import _generate_gemini_tts
+
+        config = {
+            "gemini": {
+                "model": "gemini-3.1-flash-tts-preview",
+                "audio_tags": True,
+            }
+        }
+        monkeypatch.setenv("GEMINI_API_KEY", "test-key")
+
+        with patch("agent.auxiliary_client.call_llm", side_effect=RuntimeError("boom")), \
+             patch("requests.post", return_value=mock_gemini_response) as mock_post:
+            _generate_gemini_tts("Hi there.", str(tmp_path / "test.wav"), config)
+
+        prompt_text = mock_post.call_args[1]["json"]["contents"][0]["parts"][0]["text"]
+        assert prompt_text == "Hi there."
+        assert "audio tag rewrite failed" in caplog.text
+
 
 class TestGeminiInCheckRequirements:
     def test_gemini_api_key_satisfies_requirements(self, monkeypatch):

tests/tools/test_web_tools_config.py

@@ -340,12 +340,13 @@ class TestBackendSelection:
              patch.dict(os.environ, {"EXA_API_KEY": "exa-test"}):
             assert _get_backend() == "exa"
 
-    def test_fallback_parallel_takes_priority_over_exa(self):
-        """Exa should only win the fallback path when it is the only configured backend."""
+    def test_fallback_exa_takes_priority_over_parallel(self):
+        """Direct-credential backends are tried in the order tavily > exa > parallel
+        so an explicit Exa key wins when both Exa and Parallel are configured."""
         from tools.web_tools import _get_backend
         with patch("tools.web_tools._load_web_config", return_value={}), \
              patch.dict(os.environ, {"EXA_API_KEY": "exa-test", "PARALLEL_API_KEY": "par-test"}):
-            assert _get_backend() == "parallel"
+            assert _get_backend() == "exa"
 
     def test_fallback_tavily_only_key(self):
         """Only TAVILY_API_KEY set → 'tavily'."""
@@ -354,27 +355,27 @@ class TestBackendSelection:
              patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-test"}):
             assert _get_backend() == "tavily"
 
-    def test_fallback_tavily_with_firecrawl_prefers_firecrawl(self):
-        """Tavily + Firecrawl keys, no config → 'firecrawl' (backward compat)."""
+    def test_fallback_tavily_beats_firecrawl_direct(self):
+        """Tavily ranks above firecrawl in the explicit-credential block."""
         from tools.web_tools import _get_backend
         with patch("tools.web_tools._load_web_config", return_value={}), \
              patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-test", "FIRECRAWL_API_KEY": "fc-test"}):
-            assert _get_backend() == "firecrawl"
+            assert _get_backend() == "tavily"
 
-    def test_fallback_tavily_with_parallel_prefers_parallel(self):
-        """Tavily + Parallel keys, no config → 'parallel' (Parallel takes priority over Tavily)."""
+    def test_fallback_tavily_beats_parallel(self):
+        """Tavily is first in the explicit-credential block so it wins over parallel."""
         from tools.web_tools import _get_backend
         with patch("tools.web_tools._load_web_config", return_value={}), \
              patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-test", "PARALLEL_API_KEY": "par-test"}):
-            # Parallel + no Firecrawl → parallel
-            assert _get_backend() == "parallel"
+            assert _get_backend() == "tavily"
 
-    def test_fallback_both_keys_defaults_to_firecrawl(self):
-        """Both keys set, no config → 'firecrawl' (backward compat)."""
+    def test_fallback_parallel_beats_firecrawl_direct(self):
+        """Parallel + Firecrawl-direct → parallel (parallel is the higher-priority
+        explicit-credential backend; firecrawl-direct ranks below it)."""
         from tools.web_tools import _get_backend
         with patch("tools.web_tools._load_web_config", return_value={}), \
              patch.dict(os.environ, {"PARALLEL_API_KEY": "test-key", "FIRECRAWL_API_KEY": "fc-test"}):
-            assert _get_backend() == "firecrawl"
+            assert _get_backend() == "parallel"
 
     def test_fallback_firecrawl_only_key(self):
         """Only FIRECRAWL_API_KEY set → 'firecrawl'."""
@@ -396,6 +397,27 @@ class TestBackendSelection:
              patch.dict(os.environ, {"PARALLEL_API_KEY": "test-key"}):
             assert _get_backend() == "parallel"
 
+    def test_managed_gateway_does_not_preempt_explicit_tavily(self):
+        """Regression: a Nous OAuth token (managed gateway "ready") must NOT
+        beat an explicitly configured TAVILY_API_KEY in the fallback path.
+        Free Nous tiers don't include web search, so the user's deliberate
+        Tavily setup would fail at runtime with "no subscription" if the
+        gateway pre-empted it."""
+        from tools.web_tools import _get_backend
+        with patch("tools.web_tools._load_web_config", return_value={}), \
+             patch("tools.web_tools._is_tool_gateway_ready", return_value=True), \
+             patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-test"}):
+            assert _get_backend() == "tavily"
+
+    def test_managed_gateway_only_falls_through_to_firecrawl(self):
+        """When no explicit-credential backend is configured, a Nous-managed
+        gateway token still selects firecrawl — the convenience path is
+        preserved, just no longer pre-empts."""
+        from tools.web_tools import _get_backend
+        with patch("tools.web_tools._load_web_config", return_value={}), \
+             patch("tools.web_tools._is_tool_gateway_ready", return_value=True):
+            assert _get_backend() == "firecrawl"
+
 
 class TestParallelClientConfig:
     """Test suite for Parallel client initialization."""

tests/tools/test_write_approval.py

@@ -1,9 +1,10 @@
 """Tests for the memory/skill write-approval gate (tools/write_approval.py)
 and the shared slash-command handlers (hermes_cli/write_approval_commands.py).
 
-Covers the tri-state write_mode (on/off/approve) for both subsystems, the
-foreground-vs-background staging split, pending store CRUD, and the
-list/approve/reject/diff/mode subcommand dispatch.
+Covers the boolean write_approval gate (off by default = write freely; on =
+require approval) for both subsystems, the foreground-vs-background staging
+split, pending store CRUD, and the list/approve/reject/diff/approval
+subcommand dispatch.
 """
 
 import json
@@ -24,64 +25,64 @@ def hermes_home(monkeypatch):
     shutil.rmtree(d, ignore_errors=True)
 
 
-def _set_mode(subsystem, mode):
+def _set_approval(subsystem, enabled):
     import hermes_cli.config as cfg
     c = cfg.load_config()
-    c.setdefault(subsystem, {})["write_mode"] = mode
+    c.setdefault(subsystem, {})["write_approval"] = enabled
     cfg.save_config(c)
 
 
 # ---------------------------------------------------------------------------
-# Mode resolution
+# Config resolution
 # ---------------------------------------------------------------------------
 
-def test_default_write_mode_is_on(hermes_home):
+def test_default_gate_is_off(hermes_home):
     from tools import write_approval as wa
-    assert wa.get_write_mode("memory") == "on"
-    assert wa.get_write_mode("skills") == "on"
+    # Default: gate off → writes flow freely.
+    assert wa.write_approval_enabled("memory") is False
+    assert wa.write_approval_enabled("skills") is False
 
 
-def test_invalid_subsystem_returns_on(hermes_home):
+def test_invalid_subsystem_is_off(hermes_home):
     from tools import write_approval as wa
-    assert wa.get_write_mode("bogus") == "on"
+    assert wa.write_approval_enabled("bogus") is False
 
 
-def test_normalize_mode_handles_yaml_bool():
+def test_normalize_enabled_coerces_values():
     from tools import write_approval as wa
-    assert wa._normalize_mode(False) == "off"
-    assert wa._normalize_mode(True) == "on"
-    assert wa._normalize_mode("approve") == "approve"
-    assert wa._normalize_mode("garbage") == "on"
+    # Real bools pass through.
+    assert wa._normalize_enabled(True) is True
+    assert wa._normalize_enabled(False) is False
+    # Truthy strings → True (incl. legacy 'approve').
+    assert wa._normalize_enabled("on") is True
+    assert wa._normalize_enabled("approve") is True
+    assert wa._normalize_enabled("true") is True
+    # Everything else → False (gate off is the safe default).
+    assert wa._normalize_enabled("off") is False
+    assert wa._normalize_enabled("garbage") is False
+    assert wa._normalize_enabled(None) is False
 
 
 # ---------------------------------------------------------------------------
 # Memory gate
 # ---------------------------------------------------------------------------
 
-def test_memory_off_blocks_write(hermes_home):
+def test_memory_gate_off_allows_write(hermes_home):
+    # Default (gate off) → write straight through, no staging.
     from tools.memory_tool import memory_tool, MemoryStore
-    _set_mode("memory", "off")
-    store = MemoryStore(); store.load_from_disk()
-    r = json.loads(memory_tool("add", "user", "should not save", store=store))
-    assert r["success"] is False
-    assert "disabled" in r["error"].lower()
-    assert store.user_entries == []
-
-
-def test_memory_on_allows_write(hermes_home):
-    from tools.memory_tool import memory_tool, MemoryStore
-    _set_mode("memory", "on")
+    from tools import write_approval as wa
     store = MemoryStore(); store.load_from_disk()
     r = json.loads(memory_tool("add", "user", "save me", store=store))
     assert r["success"] is True
     assert r["entry_count"] == 1
+    assert wa.pending_count("memory") == 0
 
 
-def test_memory_approve_no_interactive_stages(hermes_home):
-    # No approval callback registered and not a gateway context → stage.
+def test_memory_gate_on_no_interactive_stages(hermes_home):
+    # Gate on, no approval callback / not a gateway context → stage.
     from tools.memory_tool import memory_tool, MemoryStore
     from tools import write_approval as wa
-    _set_mode("memory", "approve")
+    _set_approval("memory", True)
     store = MemoryStore(); store.load_from_disk()
     r = json.loads(memory_tool("add", "memory", "stage me", store=store))
     assert r.get("staged") is True
@@ -93,10 +94,10 @@ def test_memory_approve_no_interactive_stages(hermes_home):
     assert pend[0]["id"] == r["pending_id"]
 
 
-def test_memory_approve_then_apply(hermes_home):
+def test_memory_gate_on_then_apply(hermes_home):
     from tools.memory_tool import memory_tool, MemoryStore, apply_memory_pending
     from tools import write_approval as wa
-    _set_mode("memory", "approve")
+    _set_approval("memory", True)
     store = MemoryStore(); store.load_from_disk()
     r = json.loads(memory_tool("add", "user", "approved entry", store=store))
     pid = r["pending_id"]
@@ -116,33 +117,36 @@ _SKILL = (
 )
 
 
-def test_skill_off_blocks_create(hermes_home):
-    from tools.skill_manager_tool import skill_manage
-    _set_mode("skills", "off")
-    r = json.loads(skill_manage("create", "blocked-skill", content=_SKILL))
-    assert r["success"] is False
-    assert "disabled" in r["error"].lower()
+def test_skill_gate_off_allows_create(hermes_home):
+    # Default (gate off) → skill is created normally, not staged.
+    import importlib
+    import tools.skill_manager_tool as smt
+    importlib.reload(smt)
+    from tools import write_approval as wa
+    r = json.loads(smt.skill_manage("create", "free-skill", content=_SKILL))
+    assert r.get("success") is True
+    assert wa.pending_count("skills") == 0
 
 
-def test_skill_approve_always_stages(hermes_home):
+def test_skill_gate_on_always_stages(hermes_home):
     # Skills stage even in the foreground (too big to review inline).
     from tools.skill_manager_tool import skill_manage
     from tools import write_approval as wa
-    _set_mode("skills", "approve")
+    _set_approval("skills", True)
     r = json.loads(skill_manage("create", "staged-skill", content=_SKILL))
     assert r.get("staged") is True
     assert "staged-skill" in r.get("gist", "")
     assert wa.pending_count("skills") == 1
 
 
-def test_skill_approve_then_apply_writes_file(hermes_home):
+def test_skill_gate_on_then_apply_writes_file(hermes_home):
     # SKILLS_DIR is resolved at import time, so reload the skill module under
     # this test's HERMES_HOME to exercise the real on-disk write path.
     import importlib
     import tools.skill_manager_tool as smt
     importlib.reload(smt)
     from tools import write_approval as wa
-    _set_mode("skills", "approve")
+    _set_approval("skills", True)
     r = json.loads(smt.skill_manage("create", "applied-skill", content=_SKILL))
     rec = wa.get_pending("skills", r["pending_id"])
     res = json.loads(smt.apply_skill_pending(rec["payload"]))
@@ -153,7 +157,7 @@ def test_skill_approve_then_apply_writes_file(hermes_home):
 def test_skill_create_diff_is_full_content(hermes_home):
     from tools.skill_manager_tool import skill_manage
     from tools import write_approval as wa
-    _set_mode("skills", "approve")
+    _set_approval("skills", True)
     r = json.loads(skill_manage("create", "diff-skill", content=_SKILL))
     rec = wa.get_pending("skills", r["pending_id"])
     diff = wa.skill_pending_diff(rec)
@@ -212,24 +216,49 @@ def test_handle_reject(hermes_home):
     assert wa.pending_count("skills") == 0
 
 
-def test_handle_mode_set(hermes_home):
+def test_handle_approval_on(hermes_home):
     from hermes_cli.write_approval_commands import handle_pending_subcommand
     from tools import write_approval as wa
     captured = {}
     out = handle_pending_subcommand(
-        wa.MEMORY, ["mode", "approve"],
-        set_mode_fn=lambda m: captured.update(mode=m),
+        wa.MEMORY, ["approval", "on"],
+        set_mode_fn=lambda enabled: captured.update(enabled=enabled),
     )
-    assert captured["mode"] == "approve"
-    assert "approve" in out
+    assert captured["enabled"] is True
+    assert "on" in out
 
 
-def test_handle_mode_invalid(hermes_home):
+def test_handle_approval_off(hermes_home):
     from hermes_cli.write_approval_commands import handle_pending_subcommand
     from tools import write_approval as wa
-    out = handle_pending_subcommand(wa.MEMORY, ["mode", "bogus"],
-                                    set_mode_fn=lambda m: None)
-    assert "Invalid mode" in out
+    captured = {}
+    out = handle_pending_subcommand(
+        wa.SKILLS, ["approval", "off"],
+        set_mode_fn=lambda enabled: captured.update(enabled=enabled),
+    )
+    assert captured["enabled"] is False
+    assert "off" in out
+
+
+def test_handle_mode_alias_still_works(hermes_home):
+    # 'mode' is kept as a back-compat alias for 'approval'.
+    from hermes_cli.write_approval_commands import handle_pending_subcommand
+    from tools import write_approval as wa
+    captured = {}
+    out = handle_pending_subcommand(
+        wa.MEMORY, ["mode", "on"],
+        set_mode_fn=lambda enabled: captured.update(enabled=enabled),
+    )
+    assert captured["enabled"] is True
+    assert "on" in out
+
+
+def test_handle_approval_invalid(hermes_home):
+    from hermes_cli.write_approval_commands import handle_pending_subcommand
+    from tools import write_approval as wa
+    out = handle_pending_subcommand(wa.MEMORY, ["approval", "bogus"],
+                                    set_mode_fn=lambda enabled: None)
+    assert "Invalid value" in out
 
 
 def test_handle_unknown_subcommand_returns_none(hermes_home):
@@ -239,3 +268,117 @@ def test_handle_unknown_subcommand_returns_none(hermes_home):
     # the CLI falls through to the skills hub.
     out = handle_pending_subcommand(wa.SKILLS, ["search", "foo"])
     assert out is None
+
+
+# ---------------------------------------------------------------------------
+# Inline (interactive CLI) approval path — regression for the bug where the
+# per-thread approval callback was never passed to prompt_dangerous_approval,
+# so every gated foreground memory write was silently denied.
+# ---------------------------------------------------------------------------
+
+@pytest.fixture
+def approval_callback_cleanup():
+    yield
+    from tools.terminal_tool import set_approval_callback
+    set_approval_callback(None)
+
+
+def test_memory_inline_approve_writes(hermes_home, approval_callback_cleanup):
+    from tools.memory_tool import memory_tool, MemoryStore
+    from tools.terminal_tool import set_approval_callback
+    from tools import write_approval as wa
+    _set_approval("memory", True)
+
+    calls = []
+    def approve_cb(command, description, **kw):
+        calls.append((command, description))
+        return "once"
+    set_approval_callback(approve_cb)
+
+    store = MemoryStore(); store.load_from_disk()
+    r = json.loads(memory_tool("add", "memory", "approved fact", store=store))
+    assert r["success"] is True
+    assert r.get("staged") is None  # real write, not staged
+    assert store.memory_entries == ["approved fact"]
+    assert wa.pending_count("memory") == 0
+    # The registered callback must actually be invoked (not the input() path).
+    assert len(calls) == 1
+    assert "approved fact" in calls[0][0]
+
+
+def test_memory_inline_deny_blocks(hermes_home, approval_callback_cleanup):
+    from tools.memory_tool import memory_tool, MemoryStore
+    from tools.terminal_tool import set_approval_callback
+    from tools import write_approval as wa
+    _set_approval("memory", True)
+    set_approval_callback(lambda command, description, **kw: "deny")
+
+    store = MemoryStore(); store.load_from_disk()
+    r = json.loads(memory_tool("add", "memory", "denied fact", store=store))
+    assert r["success"] is False
+    assert "denied" in r["error"].lower()
+    assert store.memory_entries == []
+    assert wa.pending_count("memory") == 0  # denied, not staged
+
+
+def test_memory_inline_callback_error_stages(hermes_home, approval_callback_cleanup):
+    # If the prompt machinery fails, fall back to staging — never drop silently.
+    from tools.memory_tool import memory_tool, MemoryStore
+    from tools.terminal_tool import set_approval_callback
+    from tools import write_approval as wa
+    _set_approval("memory", True)
+    def broken_cb(command, description, **kw):
+        raise RuntimeError("boom")
+    set_approval_callback(broken_cb)
+
+    store = MemoryStore(); store.load_from_disk()
+    r = json.loads(memory_tool("add", "memory", "fallback fact", store=store))
+    assert r.get("staged") is True
+    assert wa.pending_count("memory") == 1
+
+
+def test_gateway_context_stages_not_prompts(hermes_home, monkeypatch):
+    # A gateway session has no per-thread CLI callback; the dangerous-command
+    # /approve round-trip lives in the pending-queue machinery which the gate
+    # does not use. The gate must stage, never attempt an inline prompt
+    # (which would hit the input() fallback and silently deny).
+    from tools.memory_tool import memory_tool, MemoryStore
+    from tools import write_approval as wa
+    _set_approval("memory", True)
+    monkeypatch.setenv("HERMES_GATEWAY_SESSION", "1")
+
+    store = MemoryStore(); store.load_from_disk()
+    r = json.loads(memory_tool("add", "memory", "gateway fact", store=store))
+    assert r.get("staged") is True
+    assert store.memory_entries == []
+    assert wa.pending_count("memory") == 1
+
+
+def test_skills_never_prompt_inline_even_with_callback(hermes_home, approval_callback_cleanup):
+    # Skills always stage — even when an interactive callback is registered.
+    from tools.skill_manager_tool import skill_manage
+    from tools.terminal_tool import set_approval_callback
+    from tools import write_approval as wa
+    _set_approval("skills", True)
+
+    calls = []
+    set_approval_callback(lambda c, d, **kw: calls.append(1) or "once")
+
+    r = json.loads(skill_manage(
+        action="create", name="test-inline-skill",
+        content="---\nname: test-inline-skill\ndescription: x\n---\nbody\n"))
+    assert r.get("staged") is True
+    assert calls == []  # never prompted
+    assert wa.pending_count("skills") == 1
+
+
+def test_memory_invalid_params_rejected_before_staging(hermes_home):
+    # Param validation must run BEFORE the gate so a broken write is rejected
+    # immediately instead of staged and failing at approve time.
+    from tools.memory_tool import memory_tool, MemoryStore
+    from tools import write_approval as wa
+    _set_approval("memory", True)
+    store = MemoryStore(); store.load_from_disk()
+    r = json.loads(memory_tool("add", "memory", None, store=store))
+    assert r["success"] is False
+    assert wa.pending_count("memory") == 0

tools/computer_use/tool.py

@@ -32,10 +32,12 @@ For captures / actions with `capture_after=True`:
 
 from __future__ import annotations
 
+import base64
 import json
 import logging
 import os
 import re
+import struct
 import sys
 import threading
 from typing import Any, Dict, List, Optional, Tuple
@@ -429,6 +431,61 @@ _DEFAULT_MAX_ELEMENTS = 100
 # call passing a very large integer would silently disable the safeguard and
 # reintroduce the original unbounded behavior.
 _MAX_ALLOWED_MAX_ELEMENTS = 1000
+_MIN_PROVIDER_IMAGE_DIMENSION = 8
+
+
+def _image_dimensions_from_b64(image_b64: str) -> Optional[Tuple[int, int]]:
+    """Return (width, height) for common inline screenshot formats.
+
+    Some providers reject images below 8x8 before the model sees the tool
+    result. Inspecting the encoded bytes here lets computer_use fall back to
+    its AX/SOM text payload instead of sending an unusable placeholder.
+    """
+    if not image_b64:
+        return None
+    try:
+        raw = base64.b64decode(image_b64, validate=False)
+    except Exception:
+        return None
+
+    # PNG: signature + IHDR width/height.
+    if raw.startswith(b"\x89PNG\r\n\x1a\n") and len(raw) >= 24:
+        try:
+            width, height = struct.unpack(">II", raw[16:24])
+            return int(width), int(height)
+        except Exception:
+            return None
+
+    # JPEG: scan for SOF markers that carry dimensions.
+    if raw.startswith(b"\xff\xd8") and len(raw) > 4:
+        i = 2
+        while i + 9 < len(raw):
+            if raw[i] != 0xFF:
+                i += 1
+                continue
+            marker = raw[i + 1]
+            i += 2
+            while marker == 0xFF and i < len(raw):
+                marker = raw[i]
+                i += 1
+            if marker in {0xD8, 0xD9}:
+                continue
+            if marker == 0xDA:
+                break
+            if i + 2 > len(raw):
+                break
+            segment_len = int.from_bytes(raw[i:i + 2], "big")
+            if segment_len < 2 or i + segment_len > len(raw):
+                break
+            if marker in {
+                0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7,
+                0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF,
+            } and segment_len >= 7:
+                height = int.from_bytes(raw[i + 3:i + 5], "big")
+                width = int.from_bytes(raw[i + 5:i + 7], "big")
+                return int(width), int(height)
+            i += segment_len
+    return None
 
 
 def _coerce_max_elements(value: Any) -> int:
@@ -457,6 +514,16 @@ def _capture_response(cap: CaptureResult, max_elements: int = _DEFAULT_MAX_ELEME
     total_elements = len(cap.elements)
     visible_elements = cap.elements[:max_elements]
     truncated_elements = max(0, total_elements - len(visible_elements))
+    image_dimensions = _image_dimensions_from_b64(cap.png_b64 or "") if cap.png_b64 else None
+    response_width = image_dimensions[0] if image_dimensions else cap.width
+    response_height = image_dimensions[1] if image_dimensions else cap.height
+    image_too_small = bool(
+        image_dimensions
+        and (
+            image_dimensions[0] < _MIN_PROVIDER_IMAGE_DIMENSION
+            or image_dimensions[1] < _MIN_PROVIDER_IMAGE_DIMENSION
+        )
+    )
 
     # Index only what's actually surfaced in the response — otherwise the
     # human-readable summary references element indices the model cannot
@@ -464,7 +531,7 @@ def _capture_response(cap: CaptureResult, max_elements: int = _DEFAULT_MAX_ELEME
     # 40-line index window).
     element_index = _format_elements(visible_elements)
     summary_lines = [
-        f"capture mode={cap.mode} {cap.width}x{cap.height}"
+        f"capture mode={cap.mode} {response_width}x{response_height}"
         + (f" app={cap.app}" if cap.app else "")
         + (f" window={cap.window_title!r}" if cap.window_title else ""),
         f"{total_elements} interactable element(s):",
@@ -476,9 +543,15 @@ def _capture_response(cap: CaptureResult, max_elements: int = _DEFAULT_MAX_ELEME
     # selected) has a valid value to hand to _route_capture_through_aux_vision.
     # The AX path appends the "truncated to N of M" note to summary_lines
     # below and rebuilds; the multimodal path keeps this version untouched.
+    if image_too_small:
+        summary_lines.append(
+            f"  (screenshot omitted: {image_dimensions[0]}x{image_dimensions[1]} "
+            f"is below the {_MIN_PROVIDER_IMAGE_DIMENSION}x{_MIN_PROVIDER_IMAGE_DIMENSION} "
+            "provider minimum)"
+        )
     summary = "\n".join(summary_lines)
 
-    if cap.png_b64 and cap.mode != "ax":
+    if cap.png_b64 and cap.mode != "ax" and not image_too_small:
         # Decide whether to hand the screenshot to the auxiliary.vision
         # pipeline (text-only result) or keep the multimodal envelope (main
         # model handles vision natively). Issue #24015: previously the
@@ -510,7 +583,7 @@ def _capture_response(cap: CaptureResult, max_elements: int = _DEFAULT_MAX_ELEME
                  "image_url": {"url": f"data:{_mime};base64,{cap.png_b64}"}},
             ],
             "text_summary": summary,
-            "meta": {"mode": cap.mode, "width": cap.width, "height": cap.height,
+            "meta": {"mode": cap.mode, "width": response_width, "height": response_height,
                      "elements": total_elements, "png_bytes": cap.png_bytes_len},
         }
     # AX-only (or image-missing fallback): text path actually carries the
@@ -523,8 +596,8 @@ def _capture_response(cap: CaptureResult, max_elements: int = _DEFAULT_MAX_ELEME
     summary = "\n".join(summary_lines)
     payload: Dict[str, Any] = {
         "mode": cap.mode,
-        "width": cap.width,
-        "height": cap.height,
+        "width": response_width,
+        "height": response_height,
         "app": cap.app,
         "window_title": cap.window_title,
         "elements": [_element_to_dict(e) for e in visible_elements],

tools/memory_tool.py

@@ -681,27 +681,29 @@ def memory_tool(
     if target not in {"memory", "user"}:
         return tool_error(f"Invalid target '{target}'. Use 'memory' or 'user'.", success=False)
 
-    # Write gate: off blocks the write; approve stages it (background) or
-    # prompts inline (foreground). on (default) passes straight through.
+    # Validate required params BEFORE the gate so an invalid write is rejected
+    # immediately instead of being staged and only failing at approve time.
+    if action == "add" and not content:
+        return tool_error("Content is required for 'add' action.", success=False)
+    if action == "replace" and (not old_text or not content):
+        missing = "old_text" if not old_text else "content"
+        return tool_error(f"{missing} is required for 'replace' action.", success=False)
+    if action == "remove" and not old_text:
+        return tool_error("old_text is required for 'remove' action.", success=False)
+
+    # Approval gate: when on, stages the write (background/gateway) or prompts
+    # inline (interactive CLI); when off (default) passes straight through.
     gate_result = _apply_write_gate(action, target, content, old_text)
     if gate_result is not None:
         return gate_result
 
     if action == "add":
-        if not content:
-            return tool_error("Content is required for 'add' action.", success=False)
         result = store.add(target, content)
 
     elif action == "replace":
-        if not old_text:
-            return tool_error("old_text is required for 'replace' action.", success=False)
-        if not content:
-            return tool_error("content is required for 'replace' action.", success=False)
         result = store.replace(target, old_text, content)
 
     elif action == "remove":
-        if not old_text:
-            return tool_error("old_text is required for 'remove' action.", success=False)
         result = store.remove(target, old_text)
 
     else:

tools/skill_manager_tool.py

@@ -908,10 +908,10 @@ def skill_manage(
 
     Returns JSON string with results.
     """
-    # Write gate: off blocks the write; approve stages it for review (skills are
-    # too large to review inline, so they always stage regardless of origin).
-    # on (default) passes straight through. The gate is bypassed when this call
-    # is itself replaying an already-approved staged write (_skill_apply_pending).
+    # Approval gate: when on, stages the write for review (skills are too large
+    # to review inline, so they always stage regardless of origin); when off
+    # (default) passes straight through. The gate is bypassed when this call is
+    # itself replaying an already-approved staged write (_skill_apply_pending).
     gate_result = _apply_skill_write_gate(
         action, name, content=content, category=category,
         file_path=file_path, file_content=file_content,

tools/skills_hub.py

@@ -1946,6 +1946,12 @@ class ClawHubSource(SkillSource):
 
     BASE_URL = "https://clawhub.ai/api/v1"
 
+    # Wall-clock budget for a full catalog walk. ClawHub has 50k+ skills and
+    # the walk is sequential (~250 requests, each under per-request
+    # timeout=30 so nothing errors), so an unbounded walk can block for
+    # minutes. Bound it so a slow/large catalog cannot hang the caller.
+    CATALOG_WALK_BUDGET_SECONDS = 12
+
     def source_id(self) -> str:
         return "clawhub"
 
@@ -2113,12 +2119,13 @@ class ClawHubSource(SkillSource):
             if results:
                 return results
         else:
-            # Empty query: route through the paginating catalog walker so the
-            # full ClawHub catalog (20k+ skills) lands in the index. The
-            # single-request listing path below caps at one page (200 items)
-            # regardless of `limit`, which silently truncates the public
-            # skills index. The catalog walker follows `nextCursor`.
-            catalog = self._load_catalog_index()
+            # Empty query: route through the paginating catalog walker. When
+            # the full catalog is already disk-cached this returns it whole and
+            # the caller paginates client-side. On a cold cache, bound the walk
+            # to `limit` so a browse command renders its first page without
+            # walking the entire 50k+ catalog (max_items=0 → unbounded, used
+            # only by the offline index builder via search("", limit=0)).
+            catalog = self._load_catalog_index(max_items=limit if limit > 0 else 0)
             if catalog:
                 return self._dedupe_results(catalog)[:limit] if limit > 0 else self._dedupe_results(catalog)
 
@@ -2243,7 +2250,21 @@ class ClawHubSource(SkillSource):
         _write_index_cache(cache_key, [_skill_meta_to_dict(s) for s in results])
         return results
 
-    def _load_catalog_index(self) -> List[SkillMeta]:
+    def _load_catalog_index(self, max_items: int = 0) -> List[SkillMeta]:
+        """Walk the ClawHub catalog via cursor pagination.
+
+        ``max_items`` bounds the walk: once at least that many distinct skills
+        have been gathered the walk stops early. This is what browse's
+        cold-start fallback wants — it only renders one page, so walking the
+        entire 50k+ catalog just to slice off the first N is pure waste.
+        ``max_items=0`` (the default, used by the offline index builder) means
+        walk to exhaustion.
+
+        Caching: only a *complete* catalog (cursor exhausted or page cap) is
+        written to the shared ``clawhub_catalog_v1`` cache. A walk truncated by
+        ``max_items`` OR the wall-clock budget is partial, so caching it would
+        poison the full-catalog cache with an incomplete slice.
+        """
         cache_key = "clawhub_catalog_v1"
         cached = _read_index_cache(cache_key)
         if cached is not None:
@@ -2258,8 +2279,14 @@ class ClawHubSource(SkillSource):
         # terminates well before this on `nextCursor` going None — the cap is
         # a safety rail against an infinite-cursor loop.
         max_pages = 750
+        deadline = time.monotonic() + self.CATALOG_WALK_BUDGET_SECONDS
+        hit_deadline = False
+        hit_max_items = False
 
         for _ in range(max_pages):
+            if time.monotonic() > deadline:
+                hit_deadline = True
+                break
             params: Dict[str, Any] = {"limit": 200}
             if cursor:
                 params["cursor"] = cursor
@@ -2297,7 +2324,19 @@ class ClawHubSource(SkillSource):
             if not isinstance(cursor, str) or not cursor:
                 break
 
-        _write_index_cache(cache_key, [_skill_meta_to_dict(s) for s in results])
+            # Browse's cold-start fallback only renders one page, so stop as
+            # soon as we have enough to satisfy the caller's bound. The index
+            # builder passes max_items=0 (unbounded) and walks to exhaustion.
+            if max_items > 0 and len(results) >= max_items:
+                hit_max_items = True
+                break
+
+        # Only cache a walk that reached a natural stop (cursor exhausted or
+        # page cap). A walk truncated by the wall-clock budget OR by max_items
+        # is partial, so writing it would poison the shared full-catalog cache
+        # with incomplete data.
+        if not hit_deadline and not hit_max_items:
+            _write_index_cache(cache_key, [_skill_meta_to_dict(s) for s in results])
         return results
 
     def _get_json(self, url: str, timeout: int = 20) -> Optional[Any]:
@@ -3774,13 +3813,20 @@ def parallel_search_sources(
     if not active:
         return all_results, source_counts, timed_out_ids
 
-    with ThreadPoolExecutor(max_workers=min(len(active), 8)) as pool:
-        futures = {}
-        for src in active:
-            lim = per_source_limits.get(src.source_id(), 50)
-            fut = pool.submit(_search_one_source, src, query, lim)
-            futures[fut] = src.source_id()
+    # NOTE: a `with ThreadPoolExecutor(...) as pool` block calls
+    # ``shutdown(wait=True)`` on exit, which blocks until every submitted
+    # worker finishes — so a single slow source (e.g. ClawHub) keeps the
+    # caller blocked for minutes and renders ``overall_timeout`` a no-op.
+    # Manage the executor manually and shut it down with ``wait=False`` so
+    # the timeout is actually honoured.
+    pool = ThreadPoolExecutor(max_workers=min(len(active), 8))
+    futures = {}
+    for src in active:
+        lim = per_source_limits.get(src.source_id(), 50)
+        fut = pool.submit(_search_one_source, src, query, lim)
+        futures[fut] = src.source_id()
 
+    try:
         try:
             for fut in as_completed(futures, timeout=overall_timeout):
                 try:
@@ -3800,6 +3846,10 @@ def parallel_search_sources(
                     "Skills browse timed out waiting for: %s",
                     ", ".join(timed_out_ids),
                 )
+    finally:
+        # wait=False so a slow source cannot block the caller's return;
+        # cancel_futures drops not-yet-started work.
+        pool.shutdown(wait=False, cancel_futures=True)
 
     return all_results, source_counts, timed_out_ids
 

tools/tts_tool.py

@@ -190,6 +190,8 @@ DEFAULT_XAI_BASE_URL = "https://api.x.ai/v1"
 DEFAULT_GEMINI_TTS_MODEL = "gemini-2.5-flash-preview-tts"
 DEFAULT_GEMINI_TTS_VOICE = "Kore"
 DEFAULT_GEMINI_TTS_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
+DEFAULT_GEMINI_AUDIO_TAGS = False
+GEMINI_AUDIO_TAG_REWRITE_TASK = "tts_audio_tags"
 # PCM output specs for Gemini TTS (fixed by the API)
 GEMINI_TTS_SAMPLE_RATE = 24000
 GEMINI_TTS_CHANNELS = 1
@@ -204,8 +206,8 @@ DEFAULT_OUTPUT_DIR = _get_default_output_dir()
 # ---------------------------------------------------------------------------
 # Per-provider input-character limits (from official provider docs).
 # A single global cap was wrong: OpenAI is 4096, xAI is 15k, MiniMax is 10k,
-# ElevenLabs is model-dependent (5k / 10k / 30k / 40k), Gemini caps at ~8k
-# input tokens.  Users can override any of these via
+# ElevenLabs is model-dependent (5k / 10k / 30k / 40k), Gemini has a 32k-token
+# context window.  Users can override any of these via
 # ``tts.<provider>.max_text_length`` in config.yaml.
 # ---------------------------------------------------------------------------
 PROVIDER_MAX_TEXT_LENGTH: Dict[str, int] = {
@@ -214,7 +216,7 @@ PROVIDER_MAX_TEXT_LENGTH: Dict[str, int] = {
     "xai": 15000,         # https://docs.x.ai/developers/model-capabilities/audio/text-to-speech
     "minimax": 10000,     # https://platform.minimax.io/docs/api-reference/speech-t2a-http (sync)
     "mistral": 4000,      # conservative; no published per-request cap
-    "gemini": 5000,       # Gemini TTS caps at ~8k input tokens / ~655s audio
+    "gemini": 32000,      # Gemini TTS has a 32k-token context window; char cap is conservative
     "elevenlabs": 10000,  # fallback when model-aware lookup can't resolve (multilingual_v2)
     "neutts": 2000,       # local model, quality falls off on long text
     "kittentts": 2000,    # local 25MB model
@@ -233,6 +235,23 @@ ELEVENLABS_MODEL_MAX_TEXT_LENGTH: Dict[str, int] = {
     "eleven_flash_v2_5": 40000,
 }
 
+
+def _config_bool(value: Any, default: bool = False) -> bool:
+    """Coerce common YAML/env bool spellings without treating random strings as true."""
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return default
+    if isinstance(value, (int, float)):
+        return bool(value)
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"1", "true", "yes", "on", "enabled"}:
+            return True
+        if normalized in {"0", "false", "no", "off", "disabled"}:
+            return False
+    return default
+
 # Final fallback when provider isn't recognised at all.
 FALLBACK_MAX_TEXT_LENGTH = 4000
 
@@ -1069,20 +1088,7 @@ _XAI_FIRST_SENTENCE_RE = re.compile(r"^(.{12,120}?[.!?…])\s+(?=\S)", flags=re.
 
 
 def _xai_bool_config(value: Any, default: bool = False) -> bool:
-    """Coerce common YAML/env bool spellings without treating random strings as true."""
-    if isinstance(value, bool):
-        return value
-    if value is None:
-        return default
-    if isinstance(value, (int, float)):
-        return bool(value)
-    if isinstance(value, str):
-        normalized = value.strip().lower()
-        if normalized in {"1", "true", "yes", "on", "enabled"}:
-            return True
-        if normalized in {"0", "false", "no", "off", "disabled"}:
-            return False
-    return default
+    return _config_bool(value, default=default)
 
 
 def _apply_xai_auto_speech_tags(text: str) -> str:
@@ -1394,6 +1400,160 @@ def _wrap_pcm_as_wav(
     return riff_header + fmt_chunk + data_chunk_header + pcm_bytes
 
 
+def _resolve_gemini_persona_prompt_path(gemini_config: Dict[str, Any]) -> Optional[Path]:
+    """Return the configured persona prompt file path, if any."""
+    raw = gemini_config.get("persona_prompt_file")
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+
+    expanded = os.path.expandvars(raw.strip())
+    path = Path(expanded).expanduser()
+    if not path.is_absolute():
+        try:
+            from hermes_constants import get_hermes_home
+            path = get_hermes_home() / path
+        except Exception:
+            path = Path.cwd() / path
+    return path
+
+
+def _read_gemini_persona_prompt(gemini_config: Dict[str, Any]) -> str:
+    """Read the Gemini persona prompt file, failing soft on config mistakes."""
+    path = _resolve_gemini_persona_prompt_path(gemini_config)
+    if path is None:
+        return ""
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError) as exc:
+        logger.warning(
+            "Gemini TTS persona prompt file unavailable at %s: %s",
+            path,
+            exc,
+        )
+        return ""
+
+
+def _gemini_model_supports_audio_tags(model: str) -> bool:
+    """Return True for Gemini TTS models known to support expressive audio tags."""
+    normalized = (model or "").strip().lower().rsplit("/", 1)[-1]
+    return "gemini-3.1" in normalized and "tts" in normalized
+
+
+def _gemini_audio_tags_enabled(gemini_config: Dict[str, Any], model: str) -> bool:
+    raw = gemini_config.get("audio_tags")
+    if isinstance(raw, dict):
+        raw = raw.get("enabled")
+    enabled = _config_bool(raw, default=DEFAULT_GEMINI_AUDIO_TAGS)
+    if not enabled:
+        return False
+    if not _gemini_model_supports_audio_tags(model):
+        logger.warning(
+            "Gemini TTS audio_tags enabled, but model %s is not known to support "
+            "Gemini audio tags; skipping hidden tag rewrite",
+            model,
+        )
+        return False
+    return True
+
+
+def _clean_gemini_audio_tag_rewrite(content: str) -> str:
+    clean = (content or "").strip()
+    fence = re.fullmatch(r"```(?:[A-Za-z0-9_-]+)?\s*(.*?)\s*```", clean, flags=re.DOTALL)
+    if fence:
+        clean = fence.group(1).strip()
+    return clean
+
+
+def _extract_auxiliary_message_content(response: Any) -> str:
+    try:
+        choice = response.choices[0]
+        message = getattr(choice, "message", None)
+        if isinstance(message, dict):
+            return str(message.get("content") or "")
+        return str(getattr(message, "content", "") or "")
+    except Exception:
+        return ""
+
+
+def _rewrite_gemini_tts_audio_tags(text: str, persona_prompt: str = "") -> str:
+    """Use the configured auxiliary model to insert Gemini audio tags."""
+    transcript = text.strip()
+    if not transcript:
+        return text
+
+    system_prompt = (
+        "You rewrite transcripts for Gemini 3.1 Flash TTS by inserting expressive "
+        "audio tags.\n\n"
+        "Audio tags are inline square-bracket modifiers such as [whispers], "
+        "[excitedly], [very slow], [sarcastically], [laughs], [sighs], or [gasp]. "
+        "There is no fixed allowlist. Use creative freeform tags generously but "
+        "naturally to control tone, pace, emotional vibe, emphasis, section-level "
+        "delivery, and non-verbal sounds. Use English audio tags even when the "
+        "spoken transcript is not English.\n\n"
+        "Rules:\n"
+        "- Preserve the spoken words, order, and meaning.\n"
+        "- Do not add new spoken sentences or remove existing spoken words.\n"
+        "- Use square brackets for every audio tag.\n"
+        "- Do not use SSML or XML tags.\n"
+        "- Do not explain or comment.\n"
+        "- Return only the tagged TTS script."
+    )
+    context = persona_prompt.strip() or "(none)"
+    user_prompt = (
+        "PERSONA AND DIRECTOR CONTEXT:\n"
+        f"{context}\n\n"
+        "TRANSCRIPT TO TAG:\n"
+        f"{transcript}"
+    )
+    try:
+        from agent.auxiliary_client import call_llm
+
+        response = call_llm(
+            task=GEMINI_AUDIO_TAG_REWRITE_TASK,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+            temperature=0.7,
+        )
+        tagged = _clean_gemini_audio_tag_rewrite(_extract_auxiliary_message_content(response))
+        return tagged or text
+    except Exception as exc:
+        logger.warning("Gemini TTS audio tag rewrite failed; using untagged text: %s", exc)
+        return text
+
+
+def _compose_gemini_tts_prompt(
+    text: str,
+    gemini_config: Dict[str, Any],
+    persona_prompt: Optional[str] = None,
+) -> str:
+    """Build the Gemini prompt from persona direction plus the live transcript."""
+    transcript = text.strip()
+    if persona_prompt is None:
+        persona_prompt = _read_gemini_persona_prompt(gemini_config)
+    if not persona_prompt:
+        return transcript
+
+    preamble = (
+        "Synthesize speech from the TRANSCRIPT only. Treat AUDIO PROFILE, "
+        "SCENE, DIRECTOR'S NOTES, and SAMPLE CONTEXT as performance direction; "
+        "do not speak those sections aloud."
+    )
+
+    placeholder_patterns = (
+        re.compile(r"\{\{\s*transcript\s*\}\}", flags=re.IGNORECASE),
+        re.compile(r"\{\s*transcript\s*\}", flags=re.IGNORECASE),
+    )
+    prompt = persona_prompt
+    for pattern in placeholder_patterns:
+        if pattern.search(prompt):
+            prompt = pattern.sub(transcript, prompt)
+            return f"{preamble}\n\n{prompt}".strip()
+
+    return f"{preamble}\n\n{persona_prompt}\n\n#### TRANSCRIPT\n{transcript}".strip()
+
+
 def _generate_gemini_tts(text: str, output_path: str, tts_config: Dict[str, Any]) -> str:
     """Generate audio using Google Gemini TTS.
 
@@ -1419,7 +1579,8 @@ def _generate_gemini_tts(text: str, output_path: str, tts_config: Dict[str, Any]
             "GEMINI_API_KEY not set. Get one at https://aistudio.google.com/app/apikey"
         )
 
-    gemini_config = tts_config.get("gemini", {})
+    raw_gemini_config = tts_config.get("gemini", {})
+    gemini_config = raw_gemini_config if isinstance(raw_gemini_config, dict) else {}
     model = str(gemini_config.get("model", DEFAULT_GEMINI_TTS_MODEL)).strip() or DEFAULT_GEMINI_TTS_MODEL
     voice = str(gemini_config.get("voice", DEFAULT_GEMINI_TTS_VOICE)).strip() or DEFAULT_GEMINI_TTS_VOICE
     base_url = str(
@@ -1427,9 +1588,25 @@ def _generate_gemini_tts(text: str, output_path: str, tts_config: Dict[str, Any]
         or get_env_value("GEMINI_BASE_URL")
         or DEFAULT_GEMINI_TTS_BASE_URL
     ).strip().rstrip("/")
+    persona_prompt = _read_gemini_persona_prompt(gemini_config)
+    tts_script = text
+    if _gemini_audio_tags_enabled(gemini_config, model):
+        tts_script = _rewrite_gemini_tts_audio_tags(text, persona_prompt=persona_prompt)
+    prompt_text = _compose_gemini_tts_prompt(
+        tts_script,
+        gemini_config,
+        persona_prompt=persona_prompt,
+    )
+    max_len = _resolve_max_text_length("gemini", tts_config)
+    if len(prompt_text) > max_len:
+        logger.warning(
+            "Gemini TTS composed prompt too long (%d chars), truncating to %d",
+            len(prompt_text), max_len,
+        )
+        prompt_text = prompt_text[:max_len]
 
     payload: Dict[str, Any] = {
-        "contents": [{"parts": [{"text": text}]}],
+        "contents": [{"parts": [{"text": prompt_text}]}],
         "generationConfig": {
             "responseModalities": ["AUDIO"],
             "speechConfig": {

tools/web_tools.py

@@ -153,15 +153,18 @@ def _get_backend() -> str:
         return configured
 
     # Fallback for manual / legacy config — pick the highest-priority
-    # available backend. Firecrawl also counts as available when the managed
-    # tool gateway is configured for Nous subscribers.
-    # Free-tier backends (searxng / brave-free / ddgs) trail the paid ones so
-    # existing paid setups are unaffected.
+    # available backend. Explicit user credentials (TAVILY_API_KEY etc.)
+    # beat the managed-tool-gateway probe so a deliberate setup is not
+    # pre-empted by a Nous OAuth token whose subscription tier may not
+    # actually grant web-search access (the gateway then fails at runtime
+    # with "no subscription" and the tool returns an error to the agent
+    # without falling back). Free-tier backends trail the paid ones.
     backend_candidates = (
-        ("firecrawl", _has_env("FIRECRAWL_API_KEY") or _has_env("FIRECRAWL_API_URL") or _is_tool_gateway_ready()),
-        ("parallel", _has_env("PARALLEL_API_KEY")),
         ("tavily", _has_env("TAVILY_API_KEY")),
         ("exa", _has_env("EXA_API_KEY")),
+        ("parallel", _has_env("PARALLEL_API_KEY")),
+        ("firecrawl", _has_env("FIRECRAWL_API_KEY") or _has_env("FIRECRAWL_API_URL")),
+        ("firecrawl", _is_tool_gateway_ready()),
         ("searxng", _has_env("SEARXNG_URL")),
         ("brave-free", _has_env("BRAVE_SEARCH_API_KEY")),
         ("ddgs", _ddgs_package_importable()),

tools/write_approval.py

@@ -15,24 +15,25 @@ Both stores are written from two origins:
     turn and autonomously decides what to save (the source of the
     "wrong assumptions" users complained about)
 
-This module lets the user gate those writes per-subsystem with a tri-state
-``write_mode``:
+This module lets the user gate those writes per-subsystem with a boolean
+``write_approval``:
 
-  * ``on``      — write freely (current behaviour, default)
-  * ``off``     — never write; the tool returns a clean "disabled" result
-  * ``approve`` — do not commit the write; **stage** it to a pending store and
-    surface it for the user to approve or reject out-of-band
+  * ``false`` (default) — write freely (the pre-gate behaviour)
+  * ``true``            — require approval: do not commit the write; either
+    prompt inline (memory, interactive CLI only) or **stage** it to a pending
+    store and surface it for the user to approve or reject out-of-band
 
 The size asymmetry between memory and skills is real and unavoidable: a memory
 entry can be reviewed inline in a chat bubble; a 100 KB SKILL.md cannot. So
-``approve`` mode stages BOTH to disk, but review affordances differ by subsystem
+the gate stages BOTH to disk, but review affordances differ by subsystem
 (see ``hermes_cli`` slash handlers): memory shows full content, skills show
 metadata + a one-line gist + a ``diff`` escape hatch (CLI/dashboard/file).
 
-Staging is mandatory for background-origin writes under ``approve`` (a daemon
-thread cannot block on an interactive prompt). Foreground memory writes may
-additionally block inline via the dangerous-command approval gate; foreground
-skill writes always stage (too big to eyeball mid-loop).
+Staging is mandatory for background-origin writes (a daemon thread cannot
+block on an interactive prompt) and for gateway sessions (no inline prompt
+channel — review happens via ``/memory pending``). Foreground CLI memory
+writes prompt inline via the dangerous-command approval callback; skill
+writes always stage (too big to eyeball mid-loop).
 
 Pending records live under ``<HERMES_HOME>/pending/{memory,skills}/<id>.json``
 so they survive process restarts and can be reviewed from CLI, gateway, or the
@@ -58,48 +59,48 @@ MEMORY = "memory"
 SKILLS = "skills"
 _SUBSYSTEMS = (MEMORY, SKILLS)
 
-# Tri-state write modes
-MODE_ON = "on"
-MODE_OFF = "off"
-MODE_APPROVE = "approve"
-_VALID_MODES = (MODE_ON, MODE_OFF, MODE_APPROVE)
+# Config key (per subsystem). A single boolean: the approval gate is OFF by
+# default (writes flow freely, the pre-gate behaviour), and ON means stage /
+# prompt every write for the user's approval. There is intentionally no third
+# "block all writes" state — to disable a subsystem entirely use its own
+# enable flag (e.g. ``memory.memory_enabled: false``).
+CONFIG_KEY = "write_approval"
 
 
 # ---------------------------------------------------------------------------
 # Config resolution
 # ---------------------------------------------------------------------------
 
-def get_write_mode(subsystem: str) -> str:
-    """Return the configured write_mode for ``subsystem`` (memory|skills).
+def write_approval_enabled(subsystem: str) -> bool:
+    """Return whether the approval gate is enabled for ``subsystem``.
 
-    Reads ``<subsystem>.write_mode`` from config.yaml. Falls back to ``on``
-    (current behaviour) for any unset / invalid value so existing installs are
-    unaffected until the user opts in.
+    Reads ``<subsystem>.write_approval`` from config.yaml. Defaults to
+    ``False`` (gate off — writes flow freely) for any unset / invalid value so
+    existing installs keep their current behaviour until the user opts in.
     """
     if subsystem not in _SUBSYSTEMS:
-        return MODE_ON
+        return False
     try:
         from hermes_cli.config import load_config, cfg_get
         cfg = load_config()
-        raw = cfg_get(cfg, subsystem, "write_mode", default=MODE_ON)
+        raw = cfg_get(cfg, subsystem, CONFIG_KEY, default=False)
     except Exception:
-        return MODE_ON
-    return _normalize_mode(raw)
+        return False
+    return _normalize_enabled(raw)
 
 
-def _normalize_mode(value: Any) -> str:
-    """Coerce a config value to a valid mode string.
+def _normalize_enabled(value: Any) -> bool:
+    """Coerce a config value to a bool. Default (unknown) is False (gate off).
 
-    YAML 1.1 parses bare ``off`` / ``on`` as booleans, so handle bools the way
-    the approval-mode normalizer does.
+    Accepts real bools and the usual truthy/falsey strings. YAML 1.1 parses
+    bare ``on``/``off``/``yes``/``no`` as bools already, so the string branch
+    is mostly for hand-edited configs.
     """
     if isinstance(value, bool):
-        return MODE_OFF if value is False else MODE_ON
+        return value
     if isinstance(value, str):
-        v = value.strip().lower()
-        if v in _VALID_MODES:
-            return v
-    return MODE_ON
+        return value.strip().lower() in {"on", "true", "yes", "1", "approve", "enabled"}
+    return False
 
 
 # ---------------------------------------------------------------------------
@@ -230,14 +231,14 @@ class GateDecision:
     """Result of evaluating the write gate for a single write attempt.
 
     Exactly one of the boolean flags is True:
-      * ``allow``  — proceed with the real write (mode ``on``, or an inline
+      * ``allow``  — proceed with the real write (gate off, or an inline
         approval was granted).
-      * ``blocked`` — refuse the write (mode ``off``, or an inline approval was
-        denied). ``message`` explains why; surface it to the agent.
+      * ``blocked`` — refuse the write (the user denied an inline approval
+        prompt). ``message`` explains why; surface it to the agent.
       * ``stage``  — do not write; the caller should stage the payload via
-        ``stage_write`` (mode ``approve`` for a background write, or a
-        foreground write with no interactive prompt available). ``message`` is
-        the user-facing "staged for approval" note.
+        ``stage_write`` (gate on, and no inline prompt is available — gateway,
+        background review, script, or any skill write). ``message`` is the
+        user-facing "staged for approval" note.
     """
 
     __slots__ = ("allow", "blocked", "stage", "message")
@@ -260,29 +261,19 @@ def evaluate_gate(subsystem: str, *, inline_summary: str = "",
         inline_detail: full content shown in the inline prompt (memory entries
             are small; skills never take the inline path).
 
-    Mode matrix:
-        on       → allow
-        off      → blocked
-        approve  → memory + foreground   → inline approve/deny prompt
-                   memory + background    → stage
-                   skills (any origin)    → stage (too big to review inline)
-    """
-    mode = get_write_mode(subsystem)
+    Decision matrix:
+        gate off (default)                    → allow (writes flow freely)
+        gate on, memory + interactive CLI     → inline approve/deny prompt
+        gate on, memory + gateway/script/bg   → stage
+        gate on, skills (any origin)          → stage (too big to review inline)
 
-    if mode == MODE_ON:
+    Note: there is no config-driven "blocked" outcome — the gate only ever
+    delays a write for approval, never silently refuses it. ``blocked`` is
+    still produced when the user *actively denies* an inline prompt.
+    """
+    if not write_approval_enabled(subsystem):
         return GateDecision(allow=True)
 
-    if mode == MODE_OFF:
-        return GateDecision(
-            blocked=True,
-            message=(
-                f"{subsystem.capitalize()} writes are disabled "
-                f"({subsystem}.write_mode = off). The change was not saved. "
-                f"Set {subsystem}.write_mode to 'on' or 'approve' to allow writes."
-            ),
-        )
-
-    # mode == approve
     background = is_background()
 
     # Skills always stage — a SKILL.md is too large to review inline, and a
@@ -292,15 +283,15 @@ def evaluate_gate(subsystem: str, *, inline_summary: str = "",
         return GateDecision(
             stage=True,
             message=(
-                f"Staged for approval ({subsystem}.write_mode = approve). "
+                f"Staged for approval ({subsystem}.write_approval is on). "
                 f"Not yet saved — review with {where}."
             ),
         )
 
-    # Memory + foreground: if an interactive approval channel exists (CLI
-    # prompt_toolkit callback, or a gateway approve/deny round-trip), prompt
-    # inline — entries are small enough to show in full. Otherwise (script,
-    # batch, no listener) stage instead of forcing a blind deny.
+    # Memory + foreground: if an interactive approval channel exists (a CLI
+    # approval callback registered on this thread), prompt inline — entries
+    # are small enough to show in full. Otherwise (gateway, script, batch,
+    # no listener) stage instead of forcing a blind deny.
     if _interactive_approval_available():
         granted = _prompt_inline_memory_approval(inline_summary, inline_detail)
         if granted is True:
@@ -315,7 +306,7 @@ def evaluate_gate(subsystem: str, *, inline_summary: str = "",
     return GateDecision(
         stage=True,
         message=(
-            "Staged for approval (memory.write_mode = approve). "
+            "Staged for approval (memory.write_approval is on). "
             "Not yet saved — review with /memory pending."
         ),
     )
@@ -324,19 +315,21 @@ def evaluate_gate(subsystem: str, *, inline_summary: str = "",
 def _interactive_approval_available() -> bool:
     """True when a foreground memory write can be approved inline.
 
-    Either a per-thread approval callback is registered (interactive CLI), or
-    the call is inside a gateway/API session that supports the /approve //deny
-    round-trip. Scripts, cron, and background threads have neither → stage.
+    Inline prompting requires a per-thread approval callback registered by the
+    interactive CLI (``tools.terminal_tool.set_approval_callback``). Every
+    other surface stages instead:
+
+    * **Gateway/API sessions** — the dangerous-command ``/approve`` round-trip
+      lives in the pending-approval queue (``submit_pending`` +
+      ``_await_gateway_decision``), which ``prompt_dangerous_approval`` never
+      reaches; trying to prompt from a gateway session would hit the
+      ``input()`` fallback and silently deny. Staging gives the user a real
+      review affordance (``/memory pending``) instead.
+    * Scripts, cron, and background threads — no user present.
     """
     try:
         from tools.terminal_tool import _get_approval_callback
-        if _get_approval_callback() is not None:
-            return True
-    except Exception:
-        pass
-    try:
-        from tools.approval import _is_gateway_approval_context
-        return bool(_is_gateway_approval_context())
+        return _get_approval_callback() is not None
     except Exception:
         return False
 
@@ -345,28 +338,37 @@ def _prompt_inline_memory_approval(summary: str, detail: str) -> Optional[bool]:
     """Prompt the user inline to approve a memory write.
 
     Returns True (approved), False (denied), or None (no interactive prompt
-    available on this thread → caller should stage instead).
+    available / prompt failed → caller should stage instead).
 
-    Reuses the dangerous-command approval machinery so the CLI prompt_toolkit
-    callback and the gateway ``/approve`` ``/deny`` round-trip both work without
-    duplicating that plumbing.
+    Reuses the per-thread CLI approval callback registered for dangerous
+    commands (``tools.terminal_tool.set_approval_callback``). The callback is
+    invoked directly — NOT via ``prompt_dangerous_approval`` — because that
+    wrapper falls back to ``input()`` (deadlock-prone under prompt_toolkit,
+    see #15216) and converts callback errors into a silent deny; here a
+    failed prompt must stage the write instead.
     """
     try:
-        from tools.approval import prompt_dangerous_approval
+        from tools.terminal_tool import _get_approval_callback
     except Exception:
         return None
 
+    callback = _get_approval_callback()
+    if callback is None:
+        # No interactive channel on this thread — stage rather than risk the
+        # input() fallback (deadlock under prompt_toolkit, EOF-deny in tests).
+        return None
+
     header = summary.strip() or "Save to memory?"
     body = detail.strip()
     description = f"Save to memory: {header}"
     command = body if body else header
+    # Invoke the callback directly instead of via prompt_dangerous_approval:
+    # that wrapper swallows callback exceptions into "deny", which would
+    # silently refuse the write. Direct invocation lets a crashed prompt fall
+    # back to staging (the gate only ever delays a write, never drops it).
     try:
-        choice = prompt_dangerous_approval(
-            command,
-            description,
-            allow_permanent=False,
-        )
-    except Exception as e:  # pragma: no cover
+        choice = callback(command, description, allow_permanent=False)
+    except Exception as e:
         logger.error("Inline memory approval prompt failed: %s", e)
         return None
 

tui_gateway/server.py

@@ -1696,7 +1696,13 @@ def _persist_model_switch(result) -> None:
     save_config(cfg)
 
 
-def _apply_model_switch(sid: str, session: dict, raw_input: str) -> dict:
+def _apply_model_switch(
+    sid: str,
+    session: dict,
+    raw_input: str,
+    *,
+    confirm_expensive_model: bool = False,
+) -> dict:
     from hermes_cli.model_switch import parse_model_flags, switch_model
     from hermes_cli.runtime_provider import resolve_runtime_provider
 
@@ -1753,6 +1759,27 @@ def _apply_model_switch(sid: str, session: dict, raw_input: str) -> dict:
     if not result.success:
         raise ValueError(result.error_message or "model switch failed")
 
+    if not confirm_expensive_model:
+        try:
+            from hermes_cli.model_cost_guard import expensive_model_warning
+
+            warning = expensive_model_warning(
+                result.new_model,
+                provider=result.target_provider,
+                base_url=result.base_url or current_base_url,
+                api_key=result.api_key or current_api_key,
+                model_info=result.model_info,
+            )
+        except Exception:
+            warning = None
+        if warning is not None:
+            return {
+                "value": result.new_model,
+                "warning": warning.message,
+                "confirm_required": True,
+                "confirm_message": warning.message,
+            }
+
     if agent:
         agent.switch_model(
             new_model=result.new_model,
@@ -1787,7 +1814,11 @@ def _apply_model_switch(sid: str, session: dict, raw_input: str) -> dict:
         }
     if persist_global:
         _persist_model_switch(result)
-    return {"value": result.new_model, "warning": result.warning_message or ""}
+    return {
+        "value": result.new_model,
+        "warning": result.warning_message or "",
+        "confirm_required": False,
+    }
 
 
 def _compress_session_history(
@@ -6196,13 +6227,31 @@ def _(rid, params: dict) -> dict:
                     if session.get("agent") is None:
                         return _err(rid, 5032, "agent initialization failed")
                 result = _apply_model_switch(
-                    params.get("session_id", ""), session, value
+                    params.get("session_id", ""),
+                    session,
+                    value,
+                    confirm_expensive_model=bool(
+                        params.get("confirm_expensive_model", False)
+                    ),
                 )
             else:
-                result = _apply_model_switch("", {"agent": None}, value)
+                result = _apply_model_switch(
+                    "",
+                    {"agent": None},
+                    value,
+                    confirm_expensive_model=bool(
+                        params.get("confirm_expensive_model", False)
+                    ),
+                )
             return _ok(
                 rid,
-                {"key": key, "value": result["value"], "warning": result["warning"]},
+                {
+                    "key": key,
+                    "value": result["value"],
+                    "warning": result["warning"],
+                    "confirm_required": result.get("confirm_required", False),
+                    "confirm_message": result.get("confirm_message", ""),
+                },
             )
         except Exception as e:
             return _err(rid, 5001, str(e))

ui-tui/src/__tests__/createSlashHandler.test.ts

@@ -108,6 +108,7 @@ describe('createSlashHandler', () => {
 
     expect(createSlashHandler(ctx)('/model x-model')).toBe(true)
     expect(ctx.gateway.rpc).toHaveBeenCalledWith('config.set', {
+      confirm_expensive_model: false,
       key: 'model',
       session_id: 'sid-abc',
       value: 'x-model'
@@ -128,6 +129,7 @@ describe('createSlashHandler', () => {
       createSlashHandler(ctx)(`/model anthropic/claude-sonnet-4.6 --provider openrouter ${TUI_SESSION_MODEL_FLAG}`)
     ).toBe(true)
     expect(ctx.gateway.rpc).toHaveBeenCalledWith('config.set', {
+      confirm_expensive_model: false,
       key: 'model',
       session_id: 'sid-abc',
       value: 'anthropic/claude-sonnet-4.6 --provider openrouter'
@@ -140,6 +142,7 @@ describe('createSlashHandler', () => {
 
     createSlashHandler(ctx)('/model x-model --global')
     expect(ctx.gateway.rpc).toHaveBeenCalledWith('config.set', {
+      confirm_expensive_model: false,
       key: 'model',
       session_id: 'sid-abc',
       value: 'x-model --global'

ui-tui/src/app/slash/commands/session.ts

@@ -72,10 +72,25 @@ export const sessionCommands: SlashCommand[] = [
         return patchOverlayState({ modelPicker: true })
       }
 
-      ctx.gateway
-        .rpc<ConfigSetResponse>('config.set', { key: 'model', session_id: ctx.sid, value: modelValueForConfigSet(arg) })
+      const switchModel = (confirmExpensiveModel = false) => ctx.gateway
+        .rpc<ConfigSetResponse>('config.set', { confirm_expensive_model: confirmExpensiveModel, key: 'model', session_id: ctx.sid, value: modelValueForConfigSet(arg) })
         .then(
           ctx.guarded<ConfigSetResponse>(r => {
+            if (r.confirm_required) {
+              patchOverlayState({
+                confirm: {
+                  cancelLabel: 'Cancel',
+                  confirmLabel: 'Switch anyway',
+                  danger: true,
+                  detail: r.confirm_message || r.warning || 'This model has unusually high known pricing.',
+                  onConfirm: () => switchModel(true),
+                  title: 'Expensive model selection'
+                }
+              })
+
+              return
+            }
+
             if (!r.value) {
               return ctx.transcript.sys('error: invalid response: model switch')
             }
@@ -89,6 +104,8 @@ export const sessionCommands: SlashCommand[] = [
             }))
           })
         )
+
+      switchModel()
     }
   },