fix(windows): bootstrap utf-8 mode at entrypoints

Force UTF-8 defaults on legacy Windows by re-execing Hermes entrypoints with -X utf8, preventing locale codec crashes from implicit text encoding in file and stdio paths.
fix(windows): harden native CLI and TUI bootstrap
2026-05-07 22:43:17 -04:00 · 2026-05-07 22:04:42 -04:00 · 2026-05-07 17:54:47 -07:00 · 2026-05-07 17:47:22 -07:00 · 2026-05-07 17:47:22 -07:00 · 2026-05-07 17:33:09 -07:00
273 changed files with 32465 additions and 2699 deletions
@@ -423,3 +423,24 @@ IMAGE_TOOLS_DEBUG=false
 # TEAMS_HOME_CHANNEL=                  # Default channel/chat ID for cron delivery
 # TEAMS_HOME_CHANNEL_NAME=             # Display name for the home channel
 # TEAMS_PORT=3978                      # Webhook listen port (Bot Framework default)
+
+# =============================================================================
+# GOOGLE CHAT INTEGRATION
+# =============================================================================
+# Connects via Cloud Pub/Sub pull subscription (no public URL required).
+# Setup walkthrough: website/docs/user-guide/messaging/google_chat.md.
+# 1. Create a GCP project, enable the Google Chat API and Cloud Pub/Sub.
+# 2. Create a Service Account with roles/pubsub.subscriber on the
+#    subscription (NOT project-wide); download the JSON key.
+# 3. Configure your Chat app at console.cloud.google.com/apis/credentials
+#    → Google Chat API → Configuration → Cloud Pub/Sub topic.
+# 4. (Optional, for native attachment delivery) Each user runs
+#    `/setup-files` once in their own DM after Pub/Sub is wired up.
+#
+# GOOGLE_CHAT_PROJECT_ID=                       # GCP project hosting the topic (or set GOOGLE_CLOUD_PROJECT)
+# GOOGLE_CHAT_SUBSCRIPTION_NAME=                # Full path: projects/<id>/subscriptions/<name>
+# GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=             # Path to SA JSON (or set GOOGLE_APPLICATION_CREDENTIALS)
+# GOOGLE_CHAT_ALLOWED_USERS=                    # Comma-separated emails allowed to talk to the bot
+# GOOGLE_CHAT_ALLOW_ALL_USERS=false             # Set true to skip the allowlist
+# GOOGLE_CHAT_HOME_CHANNEL=                     # Default space (spaces/XXXX) for cron delivery
+# GOOGLE_CHAT_HOME_CHANNEL_NAME=                # Display name for the home channel
@@ -65,19 +65,31 @@ jobs:

      - name: Test image starts
        run: |
+          mkdir -p /tmp/hermes-test
+          sudo chown -R 10000:10000 /tmp/hermes-test
          # The image runs as the hermes user (UID 10000).  GitHub Actions
          # creates /tmp/hermes-test root-owned by default, which hermes
          # can't write to — chown it to match the in-container UID before
          # bind-mounting.  Real users doing `docker run -v ~/.hermes:...`
          # with their own UID hit the same issue and have their own
          # remediations (HERMES_UID env var, or chown locally).
-          mkdir -p /tmp/hermes-test
-          sudo chown -R 10000:10000 /tmp/hermes-test
          docker run --rm \
            -v /tmp/hermes-test:/opt/data \
            --entrypoint /opt/hermes/docker/entrypoint.sh \
            nousresearch/hermes-agent:test --help

+      - name: Test dashboard subcommand
+        run: |
+          mkdir -p /tmp/hermes-test
+          sudo chown -R 10000:10000 /tmp/hermes-test
+          # Verify the dashboard subcommand is included in the Docker image.
+          # This prevents regressions like #9153 where the dashboard command
+          # was present in source but missing from the published image.
+          docker run --rm \
+            -v /tmp/hermes-test:/opt/data \
+            --entrypoint /opt/hermes/docker/entrypoint.sh \
+            nousresearch/hermes-agent:test dashboard --help
+
      - name: Log in to Docker Hub
        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9  # v3
@@ -106,6 +106,11 @@ hermes chat -q "Hello"
 ### Run tests

 ```bash
+# Preferred — matches CI (hermetic env, 4 xdist workers); see AGENTS.md
+scripts/run_tests.sh
+
+# Alternative (activate the venv first). The wrapper is still recommended
+# for parity with GitHub Actions before you open a PR:
 pytest tests/ -v
 ```

@@ -286,16 +291,18 @@ registry.register(
 )
 ```

-Then add the import to `model_tools.py` in the `_modules` list:
+**Wire into a toolset (required):** Built-in tools are auto-discovered: any
+`tools/*.py` file that contains a top-level `registry.register(...)` call is
+imported by `discover_builtin_tools()` in `tools/registry.py` when `model_tools`
+loads. There is **no** manual import list in `model_tools.py` to maintain.

-```python
-_modules = [
-    # ... existing modules ...
-    "tools.my_tool",
-]
-```
+You must still add the tool name to the appropriate list in `toolsets.py`
+(for example `_HERMES_CORE_TOOLS` or a dedicated toolset); otherwise the tool
+registers but is never exposed to the agent. If you introduce a new toolset,
+add it in `toolsets.py` and wire it into the relevant platform presets.

-If it's a new toolset, add it to `toolsets.py` and to the relevant platform presets.
+See `AGENTS.md` (section **Adding New Tools**) for profile-aware paths and
+plugin vs core guidance.

 ---

@@ -595,7 +602,7 @@ refactor/description   # Code restructuring

 ### Before submitting

-1. **Run tests**: `pytest tests/ -v`
+1. **Run tests**: `scripts/run_tests.sh` (recommended; same as CI) or `pytest tests/ -v` with the project venv activated
 2. **Test manually**: Run `hermes` and exercise the code path you changed
 3. **Check cross-platform impact**: If you touch file I/O, process management, or terminal handling, consider macOS, Linux, and WSL2
 4. **Keep PRs focused**: One logical change per PR. Don't mix a bug fix with a refactor with a new feature.
@@ -66,8 +66,14 @@ RUN cd web && 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.
+# node_modules trees additionally need to be writable by the hermes user
+# so the runtime `npm install` triggered by _tui_need_npm_install() in
+# hermes_cli/main.py succeeds (see #18800). /opt/hermes/web is build-time
+# only (HERMES_WEB_DIST points at hermes_cli/web_dist) and is intentionally
+# not chowned here.
 USER root
-RUN chmod -R a+rX /opt/hermes
+RUN chmod -R a+rX /opt/hermes && \
+    chown -R hermes:hermes /opt/hermes/ui-tui /opt/hermes/node_modules
 # Start as root so the entrypoint can usermod/groupmod + gosu.
 # If HERMES_UID is unset, the entrypoint drops to the default hermes user (10000).

@@ -155,13 +155,13 @@ Manual path (equivalent to the above):

 ```bash
 curl -LsSf https://astral.sh/uv/install.sh | sh
-uv venv venv --python 3.11
-source venv/bin/activate
+uv venv .venv --python 3.11
+source .venv/bin/activate
 uv pip install -e ".[all,dev]"
 scripts/run_tests.sh
 ```

-> **RL Training (optional):** The RL/Atropos integration (`environments/`) ships via the `atroposlib` and `tinker` dependencies pulled in by `.[all,dev]` — no submodule setup required.
+> **RL Training (optional):** The RL/Atropos integration (`environments/`) — see [`CONTRIBUTING.md`](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#development-setup) for the full setup.

 ---

@@ -0,0 +1,641 @@
+# Hermes Agent v0.13.0 (v2026.5.7)
+
+**Release Date:** May 7, 2026
+**Since v0.12.0:** 864 commits · 588 merged PRs · 829 files changed · 128,366 insertions · 282 issues closed (13 P0, 36 P1) · 295 community contributors (including co-authors)
+
+> The Tenacity Release — Hermes Agent now finishes what it starts. Kanban ships as a durable multi-agent board (heartbeat, reclaim, zombie detection, auto-block on incomplete exit, per-task retries, hallucination recovery). `/goal` keeps the agent locked on a target across turns (Ralph loop). Checkpoints v2 rewrites state persistence with real pruning. Gateway auto-resumes interrupted sessions after restart. Cron grows a `no_agent` watchdog mode. A security wave closes 8 P0s — redaction is now ON by default, Discord role-allowlists are guild-scoped, WhatsApp rejects strangers by default, and TOCTOU windows close across auth.json and MCP OAuth. Google Chat becomes the 20th platform. Providers become a pluggable surface. Seven i18n locales ship.
+
+---
+
+## ✨ Highlights
+
+- **Multi-agent Kanban — delegate to an AI team that actually finishes** — Spin up a durable board, drop tasks on it, and let multiple Hermes workers pick them up, hand off, and close them out. Heartbeats, reclaim, zombie detection, retry budgets, and a hallucination gate keep the team honest. One install, many kanbans. ([#17805](https://github.com/NousResearch/hermes-agent/pull/17805), [#19653](https://github.com/NousResearch/hermes-agent/pull/19653), [#20232](https://github.com/NousResearch/hermes-agent/pull/20232), [#20332](https://github.com/NousResearch/hermes-agent/pull/20332), [#21330](https://github.com/NousResearch/hermes-agent/pull/21330), [#21183](https://github.com/NousResearch/hermes-agent/pull/21183), [#21214](https://github.com/NousResearch/hermes-agent/pull/21214))
+
+- **`/goal` — the agent doesn't forget what you asked it to do** — Lock the agent onto a target and it stays on task across turns. The Ralph loop as a first-class primitive. ([#18262](https://github.com/NousResearch/hermes-agent/pull/18262), [#18275](https://github.com/NousResearch/hermes-agent/pull/18275), [#21287](https://github.com/NousResearch/hermes-agent/pull/21287))
+
+- **Show it a video** — new `video_analyze` tool for native video understanding on Gemini and compatible multimodal models. (@alt-glitch) ([#19301](https://github.com/NousResearch/hermes-agent/pull/19301))
+
+- **Clone a voice** — xAI Custom Voices lands as a TTS provider with voice cloning support. (@alt-glitch) ([#18776](https://github.com/NousResearch/hermes-agent/pull/18776))
+
+- **Hermes speaks your language** — static gateway + CLI messages translate to 7 locales: Chinese, Japanese, German, Spanish, French, Ukrainian, and Turkish. Docs site gains a Chinese (zh-Hans) locale. ([#20231](https://github.com/NousResearch/hermes-agent/pull/20231), [#20329](https://github.com/NousResearch/hermes-agent/pull/20329), [#20467](https://github.com/NousResearch/hermes-agent/pull/20467), [#20474](https://github.com/NousResearch/hermes-agent/pull/20474), [#20430](https://github.com/NousResearch/hermes-agent/pull/20430), [#20431](https://github.com/NousResearch/hermes-agent/pull/20431))
+
+- **Google Chat — the 20th messaging platform** — plus a generic platform-plugin hooks surface so third-party adapters drop in without touching core (IRC and Teams migrated). ([#21306](https://github.com/NousResearch/hermes-agent/pull/21306), [#21331](https://github.com/NousResearch/hermes-agent/pull/21331))
+
+- **Sessions survive restarts** — gateway bounces mid-agent, `/update` restarts, source-file reloads — conversations auto-resume when the gateway comes back. ([#21192](https://github.com/NousResearch/hermes-agent/pull/21192))
+
+- **Security wave — 8 P0 closures** — redaction ON by default, Discord role-allowlists guild-scoped (CVSS 8.1 cross-guild DM bypass closed), WhatsApp rejects strangers by default, TOCTOU windows closed across `auth.json` and MCP OAuth, browser enforces cloud-metadata SSRF floor, cron prompt-injection scans assembled skill content, `hermes debug share` redacts at upload. ([#21193](https://github.com/NousResearch/hermes-agent/pull/21193), [#21241](https://github.com/NousResearch/hermes-agent/pull/21241), [#21291](https://github.com/NousResearch/hermes-agent/pull/21291), [#21176](https://github.com/NousResearch/hermes-agent/pull/21176), [#21194](https://github.com/NousResearch/hermes-agent/pull/21194), [#21228](https://github.com/NousResearch/hermes-agent/pull/21228), [#21350](https://github.com/NousResearch/hermes-agent/pull/21350), [#19318](https://github.com/NousResearch/hermes-agent/pull/19318))
+
+- **Checkpoints v2** — state persistence rewritten. Real pruning, disk guardrails, no more orphan shadow repos. ([#20709](https://github.com/NousResearch/hermes-agent/pull/20709))
+
+- **The agent lints its own writes** — post-write delta lint on `write_file` + `patch`. Python, JSON, YAML, TOML. Syntax errors surface immediately instead of shipping downstream. ([#20191](https://github.com/NousResearch/hermes-agent/pull/20191))
+
+- **`no_agent` cron mode — script-only watchdog** — cron jobs can now skip the agent entirely and just run a script. Empty stdout is silent, non-empty gets delivered verbatim. ([#19709](https://github.com/NousResearch/hermes-agent/pull/19709))
+
+- **Platform allowlists everywhere** — `allowed_channels` / `allowed_chats` / `allowed_rooms` config across Slack, Telegram, Mattermost, Matrix, and DingTalk. ([#21251](https://github.com/NousResearch/hermes-agent/pull/21251))
+
+- **Providers are now plugins** — `ProviderProfile` ABC + `plugins/model-providers/`. Drop in third-party providers without touching core. ([#20324](https://github.com/NousResearch/hermes-agent/pull/20324))
+
+- **API server — long-term memory per session** — `X-Hermes-Session-Key` header gives memory providers a stable session identifier. ([#20199](https://github.com/NousResearch/hermes-agent/pull/20199))
+
+- **MCP levels up** — SSE transport with OAuth forwarding, stale-pipe retries, image results surface as MEDIA tags instead of getting dropped, keepalive on long-lived lifecycle waits. ([#21227](https://github.com/NousResearch/hermes-agent/pull/21227), [#21323](https://github.com/NousResearch/hermes-agent/pull/21323), [#21289](https://github.com/NousResearch/hermes-agent/pull/21289), [#21328](https://github.com/NousResearch/hermes-agent/pull/21328), [#20209](https://github.com/NousResearch/hermes-agent/pull/20209))
+
+- **Curator grows subcommands** — `hermes curator archive`, `prune`, `list-archived`. Manual `hermes curator run` is synchronous now — you see results without polling. ([#20200](https://github.com/NousResearch/hermes-agent/pull/20200), [#21236](https://github.com/NousResearch/hermes-agent/pull/21236), [#21216](https://github.com/NousResearch/hermes-agent/pull/21216))
+
+- **ACP — `/steer` and `/queue`** — direct the in-flight agent or queue follow-ups from Zed, VS Code, or JetBrains. Plus atomic session persistence and reasoning-metadata preservation across restarts. (@HenkDz) ([#18114](https://github.com/NousResearch/hermes-agent/pull/18114), [#20279](https://github.com/NousResearch/hermes-agent/pull/20279), [#20296](https://github.com/NousResearch/hermes-agent/pull/20296), [#20433](https://github.com/NousResearch/hermes-agent/pull/20433))
+
+- **TUI glow-up** — `/model` picker matches `hermes model` with inline auth (@austinpickett), collapsible startup banner sections (@kshitijk4poor), context-compression counter in the status bar. ([#18117](https://github.com/NousResearch/hermes-agent/pull/18117), [#20625](https://github.com/NousResearch/hermes-agent/pull/20625), [#21218](https://github.com/NousResearch/hermes-agent/pull/21218))
+
+- **Dashboard grows up** — Plugins page (manage, enable/disable, auth status) (@austinpickett), Profiles management page (@vincez-hms-coder), sortable analytics tables, reverse-proxy support via `X-Forwarded-Prefix`, new `default-large` 18px theme. ([#18095](https://github.com/NousResearch/hermes-agent/pull/18095), [#16419](https://github.com/NousResearch/hermes-agent/pull/16419), [#18192](https://github.com/NousResearch/hermes-agent/pull/18192), [#21296](https://github.com/NousResearch/hermes-agent/pull/21296), [#20820](https://github.com/NousResearch/hermes-agent/pull/20820))
+
+- **SearXNG + split web tools** — SearXNG ships as a native search-only backend; web tools now let you pick different backends per capability (search vs extract vs browse). (@kshitijk4poor) ([#20823](https://github.com/NousResearch/hermes-agent/pull/20823), [#20061](https://github.com/NousResearch/hermes-agent/pull/20061), [#20841](https://github.com/NousResearch/hermes-agent/pull/20841))
+
+- **OpenRouter response caching** — explicit cache control for models that expose it. (@kshitijk4poor) ([#19132](https://github.com/NousResearch/hermes-agent/pull/19132))
+
+- **`[[as_document]]` — skill media-routing directive** — skills can force the gateway to deliver output as a document on platforms that support it. ([#21210](https://github.com/NousResearch/hermes-agent/pull/21210))
+
+- **`transform_llm_output` plugin hook** — new lifecycle hook that lets plugins reshape or filter LLM output before it hits the conversation. Useful for context-window reducers and content filters. ([#21235](https://github.com/NousResearch/hermes-agent/pull/21235))
+
+- **Nous OAuth persists across profiles** — shared token store: sign in once, every profile inherits the session. ([#19712](https://github.com/NousResearch/hermes-agent/pull/19712))
+
+- **QQBot — native approval keyboards** — feature parity with Telegram / Discord approval UX. Chunked upload, quoted attachments. ([#21342](https://github.com/NousResearch/hermes-agent/pull/21342), [#21353](https://github.com/NousResearch/hermes-agent/pull/21353))
+
+- **6 new optional skills** — Shopify (Admin + Storefront GraphQL), here.now, shop-app personal shopping assistant, Anthropic financial-services bundle, kanban-video-orchestrator (@SHL0MS), searxng-search (@kshitijk4poor). ([#18116](https://github.com/NousResearch/hermes-agent/pull/18116), [#18170](https://github.com/NousResearch/hermes-agent/pull/18170), [#20702](https://github.com/NousResearch/hermes-agent/pull/20702), [#21180](https://github.com/NousResearch/hermes-agent/pull/21180), [#19281](https://github.com/NousResearch/hermes-agent/pull/19281), [#20841](https://github.com/NousResearch/hermes-agent/pull/20841))
+
+- **New models** — `deepseek/deepseek-v4-pro`, `x-ai/grok-4.3`, `openrouter/owl-alpha` (free), `tencent/hy3-preview` (@Contentment003111), Arcee Trinity Large Thinking temperature + compression overrides. ([#20495](https://github.com/NousResearch/hermes-agent/pull/20495), [#20497](https://github.com/NousResearch/hermes-agent/pull/20497), [#18071](https://github.com/NousResearch/hermes-agent/pull/18071), [#21077](https://github.com/NousResearch/hermes-agent/pull/21077), [#20473](https://github.com/NousResearch/hermes-agent/pull/20473))
+
+- **100 fresh CLI startup tips** — the random tip banner gets 100 new entries covering cron, kanban, curator, plugins, and lesser-known flags. ([#20168](https://github.com/NousResearch/hermes-agent/pull/20168))
+
+---
+
+## 🧩 Multi-Agent Kanban (Durable)
+
+### New — durable multi-profile collaboration board
+- **`feat(kanban): durable multi-profile collaboration board`** — post-revert reimplementation, multi-profile by design ([#17805](https://github.com/NousResearch/hermes-agent/pull/17805))
+- **Multi-project boards** — one install, many kanbans ([#19653](https://github.com/NousResearch/hermes-agent/pull/19653), [#19679](https://github.com/NousResearch/hermes-agent/pull/19679))
+- **Share board, workspaces, and worker logs across profiles** ([#19378](https://github.com/NousResearch/hermes-agent/pull/19378))
+- **Hallucination gate + recovery UX for worker-created-card claims** (closes #20017) ([#20232](https://github.com/NousResearch/hermes-agent/pull/20232))
+- **Generic diagnostics engine for task distress signals** ([#20332](https://github.com/NousResearch/hermes-agent/pull/20332))
+- **Per-task `max_retries` override** (supersedes #20972) ([#21330](https://github.com/NousResearch/hermes-agent/pull/21330))
+- **Multiline textarea for inline-create title** (salvage of #20970) ([#21243](https://github.com/NousResearch/hermes-agent/pull/21243))
+
+### Kanban Dashboard
+- **Workspace kind + path inputs in inline create form** ([#19679](https://github.com/NousResearch/hermes-agent/pull/19679))
+- **Per-platform home-channel notification toggles** ([#19864](https://github.com/NousResearch/hermes-agent/pull/19864))
+- **Sharper home-channel toggle contrast + drop → running action** ([#19916](https://github.com/NousResearch/hermes-agent/pull/19916))
+- Fix: reject direct status transition to 'running' via dashboard API (salvage of #19554) ([#19705](https://github.com/NousResearch/hermes-agent/pull/19705))
+- Fix: dashboard board pin authoritative over server current file (#20879) ([#21230](https://github.com/NousResearch/hermes-agent/pull/21230))
+- Fix: treat dashboard event-stream cancellation as normal shutdown (#20790) ([#21222](https://github.com/NousResearch/hermes-agent/pull/21222))
+- Fix: filter dashboard board by selected tenant (#19817) ([#21349](https://github.com/NousResearch/hermes-agent/pull/21349))
+- Fix: code/pre styling theme-immune across all themes (#21086) ([#21247](https://github.com/NousResearch/hermes-agent/pull/21247))
+- Fix: reset `<code>` background inside dashboard board ([#20687](https://github.com/NousResearch/hermes-agent/pull/20687))
+- Fix: preserve dashboard completion summaries + add kanban edit (salvages #20016) ([#20195](https://github.com/NousResearch/hermes-agent/pull/20195))
+- Fix: avoid fragile failure-column renames (salvage #20848) (@kshitijk4poor) ([#20855](https://github.com/NousResearch/hermes-agent/pull/20855))
+
+### Worker lifecycle + reliability
+- **Heartbeat + reclaim + zombie + retry-cap fixes** (#21147, #21141, #21169, #20881) ([#21183](https://github.com/NousResearch/hermes-agent/pull/21183))
+- **Auto-block workers that exit without completing + shutdown race** (#20894) ([#21214](https://github.com/NousResearch/hermes-agent/pull/21214))
+- **Detect darwin zombie workers** (salvages #20023) ([#20188](https://github.com/NousResearch/hermes-agent/pull/20188))
+- **Unify failure counter across spawn/timeout/crash outcomes** ([#20410](https://github.com/NousResearch/hermes-agent/pull/20410))
+- **Enforce worker task-ownership on destructive tool calls** ([#19713](https://github.com/NousResearch/hermes-agent/pull/19713))
+- **Drop worker identity claim from KANBAN_GUIDANCE** ([#19427](https://github.com/NousResearch/hermes-agent/pull/19427))
+- Fix: skip dispatch for tasks assigned to non-profile lanes (salvages #20105, #20134) ([#20165](https://github.com/NousResearch/hermes-agent/pull/20165))
+- Fix: include default profile in on-disk assignee enumeration (salvages #20123) ([#20170](https://github.com/NousResearch/hermes-agent/pull/20170))
+- Fix: ignore stale current board pointers (salvages #20063) ([#20183](https://github.com/NousResearch/hermes-agent/pull/20183))
+- Fix: profile discovery ignores HERMES_HOME in custom-root deployments (@jackey8616) ([#19020](https://github.com/NousResearch/hermes-agent/pull/19020))
+- Fix: allow orchestrator profiles to see kanban tools via toolsets config ([#19606](https://github.com/NousResearch/hermes-agent/pull/19606))
+
+### Batch salvages
+- Tier-1 batch — metadata test, max_spawn config, run-id lifecycle guard (salvages #19522 #19556 #19829) ([#20440](https://github.com/NousResearch/hermes-agent/pull/20440))
+- Tier-2 batch — doctor, started_at, parent-guard, latest_summary, selects, linked-children ([#20448](https://github.com/NousResearch/hermes-agent/pull/20448))
+
+### Documentation
+- Backfill multi-board refs in reference docs ([#19704](https://github.com/NousResearch/hermes-agent/pull/19704))
+- Document `/kanban` slash command ([#19584](https://github.com/NousResearch/hermes-agent/pull/19584))
+- Document recommended handoff evidence metadata (salvage #19512) ([#20415](https://github.com/NousResearch/hermes-agent/pull/20415))
+- Fix orchestrator + worker skill setup instructions (@helix4u) ([#20958](https://github.com/NousResearch/hermes-agent/pull/20958), [#20960](https://github.com/NousResearch/hermes-agent/pull/20960))
+
+---
+
+## 🎯 Persistent Goals, Checkpoints & Session Durability
+
+### `/goal` — persistent cross-turn goals (Ralph loop)
+- **`feat: /goal — persistent cross-turn goals`** ([#18262](https://github.com/NousResearch/hermes-agent/pull/18262))
+- **Docs page — Persistent Goals (/goal)** ([#18275](https://github.com/NousResearch/hermes-agent/pull/18275))
+- Fix: honor configured goal turn budget (salvage #19423) ([#21287](https://github.com/NousResearch/hermes-agent/pull/21287))
+
+### Checkpoints v2
+- **Single-store rewrite with real pruning + disk guardrails** ([#20709](https://github.com/NousResearch/hermes-agent/pull/20709))
+
+### Session durability
+- **Auto-resume interrupted sessions after gateway restart** (salvage #20888) ([#21192](https://github.com/NousResearch/hermes-agent/pull/21192))
+- **Preserve pending update prompts across restarts** ([#20160](https://github.com/NousResearch/hermes-agent/pull/20160))
+- **Preserve home-channel thread targets across restart notifications** (salvage #18440) ([#19271](https://github.com/NousResearch/hermes-agent/pull/19271))
+- **Preserve thread routing from cached live session sources** ([#21206](https://github.com/NousResearch/hermes-agent/pull/21206))
+- **Preserve assistant metadata when branching sessions** ([#18222](https://github.com/NousResearch/hermes-agent/pull/18222))
+- **Preserve thread routing for /update progress and prompts** ([#18193](https://github.com/NousResearch/hermes-agent/pull/18193))
+- **Preserve document type when merging queued events** ([#18215](https://github.com/NousResearch/hermes-agent/pull/18215))
+
+---
+
+## 🛡️ Security & Reliability
+
+### Security hardening (8 P0 closures)
+- **Enable secret redaction by default** (#17691, #20785) ([#21193](https://github.com/NousResearch/hermes-agent/pull/21193))
+- **Discord — scope `DISCORD_ALLOWED_ROLES` to originating guild** (#12136, CVSS 8.1) ([#21241](https://github.com/NousResearch/hermes-agent/pull/21241))
+- **WhatsApp — reject strangers by default, never respond in self-chat** (#8389) ([#21291](https://github.com/NousResearch/hermes-agent/pull/21291))
+- **MCP OAuth — close TOCTOU window when saving credentials** ([#21176](https://github.com/NousResearch/hermes-agent/pull/21176))
+- **`hermes_cli/auth.py` — close TOCTOU window in credential writers** ([#21194](https://github.com/NousResearch/hermes-agent/pull/21194))
+- **Browser — enforce cloud-metadata SSRF floor in hybrid routing** (#16234) ([#21228](https://github.com/NousResearch/hermes-agent/pull/21228))
+- **`hermes debug share` — redact log content at upload time** (@GodsBoy) ([#19318](https://github.com/NousResearch/hermes-agent/pull/19318))
+- **Cron — scan assembled prompt including skill content for prompt injection** (#3968) ([#21350](https://github.com/NousResearch/hermes-agent/pull/21350))
+- **Restore .env/auth.json/state.db with 0600 perms** ([#19699](https://github.com/NousResearch/hermes-agent/pull/19699))
+- **SRI integrity for dashboard plugin scripts** (salvage #19389) ([#21277](https://github.com/NousResearch/hermes-agent/pull/21277))
+- **Bind Meet node server to localhost, restrict token file to owner read** ([#19597](https://github.com/NousResearch/hermes-agent/pull/19597))
+- **Extend sensitive-write target to cover shell RC and credential files** ([#19282](https://github.com/NousResearch/hermes-agent/pull/19282))
+- **Harden YOLO mode env parsing against quoted-bool strings** ([#18214](https://github.com/NousResearch/hermes-agent/pull/18214))
+- **OSV-Scanner CI + Dependabot for github-actions only** ([#20037](https://github.com/NousResearch/hermes-agent/pull/20037))
+
+### Reliability — critical bug closures
+- **CLI crash on startup — `Invalid key 'c-S-c'`** (P0, prompt_toolkit doesn't support Shift modifier) ([#19895](https://github.com/NousResearch/hermes-agent/pull/19895), [#19919](https://github.com/NousResearch/hermes-agent/pull/19919))
+- **CLOSE_WAIT fd leak audit** — httpx keepalive + WhatsApp aiohttp leak + Feishu hygiene (#18451) ([#18766](https://github.com/NousResearch/hermes-agent/pull/18766))
+- **Gateway creates AIAgent with empty OpenRouter API key when OPENROUTER_API_KEY is missing** (#20982) — fallback providers correctly honored
+- **Background review + curator protected from overwriting bundled/hub skills** (#20273) ([#20194](https://github.com/NousResearch/hermes-agent/pull/20194))
+- **TUI compression continuation — ghost sessions with incomplete metadata** (#20001)
+- **`hermes mcp add` silently launches chat instead of registering MCP server** (#19785) ([#21204](https://github.com/NousResearch/hermes-agent/pull/21204))
+- **Background review agent runtime propagation** — provider/model/credentials now actually inherit from parent
+- **Inbound document host paths translated to container paths for Docker backend** (salvage #19048) ([#21184](https://github.com/NousResearch/hermes-agent/pull/21184))
+- **Matrix gateway race between auto-redaction and message delivery with high-speed models** (#19075)
+- **`/new` during active agent session never sends response on Telegram** (#18912)
+
+---
+
+## 📱 Messaging Platforms (Gateway)
+
+### New platform
+- **Google Chat — 20th platform** + generic `env_enablement_fn` / `cron_deliver_env_var` platform-plugin hooks (IRC + Teams migrated) ([#21306](https://github.com/NousResearch/hermes-agent/pull/21306), [#21331](https://github.com/NousResearch/hermes-agent/pull/21331))
+
+### Cross-platform
+- **`allowed_{channels,chats,rooms}` whitelist** — Slack (salvage #7401), Telegram, Mattermost, Matrix, DingTalk ([#21251](https://github.com/NousResearch/hermes-agent/pull/21251))
+- **Per-platform `gateway_restart_notification` flag** ([#20892](https://github.com/NousResearch/hermes-agent/pull/20892))
+- **`busy_ack_enabled` config — suppress ack messages** ([#18194](https://github.com/NousResearch/hermes-agent/pull/18194))
+- **Auto-delete slash-command system notices after TTL** ([#18266](https://github.com/NousResearch/hermes-agent/pull/18266))
+- **Opt-in cleanup of temporary progress bubbles** ([#21186](https://github.com/NousResearch/hermes-agent/pull/21186))
+- **`[[as_document]]` directive — skill media routing** (salvage #19069) ([#21210](https://github.com/NousResearch/hermes-agent/pull/21210))
+- **`hermes gateway list` — cross-profile status** (salvage #19129) ([#21225](https://github.com/NousResearch/hermes-agent/pull/21225))
+- **Auto-resume interrupted sessions after restart** (salvage #20888) ([#21192](https://github.com/NousResearch/hermes-agent/pull/21192))
+- **Atomic restart markers + Windows runtime-lock offset** (#17842) ([#18179](https://github.com/NousResearch/hermes-agent/pull/18179))
+- Fix: `config.yaml` wins over `.env` for agent/display/timezone settings ([#18764](https://github.com/NousResearch/hermes-agent/pull/18764))
+- Fix: auto-restart when source files change out from under us (#17648) ([#18409](https://github.com/NousResearch/hermes-agent/pull/18409))
+- Fix: use git HEAD SHA for stale-code check, not file mtimes ([#19740](https://github.com/NousResearch/hermes-agent/pull/19740))
+- Fix: shutdown + restart hygiene — drain timeout, false-fatal, success log ([#18761](https://github.com/NousResearch/hermes-agent/pull/18761))
+- Fix: preserve max_turns after env reload (salvage #19183) ([#21240](https://github.com/NousResearch/hermes-agent/pull/21240))
+- Fix: exclude ancestor PIDs from gateway process scan ([#19586](https://github.com/NousResearch/hermes-agent/pull/19586))
+- Fix: move quick-command alias dispatch before built-ins ([#19588](https://github.com/NousResearch/hermes-agent/pull/19588))
+- Fix: show other profiles in 'gateway status' to prevent confusion ([#19582](https://github.com/NousResearch/hermes-agent/pull/19582))
+- Fix: include external_dirs skills in Telegram/Discord slash commands (salvage #8790) ([#18741](https://github.com/NousResearch/hermes-agent/pull/18741))
+- Fix: match disabled/optional skills by frontmatter slug, not dir name ([#18753](https://github.com/NousResearch/hermes-agent/pull/18753))
+- Fix: read /status token totals from SessionDB (#17158) ([#18206](https://github.com/NousResearch/hermes-agent/pull/18206))
+- Fix: snapshot callback generation after agent binds it, not before ([#18219](https://github.com/NousResearch/hermes-agent/pull/18219))
+- Fix: re-inject topic-bound skill after /new or /reset ([#18205](https://github.com/NousResearch/hermes-agent/pull/18205))
+- Fix: isolate pending native image paths by session ([#18202](https://github.com/NousResearch/hermes-agent/pull/18202))
+- Fix: clear queued reload skills notes on new/resume/branch ([#19431](https://github.com/NousResearch/hermes-agent/pull/19431))
+- Fix: hide required-arg commands from Telegram menu ([#19400](https://github.com/NousResearch/hermes-agent/pull/19400))
+- Fix: bridge top-level `require_mention` to Telegram config ([#19429](https://github.com/NousResearch/hermes-agent/pull/19429))
+- Fix: suppress duplicate voice transcripts ([#19428](https://github.com/NousResearch/hermes-agent/pull/19428))
+- Fix: show friendly error when service is not installed ([#19707](https://github.com/NousResearch/hermes-agent/pull/19707))
+- Fix: read context_length from custom_providers in session info header ([#19708](https://github.com/NousResearch/hermes-agent/pull/19708))
+- Fix: preserve WSL interop PATH in systemd units ([#19867](https://github.com/NousResearch/hermes-agent/pull/19867))
+- Fix: handle planned service stops (salvage #19876) ([#19936](https://github.com/NousResearch/hermes-agent/pull/19936))
+- Fix: keep DoH-confirmed Telegram IPs that match system DNS (salvage #17043) ([#20175](https://github.com/NousResearch/hermes-agent/pull/20175))
+- Fix: load `reply_to_mode` from config.yaml for Discord + Telegram (salvage #17117) ([#20171](https://github.com/NousResearch/hermes-agent/pull/20171))
+- Fix: tolerate malformed HERMES_HUMAN_DELAY_* env vars (salvage #16933) ([#20217](https://github.com/NousResearch/hermes-agent/pull/20217))
+- Fix: deterministic thread eviction preserves newest entries (salvage #13639) ([#20285](https://github.com/NousResearch/hermes-agent/pull/20285))
+- Fix: don't dead-end setup wizard when only system-scope unit is installed ([#20905](https://github.com/NousResearch/hermes-agent/pull/20905))
+- Fix: wait for systemd restart readiness + harden Discord slash-command sync ([#20949](https://github.com/NousResearch/hermes-agent/pull/20949))
+- Fix: avoid duplicated Responses history (salvage #18995) ([#21185](https://github.com/NousResearch/hermes-agent/pull/21185))
+- Fix: surface bootstrap failures to stderr (salvage #21157) ([#21278](https://github.com/NousResearch/hermes-agent/pull/21278))
+- Fix: log agent task failures instead of silently losing usage data (salvage #21159) ([#21274](https://github.com/NousResearch/hermes-agent/pull/21274))
+- Fix: log runtime-status write failures with rate-limiting (salvage #21158) ([#21285](https://github.com/NousResearch/hermes-agent/pull/21285))
+- Fix: reset-failed before every fallback restart so the gateway can't get stranded ([#21371](https://github.com/NousResearch/hermes-agent/pull/21371))
+- Fix: Telegram — preserve `thread_id=1` for forum General typing indicator ([#21390](https://github.com/NousResearch/hermes-agent/pull/21390))
+- Fix: batch critical fixes — session resume, /new race, HA WebSocket scheme (@kshitijk4poor) ([#19182](https://github.com/NousResearch/hermes-agent/pull/19182))
+
+### Telegram
+- **DM user-managed multi-session topics** (salvage of #19185) ([#19206](https://github.com/NousResearch/hermes-agent/pull/19206))
+
+### Discord
+- **Message deletion action** (salvage #19052) ([#21197](https://github.com/NousResearch/hermes-agent/pull/21197))
+- Fix: allow `free_response_channels` to override `DISCORD_IGNORE_NO_MENTION` ([#19629](https://github.com/NousResearch/hermes-agent/pull/19629))
+
+### Slack
+- Fix: ephemeral slash-command ack, private notice delivery, format_message fixes (@kshitijk4poor) ([#18198](https://github.com/NousResearch/hermes-agent/pull/18198))
+
+### WhatsApp
+- Fix: load WhatsApp home channel from env overrides ([#18190](https://github.com/NousResearch/hermes-agent/pull/18190))
+
+### Feishu
+- **Operator-configurable bot admission and mention policy** ([#18208](https://github.com/NousResearch/hermes-agent/pull/18208))
+- Fix: force text mode for markdown tables (salvage of #13723 by @WuTianyi123) ([#20275](https://github.com/NousResearch/hermes-agent/pull/20275))
+
+### Matrix + Email
+- Fix: `/sethome` on Matrix and Email now persists across restarts ([#18272](https://github.com/NousResearch/hermes-agent/pull/18272))
+
+### Teams
+- **Docs + feat: sidebar + threading with group-chat fallback** ([#20042](https://github.com/NousResearch/hermes-agent/pull/20042))
+
+### Weixin
+- Fix: deduplicate Weixin messages by content fingerprint ([#19742](https://github.com/NousResearch/hermes-agent/pull/19742))
+
+### QQBot
+- **Port SDK improvements in-tree — chunked upload, approval keyboards, quoted attachments** ([#21342](https://github.com/NousResearch/hermes-agent/pull/21342))
+- **Wire native tool-approval UX via inline keyboards** ([#21353](https://github.com/NousResearch/hermes-agent/pull/21353))
+
+---
+
+## 🏗️ Core Agent & Architecture
+
+### Provider & Model Support
+
+#### Pluggable providers
+- **ProviderProfile ABC + `plugins/model-providers/`** — inference providers are now a pluggable surface (salvage of #14424) ([#20324](https://github.com/NousResearch/hermes-agent/pull/20324))
+- **`list_picker_providers`** — credential-filtered picker (salvage #13561) ([#20298](https://github.com/NousResearch/hermes-agent/pull/20298))
+- **Remove `/provider` alias for `/model`** ([#20358](https://github.com/NousResearch/hermes-agent/pull/20358))
+- **Shared Hermes dotenv loader across CLI + plugins** (salvage #13660) ([#20281](https://github.com/NousResearch/hermes-agent/pull/20281))
+- **Nous OAuth persisted across profiles via shared token store** ([#19712](https://github.com/NousResearch/hermes-agent/pull/19712))
+
+#### New models
+- `deepseek/deepseek-v4-pro` added to OpenRouter + Nous Portal ([#20495](https://github.com/NousResearch/hermes-agent/pull/20495))
+- `x-ai/grok-4.3` added to OpenRouter + Nous Portal ([#20497](https://github.com/NousResearch/hermes-agent/pull/20497))
+- `openrouter/owl-alpha` (free tier) added to curated OpenRouter list ([#18071](https://github.com/NousResearch/hermes-agent/pull/18071))
+- `tencent/hy3-preview` paid route on OpenRouter (@Contentment003111) ([#21077](https://github.com/NousResearch/hermes-agent/pull/21077))
+- Arcee Trinity Large Thinking — temperature + compression overrides ([#20473](https://github.com/NousResearch/hermes-agent/pull/20473))
+- Rename `x-ai/grok-4.20-beta` to `x-ai/grok-4.20` ([#19640](https://github.com/NousResearch/hermes-agent/pull/19640))
+- Demote Vercel AI Gateway to bottom of provider picker ([#18112](https://github.com/NousResearch/hermes-agent/pull/18112))
+
+#### Provider configuration
+- **OpenRouter — response caching support** (@kshitijk4poor) ([#19132](https://github.com/NousResearch/hermes-agent/pull/19132))
+- **`image_gen.model` from config.yaml honored** (salvage #19376) ([#21273](https://github.com/NousResearch/hermes-agent/pull/21273))
+- Fix: honor runtime default model during delegate provider resolution (@johnncenae) ([#17587](https://github.com/NousResearch/hermes-agent/pull/17587))
+- Fix: avoid Bedrock credential probe in provider picker (@helix4u) ([#18998](https://github.com/NousResearch/hermes-agent/pull/18998))
+- Fix: drop stale env-var override of persisted provider for cron ([#19627](https://github.com/NousResearch/hermes-agent/pull/19627))
+- Fix: auxiliary curator api_key/base_url into runtime resolution ([#19421](https://github.com/NousResearch/hermes-agent/pull/19421))
+
+### Agent Loop & Conversation
+- **`video_analyze` — native video understanding tool** (@alt-glitch) ([#19301](https://github.com/NousResearch/hermes-agent/pull/19301))
+- **Show context compression count in status bar** (CLI + TUI) ([#21218](https://github.com/NousResearch/hermes-agent/pull/21218))
+- **Isolate `get_tool_definitions` quiet_mode cache + dedup LCM injection** (#17335) ([#17889](https://github.com/NousResearch/hermes-agent/pull/17889))
+- Fix: warning-first tool-call loop guardrails ([#18227](https://github.com/NousResearch/hermes-agent/pull/18227))
+- Fix: break permanent empty-response loop from orphan tool-tail ([#21385](https://github.com/NousResearch/hermes-agent/pull/21385))
+- Fix: propagate ContextVars to concurrent tool worker threads (salvage #16660) ([#18123](https://github.com/NousResearch/hermes-agent/pull/18123))
+- Fix: surface self-improvement review summaries across CLI, TUI, and gateway ([#18073](https://github.com/NousResearch/hermes-agent/pull/18073))
+- Fix: serialize concurrent `hermes_tools` RPC calls from `execute_code` ([#17894](https://github.com/NousResearch/hermes-agent/pull/17894), [#17902](https://github.com/NousResearch/hermes-agent/pull/17902))
+- Fix: include system prompt + tool schemas in token estimates for compression ([#18265](https://github.com/NousResearch/hermes-agent/pull/18265))
+
+### Compression
+- Fix: skip non-string tool content in dedup pass to prevent AttributeError ([#19398](https://github.com/NousResearch/hermes-agent/pull/19398))
+- Fix: reset `_summary_failure_cooldown_until` on session reset ([#19622](https://github.com/NousResearch/hermes-agent/pull/19622))
+- Fix: trigger fallback on timeout errors alongside model-unavailable errors ([#19665](https://github.com/NousResearch/hermes-agent/pull/19665))
+- Fix: `_prune_old_tool_results` boundary direction ([#19725](https://github.com/NousResearch/hermes-agent/pull/19725))
+- Fix: soften summary prompt for content filters (salvage #19456) ([#21302](https://github.com/NousResearch/hermes-agent/pull/21302))
+
+### Delegate
+- Fix: inherit parent fallback_chain in `_build_child_agent` ([#19601](https://github.com/NousResearch/hermes-agent/pull/19601))
+- Fix: guard `_load_config()` against `delegation: null` in config.yaml ([#19662](https://github.com/NousResearch/hermes-agent/pull/19662))
+- Fix: inherit parent api_key when `delegation.base_url` set without `delegation.api_key` ([#19741](https://github.com/NousResearch/hermes-agent/pull/19741))
+- Fix: expand composite toolsets before intersection (salvage #19455) ([#21300](https://github.com/NousResearch/hermes-agent/pull/21300))
+- Fix: correct ACP docs — Claude Code CLI has no --acp flag (salvage #19058) ([#21201](https://github.com/NousResearch/hermes-agent/pull/21201))
+
+### Session & Memory
+- **Hindsight — probe API for `update_mode='append'` to dedupe across processes** (@nicoloboschi) ([#20222](https://github.com/NousResearch/hermes-agent/pull/20222))
+
+### Curator
+- **`hermes curator archive` and `prune` subcommands** ([#20200](https://github.com/NousResearch/hermes-agent/pull/20200))
+- **`hermes curator list-archived`** (#20651) ([#21236](https://github.com/NousResearch/hermes-agent/pull/21236))
+- **Synchronous manual `hermes curator run`** (#20555) ([#21216](https://github.com/NousResearch/hermes-agent/pull/21216))
+- Fix: preserve `last_report_path` in state ([#18169](https://github.com/NousResearch/hermes-agent/pull/18169))
+- Fix: rewrite cron job skill refs after consolidation ([#18253](https://github.com/NousResearch/hermes-agent/pull/18253))
+- Fix: defer first run + `--dry-run` preview (#18373) ([#18389](https://github.com/NousResearch/hermes-agent/pull/18389))
+- Fix: authoritative `absorbed_into` on delete + restore cron skill links on rollback (#18671) ([#18731](https://github.com/NousResearch/hermes-agent/pull/18731))
+- Fix: prevent false-positive consolidation from substring matching ([#19573](https://github.com/NousResearch/hermes-agent/pull/19573))
+- Fix: only mark agent-created for background-review sediment ([#19621](https://github.com/NousResearch/hermes-agent/pull/19621))
+- Fix: protect hub skills by frontmatter name ([#20194](https://github.com/NousResearch/hermes-agent/pull/20194))
+
+---
+
+## 🔧 Tool System
+
+### File tools
+- **Post-write delta lint on `write_file` + `patch`** — in-proc linters for Python, JSON, YAML, TOML ([#20191](https://github.com/NousResearch/hermes-agent/pull/20191))
+
+### Cron
+- **`no_agent` mode — script-only cron jobs (watchdog pattern)** ([#19709](https://github.com/NousResearch/hermes-agent/pull/19709))
+- **`context_from` chaining docs** (salvage #15724) ([#20394](https://github.com/NousResearch/hermes-agent/pull/20394))
+- Fix: treat non-dict origin as missing instead of crashing tick ([#19283](https://github.com/NousResearch/hermes-agent/pull/19283))
+- Fix: bump skill usage when cron jobs load skills ([#19433](https://github.com/NousResearch/hermes-agent/pull/19433))
+- Fix: recover null `next_run_at` jobs ([#19576](https://github.com/NousResearch/hermes-agent/pull/19576))
+- Fix: skip AI call when prerun script produces no output ([#19628](https://github.com/NousResearch/hermes-agent/pull/19628))
+- Fix: expand config.yaml refs during job execution ([#19872](https://github.com/NousResearch/hermes-agent/pull/19872))
+- Fix: serialize `get_due_jobs` writes to prevent parallel state corruption ([#19874](https://github.com/NousResearch/hermes-agent/pull/19874))
+- Fix: initialize MCP servers before constructing the cron AIAgent ([#21354](https://github.com/NousResearch/hermes-agent/pull/21354))
+
+### MCP
+- **SSE transport support** (salvage #19135) ([#21227](https://github.com/NousResearch/hermes-agent/pull/21227))
+- **Forward OAuth auth + bump `sse_read_timeout` on SSE transport** ([#21323](https://github.com/NousResearch/hermes-agent/pull/21323))
+- **Retry stale pipe transport failures as session-expired** ([#21289](https://github.com/NousResearch/hermes-agent/pull/21289))
+- **Surface image tool results as MEDIA tags instead of dropping them** ([#21328](https://github.com/NousResearch/hermes-agent/pull/21328))
+- **Periodic keepalive to `_wait_for_lifecycle_event`** (salvage #17016) ([#20209](https://github.com/NousResearch/hermes-agent/pull/20209))
+- Fix: reconnect on terminated sessions ([#19380](https://github.com/NousResearch/hermes-agent/pull/19380))
+- Fix: decouple AnyUrl import from mcp dependency ([#19695](https://github.com/NousResearch/hermes-agent/pull/19695))
+- Fix: `mcp add --command` gets distinct argparse dest ([#21204](https://github.com/NousResearch/hermes-agent/pull/21204))
+- Fix: clear stale thread interrupt before MCP discovery ([#21276](https://github.com/NousResearch/hermes-agent/pull/21276))
+- Fix: report configured timeout in MCP call errors ([#21281](https://github.com/NousResearch/hermes-agent/pull/21281))
+- Fix: include exception type in error messages when str(exc) is empty (salvage #19425) ([#21292](https://github.com/NousResearch/hermes-agent/pull/21292))
+- Fix: re-raise CancelledError explicitly in `MCPServerTask.run` ([#21318](https://github.com/NousResearch/hermes-agent/pull/21318))
+- Fix: coerce numeric tool args defensively in `mcp_serve` ([#21329](https://github.com/NousResearch/hermes-agent/pull/21329))
+- Fix: gate utility stubs on server-advertised capabilities ([#21347](https://github.com/NousResearch/hermes-agent/pull/21347))
+
+### Browser
+- Fix: allow explicit CDP override without local agent-browser ([#19670](https://github.com/NousResearch/hermes-agent/pull/19670))
+- Fix: inject `--no-sandbox` for root + AppArmor userns restrictions ([#19747](https://github.com/NousResearch/hermes-agent/pull/19747))
+- Fix: tighten Lightpanda fallback edge cases (@kshitijk4poor) ([#20672](https://github.com/NousResearch/hermes-agent/pull/20672))
+
+### Web tools
+- **Per-capability backend selection — search/extract split** (@kshitijk4poor) ([#20061](https://github.com/NousResearch/hermes-agent/pull/20061))
+- **SearXNG native search-only backend** (@kshitijk4poor) ([#20823](https://github.com/NousResearch/hermes-agent/pull/20823))
+
+### Approval / Tool gating
+- Fix: wake blocked gateway approvals on session cleanup ([#18171](https://github.com/NousResearch/hermes-agent/pull/18171))
+- Fix: harden YOLO mode env parsing against quoted-bool strings ([#18214](https://github.com/NousResearch/hermes-agent/pull/18214))
+- Fix: extend sensitive write target to cover shell RC and credential files ([#19282](https://github.com/NousResearch/hermes-agent/pull/19282))
+
+---
+
+## 🔌 Plugin System
+
+- **`transform_llm_output` plugin hook** (salvage of #20813) ([#21235](https://github.com/NousResearch/hermes-agent/pull/21235))
+- **Document `env_enablement_fn` + `cron_deliver_env_var` platform-plugin hooks** ([#21331](https://github.com/NousResearch/hermes-agent/pull/21331))
+- **Pluggable surfaces coverage — model-provider guide, full plugin map, opt-in fix** ([#20749](https://github.com/NousResearch/hermes-agent/pull/20749))
+- **Plugin-authoring gaps — image-gen provider guide + publishing a skill tap** ([#20800](https://github.com/NousResearch/hermes-agent/pull/20800))
+
+---
+
+## 🧩 Skills Ecosystem
+
+### New optional skills
+- **Shopify** — Admin + Storefront GraphQL optional skill ([#18116](https://github.com/NousResearch/hermes-agent/pull/18116))
+- **here.now** — optional skill ([#18170](https://github.com/NousResearch/hermes-agent/pull/18170))
+- **shop-app** — personal shopping assistant (optional) ([#20702](https://github.com/NousResearch/hermes-agent/pull/20702))
+- **Anthropic financial-services bundle** — ported as optional finance skills ([#21180](https://github.com/NousResearch/hermes-agent/pull/21180))
+- **kanban-video-orchestrator** — creative optional skill (@SHL0MS) ([#19281](https://github.com/NousResearch/hermes-agent/pull/19281))
+- **searxng-search** — optional skill + Web Search + Extract docs page (@kshitijk4poor) ([#20841](https://github.com/NousResearch/hermes-agent/pull/20841), [#20844](https://github.com/NousResearch/hermes-agent/pull/20844))
+
+### Skill UX
+- **Linear skill — add Documents support + Python helper script** ([#20752](https://github.com/NousResearch/hermes-agent/pull/20752))
+- **Modernize Obsidian skill to use file tools** (salvage #19332) ([#20413](https://github.com/NousResearch/hermes-agent/pull/20413))
+- **Default custom tool creation to plugins** (@kshitijk4poor) ([#19755](https://github.com/NousResearch/hermes-agent/pull/19755))
+- **skill_commands cache — rescan on platform scope changes** (salvage #14570 by @LeonSGP43) ([#18739](https://github.com/NousResearch/hermes-agent/pull/18739))
+- **Skills — additional rescan paths in skill_commands cache** (salvage #19042) ([#21181](https://github.com/NousResearch/hermes-agent/pull/21181))
+- Fix: regression tests for non-dict metadata in `extract_skill_conditions` ([#18213](https://github.com/NousResearch/hermes-agent/pull/18213))
+- Docs: explain restoring bundled skills (salvage #19254) ([#20404](https://github.com/NousResearch/hermes-agent/pull/20404))
+- Docs: document `hermes skills reset` subcommand (salvage #11544) ([#20395](https://github.com/NousResearch/hermes-agent/pull/20395))
+- Docs: himalaya v1.2.0 `folder.aliases` syntax ([#19882](https://github.com/NousResearch/hermes-agent/pull/19882))
+- Point agent at `hermes-agent` skill + docs site sync ([#20390](https://github.com/NousResearch/hermes-agent/pull/20390))
+
+---
+
+## 🖥️ CLI & User Experience
+
+### CLI
+- **`/new` accepts optional session name argument** (salvage of #19555) ([#19637](https://github.com/NousResearch/hermes-agent/pull/19637))
+- **100 new CLI startup tips** ([#20168](https://github.com/NousResearch/hermes-agent/pull/20168))
+- **`display.language` — static message translation** (zh/ja/de/es) ([#20231](https://github.com/NousResearch/hermes-agent/pull/20231))
+- **French (fr) locale** (@Foolafroos) ([#20329](https://github.com/NousResearch/hermes-agent/pull/20329))
+- **Ukrainian (uk) locale** ([#20467](https://github.com/NousResearch/hermes-agent/pull/20467))
+- **Turkish (tr) locale** ([#20474](https://github.com/NousResearch/hermes-agent/pull/20474))
+- Fix: recover classic CLI output after resize (@helix4u) ([#20444](https://github.com/NousResearch/hermes-agent/pull/20444))
+- Fix: complete absolute paths as paths (@helix4u) ([#19930](https://github.com/NousResearch/hermes-agent/pull/19930))
+- Fix: resolve lazy session creation regressions (#18370 fallout) (@alt-glitch) ([#20363](https://github.com/NousResearch/hermes-agent/pull/20363))
+- Fix: local backend CLI always uses launch directory (@alt-glitch) ([#19334](https://github.com/NousResearch/hermes-agent/pull/19334))
+- Refactor: drop dead c-S-c key binding (follow-up to #19895) ([#19919](https://github.com/NousResearch/hermes-agent/pull/19919))
+
+### TUI (Ink)
+- **`/model` picker overhaul to match `hermes model` with inline auth** (@austinpickett) ([#18117](https://github.com/NousResearch/hermes-agent/pull/18117))
+- **Collapsible sections in startup banner** — skills, system prompt, MCP (@kshitijk4poor) ([#20625](https://github.com/NousResearch/hermes-agent/pull/20625))
+- **Show context compression count in status bar** ([#21218](https://github.com/NousResearch/hermes-agent/pull/21218))
+- Perf: reduce overlay render churn with focused selectors (@OutThisLife) ([#20393](https://github.com/NousResearch/hermes-agent/pull/20393))
+- Fix: restore voice push-to-talk parity (salvage of #16189 by @Montbra) (@OutThisLife) ([#20897](https://github.com/NousResearch/hermes-agent/pull/20897))
+- Fix: kanban button (@austinpickett) ([#18358](https://github.com/NousResearch/hermes-agent/pull/18358))
+
+### Dashboard
+- **Plugins page — manage, enable/disable, auth status** (@austinpickett) ([#18095](https://github.com/NousResearch/hermes-agent/pull/18095))
+- **Profiles management page** (@vincez-hms-coder) ([#16419](https://github.com/NousResearch/hermes-agent/pull/16419))
+- **Interactive column sorting in analytics tables** ([#18192](https://github.com/NousResearch/hermes-agent/pull/18192))
+- **`default-large` built-in theme with 18px base size** ([#20820](https://github.com/NousResearch/hermes-agent/pull/20820))
+- **Support serving under URL prefix via `X-Forwarded-Prefix`** (salvage #19450) ([#21296](https://github.com/NousResearch/hermes-agent/pull/21296))
+- **Launch dashboard as side-process via `HERMES_DASHBOARD=1` in Docker** (@benbarclay) ([#19540](https://github.com/NousResearch/hermes-agent/pull/19540))
+- Fix: dashboard theme layout shift (@AllardQuek) ([#17232](https://github.com/NousResearch/hermes-agent/pull/17232))
+- Fix: gateway model picker current context (@helix4u) ([#20513](https://github.com/NousResearch/hermes-agent/pull/20513))
+
+### Update + setup
+- **`hermes update --yes/-y` to skip interactive prompts** ([#18261](https://github.com/NousResearch/hermes-agent/pull/18261))
+- **Restart manual profile gateways after update** ([#18178](https://github.com/NousResearch/hermes-agent/pull/18178))
+
+### Profiles
+- **`--no-skills` flag for empty profile creation** ([#20986](https://github.com/NousResearch/hermes-agent/pull/20986))
+
+---
+
+## 🎵 Voice, Image & Media
+
+- **xAI Custom Voices — voice cloning** (@alt-glitch) ([#18776](https://github.com/NousResearch/hermes-agent/pull/18776))
+- **Achievements — share card render on unlocked badges** ([#19657](https://github.com/NousResearch/hermes-agent/pull/19657))
+- **Refresh systemd unit on gateway boot (not just start/restart)** (@alt-glitch) ([#19684](https://github.com/NousResearch/hermes-agent/pull/19684))
+
+---
+
+## 🔗 API Server & Remote Access
+
+- **`X-Hermes-Session-Key` header for long-term memory scoping** (closes #20060) ([#20199](https://github.com/NousResearch/hermes-agent/pull/20199))
+
+---
+
+## 🧰 ACP Adapter (VS Code / Zed / JetBrains)
+
+- **`/steer` and `/queue` slash commands** (@HenkDz) ([#18114](https://github.com/NousResearch/hermes-agent/pull/18114))
+- Fix: translate Windows cwd for WSL sessions (salvage #18128) ([#18233](https://github.com/NousResearch/hermes-agent/pull/18233))
+- Fix: run `/steer` as a regular prompt on idle sessions ([#18258](https://github.com/NousResearch/hermes-agent/pull/18258))
+- Fix: route Zed thoughts to reasoning + polish tool/context rendering ([#19139](https://github.com/NousResearch/hermes-agent/pull/19139))
+- Fix: atomic session persistence via `replace_messages` (salvage #13675) ([#20279](https://github.com/NousResearch/hermes-agent/pull/20279))
+- Fix: preserve assistant reasoning metadata in session persistence (salvage #13575) ([#20296](https://github.com/NousResearch/hermes-agent/pull/20296))
+- Docs: update VS Code setup for ACP Client extension (salvage #12495) ([#20433](https://github.com/NousResearch/hermes-agent/pull/20433))
+
+---
+
+## 🐳 Docker
+
+- **Launch dashboard as side-process via `HERMES_DASHBOARD=1`** (@benbarclay) ([#19540](https://github.com/NousResearch/hermes-agent/pull/19540))
+- **Refuse root gateway runs in official image** (salvage #19215) ([#21250](https://github.com/NousResearch/hermes-agent/pull/21250))
+- **Chown runtime `node_modules` trees to hermes user** (salvage #19303) ([#21267](https://github.com/NousResearch/hermes-agent/pull/21267))
+- Fix: exclude compose/profile runtime state from build context ([#19626](https://github.com/NousResearch/hermes-agent/pull/19626))
+- CI: don't cancel overlapping builds, guard `:latest` (@ethernet8023) ([#20890](https://github.com/NousResearch/hermes-agent/pull/20890))
+- Test: align Dockerfile contract tests with simplified TUI flow (salvage #19024) ([#21174](https://github.com/NousResearch/hermes-agent/pull/21174))
+- Docs: connect to local inference servers (vLLM, Ollama) (salvage #12335) ([#20407](https://github.com/NousResearch/hermes-agent/pull/20407))
+- Docs: document `API_SERVER_*` env vars (salvage #11758) ([#20409](https://github.com/NousResearch/hermes-agent/pull/20409))
+- Docs: clarify Docker terminal backend is a single persistent container ([#20003](https://github.com/NousResearch/hermes-agent/pull/20003))
+
+---
+
+## 🐛 Notable Bug Fixes
+
+### Agent
+- Fix: recover lazy session creation regressions (#18370 fallout) (@alt-glitch) ([#20363](https://github.com/NousResearch/hermes-agent/pull/20363))
+- Fix: propagate ContextVars to concurrent tool worker threads (salvage #16660) ([#18123](https://github.com/NousResearch/hermes-agent/pull/18123))
+- Fix: warning-first tool-call loop guardrails ([#18227](https://github.com/NousResearch/hermes-agent/pull/18227))
+- Fix: surface self-improvement review summaries across CLI, TUI, and gateway ([#18073](https://github.com/NousResearch/hermes-agent/pull/18073))
+
+### Gateway streaming
+- Fix: harden StreamingConfig bool and numeric coercion (@simbam99) ([#16463](https://github.com/NousResearch/hermes-agent/pull/16463))
+
+### Model
+- Fix: avoid Bedrock credential probe in provider picker (@helix4u) ([#18998](https://github.com/NousResearch/hermes-agent/pull/18998))
+
+### Doctor
+- Fix: check global agent-browser when local install not found ([#19671](https://github.com/NousResearch/hermes-agent/pull/19671))
+- Test: kimi-coding-cn provider validation regression ([#19734](https://github.com/NousResearch/hermes-agent/pull/19734))
+
+### Update
+- Fix: patch `isatty` on real streams to fix xdist-flaky `--yes` tests (salvage #19026) ([#21175](https://github.com/NousResearch/hermes-agent/pull/21175))
+- Fix: teach restart-mocks about the post-update survivor sweep (salvage #19031) ([#21177](https://github.com/NousResearch/hermes-agent/pull/21177))
+
+### Auth
+- Fix: acp preserve assistant reasoning metadata ([#20296](https://github.com/NousResearch/hermes-agent/pull/20296))
+
+### Redact
+- Fix: add `code_file` param to skip false-positive ENV/JSON patterns ([#19715](https://github.com/NousResearch/hermes-agent/pull/19715))
+
+### Email
+- Fix: quoted-relative file-drop paths + Date header on tool email path ([#19646](https://github.com/NousResearch/hermes-agent/pull/19646))
+
+---
+
+## 🧪 Testing
+
+- **ACP — accept prompt persistence kwargs in MCP E2E mocks** (@stephenschoettler) ([#18047](https://github.com/NousResearch/hermes-agent/pull/18047))
+- **Toolsets — include kanban in expected post-#17805 toolset assertions** (@briandevans) ([#18122](https://github.com/NousResearch/hermes-agent/pull/18122))
+- **Agent — cover max-iterations summary message sanitization** ([#19580](https://github.com/NousResearch/hermes-agent/pull/19580))
+- **run_agent — `-inf` and `nan` regression coverage for `_coerce_number`** ([#19703](https://github.com/NousResearch/hermes-agent/pull/19703))
+
+---
+
+## 📚 Documentation
+
+### Major docs additions
+- **`llms.txt` + `llms-full.txt` — agent-friendly ingestion** ([#18276](https://github.com/NousResearch/hermes-agent/pull/18276))
+- **User Stories and Use Cases collage page** ([#18282](https://github.com/NousResearch/hermes-agent/pull/18282))
+- **Persistent Goals (/goal) feature page** ([#18275](https://github.com/NousResearch/hermes-agent/pull/18275))
+- **Windows (WSL2) guide expansion** — filesystem, networking, services, pitfalls ([#20748](https://github.com/NousResearch/hermes-agent/pull/20748))
+- **Chinese (zh-CN) README translation** (salvage #13508) ([#20431](https://github.com/NousResearch/hermes-agent/pull/20431))
+- **zh-Hans Docusaurus locale** + Tool Gateway / image-gen / WSL quickstart translations (salvage #11728) ([#20430](https://github.com/NousResearch/hermes-agent/pull/20430))
+- **Tool Gateway docs restructure** — lead with what it does, config moved to bottom ([#20827](https://github.com/NousResearch/hermes-agent/pull/20827))
+- **Quickstart — Onchain AI Garage Hermes tutorials playlist** ([#20192](https://github.com/NousResearch/hermes-agent/pull/20192))
+- **Open WebUI bootstrap script** (salvage #9566) ([#20427](https://github.com/NousResearch/hermes-agent/pull/20427))
+- **Local Ollama setup guide** (salvage #5842) ([#20426](https://github.com/NousResearch/hermes-agent/pull/20426))
+- **Google Gemini guide** (salvage #17450) ([#20401](https://github.com/NousResearch/hermes-agent/pull/20401))
+- **Custom model aliases for /model command** ([#20475](https://github.com/NousResearch/hermes-agent/pull/20475))
+- **Together/Groq/Perplexity cookbook via `custom_providers`** (salvage #15214) ([#20400](https://github.com/NousResearch/hermes-agent/pull/20400))
+- **Doubao speech integration examples** (TTS + STT) (salvage #18065) ([#20418](https://github.com/NousResearch/hermes-agent/pull/20418))
+- **WSL-to-Windows Chrome MCP bridge** (salvage #8313) ([#20428](https://github.com/NousResearch/hermes-agent/pull/20428))
+- **Hermes skills docs sync** — slash commands + durable-systems section ([#20390](https://github.com/NousResearch/hermes-agent/pull/20390))
+- **AGENTS.md — curator/cron/delegation/toolsets + fix plugin tree** ([#20226](https://github.com/NousResearch/hermes-agent/pull/20226))
+- **Bedrock quickstart entry + fallback comment + deployment link** (salvage #11093) ([#20397](https://github.com/NousResearch/hermes-agent/pull/20397))
+
+### Docs polish
+- Collapse exploding skills tree to a single Skills node ([#18259](https://github.com/NousResearch/hermes-agent/pull/18259))
+- Clarify `session_search` auxiliary model docs ([#19593](https://github.com/NousResearch/hermes-agent/pull/19593))
+- Open WebUI Quick Setup gap fill ([#19654](https://github.com/NousResearch/hermes-agent/pull/19654))
+- Default custom tool creation to plugins (@kshitijk4poor) ([#19755](https://github.com/NousResearch/hermes-agent/pull/19755))
+- Clarify Telegram group chat troubleshooting (salvage #18672) ([#20416](https://github.com/NousResearch/hermes-agent/pull/20416))
+- Codex OAuth auth prerequisite clarification (salvage #18688) ([#20417](https://github.com/NousResearch/hermes-agent/pull/20417))
+- Discord Server Members Intent + SSRC-mapping drift + /voice join slash Choice (salvage #11350) ([#20411](https://github.com/NousResearch/hermes-agent/pull/20411))
+- Document `ctx.dispatch_tool()` (salvage #10955) ([#20391](https://github.com/NousResearch/hermes-agent/pull/20391))
+- Document `hermes webhook subscribe --deliver-only` (salvage #12612) ([#20392](https://github.com/NousResearch/hermes-agent/pull/20392))
+- Document `hermes import` reference (salvage #14711) ([#20396](https://github.com/NousResearch/hermes-agent/pull/20396))
+- Document per-provider TTS `max_text_length` caps (salvage #13825) ([#20389](https://github.com/NousResearch/hermes-agent/pull/20389))
+- Clarify supported prompt customization surfaces (salvage #19987) ([#20383](https://github.com/NousResearch/hermes-agent/pull/20383))
+- Correct `web_extract` summarizer timeout comment (salvage #20051) ([#20381](https://github.com/NousResearch/hermes-agent/pull/20381))
+- Fix fallback provider config paths (salvage #20033) ([#20382](https://github.com/NousResearch/hermes-agent/pull/20382))
+- Fix misleading RL install-extras claim (salvage #19080) ([#21213](https://github.com/NousResearch/hermes-agent/pull/21213))
+- Clarify API server tool execution locality (salvage #19117) ([#21223](https://github.com/NousResearch/hermes-agent/pull/21223))
+- Prefer `.venv` to match AGENTS.md and scripts/run_tests.sh (@xxxigm) ([#21334](https://github.com/NousResearch/hermes-agent/pull/21334))
+- Align tool discovery + test runner with AGENTS.md (@xxxigm) ([#20791](https://github.com/NousResearch/hermes-agent/pull/20791))
+- Align terminal-backend count and naming across docs and code (salvage #19044) ([#20402](https://github.com/NousResearch/hermes-agent/pull/20402))
+- Refresh stale platform counts (salvage #19053) ([#20403](https://github.com/NousResearch/hermes-agent/pull/20403))
+
+---
+
+## 👥 Contributors
+
+### Core
+- **@teknium1** — salvage, triage, review, feature work, and release management
+
+### Top Community Contributors
+
+- **@kshitijk4poor** (21 PRs) — SearXNG native search backend, per-capability backend selection, collapsible TUI startup banner, Slack ephemeral ack + format fixes, Lightpanda fallback hardening, searxng-search optional skill + Web Search + Extract docs, default custom tool creation to plugins, kanban failure-column fix
+- **@alt-glitch** (13 PRs) — video_analyze tool, xAI Custom Voices (voice cloning), local-backend CLI launch-directory fix, lazy-session creation regression recovery, systemd unit refresh on gateway boot
+- **@OutThisLife** (9 PRs) — TUI perf — overlay render churn reduction, voice push-to-talk parity restoration (salvaging @Montbra)
+- **@helix4u** (6 PRs) — Classic CLI output recovery after resize, absolute-path TUI completion, gateway model picker current-context fix, Bedrock credential probe avoidance, kanban docs fixes
+- **@ethernet8023** (3 PRs) — Docker CI — don't cancel overlapping builds, :latest guard
+- **@benbarclay** (3 PRs) — Docker — launch dashboard as side-process via HERMES_DASHBOARD=1
+- **@austinpickett** (3 PRs) — Dashboard Plugins page, TUI /model picker overhaul with inline auth, kanban button fix
+- **@sprmn24** (2 PRs) — Contributor (2 PRs)
+- **@asheriif** (2 PRs) — Contributor (2 PRs)
+- **@xxxigm** (2 PRs) — Contributing docs — .venv preference and test runner alignment with AGENTS.md
+- **@stephenschoettler** (1 PR) — ACP — MCP E2E mock kwargs
+- **@vincez-hms-coder** (1 PR) — Dashboard — Profiles management page
+- **@cdanis** (1 PR) — Contributor
+- **@briandevans** (1 PR) — Toolsets test — kanban assertions post-#17805
+- **@heyitsaamir** (1 PR) — Contributor
+
+### All Contributors
+
+Thanks to everyone who contributed to v0.13.0 — commits, co-authored work, and salvaged PRs. 295 contributors in one week.
+
+@0oAstro, @0xDevNinja, @0xharryriddle, @0xKingBack, @0xsir0000, @0xyg3n, @0z1-ghb, @abhinav11082001-stack,
+@acc001k, @acesjohnny, @adamludwin, @adybag14-cyber, @agentlinker, @agilejava, @ai-ag2026, @AJV20,
+@alanxchen85, @albert748, @AllardQuek, @alt-glitch, @altmazza0-star, @ambition0802, @amitgaur, @amroessam,
+@andrewhosf, @Asce66, @asheriif, @ashermorse, @asimons81, @Aslaaen, @Asunfly, @atongrun, @austinpickett,
+@banditburai, @barteqpl, @Bartok9, @Beandon13, @beardthelion, @beibi9966, @benbarclay, @binhnt92, @bjianhang,
+@BlackJulySnow, @bobashopcashier, @bogerman1, @Bongulielmi, @Brecht-H, @briandevans, @brooklynnicholson,
+@c3115644151, @camaragon, @CashWilliams, @CCClelo, @cdanis, @CES4751, @cg2aigc, @changchun989, @ChanlerDev,
+@CharlieKerfoot, @chengoak, @chenyunbo411, @chinadbo, @CIRWEL, @cixuuz, @cmcgrabby-hue, @colorcross,
+@Contentment003111, @CoreyNoDream, @counterposition, @curiouscleo, @DaniuXie, @deep-name, @dengtaoyuan450-a11y,
+@discodirector, @donramon77, @dpaluy, @ee-blog, @ehz0ah, @el-analista, @elmatadorgh, @EmelyanenkoK,
+@Emidomenge, @emozilla, @Es1la, @EthanGuo-coder, @etherman-os, @ethernet8023, @EvilDrag0n, @exxmen, @Fearvox,
+@Feranmi10, @firefly, @flobo3, @fmercurio, @Foolafroos, @formulahendry, @franksong2702, @ggnnggez, @GinWU05,
+@giwaov, @glesperance, @gnanirahulnutakki, @GodsBoy, @Gosuj, @Grey0202, @guillaumemeyer, @Gutslabs, @h0tp-ftw,
+@haidao1919, @halmisen, @happy5318, @hedirman, @helix4u, @hendrixfreire, @HenkDz, @hex-clawd, @heyitsaamir,
+@hharry11, @Hinotoi-agent, @holynn-q, @hrkzogw, @Hypn0sis, @Hypnus-Yuan, @ideathinklab01-source, @IMHaoyan,
+@Interstellar-code, @ishardo, @jacdevos, @jackey8616, @JanCong, @jasonoutland, @jatingodnani, @JayGwod,
+@jethac, @JezzaHehn, @JiaDe-Wu, @jjjojoj, @jkausel-ai, @John-tip, @johnncenae, @jrusso1020, @jslizar,
+@JTroyerOvermatch, @julysir, @Junass1, @JustinUssuri, @Kailigithub, @keepcalmqqf, @kiala9, @konsisumer,
+@kowenhaoai, @Krionex, @kshitijk4poor, @kyan12, @leavrcn, @leon7609, @LeonSGP43, @leprincep35700, @lhysdl,
+@likejudy, @lisanhu, @liu-collab, @liuguangyong93, @liuhao1024, @LucianoSP, @luoyuctl, @luyao618, @M3RCUR2Y,
+@maciekczech, @Magicray1217, @magicray1217, @MaHaoHao-ch, @malaiwah, @manateelazycat, @masonjames, @megastary,
+@memosr, @MichaelWDanko, @mikeyobrien, @millerc79, @Mind-Dragon, @mioimotoai-lgtm, @misery-hl, @molvikar,
+@momowind, @Montbra, @MottledShadow, @mrbob-git, @mrcharlesiv, @mrcoferland, @ms-alan, @mwnickerson,
+@nazirulhafiy, @nftpoetrist, @nicoloboschi, @nightq, @nikolay-bratanov, @NikolayGusev-astra, @nocturnum91,
+@noOne-list, @nouseman666, @novax635, @npmisantosh, @nudiltoys-cmyk, @olisikh, @oluwadareab12, @Oxidane-bot,
+@pama0227, @pander, @pasevin, @paul-tian, @pdonizete, @perlowja, @pingchesu, @PratikRai0101, @priveperfumes,
+@probepark, @QifengKuang, @quocanh261997, @qWaitCrypto, @qxxaa, @r266-tech, @rames-jusso, @revaraver,
+@Ricardo-M-L, @rob-maron, @Roy-oss1, @rxdxxxx, @SandroHub013, @Sanjays2402, @Sertug17, @shashwatgokhe,
+@shellybotmoyer, @SHL0MS, @SimbaKingjoe, @simbam99, @simplenamebox-ops, @socrates1024, @sonic-netizen,
+@sprmn24, @steezkelly, @stephen0110, @stephenschoettler, @stevenchanin, @stevenchouai, @stormhierta,
+@subtract0, @suncokret12, @swithek, @taeng0204, @TakeshiSawaguchi, @tangyuanjc, @TheEpTic, @thelumiereguy,
+@Tkander1715, @tmdgusya, @Tranquil-Flow, @TruaShamu, @UgwujaGeorge, @valda, @vincez-hms-coder, @VinVC,
+@vominh1919, @wabrent, @WadydX, @wanazhar, @WanderWang, @warabe1122, @web-dev0521, @WideLee, @willy-scr,
+@wmagev, @WuTianyi123, @wxst, @wysie, @Wysie, @xsfX20, @xxxigm, @xyiy001, @YanzhongSu, @ygd58, @Yoimex,
+@yuehei, @Yukipukii1, @yuqianma, @YX234, @zeejaytan, @zhanggttry, @zhao0112, @zng8418, @zons-zhaozhy, @Zyproth
+
+---
+
+**Full Changelog**: [v2026.4.30...v2026.5.7](https://github.com/NousResearch/hermes-agent/compare/v2026.4.30...v2026.5.7)
@@ -17,7 +17,15 @@ import asyncio
 import logging
 import sys
 from pathlib import Path
+
 from hermes_constants import get_hermes_home
+from utf8_bootstrap import ensure_windows_utf8_mode
+
+# Ensure ACP stdio/file defaults are UTF-8 on legacy Windows builds.
+ensure_windows_utf8_mode(
+    module="acp_adapter.entry",
+    entrypoint_markers=("hermes-acp", "entry.py"),
+)


 # Methods clients send as periodic liveness probes. They are not part of the
@@ -3,13 +3,16 @@
 from __future__ import annotations

 import asyncio
+import base64
 import contextvars
 import json
 import logging
 import os
 from collections import defaultdict, deque
 from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
 from typing import Any, Deque, Optional
+from urllib.parse import unquote, urlparse

 import acp
 from acp.schema import (
@@ -18,6 +21,7 @@ from acp.schema import (
    AuthenticateResponse,
    AvailableCommand,
    AvailableCommandsUpdate,
+    BlobResourceContents,
    ClientCapabilities,
    EmbeddedResourceContentBlock,
    ForkSessionResponse,
@@ -46,6 +50,7 @@ from acp.schema import (
    SessionResumeCapabilities,
    SessionInfo,
    TextContentBlock,
+    TextResourceContents,
    UnstructuredCommandInput,
    Usage,
    UsageUpdate,
@@ -83,6 +88,272 @@ _executor = ThreadPoolExecutor(max_workers=4, thread_name_prefix="acp-agent")
 # does not expose a client-side limit, so this is a fixed cap that clients
 # paginate against using `cursor` / `next_cursor`.
 _LIST_SESSIONS_PAGE_SIZE = 50
+_MAX_ACP_RESOURCE_BYTES = 512 * 1024
+_TEXT_RESOURCE_MIME_PREFIXES = ("text/",)
+_TEXT_RESOURCE_MIME_TYPES = {
+    "application/json",
+    "application/javascript",
+    "application/typescript",
+    "application/xml",
+    "application/x-yaml",
+    "application/yaml",
+    "application/toml",
+    "application/sql",
+}
+
+
+def _resource_display_name(uri: str, name: str | None = None, title: str | None = None) -> str:
+    """Human-readable attachment name for prompt context."""
+    raw_name = (name or "").strip()
+    raw_title = (title or "").strip()
+    if raw_title and raw_name and raw_title != raw_name:
+        return f"{raw_title} ({raw_name})"
+    if raw_title:
+        return raw_title
+    if raw_name:
+        return raw_name
+    parsed = urlparse(uri)
+    candidate = parsed.path if parsed.scheme else uri
+    return Path(unquote(candidate)).name or uri or "resource"
+
+
+def _is_text_resource(mime_type: str | None) -> bool:
+    mime = (mime_type or "").split(";", 1)[0].strip().lower()
+    if not mime:
+        return False
+    return mime.startswith(_TEXT_RESOURCE_MIME_PREFIXES) or mime in _TEXT_RESOURCE_MIME_TYPES
+
+
+def _is_image_resource(mime_type: str | None) -> bool:
+    mime = (mime_type or "").split(";", 1)[0].strip().lower()
+    return mime.startswith("image/")
+
+
+def _guess_image_mime_from_path(path: Path) -> str | None:
+    suffix = path.suffix.lower()
+    return {
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".bmp": "image/bmp",
+        ".svg": "image/svg+xml",
+    }.get(suffix)
+
+
+def _image_data_url(data: bytes, mime_type: str) -> str:
+    return f"data:{mime_type};base64,{base64.b64encode(data).decode('ascii')}"
+
+
+def _path_from_file_uri(uri: str) -> Path | None:
+    """Convert local file URIs/paths from ACP clients into a readable Path.
+
+    Zed may send POSIX file URIs from Linux/WSL workspaces or Windows-ish paths
+    when launched through wsl.exe. Translate the common Windows drive form to
+    /mnt/<drive>/... so Hermes running in WSL can read it.
+    """
+    raw = (uri or "").strip()
+    if not raw:
+        return None
+
+    parsed = urlparse(raw)
+    if parsed.scheme and parsed.scheme != "file":
+        return None
+
+    if parsed.scheme == "file":
+        if parsed.netloc and parsed.netloc not in {"", "localhost"}:
+            return None
+        path_text = unquote(parsed.path or "")
+    else:
+        path_text = unquote(raw)
+
+    # file:///C:/Users/... or C:\Users\...
+    if len(path_text) >= 3 and path_text[0] == "/" and path_text[2] == ":" and path_text[1].isalpha():
+        drive = path_text[1].lower()
+        rest = path_text[3:].lstrip("/\\").replace("\\", "/")
+        return Path("/mnt") / drive / rest
+    if len(path_text) >= 2 and path_text[1] == ":" and path_text[0].isalpha():
+        drive = path_text[0].lower()
+        rest = path_text[2:].lstrip("/\\").replace("\\", "/")
+        return Path("/mnt") / drive / rest
+
+    return Path(path_text)
+
+
+def _decode_text_bytes(data: bytes, mime_type: str | None) -> str | None:
+    """Decode resource bytes if they are probably text; return None for binary."""
+    if b"\x00" in data and not _is_text_resource(mime_type):
+        return None
+    for encoding in ("utf-8-sig", "utf-8", "latin-1"):
+        try:
+            return data.decode(encoding)
+        except UnicodeDecodeError:
+            continue
+    return data.decode("utf-8", errors="replace")
+
+
+def _format_resource_text(
+    *,
+    uri: str,
+    body: str,
+    name: str | None = None,
+    title: str | None = None,
+    note: str | None = None,
+) -> str:
+    display = _resource_display_name(uri, name=name, title=title)
+    header = f"[Attached file: {display}]"
+    if note:
+        header += f" ({note})"
+    return f"{header}\nURI: {uri}\n\n{body}"
+
+
+def _resource_link_to_parts(block: ResourceContentBlock) -> list[dict[str, Any]]:
+    """Convert an ACP resource_link block to OpenAI content parts.
+
+    Returns a list of {"type": "text", ...} and/or {"type": "image_url", ...}
+    parts. Image resources produce an image_url part with a small text header
+    so the model knows which attachment it is. Non-image resources return a
+    single text part with the inlined file body (or a binary-omit note).
+    """
+    uri = str(getattr(block, "uri", "") or "").strip()
+    if not uri:
+        return []
+
+    name = str(getattr(block, "name", "") or "").strip() or None
+    title = str(getattr(block, "title", "") or "").strip() or None
+    mime_type = str(getattr(block, "mime_type", "") or "").strip() or None
+    path = _path_from_file_uri(uri)
+
+    if path is None:
+        return [{
+            "type": "text",
+            "text": _format_resource_text(
+                uri=uri,
+                name=name,
+                title=title,
+                body="[Resource link only; Hermes cannot read non-file ACP resource URIs directly.]",
+            ),
+        }]
+
+    # Image files: emit a short text header + image_url data URL so vision
+    # models can see the attachment instead of a "binary omitted" note.
+    image_mime = mime_type if _is_image_resource(mime_type) else _guess_image_mime_from_path(path)
+    if image_mime and _is_image_resource(image_mime):
+        try:
+            size = path.stat().st_size
+            if size > _MAX_ACP_RESOURCE_BYTES:
+                return [{
+                    "type": "text",
+                    "text": _format_resource_text(
+                        uri=uri,
+                        name=name,
+                        title=title,
+                        body=f"[Image too large to inline: {size} bytes, cap={_MAX_ACP_RESOURCE_BYTES}]",
+                    ),
+                }]
+            with path.open("rb") as fh:
+                data = fh.read()
+        except OSError as exc:
+            logger.warning("ACP image resource read failed: %s", uri, exc_info=True)
+            return [{
+                "type": "text",
+                "text": _format_resource_text(
+                    uri=uri,
+                    name=name,
+                    title=title,
+                    body=f"[Could not read attached image: {exc}]",
+                ),
+            }]
+        display = _resource_display_name(uri, name=name, title=title)
+        return [
+            {"type": "text", "text": f"[Attached image: {display}]\nURI: {uri}"},
+            {"type": "image_url", "image_url": {"url": _image_data_url(data, image_mime)}},
+        ]
+
+    try:
+        size = path.stat().st_size
+        read_size = min(size, _MAX_ACP_RESOURCE_BYTES)
+        with path.open("rb") as fh:
+            data = fh.read(read_size)
+        text = _decode_text_bytes(data, mime_type)
+        if text is None:
+            return [{
+                "type": "text",
+                "text": _format_resource_text(
+                    uri=uri,
+                    name=name,
+                    title=title,
+                    body=f"[Binary file omitted: {size} bytes, mime={mime_type or 'unknown'}]",
+                ),
+            }]
+        note = None
+        if size > _MAX_ACP_RESOURCE_BYTES:
+            note = f"truncated to {_MAX_ACP_RESOURCE_BYTES} of {size} bytes"
+        return [{
+            "type": "text",
+            "text": _format_resource_text(uri=uri, name=name, title=title, body=text, note=note),
+        }]
+    except OSError as exc:
+        logger.warning("ACP resource read failed: %s", uri, exc_info=True)
+        return [{
+            "type": "text",
+            "text": _format_resource_text(
+                uri=uri,
+                name=name,
+                title=title,
+                body=f"[Could not read attached file: {exc}]",
+            ),
+        }]
+
+
+def _embedded_resource_to_parts(block: EmbeddedResourceContentBlock) -> list[dict[str, Any]]:
+    resource = getattr(block, "resource", None)
+    if resource is None:
+        return []
+
+    uri = str(getattr(resource, "uri", "") or "").strip()
+    mime_type = str(getattr(resource, "mime_type", "") or "").strip() or None
+
+    if isinstance(resource, TextResourceContents):
+        return [{"type": "text", "text": _format_resource_text(uri=uri, body=resource.text)}]
+
+    if isinstance(resource, BlobResourceContents):
+        blob = resource.blob or ""
+        try:
+            data = base64.b64decode(blob, validate=True)
+        except Exception:
+            data = blob.encode("utf-8", errors="replace")
+
+        # Image blobs go through as image_url so vision models can see them.
+        if _is_image_resource(mime_type):
+            if len(data) > _MAX_ACP_RESOURCE_BYTES:
+                return [{
+                    "type": "text",
+                    "text": _format_resource_text(
+                        uri=uri,
+                        body=f"[Embedded image too large to inline: {len(data)} bytes, cap={_MAX_ACP_RESOURCE_BYTES}]",
+                    ),
+                }]
+            display = _resource_display_name(uri)
+            return [
+                {"type": "text", "text": f"[Attached image: {display}]" + (f"\nURI: {uri}" if uri else "")},
+                {"type": "image_url", "image_url": {"url": _image_data_url(data, mime_type or "image/png")}},
+            ]
+
+        text = _decode_text_bytes(data[:_MAX_ACP_RESOURCE_BYTES], mime_type)
+        if text is None:
+            body = f"[Binary embedded file omitted: {len(data)} bytes, mime={mime_type or 'unknown'}]"
+        else:
+            body = text
+            if len(data) > _MAX_ACP_RESOURCE_BYTES:
+                body += f"\n\n[Truncated to {_MAX_ACP_RESOURCE_BYTES} of {len(data)} bytes]"
+        return [{"type": "text", "text": _format_resource_text(uri=uri, body=body)}]
+
+    text = getattr(resource, "text", None)
+    if text:
+        return [{"type": "text", "text": _format_resource_text(uri=uri, body=str(text))}]
+    return []


 def _extract_text(
@@ -144,6 +415,20 @@ def _content_blocks_to_openai_user_content(
            if image_part is not None:
                parts.append(image_part)
            continue
+        if isinstance(block, ResourceContentBlock):
+            resource_parts = _resource_link_to_parts(block)
+            for part in resource_parts:
+                parts.append(part)
+                if part.get("type") == "text":
+                    text_parts.append(part["text"])
+            continue
+        if isinstance(block, EmbeddedResourceContentBlock):
+            resource_parts = _embedded_resource_to_parts(block)
+            for part in resource_parts:
+                parts.append(part)
+                if part.get("type") == "text":
+                    text_parts.append(part["text"])
+            continue

    if not parts:
        return _extract_text(prompt)
@@ -803,6 +1088,7 @@ class HermesACPAgent(acp.Agent):

        user_text = _extract_text(prompt).strip()
        user_content = _content_blocks_to_openai_user_content(prompt)
+        text_only_prompt = all(isinstance(block, TextContentBlock) for block in prompt)
        has_content = bool(user_text) or (
            isinstance(user_content, list) and bool(user_content)
        )
@@ -821,7 +1107,7 @@ class HermesACPAgent(acp.Agent):
        #      silently append to state.queued_prompts and respond with
        #      "No active turn — queued for the next turn", which looks like
        #      /queue even though the user never typed /queue.
-        if isinstance(user_content, str) and user_text.startswith("/steer"):
+        if text_only_prompt and isinstance(user_content, str) and user_text.startswith("/steer"):
            steer_text = user_text.split(maxsplit=1)[1].strip() if len(user_text.split(maxsplit=1)) > 1 else ""
            interrupted_prompt = ""
            rewrite_idle = False
@@ -846,7 +1132,7 @@ class HermesACPAgent(acp.Agent):
        # Slash commands are text-only; if the client included images/resources,
        # send the whole multimodal prompt to the agent instead of treating it as
        # an ACP command.
-        if isinstance(user_content, str) and user_text.startswith("/"):
+        if text_only_prompt and isinstance(user_content, str) and user_text.startswith("/"):
            response_text = self._handle_slash_command(user_text, state)
            if response_text is not None:
                if self._conn:
@@ -231,33 +231,30 @@ def _supports_fast_mode(model: str) -> bool:
    return any(v in model for v in _FAST_MODE_SUPPORTED_SUBSTRINGS)


-# Beta headers for enhanced features (sent with ALL auth types).
-# As of Opus 4.7 (2026-04-16), the first two are GA on Claude 4.6+ — the
+# Beta headers for enhanced features that are safe on ordinary/native Anthropic
+# requests. As of Opus 4.7 (2026-04-16), these are GA on Claude 4.6+ — the
 # beta headers are still accepted (harmless no-op) but not required. Kept
-# here so older Claude (4.5, 4.1) + third-party Anthropic-compat endpoints
-# that still gate on the headers continue to get the enhanced features.
+# here so older Claude (4.5, 4.1) + compatible endpoints that still gate on
+# the headers continue to get the enhanced features.
 #
-# ``context-1m-2025-08-07`` unlocks the 1M context window on Claude Opus 4.6/4.7
-# and Sonnet 4.6 when served via AWS Bedrock or Azure AI Foundry. 1M is GA on
-# native Anthropic (api.anthropic.com) for Opus 4.6+, but Bedrock/Azure still
-# gate it behind this beta header as of 2026-04 — without it Bedrock caps Opus
-# at 200K even though model_metadata.py advertises 1M. The header is a harmless
-# no-op on endpoints where 1M is GA.
+# Do NOT include ``context-1m-2025-08-07`` here. Anthropic returns HTTP 400
+# ("long context beta is not yet available for this subscription") for
+# accounts without the long-context beta, which breaks normal short auxiliary
+# calls like title generation/session summarization.
 #
-# Migration guide: remove these if you no longer support ≤4.5 models or once
-# Bedrock/Azure promote 1M to GA.
+# ``context-1m-2025-08-07`` is still required to unlock the 1M context window
+# on Claude Opus 4.6/4.7 and Sonnet 4.6 when served via AWS Bedrock or Azure
+# AI Foundry. Add it only for those endpoint-specific paths below.
 _COMMON_BETAS = [
    "interleaved-thinking-2025-05-14",
    "fine-grained-tool-streaming-2025-05-14",
-    "context-1m-2025-08-07",
 ]
 # MiniMax's Anthropic-compatible endpoints fail tool-use requests when
 # the fine-grained tool streaming beta is present.  Omit it so tool calls
 # fall back to the provider's default response path.
 _TOOL_STREAMING_BETA = "fine-grained-tool-streaming-2025-05-14"
-# 1M context beta — see comment on _COMMON_BETAS above. Stripped for
-# Bearer-auth (MiniMax) endpoints since they host their own models and
-# unknown Anthropic beta headers risk request rejection.
+# 1M context beta. Native Anthropic does not get this by default because some
+# subscriptions reject it, but Bedrock/Azure still need it for 1M context.
 _CONTEXT_1M_BETA = "context-1m-2025-08-07"

 # Fast mode beta — enables the ``speed: "fast"`` request parameter for
@@ -476,6 +473,14 @@ def _requires_bearer_auth(base_url: str | None) -> bool:
    return normalized.startswith(("https://api.minimax.io/anthropic", "https://api.minimaxi.com/anthropic"))


+def _base_url_needs_context_1m_beta(base_url: str | None) -> bool:
+    """Return True for endpoints that still gate 1M context behind a beta."""
+    normalized = _normalize_base_url_text(base_url).lower()
+    if not normalized:
+        return False
+    return "azure.com" in normalized
+
+
 def _common_betas_for_base_url(
    base_url: str | None,
    *,
@@ -485,27 +490,25 @@ def _common_betas_for_base_url(

    MiniMax's Anthropic-compatible endpoints (Bearer-auth) reject requests
    that include Anthropic's ``fine-grained-tool-streaming`` beta — every
-    tool-use message triggers a connection error.  Strip that beta for
-    Bearer-auth endpoints while keeping all other betas intact.
+    tool-use message triggers a connection error.

-    The ``context-1m-2025-08-07`` beta is also stripped for Bearer-auth
-    endpoints — MiniMax hosts its own models, not Claude, so the header is
-    irrelevant at best and risks request rejection at worst.
+    The ``context-1m-2025-08-07`` beta is not sent to native Anthropic by
+    default because some subscriptions reject it. Add it only for endpoint
+    families that still require it for 1M context, currently Azure AI Foundry.
+    Bedrock uses its own client helper below and opts in explicitly.

-    ``drop_context_1m_beta=True`` additionally strips the 1M-context beta on
-    otherwise-unrelated endpoints. The OAuth retry path flips this flag after
-    a subscription rejects the beta with
-    "The long context beta is not yet available for this subscription" so
-    subsequent requests in the same session don't repeat the probe. See the
-    reactive recovery loop in ``run_agent.py`` and issue-comment history on
-    PR #17680 for the full rationale.
+    ``drop_context_1m_beta=True`` strips the 1M-context beta from any path that
+    would otherwise include it after a subscription/endpoint rejects the beta.
    """
+    betas = list(_COMMON_BETAS)
+    if _base_url_needs_context_1m_beta(base_url) and not drop_context_1m_beta:
+        betas.append(_CONTEXT_1M_BETA)
    if _requires_bearer_auth(base_url):
        _stripped = {_TOOL_STREAMING_BETA, _CONTEXT_1M_BETA}
-        return [b for b in _COMMON_BETAS if b not in _stripped]
+        return [b for b in betas if b not in _stripped]
    if drop_context_1m_beta:
-        return [b for b in _COMMON_BETAS if b != _CONTEXT_1M_BETA]
-    return _COMMON_BETAS
+        return [b for b in betas if b != _CONTEXT_1M_BETA]
+    return betas


 def build_anthropic_client(
@@ -642,7 +645,7 @@ def build_anthropic_bedrock_client(region: str):
    return _anthropic_sdk.AnthropicBedrock(
        aws_region=region,
        timeout=Timeout(timeout=900.0, connect=10.0),
-        default_headers={"anthropic-beta": ",".join(_COMMON_BETAS)},
+        default_headers={"anthropic-beta": ",".join([*_COMMON_BETAS, _CONTEXT_1M_BETA])},
    )


@@ -455,6 +455,12 @@ def _to_openai_base_url(base_url: str) -> str:
    """
    url = str(base_url or "").strip().rstrip("/")
    if url.endswith("/anthropic"):
+        # ZAI (open.bigmodel.cn) uses /api/anthropic for Anthropic wire
+        # but /api/paas/v4 for OpenAI wire — the generic /v1 rewrite is wrong.
+        if "open.bigmodel.cn" in url or "bigmodel" in url:
+            rewritten = url[: -len("/anthropic")] + "/paas/v4"
+            logger.debug("Auxiliary client: rewrote ZAI base URL %s → %s", url, rewritten)
+            return rewritten
        rewritten = url[: -len("/anthropic")] + "/v1"
        logger.debug("Auxiliary client: rewrote base URL %s → %s", url, rewritten)
        return rewritten
@@ -596,6 +602,14 @@ class _CodexCompletionsAdapter:
            "store": False,
        }

+        # Preserve the chat.completions timeout contract. This adapter is used
+        # by auxiliary calls such as context compression; if the timeout is not
+        # forwarded and enforced, a Codex Responses stream can sit behind a
+        # dead-looking CLI until the user force-interrupts the whole session.
+        timeout = kwargs.get("timeout")
+        if timeout is not None:
+            resp_kwargs["timeout"] = timeout
+
        # Note: the Codex endpoint (chatgpt.com/backend-api/codex) does NOT
        # support max_output_tokens or temperature — omit to avoid 400 errors.

@@ -653,6 +667,37 @@ class _CodexCompletionsAdapter:
        text_parts: List[str] = []
        tool_calls_raw: List[Any] = []
        usage = None
+        total_timeout = timeout if isinstance(timeout, (int, float)) and timeout > 0 else None
+        deadline = time.monotonic() + float(total_timeout) if total_timeout else None
+        timed_out = threading.Event()
+        timeout_timer: Optional[threading.Timer] = None
+
+        def _timeout_message() -> str:
+            return f"Codex auxiliary Responses stream exceeded {float(total_timeout):.1f}s total timeout"
+
+        def _close_client_on_timeout() -> None:
+            timed_out.set()
+            close = getattr(self._client, "close", None)
+            if callable(close):
+                try:
+                    close()
+                except Exception:
+                    logger.debug("Codex auxiliary: client close during timeout failed", exc_info=True)
+
+        def _check_cancelled() -> None:
+            if deadline is not None and time.monotonic() >= deadline:
+                timed_out.set()
+                raise TimeoutError(_timeout_message())
+            try:
+                from tools.interrupt import is_interrupted
+                if is_interrupted():
+                    raise InterruptedError("Codex auxiliary Responses stream interrupted")
+            except InterruptedError:
+                raise
+            except Exception:
+                # Interrupt state is a best-effort UX hook; never make it a
+                # new failure mode for auxiliary calls.
+                pass

        try:
            # Collect output items and text deltas during streaming —
@@ -661,8 +706,14 @@ class _CodexCompletionsAdapter:
            collected_output_items: List[Any] = []
            collected_text_deltas: List[str] = []
            has_function_calls = False
+            if total_timeout:
+                timeout_timer = threading.Timer(float(total_timeout), _close_client_on_timeout)
+                timeout_timer.daemon = True
+                timeout_timer.start()
+            _check_cancelled()
            with self._client.responses.stream(**resp_kwargs) as stream:
                for _event in stream:
+                    _check_cancelled()
                    _etype = getattr(_event, "type", "")
                    if _etype == "response.output_item.done":
                        _done = getattr(_event, "item", None)
@@ -674,6 +725,7 @@ class _CodexCompletionsAdapter:
                            collected_text_deltas.append(_delta)
                    elif "function_call" in _etype:
                        has_function_calls = True
+                _check_cancelled()
                final = stream.get_final_response()

            # Backfill empty output from collected stream events
@@ -733,8 +785,13 @@ class _CodexCompletionsAdapter:
                    total_tokens=getattr(resp_usage, "total_tokens", 0),
                )
        except Exception as exc:
+            if timed_out.is_set():
+                raise TimeoutError(_timeout_message()) from exc
            logger.debug("Codex auxiliary Responses API call failed: %s", exc)
            raise
+        finally:
+            if timeout_timer is not None:
+                timeout_timer.cancel()

        content = "".join(text_parts).strip() or None

@@ -828,7 +885,14 @@ class _AnthropicCompletionsAdapter:
        model = kwargs.get("model", self._model)
        tools = kwargs.get("tools")
        tool_choice = kwargs.get("tool_choice")
-        max_tokens = kwargs.get("max_tokens") or kwargs.get("max_completion_tokens") or 2000
+        # ZAI's Anthropic-compatible endpoint rejects max_tokens on vision
+        # models (glm-4v-flash etc.) with error code 1210.  When the caller
+        # signals this by setting _skip_zai_max_tokens in kwargs, omit it.
+        _skip_mt = kwargs.pop("_skip_zai_max_tokens", False)
+        if _skip_mt:
+            max_tokens = None
+        else:
+            max_tokens = kwargs.get("max_tokens") or kwargs.get("max_completion_tokens") or 2000
        temperature = kwargs.get("temperature")

        normalized_tool_choice = None
@@ -2835,6 +2899,33 @@ def resolve_vision_provider_client(
        )
        return _finalize(requested, sync_client, default_model)

+    # ZAI vision models must use the OpenAI-compatible endpoint, not the
+    # Anthropic-compatible one (which may be the main-runtime default).
+    # The Anthropic wire rejects max_tokens on multimodal calls (error 1210),
+    # while the OpenAI wire handles it correctly.
+    if requested == "zai" and not resolved_base_url:
+        zai_openai_urls = [
+            "https://open.bigmodel.cn/api/paas/v4",
+            "https://api.z.ai/api/paas/v4",
+        ]
+        for _zai_url in zai_openai_urls:
+            client, final_model = _get_cached_client(
+                requested, resolved_model, async_mode,
+                base_url=_zai_url,
+                api_key=resolved_api_key or None,
+                api_mode="chat_completions",
+                is_vision=True,
+            )
+            if client is not None:
+                return _finalize(requested, client, final_model)
+        # Fallback: try without explicit base_url (old behavior)
+        client, final_model = _get_cached_client(requested, resolved_model, async_mode,
+                                                 api_mode=resolved_api_mode,
+                                                 is_vision=True)
+        if client is None:
+            return requested, None, None
+        return requested, client, final_model
+
    client, final_model = _get_cached_client(requested, resolved_model, async_mode,
                                             api_mode=resolved_api_mode,
                                             is_vision=True)
@@ -2862,10 +2953,11 @@ def auxiliary_max_tokens_param(value: int) -> dict:
    """
    custom_base = _current_custom_base_url()
    or_key = os.getenv("OPENROUTER_API_KEY")
-    # Only use max_completion_tokens for direct OpenAI custom endpoints
+    # Use max_completion_tokens for direct OpenAI-compatible providers that reject
+    # max_tokens on newer GPT-4o/o-series/GPT-5-style models.
    if (not or_key
            and _read_nous_auth() is None
-            and base_url_hostname(custom_base) == "api.openai.com"):
+            and base_url_hostname(custom_base) in {"api.openai.com", "api.githubcopilot.com"}):
        return {"max_completion_tokens": value}
    return {"max_tokens": value}

@@ -3393,7 +3485,16 @@ def _build_call_kwargs(
    if max_tokens is not None:
        # Codex adapter handles max_tokens internally; OpenRouter/Nous use max_tokens.
        # Direct OpenAI api.openai.com with newer models needs max_completion_tokens.
-        if provider == "custom":
+        # ZAI vision models (glm-4v-flash, glm-4v-plus, etc.) reject max_tokens with
+        # error code 1210 ("API 调用参数有误") on multimodal requests — skip it.
+        _model_lower = (model or "").lower()
+        _skip_max_tokens = (
+            provider == "zai"
+            and ("4v" in _model_lower or "5v" in _model_lower or "-v" in _model_lower)
+        )
+        if _skip_max_tokens:
+            pass  # ZAI vision models do not accept max_tokens
+        elif provider == "custom":
            custom_base = base_url or _current_custom_base_url()
            if base_url_hostname(custom_base) == "api.openai.com":
                kwargs["max_completion_tokens"] = max_tokens
@@ -3624,13 +3725,23 @@ def call_llm(
                kwargs = retry_kwargs

        err_str = str(first_err)
+        # ZAI vision models (glm-4v-flash etc.) return error code 1210
+        # ("API 调用参数有误") when max_tokens is passed on multimodal
+        # calls.  The error message does NOT contain "max_tokens" so the
+        # generic retry below never fires.  Detect the ZAI-specific error
+        # and strip max_tokens before retrying.
+        _is_zai_param_error = (
+            "1210" in err_str
+            and "bigmodel" in str(getattr(client, "base_url", ""))
+        )
        if max_tokens is not None and (
            "max_tokens" in err_str
            or "unsupported_parameter" in err_str
            or _is_unsupported_parameter_error(first_err, "max_tokens")
+            or _is_zai_param_error
        ):
            kwargs.pop("max_tokens", None)
-            kwargs["max_completion_tokens"] = max_tokens
+            kwargs.pop("max_completion_tokens", None)
            try:
                return _validate_llm_response(
                    client.chat.completions.create(**kwargs), task)
@@ -3930,13 +4041,23 @@ async def async_call_llm(
                kwargs = retry_kwargs

        err_str = str(first_err)
+        # ZAI vision models (glm-4v-flash etc.) return error code 1210
+        # ("API 调用参数有误") when max_tokens is passed on multimodal
+        # calls.  The error message does NOT contain "max_tokens" so the
+        # generic retry below never fires.  Detect the ZAI-specific error
+        # and strip max_tokens before retrying.
+        _is_zai_param_error = (
+            "1210" in err_str
+            and "bigmodel" in str(getattr(client, "base_url", ""))
+        )
        if max_tokens is not None and (
            "max_tokens" in err_str
            or "unsupported_parameter" in err_str
            or _is_unsupported_parameter_error(first_err, "max_tokens")
+            or _is_zai_param_error
        ):
            kwargs.pop("max_tokens", None)
-            kwargs["max_completion_tokens"] = max_tokens
+            kwargs.pop("max_completion_tokens", None)
            try:
                return _validate_llm_response(
                    await client.chat.completions.create(**kwargs), task)
@@ -631,11 +631,18 @@ def normalize_converse_response(response: Dict) -> SimpleNamespace:
    stop_reason = response.get("stopReason", "end_turn")

    text_parts = []
+    reasoning_parts = []
    tool_calls = []

    for block in content_blocks:
        if "text" in block:
            text_parts.append(block["text"])
+        elif "reasoningContent" in block:
+            reasoning = block["reasoningContent"]
+            if isinstance(reasoning, dict):
+                thinking_text = reasoning.get("text", "")
+                if thinking_text:
+                    reasoning_parts.append(str(thinking_text))
        elif "toolUse" in block:
            tu = block["toolUse"]
            tool_calls.append(SimpleNamespace(
@@ -652,6 +659,7 @@ def normalize_converse_response(response: Dict) -> SimpleNamespace:
        role="assistant",
        content="\n".join(text_parts) if text_parts else None,
        tool_calls=tool_calls if tool_calls else None,
+        reasoning_content="\n\n".join(reasoning_parts) if reasoning_parts else None,
    )

    # Build usage stats
@@ -732,6 +740,7 @@ def stream_converse_with_callbacks(
        ``normalize_converse_response()``.
    """
    text_parts: List[str] = []
+    reasoning_parts: List[str] = []
    tool_calls: List[SimpleNamespace] = []
    current_tool: Optional[Dict] = None
    current_text_buffer: List[str] = []
@@ -777,8 +786,10 @@ def stream_converse_with_callbacks(
                reasoning = delta["reasoningContent"]
                if isinstance(reasoning, dict):
                    thinking_text = reasoning.get("text", "")
-                    if thinking_text and on_reasoning_delta:
-                        on_reasoning_delta(thinking_text)
+                    if thinking_text:
+                        reasoning_parts.append(str(thinking_text))
+                        if on_reasoning_delta:
+                            on_reasoning_delta(thinking_text)

        elif "contentBlockStop" in event:
            if current_tool is not None:
@@ -817,6 +828,7 @@ def stream_converse_with_callbacks(
        role="assistant",
        content="\n".join(text_parts) if text_parts else None,
        tool_calls=tool_calls if tool_calls else None,
+        reasoning_content="\n\n".join(reasoning_parts) if reasoning_parts else None,
    )

    usage = SimpleNamespace(
@@ -6,8 +6,7 @@ protecting head and tail context.

 Improvements over v2:
  - Structured summary template with Resolved/Pending question tracking
-  - Summarizer preamble: "Do not respond to any questions" (from OpenCode)
-  - Handoff framing: "different assistant" (from Codex) to create separation
+  - Filter-safe summarizer preamble that treats prior turns as source material
  - "Remaining Work" replaces "Next Steps" to avoid reading as active instructions
  - Clear separator when summary merges into tail message
  - Iterative summary updates (preserves info across multiple compactions)
@@ -755,15 +754,14 @@ class ContextCompressor(ContextEngine):
        content_to_summarize = self._serialize_for_summary(turns_to_summarize)

        # Preamble shared by both first-compaction and iterative-update prompts.
-        # Inspired by OpenCode's "do not respond to any questions" instruction
-        # and Codex's "another language model" framing.
+        # Keep the wording deliberately plain: Azure/OpenAI-compatible content
+        # filters have flagged stronger "injection" / "do not respond" framing.
        _summarizer_preamble = (
            "You are a summarization agent creating a context checkpoint. "
-            "Your output will be injected as reference material for a DIFFERENT "
-            "assistant that continues the conversation. "
-            "Do NOT respond to any questions or requests in the conversation — "
-            "only output the structured summary. "
-            "Do NOT include any preamble, greeting, or prefix. "
+            "Treat the conversation turns below as source material for a "
+            "compact record of prior work. "
+            "Produce only the structured summary; do not add a greeting, "
+            "preamble, or prefix. "
            "Write the summary in the same language the user was using in the "
            "conversation — do not translate or switch to English. "
            "NEVER include API keys, tokens, passwords, secrets, credentials, "
@@ -777,7 +775,7 @@ class ContextCompressor(ContextEngine):
 [THE SINGLE MOST IMPORTANT FIELD. Copy the user's most recent request or
 task assignment verbatim — the exact words they used. If multiple tasks
 were requested and only some are done, list only the ones NOT yet completed.
-The next assistant must pick up exactly here. Example:
+Continuation should pick up exactly here. Example:
 "User asked: 'Now refactor the auth module to use JWT instead of sessions'"
 If no outstanding task exists, write "None."]

@@ -814,7 +812,7 @@ Be specific with file paths, commands, line numbers, and results.]
 [Important technical decisions and WHY they were made]

 ## Resolved Questions
-[Questions the user asked that were ALREADY answered — include the answer so the next assistant does not re-answer them]
+[Questions the user asked that were ALREADY answered — include the answer so it is not repeated]

 ## Pending User Asks
 [Questions or requests from the user that have NOT yet been answered or fulfilled. If none, write "None."]
@@ -851,7 +849,7 @@ Update the summary using this exact structure. PRESERVE all existing information
            # First compaction: summarize from scratch
            prompt = f"""{_summarizer_preamble}

-Create a structured handoff summary for a different assistant that will continue this conversation after earlier turns are compacted. The next assistant should be able to understand what happened without re-reading the original turns.
+Create a structured checkpoint summary for the conversation after earlier turns are compacted. The summary should preserve enough detail for continuity without re-reading the original turns.

 TURNS TO SUMMARIZE:
 {content_to_summarize}
@@ -477,8 +477,8 @@ class CopilotACPClient:
            proc.stdin.write(json.dumps(payload) + "\n")
            proc.stdin.flush()

-            deadline = time.time() + timeout_seconds
-            while time.time() < deadline:
+            deadline = time.monotonic() + timeout_seconds
+            while time.monotonic() < deadline:
                if proc.poll() is not None:
                    break
                try:
@@ -68,8 +68,10 @@ SUPPORTED_POOL_STRATEGIES = {
 }

 # Cooldown before retrying an exhausted credential.
-# 429 (rate-limited) and 402 (billing/quota) both cool down after 1 hour.
+# Transient 401 auth failures cool down briefly so single-key setups can recover.
+# 429 (rate-limited), 402 (billing/quota), and other failures cool down after 1 hour.
 # Provider-supplied reset_at timestamps override these defaults.
+EXHAUSTED_TTL_401_SECONDS = 5 * 60           # 5 minutes
 EXHAUSTED_TTL_429_SECONDS = 60 * 60          # 1 hour
 EXHAUSTED_TTL_DEFAULT_SECONDS = 60 * 60      # 1 hour

@@ -190,6 +192,8 @@ def _is_manual_source(source: str) -> bool:

 def _exhausted_ttl(error_code: Optional[int]) -> int:
    """Return cooldown seconds based on the HTTP status that caused exhaustion."""
+    if error_code == 401:
+        return EXHAUSTED_TTL_401_SECONDS
    if error_code == 429:
        return EXHAUSTED_TTL_429_SECONDS
    return EXHAUSTED_TTL_DEFAULT_SECONDS
@@ -305,14 +309,29 @@ def _iter_custom_providers(config: Optional[dict] = None):
        yield _normalize_custom_pool_name(name), entry


-def get_custom_provider_pool_key(base_url: str) -> Optional[str]:
+def get_custom_provider_pool_key(base_url: str, provider_name: Optional[str] = None) -> Optional[str]:
    """Look up the custom_providers list in config.yaml and return 'custom:<name>' for a matching base_url.

+    When provider_name is given, prefer matching by name first (solving the case where
+    multiple custom providers share the same base_url but have different API keys).
+    Falls back to base_url matching when no name match is found.
+
    Returns None if no match is found.
    """
    if not base_url:
        return None
    normalized_url = base_url.strip().rstrip("/")
+
+    # When a provider name is given, try to match by name first.
+    # This fixes the P1 bug where two custom providers sharing the same
+    # base_url always resolve to the first one's credentials.
+    if provider_name:
+        normalized_name = _normalize_custom_pool_name(provider_name)
+        for norm_name, entry in _iter_custom_providers():
+            if norm_name == normalized_name:
+                return f"{CUSTOM_POOL_PREFIX}{norm_name}"
+
+    # Fall back to base_url matching (original behavior)
    for norm_name, entry in _iter_custom_providers():
        entry_url = str(entry.get("base_url") or "").strip().rstrip("/")
        if entry_url and entry_url == normalized_url:
@@ -852,13 +852,15 @@ def get_cute_tool_message(
        s = str(s)
        if _tool_preview_max_len == 0:
            return s  # no limit
-        return (s[:n-3] + "...") if len(s) > n else s
+        limit = _tool_preview_max_len
+        return (s[:limit-3] + "...") if len(s) > limit else s

    def _path(p, n=35):
        p = str(p)
        if _tool_preview_max_len == 0:
            return p  # no limit
-        return ("..." + p[-(n-3):]) if len(p) > n else p
+        limit = _tool_preview_max_len
+        return ("..." + p[-(limit-3):]) if len(p) > limit else p

    def _wrap(line: str) -> str:
        """Apply skin tool prefix and failure suffix."""
@@ -144,7 +144,51 @@ def decide_image_input_mode(
 # it fires, which is cheaper than permanent quality loss.


-def _guess_mime(path: Path) -> str:
+def _sniff_mime_from_bytes(raw: bytes) -> Optional[str]:
+    """Detect image MIME from magic bytes. Returns None if unrecognised.
+
+    Filename-based detection (``mimetypes.guess_type``) is unreliable when
+    upstream platforms lie about content-type. Discord, for example, can
+    serve a PNG with ``content_type=image/webp`` for proxied/animated
+    stickers, custom emoji previews, or images uploaded via certain bots.
+    Anthropic strictly validates that declared media_type matches the
+    actual bytes and returns HTTP 400 on mismatch, so we sniff to be safe.
+    """
+    if not raw:
+        return None
+    # PNG: 89 50 4E 47 0D 0A 1A 0A
+    if raw.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    # JPEG: FF D8 FF
+    if raw.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    # GIF87a / GIF89a
+    if raw[:6] in (b"GIF87a", b"GIF89a"):
+        return "image/gif"
+    # WEBP: "RIFF" .... "WEBP"
+    if len(raw) >= 12 and raw[:4] == b"RIFF" and raw[8:12] == b"WEBP":
+        return "image/webp"
+    # BMP: "BM"
+    if raw.startswith(b"BM"):
+        return "image/bmp"
+    # HEIC/HEIF: ftypheic / ftypheix / ftypmif1 / ftypmsf1 etc.
+    if len(raw) >= 12 and raw[4:8] == b"ftyp" and raw[8:12] in (
+        b"heic", b"heix", b"hevc", b"hevx", b"mif1", b"msf1", b"heim", b"heis",
+    ):
+        return "image/heic"
+    return None
+
+
+def _guess_mime(path: Path, raw: Optional[bytes] = None) -> str:
+    """Return image MIME type for *path*.
+
+    If *raw* bytes are provided, magic-byte sniffing wins (authoritative).
+    Otherwise we fall back to ``mimetypes`` then suffix-based defaults.
+    """
+    if raw is not None:
+        sniffed = _sniff_mime_from_bytes(raw)
+        if sniffed:
+            return sniffed
    mime, _ = mimetypes.guess_type(str(path))
    if mime and mime.startswith("image/"):
        return mime
@@ -178,7 +222,7 @@ def _file_to_data_url(path: Path) -> Optional[str]:
    except Exception as exc:
        logger.warning("image_routing: failed to read %s — %s", path, exc)
        return None
-    mime = _guess_mime(path)
+    mime = _guess_mime(path, raw=raw)
    b64 = base64.b64encode(raw).decode("ascii")
    return f"data:{mime};base64,{b64}"

@@ -190,24 +234,30 @@ def build_native_content_parts(
    """Build an OpenAI-style ``content`` list for a user turn.

    Shape:
-      [{"type": "text", "text": "..."},
+      [{"type": "text", "text": "...\\n\\n[Image attached at: /local/path]"},
       {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}},
       ...]

+    The local path of each successfully attached image is appended to the
+    text part as ``[Image attached at: <path>]``. The model still sees the
+    pixels via the ``image_url`` part (full native vision); the path note
+    just gives it a string handle so MCP/skill tools that take an image
+    path or URL argument can be invoked on the same image without an
+    extra round-trip. This parallels the text-mode hint produced by
+    ``Runner._enrich_message_with_vision`` (``vision_analyze using image_url:
+    <path>``) so behaviour is consistent across both image input modes.
+
    Images are attached at their native size. If a provider rejects the
    request because an image is too large (e.g. Anthropic's 5 MB per-image
    ceiling), the agent's retry loop transparently shrinks and retries
    once — see ``run_agent._try_shrink_image_parts_in_messages``.

    Returns (content_parts, skipped_paths). Skipped paths are files that
-    couldn't be read from disk.
+    couldn't be read from disk and are NOT advertised in the path hints.
    """
-    parts: List[Dict[str, Any]] = []
    skipped: List[str] = []
-
-    text = (user_text or "").strip()
-    if text:
-        parts.append({"type": "text", "text": text})
+    image_parts: List[Dict[str, Any]] = []
+    attached_paths: List[str] = []

    for raw_path in image_paths:
        p = Path(raw_path)
@@ -218,15 +268,30 @@ def build_native_content_parts(
        if not data_url:
            skipped.append(str(raw_path))
            continue
-        parts.append({
+        image_parts.append({
            "type": "image_url",
            "image_url": {"url": data_url},
        })
+        attached_paths.append(str(raw_path))

-    # If the text was empty, add a neutral prompt so the turn isn't just images.
-    if not text and any(p.get("type") == "image_url" for p in parts):
-        parts.insert(0, {"type": "text", "text": "What do you see in this image?"})
+    text = (user_text or "").strip()

+    # If at least one image attached, build a single text part that combines
+    # the user's caption (or a neutral default) with one path hint per image.
+    if attached_paths:
+        base_text = text or "What do you see in this image?"
+        path_hints = "\n".join(
+            f"[Image attached at: {p}]" for p in attached_paths
+        )
+        combined_text = f"{base_text}\n\n{path_hints}"
+        parts: List[Dict[str, Any]] = [{"type": "text", "text": combined_text}]
+        parts.extend(image_parts)
+        return parts, skipped
+
+    # No images successfully attached — fall back to plain text-only behaviour.
+    parts = []
+    if text:
+        parts.append({"type": "text", "text": text})
    return parts, skipped


@@ -381,14 +381,18 @@ def get_model_capabilities(provider: str, model: str) -> Optional[ModelCapabilit

    # Extract capability flags (default to False if missing)
    supports_tools = bool(entry.get("tool_call", False))
-    # Vision: check both the `attachment` flag and `modalities.input` for "image".
-    # Some models (e.g. gemma-4) list image in input modalities but not attachment.
+    # Vision: prefer explicit `modalities.input` when models.dev provides it.
+    # The older `attachment` flag can be stale or too broad for image routing;
+    # fall back to it only when the input modalities are absent/invalid.
    input_mods = entry.get("modalities", {})
    if isinstance(input_mods, dict):
-        input_mods = input_mods.get("input", [])
+        input_mods = input_mods.get("input")
    else:
-        input_mods = []
-    supports_vision = bool(entry.get("attachment", False)) or "image" in input_mods
+        input_mods = None
+    if isinstance(input_mods, list):
+        supports_vision = "image" in input_mods
+    else:
+        supports_vision = bool(entry.get("attachment", False))
    supports_reasoning = bool(entry.get("reasoning", False))

    # Extract limits
@@ -56,12 +56,15 @@ _SENSITIVE_BODY_KEYS = frozenset({
 })

 # Snapshot at import time so runtime env mutations (e.g. LLM-generated
-# `export HERMES_REDACT_SECRETS=true`) cannot enable/disable redaction
-# mid-session.  OFF by default — user must opt in via
-# `security.redact_secrets: true` in config.yaml (bridged to this env var
-# in hermes_cli/main.py and gateway/run.py) or `HERMES_REDACT_SECRETS=true`
-# in ~/.hermes/.env.
-_REDACT_ENABLED = os.getenv("HERMES_REDACT_SECRETS", "").lower() in ("1", "true", "yes", "on")
+# `export HERMES_REDACT_SECRETS=false`) cannot disable redaction
+# mid-session.  ON by default — secure default per issue #17691. Users who
+# need raw credential values in tool output (e.g. working on the redactor
+# itself) can opt out via `security.redact_secrets: false` in config.yaml
+# (bridged to this env var in hermes_cli/main.py, gateway/run.py, and
+# cli.py) or `HERMES_REDACT_SECRETS=false` in ~/.hermes/.env. An opt-out
+# warning is logged at gateway and CLI startup so operators see the
+# downgrade — see `_log_redaction_status()` in gateway/run.py and cli.py.
+_REDACT_ENABLED = os.getenv("HERMES_REDACT_SECRETS", "true").lower() in ("1", "true", "yes", "on")

 # Known API key prefixes -- match the prefix + contiguous token chars
 _PREFIX_PATTERNS = [
@@ -1,5 +1,6 @@
 from __future__ import annotations

+import re
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from decimal import Decimal
@@ -82,6 +83,121 @@ _UTC_NOW = lambda: datetime.now(timezone.utc)
 # Official docs snapshot entries. Models whose published pricing and cache
 # semantics are stable enough to encode exactly.
 _OFFICIAL_DOCS_PRICING: Dict[tuple[str, str], PricingEntry] = {
+    # ── Anthropic Claude 4.7 ─────────────────────────────────────────────
+    # Opus 4.5/4.6/4.7 share $5/$25 pricing (new tokenizer, up to 35% more
+    # tokens for the same text).
+    # Source: https://platform.claude.com/docs/en/about-claude/pricing
+    (
+        "anthropic",
+        "claude-opus-4-7",
+    ): PricingEntry(
+        input_cost_per_million=Decimal("5.00"),
+        output_cost_per_million=Decimal("25.00"),
+        cache_read_cost_per_million=Decimal("0.50"),
+        cache_write_cost_per_million=Decimal("6.25"),
+        source="official_docs_snapshot",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
+    ),
+    (
+        "anthropic",
+        "claude-opus-4-7-20250507",
+    ): PricingEntry(
+        input_cost_per_million=Decimal("5.00"),
+        output_cost_per_million=Decimal("25.00"),
+        cache_read_cost_per_million=Decimal("0.50"),
+        cache_write_cost_per_million=Decimal("6.25"),
+        source="official_docs_snapshot",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
+    ),
+    # ── Anthropic Claude 4.6 ─────────────────────────────────────────────
+    (
+        "anthropic",
+        "claude-opus-4-6",
+    ): PricingEntry(
+        input_cost_per_million=Decimal("5.00"),
+        output_cost_per_million=Decimal("25.00"),
+        cache_read_cost_per_million=Decimal("0.50"),
+        cache_write_cost_per_million=Decimal("6.25"),
+        source="official_docs_snapshot",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
+    ),
+    (
+        "anthropic",
+        "claude-opus-4-6-20250414",
+    ): PricingEntry(
+        input_cost_per_million=Decimal("5.00"),
+        output_cost_per_million=Decimal("25.00"),
+        cache_read_cost_per_million=Decimal("0.50"),
+        cache_write_cost_per_million=Decimal("6.25"),
+        source="official_docs_snapshot",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
+    ),
+    (
+        "anthropic",
+        "claude-sonnet-4-6",
+    ): PricingEntry(
+        input_cost_per_million=Decimal("3.00"),
+        output_cost_per_million=Decimal("15.00"),
+        cache_read_cost_per_million=Decimal("0.30"),
+        cache_write_cost_per_million=Decimal("3.75"),
+        source="official_docs_snapshot",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
+    ),
+    (
+        "anthropic",
+        "claude-sonnet-4-6-20250414",
+    ): PricingEntry(
+        input_cost_per_million=Decimal("3.00"),
+        output_cost_per_million=Decimal("15.00"),
+        cache_read_cost_per_million=Decimal("0.30"),
+        cache_write_cost_per_million=Decimal("3.75"),
+        source="official_docs_snapshot",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
+    ),
+    # ── Anthropic Claude 4.5 ─────────────────────────────────────────────
+    (
+        "anthropic",
+        "claude-opus-4-5",
+    ): PricingEntry(
+        input_cost_per_million=Decimal("5.00"),
+        output_cost_per_million=Decimal("25.00"),
+        cache_read_cost_per_million=Decimal("0.50"),
+        cache_write_cost_per_million=Decimal("6.25"),
+        source="official_docs_snapshot",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
+    ),
+    (
+        "anthropic",
+        "claude-sonnet-4-5",
+    ): PricingEntry(
+        input_cost_per_million=Decimal("3.00"),
+        output_cost_per_million=Decimal("15.00"),
+        cache_read_cost_per_million=Decimal("0.30"),
+        cache_write_cost_per_million=Decimal("3.75"),
+        source="official_docs_snapshot",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
+    ),
+    (
+        "anthropic",
+        "claude-haiku-4-5",
+    ): PricingEntry(
+        input_cost_per_million=Decimal("1.00"),
+        output_cost_per_million=Decimal("5.00"),
+        cache_read_cost_per_million=Decimal("0.10"),
+        cache_write_cost_per_million=Decimal("1.25"),
+        source="official_docs_snapshot",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
+    ),
+    # ── Anthropic Claude 4 / 4.1 ─────────────────────────────────────────
    (
        "anthropic",
        "claude-opus-4-20250514",
@@ -91,8 +207,8 @@ _OFFICIAL_DOCS_PRICING: Dict[tuple[str, str], PricingEntry] = {
        cache_read_cost_per_million=Decimal("1.50"),
        cache_write_cost_per_million=Decimal("18.75"),
        source="official_docs_snapshot",
-        source_url="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching",
-        pricing_version="anthropic-prompt-caching-2026-03-16",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
    ),
    (
        "anthropic",
@@ -103,8 +219,8 @@ _OFFICIAL_DOCS_PRICING: Dict[tuple[str, str], PricingEntry] = {
        cache_read_cost_per_million=Decimal("0.30"),
        cache_write_cost_per_million=Decimal("3.75"),
        source="official_docs_snapshot",
-        source_url="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching",
-        pricing_version="anthropic-prompt-caching-2026-03-16",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
    ),
    # OpenAI
    (
@@ -184,7 +300,7 @@ _OFFICIAL_DOCS_PRICING: Dict[tuple[str, str], PricingEntry] = {
        source_url="https://openai.com/api/pricing/",
        pricing_version="openai-pricing-2026-03-16",
    ),
-    # Anthropic older models (pre-4.6 generation)
+    # ── Anthropic older models (pre-4.5 generation) ────────────────────────
    (
        "anthropic",
        "claude-3-5-sonnet-20241022",
@@ -194,8 +310,8 @@ _OFFICIAL_DOCS_PRICING: Dict[tuple[str, str], PricingEntry] = {
        cache_read_cost_per_million=Decimal("0.30"),
        cache_write_cost_per_million=Decimal("3.75"),
        source="official_docs_snapshot",
-        source_url="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching",
-        pricing_version="anthropic-pricing-2026-03-16",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
    ),
    (
        "anthropic",
@@ -206,8 +322,8 @@ _OFFICIAL_DOCS_PRICING: Dict[tuple[str, str], PricingEntry] = {
        cache_read_cost_per_million=Decimal("0.08"),
        cache_write_cost_per_million=Decimal("1.00"),
        source="official_docs_snapshot",
-        source_url="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching",
-        pricing_version="anthropic-pricing-2026-03-16",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
    ),
    (
        "anthropic",
@@ -218,8 +334,8 @@ _OFFICIAL_DOCS_PRICING: Dict[tuple[str, str], PricingEntry] = {
        cache_read_cost_per_million=Decimal("1.50"),
        cache_write_cost_per_million=Decimal("18.75"),
        source="official_docs_snapshot",
-        source_url="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching",
-        pricing_version="anthropic-pricing-2026-03-16",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
    ),
    (
        "anthropic",
@@ -230,8 +346,8 @@ _OFFICIAL_DOCS_PRICING: Dict[tuple[str, str], PricingEntry] = {
        cache_read_cost_per_million=Decimal("0.03"),
        cache_write_cost_per_million=Decimal("0.30"),
        source="official_docs_snapshot",
-        source_url="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching",
-        pricing_version="anthropic-pricing-2026-03-16",
+        source_url="https://platform.claude.com/docs/en/about-claude/pricing",
+        pricing_version="anthropic-pricing-2026-05",
    ),
    # DeepSeek
    (
@@ -426,8 +542,37 @@ def resolve_billing_route(
    return BillingRoute(provider=provider_name or "unknown", model=model.split("/")[-1] if model else "", base_url=base_url or "", billing_mode="unknown")


+def _normalize_anthropic_model_name(model: str) -> str:
+    """Normalize Anthropic model name variants to canonical form.
+
+    Handles:
+      - Dot notation: claude-opus-4.7 → claude-opus-4-7
+      - Short aliases: claude-opus-4.7 → claude-opus-4-7
+      - Strips anthropic/ prefix if present
+    """
+    name = model.lower().strip()
+    if name.startswith("anthropic/"):
+        name = name[len("anthropic/"):]
+    # Normalize dots to dashes in version numbers (e.g. 4.7 → 4-7, 4.6 → 4-6)
+    # But preserve the rest of the name structure
+    name = re.sub(r"(\d+)\.(\d+)", r"\1-\2", name)
+    return name
+
+
 def _lookup_official_docs_pricing(route: BillingRoute) -> Optional[PricingEntry]:
-    return _OFFICIAL_DOCS_PRICING.get((route.provider, route.model.lower()))
+    model = route.model.lower()
+    # Direct lookup first
+    entry = _OFFICIAL_DOCS_PRICING.get((route.provider, model))
+    if entry:
+        return entry
+    # Try normalized name for Anthropic (handles dot-notation like opus-4.7)
+    if route.provider == "anthropic":
+        normalized = _normalize_anthropic_model_name(model)
+        if normalized != model:
+            entry = _OFFICIAL_DOCS_PRICING.get((route.provider, normalized))
+            if entry:
+                return entry
+    return None


 def _openrouter_pricing_entry(route: BillingRoute) -> Optional[PricingEntry]:
@@ -601,7 +601,7 @@ agent:
 #   - A preset like "hermes-cli" or "hermes-telegram" (curated tool set)
 #   - A list of individual toolsets to compose your own (see list below)
 #
-# Supported platform keys: cli, telegram, discord, whatsapp, slack, qqbot, teams
+# Supported platform keys: cli, telegram, discord, whatsapp, slack, qqbot, teams, google_chat
 #
 # Examples:
 #
@@ -632,6 +632,7 @@ agent:
 #   homeassistant: hermes-homeassistant  (same as telegram)
 #   qqbot:            hermes-qqbot            (same as telegram)
 #   teams:            hermes-teams            (same as telegram)
+#   google_chat:      hermes-google_chat      (same as telegram)
 #
 platform_toolsets:
  cli: [hermes-cli]
@@ -644,6 +645,7 @@ platform_toolsets:
  qqbot: [hermes-qqbot]
  yuanbao: [hermes-yuanbao]
  teams: [hermes-teams]
+  google_chat: [hermes-google_chat]

 # =============================================================================
 # Gateway Platform Settings
@@ -875,6 +877,22 @@ display:
  # Toggle at runtime with /verbose in the CLI
  tool_progress: all

+  # Auto-cleanup of temporary progress bubbles after the final response lands.
+  # On platforms that support message deletion (currently Telegram), this
+  # removes the tool-progress bubble, "⏳ Still working..." notices, and
+  # context-pressure status messages once the final reply has been delivered —
+  # keeping long-running turns visible live, then tidy afterward. Failed runs
+  # leave the bubbles in place as breadcrumbs. Off by default.
+  # Per-platform override: display.platforms.telegram.cleanup_progress
+  #   true:  Delete tracked progress/status bubbles on successful turn
+  #   false: Leave everything in place (default)
+  # Example:
+  #   display:
+  #     platforms:
+  #       telegram:
+  #         cleanup_progress: true
+  cleanup_progress: false
+
  # Gateway-only natural mid-turn assistant updates.
  # When true, completed assistant status messages are sent as separate chat
  # messages. This is independent of tool_progress and gateway streaming.
@@ -34,6 +34,8 @@ from pathlib import Path
 from datetime import datetime
 from typing import List, Dict, Any, Optional

+from utf8_bootstrap import ensure_windows_utf8_mode
+
 logger = logging.getLogger(__name__)

 # Suppress startup messages for clean CLI experience
@@ -1408,7 +1410,13 @@ def _cprint(text: str):

    import asyncio as _asyncio
    try:
-        current_loop = _asyncio.get_event_loop_policy().get_event_loop()
+        # Use get_running_loop() instead of get_event_loop() to avoid the
+        # DeprecationWarning / RuntimeWarning emitted by Python 3.10+ when
+        # get_event_loop() is called from a thread that has no current event
+        # loop set (e.g. the process_loop background thread).  Fixes #19285.
+        current_loop = _asyncio.get_running_loop()
+    except RuntimeError:
+        current_loop = None
    except Exception:
        current_loop = None
    # Same thread as the app's loop → safe to print directly.
@@ -2571,6 +2579,15 @@ class HermesCLI:
            return "class:status-bar-warn"
        return "class:status-bar-good"

+    @staticmethod
+    def _compression_count_style(count: int) -> str:
+        """Return a style class reflecting context compression pressure."""
+        if count >= 10:
+            return "class:status-bar-bad"
+        if count >= 5:
+            return "class:status-bar-warn"
+        return "class:status-bar-dim"
+
    def _build_context_bar(self, percent_used: Optional[int], width: int = 10) -> str:
        safe_percent = max(0, min(100, percent_used or 0))
        filled = round((safe_percent / 100) * width)
@@ -2854,6 +2871,9 @@ class HermesCLI:
                return self._trim_status_bar_text(text, width)
            if width < 76:
                parts = [f"⚕ {snapshot['model_short']}", percent_label]
+                compressions = snapshot.get("compressions", 0)
+                if compressions:
+                    parts.append(f"🗜️ {compressions}")
                parts.append(duration_label)
                return self._trim_status_bar_text(" · ".join(parts), width)

@@ -2864,7 +2884,10 @@ class HermesCLI:
            else:
                context_label = "ctx --"

+            compressions = snapshot.get("compressions", 0)
            parts = [f"⚕ {snapshot['model_short']}", context_label, percent_label]
+            if compressions:
+                parts.append(f"🗜️ {compressions}")
            parts.append(duration_label)
            prompt_elapsed = snapshot.get("prompt_elapsed")
            if prompt_elapsed:
@@ -2898,15 +2921,21 @@ class HermesCLI:
                percent = snapshot["context_percent"]
                percent_label = f"{percent}%" if percent is not None else "--"
                if width < 76:
+                    compressions = snapshot.get("compressions", 0)
                    frags = [
                        ("class:status-bar", " ⚕ "),
                        ("class:status-bar-strong", snapshot["model_short"]),
                        ("class:status-bar-dim", " · "),
                        (self._status_bar_context_style(percent), percent_label),
+                    ]
+                    if compressions:
+                        frags.append(("class:status-bar-dim", " · "))
+                        frags.append((self._compression_count_style(compressions), f"🗜️ {compressions}"))
+                    frags.extend([
                        ("class:status-bar-dim", " · "),
                        ("class:status-bar-dim", duration_label),
                        ("class:status-bar", " "),
-                    ]
+                    ])
                else:
                    if snapshot["context_length"]:
                        ctx_total = _format_context_length(snapshot["context_length"])
@@ -2916,6 +2945,7 @@ class HermesCLI:
                        context_label = "ctx --"

                    bar_style = self._status_bar_context_style(percent)
+                    compressions = snapshot.get("compressions", 0)
                    frags = [
                        ("class:status-bar", " ⚕ "),
                        ("class:status-bar-strong", snapshot["model_short"]),
@@ -2925,9 +2955,14 @@ class HermesCLI:
                        (bar_style, self._build_context_bar(percent)),
                        ("class:status-bar-dim", " "),
                        (bar_style, percent_label),
+                    ]
+                    if compressions:
+                        frags.append(("class:status-bar-dim", " │ "))
+                        frags.append((self._compression_count_style(compressions), f"🗜️ {compressions}"))
+                    frags.extend([
                        ("class:status-bar-dim", " │ "),
                        ("class:status-bar-dim", duration_label),
-                    ]
+                    ])
                    # Position 7: per-prompt elapsed timer (live or frozen)
                    prompt_elapsed = snapshot.get("prompt_elapsed")
                    if prompt_elapsed:
@@ -7958,6 +7993,7 @@ class HermesCLI:
        output_tokens = getattr(agent, "session_output_tokens", 0) or 0
        cache_read_tokens = getattr(agent, "session_cache_read_tokens", 0) or 0
        cache_write_tokens = getattr(agent, "session_cache_write_tokens", 0) or 0
+        reasoning_tokens = getattr(agent, "session_reasoning_tokens", 0) or 0
        prompt = agent.session_prompt_tokens
        completion = agent.session_completion_tokens
        total = agent.session_total_tokens
@@ -7989,6 +8025,8 @@ class HermesCLI:
        print(f"  Cache read tokens:         {cache_read_tokens:>10,}")
        print(f"  Cache write tokens:        {cache_write_tokens:>10,}")
        print(f"  Output tokens:             {output_tokens:>10,}")
+        if reasoning_tokens:
+            print(f"  ↳ Reasoning (subset):      {reasoning_tokens:>10,}")
        print(f"  Prompt tokens (total):     {prompt:>10,}")
        print(f"  Completion tokens:         {completion:>10,}")
        print(f"  Total tokens:              {total:>10,}")
@@ -10213,6 +10251,24 @@ class HermesCLI:
            _welcome_text = "Welcome to Hermes Agent! Type your message or /help for commands."
            _welcome_color = "#FFF8DC"
        self._console_print(f"[{_welcome_color}]{_welcome_text}[/]")
+
+        # Redaction opt-out warning (#17691): ON by default, loud when off.
+        # The redactor snapshots its state at import time so any toggle now
+        # won't affect the running process — we just want the operator to
+        # see that they're running without the safety net.
+        try:
+            _redact_raw = os.getenv("HERMES_REDACT_SECRETS", "true")
+            if _redact_raw.lower() not in ("1", "true", "yes", "on"):
+                self._console_print(
+                    "[bold red]⚠  Secret redaction is DISABLED[/] "
+                    f"(HERMES_REDACT_SECRETS={_redact_raw}). "
+                    "API keys and tokens may appear verbatim in chat output, "
+                    "session JSONs, and logs. Set "
+                    "[cyan]security.redact_secrets: true[/] in config.yaml "
+                    "to re-enable."
+                )
+        except Exception:
+            pass
        # First-time OpenClaw-residue banner — fires once if ~/.openclaw/ exists
        # after an OpenClaw→Hermes migration (especially migrations done by
        # OpenClaw's own tool, which doesn't archive the source directory).
@@ -12145,8 +12201,12 @@ class HermesCLI:
                # Set the custom handler on prompt_toolkit's event loop
                try:
                    import asyncio as _aio
-                    _loop = _aio.get_event_loop()
+                    # Use get_running_loop() to avoid DeprecationWarning on
+                    # Python 3.10+ when called outside an async context.
+                    _loop = _aio.get_running_loop()
                    _loop.set_exception_handler(_suppress_closed_loop_errors)
+                except RuntimeError:
+                    pass  # No running loop -- nothing to patch
                except Exception:
                    pass
                app.run()
@@ -12284,6 +12344,11 @@ def main(
    """
    global _active_worktree

+    ensure_windows_utf8_mode(
+        module="cli",
+        entrypoint_markers=("hermes", "cli.py"),
+    )
+
    # Signal to terminal_tool that we're in interactive mode
    # This enables interactive sudo password prompts with timeout
    os.environ["HERMES_INTERACTIVE"] = "1"
@@ -12481,7 +12546,18 @@ def main(
                    ):
                        cli.session_id = cli.agent.session_id
                    response = result.get("final_response", "") if isinstance(result, dict) else str(result)
-                    if response:
+                    # Surface backend errors that produced no visible output
+                    # (e.g. invalid model slug → provider 4xx). Mirrors the
+                    # interactive CLI path. Write to stderr so piped stdout
+                    # stays clean for automation wrappers.
+                    if (
+                        not response
+                        and isinstance(result, dict)
+                        and result.get("error")
+                        and (result.get("failed") or result.get("partial"))
+                    ):
+                        print(f"Error: {result['error']}", file=sys.stderr)
+                    elif response:
                        print(response)
                    # Session ID goes to stderr so piped stdout is clean.
                    print(f"\nsession_id: {cli.session_id}", file=sys.stderr)
@@ -41,6 +41,19 @@ from hermes_time import now as _hermes_now
 logger = logging.getLogger(__name__)


+class CronPromptInjectionBlocked(Exception):
+    """Raised by _build_job_prompt when the fully-assembled prompt trips the
+    injection scanner. Caught in run_job so the operator sees a clean
+    "job blocked" delivery instead of the scheduler crashing.
+
+    Assembled-prompt scanning (including loaded skill content) plugs the
+    gap from #3968: create-time scanning only covers the user-supplied
+    prompt field; skill content loaded at runtime was never scanned, so a
+    malicious skill could carry an injection payload that reached the
+    non-interactive (auto-approve) cron agent.
+    """
+
+
 def _resolve_cron_enabled_toolsets(job: dict, cfg: dict) -> list[str] | None:
    """Resolve the toolset list for a cron job.

@@ -152,9 +165,54 @@ def _resolve_origin(job: dict) -> Optional[dict]:
    return None


+def _plugin_cron_env_var(platform_name: str) -> str:
+    """Return the cron home-channel env var registered by a plugin platform.
+
+    Falls through the platform registry so plugins that set
+    ``cron_deliver_env_var`` on their ``PlatformEntry`` get cron delivery
+    support without editing this module.
+    """
+    try:
+        from hermes_cli.plugins import discover_plugins
+        discover_plugins()  # idempotent
+        from gateway.platform_registry import platform_registry
+        entry = platform_registry.get(platform_name.lower())
+        if entry and entry.cron_deliver_env_var:
+            return entry.cron_deliver_env_var
+    except Exception:
+        pass
+    return ""
+
+
+def _is_known_delivery_platform(platform_name: str) -> bool:
+    """Whether ``platform_name`` is a valid cron delivery target.
+
+    Hardcoded built-ins in ``_KNOWN_DELIVERY_PLATFORMS`` are checked first;
+    plugin platforms registered via ``PlatformEntry`` are accepted if they
+    provide a ``cron_deliver_env_var``.
+    """
+    name = platform_name.lower()
+    if name in _KNOWN_DELIVERY_PLATFORMS:
+        return True
+    return bool(_plugin_cron_env_var(name))
+
+
+def _resolve_home_env_var(platform_name: str) -> str:
+    """Return the env var name for a platform's cron home channel.
+
+    Built-in platforms are in ``_HOME_TARGET_ENV_VARS``; plugin platforms are
+    resolved from the platform registry.
+    """
+    name = platform_name.lower()
+    env_var = _HOME_TARGET_ENV_VARS.get(name)
+    if env_var:
+        return env_var
+    return _plugin_cron_env_var(name)
+
+
 def _get_home_target_chat_id(platform_name: str) -> str:
    """Return the configured home target chat/room ID for a delivery platform."""
-    env_var = _HOME_TARGET_ENV_VARS.get(platform_name.lower())
+    env_var = _resolve_home_env_var(platform_name)
    if not env_var:
        return ""
    value = os.getenv(env_var, "")
@@ -167,7 +225,7 @@ def _get_home_target_chat_id(platform_name: str) -> str:

 def _get_home_target_thread_id(platform_name: str) -> Optional[str]:
    """Return the optional thread/topic ID for a platform home target."""
-    env_var = _HOME_TARGET_ENV_VARS.get(platform_name.lower())
+    env_var = _resolve_home_env_var(platform_name)
    if not env_var:
        return None
    value = os.getenv(f"{env_var}_THREAD_ID", "").strip()
@@ -178,6 +236,24 @@ def _get_home_target_thread_id(platform_name: str) -> Optional[str]:
    return value or None


+def _iter_home_target_platforms():
+    """Iterate built-in + plugin platform names that expose a home channel.
+
+    Used by the ``deliver=origin`` fallback when the job has no origin.
+    """
+    for name in _HOME_TARGET_ENV_VARS:
+        yield name
+    try:
+        from hermes_cli.plugins import discover_plugins
+        discover_plugins()  # idempotent
+        from gateway.platform_registry import platform_registry
+        for entry in platform_registry.plugin_entries():
+            if entry.cron_deliver_env_var and entry.name not in _HOME_TARGET_ENV_VARS:
+                yield entry.name
+    except Exception:
+        pass
+
+
 def _resolve_single_delivery_target(job: dict, deliver_value: str) -> Optional[dict]:
    """Resolve one concrete auto-delivery target for a cron job."""

@@ -195,7 +271,7 @@ def _resolve_single_delivery_target(job: dict, deliver_value: str) -> Optional[d
            }
        # Origin missing (e.g. job created via API/script) — try each
        # platform's home channel as a fallback instead of silently dropping.
-        for platform_name in _HOME_TARGET_ENV_VARS:
+        for platform_name in _iter_home_target_platforms():
            chat_id = _get_home_target_chat_id(platform_name)
            if chat_id:
                logger.info(
@@ -251,7 +327,7 @@ def _resolve_single_delivery_target(job: dict, deliver_value: str) -> Optional[d
            "thread_id": origin.get("thread_id"),
        }

-    if platform_name.lower() not in _KNOWN_DELIVERY_PLATFORMS:
+    if not _is_known_delivery_platform(platform_name):
        return None
    chat_id = _get_home_target_chat_id(platform_name)
    if not chat_id:
@@ -805,7 +881,7 @@ def _build_job_prompt(job: dict, prerun_script: Optional[tuple] = None) -> str:

    skill_names = [str(name).strip() for name in skills if str(name).strip()]
    if not skill_names:
-        return prompt
+        return _scan_assembled_cron_prompt(prompt, job)

    from tools.skills_tool import skill_view
    from tools.skill_usage import bump_use
@@ -848,7 +924,32 @@ def _build_job_prompt(job: dict, prerun_script: Optional[tuple] = None) -> str:

    if prompt:
        parts.extend(["", f"The user has provided the following instruction alongside the skill invocation: {prompt}"])
-    return "\n".join(parts)
+    return _scan_assembled_cron_prompt("\n".join(parts), job)
+
+
+def _scan_assembled_cron_prompt(assembled: str, job: dict) -> str:
+    """Scan the fully-assembled cron prompt (including skill content) for
+    injection patterns. Raises ``CronPromptInjectionBlocked`` when a match
+    fires so ``run_job`` can surface a clear refusal to the operator.
+
+    Plugs the #3968 gap: ``_scan_cron_prompt`` runs on the user-supplied
+    prompt at create/update, but skill content is loaded from disk at
+    runtime and was never scanned. Since cron runs non-interactively
+    (auto-approves tool calls), a malicious skill carrying an injection
+    payload bypassed every gate.
+    """
+    from tools.cronjob_tools import _scan_cron_prompt
+
+    scan_error = _scan_cron_prompt(assembled)
+    if scan_error:
+        job_label = job.get("name") or job.get("id") or "<unknown>"
+        logger.warning(
+            "Cron job '%s': assembled prompt blocked by injection scanner — %s",
+            job_label,
+            scan_error,
+        )
+        raise CronPromptInjectionBlocked(scan_error)
+    return assembled


 def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
@@ -1003,7 +1104,31 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
            )
            return True, silent_doc, SILENT_MARKER, None

-    prompt = _build_job_prompt(job, prerun_script=prerun_script)
+    try:
+        prompt = _build_job_prompt(job, prerun_script=prerun_script)
+    except CronPromptInjectionBlocked as block_exc:
+        # Assembled prompt (user prompt + loaded skill content) tripped the
+        # injection scanner. Refuse to run the agent this tick and surface
+        # a clear failure to the operator so they see WHY the scheduled job
+        # didn't run and can audit the offending skill.
+        logger.warning(
+            "Job '%s' (ID: %s): blocked by prompt-injection scanner — %s",
+            job_name, job_id, block_exc,
+        )
+        blocked_doc = (
+            f"# Cron Job: {job_name}\n\n"
+            f"**Job ID:** {job_id}\n"
+            f"**Run Time:** {_hermes_now().strftime('%Y-%m-%d %H:%M:%S')}\n"
+            f"**Status:** BLOCKED\n\n"
+            "The assembled prompt (user prompt + loaded skill content) tripped "
+            "the cron injection scanner and the agent was NOT run.\n\n"
+            f"**Scanner result:** {block_exc}\n\n"
+            "Audit the skill(s) attached to this job for prompt-injection "
+            "payloads or invisible-unicode markers. If the skill is legitimate "
+            "and the match is a false positive, rephrase the content to avoid "
+            "the threat pattern (`tools/cronjob_tools.py::_CRON_THREAT_PATTERNS`)."
+        )
+        return False, blocked_doc, "", str(block_exc)
    if prompt is None:
        logger.info("Job '%s': script produced no output, skipping AI call.", job_name)
        return True, "", SILENT_MARKER, None
@@ -1198,6 +1323,27 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
            except Exception as e:
                logger.debug("Job '%s': failed to load credential pool for %s: %s", job_id, runtime_provider, e)

+        # Initialize MCP servers so configured mcp_servers are available to
+        # the agent's tool registry before AIAgent is constructed. Without
+        # this, cron jobs never saw any MCP tools — only the gateway / CLI
+        # paths called discover_mcp_tools() at startup. Idempotent: subsequent
+        # ticks short-circuit on already-connected servers inside
+        # register_mcp_servers(). Non-fatal on failure: a broken MCP server
+        # shouldn't kill an otherwise-working cron job. See #4219.
+        try:
+            from tools.mcp_tool import discover_mcp_tools
+            _mcp_tools = discover_mcp_tools()
+            if _mcp_tools:
+                logger.info(
+                    "Job '%s': %d MCP tool(s) available",
+                    job_id, len(_mcp_tools),
+                )
+        except Exception as _mcp_exc:
+            logger.warning(
+                "Job '%s': MCP initialization failed (non-fatal): %s",
+                job_id, _mcp_exc,
+            )
+
        agent = AIAgent(
            model=model,
            api_key=runtime.get("api_key"),
@@ -14,6 +14,9 @@
 #     keys; exposing it on LAN without auth is unsafe. If you want remote
 #     access, use an SSH tunnel or put it behind a reverse proxy that
 #     adds authentication — do NOT pass --insecure --host 0.0.0.0.
+#   - If you override entrypoint, keep /opt/hermes/docker/entrypoint.sh in
+#     the command chain. It drops root to the hermes user before gateway
+#     files such as gateway.lock are created.
 #   - The gateway's API server is off unless you uncomment API_SERVER_KEY
 #     and API_SERVER_HOST. See docs/user-guide/api-server.md before doing
 #     this on an internet-facing host.
@@ -41,6 +44,15 @@ services:
      # - TEAMS_TENANT_ID=${TEAMS_TENANT_ID}
      # - TEAMS_ALLOWED_USERS=${TEAMS_ALLOWED_USERS}
      # - TEAMS_PORT=${TEAMS_PORT:-3978}
+      # Google Chat — uncomment and fill in to enable the Google Chat gateway.
+      # See website/docs/user-guide/messaging/google_chat.md for the full setup.
+      # The SA JSON path must point to a file mounted into the container —
+      # add a volume entry above (e.g. ``- ~/.hermes/google-chat-sa.json:/secrets/google-chat-sa.json:ro``)
+      # then set GOOGLE_CHAT_SERVICE_ACCOUNT_JSON to that mount path.
+      # - GOOGLE_CHAT_PROJECT_ID=${GOOGLE_CHAT_PROJECT_ID}
+      # - GOOGLE_CHAT_SUBSCRIPTION_NAME=${GOOGLE_CHAT_SUBSCRIPTION_NAME}
+      # - GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=${GOOGLE_CHAT_SERVICE_ACCOUNT_JSON}
+      # - GOOGLE_CHAT_ALLOWED_USERS=${GOOGLE_CHAT_ALLOWED_USERS}
    command: ["gateway", "run"]

  dashboard:
@@ -809,6 +809,12 @@ def load_gateway_config() -> GatewayConfig:
                    os.environ["SLACK_FREE_RESPONSE_CHANNELS"] = str(frc)
                if "reactions" in slack_cfg and not os.getenv("SLACK_REACTIONS"):
                    os.environ["SLACK_REACTIONS"] = str(slack_cfg["reactions"]).lower()
+                # allowed_channels: if set, bot ONLY responds in these channels (whitelist)
+                ac = slack_cfg.get("allowed_channels")
+                if ac is not None and not os.getenv("SLACK_ALLOWED_CHANNELS"):
+                    if isinstance(ac, list):
+                        ac = ",".join(str(v) for v in ac)
+                    os.environ["SLACK_ALLOWED_CHANNELS"] = str(ac)

            # Discord settings → env vars (env vars take precedence)
            discord_cfg = yaml_cfg.get("discord", {})
@@ -893,6 +899,12 @@ def load_gateway_config() -> GatewayConfig:
                    if isinstance(frc, list):
                        frc = ",".join(str(v) for v in frc)
                    os.environ["TELEGRAM_FREE_RESPONSE_CHATS"] = str(frc)
+                # allowed_chats: if set, bot ONLY responds in these group chats (whitelist)
+                ac = telegram_cfg.get("allowed_chats")
+                if ac is not None and not os.getenv("TELEGRAM_ALLOWED_CHATS"):
+                    if isinstance(ac, list):
+                        ac = ",".join(str(v) for v in ac)
+                    os.environ["TELEGRAM_ALLOWED_CHATS"] = str(ac)
                ignored_threads = telegram_cfg.get("ignored_threads")
                if ignored_threads is not None and not os.getenv("TELEGRAM_IGNORED_THREADS"):
                    if isinstance(ignored_threads, list):
@@ -976,12 +988,35 @@ def load_gateway_config() -> GatewayConfig:
                    if isinstance(frc, list):
                        frc = ",".join(str(v) for v in frc)
                    os.environ["DINGTALK_FREE_RESPONSE_CHATS"] = str(frc)
+                # allowed_chats: if set, bot ONLY responds in these group chats (whitelist)
+                ac = dingtalk_cfg.get("allowed_chats")
+                if ac is not None and not os.getenv("DINGTALK_ALLOWED_CHATS"):
+                    if isinstance(ac, list):
+                        ac = ",".join(str(v) for v in ac)
+                    os.environ["DINGTALK_ALLOWED_CHATS"] = str(ac)
                allowed = dingtalk_cfg.get("allowed_users")
                if allowed is not None and not os.getenv("DINGTALK_ALLOWED_USERS"):
                    if isinstance(allowed, list):
                        allowed = ",".join(str(v) for v in allowed)
                    os.environ["DINGTALK_ALLOWED_USERS"] = str(allowed)

+            # Mattermost settings → env vars (env vars take precedence)
+            mattermost_cfg = yaml_cfg.get("mattermost", {})
+            if isinstance(mattermost_cfg, dict):
+                if "require_mention" in mattermost_cfg and not os.getenv("MATTERMOST_REQUIRE_MENTION"):
+                    os.environ["MATTERMOST_REQUIRE_MENTION"] = str(mattermost_cfg["require_mention"]).lower()
+                frc = mattermost_cfg.get("free_response_channels")
+                if frc is not None and not os.getenv("MATTERMOST_FREE_RESPONSE_CHANNELS"):
+                    if isinstance(frc, list):
+                        frc = ",".join(str(v) for v in frc)
+                    os.environ["MATTERMOST_FREE_RESPONSE_CHANNELS"] = str(frc)
+                # allowed_channels: if set, bot ONLY responds in these channels (whitelist)
+                ac = mattermost_cfg.get("allowed_channels")
+                if ac is not None and not os.getenv("MATTERMOST_ALLOWED_CHANNELS"):
+                    if isinstance(ac, list):
+                        ac = ",".join(str(v) for v in ac)
+                    os.environ["MATTERMOST_ALLOWED_CHANNELS"] = str(ac)
+
            # Matrix settings → env vars (env vars take precedence)
            matrix_cfg = yaml_cfg.get("matrix", {})
            if isinstance(matrix_cfg, dict):
@@ -992,6 +1027,12 @@ def load_gateway_config() -> GatewayConfig:
                    if isinstance(frc, list):
                        frc = ",".join(str(v) for v in frc)
                    os.environ["MATRIX_FREE_RESPONSE_ROOMS"] = str(frc)
+                # allowed_rooms: if set, bot ONLY responds in these rooms (whitelist)
+                ar = matrix_cfg.get("allowed_rooms")
+                if ar is not None and not os.getenv("MATRIX_ALLOWED_ROOMS"):
+                    if isinstance(ar, list):
+                        ar = ",".join(str(v) for v in ar)
+                    os.environ["MATRIX_ALLOWED_ROOMS"] = str(ar)
                if "auto_thread" in matrix_cfg and not os.getenv("MATRIX_AUTO_THREAD"):
                    os.environ["MATRIX_AUTO_THREAD"] = str(matrix_cfg["auto_thread"]).lower()
                if "dm_mention_threads" in matrix_cfg and not os.getenv("MATRIX_DM_MENTION_THREADS"):
@@ -1152,10 +1193,17 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
    
    # WhatsApp (typically uses different auth mechanism)
    whatsapp_enabled = os.getenv("WHATSAPP_ENABLED", "").lower() in ("true", "1", "yes")
-    if whatsapp_enabled:
-        if Platform.WHATSAPP not in config.platforms:
-            config.platforms[Platform.WHATSAPP] = PlatformConfig()
-        config.platforms[Platform.WHATSAPP].enabled = True
+    whatsapp_disabled_explicitly = os.getenv("WHATSAPP_ENABLED", "").lower() in ("false", "0", "no")
+    if Platform.WHATSAPP in config.platforms:
+        # YAML config exists — respect explicit disable
+        wa_cfg = config.platforms[Platform.WHATSAPP]
+        if whatsapp_disabled_explicitly:
+            wa_cfg.enabled = False
+        elif whatsapp_enabled:
+            wa_cfg.enabled = True
+        # else: keep whatever the YAML set
+    elif whatsapp_enabled:
+        config.platforms[Platform.WHATSAPP] = PlatformConfig(enabled=True)
    whatsapp_home = os.getenv("WHATSAPP_HOME_CHANNEL")
    if whatsapp_home and Platform.WHATSAPP in config.platforms:
        config.platforms[Platform.WHATSAPP].home_channel = HomeChannel(
@@ -1616,7 +1664,10 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
    # Registry-driven enable for plugin platforms.  Built-ins have explicit
    # blocks above; plugins expose check_fn() which is the single source of
    # truth for "are my env vars set?".  When it returns True, ensure the
-    # platform is enabled so start() will create its adapter.
+    # platform is enabled so start() will create its adapter.  Plugins that
+    # need to seed ``PlatformConfig.extra`` from env vars (e.g. Google Chat's
+    # project_id / subscription_name) can supply ``env_enablement_fn`` on
+    # their PlatformEntry — called here BEFORE adapter construction.
    try:
        from hermes_cli.plugins import discover_plugins
        discover_plugins()  # idempotent
@@ -1632,5 +1683,31 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
            if platform not in config.platforms:
                config.platforms[platform] = PlatformConfig()
            config.platforms[platform].enabled = True
+            # Seed extras from env if the plugin opted in.
+            if entry.env_enablement_fn is not None:
+                try:
+                    seed = entry.env_enablement_fn()
+                except Exception as e:
+                    logger.debug(
+                        "env_enablement_fn for %s raised: %s", entry.name, e
+                    )
+                    seed = None
+                if isinstance(seed, dict) and seed:
+                    # Extract the home_channel dict (if provided) so we wire it
+                    # up as a proper HomeChannel dataclass.  Everything else is
+                    # merged into ``extra``.
+                    home = seed.pop("home_channel", None)
+                    config.platforms[platform].extra.update(seed)
+                    if isinstance(home, dict) and home.get("chat_id"):
+                        config.platforms[platform].home_channel = HomeChannel(
+                            platform=platform,
+                            chat_id=str(home["chat_id"]),
+                            name=str(home.get("name") or "Home"),
+                            thread_id=(
+                                str(home["thread_id"])
+                                if home.get("thread_id")
+                                else None
+                            ),
+                        )
    except Exception as e:
        logger.debug("Plugin platform enable pass failed: %s", e)
@@ -35,6 +35,12 @@ _GLOBAL_DEFAULTS: dict[str, Any] = {
    "show_reasoning": False,
    "tool_preview_length": 0,
    "streaming": None,  # None = follow top-level streaming config
+    # When true, delete tool-progress / "Still working..." / status bubbles
+    # after the final response lands on platforms that support message
+    # deletion (e.g. Telegram). Off by default — progress is still shown
+    # live, just cleaned up after success so the chat doesn't fill up with
+    # stale breadcrumbs. Failed runs leave bubbles in place as breadcrumbs.
+    "cleanup_progress": False,
 }

 # ---------------------------------------------------------------------------
@@ -188,6 +194,10 @@ def _normalise(setting: str, value: Any) -> Any:
        if isinstance(value, str):
            return value.lower() in ("true", "1", "yes", "on")
        return bool(value)
+    if setting == "cleanup_progress":
+        if isinstance(value, str):
+            return value.lower() in ("true", "1", "yes", "on")
+        return bool(value)
    if setting == "tool_preview_length":
        try:
            return int(value)
@@ -195,12 +195,23 @@ class PairingStore:
        """
        Approve a pairing code. Adds the user to the approved list.

-        Returns {user_id, user_name} on success, None if code is invalid/expired.
+        Returns {user_id, user_name} on success, None if code is
+        invalid/expired OR the platform is currently locked out after
+        ``MAX_FAILED_ATTEMPTS`` failed approvals (#10195). Callers can
+        disambiguate with ``_is_locked_out(platform)``.
        """
        with self._lock:
            self._cleanup_expired(platform)
            code = code.upper().strip()

+            # Lockout check — must run before the pending lookup so a
+            # valid code (e.g. one already sitting in pending) cannot be
+            # accepted once the lockout fires. Without this, the lockout
+            # only blocks `generate_code`, not `approve_code` — nullifying
+            # the brute-force protection for any code already issued.
+            if self._is_locked_out(platform):
+                return None
+
            pending = self._load_json(self._pending_path(platform))
            if code not in pending:
                self._record_failed_attempt(platform)
@@ -110,6 +110,21 @@ class PlatformEntry:
    # Do not use markdown.").  Empty string = no hint.
    platform_hint: str = ""

+    # ── Env-driven auto-configuration ──
+    # Optional: read env vars, return a dict of ``PlatformConfig.extra`` fields
+    # to seed when the platform is auto-enabled.  Called during
+    # ``_apply_env_overrides`` BEFORE the adapter is constructed, so
+    # ``gateway status`` etc. can reflect env-only configuration without
+    # instantiating the adapter.  Return ``None`` (or an empty dict) to skip.
+    # Signature: () -> Optional[dict[str, Any]]
+    env_enablement_fn: Optional[Callable[[], Optional[dict]]] = None
+
+    # Optional: home-channel env var name for cron/notification delivery
+    # (e.g. ``"IRC_HOME_CHANNEL"``).  When set, ``cron.scheduler`` treats this
+    # platform as a valid ``deliver=<name>`` target and reads the env var to
+    # resolve the default chat/room ID.  Empty = no cron home-channel support.
+    cron_deliver_env_var: str = ""
+

 class PlatformRegistry:
    """Central registry of platform adapters.
@@ -4,18 +4,34 @@ There are two ways to add a platform to the Hermes gateway:

 ## Plugin Path (Recommended for Community/Third-Party)

-Create a plugin directory in `~/.hermes/plugins/` with a `PLUGIN.yaml` and
-`adapter.py`.  The adapter inherits from `BasePlatformAdapter` and registers
-via `ctx.register_platform()` in the `register(ctx)` entry point.  This
-requires **zero changes to core Hermes code**.
+Create a plugin directory in `~/.hermes/plugins/` (or under `plugins/platforms/`
+for bundled plugins) with a `plugin.yaml` and `adapter.py`.  The adapter
+inherits from `BasePlatformAdapter` and registers via
+`ctx.register_platform()` in the `register(ctx)` entry point.  This requires
+**zero changes to core Hermes code**.

 The plugin system automatically handles: adapter creation, config parsing,
 user authorization, cron delivery, send_message routing, system prompt hints,
 status display, gateway setup, and more.

-See `plugins/platforms/irc/` for a complete reference implementation, and
+**Three optional hooks cover the edges most adapters need:**
+
+- `env_enablement_fn: () -> Optional[dict]` — seeds `PlatformConfig.extra`
+  (and an optional `home_channel` dict) from env vars BEFORE the adapter is
+  constructed.  Without this, env-only setups don't surface in
+  `hermes gateway status` or `get_connected_platforms()` until the SDK
+  instantiates.
+- `cron_deliver_env_var: str` — name of the `*_HOME_CHANNEL` env var.  When
+  set, `deliver=<name>` cron jobs route to this var without editing
+  `cron/scheduler.py`'s hardcoded sets.
+- `plugin.yaml` `requires_env` / `optional_env` rich-dict entries —
+  auto-populate `OPTIONAL_ENV_VARS` in `hermes_cli/config.py` so the setup
+  wizard surfaces proper descriptions, prompts, password flags, and URLs.
+
+See `plugins/platforms/irc/`, `plugins/platforms/teams/`, and
+`plugins/platforms/google_chat/` for complete working examples, and
 `website/docs/developer-guide/adding-platform-adapters.md` for the full
-plugin guide with code examples.
+plugin guide with code examples and hook documentation.

 ---

@@ -917,6 +917,16 @@ class APIServerAdapter(BasePlatformAdapter):
                "type": "bearer",
                "required": bool(self._api_key),
            },
+            "runtime": {
+                "mode": "server_agent",
+                "tool_execution": "server",
+                "split_runtime": False,
+                "description": (
+                    "The API server creates a server-side Hermes AIAgent; "
+                    "tools execute on the API-server host unless a future "
+                    "explicit split-runtime mode is enabled."
+                ),
+            },
            "features": {
                "chat_completions": True,
                "chat_completions_streaming": True,
@@ -1316,8 +1326,8 @@ class APIServerAdapter(BasePlatformAdapter):
            try:
                result, agent_usage = await agent_task
                usage = agent_usage or usage
-            except Exception:
-                pass
+            except Exception as exc:
+                logger.warning("Agent task %s failed, usage data lost: %s", completion_id, exc)

            # Finish chunk
            finish_chunk = {
@@ -1888,12 +1898,12 @@ class APIServerAdapter(BasePlatformAdapter):
                    "output_tokens": usage.get("output_tokens", 0),
                    "total_tokens": usage.get("total_tokens", 0),
                }
-                full_history = list(conversation_history)
-                full_history.append({"role": "user", "content": user_message})
-                if isinstance(result, dict) and result.get("messages"):
-                    full_history.extend(result["messages"])
-                else:
-                    full_history.append({"role": "assistant", "content": final_response_text})
+                full_history = self._build_response_conversation_history(
+                    conversation_history,
+                    user_message,
+                    result,
+                    final_response_text,
+                )
                _persist_response_snapshot(
                    completed_env,
                    conversation_history_snapshot=full_history,
@@ -2192,17 +2202,22 @@ class APIServerAdapter(BasePlatformAdapter):

        # Build the full conversation history for storage
        # (includes tool calls from the agent run)
-        full_history = list(conversation_history)
-        full_history.append({"role": "user", "content": user_message})
-        # Add agent's internal messages if available
-        agent_messages = result.get("messages", [])
-        if agent_messages:
-            full_history.extend(agent_messages)
-        else:
-            full_history.append({"role": "assistant", "content": final_response})
+        full_history = self._build_response_conversation_history(
+            conversation_history,
+            user_message,
+            result,
+            final_response,
+        )

-        # Build output items (includes tool calls + final message)
-        output_items = self._extract_output_items(result)
+        # Build output items from the current turn only.  AIAgent returns a
+        # full transcript in result["messages"], while older/mocked paths may
+        # return only the current turn suffix.
+        output_start_index = self._response_messages_turn_start_index(
+            conversation_history,
+            user_message,
+            result,
+        )
+        output_items = self._extract_output_items(result, start_index=output_start_index)

        response_data = {
            "id": response_id,
@@ -2494,17 +2509,70 @@ class APIServerAdapter(BasePlatformAdapter):
    # ------------------------------------------------------------------

    @staticmethod
-    def _extract_output_items(result: Dict[str, Any]) -> List[Dict[str, Any]]:
-        """
-        Build the full output item array from the agent's messages.
+    def _build_response_conversation_history(
+        conversation_history: List[Dict[str, Any]],
+        user_message: Any,
+        result: Dict[str, Any],
+        final_response: Any,
+    ) -> List[Dict[str, Any]]:
+        """Build the stored Responses transcript without duplicating history."""
+        prior = list(conversation_history)
+        current_user = {"role": "user", "content": user_message}
+        agent_messages = result.get("messages") if isinstance(result, dict) else None

-        Walks *result["messages"]* and emits:
+        if isinstance(agent_messages, list) and agent_messages:
+            turn_start = APIServerAdapter._response_messages_turn_start_index(
+                conversation_history,
+                user_message,
+                result,
+            )
+            if turn_start:
+                return list(agent_messages)
+
+            full_history = prior
+            full_history.append(current_user)
+            full_history.extend(agent_messages)
+            return full_history
+
+        full_history = prior
+        full_history.append(current_user)
+        full_history.append({"role": "assistant", "content": final_response})
+        return full_history
+
+    @staticmethod
+    def _response_messages_turn_start_index(
+        conversation_history: List[Dict[str, Any]],
+        user_message: Any,
+        result: Dict[str, Any],
+    ) -> int:
+        """Detect transcript-shaped result["messages"] and return turn start."""
+        agent_messages = result.get("messages") if isinstance(result, dict) else None
+        if not isinstance(agent_messages, list) or not agent_messages:
+            return 0
+
+        prior = list(conversation_history)
+        current_user = {"role": "user", "content": user_message}
+        expected_prefix = prior + [current_user]
+        if agent_messages[:len(expected_prefix)] == expected_prefix:
+            return len(expected_prefix)
+        if prior and agent_messages[:len(prior)] == prior:
+            return len(prior)
+        return 0
+
+    @staticmethod
+    def _extract_output_items(result: Dict[str, Any], start_index: int = 0) -> List[Dict[str, Any]]:
+        """
+        Build the output item array from the agent's messages.
+
+        Walks *result["messages"]* starting at *start_index* and emits:
        - ``function_call`` items for each tool_call on assistant messages
        - ``function_call_output`` items for each tool-role message
        - a final ``message`` item with the assistant's text reply
        """
        items: List[Dict[str, Any]] = []
        messages = result.get("messages", [])
+        if start_index > 0:
+            messages = messages[start_index:]

        for msg in messages:
            role = msg.get("role")
@@ -1304,37 +1304,52 @@ class BasePlatformAdapter(ABC):
        self._fatal_error_code = None
        self._fatal_error_message = None
        self._fatal_error_retryable = True
-        try:
-            from gateway.status import write_runtime_status
-            write_runtime_status(platform=self.platform.value, platform_state="connected", error_code=None, error_message=None)
-        except Exception:
-            pass
+        self._write_runtime_status_safe("connected", platform_state="connected", error_code=None, error_message=None)

    def _mark_disconnected(self) -> None:
        self._running = False
        if self.has_fatal_error:
            return
-        try:
-            from gateway.status import write_runtime_status
-            write_runtime_status(platform=self.platform.value, platform_state="disconnected", error_code=None, error_message=None)
-        except Exception:
-            pass
+        self._write_runtime_status_safe("disconnected", platform_state="disconnected", error_code=None, error_message=None)

    def _set_fatal_error(self, code: str, message: str, *, retryable: bool) -> None:
        self._running = False
        self._fatal_error_code = code
        self._fatal_error_message = message
        self._fatal_error_retryable = retryable
+        self._write_runtime_status_safe("fatal", platform_state="fatal", error_code=code, error_message=message)
+
+    def _write_runtime_status_safe(self, context: str, **kwargs) -> None:
+        """Write runtime status; log first failure per context at warning, rest at debug.
+
+        Status writes can fail on permissions, ENOSPC, missing status dir, etc.
+        A persistently failing status dir used to be silent (``except: pass``).
+        Logging every failure would spam the log on reconnect loops, so this
+        surfaces the first failure per (platform, context) at warning level and
+        downgrades subsequent failures to debug.
+        """
        try:
            from gateway.status import write_runtime_status
-            write_runtime_status(
-                platform=self.platform.value,
-                platform_state="fatal",
-                error_code=code,
-                error_message=message,
-            )
-        except Exception:
-            pass
+            write_runtime_status(platform=self.platform.value, **kwargs)
+        except Exception as exc:
+            # Use getattr so object.__new__(...) test harnesses that skip __init__
+            # don't blow up on attribute access.
+            logged = getattr(self, "_status_write_logged", None)
+            if logged is None:
+                logged = set()
+                try:
+                    self._status_write_logged = logged
+                except Exception:
+                    pass
+            key = (self.platform.value, context)
+            if key not in logged:
+                logger.warning(
+                    "Failed to write runtime status (%s) for %s: %s (further failures at debug level)",
+                    context, self.platform.value, exc,
+                )
+                logged.add(key)
+            else:
+                logger.debug("Failed to write runtime status (%s) for %s: %s", context, self.platform.value, exc)

    async def _notify_fatal_error(self) -> None:
        handler = self._fatal_error_handler
@@ -1874,23 +1889,38 @@ class BasePlatformAdapter(ABC):
    def extract_media(content: str) -> Tuple[List[Tuple[str, bool]], str]:
        """
        Extract MEDIA:<path> tags and [[audio_as_voice]] directives from response text.
-        
+
        The TTS tool returns responses like:
            [[audio_as_voice]]
            MEDIA:/path/to/audio.ogg
-        
+
+        Skills that produce large/lossless images (e.g. info-graph, where a
+        rendered JPG is 1-2 MB but Telegram's sendPhoto recompresses to
+        ~200 KB at 1280px) can use ``[[as_document]]`` to request unmodified
+        delivery via sendDocument instead of sendPhoto/sendMediaGroup. The
+        directive is detected at the dispatch sites (which have access to the
+        original response); this method just strips it so it never leaks into
+        user-visible text. Per-file granularity is intentionally not exposed —
+        when an agent emits ``[[as_document]]`` once, every image path in the
+        same response is delivered as a document, mirroring the all-or-nothing
+        scope of ``[[audio_as_voice]]``.
+
        Args:
            content: The response text to scan.
-        
+
        Returns:
            Tuple of (list of (path, is_voice) pairs, cleaned content with tags removed).
        """
        media = []
        cleaned = content
-        
+
        # Check for [[audio_as_voice]] directive
        has_voice_tag = "[[audio_as_voice]]" in content
        cleaned = cleaned.replace("[[audio_as_voice]]", "")
+        # Strip [[as_document]] directive — callers inspect the original
+        # ``content`` for it (so they can still react to it); here we just
+        # keep it out of the user-visible cleaned text.
+        cleaned = cleaned.replace("[[as_document]]", "")
        
        # Extract MEDIA:<path> tags, allowing optional whitespace after the colon
        # and quoted/backticked paths for LLM-formatted outputs.
@@ -2096,9 +2126,52 @@ class BasePlatformAdapter(ABC):

        ``generation`` lets callers tie the callback to a specific gateway run
        generation so stale runs cannot clear callbacks owned by a fresher run.
+
+        If a callback for the same ``session_key`` (and generation, when set)
+        is already registered, the new callback is chained — both fire, in
+        registration order, with per-callback exception isolation. This lets
+        independent features (background-review release + temporary-bubble
+        cleanup) coexist without clobbering each other. Stale-generation
+        callers never overwrite a fresher generation's slot.
        """
        if not session_key or not callable(callback):
            return
+
+        existing = self._post_delivery_callbacks.get(session_key)
+        if existing is not None:
+            if isinstance(existing, tuple) and len(existing) == 2:
+                existing_gen, existing_cb = existing
+            else:
+                existing_gen, existing_cb = None, existing
+            # Stale-generation registrations never overwrite a fresher slot.
+            if (
+                existing_gen is not None
+                and generation is not None
+                and int(generation) < int(existing_gen)
+            ):
+                return
+            # Same-or-newer generation: chain with the existing callback so
+            # both fire in registration order.
+            if callable(existing_cb) and (
+                existing_gen is None
+                or generation is None
+                or int(existing_gen) == int(generation)
+            ):
+                _prev = existing_cb
+                _new = callback
+
+                def _chained() -> None:
+                    try:
+                        _prev()
+                    except Exception:
+                        logger.debug("Post-delivery callback failed", exc_info=True)
+                    try:
+                        _new()
+                    except Exception:
+                        logger.debug("Post-delivery callback failed", exc_info=True)
+
+                callback = _chained
+
        if generation is None:
            self._post_delivery_callbacks[session_key] = callback
        else:
@@ -2772,13 +2845,21 @@ class BasePlatformAdapter(ABC):
            if not response:
                logger.debug("[%s] Handler returned empty/None response for %s", self.name, event.source.chat_id)
            if response:
+                # Capture [[as_document]] before extract_media strips it, so the
+                # dispatch partition below can route image-extension files
+                # through send_document instead of send_multiple_images. Used
+                # by skills that produce large/lossless images (e.g. info-graph)
+                # where Telegram's sendPhoto recompression destroys legibility.
+                force_document_attachments = "[[as_document]]" in response
+
                # Extract MEDIA:<path> tags (from TTS tool) before other processing
                media_files, response = self.extract_media(response)
-                
+
                # Extract image URLs and send them as native platform attachments
                images, text_content = self.extract_images(response)
                # Strip any remaining internal directives from message body (fixes #1561)
                text_content = text_content.replace("[[audio_as_voice]]", "").strip()
+                text_content = text_content.replace("[[as_document]]", "").strip()
                text_content = re.sub(r"MEDIA:\s*\S+", "", text_content).strip()
                if images:
                    logger.info("[%s] extract_images found %d image(s) in response (%d chars)", self.name, len(images), len(response))
@@ -2880,19 +2961,26 @@ class BasePlatformAdapter(ABC):
                _IMAGE_EXTS = {'.jpg', '.jpeg', '.png', '.webp', '.gif'}

                # Partition images out of media_files + local_files so they
-                # can be sent as a single batch (Signal RPC)
+                # can be sent as a single batch (Signal RPC). When
+                # ``[[as_document]]`` was set on the original response, image
+                # files skip the photo path and route to send_document below
+                # so they're delivered with original bytes (no Telegram
+                # sendPhoto recompression).
                from urllib.parse import quote as _quote
                _image_paths: list = []
                _non_image_media: list = []
                for media_path, is_voice in media_files:
                    _ext = Path(media_path).suffix.lower()
-                    if _ext in _IMAGE_EXTS and not is_voice:
+                    if (_ext in _IMAGE_EXTS
+                            and not is_voice
+                            and not force_document_attachments):
                        _image_paths.append(media_path)
                    else:
                        _non_image_media.append((media_path, is_voice))
                _non_image_local: list = []
                for file_path in local_files:
-                    if Path(file_path).suffix.lower() in _IMAGE_EXTS:
+                    if (Path(file_path).suffix.lower() in _IMAGE_EXTS
+                            and not force_document_attachments):
                        _image_paths.append(file_path)
                    else:
                        _non_image_local.append(file_path)
@@ -3058,7 +3146,9 @@ class BasePlatformAdapter(ABC):
                _post_cb = getattr(self, "_post_delivery_callbacks", {}).pop(session_key, None)
            if callable(_post_cb):
                try:
-                    _post_cb()
+                    _post_result = _post_cb()
+                    if inspect.isawaitable(_post_result):
+                        await _post_result
                except Exception:
                    pass
            # Stop typing indicator
@@ -365,6 +365,20 @@ class DingTalkAdapter(BasePlatformAdapter):
            return {str(part).strip() for part in raw if str(part).strip()}
        return {part.strip() for part in str(raw).split(",") if part.strip()}

+    def _dingtalk_allowed_chats(self) -> Set[str]:
+        """Return the whitelist of group chat IDs the bot will respond in.
+
+        When non-empty, group messages from chats NOT in this set are silently
+        ignored — even if the bot is @mentioned.  DMs are never filtered.
+        Empty set means no restriction (fully backward compatible).
+        """
+        raw = self.config.extra.get("allowed_chats") if self.config.extra else None
+        if raw is None:
+            raw = os.getenv("DINGTALK_ALLOWED_CHATS", "")
+        if isinstance(raw, list):
+            return {str(part).strip() for part in raw if str(part).strip()}
+        return {part.strip() for part in str(raw).split(",") if part.strip()}
+
    def _compile_mention_patterns(self) -> List[re.Pattern]:
        """Compile optional regex wake-word patterns for group triggers."""
        patterns = self.config.extra.get("mention_patterns") if self.config.extra else None
@@ -443,13 +457,21 @@ class DingTalkAdapter(BasePlatformAdapter):

        DMs remain unrestricted (subject to ``allowed_users`` which is enforced
        earlier). Group messages are accepted when:
+        - the chat passes the ``allowed_chats`` whitelist (when set)
        - the chat is explicitly allowlisted in ``free_response_chats``
        - ``require_mention`` is disabled
        - the bot is @mentioned (``is_in_at_list``)
        - the text matches a configured regex wake-word pattern
+
+        When ``allowed_chats`` is non-empty, it acts as a hard gate — messages
+        from any group chat not in the list are ignored regardless of the
+        other rules.
        """
        if not is_group:
            return True
+        allowed = self._dingtalk_allowed_chats()
+        if allowed and chat_id and chat_id not in allowed:
+            return False
        if chat_id and chat_id in self._dingtalk_free_response_chats():
            return True
        if not self._dingtalk_require_mention():
@@ -477,6 +477,34 @@ class VoiceReceiver:
                pass


+def _read_dm_role_auth_guild() -> Optional[int]:
+    """Return the guild ID opted-in for DM role-based auth, or None.
+
+    Reads ``discord.dm_role_auth_guild`` from config.yaml. This is
+    deliberately a config.yaml-only setting (not an env var): per repo
+    policy, ``~/.hermes/.env`` is for secrets only, and this is a
+    behavioral setting. Guild IDs aren't secrets.
+
+    Accepts ints or numeric strings in the config. Anything else
+    (empty, malformed, None) returns None, which keeps the secure
+    default (DM role-auth disabled).
+    """
+    try:
+        from hermes_cli.config import read_raw_config
+        cfg = read_raw_config() or {}
+        discord_cfg = cfg.get("discord", {}) or {}
+        raw = discord_cfg.get("dm_role_auth_guild")
+    except Exception:
+        return None
+    if raw is None or raw == "":
+        return None
+    try:
+        guild_id = int(raw)
+    except (TypeError, ValueError):
+        return None
+    return guild_id if guild_id > 0 else None
+
+
 class DiscordAdapter(BasePlatformAdapter):
    """
    Discord bot adapter.
@@ -701,7 +729,17 @@ class DiscordAdapter(BasePlatformAdapter):
                    # human-user allowlist below (bots aren't in it).
                else:
                    # Non-bot: enforce the configured user/role allowlists.
-                    if not self._is_allowed_user(str(message.author.id), message.author):
+                    # Pass guild + is_dm so role checks are scoped to the
+                    # originating guild (prevents cross-guild DM bypass, see
+                    # _is_allowed_user docstring).
+                    _msg_guild = getattr(message, "guild", None)
+                    _is_dm = isinstance(message.channel, discord.DMChannel) or _msg_guild is None
+                    if not self._is_allowed_user(
+                        str(message.author.id),
+                        message.author,
+                        guild=_msg_guild,
+                        is_dm=_is_dm,
+                    ):
                        return
                
                # Multi-agent filtering: if the message mentions specific bots
@@ -2063,8 +2101,16 @@ class DiscordAdapter(BasePlatformAdapter):
                        pass

                completed = receiver.check_silence()
+                # Voice inputs always originate from a specific guild
+                # (guild_id is in scope). Pass it so role checks are
+                # guild-scoped and not cross-guild.
+                _vc_guild = self._client.get_guild(guild_id) if self._client is not None else None
                for user_id, pcm_data in completed:
-                    if not self._is_allowed_user(str(user_id)):
+                    if not self._is_allowed_user(
+                        str(user_id),
+                        guild=_vc_guild,
+                        is_dm=False,
+                    ):
                        continue
                    await self._process_voice_input(guild_id, user_id, pcm_data)
        except asyncio.CancelledError:
@@ -2107,13 +2153,32 @@ class DiscordAdapter(BasePlatformAdapter):
            except OSError:
                pass

-    def _is_allowed_user(self, user_id: str, author=None) -> bool:
+    def _is_allowed_user(
+        self,
+        user_id: str,
+        author=None,
+        *,
+        guild=None,
+        is_dm: bool = False,
+    ) -> bool:
        """Check if user is allowed via DISCORD_ALLOWED_USERS or DISCORD_ALLOWED_ROLES.

        Uses OR semantics: if the user matches EITHER allowlist, they're allowed.
        If both allowlists are empty, everyone is allowed (backwards compatible).
-        When author is a Member, checks .roles directly; otherwise falls back
-        to scanning the bot's mutual guilds for a Member record.
+
+        Role checks are **scoped to the guild the message originated from**.
+        For DMs (no guild context), role-based auth is disabled by default and
+        only user-ID allowlist applies. Set ``discord.dm_role_auth_guild``
+        in config.yaml to a specific guild ID to opt-in: role membership in
+        that one guild will authorize DMs. This prevents cross-guild
+        privilege escalation where a user with the configured role in any
+        shared public server could DM the bot and pass the allowlist.
+
+        Args:
+            user_id: Author ID as a string.
+            author: Optional Member/User object for in-guild role lookup.
+            guild: The guild the message arrived in (None for DMs).
+            is_dm: True if the message came from a DM channel.
        """
        # ``getattr`` fallbacks here guard against test fixtures that build
        # an adapter via ``object.__new__(DiscordAdapter)`` and skip __init__
@@ -2124,31 +2189,54 @@ class DiscordAdapter(BasePlatformAdapter):
        has_roles = bool(allowed_roles)
        if not has_users and not has_roles:
            return True
-        # Check user ID allowlist
+        # Check user ID allowlist (works for both DMs and guild messages)
        if has_users and user_id in allowed_users:
            return True
-        # Check role allowlist
-        if has_roles:
-            # Try direct role check from Member object
-            direct_roles = getattr(author, "roles", None) if author is not None else None
-            if direct_roles:
-                if any(getattr(r, "id", None) in allowed_roles for r in direct_roles):
-                    return True
-            # Fallback: scan mutual guilds for member's roles
-            if self._client is not None:
-                try:
-                    uid_int = int(user_id)
-                except (TypeError, ValueError):
-                    uid_int = None
-                if uid_int is not None:
-                    for guild in self._client.guilds:
-                        m = guild.get_member(uid_int)
-                        if m is None:
-                            continue
-                        m_roles = getattr(m, "roles", None) or []
-                        if any(getattr(r, "id", None) in allowed_roles for r in m_roles):
-                            return True
-        return False
+        # Role allowlist is only consulted when configured.
+        if not has_roles:
+            return False
+
+        # DM path: roles require explicit opt-in via
+        # ``discord.dm_role_auth_guild`` in config.yaml. Without this, a
+        # user with the configured role in ANY mutual guild could DM the
+        # bot and bypass the allowlist (cross-guild leakage).
+        if is_dm or guild is None:
+            dm_guild_id = _read_dm_role_auth_guild()
+            if dm_guild_id is None:
+                return False
+            if self._client is None:
+                return False
+            dm_guild = self._client.get_guild(dm_guild_id)
+            if dm_guild is None:
+                return False
+            try:
+                uid_int = int(user_id)
+            except (TypeError, ValueError):
+                return False
+            m = dm_guild.get_member(uid_int)
+            if m is None:
+                return False
+            m_roles = getattr(m, "roles", None) or []
+            return any(getattr(r, "id", None) in allowed_roles for r in m_roles)
+
+        # Guild path: role check is scoped to THIS guild only.
+        # 1) Prefer the direct Member object passed in (correct guild by construction).
+        direct_roles = getattr(author, "roles", None) if author is not None else None
+        author_guild = getattr(author, "guild", None)
+        if direct_roles and (author_guild is None or author_guild.id == guild.id):
+            if any(getattr(r, "id", None) in allowed_roles for r in direct_roles):
+                return True
+        # 2) Fallback: resolve the Member in the message's guild only — NEVER
+        #    scan other mutual guilds (that is the cross-guild bypass bug).
+        try:
+            uid_int = int(user_id)
+        except (TypeError, ValueError):
+            return False
+        m = guild.get_member(uid_int)
+        if m is None:
+            return False
+        m_roles = getattr(m, "roles", None) or []
+        return any(getattr(r, "id", None) in allowed_roles for r in m_roles)

    # ── Slash command authorization ─────────────────────────────────────
    # Slash commands (``_run_simple_slash`` and ``_handle_thread_create_slash``)
@@ -2245,7 +2333,16 @@ class DiscordAdapter(BasePlatformAdapter):
            return (True, None)

        user_id = str(user.id)
-        if not self._is_allowed_user(user_id, author=user):
+        # Pass guild + is_dm so role check is scoped to the originating
+        # guild and cross-guild DM bypass (#12136) can't land via the
+        # slash surface either.
+        interaction_guild = getattr(interaction, "guild", None)
+        if not self._is_allowed_user(
+            user_id,
+            author=user,
+            guild=interaction_guild,
+            is_dm=in_dm,
+        ):
            return (
                False,
                "user not in DISCORD_ALLOWED_USERS / DISCORD_ALLOWED_ROLES",
@@ -4591,12 +4591,12 @@ def _poll_registration(
    Returns dict with app_id, app_secret, domain, open_id on success.
    Returns None on failure.
    """
-    deadline = time.time() + expire_in
+    deadline = time.monotonic() + expire_in
    current_domain = domain
    domain_switched = False
    poll_count = 0

-    while time.time() < deadline:
+    while time.monotonic() < deadline:
        base_url = _accounts_base_url(current_domain)
        try:
            res = _post_registration(base_url, {
@@ -17,7 +17,8 @@ Environment variables:
    MATRIX_REACTIONS        Set "false" to disable processing lifecycle reactions
                            (eyes/checkmark/cross). Default: true
    MATRIX_REQUIRE_MENTION      Require @mention in rooms (default: true)
-    MATRIX_FREE_RESPONSE_ROOMS  Comma-separated room IDs exempt from mention requirement
+    MATRIX_FREE_RESPONSE_ROOMS  Comma-separated room IDs exempt from mention requirement (alias of matrix.free_response_rooms)
+    MATRIX_ALLOWED_ROOMS    Comma-separated room IDs; if set, bot ONLY responds in these rooms (whitelist, DMs exempt; alias of matrix.allowed_rooms)
    MATRIX_AUTO_THREAD          Auto-create threads for room messages (default: true)
    MATRIX_DM_AUTO_THREAD       Auto-create threads for DM messages (default: false)
    MATRIX_RECOVERY_KEY         Recovery key for cross-signing verification after device key rotation
@@ -343,10 +344,29 @@ class MatrixAdapter(BasePlatformAdapter):
        self._require_mention: bool = os.getenv(
            "MATRIX_REQUIRE_MENTION", "true"
        ).lower() not in ("false", "0", "no")
-        free_rooms_raw = os.getenv("MATRIX_FREE_RESPONSE_ROOMS", "")
-        self._free_rooms: Set[str] = {
-            r.strip() for r in free_rooms_raw.split(",") if r.strip()
-        }
+        free_rooms_raw = config.extra.get("free_response_rooms")
+        if free_rooms_raw is None:
+            free_rooms_raw = os.getenv("MATRIX_FREE_RESPONSE_ROOMS", "")
+        if isinstance(free_rooms_raw, list):
+            self._free_rooms: Set[str] = {
+                str(r).strip() for r in free_rooms_raw if str(r).strip()
+            }
+        else:
+            self._free_rooms: Set[str] = {
+                r.strip() for r in str(free_rooms_raw).split(",") if r.strip()
+            }
+        # If non-empty, bot ONLY responds in these rooms (whitelist); DMs exempt.
+        allowed_rooms_raw = config.extra.get("allowed_rooms")
+        if allowed_rooms_raw is None:
+            allowed_rooms_raw = os.getenv("MATRIX_ALLOWED_ROOMS", "")
+        if isinstance(allowed_rooms_raw, list):
+            self._allowed_rooms: Set[str] = {
+                str(r).strip() for r in allowed_rooms_raw if str(r).strip()
+            }
+        else:
+            self._allowed_rooms: Set[str] = {
+                r.strip() for r in str(allowed_rooms_raw).split(",") if r.strip()
+            }
        self._auto_thread: bool = os.getenv("MATRIX_AUTO_THREAD", "true").lower() in (
            "true",
            "1",
@@ -364,6 +384,12 @@ class MatrixAdapter(BasePlatformAdapter):
            "MATRIX_REACTIONS", "true"
        ).lower() not in ("false", "0", "no")
        self._pending_reactions: dict[tuple[str, str], str] = {}
+        # Delay before redacting reactions so Matrix homeservers have time to
+        # deliver the final message event without tripping "missing event"
+        # errors in some clients.  5s is empirically safe; not user-tunable —
+        # if that changes, add a config.yaml entry rather than an env var.
+        self._reaction_redaction_delay_seconds = 5.0
+        self._reaction_redaction_tasks: Set[asyncio.Task] = set()

        # Proxy support — resolve once at init, reuse for all HTTP traffic.
        self._proxy_url: str | None = resolve_proxy_url(platform_env_var="MATRIX_PROXY")
@@ -851,6 +877,14 @@ class MatrixAdapter(BasePlatformAdapter):
            except (asyncio.CancelledError, Exception):
                pass

+        redaction_tasks = list(self._reaction_redaction_tasks)
+        for task in redaction_tasks:
+            if not task.done():
+                task.cancel()
+        if redaction_tasks:
+            await asyncio.gather(*redaction_tasks, return_exceptions=True)
+        self._reaction_redaction_tasks.clear()
+
        # Close the SQLite crypto store database.
        if hasattr(self, "_crypto_db") and self._crypto_db:
            try:
@@ -1559,6 +1593,18 @@ class MatrixAdapter(BasePlatformAdapter):

        # Require-mention gating.
        if not is_dm:
+            # allowed_rooms check (whitelist — must pass before other gating).
+            # When set, messages from rooms NOT in this whitelist are silently
+            # ignored, even if @mentioned.  DMs are already excluded above.
+            if self._allowed_rooms and room_id not in self._allowed_rooms:
+                logger.debug(
+                    "Matrix: ignoring message %s in %s — room not in "
+                    "MATRIX_ALLOWED_ROOMS whitelist",
+                    event_id,
+                    room_id,
+                )
+                return None
+
            is_free_room = room_id in self._free_rooms
            in_bot_thread = bool(thread_id and thread_id in self._threads)
            if self._require_mention and not is_free_room and not in_bot_thread:
@@ -1929,6 +1975,35 @@ class MatrixAdapter(BasePlatformAdapter):
        """Remove a reaction by redacting its event."""
        return await self.redact_message(room_id, reaction_event_id, reason)

+    def _schedule_reaction_redaction(
+        self,
+        room_id: str,
+        reaction_event_id: str,
+        reason: str = "",
+    ) -> None:
+        """Redact a reaction after a short delay so message delivery settles."""
+
+        async def _redact_later() -> None:
+            try:
+                if self._reaction_redaction_delay_seconds:
+                    await asyncio.sleep(self._reaction_redaction_delay_seconds)
+                if not await self._redact_reaction(room_id, reaction_event_id, reason):
+                    logger.debug(
+                        "Matrix: failed to redact reaction %s", reaction_event_id
+                    )
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                logger.debug(
+                    "Matrix: delayed reaction redaction failed for %s: %s",
+                    reaction_event_id,
+                    exc,
+                )
+
+        task = asyncio.create_task(_redact_later())
+        self._reaction_redaction_tasks.add(task)
+        task.add_done_callback(self._reaction_redaction_tasks.discard)
+
    async def on_processing_start(self, event: MessageEvent) -> None:
        """Add eyes reaction when the agent starts processing a message."""
        if not self._reactions_enabled:
@@ -1957,8 +2032,11 @@ class MatrixAdapter(BasePlatformAdapter):
        reaction_key = (room_id, msg_id)
        if reaction_key in self._pending_reactions:
            eyes_event_id = self._pending_reactions.pop(reaction_key)
-            if not await self._redact_reaction(room_id, eyes_event_id):
-                logger.debug("Matrix: failed to redact eyes reaction %s", eyes_event_id)
+            self._schedule_reaction_redaction(
+                room_id,
+                eyes_event_id,
+                "processing complete",
+            )
        await self._send_reaction(
            room_id,
            msg_id,
@@ -2037,11 +2115,8 @@ class MatrixAdapter(BasePlatformAdapter):
    ) -> None:
        """Redact the bot's seed ✅/❎ reactions, leaving only the user's reaction."""
        for emoji, evt_id in prompt.bot_reaction_events.items():
-            try:
-                await self.redact_message(room_id, evt_id, "approval resolved")
-                logger.debug("Matrix: redacted bot reaction %s (%s)", emoji, evt_id)
-            except Exception as exc:
-                logger.debug("Matrix: failed to redact bot reaction %s: %s", emoji, exc)
+            self._schedule_reaction_redaction(room_id, evt_id, "approval resolved")
+            logger.debug("Matrix: scheduled bot reaction redaction %s (%s)", emoji, evt_id)

    # ------------------------------------------------------------------
    # Text message aggregation (handles Matrix client-side splits)
@@ -706,10 +706,30 @@ class MattermostAdapter(BasePlatformAdapter):
        message_text = post.get("message", "")

        # Mention-gating for non-DM channels.
-        # Config (env vars):
-        #   MATTERMOST_REQUIRE_MENTION: Require @mention in channels (default: true)
-        #   MATTERMOST_FREE_RESPONSE_CHANNELS: Channel IDs where bot responds without mention
+        # Config (config.yaml `mattermost.*` with env-var fallback):
+        #   require_mention / MATTERMOST_REQUIRE_MENTION: Require @mention in channels (default: true)
+        #   free_response_channels / MATTERMOST_FREE_RESPONSE_CHANNELS: Channel IDs where bot responds without mention
+        #   allowed_channels / MATTERMOST_ALLOWED_CHANNELS: If set, bot ONLY responds in these channels (whitelist)
        if channel_type_raw != "D":
+            # allowed_channels check (whitelist — must pass before other gating).
+            # When set, messages from channels NOT in this list are silently
+            # ignored, even if @mentioned.  DMs are already excluded above.
+            allowed_raw = self.config.extra.get("allowed_channels") if self.config.extra else None
+            if allowed_raw is None:
+                allowed_raw = os.getenv("MATTERMOST_ALLOWED_CHANNELS", "")
+            if isinstance(allowed_raw, list):
+                allowed_channels = {str(c).strip() for c in allowed_raw if str(c).strip()}
+            else:
+                allowed_channels = {
+                    c.strip() for c in str(allowed_raw).split(",") if c.strip()
+                }
+            if allowed_channels and channel_id not in allowed_channels:
+                logger.debug(
+                    "Mattermost: ignoring message in non-allowed channel: %s",
+                    channel_id,
+                )
+                return
+
            require_mention = os.getenv(
                "MATTERMOST_REQUIRE_MENTION", "true"
            ).lower() not in ("false", "0", "no")
@@ -34,6 +34,27 @@ from .crypto import decrypt_secret, generate_bind_key  # noqa: F401
 # -- Utils -----------------------------------------------------------------
 from .utils import build_user_agent, get_api_headers, coerce_list  # noqa: F401

+# -- Chunked upload --------------------------------------------------------
+from .chunked_upload import (  # noqa: F401
+    ChunkedUploader,
+    UploadDailyLimitExceededError,
+    UploadFileTooLargeError,
+)
+
+# -- Inline keyboards ------------------------------------------------------
+from .keyboards import (  # noqa: F401
+    ApprovalRequest,
+    ApprovalSender,
+    InlineKeyboard,
+    InteractionEvent,
+    build_approval_keyboard,
+    build_approval_text,
+    build_update_prompt_keyboard,
+    parse_approval_button_data,
+    parse_interaction_event,
+    parse_update_prompt_button_data,
+)
+
 __all__ = [
    # adapter
    "QQAdapter",
@@ -52,4 +73,19 @@ __all__ = [
    "build_user_agent",
    "get_api_headers",
    "coerce_list",
+    # chunked upload
+    "ChunkedUploader",
+    "UploadDailyLimitExceededError",
+    "UploadFileTooLargeError",
+    # keyboards
+    "ApprovalRequest",
+    "ApprovalSender",
+    "InlineKeyboard",
+    "InteractionEvent",
+    "build_approval_keyboard",
+    "build_approval_text",
+    "build_update_prompt_keyboard",
+    "parse_approval_button_data",
+    "parse_interaction_event",
+    "parse_update_prompt_button_data",
 ]
@@ -41,7 +41,7 @@ import time
 import uuid
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Tuple
 from urllib.parse import urlparse

 try:
@@ -119,6 +119,22 @@ from gateway.platforms.qqbot.utils import (
    coerce_list as _coerce_list_impl,
    build_user_agent,
 )
+from gateway.platforms.qqbot.chunked_upload import (
+    ChunkedUploader,
+    UploadDailyLimitExceededError,
+    UploadFileTooLargeError,
+)
+from gateway.platforms.qqbot.keyboards import (
+    ApprovalRequest,
+    ApprovalSender,
+    InlineKeyboard,
+    InteractionEvent,
+    build_approval_keyboard,
+    build_update_prompt_keyboard,
+    parse_approval_button_data,
+    parse_interaction_event,
+    parse_update_prompt_button_data,
+)


 def check_qq_requirements() -> bool:
@@ -208,6 +224,22 @@ class QQAdapter(BasePlatformAdapter):
        # Upload cache: content_hash -> {file_info, file_uuid, expires_at}
        self._upload_cache: Dict[str, Dict[str, Any]] = {}

+        # Inline-keyboard interaction routing. The callback (if set) is invoked
+        # for every INTERACTION_CREATE event after the adapter has already
+        # ACKed it. Callers (gateway wiring for approvals / update prompts)
+        # register via set_interaction_callback().
+        self._interaction_callback: Optional[
+            Callable[[InteractionEvent], Awaitable[None]]
+        ] = None
+
+        # Default interaction dispatcher: routes approval-button clicks to
+        # tools.approval.resolve_gateway_approval() and update-prompt clicks
+        # to ~/.hermes/.update_response. Set here so the cross-adapter gateway
+        # contract (send_exec_approval / send_update_prompt) works out of the
+        # box; callers can override with set_interaction_callback(None) or
+        # register a custom handler.
+        self._interaction_callback = self._default_interaction_dispatch
+
    # ------------------------------------------------------------------
    # Properties
    # ------------------------------------------------------------------
@@ -759,6 +791,8 @@ class QQAdapter(BasePlatformAdapter):
                    "GUILD_AT_MESSAGE_CREATE",
            ):
                asyncio.create_task(self._on_message(t, d))
+            elif t == "INTERACTION_CREATE":
+                self._create_task(self._on_interaction(d))
            else:
                logger.debug("[%s] Unhandled dispatch: %s", self._log_tag, t)
            return
@@ -832,6 +866,206 @@ class QQAdapter(BasePlatformAdapter):
        elif event_type == "DIRECT_MESSAGE_CREATE":
            await self._handle_dm_message(d, msg_id, content, author, timestamp)

+    # ------------------------------------------------------------------
+    # Inline-keyboard interactions (INTERACTION_CREATE)
+    # ------------------------------------------------------------------
+
+    def set_interaction_callback(
+        self,
+        callback: Optional[Callable[[InteractionEvent], Awaitable[None]]],
+    ) -> None:
+        """Register (or clear) the interaction callback.
+
+        Invoked once per ``INTERACTION_CREATE`` event *after* the adapter has
+        ACKed the interaction. The callback is responsible for routing the
+        button click to the right subsystem (approval resolver, update-prompt
+        resolver, etc.) based on the ``button_data`` payload.
+        """
+        self._interaction_callback = callback
+
+    async def _on_interaction(self, d: Any) -> None:
+        """Handle an ``INTERACTION_CREATE`` event.
+
+        Responsibilities:
+
+        1. Parse the raw payload into an :class:`InteractionEvent`.
+        2. ACK the interaction (``PUT /interactions/{id}``) so the client
+           stops showing a loading indicator on the button.
+        3. Dispatch to the registered interaction callback, if any.
+        """
+        if not isinstance(d, dict):
+            return
+        try:
+            event = parse_interaction_event(d)
+        except Exception as exc:
+            logger.warning(
+                "[%s] Failed to parse INTERACTION_CREATE: %s", self._log_tag, exc
+            )
+            return
+
+        if not event.id:
+            logger.warning(
+                "[%s] INTERACTION_CREATE missing id, skipping ACK", self._log_tag
+            )
+            return
+
+        # ACK the interaction promptly — per the QQ docs the client will show
+        # an error icon on the button if we don't respond quickly.
+        try:
+            await self._acknowledge_interaction(event.id)
+        except Exception as exc:
+            logger.warning(
+                "[%s] Failed to ACK interaction %s: %s",
+                self._log_tag, event.id, exc,
+            )
+
+        logger.info(
+            "[%s] Interaction: scene=%s button_data=%r operator=%s",
+            self._log_tag, event.scene, event.button_data, event.operator_openid,
+        )
+
+        callback = self._interaction_callback
+        if callback is None:
+            logger.debug(
+                "[%s] No interaction callback registered; dropping button "
+                "click %r",
+                self._log_tag, event.button_data,
+            )
+            return
+        try:
+            await callback(event)
+        except Exception as exc:
+            logger.error(
+                "[%s] Interaction callback raised: %s",
+                self._log_tag, exc, exc_info=True,
+            )
+
+    async def _acknowledge_interaction(
+            self,
+            interaction_id: str,
+            code: int = 0,
+    ) -> None:
+        """ACK a button interaction via ``PUT /interactions/{id}``.
+
+        :param interaction_id: The ``id`` field from the
+            ``INTERACTION_CREATE`` event.
+        :param code: Response code (``0`` = success).
+        """
+        if not self._http_client:
+            raise RuntimeError("HTTP client not initialized — not connected?")
+        token = await self._ensure_token()
+        headers = {
+            "Authorization": f"QQBot {token}",
+            "Content-Type": "application/json",
+            "User-Agent": build_user_agent(),
+        }
+        resp = await self._http_client.put(
+            f"{API_BASE}/interactions/{interaction_id}",
+            headers=headers,
+            json={"code": code},
+            timeout=DEFAULT_API_TIMEOUT,
+        )
+        if resp.status_code >= 400:
+            raise RuntimeError(
+                f"Interaction ACK failed [{resp.status_code}]: "
+                f"{resp.text[:200]}"
+            )
+
+    # Mapping from QQ keyboard button decisions → the ``choice`` vocabulary
+    # accepted by ``tools.approval.resolve_gateway_approval``. QQ's 3-button
+    # layout (mobile-space constraint) collapses "session" and "always" into
+    # a single "always" button; users wanting session-only approval can fall
+    # back to the ``/approve session`` text command.
+    _APPROVAL_BUTTON_TO_CHOICE = {
+        "allow-once": "once",
+        "allow-always": "always",
+        "deny": "deny",
+    }
+
+    async def _default_interaction_dispatch(
+            self,
+            event: InteractionEvent,
+    ) -> None:
+        """Route ``INTERACTION_CREATE`` button clicks to the right subsystem.
+
+        - ``approve:<session_key>:<decision>`` →
+          :func:`tools.approval.resolve_gateway_approval`
+          (unblocks the agent thread waiting on a dangerous-command approval).
+        - ``update_prompt:<answer>`` →
+          writes the answer to ``~/.hermes/.update_response`` for the
+          detached ``hermes update --gateway`` process to consume.
+        - Anything else is logged at DEBUG and ignored.
+
+        Installed as the adapter's default interaction callback in
+        ``__init__``. Callers can replace via
+        :meth:`set_interaction_callback` to route clicks elsewhere (or pass
+        ``None`` to drop them entirely).
+        """
+        button_data = event.button_data
+        if not button_data:
+            return
+
+        approval = parse_approval_button_data(button_data)
+        if approval is not None:
+            session_key, decision = approval
+            choice = self._APPROVAL_BUTTON_TO_CHOICE.get(decision)
+            if choice is None:
+                logger.warning(
+                    "[%s] Unknown approval decision %r (session=%s)",
+                    self._log_tag, decision, session_key,
+                )
+                return
+            try:
+                # Import lazily to keep the adapter importable in tests that
+                # don't exercise the approval subsystem.
+                from tools.approval import resolve_gateway_approval
+                count = resolve_gateway_approval(session_key, choice)
+                logger.info(
+                    "[%s] Button resolved %d approval(s) for session %s "
+                    "(choice=%s, operator=%s)",
+                    self._log_tag, count, session_key, choice,
+                    event.operator_openid,
+                )
+            except Exception as exc:
+                logger.error(
+                    "[%s] resolve_gateway_approval failed for session %s: %s",
+                    self._log_tag, session_key, exc,
+                )
+            return
+
+        update_answer = parse_update_prompt_button_data(button_data)
+        if update_answer is not None:
+            self._write_update_response(update_answer, event.operator_openid)
+            return
+
+        logger.debug(
+            "[%s] Unrecognised button_data %r from interaction %s",
+            self._log_tag, button_data, event.id,
+        )
+
+    @staticmethod
+    def _write_update_response(answer: str, operator: str = "") -> None:
+        """Atomically write the update-prompt answer to ``.update_response``.
+
+        Mirrors the Discord / Telegram / Feishu adapters: the detached
+        ``hermes update --gateway`` watcher polls this file for a ``y``/``n``
+        response to its interactive prompts (stash-restore, config migration).
+        Writes via ``tmp + rename`` so a partial write can't fool the reader.
+        """
+        try:
+            from hermes_constants import get_hermes_home
+            home = get_hermes_home()
+            response_path = home / ".update_response"
+            tmp = response_path.with_suffix(".tmp")
+            tmp.write_text(answer)
+            tmp.replace(response_path)
+            logger.info(
+                "QQ update prompt answered %r by %s",
+                answer, operator or "(unknown)",
+            )
+        except Exception as exc:
+            logger.error("Failed to write update response: %s", exc)
+
    async def _handle_c2c_message(
            self,
            d: Dict[str, Any],
@@ -900,6 +1134,13 @@ class QQAdapter(BasePlatformAdapter):
            len(voice_transcripts),
        )

+        # Merge any quoted-message context (message_type=103 → msg_elements[0]).
+        quoted = await self._process_quoted_context(d)
+        text = self._merge_quote_into(text, quoted["quote_block"])
+        if quoted["image_urls"]:
+            image_urls = image_urls + quoted["image_urls"]
+            image_media_types = image_media_types + quoted["image_media_types"]
+
        if not text.strip() and not image_urls:
            return

@@ -958,6 +1199,13 @@ class QQAdapter(BasePlatformAdapter):
                else attachment_info
            )

+        # Merge any quoted-message context (message_type=103 → msg_elements[0]).
+        quoted = await self._process_quoted_context(d)
+        text = self._merge_quote_into(text, quoted["quote_block"])
+        if quoted["image_urls"]:
+            image_urls = image_urls + quoted["image_urls"]
+            image_media_types = image_media_types + quoted["image_media_types"]
+
        if not text.strip() and not image_urls:
            return

@@ -1025,6 +1273,13 @@ class QQAdapter(BasePlatformAdapter):
                else attachment_info
            )

+        # Merge any quoted-message context (message_type=103 → msg_elements[0]).
+        quoted = await self._process_quoted_context(d)
+        text = self._merge_quote_into(text, quoted["quote_block"])
+        if quoted["image_urls"]:
+            image_urls = image_urls + quoted["image_urls"]
+            image_media_types = image_media_types + quoted["image_media_types"]
+
        if not text.strip() and not image_urls:
            return

@@ -1089,6 +1344,13 @@ class QQAdapter(BasePlatformAdapter):
                else attachment_info
            )

+        # Merge any quoted-message context (message_type=103 → msg_elements[0]).
+        quoted = await self._process_quoted_context(d)
+        text = self._merge_quote_into(text, quoted["quote_block"])
+        if quoted["image_urls"]:
+            image_urls = image_urls + quoted["image_urls"]
+            image_media_types = image_media_types + quoted["image_media_types"]
+
        if not text.strip() and not image_urls:
            return

@@ -1109,6 +1371,113 @@ class QQAdapter(BasePlatformAdapter):
        )
        await self.handle_message(event)

+    # ------------------------------------------------------------------
+    # Quoted-message handling
+    # ------------------------------------------------------------------
+
+    async def _process_quoted_context(
+            self,
+            d: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Process the quoted message a user is replying to.
+
+        When a user replies while quoting another message, the platform sets
+        ``message_type = 103`` and pushes the referenced message's content and
+        attachments inside ``msg_elements[0]``. The old adapter ignored
+        ``msg_elements`` entirely, so:
+
+        - Quoted text was surfaced only when the user typed something of
+          their own — bare quote-replies showed nothing.
+        - Quoted attachments (images, voice, files) were never downloaded
+          or described.
+        - Quoted voice messages specifically produced no transcript, so the
+          LLM had no way to see what the user was referring to.
+
+        This method parses ``msg_elements`` and runs the quoted attachments
+        through the same :meth:`_process_attachments` pipeline as the main
+        message body, so quoted voice messages get STT transcripts and
+        quoted images are cached identically.
+
+        :param d: Raw inbound message dict (from the WS dispatch payload).
+        :returns: Dict with keys:
+
+            - ``quote_block``: string to prepend to the user's text body
+              (empty when there's nothing quoted).
+            - ``image_urls``: list of cached quoted-image paths.
+            - ``image_media_types``: parallel list of image MIME types.
+        """
+        empty = {
+            "quote_block": "",
+            "image_urls": [],
+            "image_media_types": [],
+        }
+        # Short-circuit: only message_type 103 indicates a quote.
+        try:
+            if int(d.get("message_type", 0) or 0) != 103:
+                return empty
+        except (TypeError, ValueError):
+            return empty
+
+        elements = d.get("msg_elements")
+        if not isinstance(elements, list) or not elements:
+            return empty
+
+        # msg_elements[0] carries the referenced message. Additional elements
+        # (if any) are very rare in practice; we concatenate their text and
+        # union their attachments for completeness.
+        quoted_text_parts: List[str] = []
+        all_attachments: List[Dict[str, Any]] = []
+        for elem in elements:
+            if not isinstance(elem, dict):
+                continue
+            etext = str(elem.get("content", "")).strip()
+            if etext:
+                quoted_text_parts.append(etext)
+            eatts = elem.get("attachments")
+            if isinstance(eatts, list):
+                for a in eatts:
+                    if isinstance(a, dict):
+                        all_attachments.append(a)
+
+        att_result = await self._process_attachments(all_attachments)
+        quoted_voice = att_result.get("voice_transcripts") or []
+        quoted_info = att_result.get("attachment_info") or ""
+        quoted_images = att_result.get("image_urls") or []
+        quoted_image_types = att_result.get("image_media_types") or []
+
+        lines: List[str] = []
+        if quoted_text_parts:
+            lines.append(" ".join(quoted_text_parts))
+        for t in quoted_voice:
+            lines.append(t)
+        if quoted_info:
+            lines.append(quoted_info)
+
+        if not lines and not quoted_images:
+            return empty
+
+        if lines:
+            quote_block = "[Quoted message]:\n" + "\n".join(lines)
+        else:
+            # Images-only quote: give the LLM at least a marker so it knows
+            # context was referenced.
+            quote_block = "[Quoted message]: (image)"
+
+        return {
+            "quote_block": quote_block,
+            "image_urls": quoted_images,
+            "image_media_types": quoted_image_types,
+        }
+
+    @staticmethod
+    def _merge_quote_into(text: str, quote_block: str) -> str:
+        """Prepend ``quote_block`` to *text*, separated by a blank line."""
+        if not quote_block:
+            return text
+        if text.strip():
+            return f"{quote_block}\n\n{text}".strip()
+        return quote_block
+
    # ------------------------------------------------------------------
    # Attachment processing
    # ------------------------------------------------------------------
@@ -1992,26 +2361,44 @@ class QQAdapter(BasePlatformAdapter):
        return SendResult(success=False, error=error_msg, retryable=retryable)

    async def _send_c2c_text(
-            self, openid: str, content: str, reply_to: Optional[str] = None
+            self,
+            openid: str,
+            content: str,
+            reply_to: Optional[str] = None,
+            keyboard: Optional[InlineKeyboard] = None,
    ) -> SendResult:
-        """Send text to a C2C user via REST API."""
+        """Send text to a C2C user via REST API.
+
+        :param keyboard: Optional inline keyboard attached to the message.
+        """
        self._next_msg_seq(reply_to or openid)
        body = self._build_text_body(content, reply_to)
        if reply_to:
            body["msg_id"] = reply_to
+        if keyboard is not None:
+            body["keyboard"] = keyboard.to_dict()

        data = await self._api_request("POST", f"/v2/users/{openid}/messages", body)
        msg_id = str(data.get("id", uuid.uuid4().hex[:12]))
        return SendResult(success=True, message_id=msg_id, raw_response=data)

    async def _send_group_text(
-            self, group_openid: str, content: str, reply_to: Optional[str] = None
+            self,
+            group_openid: str,
+            content: str,
+            reply_to: Optional[str] = None,
+            keyboard: Optional[InlineKeyboard] = None,
    ) -> SendResult:
-        """Send text to a group via REST API."""
+        """Send text to a group via REST API.
+
+        :param keyboard: Optional inline keyboard attached to the message.
+        """
        self._next_msg_seq(reply_to or group_openid)
        body = self._build_text_body(content, reply_to)
        if reply_to:
            body["msg_id"] = reply_to
+        if keyboard is not None:
+            body["keyboard"] = keyboard.to_dict()

        data = await self._api_request(
            "POST", f"/v2/groups/{group_openid}/messages", body
@@ -2031,6 +2418,156 @@ class QQAdapter(BasePlatformAdapter):
        msg_id = str(data.get("id", uuid.uuid4().hex[:12]))
        return SendResult(success=True, message_id=msg_id, raw_response=data)

+    # ------------------------------------------------------------------
+    # Inline-keyboard outbound helpers (approval / update-prompt flows)
+    # ------------------------------------------------------------------
+
+    async def send_with_keyboard(
+            self,
+            chat_id: str,
+            content: str,
+            keyboard: InlineKeyboard,
+            reply_to: Optional[str] = None,
+    ) -> SendResult:
+        """Send a single text message with an inline keyboard attached.
+
+        Unlike :meth:`send`, this does NOT split long content into chunks —
+        a keyboard message has exactly one interactive surface, and splitting
+        would orphan the buttons from the first chunk. Callers should keep
+        approval/update-prompt bodies short.
+
+        Guild (channel) chats don't support inline keyboards; returns a
+        non-retryable failure for those.
+        """
+        if not self.is_connected:
+            if not await self._wait_for_reconnection():
+                return SendResult(
+                    success=False, error="Not connected", retryable=True
+                )
+
+        chat_type = self._guess_chat_type(chat_id)
+        formatted = self.format_message(content)
+        truncated = formatted[: self.MAX_MESSAGE_LENGTH]
+        try:
+            if chat_type == "c2c":
+                return await self._send_c2c_text(
+                    chat_id, truncated, reply_to, keyboard=keyboard,
+                )
+            if chat_type == "group":
+                return await self._send_group_text(
+                    chat_id, truncated, reply_to, keyboard=keyboard,
+                )
+            return SendResult(
+                success=False,
+                error=(
+                    f"Inline keyboards not supported for chat_type "
+                    f"{chat_type!r}"
+                ),
+                retryable=False,
+            )
+        except Exception as exc:
+            logger.error(
+                "[%s] send_with_keyboard failed: %s", self._log_tag, exc
+            )
+            return SendResult(success=False, error=str(exc))
+
+    async def send_approval_request(
+            self,
+            chat_id: str,
+            req: ApprovalRequest,
+            reply_to: Optional[str] = None,
+    ) -> SendResult:
+        """Send a 3-button approval request (``allow-once / allow-always / deny``).
+
+        The rendered text comes from :func:`build_approval_text`; callers can
+        override by passing a custom :class:`ApprovalRequest`.
+
+        Users click the button → ``INTERACTION_CREATE`` fires → the adapter's
+        registered :meth:`set_interaction_callback` handler decodes
+        ``button_data`` via :func:`parse_approval_button_data`.
+        """
+        from gateway.platforms.qqbot.keyboards import build_approval_text
+        return await self.send_with_keyboard(
+            chat_id,
+            build_approval_text(req),
+            build_approval_keyboard(req.session_key),
+            reply_to=reply_to,
+        )
+
+    # ------------------------------------------------------------------
+    # Cross-adapter gateway contract — send_exec_approval + send_update_prompt
+    # ------------------------------------------------------------------
+    #
+    # These mirror the signatures that gateway/run.py detects on the adapter
+    # class (e.g. type(adapter).send_exec_approval, type(adapter).send_update_prompt)
+    # for button-based approval / update-confirm UX. Discord, Telegram, Slack,
+    # Matrix, and Feishu already implement the same contract.
+
+    async def send_exec_approval(
+            self,
+            chat_id: str,
+            command: str,
+            session_key: str,
+            description: str = "dangerous command",
+            metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Send a button-based exec-approval prompt for a dangerous command.
+
+        Called by ``gateway/run.py``'s ``_approval_notify_sync`` when the
+        agent is blocked waiting for approval. Button clicks resolve via
+        :func:`tools.approval.resolve_gateway_approval` — dispatched by the
+        adapter's interaction callback (:meth:`_default_interaction_dispatch`).
+        """
+        del metadata  # QQ doesn't have thread_id / DM targeting overrides.
+
+        # Use the reply-to message for passive-message context when we have one.
+        # QQ requires a msg_id on outbound messages to a user we've never
+        # seen; the last inbound msg_id is the natural choice.
+        msg_id = self._last_msg_id.get(chat_id)
+
+        req = ApprovalRequest(
+            session_key=session_key,
+            title=f"Execute this command?",
+            description=description,
+            command_preview=command,
+            timeout_sec=self._APPROVAL_TIMEOUT_SECONDS,
+        )
+        return await self.send_approval_request(
+            chat_id, req, reply_to=msg_id,
+        )
+
+    _APPROVAL_TIMEOUT_SECONDS = 300  # matches gateway's default gateway_timeout
+
+    async def send_update_prompt(
+            self,
+            chat_id: str,
+            prompt: str,
+            default: str = "",
+            session_key: str = "",
+            metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Send a Yes/No update-confirmation prompt with inline buttons.
+
+        Matches the cross-adapter contract used by
+        ``gateway/run.py``'s ``hermes update --gateway`` watcher. Button
+        clicks surface as ``INTERACTION_CREATE`` with
+        ``button_data = 'update_prompt:y'`` or ``'update_prompt:n'``;
+        the adapter's interaction callback writes the answer to
+        ``~/.hermes/.update_response`` so the detached update process
+        can read it.
+        """
+        del session_key, metadata  # present for contract parity only.
+
+        default_hint = f" (default: {default})" if default else ""
+        content = f"⚕ **Update Needs Your Input**\n\n{prompt}{default_hint}"
+        msg_id = self._last_msg_id.get(chat_id)
+        return await self.send_with_keyboard(
+            chat_id,
+            content,
+            build_update_prompt_keyboard(),
+            reply_to=msg_id,
+        )
+
    def _build_text_body(
            self, content: str, reply_to: Optional[str] = None
    ) -> Dict[str, Any]:
@@ -2160,42 +2697,62 @@ class QQAdapter(BasePlatformAdapter):
            reply_to: Optional[str] = None,
            file_name: Optional[str] = None,
    ) -> SendResult:
-        """Upload media and send as a native message."""
+        """Upload media and send as a native message.
+
+        Upload strategy:
+
+        - **HTTP(S) URLs** → single ``POST /v2/{users|groups}/{id}/files``
+          with ``url=...``. The QQ platform fetches the URL directly; fastest
+          path when the source is already hosted.
+        - **Local files** → three-step chunked upload (prepare / PUT parts /
+          complete). Handles files up to the platform's ~100 MB per-file
+          limit without the ~10 MB inline-base64 cap of the old adapter.
+        """
        if not self.is_connected:
            if not await self._wait_for_reconnection():
                return SendResult(success=False, error="Not connected", retryable=True)

-        try:
-            # Resolve media source
-            data, content_type, resolved_name = await self._load_media(
-                media_source, file_name
+        chat_type = self._guess_chat_type(chat_id)
+        if chat_type == "guild":
+            # Guild channels don't support native media upload in the same way.
+            return SendResult(
+                success=False,
+                error="Guild media send not supported via this path",
            )

-            # Route
-            chat_type = self._guess_chat_type(chat_id)
-
-            if chat_type == "guild":
-                # Guild channels don't support native media upload in the same way
-                # Send as URL fallback
-                return SendResult(
-                    success=False, error="Guild media send not supported via this path"
+        try:
+            if self._is_url(media_source):
+                # URL upload — let the platform fetch it directly.
+                resolved_name = (
+                    file_name
+                    or Path(urlparse(media_source).path).name
+                    or "media"
+                )
+                upload = await self._upload_media(
+                    chat_type,
+                    chat_id,
+                    file_type,
+                    url=media_source,
+                    srv_send_msg=False,
+                    file_name=resolved_name if file_type == MEDIA_TYPE_FILE else None,
+                )
+            else:
+                # Local file — chunked upload (prepare / PUT parts / complete).
+                resolved_name, upload = await self._upload_local_file(
+                    chat_type,
+                    chat_id,
+                    media_source,
+                    file_type,
+                    file_name,
                )

-            # Upload
-            upload = await self._upload_media(
-                chat_type,
-                chat_id,
-                file_type,
-                file_data=data if not self._is_url(media_source) else None,
-                url=media_source if self._is_url(media_source) else None,
-                srv_send_msg=False,
-                file_name=resolved_name if file_type == MEDIA_TYPE_FILE else None,
-            )
-
-            file_info = upload.get("file_info")
+            file_info = upload.get("file_info") or (
+                upload.get("data", {}) or {}
+            ).get("file_info")
            if not file_info:
                return SendResult(
-                    success=False, error=f"Upload returned no file_info: {upload}"
+                    success=False,
+                    error=f"Upload returned no file_info: {upload}",
                )

            # Send media message
@@ -2224,10 +2781,86 @@ class QQAdapter(BasePlatformAdapter):
                message_id=str(send_data.get("id", uuid.uuid4().hex[:12])),
                raw_response=send_data,
            )
+        except UploadDailyLimitExceededError as exc:
+            # Non-retryable: daily quota hit. Give the caller actionable text
+            # so the model can compose a helpful reply.
+            logger.warning(
+                "[%s] Daily upload limit exceeded for %s (%s)",
+                self._log_tag, exc.file_name, exc.file_size_human,
+            )
+            return SendResult(
+                success=False,
+                error=(
+                    f"QQ daily upload limit exceeded for {exc.file_name!r} "
+                    f"({exc.file_size_human}). Retry tomorrow."
+                ),
+                retryable=False,
+            )
+        except UploadFileTooLargeError as exc:
+            logger.warning(
+                "[%s] File too large: %s (%s, platform limit %s)",
+                self._log_tag, exc.file_name, exc.file_size_human, exc.limit_human,
+            )
+            return SendResult(
+                success=False,
+                error=(
+                    f"{exc.file_name!r} ({exc.file_size_human}) exceeds the "
+                    f"QQ per-file upload limit ({exc.limit_human})."
+                ),
+                retryable=False,
+            )
        except Exception as exc:
            logger.error("[%s] Media send failed: %s", self._log_tag, exc)
            return SendResult(success=False, error=str(exc))

+    async def _upload_local_file(
+            self,
+            chat_type: str,
+            chat_id: str,
+            media_source: str,
+            file_type: int,
+            file_name: Optional[str],
+    ) -> Tuple[str, Dict[str, Any]]:
+        """Chunked-upload a local file and return ``(resolved_name, complete_response)``.
+
+        The returned ``complete_response`` contains the ``file_info`` token
+        that goes into the subsequent RichMedia message body.
+
+        :raises UploadDailyLimitExceededError: On biz_code 40093002.
+        :raises UploadFileTooLargeError: When the file exceeds the platform limit.
+        :raises FileNotFoundError: If the path does not exist.
+        :raises ValueError: If the path looks like a placeholder (``<path>``).
+        :raises RuntimeError: If the HTTP client is not initialized.
+        """
+        if not self._http_client:
+            raise RuntimeError("HTTP client not initialized — not connected?")
+
+        local_path = Path(media_source).expanduser()
+        if not local_path.is_absolute():
+            local_path = (Path.cwd() / local_path).resolve()
+
+        if not local_path.exists() or not local_path.is_file():
+            if media_source.startswith("<") or len(media_source) < 3:
+                raise ValueError(
+                    f"Invalid media source (looks like a placeholder): {media_source!r}"
+                )
+            raise FileNotFoundError(f"Media file not found: {local_path}")
+
+        resolved_name = file_name or local_path.name
+        uploader = ChunkedUploader(
+            api_request=self._api_request,
+            http_put=self._http_client.put,
+            log_tag=self._log_tag,
+        )
+        complete = await uploader.upload(
+            chat_type=chat_type,
+            target_id=chat_id,
+            file_path=str(local_path),
+            file_type=file_type,
+            file_name=resolved_name,
+        )
+        return resolved_name, complete
+
    async def _load_media(
            self, source: str, file_name: Optional[str] = None
    ) -> Tuple[str, str, str]:
@@ -0,0 +1,603 @@
+"""QQ Bot chunked upload flow.
+
+The QQ v2 API caps inline base64 uploads (``file_data`` / ``url``) at ~10 MB.
+For files between 10 MB and ~100 MB we have to use the three-step chunked
+upload flow::
+
+    1. POST /v2/{users|groups}/{id}/upload_prepare
+       → returns upload_id, block_size, and an array of pre-signed COS part URLs.
+    2. For each part:
+         PUT the part bytes to its pre-signed COS URL,
+         then POST /v2/{users|groups}/{id}/upload_part_finish to acknowledge.
+    3. POST /v2/{users|groups}/{id}/files with {"upload_id": ...}
+       → returns the ``file_info`` token the caller uses in a RichMedia
+       message.
+
+Error-code semantics (from the QQ Bot v2 API spec):
+
+- ``40093001`` — ``upload_part_finish`` retryable. Retry until the server-provided
+  ``retry_timeout`` elapses (or a local cap).
+- ``40093002`` — daily cumulative upload quota exceeded. Not retryable; surface
+  as :class:`UploadDailyLimitExceededError` so the caller can build a
+  user-friendly reply.
+
+Exceptions:
+
+- :class:`UploadDailyLimitExceededError` — daily quota hit (non-retryable).
+- :class:`UploadFileTooLargeError` — file exceeds the platform per-file limit.
+- :class:`RuntimeError` — generic upload failure (network, part PUT, complete).
+
+Ported from WideLee's qqbot-agent-sdk v1.2.2 (``media_loader.py::ChunkedUploader``)
+so the heavy-upload path stays in-tree. Authorship preserved via Co-authored-by.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import hashlib
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+
+from gateway.platforms.qqbot.constants import FILE_UPLOAD_TIMEOUT
+
+logger = logging.getLogger(__name__)
+
+
+# ── Error codes ──────────────────────────────────────────────────────
+_BIZ_CODE_DAILY_LIMIT = 40093002     # upload_prepare: daily cumulative limit
+_BIZ_CODE_PART_RETRYABLE = 40093001  # upload_part_finish: transient
+
+# ── Part upload tuning ───────────────────────────────────────────────
+_DEFAULT_CONCURRENT_PARTS = 1
+_MAX_CONCURRENT_PARTS = 10
+
+_PART_UPLOAD_TIMEOUT = 300.0        # 5 minutes per COS PUT
+_PART_UPLOAD_MAX_RETRIES = 2
+_PART_FINISH_RETRY_INTERVAL = 1.0
+_PART_FINISH_DEFAULT_TIMEOUT = 120.0
+_PART_FINISH_MAX_TIMEOUT = 600.0
+
+_COMPLETE_UPLOAD_MAX_RETRIES = 2
+_COMPLETE_UPLOAD_BASE_DELAY = 2.0
+
+# First 10,002,432 bytes used for the ``md5_10m`` hash (per QQ API spec).
+_MD5_10M_SIZE = 10_002_432
+
+
+# ── Exceptions ───────────────────────────────────────────────────────
+
+class UploadDailyLimitExceededError(Exception):
+    """Raised when ``upload_prepare`` returns biz_code 40093002.
+
+    The daily cumulative upload quota for this bot has been reached. Callers
+    should surface :attr:`file_name` + :attr:`file_size_human` so the model
+    can compose a helpful reply.
+    """
+
+    def __init__(self, file_name: str, file_size: int, message: str = "") -> None:
+        self.file_name = file_name
+        self.file_size = file_size
+        super().__init__(
+            message or f"Daily upload limit exceeded for {file_name!r}"
+        )
+
+    @property
+    def file_size_human(self) -> str:
+        return format_size(self.file_size)
+
+
+class UploadFileTooLargeError(Exception):
+    """Raised when a file exceeds the platform per-file size limit."""
+
+    def __init__(
+        self,
+        file_name: str,
+        file_size: int,
+        limit_bytes: int = 0,
+        message: str = "",
+    ) -> None:
+        self.file_name = file_name
+        self.file_size = file_size
+        self.limit_bytes = limit_bytes
+        limit_str = f" ({format_size(limit_bytes)})" if limit_bytes else ""
+        super().__init__(
+            message
+            or (
+                f"File {file_name!r} ({format_size(file_size)}) "
+                f"exceeds platform limit{limit_str}"
+            )
+        )
+
+    @property
+    def file_size_human(self) -> str:
+        return format_size(self.file_size)
+
+    @property
+    def limit_human(self) -> str:
+        return format_size(self.limit_bytes) if self.limit_bytes else "unknown"
+
+
+# ── Progress tracking ────────────────────────────────────────────────
+
+@dataclass
+class _UploadProgress:
+    total_parts: int = 0
+    total_bytes: int = 0
+    completed_parts: int = 0
+    uploaded_bytes: int = 0
+
+
+# ── Prepare-response shape ───────────────────────────────────────────
+
+@dataclass
+class _PreparePart:
+    index: int
+    presigned_url: str
+    block_size: int = 0
+
+
+@dataclass
+class _PrepareResult:
+    upload_id: str
+    block_size: int
+    parts: List[_PreparePart]
+    concurrency: int = _DEFAULT_CONCURRENT_PARTS
+    retry_timeout: float = 0.0
+
+
+def _parse_prepare_response(raw: Dict[str, Any]) -> _PrepareResult:
+    """Parse the upload_prepare API response into a normalized shape.
+
+    The API may return the response directly or wrapped in ``data``.
+    """
+    src = raw.get("data") if isinstance(raw.get("data"), dict) else raw
+    upload_id = str(src.get("upload_id", ""))
+    if not upload_id:
+        raise ValueError(
+            f"upload_prepare response missing upload_id: {str(raw)[:200]}"
+        )
+    block_size = int(src.get("block_size", 0))
+    raw_parts = src.get("parts") or src.get("part_list") or []
+    if not isinstance(raw_parts, list) or not raw_parts:
+        raise ValueError(
+            f"upload_prepare response missing parts: {str(raw)[:200]}"
+        )
+    parts: List[_PreparePart] = []
+    for p in raw_parts:
+        if not isinstance(p, dict):
+            continue
+        parts.append(
+            _PreparePart(
+                index=int(p.get("part_index") or p.get("index") or 0),
+                presigned_url=str(
+                    p.get("presigned_url") or p.get("url") or ""
+                ),
+                block_size=int(p.get("block_size", 0)),
+            )
+        )
+    return _PrepareResult(
+        upload_id=upload_id,
+        block_size=block_size,
+        parts=parts,
+        concurrency=int(src.get("concurrency", _DEFAULT_CONCURRENT_PARTS)) or _DEFAULT_CONCURRENT_PARTS,
+        retry_timeout=float(src.get("retry_timeout", 0.0) or 0.0),
+    )
+
+
+# ── Chunked upload driver ────────────────────────────────────────────
+
+ApiRequestFn = Callable[..., Awaitable[Dict[str, Any]]]
+"""Signature of the adapter's ``_api_request`` callable.
+
+We pass the bound method in rather than importing the adapter, to avoid
+circular imports and keep this module testable in isolation.
+"""
+
+
+class ChunkedUploader:
+    """Run the prepare → PUT parts → complete sequence.
+
+    :param api_request: Bound ``_api_request(method, path, body=..., timeout=...)``
+        coroutine from the adapter. Must raise ``RuntimeError`` with the biz_code
+        embedded in the message on API errors.
+    :param http_put: Coroutine ``(url, data, headers, timeout) -> response`` for
+        COS part uploads. Typically wraps ``httpx.AsyncClient.put``.
+    :param log_tag: Log prefix.
+    """
+
+    def __init__(
+        self,
+        api_request: ApiRequestFn,
+        http_put: Callable[..., Awaitable[Any]],
+        log_tag: str = "QQBot",
+    ) -> None:
+        self._api_request = api_request
+        self._http_put = http_put
+        self._log_tag = log_tag
+
+    async def upload(
+        self,
+        chat_type: str,
+        target_id: str,
+        file_path: str,
+        file_type: int,
+        file_name: str,
+    ) -> Dict[str, Any]:
+        """Run the full chunked upload and return the ``complete_upload`` response.
+
+        :param chat_type: ``'c2c'`` or ``'group'``.
+        :param target_id: User or group openid.
+        :param file_path: Absolute path to a local file.
+        :param file_type: ``MEDIA_TYPE_*`` constant.
+        :param file_name: Original filename (for upload_prepare).
+        :returns: The raw response dict from ``complete_upload`` — contains
+            ``file_info`` that the caller uses in a RichMedia message body.
+        :raises UploadDailyLimitExceededError: On biz_code 40093002.
+        :raises UploadFileTooLargeError: When the file exceeds the platform limit.
+        :raises RuntimeError: On other API or I/O failures.
+        """
+        if chat_type not in ("c2c", "group"):
+            raise ValueError(
+                f"ChunkedUploader: unsupported chat_type {chat_type!r}"
+            )
+
+        path = Path(file_path)
+        file_size = path.stat().st_size
+
+        logger.info(
+            "[%s] Chunked upload start: file=%s size=%s type=%d",
+            self._log_tag, file_name, format_size(file_size), file_type,
+        )
+
+        # Step 1: compute hashes (blocking I/O → executor).
+        hashes = await asyncio.get_running_loop().run_in_executor(
+            None, _compute_file_hashes, file_path, file_size
+        )
+
+        # Step 2: upload_prepare.
+        prepare = await self._prepare(
+            chat_type, target_id, file_type, file_name, file_size, hashes
+        )
+        max_concurrent = min(prepare.concurrency, _MAX_CONCURRENT_PARTS)
+        retry_timeout = min(
+            prepare.retry_timeout if prepare.retry_timeout > 0 else _PART_FINISH_DEFAULT_TIMEOUT,
+            _PART_FINISH_MAX_TIMEOUT,
+        )
+        logger.info(
+            "[%s] Prepared: upload_id=%s block_size=%s parts=%d concurrency=%d",
+            self._log_tag, prepare.upload_id, format_size(prepare.block_size),
+            len(prepare.parts), max_concurrent,
+        )
+
+        progress = _UploadProgress(
+            total_parts=len(prepare.parts),
+            total_bytes=file_size,
+        )
+
+        # Step 3: PUT each part + notify.
+        tasks: List[Callable[[], Awaitable[None]]] = [
+            functools.partial(
+                self._upload_one_part,
+                chat_type=chat_type,
+                target_id=target_id,
+                file_path=file_path,
+                file_size=file_size,
+                upload_id=prepare.upload_id,
+                rsp_block_size=prepare.block_size,
+                part=part,
+                retry_timeout=retry_timeout,
+                progress=progress,
+            )
+            for part in prepare.parts
+        ]
+        await _run_with_concurrency(tasks, max_concurrent)
+
+        logger.info(
+            "[%s] All %d parts uploaded, completing…",
+            self._log_tag, len(prepare.parts),
+        )
+
+        # Step 4: complete_upload (retry on transient errors).
+        return await self._complete(chat_type, target_id, prepare.upload_id)
+
+    # ──────────────────────────────────────────────────────────────────
+    # Step 1 — upload_prepare
+    # ──────────────────────────────────────────────────────────────────
+
+    async def _prepare(
+        self,
+        chat_type: str,
+        target_id: str,
+        file_type: int,
+        file_name: str,
+        file_size: int,
+        hashes: Dict[str, str],
+    ) -> _PrepareResult:
+        base = "/v2/users" if chat_type == "c2c" else "/v2/groups"
+        path = f"{base}/{target_id}/upload_prepare"
+        body = {
+            "file_type": file_type,
+            "file_name": file_name,
+            "file_size": file_size,
+            "md5": hashes["md5"],
+            "sha1": hashes["sha1"],
+            "md5_10m": hashes["md5_10m"],
+        }
+        try:
+            raw = await self._api_request(
+                "POST", path, body=body, timeout=FILE_UPLOAD_TIMEOUT
+            )
+        except RuntimeError as exc:
+            err_msg = str(exc)
+            if f"{_BIZ_CODE_DAILY_LIMIT}" in err_msg:
+                raise UploadDailyLimitExceededError(
+                    file_name, file_size, err_msg
+                ) from exc
+            raise
+        return _parse_prepare_response(raw)
+
+    # ──────────────────────────────────────────────────────────────────
+    # Step 2 — PUT one part + part_finish
+    # ──────────────────────────────────────────────────────────────────
+
+    async def _upload_one_part(
+        self,
+        chat_type: str,
+        target_id: str,
+        file_path: str,
+        file_size: int,
+        upload_id: str,
+        rsp_block_size: int,
+        part: _PreparePart,
+        retry_timeout: float,
+        progress: _UploadProgress,
+    ) -> None:
+        """PUT one part to COS, then call ``upload_part_finish``."""
+        part_index = part.index
+        # Per-part block_size wins; fall back to the response-level value.
+        actual_block_size = part.block_size if part.block_size > 0 else rsp_block_size
+        offset = (part_index - 1) * rsp_block_size
+        length = min(actual_block_size, file_size - offset)
+
+        # Read this slice of the file (blocking → executor).
+        data = await asyncio.get_running_loop().run_in_executor(
+            None, _read_file_chunk, file_path, offset, length
+        )
+        md5_hex = hashlib.md5(data).hexdigest()
+
+        logger.debug(
+            "[%s] Part %d/%d: uploading %s (offset=%d md5=%s)",
+            self._log_tag, part_index, progress.total_parts,
+            format_size(length), offset, md5_hex,
+        )
+
+        await self._put_to_presigned_url(
+            part.presigned_url, data, part_index, progress.total_parts
+        )
+        await self._part_finish_with_retry(
+            chat_type, target_id, upload_id,
+            part_index, length, md5_hex, retry_timeout,
+        )
+
+        progress.completed_parts += 1
+        progress.uploaded_bytes += length
+        logger.debug(
+            "[%s] Part %d/%d done (%d/%d total)",
+            self._log_tag, part_index, progress.total_parts,
+            progress.completed_parts, progress.total_parts,
+        )
+
+    async def _put_to_presigned_url(
+        self,
+        url: str,
+        data: bytes,
+        part_index: int,
+        total_parts: int,
+    ) -> None:
+        """PUT part data to a pre-signed COS URL with retry."""
+        last_exc: Optional[Exception] = None
+        for attempt in range(_PART_UPLOAD_MAX_RETRIES + 1):
+            try:
+                resp = await asyncio.wait_for(
+                    self._http_put(
+                        url,
+                        data=data,
+                        headers={"Content-Length": str(len(data))},
+                    ),
+                    timeout=_PART_UPLOAD_TIMEOUT,
+                )
+                # Caller's http_put is expected to return an httpx-like response.
+                status = getattr(resp, "status_code", 0)
+                if 200 <= status < 300:
+                    logger.debug(
+                        "[%s] PUT part %d/%d: %d OK",
+                        self._log_tag, part_index, total_parts, status,
+                    )
+                    return
+                body_preview = ""
+                try:
+                    body_preview = getattr(resp, "text", "")[:200]
+                except Exception:  # pragma: no cover — defensive
+                    pass
+                raise RuntimeError(
+                    f"COS PUT returned {status}: {body_preview}"
+                )
+            except Exception as exc:
+                last_exc = exc
+                if attempt < _PART_UPLOAD_MAX_RETRIES:
+                    delay = 1.0 * (2 ** attempt)
+                    logger.warning(
+                        "[%s] PUT part %d/%d attempt %d failed, retry in %.1fs: %s",
+                        self._log_tag, part_index, total_parts,
+                        attempt + 1, delay, exc,
+                    )
+                    await asyncio.sleep(delay)
+        raise RuntimeError(
+            f"Part {part_index}/{total_parts} upload failed after "
+            f"{_PART_UPLOAD_MAX_RETRIES + 1} attempts: {last_exc}"
+        )
+
+    async def _part_finish_with_retry(
+        self,
+        chat_type: str,
+        target_id: str,
+        upload_id: str,
+        part_index: int,
+        block_size: int,
+        md5: str,
+        retry_timeout: float,
+    ) -> None:
+        """Call ``upload_part_finish``, retrying on biz_code 40093001."""
+        base = "/v2/users" if chat_type == "c2c" else "/v2/groups"
+        path = f"{base}/{target_id}/upload_part_finish"
+        body = {
+            "upload_id": upload_id,
+            "part_index": part_index,
+            "block_size": block_size,
+            "md5": md5,
+        }
+
+        loop = asyncio.get_running_loop()
+        start = loop.time()
+        attempt = 0
+        while True:
+            try:
+                await self._api_request(
+                    "POST", path, body=body, timeout=FILE_UPLOAD_TIMEOUT
+                )
+                return
+            except RuntimeError as exc:
+                err_msg = str(exc)
+                if f"{_BIZ_CODE_PART_RETRYABLE}" not in err_msg:
+                    raise
+                elapsed = loop.time() - start
+                if elapsed >= retry_timeout:
+                    raise RuntimeError(
+                        f"upload_part_finish persistent retry timed out "
+                        f"after {retry_timeout:.0f}s ({attempt} retries): {exc}"
+                    ) from exc
+                attempt += 1
+                logger.debug(
+                    "[%s] part_finish retryable error, attempt %d, "
+                    "elapsed=%.1fs: %s",
+                    self._log_tag, attempt, elapsed, exc,
+                )
+                await asyncio.sleep(_PART_FINISH_RETRY_INTERVAL)
+
+    # ──────────────────────────────────────────────────────────────────
+    # Step 3 — complete_upload
+    # ──────────────────────────────────────────────────────────────────
+
+    async def _complete(
+        self,
+        chat_type: str,
+        target_id: str,
+        upload_id: str,
+    ) -> Dict[str, Any]:
+        """Call ``complete_upload`` with retry.
+
+        This reuses the ``/files`` endpoint (same as the simple URL-based upload)
+        but signals the chunked-completion path by sending only ``upload_id``.
+        """
+        base = "/v2/users" if chat_type == "c2c" else "/v2/groups"
+        path = f"{base}/{target_id}/files"
+        body = {"upload_id": upload_id}
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(_COMPLETE_UPLOAD_MAX_RETRIES + 1):
+            try:
+                return await self._api_request(
+                    "POST", path, body=body, timeout=FILE_UPLOAD_TIMEOUT
+                )
+            except Exception as exc:
+                last_exc = exc
+                if attempt < _COMPLETE_UPLOAD_MAX_RETRIES:
+                    delay = _COMPLETE_UPLOAD_BASE_DELAY * (2 ** attempt)
+                    logger.warning(
+                        "[%s] complete_upload attempt %d failed, "
+                        "retry in %.1fs: %s",
+                        self._log_tag, attempt + 1, delay, exc,
+                    )
+                    await asyncio.sleep(delay)
+        raise RuntimeError(
+            f"complete_upload failed after "
+            f"{_COMPLETE_UPLOAD_MAX_RETRIES + 1} attempts: {last_exc}"
+        )
+
+
+# ── Helpers (module-level for testability) ───────────────────────────
+
+def format_size(size_bytes: int) -> str:
+    """Return a human-readable file size string (e.g. ``'12.3 MB'``)."""
+    size = float(size_bytes)
+    for unit in ("B", "KB", "MB", "GB"):
+        if size < 1024.0:
+            return f"{size:.1f} {unit}"
+        size /= 1024.0
+    return f"{size:.1f} TB"
+
+
+def _read_file_chunk(file_path: str, offset: int, length: int) -> bytes:
+    """Read *length* bytes from *file_path* starting at *offset*.
+
+    :raises IOError: If fewer bytes were read than expected (truncated file).
+    """
+    with open(file_path, "rb") as fh:
+        fh.seek(offset)
+        data = fh.read(length)
+        if len(data) != length:
+            raise IOError(
+                f"Short read from {file_path}: expected {length} bytes at "
+                f"offset {offset}, got {len(data)} (file may be truncated)"
+            )
+        return data
+
+
+def _compute_file_hashes(file_path: str, file_size: int) -> Dict[str, str]:
+    """Compute md5, sha1, and md5_10m in a single pass."""
+    md5 = hashlib.md5()
+    sha1 = hashlib.sha1()
+    md5_10m = hashlib.md5()
+
+    need_10m = file_size > _MD5_10M_SIZE
+    bytes_read = 0
+
+    with open(file_path, "rb") as fh:
+        while True:
+            chunk = fh.read(65536)
+            if not chunk:
+                break
+            md5.update(chunk)
+            sha1.update(chunk)
+            if need_10m:
+                remaining = _MD5_10M_SIZE - bytes_read
+                if remaining > 0:
+                    md5_10m.update(chunk[:remaining])
+            bytes_read += len(chunk)
+
+    full_md5 = md5.hexdigest()
+    return {
+        "md5": full_md5,
+        "sha1": sha1.hexdigest(),
+        # For small files the "10m" hash is just the full md5.
+        "md5_10m": md5_10m.hexdigest() if need_10m else full_md5,
+    }
+
+
+async def _run_with_concurrency(
+    tasks: List[Callable[[], Awaitable[None]]],
+    concurrency: int,
+) -> None:
+    """Run a list of thunks with a bounded number in flight at once."""
+    if concurrency < 1:
+        concurrency = 1
+    sem = asyncio.Semaphore(concurrency)
+
+    async def _wrap(thunk: Callable[[], Awaitable[None]]) -> None:
+        async with sem:
+            await thunk()
+
+    await asyncio.gather(*(_wrap(t) for t in tasks))
@@ -0,0 +1,473 @@
+"""QQ Bot inline keyboards + approval / update-prompt senders.
+
+QQ Bot v2 supports attaching inline keyboards to outbound messages. When a
+user clicks a button, the platform dispatches an ``INTERACTION_CREATE``
+gateway event containing the button's ``data`` payload. The bot must ACK the
+interaction promptly via ``PUT /interactions/{id}`` or the user sees an
+error indicator on the button.
+
+This module provides:
+
+- :class:`InlineKeyboard` + button dataclasses — serialized into the
+  ``keyboard`` field of the outbound message body.
+- :func:`build_approval_keyboard` — 3-button ✅ once / ⭐ always / ❌ deny
+  keyboard for tool-approval flows.
+- :func:`build_update_prompt_keyboard` — Yes/No keyboard for update confirms.
+- :func:`parse_approval_button_data` / :func:`parse_update_prompt_button_data`
+  — decode the ``button_data`` payload from ``INTERACTION_CREATE``.
+- :class:`ApprovalRequest` + :class:`ApprovalSender` — high-level helper that
+  builds an approval message with keyboard and posts it to a c2c / group chat.
+
+``button_data`` formats::
+
+    approve:<session_key>:<decision>      # decision = allow-once|allow-always|deny
+    update_prompt:<answer>                # answer = y|n
+
+Ported from WideLee's qqbot-agent-sdk v1.2.2 (``approval.py`` + ``dto.py``
+keyboard types). Authorship preserved via Co-authored-by.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# ── button_data prefixes + patterns ──────────────────────────────────
+
+APPROVAL_BUTTON_PREFIX = "approve:"
+UPDATE_PROMPT_PREFIX = "update_prompt:"
+
+# Pattern: approve:<session_key>:<decision>
+# session_key may itself contain colons (e.g. agent:main:qqbot:c2c:OPENID),
+# so the session_key group is greedy but trails the decision.
+_APPROVAL_DATA_RE = re.compile(
+    r"^approve:(.+):(allow-once|allow-always|deny)$"
+)
+
+# Pattern: update_prompt:y | update_prompt:n
+_UPDATE_PROMPT_RE = re.compile(r"^update_prompt:(y|n)$")
+
+
+# ── Keyboard dataclasses ─────────────────────────────────────────────
+
+@dataclass
+class KeyboardButtonPermission:
+    """Button permission metadata. ``type=2`` means all users can click."""
+    type: int = 2
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type}
+
+
+@dataclass
+class KeyboardButtonAction:
+    """What happens when the button is clicked.
+
+    :param type: ``1`` (Callback — triggers ``INTERACTION_CREATE``) or
+        ``2`` (Link — opens a URL).
+    :param data: Payload delivered in ``data.resolved.button_data`` when
+        ``type=1``.
+    :param permission: :class:`KeyboardButtonPermission`.
+    :param click_limit: Max clicks per user (``1`` = single-use).
+    """
+    type: int
+    data: str
+    permission: KeyboardButtonPermission = field(
+        default_factory=KeyboardButtonPermission
+    )
+    click_limit: int = 1
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "type": self.type,
+            "data": self.data,
+            "permission": self.permission.to_dict(),
+            "click_limit": self.click_limit,
+        }
+
+
+@dataclass
+class KeyboardButtonRenderData:
+    """Visual rendering of a button.
+
+    :param label: Pre-click label.
+    :param visited_label: Post-click label (button stays greyed in place).
+    :param style: ``0`` = grey, ``1`` = blue.
+    """
+    label: str
+    visited_label: str
+    style: int = 1
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "label": self.label,
+            "visited_label": self.visited_label,
+            "style": self.style,
+        }
+
+
+@dataclass
+class KeyboardButton:
+    """One button in a keyboard.
+
+    :param group_id: Buttons sharing a ``group_id`` are mutually exclusive —
+        clicking one greys the rest.
+    """
+    id: str
+    render_data: KeyboardButtonRenderData
+    action: KeyboardButtonAction
+    group_id: str = "default"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "render_data": self.render_data.to_dict(),
+            "action": self.action.to_dict(),
+            "group_id": self.group_id,
+        }
+
+
+@dataclass
+class KeyboardRow:
+    buttons: List[KeyboardButton] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"buttons": [b.to_dict() for b in self.buttons]}
+
+
+@dataclass
+class KeyboardContent:
+    rows: List[KeyboardRow] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"rows": [r.to_dict() for r in self.rows]}
+
+
+@dataclass
+class InlineKeyboard:
+    """Top-level keyboard payload — goes into ``MessageToCreate.keyboard``."""
+    content: KeyboardContent = field(default_factory=KeyboardContent)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"content": self.content.to_dict()}
+
+
+# ── INTERACTION_CREATE parsing ───────────────────────────────────────
+
+def parse_approval_button_data(button_data: str) -> Optional[tuple[str, str]]:
+    """Parse approval ``button_data`` into ``(session_key, decision)``.
+
+    :param button_data: Raw ``data.resolved.button_data`` from
+        ``INTERACTION_CREATE``.
+    :returns: ``(session_key, decision)`` or ``None`` if not an approval button.
+    """
+    m = _APPROVAL_DATA_RE.match(button_data or "")
+    if not m:
+        return None
+    return m.group(1), m.group(2)
+
+
+def parse_update_prompt_button_data(button_data: str) -> Optional[str]:
+    """Parse update-prompt ``button_data`` into ``'y'`` or ``'n'``."""
+    m = _UPDATE_PROMPT_RE.match(button_data or "")
+    if not m:
+        return None
+    return m.group(1)
+
+
+# ── Keyboard builders ────────────────────────────────────────────────
+
+def _make_callback_button(
+    btn_id: str,
+    label: str,
+    visited_label: str,
+    data: str,
+    style: int,
+    group_id: str,
+) -> KeyboardButton:
+    return KeyboardButton(
+        id=btn_id,
+        render_data=KeyboardButtonRenderData(
+            label=label,
+            visited_label=visited_label,
+            style=style,
+        ),
+        action=KeyboardButtonAction(type=1, data=data),
+        group_id=group_id,
+    )
+
+
+def build_approval_keyboard(session_key: str) -> InlineKeyboard:
+    """Build the 3-button approval keyboard.
+
+    Layout: ``[✅ 允许一次] [⭐ 始终允许] [❌ 拒绝]`` — all three share
+    ``group_id='approval'`` so clicking one greys out the rest.
+
+    :param session_key: Embedded into ``button_data`` so the decision
+        routes back to the right pending approval.
+    """
+    return InlineKeyboard(
+        content=KeyboardContent(
+            rows=[
+                KeyboardRow(buttons=[
+                    _make_callback_button(
+                        btn_id="allow",
+                        label="✅ 允许一次",
+                        visited_label="已允许",
+                        data=f"{APPROVAL_BUTTON_PREFIX}{session_key}:allow-once",
+                        style=1,
+                        group_id="approval",
+                    ),
+                    _make_callback_button(
+                        btn_id="always",
+                        label="⭐ 始终允许",
+                        visited_label="已始终允许",
+                        data=f"{APPROVAL_BUTTON_PREFIX}{session_key}:allow-always",
+                        style=1,
+                        group_id="approval",
+                    ),
+                    _make_callback_button(
+                        btn_id="deny",
+                        label="❌ 拒绝",
+                        visited_label="已拒绝",
+                        data=f"{APPROVAL_BUTTON_PREFIX}{session_key}:deny",
+                        style=0,
+                        group_id="approval",
+                    ),
+                ]),
+            ]
+        )
+    )
+
+
+def build_update_prompt_keyboard() -> InlineKeyboard:
+    """Build a Yes/No keyboard for update confirmation prompts."""
+    return InlineKeyboard(
+        content=KeyboardContent(
+            rows=[
+                KeyboardRow(buttons=[
+                    _make_callback_button(
+                        btn_id="yes",
+                        label="✓ 确认",
+                        visited_label="已确认",
+                        data=f"{UPDATE_PROMPT_PREFIX}y",
+                        style=1,
+                        group_id="update_prompt",
+                    ),
+                    _make_callback_button(
+                        btn_id="no",
+                        label="✗ 取消",
+                        visited_label="已取消",
+                        data=f"{UPDATE_PROMPT_PREFIX}n",
+                        style=0,
+                        group_id="update_prompt",
+                    ),
+                ]),
+            ]
+        )
+    )
+
+
+# ── ApprovalRequest + text builder ───────────────────────────────────
+
+@dataclass
+class ApprovalRequest:
+    """Structured approval-request display data.
+
+    :param session_key: Routes the decision back to the waiting caller.
+    :param title: Short title at the top.
+    :param description: Optional longer description.
+    :param command_preview: Command text (exec approvals).
+    :param cwd: Working directory (exec approvals).
+    :param tool_name: Tool name (plugin approvals).
+    :param severity: ``'critical' | 'info' | ''``.
+    :param timeout_sec: Seconds until the approval expires.
+    """
+    session_key: str
+    title: str
+    description: str = ""
+    command_preview: str = ""
+    cwd: str = ""
+    tool_name: str = ""
+    severity: str = ""
+    timeout_sec: int = 120
+
+
+def build_approval_text(req: ApprovalRequest) -> str:
+    """Render an :class:`ApprovalRequest` into the message body (markdown)."""
+    if req.command_preview or req.cwd:
+        return _build_exec_text(req)
+    return _build_plugin_text(req)
+
+
+def _build_exec_text(req: ApprovalRequest) -> str:
+    lines: List[str] = ["🔐 **命令执行审批**", ""]
+    if req.command_preview:
+        preview = req.command_preview[:300]
+        lines.append(f"```\n{preview}\n```")
+    if req.cwd:
+        lines.append(f"📁 目录: {req.cwd}")
+    if req.title and req.title != req.command_preview:
+        lines.append(f"📋 {req.title}")
+    if req.description:
+        lines.append(f"📝 {req.description}")
+    lines.append("")
+    lines.append(f"⏱️ 超时: {req.timeout_sec} 秒")
+    return "\n".join(lines)
+
+
+def _build_plugin_text(req: ApprovalRequest) -> str:
+    icon = (
+        "🔴" if req.severity == "critical"
+        else "🔵" if req.severity == "info"
+        else "🟡"
+    )
+    lines: List[str] = [f"{icon} **审批请求**", ""]
+    lines.append(f"📋 {req.title}")
+    if req.description:
+        lines.append(f"📝 {req.description}")
+    if req.tool_name:
+        lines.append(f"🔧 工具: {req.tool_name}")
+    lines.append("")
+    lines.append(f"⏱️ 超时: {req.timeout_sec} 秒")
+    return "\n".join(lines)
+
+
+# ── ApprovalSender ───────────────────────────────────────────────────
+
+PostMessageFn = Callable[..., Awaitable[Dict[str, Any]]]
+"""Signature of an async POST to ``/v2/{users|groups}/{id}/messages``.
+
+Implementations accept a body dict and return the raw API response.
+"""
+
+
+class ApprovalSender:
+    """Send an approval-request message with an inline keyboard.
+
+    Decoupled from the adapter via callables so it can be unit-tested in
+    isolation. Pass the adapter's ``_send_message_with_keyboard`` helper
+    (or any equivalent) as ``post_message``.
+    """
+
+    def __init__(
+        self,
+        post_c2c: PostMessageFn,
+        post_group: PostMessageFn,
+        log_tag: str = "QQBot",
+    ) -> None:
+        self._post_c2c = post_c2c
+        self._post_group = post_group
+        self._log_tag = log_tag
+
+    async def send(
+        self,
+        chat_type: str,
+        chat_id: str,
+        req: ApprovalRequest,
+        msg_id: Optional[str] = None,
+    ) -> bool:
+        """Send an approval message to *chat_id*.
+
+        :param chat_type: ``'c2c'`` or ``'group'``.
+        :param chat_id: User openid or group openid.
+        :param req: :class:`ApprovalRequest`.
+        :param msg_id: Reply-to message id (required for passive messages).
+        :returns: ``True`` on success, ``False`` on failure.
+        """
+        text = build_approval_text(req)
+        keyboard = build_approval_keyboard(req.session_key)
+
+        logger.info(
+            "[%s] Sending approval request to %s:%s (session=%.20s…)",
+            self._log_tag, chat_type, chat_id, req.session_key,
+        )
+
+        try:
+            if chat_type == "c2c":
+                await self._post_c2c(chat_id, text, msg_id, keyboard)
+            elif chat_type == "group":
+                await self._post_group(chat_id, text, msg_id, keyboard)
+            else:
+                logger.warning(
+                    "[%s] Approval: unsupported chat_type %r",
+                    self._log_tag, chat_type,
+                )
+                return False
+            logger.info(
+                "[%s] Approval message sent to %s:%s",
+                self._log_tag, chat_type, chat_id,
+            )
+            return True
+        except Exception as exc:
+            logger.error(
+                "[%s] Failed to send approval message to %s:%s: %s",
+                self._log_tag, chat_type, chat_id, exc,
+            )
+            return False
+
+
+# ── INTERACTION_CREATE event shape ───────────────────────────────────
+
+@dataclass
+class InteractionEvent:
+    """Parsed ``INTERACTION_CREATE`` event payload.
+
+    See https://bot.q.qq.com/wiki/develop/api-v2/dev-prepare/interface-framework/event-emit.html
+    """
+    id: str = ""
+    """Interaction event id — required for the ``PUT /interactions/{id}`` ACK."""
+
+    type: int = 0
+    """Event type code (``11`` = message button)."""
+
+    chat_type: int = 0
+    """``0`` = guild, ``1`` = group, ``2`` = c2c."""
+
+    scene: str = ""
+    """``'guild'`` | ``'group'`` | ``'c2c'`` — human-readable scene."""
+
+    group_openid: str = ""
+    group_member_openid: str = ""
+    user_openid: str = ""
+    channel_id: str = ""
+    guild_id: str = ""
+
+    button_data: str = ""
+    button_id: str = ""
+    resolver_user_id: str = ""
+
+    @property
+    def operator_openid(self) -> str:
+        """Best available operator openid (group → member; c2c → user)."""
+        return (
+            self.group_member_openid
+            or self.user_openid
+            or self.resolver_user_id
+        )
+
+
+def parse_interaction_event(raw: Dict[str, Any]) -> InteractionEvent:
+    """Parse a raw ``INTERACTION_CREATE`` dispatch payload (``d``)."""
+    data_raw = raw.get("data") or {}
+    resolved = data_raw.get("resolved") or {}
+    scene_code = int(raw.get("chat_type", 0) or 0)
+    scene = {0: "guild", 1: "group", 2: "c2c"}.get(scene_code, "")
+    return InteractionEvent(
+        id=str(raw.get("id", "")),
+        type=int(data_raw.get("type", 0) or 0),
+        chat_type=scene_code,
+        scene=scene,
+        group_openid=str(raw.get("group_openid", "")),
+        group_member_openid=str(raw.get("group_member_openid", "")),
+        user_openid=str(raw.get("user_openid", "")),
+        channel_id=str(raw.get("channel_id", "")),
+        guild_id=str(raw.get("guild_id", "")),
+        button_data=str(resolved.get("button_data", "")),
+        button_id=str(resolved.get("button_id", "")),
+        resolver_user_id=str(resolved.get("user_id", "")),
+    )
@@ -1887,6 +1887,12 @@ class SlackAdapter(BasePlatformAdapter):
        is_thread_reply = bool(event_thread_ts and event_thread_ts != ts)

        if not is_dm and bot_uid:
+            # Check allowed channels — if set, only respond in these channels (whitelist)
+            allowed_channels = self._slack_allowed_channels()
+            if allowed_channels and channel_id not in allowed_channels:
+                logger.debug("[Slack] Ignoring message in non-allowed channel: %s", channel_id)
+                return
+
            if channel_id in self._slack_free_response_channels():
                pass  # Free-response channel — always process
            elif not self._slack_require_mention():
@@ -2924,3 +2930,19 @@ class SlackAdapter(BasePlatformAdapter):
        if s:
            return {part.strip() for part in s.split(",") if part.strip()}
        return set()
+
+    def _slack_allowed_channels(self) -> set:
+        """Return the whitelist of channel IDs the bot will respond in.
+
+        When non-empty, messages from channels NOT in this set are silently
+        ignored — even if the bot is @mentioned.  DMs are never filtered.
+        Empty set means no restriction (fully backward compatible).
+        """
+        raw = self.config.extra.get("allowed_channels")
+        if raw is None:
+            raw = os.getenv("SLACK_ALLOWED_CHANNELS", "")
+        if isinstance(raw, list):
+            return {str(part).strip() for part in raw if str(part).strip()}
+        if isinstance(raw, str) and raw.strip():
+            return {part.strip() for part in raw.split(",") if part.strip()}
+        return set()
@@ -86,6 +86,22 @@ from gateway.platforms.telegram_network import (
 )
 from utils import atomic_replace

+_TELEGRAM_IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".webp", ".gif"}
+_TELEGRAM_IMAGE_MIME_TO_EXT = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/jpg": ".jpg",
+    "image/webp": ".webp",
+    "image/gif": ".gif",
+}
+_TELEGRAM_IMAGE_EXT_TO_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+}
+

 def check_telegram_requirements() -> bool:
    """Check if Telegram dependencies are available."""
@@ -353,10 +369,14 @@ class TelegramAdapter(BasePlatformAdapter):

    @classmethod
    def _message_thread_id_for_typing(cls, thread_id: Optional[str]) -> Optional[int]:
-        # Mirrors _message_thread_id_for_send: the General forum topic (thread id
-        # "1") is represented as "no thread id" on the wire. User-created topics
-        # keep their real id so typing stays scoped to that topic.
-        if not thread_id or str(thread_id) == cls._GENERAL_TOPIC_THREAD_ID:
+        # Asymmetric with _message_thread_id_for_send on purpose. Telegram's
+        # sendMessage and sendChatAction treat thread id "1" (the forum General
+        # topic) differently: sends reject message_thread_id=1 and must omit it,
+        # but sendChatAction needs message_thread_id=1 to place the typing
+        # bubble in the General topic (omitting it hides the bubble entirely
+        # from the client's view of that topic). Preserve the real id here —
+        # sends still map "1" → None via _message_thread_id_for_send.
+        if not thread_id:
            return None
        return int(thread_id)

@@ -2755,6 +2775,20 @@ class TelegramAdapter(BasePlatformAdapter):
            return {str(part).strip() for part in raw if str(part).strip()}
        return {part.strip() for part in str(raw).split(",") if part.strip()}

+    def _telegram_allowed_chats(self) -> set[str]:
+        """Return the whitelist of group/supergroup chat IDs the bot will respond in.
+
+        When non-empty, group messages from chats NOT in this set are silently
+        ignored — even if the bot is @mentioned.  DMs are never filtered.
+        Empty set means no restriction (fully backward compatible).
+        """
+        raw = self.config.extra.get("allowed_chats")
+        if raw is None:
+            raw = os.getenv("TELEGRAM_ALLOWED_CHATS", "")
+        if isinstance(raw, list):
+            return {str(part).strip() for part in raw if str(part).strip()}
+        return {part.strip() for part in str(raw).split(",") if part.strip()}
+
    def _telegram_ignored_threads(self) -> set[int]:
        raw = self.config.extra.get("ignored_threads")
        if raw is None:
@@ -2903,13 +2937,16 @@ class TelegramAdapter(BasePlatformAdapter):
        """Apply Telegram group trigger rules.

        DMs remain unrestricted. Group/supergroup messages are accepted when:
+        - the chat passes the ``allowed_chats`` whitelist (when set)
        - the chat is explicitly allowlisted in ``free_response_chats``
        - ``require_mention`` is disabled
        - the message replies to the bot
        - the bot is @mentioned
        - the text/caption matches a configured regex wake-word pattern

-        When ``require_mention`` is enabled, slash commands are not given
+        When ``allowed_chats`` is non-empty, it acts as a hard gate — messages
+        from any chat not in the list are ignored regardless of the other
+        rules.  When ``require_mention`` is enabled, slash commands are not given
        special treatment — they must pass the same mention/reply checks
        as any other group message.  Users can still trigger commands via
        the Telegram bot menu (``/command@botname``) or by explicitly
@@ -2918,6 +2955,14 @@ class TelegramAdapter(BasePlatformAdapter):
        """
        if not self._is_group_chat(message):
            return True
+        # allowed_chats check (whitelist — must pass before other gating).
+        # When set, group messages from chats NOT in this whitelist are
+        # silently ignored, even if @mentioned.  DMs are already excluded above.
+        allowed = self._telegram_allowed_chats()
+        if allowed:
+            chat_id_str = str(getattr(getattr(message, "chat", None), "id", ""))
+            if chat_id_str not in allowed:
+                return False
        thread_id = getattr(message, "message_thread_id", None)
        if thread_id is not None:
            try:
@@ -3239,10 +3284,59 @@ class TelegramAdapter(BasePlatformAdapter):
                    _, ext = os.path.splitext(original_filename)
                    ext = ext.lower()

+                # Normalize mime_type for robust comparisons (some clients send
+                # uppercase like "IMAGE/PNG").
+                doc_mime = (doc.mime_type or "").lower()
+
                # If no extension from filename, reverse-lookup from MIME type
-                if not ext and doc.mime_type:
-                    mime_to_ext = {v: k for k, v in SUPPORTED_DOCUMENT_TYPES.items()}
-                    ext = mime_to_ext.get(doc.mime_type, "")
+                if not ext and doc_mime:
+                    ext = _TELEGRAM_IMAGE_MIME_TO_EXT.get(doc_mime, "")
+                    if not ext:
+                        mime_to_ext = {v: k for k, v in SUPPORTED_DOCUMENT_TYPES.items()}
+                        ext = mime_to_ext.get(doc_mime, "")
+
+                # Check file size early so image documents cannot bypass the
+                # document size limit by taking the image path.
+                MAX_DOC_BYTES = 20 * 1024 * 1024
+                if not doc.file_size or doc.file_size > MAX_DOC_BYTES:
+                    event.text = (
+                        "The document is too large or its size could not be verified. "
+                        "Maximum: 20 MB."
+                    )
+                    logger.info("[Telegram] Document too large: %s bytes", doc.file_size)
+                    await self.handle_message(event)
+                    return
+
+                # Telegram may deliver screenshots/photos as documents. If the
+                # payload is actually an image, route it through the image cache
+                # and batching path instead of rejecting it as a document.
+                if ext in _TELEGRAM_IMAGE_EXTENSIONS or doc_mime.startswith("image/"):
+                    file_obj = await doc.get_file()
+                    image_bytes = await file_obj.download_as_bytearray()
+                    image_ext = ext if ext in _TELEGRAM_IMAGE_EXTENSIONS else _TELEGRAM_IMAGE_MIME_TO_EXT.get(doc_mime, ".jpg")
+                    try:
+                        cached_path = cache_image_from_bytes(bytes(image_bytes), ext=image_ext)
+                    except ValueError as e:
+                        logger.warning("[Telegram] Failed to cache image document: %s", e, exc_info=True)
+                        event.text = (
+                            f"Image document '{original_filename or doc_mime or ext or 'unknown'}' "
+                            "could not be read as an image."
+                        )
+                        await self.handle_message(event)
+                        return
+
+                    event.message_type = MessageType.PHOTO
+                    event.media_urls = [cached_path]
+                    event.media_types = [doc_mime if doc_mime.startswith("image/") else _TELEGRAM_IMAGE_EXT_TO_MIME.get(image_ext, "image/jpeg")]
+                    logger.info("[Telegram] Cached user image-document at %s", cached_path)
+
+                    media_group_id = getattr(msg, "media_group_id", None)
+                    if media_group_id:
+                        await self._queue_media_group_event(str(media_group_id), event)
+                    else:
+                        batch_key = self._photo_batch_key(event, msg)
+                        self._enqueue_photo_event(batch_key, event)
+                    return

                if not ext and doc.mime_type:
                    video_mime_to_ext = {v: k for k, v in SUPPORTED_VIDEO_TYPES.items()}
@@ -3270,17 +3364,6 @@ class TelegramAdapter(BasePlatformAdapter):
                    await self.handle_message(event)
                    return

-                # Check file size (Telegram Bot API limit: 20 MB)
-                MAX_DOC_BYTES = 20 * 1024 * 1024
-                if not doc.file_size or doc.file_size > MAX_DOC_BYTES:
-                    event.text = (
-                        "The document is too large or its size could not be verified. "
-                        "Maximum: 20 MB."
-                    )
-                    logger.info("[Telegram] Document too large: %s bytes", doc.file_size)
-                    await self.handle_message(event)
-                    return
-
                # Download and cache
                file_obj = await doc.get_file()
                doc_bytes = await file_obj.download_as_bytearray()
@@ -59,6 +59,29 @@ DEFAULT_PORT = 8644
 _INSECURE_NO_AUTH = "INSECURE_NO_AUTH"
 _DYNAMIC_ROUTES_FILENAME = "webhook_subscriptions.json"

+# Hostnames/IP literals that only serve connections originating on the same
+# machine. Anything else is treated as a public bind for safety-rail purposes.
+_LOOPBACK_HOSTS = frozenset({
+    "127.0.0.1",
+    "localhost",
+    "::1",
+    "ip6-localhost",
+    "ip6-loopback",
+})
+
+
+def _is_loopback_host(host: str) -> bool:
+    """True when `host` binds only to the local machine.
+
+    Covers IPv4 loopback, the standard `localhost` alias, IPv6 loopback in
+    both bracketed and bare form, and the common Debian-style aliases. Any
+    falsy value (empty string, None) is conservatively treated as non-loopback
+    because an unset host usually means the platform-default public bind.
+    """
+    if not host:
+        return False
+    return host.strip().lower() in _LOOPBACK_HOSTS
+

 def check_webhook_requirements() -> bool:
    """Check if webhook adapter dependencies are available."""
@@ -126,6 +149,17 @@ class WebhookAdapter(BasePlatformAdapter):
                    f"For testing without auth, set secret to '{_INSECURE_NO_AUTH}'."
                )

+            # Safety rail: refuse to start if INSECURE_NO_AUTH is combined with a
+            # non-loopback bind. The escape hatch is for local testing only;
+            # serving an unauthenticated route on a public interface is a
+            # deployment-grade footgun we'd rather crash early than ship.
+            if secret == _INSECURE_NO_AUTH and not _is_loopback_host(self._host):
+                raise ValueError(
+                    f"[webhook] Route '{name}' uses INSECURE_NO_AUTH secret "
+                    f"but is bound to non-loopback host '{self._host}'. "
+                    f"INSECURE_NO_AUTH is for local testing only. "
+                    f"Refusing to start to prevent accidental exposure."
+                )
            # deliver_only routes bypass the agent — the POST body becomes a
            # direct push notification via the configured delivery target.
            # Validate up-front so misconfiguration surfaces at startup rather
@@ -37,6 +37,7 @@ import logging
 import mimetypes
 import os
 import re
+import time
 import uuid
 from datetime import datetime, timezone
 from pathlib import Path
@@ -1562,12 +1563,11 @@ def qr_scan_for_bot_info(
    print("  Fetching configuration results...", end="", flush=True)

    # ── Step 3: Poll for result ──
-    import time
-    deadline = time.time() + timeout_seconds
+    deadline = time.monotonic() + timeout_seconds
    query_url = f"{_QR_QUERY_URL}?scode={urllib.parse.quote(scode)}"
    poll_count = 0

-    while time.time() < deadline:
+    while time.monotonic() < deadline:
        try:
            req = urllib.request.Request(query_url, headers={"User-Agent": "HermesAgent/1.0"})
            with urllib.request.urlopen(req, timeout=10) as resp:
@@ -23,6 +23,7 @@ import re
 import secrets
 import struct
 import tempfile
+import textwrap
 import time
 import uuid
 from datetime import datetime
@@ -32,6 +33,8 @@ from urllib.parse import quote, urlparse

 logger = logging.getLogger(__name__)

+WEIXIN_COPY_LINE_WIDTH = 120
+
 try:
    import aiohttp

@@ -548,17 +551,21 @@ async def _upload_ciphertext(
    Accepts either a constructed CDN URL (from upload_param) or a direct
    upload_full_url — both use POST with the raw ciphertext as the body.
    """
-    timeout = aiohttp.ClientTimeout(total=120)
-    async with session.post(upload_url, data=ciphertext, headers={"Content-Type": "application/octet-stream"}, timeout=timeout) as response:
-        if response.status == 200:
-            encrypted_param = response.headers.get("x-encrypted-param")
-            if encrypted_param:
-                await response.read()
-                return encrypted_param
+    # Use asyncio.wait_for() instead of aiohttp ClientTimeout to avoid
+    # "Timeout context manager should be used inside a task" errors when
+    # invoked via asyncio.run_coroutine_threadsafe() from cron jobs.
+    async def _do_upload() -> str:
+        async with session.post(upload_url, data=ciphertext, headers={"Content-Type": "application/octet-stream"}) as response:
+            if response.status == 200:
+                encrypted_param = response.headers.get("x-encrypted-param")
+                if encrypted_param:
+                    await response.read()
+                    return encrypted_param
+                raw = await response.text()
+                raise RuntimeError(f"CDN upload missing x-encrypted-param header: {raw[:200]}")
            raw = await response.text()
-            raise RuntimeError(f"CDN upload missing x-encrypted-param header: {raw[:200]}")
-        raw = await response.text()
-        raise RuntimeError(f"CDN upload HTTP {response.status}: {raw[:200]}")
+            raise RuntimeError(f"CDN upload HTTP {response.status}: {raw[:200]}")
+    return await asyncio.wait_for(_do_upload(), timeout=120)


 async def _download_bytes(
@@ -567,10 +574,13 @@ async def _download_bytes(
    url: str,
    timeout_seconds: float = 60.0,
 ) -> bytes:
-    timeout = aiohttp.ClientTimeout(total=timeout_seconds)
-    async with session.get(url, timeout=timeout) as response:
-        response.raise_for_status()
-        return await response.read()
+    # Use asyncio.wait_for() instead of aiohttp ClientTimeout to avoid
+    # "Timeout context manager should be used inside a task" errors.
+    async def _do_download() -> bytes:
+        async with session.get(url) as response:
+            response.raise_for_status()
+            return await response.read()
+    return await asyncio.wait_for(_do_download(), timeout=timeout_seconds)


 _WEIXIN_CDN_ALLOWLIST: frozenset[str] = frozenset(
@@ -724,6 +734,46 @@ def _normalize_markdown_blocks(content: str) -> str:
    return "\n".join(result).strip()


+def _wrap_copy_friendly_lines_for_weixin(content: str) -> str:
+    """Wrap long display lines that are hard to copy in WeChat clients."""
+    if not content:
+        return content
+
+    wrapped: List[str] = []
+    in_code_block = False
+
+    for raw_line in content.splitlines():
+        line = raw_line.rstrip()
+        stripped = line.strip()
+
+        if _FENCE_RE.match(stripped):
+            in_code_block = not in_code_block
+            wrapped.append(line)
+            continue
+
+        if (
+            in_code_block
+            or len(line) <= WEIXIN_COPY_LINE_WIDTH
+            or not stripped
+            or stripped.startswith("|")
+            or _TABLE_RULE_RE.match(stripped)
+        ):
+            wrapped.append(line)
+            continue
+
+        wrapped_lines = textwrap.wrap(
+            line,
+            width=WEIXIN_COPY_LINE_WIDTH,
+            break_long_words=False,
+            break_on_hyphens=False,
+            replace_whitespace=False,
+            drop_whitespace=True,
+        )
+        wrapped.extend(wrapped_lines or [line])
+
+    return "\n".join(wrapped).strip()
+
+
 def _split_markdown_blocks(content: str) -> List[str]:
    if not content:
        return []
@@ -1037,11 +1087,11 @@ async def qr_login(
        except Exception as _qr_exc:
            print(f"（终端二维码渲染失败: {_qr_exc}，请直接打开上面的二维码链接）")

-        deadline = time.time() + timeout_seconds
+        deadline = time.monotonic() + timeout_seconds
        current_base_url = ILINK_BASE_URL
        refresh_count = 0

-        while time.time() < deadline:
+        while time.monotonic() < deadline:
            try:
                status_resp = await _api_get(
                    session,
@@ -1216,7 +1266,12 @@ class WeixinAdapter(BasePlatformAdapter):
            logger.debug("[%s] Token lock unavailable (non-fatal): %s", self.name, exc)

        self._poll_session = aiohttp.ClientSession(trust_env=True, connector=_make_ssl_connector())
-        self._send_session = aiohttp.ClientSession(trust_env=True, connector=_make_ssl_connector())
+        # Disable aiohttp's built-in ClientTimeout (total=None) to prevent
+        # "Timeout context manager should be used inside a task" errors when
+        # send() is invoked via asyncio.run_coroutine_threadsafe() from cron.
+        # Timeout is managed externally via asyncio.wait_for() in _api_post/_api_get.
+        _no_aiohttp_timeout = aiohttp.ClientTimeout(total=None, connect=None, sock_connect=None, sock_read=None)
+        self._send_session = aiohttp.ClientSession(trust_env=True, connector=_make_ssl_connector(), timeout=_no_aiohttp_timeout)
        self._token_store.restore(self._account_id)
        self._poll_task = asyncio.create_task(self._poll_loop(), name="weixin-poll")
        self._mark_connected()
@@ -1824,10 +1879,14 @@ class WeixinAdapter(BasePlatformAdapter):
            raise ValueError(f"Blocked unsafe URL (SSRF protection): {url}")

        assert self._send_session is not None
-        async with self._send_session.get(url, timeout=aiohttp.ClientTimeout(total=30)) as response:
-            response.raise_for_status()
-            data = await response.read()
-            suffix = Path(url.split("?", 1)[0]).suffix or ".bin"
+        # Use asyncio.wait_for() instead of aiohttp ClientTimeout to avoid
+        # "Timeout context manager should be used inside a task" errors.
+        async def _do_fetch():
+            async with self._send_session.get(url) as response:
+                response.raise_for_status()
+                return await response.read()
+        data = await asyncio.wait_for(_do_fetch(), timeout=30)
+        suffix = Path(url.split("?", 1)[0]).suffix or ".bin"
        with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as handle:
            handle.write(data)
            return handle.name
@@ -2006,7 +2065,7 @@ class WeixinAdapter(BasePlatformAdapter):
    def format_message(self, content: Optional[str]) -> str:
        if content is None:
            return ""
-        return _normalize_markdown_blocks(content)
+        return _wrap_copy_friendly_lines_for_weixin(_normalize_markdown_blocks(content))


 async def send_weixin_direct(
@@ -21,6 +21,7 @@ import logging
 import os
 import platform
 import re
+import signal
 import subprocess

 _IS_WINDOWS = platform.system() == "Windows"
@@ -54,19 +55,77 @@ def _kill_port_process(port: int) -> None:
                        except subprocess.SubprocessError:
                            pass
        else:
-            result = subprocess.run(
-                ["fuser", f"{port}/tcp"],
-                capture_output=True, timeout=5,
-            )
-            if result.returncode == 0:
-                subprocess.run(
-                    ["fuser", "-k", f"{port}/tcp"],
+            # Try fuser first (Linux), fall back to lsof (macOS / WSL2)
+            killed = False
+            try:
+                result = subprocess.run(
+                    ["fuser", f"{port}/tcp"],
                    capture_output=True, timeout=5,
                )
+                if result.returncode == 0:
+                    subprocess.run(
+                        ["fuser", "-k", f"{port}/tcp"],
+                        capture_output=True, timeout=5,
+                    )
+                    killed = True
+            except FileNotFoundError:
+                pass  # fuser not installed
+
+            if not killed:
+                try:
+                    result = subprocess.run(
+                        ["lsof", "-ti", f":{port}"],
+                        capture_output=True, text=True, timeout=5,
+                    )
+                    for pid_str in result.stdout.strip().splitlines():
+                        try:
+                            os.kill(int(pid_str), signal.SIGTERM)
+                        except (ValueError, ProcessLookupError, PermissionError):
+                            pass
+                except FileNotFoundError:
+                    pass  # lsof not installed either
    except Exception:
        pass


+def _kill_stale_bridge_by_pidfile(session_path: Path) -> None:
+    """Kill a bridge process recorded in a PID file from a previous run.
+
+    The bridge writes ``bridge.pid`` into the session directory when it
+    starts.  If the gateway crashed without a clean shutdown the old bridge
+    process becomes orphaned — this helper finds and kills it.
+    """
+    pid_file = session_path / "bridge.pid"
+    if not pid_file.exists():
+        return
+    try:
+        pid = int(pid_file.read_text().strip())
+    except (ValueError, OSError, TypeError):
+        try:
+            pid_file.unlink()
+        except OSError:
+            pass
+        return
+    try:
+        os.kill(pid, 0)  # check existence
+        os.kill(pid, signal.SIGTERM)
+        logger.info("[whatsapp] Killed stale bridge PID %d from pidfile", pid)
+    except (ProcessLookupError, PermissionError, OSError):
+        pass
+    try:
+        pid_file.unlink()
+    except OSError:
+        pass
+
+
+def _write_bridge_pidfile(session_path: Path, pid: int) -> None:
+    """Write the bridge PID to a file for later cleanup."""
+    try:
+        (session_path / "bridge.pid").write_text(str(pid))
+    except OSError:
+        pass
+
+
 def _terminate_bridge_process(proc, *, force: bool = False) -> None:
    """Terminate the bridge process using process-tree semantics where possible."""
    if _IS_WINDOWS:
@@ -158,6 +217,7 @@ class WhatsAppAdapter(BasePlatformAdapter):
    # WhatsApp message limits — practical UX limit, not protocol max.
    # WhatsApp allows ~65K but long messages are unreadable on mobile.
    MAX_MESSAGE_LENGTH = 4096
+    DEFAULT_REPLY_PREFIX = "⚕ *Hermes Agent*\n────────────\n"
    
    # Default bridge location relative to the hermes-agent install
    _DEFAULT_BRIDGE_DIR = Path(__file__).resolve().parents[2] / "scripts" / "whatsapp-bridge"
@@ -193,6 +253,25 @@ class WhatsAppAdapter(BasePlatformAdapter):
        # notification before the normal "✓ whatsapp disconnected" fires.
        self._shutting_down: bool = False

+    def _effective_reply_prefix(self) -> str:
+        """Return the prefix the Node bridge will add in self-chat mode."""
+        whatsapp_mode = os.getenv("WHATSAPP_MODE", "self-chat")
+        if whatsapp_mode != "self-chat":
+            return ""
+        if self._reply_prefix is not None:
+            return self._reply_prefix.replace("\\n", "\n")
+        env_prefix = os.getenv("WHATSAPP_REPLY_PREFIX")
+        if env_prefix is not None:
+            return env_prefix.replace("\\n", "\n")
+        return self.DEFAULT_REPLY_PREFIX
+
+    def _outgoing_chunk_limit(self) -> int:
+        """Reserve room for the bridge-side prefix so final WhatsApp text fits."""
+        prefix_len = len(self._effective_reply_prefix())
+        # Keep enough space for truncate_message's pagination indicator and
+        # code-fence repair even if a user configures a very long prefix.
+        return max(1024, self.MAX_MESSAGE_LENGTH - prefix_len)
+
    def _whatsapp_require_mention(self) -> bool:
        configured = self.config.extra.get("require_mention")
        if configured is not None:
@@ -428,6 +507,7 @@ class WhatsAppAdapter(BasePlatformAdapter):
                pass  # Bridge not running, start a new one
            
            # Kill any orphaned bridge from a previous gateway run
+            _kill_stale_bridge_by_pidfile(self._session_path)
            _kill_port_process(self._bridge_port)
            await asyncio.sleep(1)
            
@@ -459,6 +539,7 @@ class WhatsAppAdapter(BasePlatformAdapter):
                preexec_fn=None if _IS_WINDOWS else os.setsid,
                env=bridge_env,
            )
+            _write_bridge_pidfile(self._session_path, self._bridge_process.pid)
            
            # Wait for the bridge to connect to WhatsApp.
            # Phase 1: wait for the HTTP server to come up (up to 15s).
@@ -609,6 +690,12 @@ class WhatsAppAdapter(BasePlatformAdapter):
            # Bridge was not started by us, don't kill it
            print(f"[{self.name}] Disconnecting (external bridge left running)")

+        # Clean up PID file
+        try:
+            (self._session_path / "bridge.pid").unlink(missing_ok=True)
+        except OSError:
+            pass
+
        # Cancel the poll task explicitly
        if self._poll_task and not self._poll_task.done():
            self._poll_task.cancel()
@@ -713,7 +800,7 @@ class WhatsAppAdapter(BasePlatformAdapter):

            # Format and chunk the message
            formatted = self.format_message(content)
-            chunks = self.truncate_message(formatted, self.MAX_MESSAGE_LENGTH)
+            chunks = self.truncate_message(formatted, self._outgoing_chunk_limit())

            last_message_id = None
            for chunk in chunks:
@@ -258,13 +258,18 @@ def _ensure_ssl_certs() -> None:
            return

 def _home_target_env_var(platform_name: str) -> str:
-    """Return the configured home-target env var for a platform."""
-    from cron.scheduler import _HOME_TARGET_ENV_VARS
+    """Return the configured home-target env var for a platform.

-    return _HOME_TARGET_ENV_VARS.get(
-        platform_name.lower(),
-        f"{platform_name.upper()}_HOME_CHANNEL",
-    )
+    Consults built-in ``_HOME_TARGET_ENV_VARS`` first, then the plugin
+    registry via ``cron.scheduler._resolve_home_env_var``, then falls back
+    to ``<PLATFORM>_HOME_CHANNEL`` for unknown names.
+    """
+    from cron.scheduler import _resolve_home_env_var
+
+    resolved = _resolve_home_env_var(platform_name)
+    if resolved:
+        return resolved
+    return f"{platform_name.upper()}_HOME_CHANNEL"


 def _home_thread_env_var(platform_name: str) -> str:
@@ -299,6 +304,36 @@ _env_path = _hermes_home / '.env'
 load_hermes_dotenv(hermes_home=_hermes_home, project_env=Path(__file__).resolve().parents[1] / '.env')


+def _reload_runtime_env_preserving_config_authority() -> None:
+    """Reload .env for fresh credentials without letting stale .env override config.
+
+    Gateway processes are long-lived, so per-turn code reloads ~/.hermes/.env to
+    pick up rotated API keys. config.yaml remains authoritative for agent budget
+    settings such as agent.max_turns; otherwise a stale HERMES_MAX_ITERATIONS in
+    .env can replace the startup bridge on later turns.
+    """
+    load_hermes_dotenv(
+        hermes_home=_hermes_home,
+        project_env=Path(__file__).resolve().parents[1] / '.env',
+    )
+
+    config_path = _hermes_home / 'config.yaml'
+    if not config_path.exists():
+        return
+    try:
+        import yaml as _yaml
+        with open(config_path, encoding="utf-8") as f:
+            cfg = _yaml.safe_load(f) or {}
+        from hermes_cli.config import _expand_env_vars
+        cfg = _expand_env_vars(cfg)
+    except Exception:
+        return
+
+    agent_cfg = cfg.get("agent", {})
+    if isinstance(agent_cfg, dict) and "max_turns" in agent_cfg:
+        os.environ["HERMES_MAX_ITERATIONS"] = str(agent_cfg["max_turns"])
+
+
 _DOCKER_VOLUME_SPEC_RE = re.compile(r"^(?P<host>.+):(?P<container>/[^:]+?)(?::(?P<options>[^:]+))?$")
 _DOCKER_MEDIA_OUTPUT_CONTAINER_PATHS = {"/output", "/outputs"}

@@ -468,22 +503,22 @@ try:
    _network_cfg = (_cfg if '_cfg' in dir() else {}).get("network", {})
    if isinstance(_network_cfg, dict) and _network_cfg.get("force_ipv4"):
        apply_ipv4_preference(force=True)
-except Exception:
-    pass
+except Exception as _bootstrap_exc:
+    print(f"  Warning: IPv4 preference application failed: {_bootstrap_exc}", file=sys.stderr)

 # Validate config structure early — log warnings so gateway operators see problems
 try:
    from hermes_cli.config import print_config_warnings
    print_config_warnings()
-except Exception:
-    pass
+except Exception as _bootstrap_exc:
+    print(f"  Warning: config validation failed: {_bootstrap_exc}", file=sys.stderr)

 # Warn if user has deprecated MESSAGING_CWD / TERMINAL_CWD in .env
 try:
    from hermes_cli.config import warn_deprecated_cwd_env_vars
    warn_deprecated_cwd_env_vars()
-except Exception:
-    pass
+except Exception as _bootstrap_exc:
+    print(f"  Warning: deprecation check failed: {_bootstrap_exc}", file=sys.stderr)

 # Gateway runs in quiet mode - suppress debug output and use cwd directly (no temp dirs)
 os.environ["HERMES_QUIET"] = "1"
@@ -613,7 +648,11 @@ def _try_resolve_fallback_provider() -> dict | None:
                    explicit_base_url=entry.get("base_url"),
                    explicit_api_key=entry.get("api_key"),
                )
-                logger.info("Fallback provider resolved: %s", runtime.get("provider"))
+                logger.info(
+                    "Fallback provider resolved: %s model=%s",
+                    runtime.get("provider"),
+                    entry.get("model"),
+                )
                return {
                    "api_key": runtime.get("api_key"),
                    "base_url": runtime.get("base_url"),
@@ -622,6 +661,7 @@ def _try_resolve_fallback_provider() -> dict | None:
                    "command": runtime.get("command"),
                    "args": list(runtime.get("args") or []),
                    "credential_pool": runtime.get("credential_pool"),
+                    "model": entry.get("model"),
                }
            except Exception as fb_exc:
                logger.debug("Fallback entry %s failed: %s", entry.get("provider"), fb_exc)
@@ -985,6 +1025,26 @@ def _normalize_empty_agent_response(
    return response


+def _should_clear_resume_pending_after_turn(agent_result: dict) -> bool:
+    """Return True only when a gateway turn really completed successfully.
+
+    Restart recovery uses ``resume_pending`` as a durable marker for sessions
+    interrupted during gateway drain.  A soft interrupt can still bubble out as
+    a syntactically normal agent result with an empty final response; clearing
+    the marker in that case loses the recovery signal and startup auto-resume
+    has nothing to schedule.
+    """
+    if not isinstance(agent_result, dict):
+        return False
+    if agent_result.get("interrupted"):
+        return False
+    if agent_result.get("failed") or agent_result.get("partial") or agent_result.get("error"):
+        return False
+    if agent_result.get("completed") is False:
+        return False
+    return True
+
+
 class GatewayRunner:
    """
    Main gateway controller.
@@ -1066,6 +1126,13 @@ class GatewayRunner:
        self._pending_native_image_paths_by_session: Dict[str, List[str]] = {}
        self._busy_ack_ts: Dict[str, float] = {}  # last busy-ack timestamp per session (debounce)
        self._session_run_generation: Dict[str, int] = {}
+        # LRU cache of live SessionSources keyed by session_key. Used by
+        # fallback routing paths (shutdown notifications, synthetic
+        # background-process events) when the persisted origin is missing
+        # and _parse_session_key can't recover thread_id. Capped so it
+        # cannot grow unbounded over a long-running gateway lifetime.
+        self._session_sources: "OrderedDict[str, SessionSource]" = OrderedDict()
+        self._session_sources_max = 512

        # Cache AIAgent instances per session to preserve prompt caching.
        # Without this, a new AIAgent is created per message, rebuilding the
@@ -1604,6 +1671,14 @@ class GatewayRunner:
            )

        runtime_kwargs = _resolve_runtime_agent_kwargs()
+        runtime_model = runtime_kwargs.pop("model", None)
+        if runtime_model:
+            logger.info(
+                "Runtime provider supplied explicit model override: %s -> %s",
+                model,
+                runtime_model,
+            )
+            model = runtime_model
        if override and resolved_session_key:
            model, runtime_kwargs = self._apply_session_model_override(
                resolved_session_key, model, runtime_kwargs
@@ -1828,6 +1903,59 @@ class GatewayRunner:
            depth += 1
        return depth

+    @staticmethod
+    def _is_goal_continuation_event(event_or_text: Any) -> bool:
+        """Return True for synthetic /goal continuation turns.
+
+        Goal continuations are normal queued user-role events, so pause/clear
+        must distinguish them from real user /queue messages before removing or
+        suppressing them.
+        """
+        text = getattr(event_or_text, "text", event_or_text) or ""
+        return str(text).startswith("[Continuing toward your standing goal]\nGoal:")
+
+    def _clear_goal_pending_continuations(self, session_key: str, adapter: Any) -> int:
+        """Remove queued synthetic /goal continuations for one session.
+
+        User-issued /goal pause/clear can race with a continuation already
+        queued by the judge.  Remove only synthetic goal continuations while
+        preserving normal /queue and user follow-up events.
+        """
+        removed = 0
+        pending_slot = getattr(adapter, "_pending_messages", None) if adapter is not None else None
+        if isinstance(pending_slot, dict):
+            pending_event = pending_slot.get(session_key)
+            if self._is_goal_continuation_event(pending_event):
+                pending_slot.pop(session_key, None)
+                removed += 1
+
+        queued_events = getattr(self, "_queued_events", None)
+        if isinstance(queued_events, dict):
+            overflow = queued_events.get(session_key) or []
+            if overflow:
+                kept = []
+                for queued_event in overflow:
+                    if self._is_goal_continuation_event(queued_event):
+                        removed += 1
+                    else:
+                        kept.append(queued_event)
+                if kept:
+                    queued_events[session_key] = kept
+                else:
+                    queued_events.pop(session_key, None)
+        return removed
+
+    def _goal_still_active_for_session(self, session_id: str) -> bool:
+        """Best-effort fresh DB check before running a queued continuation."""
+        if not session_id:
+            return False
+        try:
+            from hermes_cli.goals import GoalManager
+            return GoalManager(session_id=session_id).is_active()
+        except Exception as exc:
+            logger.debug("goal continuation: active-state recheck failed: %s", exc)
+            return False
+
    def _update_runtime_status(self, gateway_state: Optional[str] = None, exit_reason: Optional[str] = None) -> None:
        try:
            from gateway.status import write_runtime_status
@@ -2431,6 +2559,9 @@ class GatewayRunner:
                    e,
                )

+            if source is None:
+                source = self._get_cached_session_source(session_key)
+
            if source is not None:
                platform_str = source.platform.value
                chat_id = str(source.chat_id)
@@ -2491,7 +2622,12 @@ class GatewayRunner:
                    platform_str, chat_id, e,
                )

-        for platform, adapter in self.adapters.items():
+        # Snapshot adapters up front: adapter.send() can hit a fatal error
+        # path that pops the adapter from self.adapters (see _handle_fatal
+        # elsewhere), which would otherwise trigger
+        # ``RuntimeError: dictionary changed size during iteration`` —
+        # observed in a user report during gateway shutdown.
+        for platform, adapter in list(self.adapters.items()):
            home = self.config.get_home_channel(platform)
            if not home or not home.chat_id:
                continue
@@ -2739,6 +2875,83 @@ class GatewayRunner:
        task.add_done_callback(self._background_tasks.discard)
        return True

+    # Drain-timeout reasons set by _stop_impl() when a still-running turn is
+    # force-interrupted; "restart_interrupted" is set by
+    # SessionStore.suspend_recently_active() on crash recovery (no
+    # .clean_shutdown marker).  All three mean "the agent was mid-turn and
+    # we killed it" — eligible for startup auto-resume.
+    _AUTO_RESUME_REASONS = frozenset(
+        {"restart_timeout", "shutdown_timeout", "restart_interrupted"}
+    )
+
+    def _schedule_resume_pending_sessions(self) -> int:
+        """Auto-continue fresh restart-interrupted sessions after startup.
+
+        ``resume_pending`` already preserves the transcript AND the existing
+        ``_is_resume_pending`` branch in ``_handle_message_with_agent``
+        injects a reason-aware recovery system note on the next turn.  This
+        method closes the UX gap by synthesizing that next turn once
+        adapters are back online — the event text is empty so the existing
+        injection path owns the wording and we never double up.
+
+        Adapters that are not yet ready (adapter missing from
+        ``self.adapters``) are skipped silently; their sessions stay
+        ``resume_pending`` and will auto-resume on the next real user
+        message, or on the next gateway startup.
+        """
+        window = _auto_continue_freshness_window()
+        try:
+            with self.session_store._lock:  # noqa: SLF001 — snapshot under lock
+                self.session_store._ensure_loaded_locked()  # noqa: SLF001
+                candidates = [
+                    entry for entry in self.session_store._entries.values()  # noqa: SLF001
+                    if entry.resume_pending
+                    and not entry.suspended
+                    and entry.origin is not None
+                    and entry.resume_reason in self._AUTO_RESUME_REASONS
+                ]
+        except Exception as exc:
+            logger.warning("Failed to enumerate resume-pending sessions: %s", exc)
+            return 0
+
+        now = datetime.now()
+        scheduled = 0
+        for entry in candidates:
+            marker = entry.last_resume_marked_at or entry.updated_at
+            if marker is not None and (now - marker).total_seconds() > window:
+                continue
+
+            source = entry.origin
+            adapter = self.adapters.get(source.platform)
+            if adapter is None:
+                logger.debug(
+                    "Skipping auto-resume for %s: adapter not ready for %s",
+                    entry.session_key,
+                    getattr(source.platform, "value", source.platform),
+                )
+                continue
+
+            # Empty-text internal event — the _is_resume_pending branch in
+            # _handle_message_with_agent prepends the proper reason-aware
+            # system note before the turn runs.
+            event = MessageEvent(
+                text="",
+                message_type=MessageType.TEXT,
+                source=source,
+                internal=True,
+            )
+            task = asyncio.create_task(adapter.handle_message(event))
+            self._background_tasks.add(task)
+            task.add_done_callback(self._background_tasks.discard)
+            scheduled += 1
+
+        if scheduled:
+            logger.info(
+                "Scheduled auto-resume for %d restart-interrupted session(s)",
+                scheduled,
+            )
+        return scheduled
+
    async def start(self) -> bool:
        """
        Start the gateway and all configured platform adapters.
@@ -2763,6 +2976,29 @@ class GatewayRunner:
            )
        except Exception:
            pass
+        # Redaction status: ON by default (#17691). Surface a prominent
+        # warning if an operator has explicitly opted out so they don't
+        # forget the downgrade is active — the redactor snapshots its
+        # state at import time, so this log line is the source of truth
+        # for this process's lifetime.
+        try:
+            _redact_raw = os.getenv("HERMES_REDACT_SECRETS", "true")
+            _redact_on = _redact_raw.lower() in ("1", "true", "yes", "on")
+            if _redact_on:
+                logger.info(
+                    "Secret redaction: ENABLED (tool output, logs, and chat "
+                    "responses are scrubbed before delivery)"
+                )
+            else:
+                logger.warning(
+                    "Secret redaction: DISABLED (HERMES_REDACT_SECRETS=%s). "
+                    "API keys and tokens may appear verbatim in chat output, "
+                    "session JSONs, and logs. Set security.redact_secrets: true "
+                    "in config.yaml to re-enable.",
+                    _redact_raw,
+                )
+        except Exception:
+            pass
        try:
            from hermes_cli.profiles import get_active_profile_name
            _profile = get_active_profile_name()
@@ -3127,6 +3363,12 @@ class GatewayRunner:
                skip_targets=skip_home_targets,
            )

+        # Automatically continue fresh sessions that were interrupted by the
+        # previous gateway restart/shutdown.  The resume_pending flag is cleared
+        # by the normal successful-turn path, so a failed auto-resume remains
+        # visible for manual recovery on the next user message.
+        self._schedule_resume_pending_sessions()
+
        # Drain any recovered process watchers (from crash recovery checkpoint)
        try:
            from tools.process_registry import process_registry
@@ -3645,6 +3887,24 @@ class GatewayRunner:
        if max_spawn is not None:
            logger.info(f"kanban dispatcher: max_spawn={max_spawn}")

+        raw_failure_limit = kanban_cfg.get("failure_limit", _kb.DEFAULT_FAILURE_LIMIT)
+        try:
+            failure_limit = int(raw_failure_limit)
+        except (TypeError, ValueError):
+            logger.warning(
+                "kanban dispatcher: invalid kanban.failure_limit=%r; using default %d",
+                raw_failure_limit,
+                _kb.DEFAULT_FAILURE_LIMIT,
+            )
+            failure_limit = _kb.DEFAULT_FAILURE_LIMIT
+        if failure_limit < 1:
+            logger.warning(
+                "kanban dispatcher: kanban.failure_limit=%r is below 1; using default %d",
+                raw_failure_limit,
+                _kb.DEFAULT_FAILURE_LIMIT,
+            )
+            failure_limit = _kb.DEFAULT_FAILURE_LIMIT
+
        # Initial delay so the gateway finishes wiring adapters before the
        # dispatcher spawns workers (those workers may hit gateway notify
        # subscriptions etc.). Matches the notifier watcher's delay.
@@ -3673,7 +3933,12 @@ class GatewayRunner:
                    _kb.init_db(board=slug)  # idempotent, handles first-run
                except Exception:
                    pass
-                return _kb.dispatch_once(conn, board=slug, max_spawn=max_spawn)
+                return _kb.dispatch_once(
+                    conn,
+                    board=slug,
+                    max_spawn=max_spawn,
+                    failure_limit=failure_limit,
+                )
            except Exception:
                logger.exception("kanban dispatcher: tick failed on board %s", slug)
                return None
@@ -5624,7 +5889,7 @@ class GatewayRunner:
                    except Exception:
                        session_entry = None
                    if session_entry is not None:
-                        self._post_turn_goal_continuation(
+                        await self._post_turn_goal_continuation(
                            session_entry=session_entry,
                            source=source,
                            final_response=_final_text,
@@ -5757,6 +6022,7 @@ class GatewayRunner:

        if event.media_urls and event.message_type == MessageType.DOCUMENT:
            import mimetypes as _mimetypes
+            from tools.credential_files import to_agent_visible_cache_path

            _TEXT_EXTENSIONS = {".txt", ".md", ".csv", ".log", ".json", ".xml", ".yaml", ".yml", ".toml", ".ini", ".cfg"}
            for i, path in enumerate(event.media_urls):
@@ -5777,16 +6043,21 @@ class GatewayRunner:
                display_name = parts[2] if len(parts) >= 3 else basename
                display_name = re.sub(r'[^\w.\- ]', '_', display_name)

+                # Translate host cache path to in-container path if running under Docker backend.
+                # This ensures the agent receives a path it can open inside its sandbox, as the
+                # cache directories are auto-mounted at /root/.hermes/cache/* by get_cache_directory_mounts().
+                agent_path = to_agent_visible_cache_path(path)
+
                if mtype.startswith("text/"):
                    context_note = (
                        f"[The user sent a text document: '{display_name}'. "
                        f"Its content has been included below. "
-                        f"The file is also saved at: {path}]"
+                        f"The file is also saved at: {agent_path}]"
                    )
                else:
                    context_note = (
                        f"[The user sent a document: '{display_name}'. "
-                        f"The file is saved at: {path}. "
+                        f"The file is saved at: {agent_path}. "
                        f"Ask the user what they'd like you to do with it.]"
                    )
                message_text = f"{context_note}\n\n{message_text}"
@@ -5851,6 +6122,41 @@ class GatewayRunner:
            return []
        return list(pending_native.pop(session_key, []) or [])

+    def _cache_session_source(self, session_key: str, source) -> None:
+        if not session_key or source is None:
+            return
+        cached_sources = getattr(self, "_session_sources", None)
+        if cached_sources is None:
+            cached_sources = OrderedDict()
+            self._session_sources = cached_sources
+        try:
+            cached_sources[session_key] = dataclasses.replace(source)
+        except Exception:
+            logger.debug("Failed to cache live session source for %s", session_key, exc_info=True)
+            return
+        # LRU: mark as most-recently-used and trim to max size.
+        try:
+            cached_sources.move_to_end(session_key)
+            max_size = getattr(self, "_session_sources_max", 512)
+            while len(cached_sources) > max_size:
+                cached_sources.popitem(last=False)
+        except Exception:
+            pass
+
+    def _get_cached_session_source(self, session_key: str):
+        if not session_key:
+            return None
+        cached_sources = getattr(self, "_session_sources", None)
+        if not cached_sources:
+            return None
+        source = cached_sources.get(session_key)
+        if source is not None:
+            try:
+                cached_sources.move_to_end(session_key)
+            except Exception:
+                pass
+        return source
+
    async def _handle_message_with_agent(self, event, source, _quick_key: str, run_generation: int):
        """Inner handler that runs under the _running_agents sentinel guard."""
        _msg_start_time = time.time()
@@ -5865,6 +6171,7 @@ class GatewayRunner:
        # Get or create session
        session_entry = self.session_store.get_or_create_session(source)
        session_key = session_entry.session_key
+        self._cache_session_source(session_key, source)
        if self._is_telegram_topic_lane(source):
            try:
                binding = self._session_db.get_telegram_topic_binding(
@@ -6501,7 +6808,7 @@ class GatewayRunner:
            # shutdown) — the turn ran to completion, so recovery
            # succeeded and subsequent messages should no longer receive
            # the restart-interruption system note.
-            if session_key:
+            if session_key and _should_clear_resume_pending_after_turn(agent_result):
                self._clear_restart_failure_count(session_key)
                try:
                    self.session_store.clear_resume_pending(session_key)
@@ -8082,6 +8389,27 @@ class GatewayRunner:
    # ────────────────────────────────────────────────────────────────
    # /goal — persistent cross-turn goals (Ralph-style loop)
    # ────────────────────────────────────────────────────────────────
+    def _goal_max_turns_from_config(self) -> int:
+        """Resolve the configured /goal turn budget for gateway sessions.
+
+        GatewayRunner.config is a GatewayConfig dataclass, not the full
+        user config mapping. Top-level config blocks such as ``goals`` are
+        therefore only available through hermes_cli.config.load_config().
+        """
+        try:
+            goals_cfg = (
+                (self.config or {}).get("goals", {})
+                if isinstance(self.config, dict)
+                else getattr(self.config, "goals", {}) or {}
+            )
+            if not goals_cfg:
+                from hermes_cli.config import load_config
+
+                goals_cfg = (load_config() or {}).get("goals") or {}
+            return int(goals_cfg.get("max_turns", 20) or 20)
+        except Exception:
+            return 20
+
    def _get_goal_manager_for_event(self, event: "MessageEvent"):
        """Return a GoalManager bound to the session for this gateway event.

@@ -8101,15 +8429,7 @@ class GatewayRunner:
        sid = getattr(session_entry, "session_id", None) or ""
        if not sid:
            return None, None
-        try:
-            goals_cfg = (
-                (self.config or {}).get("goals", {})
-                if isinstance(self.config, dict)
-                else getattr(self.config, "goals", {}) or {}
-            )
-            max_turns = int(goals_cfg.get("max_turns", 20) or 20)
-        except Exception:
-            max_turns = 20
+        max_turns = self._goal_max_turns_from_config()
        return GoalManager(session_id=sid, default_max_turns=max_turns), session_entry

    async def _handle_goal_command(self, event: "MessageEvent") -> str:
@@ -8137,6 +8457,13 @@ class GatewayRunner:
            state = mgr.pause(reason="user-paused")
            if state is None:
                return "No goal set."
+            try:
+                adapter = self.adapters.get(event.source.platform) if event.source else None
+                _quick_key = self._session_key_for_source(event.source) if event.source else None
+                if adapter and _quick_key:
+                    self._clear_goal_pending_continuations(_quick_key, adapter)
+            except Exception as exc:
+                logger.debug("goal pause: pending continuation cleanup failed: %s", exc)
            return f"⏸ Goal paused: {state.goal}"

        if lower == "resume":
@@ -8151,6 +8478,13 @@ class GatewayRunner:
        if lower in ("clear", "stop", "done"):
            had = mgr.has_goal()
            mgr.clear()
+            try:
+                adapter = self.adapters.get(event.source.platform) if event.source else None
+                _quick_key = self._session_key_for_source(event.source) if event.source else None
+                if adapter and _quick_key:
+                    self._clear_goal_pending_continuations(_quick_key, adapter)
+            except Exception as exc:
+                logger.debug("goal clear: pending continuation cleanup failed: %s", exc)
            return t("gateway.goal_cleared") if had else t("gateway.no_active_goal")

        # Otherwise — treat the remaining text as the new goal.
@@ -8182,7 +8516,69 @@ class GatewayRunner:
            "Controls: /goal status · /goal pause · /goal resume · /goal clear"
        )

-    def _post_turn_goal_continuation(
+    async def _send_goal_status_notice(self, source: Any, message: str) -> None:
+        """Send a /goal judge status line back to the originating chat/thread."""
+        adapter = self.adapters.get(source.platform)
+        if not adapter:
+            logger.debug("goal continuation: no adapter for %s", getattr(source, "platform", None))
+            return
+
+        try:
+            metadata = self._thread_metadata_for_source(source)
+        except Exception:
+            metadata = {"thread_id": source.thread_id} if getattr(source, "thread_id", None) else None
+
+        result = await adapter.send(source.chat_id, message, metadata=metadata)
+        if result is not None and not getattr(result, "success", True):
+            logger.warning(
+                "goal continuation: status send failed: %s",
+                getattr(result, "error", "unknown error"),
+            )
+
+    async def _defer_goal_status_notice_after_delivery(self, source: Any, message: str) -> None:
+        """Send a /goal status line after the main response is delivered.
+
+        The gateway message handler returns the agent response to the platform
+        adapter, which sends it after this method's caller has returned.  For a
+        natural Discord/Telegram reading order, goal status belongs after that
+        send.  Platform adapters provide a one-shot post-delivery callback for
+        exactly this boundary; when unavailable, fall back to direct awaited
+        delivery rather than silently dropping the notice.
+        """
+        adapter = self.adapters.get(source.platform)
+        if not adapter:
+            logger.debug("goal continuation: no adapter for %s", getattr(source, "platform", None))
+            return
+
+        async def _deliver() -> None:
+            try:
+                await self._send_goal_status_notice(source, message)
+            except Exception as exc:
+                logger.warning("goal continuation: status send failed: %s", exc, exc_info=True)
+
+        try:
+            session_key = self._session_key_for_source(source)
+        except Exception:
+            session_key = None
+
+        if session_key and hasattr(adapter, "register_post_delivery_callback"):
+            try:
+                generation = None
+                active = getattr(adapter, "_active_sessions", {}).get(session_key)
+                if active is not None:
+                    generation = getattr(active, "_hermes_run_generation", None)
+                adapter.register_post_delivery_callback(
+                    session_key,
+                    _deliver,
+                    generation=generation,
+                )
+                return
+            except Exception as exc:
+                logger.debug("goal continuation: post-delivery callback registration failed: %s", exc)
+
+        await _deliver()
+
+    async def _post_turn_goal_continuation(
        self,
        *,
        session_entry: Any,
@@ -8209,15 +8605,7 @@ class GatewayRunner:
        if not sid:
            return

-        try:
-            goals_cfg = (
-                (self.config or {}).get("goals", {})
-                if isinstance(self.config, dict)
-                else getattr(self.config, "goals", {}) or {}
-            )
-            max_turns = int(goals_cfg.get("max_turns", 20) or 20)
-        except Exception:
-            max_turns = 20
+        max_turns = self._goal_max_turns_from_config()

        mgr = GoalManager(session_id=sid, default_max_turns=max_turns)
        if not mgr.is_active():
@@ -8226,38 +8614,14 @@ class GatewayRunner:
        decision = mgr.evaluate_after_turn(final_response or "", user_initiated=True)
        msg = decision.get("message") or ""

-        # Send the status line back to the user so they see the judge's
-        # verdict. Fire-and-forget via the adapter's ``send()`` method —
-        # adapters expose ``send(chat_id, content, reply_to, metadata)``,
-        # not a ``send_message(source, msg)`` wrapper, so an earlier
-        # ``hasattr(adapter, "send_message")`` gate here was dead code and
-        # users never saw ``✓ Goal achieved`` / ``⏸ budget exhausted``
-        # verdicts.
+        # Defer the status line until after the adapter has delivered the
+        # agent's visible final response. The judge runs after the response is
+        # produced but before BasePlatformAdapter sends it, so sending here
+        # would show "✓ Goal achieved" before the answer itself. Registering
+        # an awaited post-delivery callback preserves delivery reliability
+        # without reversing the user-visible ordering.
        if msg and source is not None:
-            try:
-                adapter = self.adapters.get(source.platform)
-                if adapter is not None and hasattr(adapter, "send"):
-                    import asyncio as _asyncio
-                    thread_meta = (
-                        {"thread_id": source.thread_id} if source.thread_id else None
-                    )
-                    coro = adapter.send(
-                        chat_id=source.chat_id,
-                        content=msg,
-                        metadata=thread_meta,
-                    )
-                    if _asyncio.iscoroutine(coro):
-                        try:
-                            loop = _asyncio.get_running_loop()
-                            loop.create_task(coro)
-                        except RuntimeError:
-                            # No running loop in this thread — best effort.
-                            try:
-                                _asyncio.run(coro)
-                            except Exception:
-                                pass
-            except Exception as exc:
-                logger.debug("goal continuation: status send failed: %s", exc)
+            await self._defer_goal_status_notice_after_delivery(source, msg)

        if not decision.get("should_continue"):
            return
@@ -8760,6 +9124,12 @@ class GatewayRunner:
        from urllib.parse import quote as _quote

        try:
+            # Capture [[as_document]] before extract_media strips it, so the
+            # dispatch partition below can route image-extension files
+            # through send_document (preserving bytes) instead of
+            # send_multiple_images (Telegram sendPhoto recompresses to ~1280px).
+            force_document_attachments = "[[as_document]]" in response
+
            media_files, _ = adapter.extract_media(response)
            _, cleaned = adapter.extract_images(response)
            local_files, _ = adapter.extract_local_files(cleaned)
@@ -8772,19 +9142,24 @@ class GatewayRunner:
            _IMAGE_EXTS = {'.jpg', '.jpeg', '.png', '.webp', '.gif'}

            # Partition out images so they can be sent as a single batch
-            # (e.g. Signal's multi-attachment RPC)
+            # (e.g. Signal's multi-attachment RPC). When [[as_document]] was
+            # set, image-extension files skip the photo path and route to
+            # send_document below — preserving original bytes.
            image_paths: list = []
            non_image_media: list = []
            for media_path, is_voice in media_files:
                ext = Path(media_path).suffix.lower()
-                if ext in _IMAGE_EXTS and not is_voice:
+                if (ext in _IMAGE_EXTS
+                        and not is_voice
+                        and not force_document_attachments):
                    image_paths.append(media_path)
                else:
                    non_image_media.append((media_path, is_voice))

            non_image_local: list = []
            for file_path in local_files:
-                if Path(file_path).suffix.lower() in _IMAGE_EXTS:
+                if (Path(file_path).suffix.lower() in _IMAGE_EXTS
+                        and not force_document_attachments):
                    image_paths.append(file_path)
                else:
                    non_image_local.append(file_path)
@@ -11739,6 +12114,10 @@ class GatewayRunner:
                    exc,
                )

+            cached_source = self._get_cached_session_source(session_key)
+            if cached_source is not None:
+                return cached_source
+
            _parsed = _parse_session_key(session_key)
            if _parsed:
                derived_platform = _parsed["platform"]
@@ -11982,6 +12361,7 @@ class GatewayRunner:
    # Add more here as new baked-at-construction config settings are added.
    _CACHE_BUSTING_CONFIG_KEYS: tuple = (
        ("model", "context_length"),
+        ("model", "max_tokens"),
        ("compression", "enabled"),
        ("compression", "threshold"),
        ("compression", "target_ratio"),
@@ -12839,6 +13219,24 @@ class GatewayRunner:
        last_tool = [None]  # Mutable container for tracking in closure
        last_progress_msg = [None]  # Track last message for dedup
        repeat_count = [0]  # How many times the same message repeated
+
+        # Auto-cleanup of temporary progress bubbles (Telegram + any adapter
+        # that implements ``delete_message``). When enabled via
+        # ``display.platforms.<platform>.cleanup_progress: true``, message IDs
+        # from the tool-progress / "Still working..." / status-callback bubbles
+        # are collected here and deleted after the final response lands.
+        # Failed runs skip cleanup so the bubbles remain as breadcrumbs.
+        _cleanup_progress = bool(
+            resolve_display_setting(user_config, platform_key, "cleanup_progress")
+        )
+        _cleanup_adapter = self.adapters.get(source.platform) if _cleanup_progress else None
+        if _cleanup_adapter is not None and (
+            type(_cleanup_adapter).delete_message is BasePlatformAdapter.delete_message
+        ):
+            # Adapter doesn't support deletion — silently disable.
+            _cleanup_progress = False
+            _cleanup_adapter = None
+        _cleanup_msg_ids: List[str] = []
        # First-touch onboarding latch: fires at most once per run, even if
        # several tools exceed the threshold.
        long_tool_hint_fired = [False]
@@ -13087,12 +13485,18 @@ class GatewayRunner:
                                    adapter.name,
                                )
                            can_edit = False
-                            await adapter.send(
+                            _flood_result = await adapter.send(
                                chat_id=source.chat_id,
                                content=msg,
                                reply_to=_progress_reply_to,
                                metadata=_progress_metadata,
                            )
+                            if (
+                                _cleanup_progress
+                                and getattr(_flood_result, "success", False)
+                                and getattr(_flood_result, "message_id", None)
+                            ):
+                                _cleanup_msg_ids.append(str(_flood_result.message_id))
                    else:
                        if can_edit:
                            # First tool: send all accumulated text as new message
@@ -13113,6 +13517,8 @@ class GatewayRunner:
                            )
                        if result.success and result.message_id:
                            progress_msg_id = result.message_id
+                            if _cleanup_progress:
+                                _cleanup_msg_ids.append(str(result.message_id))

                    _last_edit_ts = time.monotonic()

@@ -13226,7 +13632,7 @@ class GatewayRunner:
            if not _status_adapter or not _run_still_current():
                return
            try:
-                asyncio.run_coroutine_threadsafe(
+                _fut = asyncio.run_coroutine_threadsafe(
                    _status_adapter.send(
                        _status_chat_id,
                        message,
@@ -13234,6 +13640,16 @@ class GatewayRunner:
                    ),
                    _loop_for_step,
                )
+                if _cleanup_progress:
+                    def _track_status_id(fut) -> None:
+                        try:
+                            res = fut.result()
+                        except Exception:
+                            return
+                        mid = getattr(res, "message_id", None)
+                        if getattr(res, "success", False) and mid:
+                            _cleanup_msg_ids.append(str(mid))
+                    _fut.add_done_callback(_track_status_id)
            except Exception as _e:
                logger.debug("status_callback error (%s): %s", event_type, _e)

@@ -13267,13 +13683,9 @@ class GatewayRunner:
                combined_ephemeral = (combined_ephemeral + "\n\n" + self._ephemeral_system_prompt).strip()

            # Re-read .env and config for fresh credentials (gateway is long-lived,
-            # keys may change without restart).
-            try:
-                load_dotenv(_env_path, override=True, encoding="utf-8")
-            except UnicodeDecodeError:
-                load_dotenv(_env_path, override=True, encoding="latin-1")
-            except Exception:
-                pass
+            # keys may change without restart). Keep config.yaml authoritative for
+            # runtime budget settings bridged into env vars.
+            _reload_runtime_env_preserving_config_authority()

            try:
                model, runtime_kwargs = self._resolve_session_agent_runtime(
@@ -13841,6 +14253,11 @@ class GatewayRunner:
                    "messages": result.get("messages", []),
                    "api_calls": result.get("api_calls", 0),
                    "failed": result.get("failed", False),
+                    "partial": result.get("partial", False),
+                    "completed": result.get("completed"),
+                    "interrupted": result.get("interrupted", False),
+                    "interrupt_message": result.get("interrupt_message"),
+                    "error": result.get("error"),
                    "compression_exhausted": result.get("compression_exhausted", False),
                    "tools": tools_holder[0] or [],
                    "history_offset": len(agent_history),
@@ -13956,6 +14373,11 @@ class GatewayRunner:
                "last_reasoning": result.get("last_reasoning"),
                "messages": result_holder[0].get("messages", []) if result_holder[0] else [],
                "api_calls": result_holder[0].get("api_calls", 0) if result_holder[0] else 0,
+                "completed": result_holder[0].get("completed") if result_holder[0] else None,
+                "interrupted": result_holder[0].get("interrupted", False) if result_holder[0] else False,
+                "partial": result_holder[0].get("partial", False) if result_holder[0] else False,
+                "error": result_holder[0].get("error") if result_holder[0] else None,
+                "interrupt_message": result_holder[0].get("interrupt_message") if result_holder[0] else None,
                "tools": tools_holder[0] or [],
                "history_offset": _effective_history_offset,
                "last_prompt_tokens": _last_prompt_toks,
@@ -14094,11 +14516,17 @@ class GatewayRunner:
                    except Exception:
                        pass
                try:
-                    await _notify_adapter.send(
+                    _notify_res = await _notify_adapter.send(
                        source.chat_id,
                        f"⏳ Still working... ({_elapsed_mins} min elapsed{_status_detail})",
                        metadata=_status_thread_metadata,
                    )
+                    if (
+                        _cleanup_progress
+                        and getattr(_notify_res, "success", False)
+                        and getattr(_notify_res, "message_id", None)
+                    ):
+                        _cleanup_msg_ids.append(str(_notify_res.message_id))
                except Exception as _ne:
                    logger.debug("Long-running notification error: %s", _ne)

@@ -14445,14 +14873,18 @@ class GatewayRunner:
                        )
                        if callable(_bg_cb):
                            try:
-                                _bg_cb()
+                                _bg_result = _bg_cb()
+                                if inspect.isawaitable(_bg_result):
+                                    await _bg_result
                            except Exception:
                                pass
                    elif adapter and hasattr(adapter, "_post_delivery_callbacks"):
                        _bg_cb = adapter._post_delivery_callbacks.pop(session_key, None)
                        if callable(_bg_cb):
                            try:
-                                _bg_cb()
+                                _bg_result = _bg_cb()
+                                if inspect.isawaitable(_bg_result):
+                                    await _bg_result
                            except Exception:
                                pass
                # else: interrupted — discard the interrupted response ("Operation
@@ -14466,6 +14898,12 @@ class GatewayRunner:
                next_channel_prompt = None
                if pending_event is not None:
                    next_source = getattr(pending_event, "source", None) or source
+                    if self._is_goal_continuation_event(pending_event) and not self._goal_still_active_for_session(session_id):
+                        logger.info(
+                            "Discarding stale goal continuation for session %s — goal is no longer active",
+                            session_key or "?",
+                        )
+                        return result
                    next_message = await self._prepare_inbound_message_text(
                        event=pending_event,
                        source=next_source,
@@ -14572,7 +15010,49 @@ class GatewayRunner:
                    _previewed,
                )
                response["already_sent"] = True
-        
+
+        # Schedule deletion of tracked temporary progress bubbles after the
+        # final response lands. Failed runs skip this so bubbles remain as
+        # breadcrumbs for the user to see what work happened. Only fires on
+        # adapters that support ``delete_message`` (see init above); failures
+        # are swallowed — deletion is best-effort.
+        if (
+            _cleanup_progress
+            and _cleanup_adapter is not None
+            and _cleanup_msg_ids
+            and session_key
+            and isinstance(response, dict)
+            and not response.get("failed")
+            and hasattr(_cleanup_adapter, "register_post_delivery_callback")
+        ):
+            _ids_snapshot = list(_cleanup_msg_ids)
+            _chat_id_snapshot = source.chat_id
+            _adapter_snapshot = _cleanup_adapter
+            _loop_snapshot = asyncio.get_running_loop()
+
+            def _cleanup_temp_bubbles() -> None:
+                async def _delete_all() -> None:
+                    for _mid in _ids_snapshot:
+                        try:
+                            await _adapter_snapshot.delete_message(
+                                _chat_id_snapshot, _mid
+                            )
+                        except Exception:
+                            pass
+                try:
+                    asyncio.run_coroutine_threadsafe(_delete_all(), _loop_snapshot)
+                except Exception:
+                    pass
+
+            try:
+                _cleanup_adapter.register_post_delivery_callback(
+                    session_key,
+                    _cleanup_temp_bubbles,
+                    generation=run_generation,
+                )
+            except Exception as _rpe:
+                logger.debug("Post-delivery cleanup registration failed: %s", _rpe)
+
        return response


@@ -15020,6 +15500,12 @@ async def start_gateway(config: Optional[GatewayConfig] = None, replace: bool =

 def main():
    """CLI entry point for the gateway."""
+    from utf8_bootstrap import ensure_windows_utf8_mode
+    ensure_windows_utf8_mode(
+        module="gateway.run",
+        entrypoint_markers=("gateway", "run.py"),
+    )
+
    import argparse
    
    parser = argparse.ArgumentParser(description="Hermes Gateway - Multi-platform messaging")
@@ -14,8 +14,8 @@ Provides subcommands for:
 import os
 import sys

-__version__ = "0.12.0"
-__release_date__ = "2026.4.30"
+__version__ = "0.13.0"
+__release_date__ = "2026.5.7"


 def _ensure_utf8():
@@ -70,6 +70,9 @@ Examples:
    hermes logs --since 1h        Lines from the last hour
    hermes debug share             Upload debug report for support
    hermes update                 Update to latest version
+    hermes dashboard              Start web UI dashboard (port 9119)
+    hermes dashboard --stop       Stop running dashboard processes
+    hermes dashboard --status     List running dashboard processes

 For more help on a command:
    hermes <command> --help
@@ -853,36 +853,48 @@ def _auth_lock_path() -> Path:

 _auth_lock_holder = threading.local()

+
@contextmanager
-def _auth_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):
-    """Cross-process advisory lock for auth.json reads+writes.  Reentrant."""
-    # Reentrant: if this thread already holds the lock, just yield.
-    if getattr(_auth_lock_holder, "depth", 0) > 0:
-        _auth_lock_holder.depth += 1
+def _file_lock(
+    lock_path: Path,
+    holder: threading.local,
+    timeout_seconds: float,
+    timeout_message: str,
+):
+    """Cross-process advisory flock helper.
+
+    Reentrant per-thread via ``holder.depth``. Falls back to a depth-only
+    guard when neither ``fcntl`` nor ``msvcrt`` is available (rare).
+    Callers supply their own ``threading.local`` so independent locks
+    (e.g. profile auth.json vs shared Nous store) don't share reentrancy
+    state — that would let one lock's reentrant acquisition silently skip
+    the other's kernel-level flock.
+    """
+    if getattr(holder, "depth", 0) > 0:
+        holder.depth += 1
        try:
            yield
        finally:
-            _auth_lock_holder.depth -= 1
+            holder.depth -= 1
        return

-    lock_path = _auth_lock_path()
    lock_path.parent.mkdir(parents=True, exist_ok=True)

    if fcntl is None and msvcrt is None:
-        _auth_lock_holder.depth = 1
+        holder.depth = 1
        try:
            yield
        finally:
-            _auth_lock_holder.depth = 0
+            holder.depth = 0
        return

    # On Windows, msvcrt.locking needs the file to have content and the
-    # file pointer at position 0.  Ensure the lock file has at least 1 byte.
+    # file pointer at position 0. Ensure the lock file has at least 1 byte.
    if msvcrt and (not lock_path.exists() or lock_path.stat().st_size == 0):
        lock_path.write_text(" ", encoding="utf-8")

    with lock_path.open("r+" if msvcrt else "a+") as lock_file:
-        deadline = time.time() + max(1.0, timeout_seconds)
+        deadline = time.monotonic() + max(1.0, timeout_seconds)
        while True:
            try:
                if fcntl:
@@ -892,15 +904,15 @@ def _auth_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):
                    msvcrt.locking(lock_file.fileno(), msvcrt.LK_NBLCK, 1)
                break
            except (BlockingIOError, OSError, PermissionError):
-                if time.time() >= deadline:
-                    raise TimeoutError("Timed out waiting for auth store lock")
+                if time.monotonic() >= deadline:
+                    raise TimeoutError(timeout_message)
                time.sleep(0.05)

-        _auth_lock_holder.depth = 1
+        holder.depth = 1
        try:
            yield
        finally:
-            _auth_lock_holder.depth = 0
+            holder.depth = 0
            if fcntl:
                fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
            elif msvcrt:
@@ -911,6 +923,25 @@ def _auth_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):
                    pass


+@contextmanager
+def _auth_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):
+    """Cross-process advisory lock for auth.json reads+writes.  Reentrant.
+
+    Lock ordering invariant: when this lock is held together with
+    ``_nous_shared_store_lock``, acquire ``_auth_store_lock`` FIRST
+    (outer) and the shared Nous lock SECOND (inner). All runtime
+    refresh paths follow this order; violating it risks deadlock
+    against a concurrent import on the shared store.
+    """
+    with _file_lock(
+        _auth_lock_path(),
+        _auth_lock_holder,
+        timeout_seconds,
+        "Timed out waiting for auth store lock",
+    ):
+        yield
+
+
 def _load_auth_store(auth_file: Optional[Path] = None) -> Dict[str, Any]:
    auth_file = auth_file or _auth_file_path()
    if not auth_file.exists():
@@ -954,12 +985,27 @@ def _load_auth_store(auth_file: Optional[Path] = None) -> Dict[str, Any]:
 def _save_auth_store(auth_store: Dict[str, Any]) -> Path:
    auth_file = _auth_file_path()
    auth_file.parent.mkdir(parents=True, exist_ok=True)
+    # Tighten parent dir to 0o700 so siblings can't traverse to creds.
+    # No-op on Windows (POSIX mode bits not enforced); ignore failures.
+    try:
+        os.chmod(auth_file.parent, 0o700)
+    except OSError:
+        pass
    auth_store["version"] = AUTH_STORE_VERSION
    auth_store["updated_at"] = datetime.now(timezone.utc).isoformat()
    payload = json.dumps(auth_store, indent=2) + "\n"
    tmp_path = auth_file.with_name(f"{auth_file.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}")
    try:
-        with tmp_path.open("w", encoding="utf-8") as handle:
+        # Create with 0o600 atomically via os.open(O_EXCL) + fdopen to close
+        # the TOCTOU window where default umask (often 0o644) briefly exposed
+        # OAuth tokens to other local users between open() and chmod().
+        # Mirrors agent/google_oauth.py (#19673) and tools/mcp_oauth.py (#21148).
+        fd = os.open(
+            str(tmp_path),
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+            stat.S_IRUSR | stat.S_IWUSR,
+        )
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
            handle.write(payload)
            handle.flush()
            os.fsync(handle.fileno())
@@ -1523,10 +1569,33 @@ def _read_qwen_cli_tokens() -> Dict[str, Any]:
 def _save_qwen_cli_tokens(tokens: Dict[str, Any]) -> Path:
    auth_path = _qwen_cli_auth_path()
    auth_path.parent.mkdir(parents=True, exist_ok=True)
-    tmp_path = auth_path.with_suffix(".tmp")
-    tmp_path.write_text(json.dumps(tokens, indent=2, sort_keys=True) + "\n", encoding="utf-8")
-    os.chmod(tmp_path, stat.S_IRUSR | stat.S_IWUSR)
-    tmp_path.replace(auth_path)
+    try:
+        os.chmod(auth_path.parent, 0o700)
+    except OSError:
+        pass
+    # Per-process random temp suffix avoids collisions between concurrent
+    # writers and stale leftovers from a crashed prior write.
+    tmp_path = auth_path.with_name(f"{auth_path.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}")
+    # Create with 0o600 atomically via os.open(O_EXCL) — closes the TOCTOU
+    # window where write_text() + post-write chmod briefly exposed tokens
+    # at process umask (typically 0o644). See #19673, #21148.
+    fd = os.open(
+        str(tmp_path),
+        os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+        stat.S_IRUSR | stat.S_IWUSR,
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(json.dumps(tokens, indent=2, sort_keys=True) + "\n")
+            fh.flush()
+            os.fsync(fh.fileno())
+        atomic_replace(tmp_path, auth_path)
+    finally:
+        try:
+            if tmp_path.exists():
+                tmp_path.unlink()
+        except OSError:
+            pass
    return auth_path


@@ -1943,9 +2012,9 @@ def _spotify_wait_for_callback(

    thread = threading.Thread(target=server.serve_forever, kwargs={"poll_interval": 0.1}, daemon=True)
    thread.start()
-    deadline = time.time() + max(5.0, timeout_seconds)
+    deadline = time.monotonic() + max(5.0, timeout_seconds)
    try:
-        while time.time() < deadline:
+        while time.monotonic() < deadline:
            if result["code"] or result["error"]:
                return result
            time.sleep(0.1)
@@ -2708,10 +2777,10 @@ def _poll_for_token(
    poll_interval: int,
 ) -> Dict[str, Any]:
    """Poll the token endpoint until the user approves or the code expires."""
-    deadline = time.time() + max(1, expires_in)
+    deadline = time.monotonic() + max(1, expires_in)
    current_interval = max(1, min(poll_interval, DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS))

-    while time.time() < deadline:
+    while time.monotonic() < deadline:
        response = client.post(
            f"{portal_base_url}/api/oauth/token",
            data={
@@ -2769,6 +2838,7 @@ def _poll_for_token(
 # -----------------------------------------------------------------------------

 NOUS_SHARED_STORE_FILENAME = "nous_auth.json"
+_nous_shared_lock_holder = threading.local()


 def _nous_shared_auth_dir() -> Path:
@@ -2808,6 +2878,69 @@ def _nous_shared_store_path() -> Path:
    return path


+@contextmanager
+def _nous_shared_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):
+    """Cross-profile lock for the shared Nous OAuth store.
+
+    Lock ordering invariant: if both this and ``_auth_store_lock`` need
+    to be held, acquire ``_auth_store_lock`` FIRST. All runtime refresh
+    paths follow this order. The one exception is
+    ``_try_import_shared_nous_state``, which holds this lock alone for
+    the entire refresh+mint cycle so concurrent imports on sibling
+    profiles can't race on the single-use shared refresh token; that
+    helper must NOT be called with ``_auth_store_lock`` already held.
+    """
+    try:
+        lock_path = _nous_shared_store_path().with_suffix(".lock")
+    except RuntimeError:
+        # No HERMES_HOME yet (pre-setup): fall through without locking.
+        yield
+        return
+
+    with _file_lock(
+        lock_path,
+        _nous_shared_lock_holder,
+        timeout_seconds,
+        "Timed out waiting for shared Nous auth lock",
+    ):
+        yield
+
+
+def _merge_shared_nous_oauth_state(state: Dict[str, Any]) -> bool:
+    """Copy fresher shared OAuth tokens into a profile-local Nous state."""
+    shared = _read_shared_nous_state()
+    if not shared:
+        return False
+
+    shared_refresh = shared.get("refresh_token")
+    if not isinstance(shared_refresh, str) or not shared_refresh.strip():
+        return False
+
+    local_refresh = state.get("refresh_token")
+    shared_access_exp = _parse_iso_timestamp(shared.get("expires_at")) or 0.0
+    local_access_exp = _parse_iso_timestamp(state.get("expires_at")) or 0.0
+    refresh_changed = shared_refresh.strip() != str(local_refresh or "").strip()
+    fresher_access = shared_access_exp > local_access_exp
+    if not refresh_changed and not fresher_access:
+        return False
+
+    for key in (
+        "access_token",
+        "refresh_token",
+        "token_type",
+        "scope",
+        "client_id",
+        "portal_base_url",
+        "inference_base_url",
+        "obtained_at",
+        "expires_at",
+    ):
+        value = shared.get(key)
+        if value not in (None, ""):
+            state[key] = value
+    return True
+
+
 def _write_shared_nous_state(state: Dict[str, Any]) -> None:
    """Persist a minimal copy of the Nous OAuth state to the shared store.

@@ -2840,15 +2973,34 @@ def _write_shared_nous_state(state: Dict[str, Any]) -> None:
        "updated_at": datetime.now(timezone.utc).isoformat(),
    }
    try:
-        path = _nous_shared_store_path()
-        path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = path.with_suffix(path.suffix + ".tmp")
-        tmp.write_text(json.dumps(shared, indent=2, sort_keys=True))
-        try:
-            os.chmod(tmp, 0o600)
-        except OSError:
-            pass
-        os.replace(tmp, path)
+        with _nous_shared_store_lock():
+            path = _nous_shared_store_path()
+            path.parent.mkdir(parents=True, exist_ok=True)
+            try:
+                os.chmod(path.parent, 0o700)
+            except OSError:
+                pass
+            tmp = path.with_name(f"{path.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}")
+            # Create with 0o600 atomically via os.open(O_EXCL) — closes the TOCTOU
+            # window where write_text() + post-write chmod briefly exposed Nous
+            # refresh_token at process umask. See #19673, #21148.
+            fd = os.open(
+                str(tmp),
+                os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+                stat.S_IRUSR | stat.S_IWUSR,
+            )
+            try:
+                with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                    fh.write(json.dumps(shared, indent=2, sort_keys=True))
+                    fh.flush()
+                    os.fsync(fh.fileno())
+                os.replace(tmp, path)
+            finally:
+                try:
+                    if tmp.exists():
+                        tmp.unlink()
+                except OSError:
+                    pass
        _oauth_trace(
            "nous_shared_store_written",
            path=str(path),
@@ -2905,36 +3057,38 @@ def _try_import_shared_nous_state(
    etc.) — caller should then fall through to the normal device-code
    flow.
    """
-    shared = _read_shared_nous_state()
-    if not shared:
-        return None
-
-    # Build a full state dict so refresh_nous_oauth_from_state has every
-    # field it needs. force_refresh=True gets us a fresh access_token
-    # for this profile; force_mint=True gets us a fresh agent_key.
-    state: Dict[str, Any] = {
-        "access_token": shared.get("access_token"),
-        "refresh_token": shared.get("refresh_token"),
-        "client_id": shared.get("client_id") or DEFAULT_NOUS_CLIENT_ID,
-        "portal_base_url": shared.get("portal_base_url") or DEFAULT_NOUS_PORTAL_URL,
-        "inference_base_url": shared.get("inference_base_url") or DEFAULT_NOUS_INFERENCE_URL,
-        "token_type": shared.get("token_type") or "Bearer",
-        "scope": shared.get("scope") or DEFAULT_NOUS_SCOPE,
-        "obtained_at": shared.get("obtained_at"),
-        "expires_at": shared.get("expires_at"),
-        "agent_key": None,
-        "agent_key_expires_at": None,
-        "tls": {"insecure": False, "ca_bundle": None},
-    }
-
    try:
-        refreshed = refresh_nous_oauth_from_state(
-            state,
-            min_key_ttl_seconds=min_key_ttl_seconds,
-            timeout_seconds=timeout_seconds,
-            force_refresh=True,
-            force_mint=True,
-        )
+        with _nous_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):
+            shared = _read_shared_nous_state()
+            if not shared:
+                return None
+
+            # Build a full state dict so refresh_nous_oauth_from_state has every
+            # field it needs. force_refresh=True gets us a fresh access_token
+            # for this profile; force_mint=True gets us a fresh agent_key.
+            state: Dict[str, Any] = {
+                "access_token": shared.get("access_token"),
+                "refresh_token": shared.get("refresh_token"),
+                "client_id": shared.get("client_id") or DEFAULT_NOUS_CLIENT_ID,
+                "portal_base_url": shared.get("portal_base_url") or DEFAULT_NOUS_PORTAL_URL,
+                "inference_base_url": shared.get("inference_base_url") or DEFAULT_NOUS_INFERENCE_URL,
+                "token_type": shared.get("token_type") or "Bearer",
+                "scope": shared.get("scope") or DEFAULT_NOUS_SCOPE,
+                "obtained_at": shared.get("obtained_at"),
+                "expires_at": shared.get("expires_at"),
+                "agent_key": None,
+                "agent_key_expires_at": None,
+                "tls": {"insecure": False, "ca_bundle": None},
+            }
+
+            refreshed = refresh_nous_oauth_from_state(
+                state,
+                min_key_ttl_seconds=min_key_ttl_seconds,
+                timeout_seconds=timeout_seconds,
+                force_refresh=True,
+                force_mint=True,
+            )
+            _write_shared_nous_state(refreshed)
    except AuthError as exc:
        _oauth_trace(
            "nous_shared_import_failed",
@@ -3136,59 +3290,65 @@ def resolve_nous_access_token(
        client_id = str(state.get("client_id") or DEFAULT_NOUS_CLIENT_ID)
        verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)

-        access_token = state.get("access_token")
-        refresh_token = state.get("refresh_token")
-        if not isinstance(access_token, str) or not access_token:
-            raise AuthError(
-                "No access token found for Nous Portal login.",
-                provider="nous",
-                relogin_required=True,
-            )
+        with _nous_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):
+            merged_shared = _merge_shared_nous_oauth_state(state)
+            access_token = state.get("access_token")
+            refresh_token = state.get("refresh_token")
+            if not isinstance(access_token, str) or not access_token:
+                raise AuthError(
+                    "No access token found for Nous Portal login.",
+                    provider="nous",
+                    relogin_required=True,
+                )

-        if not _is_expiring(state.get("expires_at"), refresh_skew_seconds):
-            return access_token
+            if not _is_expiring(state.get("expires_at"), refresh_skew_seconds):
+                if merged_shared:
+                    _save_provider_state(auth_store, "nous", state)
+                    _save_auth_store(auth_store)
+                return access_token

-        if not isinstance(refresh_token, str) or not refresh_token:
-            raise AuthError(
-                "Session expired and no refresh token is available.",
-                provider="nous",
-                relogin_required=True,
-            )
+            if not isinstance(refresh_token, str) or not refresh_token:
+                raise AuthError(
+                    "Session expired and no refresh token is available.",
+                    provider="nous",
+                    relogin_required=True,
+                )

-        timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)
-        with httpx.Client(
-            timeout=timeout,
-            headers={"Accept": "application/json"},
-            verify=verify,
-        ) as client:
-            refreshed = _refresh_access_token(
-                client=client,
-                portal_base_url=portal_base_url,
-                client_id=client_id,
-                refresh_token=refresh_token,
-            )
+            timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)
+            with httpx.Client(
+                timeout=timeout,
+                headers={"Accept": "application/json"},
+                verify=verify,
+            ) as client:
+                refreshed = _refresh_access_token(
+                    client=client,
+                    portal_base_url=portal_base_url,
+                    client_id=client_id,
+                    refresh_token=refresh_token,
+                )

-        now = datetime.now(timezone.utc)
-        access_ttl = _coerce_ttl_seconds(refreshed.get("expires_in"))
-        state["access_token"] = refreshed["access_token"]
-        state["refresh_token"] = refreshed.get("refresh_token") or refresh_token
-        state["token_type"] = refreshed.get("token_type") or state.get("token_type") or "Bearer"
-        state["scope"] = refreshed.get("scope") or state.get("scope")
-        state["obtained_at"] = now.isoformat()
-        state["expires_in"] = access_ttl
-        state["expires_at"] = datetime.fromtimestamp(
-            now.timestamp() + access_ttl,
-            tz=timezone.utc,
-        ).isoformat()
-        state["portal_base_url"] = portal_base_url
-        state["client_id"] = client_id
-        state["tls"] = {
-            "insecure": verify is False,
-            "ca_bundle": verify if isinstance(verify, str) else None,
-        }
-        _save_provider_state(auth_store, "nous", state)
-        _save_auth_store(auth_store)
-        return state["access_token"]
+            now = datetime.now(timezone.utc)
+            access_ttl = _coerce_ttl_seconds(refreshed.get("expires_in"))
+            state["access_token"] = refreshed["access_token"]
+            state["refresh_token"] = refreshed.get("refresh_token") or refresh_token
+            state["token_type"] = refreshed.get("token_type") or state.get("token_type") or "Bearer"
+            state["scope"] = refreshed.get("scope") or state.get("scope")
+            state["obtained_at"] = now.isoformat()
+            state["expires_in"] = access_ttl
+            state["expires_at"] = datetime.fromtimestamp(
+                now.timestamp() + access_ttl,
+                tz=timezone.utc,
+            ).isoformat()
+            state["portal_base_url"] = portal_base_url
+            state["client_id"] = client_id
+            state["tls"] = {
+                "insecure": verify is False,
+                "ca_bundle": verify if isinstance(verify, str) else None,
+            }
+            _save_provider_state(auth_store, "nous", state)
+            _save_auth_store(auth_store)
+            _write_shared_nous_state(state)
+            return state["access_token"]


 def refresh_nous_oauth_pure(
@@ -3456,46 +3616,53 @@ def resolve_nous_runtime_credentials(

            # Step 1: refresh access token if expiring
            if _is_expiring(state.get("expires_at"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS):
-                if not isinstance(refresh_token, str) or not refresh_token:
-                    raise AuthError("Session expired and no refresh token is available.",
-                                    provider="nous", relogin_required=True)
+                with _nous_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):
+                    if _merge_shared_nous_oauth_state(state):
+                        access_token = state.get("access_token")
+                        refresh_token = state.get("refresh_token")
+                        _persist_state("post_shared_merge_access_expiring")

-                _oauth_trace(
-                    "refresh_start",
-                    sequence_id=sequence_id,
-                    reason="access_expiring",
-                    refresh_token_fp=_token_fingerprint(refresh_token),
-                )
-                refreshed = _refresh_access_token(
-                    client=client, portal_base_url=portal_base_url,
-                    client_id=client_id, refresh_token=refresh_token,
-                )
-                now = datetime.now(timezone.utc)
-                access_ttl = _coerce_ttl_seconds(refreshed.get("expires_in"))
-                previous_refresh_token = refresh_token
-                state["access_token"] = refreshed["access_token"]
-                state["refresh_token"] = refreshed.get("refresh_token") or refresh_token
-                state["token_type"] = refreshed.get("token_type") or state.get("token_type") or "Bearer"
-                state["scope"] = refreshed.get("scope") or state.get("scope")
-                refreshed_url = _optional_base_url(refreshed.get("inference_base_url"))
-                if refreshed_url:
-                    inference_base_url = refreshed_url
-                state["obtained_at"] = now.isoformat()
-                state["expires_in"] = access_ttl
-                state["expires_at"] = datetime.fromtimestamp(
-                    now.timestamp() + access_ttl, tz=timezone.utc
-                ).isoformat()
-                access_token = state["access_token"]
-                refresh_token = state["refresh_token"]
-                _oauth_trace(
-                    "refresh_success",
-                    sequence_id=sequence_id,
-                    reason="access_expiring",
-                    previous_refresh_token_fp=_token_fingerprint(previous_refresh_token),
-                    new_refresh_token_fp=_token_fingerprint(refresh_token),
-                )
-                # Persist immediately so downstream mint failures cannot drop rotated refresh tokens.
-                _persist_state("post_refresh_access_expiring")
+                    if _is_expiring(state.get("expires_at"), ACCESS_TOKEN_REFRESH_SKEW_SECONDS):
+                        if not isinstance(refresh_token, str) or not refresh_token:
+                            raise AuthError("Session expired and no refresh token is available.",
+                                            provider="nous", relogin_required=True)
+
+                        _oauth_trace(
+                            "refresh_start",
+                            sequence_id=sequence_id,
+                            reason="access_expiring",
+                            refresh_token_fp=_token_fingerprint(refresh_token),
+                        )
+                        refreshed = _refresh_access_token(
+                            client=client, portal_base_url=portal_base_url,
+                            client_id=client_id, refresh_token=refresh_token,
+                        )
+                        now = datetime.now(timezone.utc)
+                        access_ttl = _coerce_ttl_seconds(refreshed.get("expires_in"))
+                        previous_refresh_token = refresh_token
+                        state["access_token"] = refreshed["access_token"]
+                        state["refresh_token"] = refreshed.get("refresh_token") or refresh_token
+                        state["token_type"] = refreshed.get("token_type") or state.get("token_type") or "Bearer"
+                        state["scope"] = refreshed.get("scope") or state.get("scope")
+                        refreshed_url = _optional_base_url(refreshed.get("inference_base_url"))
+                        if refreshed_url:
+                            inference_base_url = refreshed_url
+                        state["obtained_at"] = now.isoformat()
+                        state["expires_in"] = access_ttl
+                        state["expires_at"] = datetime.fromtimestamp(
+                            now.timestamp() + access_ttl, tz=timezone.utc
+                        ).isoformat()
+                        access_token = state["access_token"]
+                        refresh_token = state["refresh_token"]
+                        _oauth_trace(
+                            "refresh_success",
+                            sequence_id=sequence_id,
+                            reason="access_expiring",
+                            previous_refresh_token_fp=_token_fingerprint(previous_refresh_token),
+                            new_refresh_token_fp=_token_fingerprint(refresh_token),
+                        )
+                        # Persist immediately so downstream mint failures cannot drop rotated refresh tokens.
+                        _persist_state("post_refresh_access_expiring")

            # Step 2: mint agent key if missing/expiring
            used_cached_key = False
@@ -3528,41 +3695,47 @@ def resolve_nous_runtime_credentials(
                        and isinstance(latest_refresh_token, str)
                        and latest_refresh_token
                    ):
-                        _oauth_trace(
-                            "refresh_start",
-                            sequence_id=sequence_id,
-                            reason="mint_retry_after_invalid_token",
-                            refresh_token_fp=_token_fingerprint(latest_refresh_token),
-                        )
-                        refreshed = _refresh_access_token(
-                            client=client, portal_base_url=portal_base_url,
-                            client_id=client_id, refresh_token=latest_refresh_token,
-                        )
-                        now = datetime.now(timezone.utc)
-                        access_ttl = _coerce_ttl_seconds(refreshed.get("expires_in"))
-                        state["access_token"] = refreshed["access_token"]
-                        state["refresh_token"] = refreshed.get("refresh_token") or latest_refresh_token
-                        state["token_type"] = refreshed.get("token_type") or state.get("token_type") or "Bearer"
-                        state["scope"] = refreshed.get("scope") or state.get("scope")
-                        refreshed_url = _optional_base_url(refreshed.get("inference_base_url"))
-                        if refreshed_url:
-                            inference_base_url = refreshed_url
-                        state["obtained_at"] = now.isoformat()
-                        state["expires_in"] = access_ttl
-                        state["expires_at"] = datetime.fromtimestamp(
-                            now.timestamp() + access_ttl, tz=timezone.utc
-                        ).isoformat()
-                        access_token = state["access_token"]
-                        refresh_token = state["refresh_token"]
-                        _oauth_trace(
-                            "refresh_success",
-                            sequence_id=sequence_id,
-                            reason="mint_retry_after_invalid_token",
-                            previous_refresh_token_fp=_token_fingerprint(latest_refresh_token),
-                            new_refresh_token_fp=_token_fingerprint(refresh_token),
-                        )
-                        # Persist retry refresh immediately for crash safety and cross-process visibility.
-                        _persist_state("post_refresh_mint_retry")
+                        with _nous_shared_store_lock(timeout_seconds=max(timeout_seconds + 5.0, AUTH_LOCK_TIMEOUT_SECONDS)):
+                            if _merge_shared_nous_oauth_state(state):
+                                access_token = state.get("access_token")
+                                latest_refresh_token = state.get("refresh_token")
+                                _persist_state("post_shared_merge_mint_retry")
+                            else:
+                                _oauth_trace(
+                                    "refresh_start",
+                                    sequence_id=sequence_id,
+                                    reason="mint_retry_after_invalid_token",
+                                    refresh_token_fp=_token_fingerprint(latest_refresh_token),
+                                )
+                                refreshed = _refresh_access_token(
+                                    client=client, portal_base_url=portal_base_url,
+                                    client_id=client_id, refresh_token=latest_refresh_token,
+                                )
+                                now = datetime.now(timezone.utc)
+                                access_ttl = _coerce_ttl_seconds(refreshed.get("expires_in"))
+                                state["access_token"] = refreshed["access_token"]
+                                state["refresh_token"] = refreshed.get("refresh_token") or latest_refresh_token
+                                state["token_type"] = refreshed.get("token_type") or state.get("token_type") or "Bearer"
+                                state["scope"] = refreshed.get("scope") or state.get("scope")
+                                refreshed_url = _optional_base_url(refreshed.get("inference_base_url"))
+                                if refreshed_url:
+                                    inference_base_url = refreshed_url
+                                state["obtained_at"] = now.isoformat()
+                                state["expires_in"] = access_ttl
+                                state["expires_at"] = datetime.fromtimestamp(
+                                    now.timestamp() + access_ttl, tz=timezone.utc
+                                ).isoformat()
+                                access_token = state["access_token"]
+                                refresh_token = state["refresh_token"]
+                                _oauth_trace(
+                                    "refresh_success",
+                                    sequence_id=sequence_id,
+                                    reason="mint_retry_after_invalid_token",
+                                    previous_refresh_token_fp=_token_fingerprint(latest_refresh_token),
+                                    new_refresh_token_fp=_token_fingerprint(refresh_token),
+                                )
+                                # Persist retry refresh immediately for crash safety and cross-process visibility.
+                                _persist_state("post_refresh_mint_retry")

                        mint_payload = _mint_agent_key(
                            client=client, portal_base_url=portal_base_url,
@@ -4058,6 +4231,14 @@ def _config_provider_matches(provider_id: Optional[str]) -> bool:
    return _get_config_provider() == provider_id.strip().lower()


+def _should_reset_config_provider_on_logout(provider_id: Optional[str]) -> bool:
+    """Return True when logout should reset the model provider config."""
+    if not provider_id:
+        return False
+    normalized = provider_id.strip().lower()
+    return normalized in PROVIDER_REGISTRY and _config_provider_matches(normalized)
+
+
 def _logout_default_provider_from_config() -> Optional[str]:
    """Fallback logout target when auth.json has no active provider.

@@ -5143,15 +5324,18 @@ def logout_command(args) -> None:
        print("No provider is currently logged in.")
        return

-    config_matches = _config_provider_matches(target)
+    should_reset_config = _should_reset_config_provider_on_logout(target)
    provider_name = get_auth_provider_display_name(target)

-    if clear_provider_auth(target) or config_matches:
-        _reset_config_provider()
+    if clear_provider_auth(target) or should_reset_config:
+        if should_reset_config:
+            _reset_config_provider()
        print(f"Logged out of {provider_name}.")
-        if os.getenv("OPENROUTER_API_KEY"):
+        if should_reset_config and os.getenv("OPENROUTER_API_KEY"):
            print("Hermes will use OpenRouter for inference.")
-        else:
+        elif should_reset_config:
            print("Run `hermes model` or configure an API key to use Hermes.")
+        else:
+            print("Model provider configuration was unchanged.")
    else:
        print(f"No auth state found for {provider_name}.")
@@ -109,6 +109,9 @@ COMMAND_REGISTRY: list[CommandDef] = [
    CommandDef("resume", "Resume a previously-named session", "Session",
               args_hint="[name]"),

+    # Configuration
+    CommandDef("sessions", "Browse and resume previous sessions", "Session"),
+
    # Configuration
    CommandDef("config", "Show current configuration", "Configuration",
               cli_only=True),
@@ -157,9 +160,9 @@ COMMAND_REGISTRY: list[CommandDef] = [
    CommandDef("cron", "Manage scheduled tasks", "Tools & Skills",
               cli_only=True, args_hint="[subcommand]",
               subcommands=("list", "add", "create", "edit", "pause", "resume", "run", "remove")),
-    CommandDef("curator", "Background skill maintenance (status, run, pin, archive)",
+    CommandDef("curator", "Background skill maintenance (status, run, pin, archive, list-archived)",
               "Tools & Skills", args_hint="[subcommand]",
-               subcommands=("status", "run", "pause", "resume", "pin", "unpin", "restore")),
+               subcommands=("status", "run", "pause", "resume", "pin", "unpin", "restore", "list-archived")),
    CommandDef("kanban", "Multi-profile collaboration board (tasks, links, comments)",
               "Tools & Skills", args_hint="[subcommand]",
               subcommands=("list", "ls", "show", "create", "assign", "link", "unlink",
@@ -21,6 +21,7 @@ import stat
 import subprocess
 import sys
 import tempfile
+import threading
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Dict, Any, Optional, List, Tuple
@@ -42,6 +43,14 @@ _LOAD_CONFIG_CACHE: Dict[str, Tuple[int, int, Dict[str, Any]]] = {}
 # _LOAD_CONFIG_CACHE but for read_raw_config() — used when callers want
 # the user's on-disk values without defaults merged in.
 _RAW_CONFIG_CACHE: Dict[str, Tuple[int, int, Dict[str, Any]]] = {}
+# Serializes all config read/write paths. libyaml's C extension is not
+# thread-safe for concurrent safe_load() on the same file, and multiple
+# tool threads (approval.py, browser_tool.py, setup flows) hit
+# load_config / read_raw_config / save_config from different threads
+# during long agent runs. RLock (not Lock) because save_config internally
+# calls read_raw_config. Also covers mutation of the module-level cache
+# dicts above.
+_CONFIG_LOCK = threading.RLock()
 # Env var names written to .env that aren't in OPTIONAL_ENV_VARS
 # (managed by setup/provider flows directly).
 _EXTRA_ENV_KEYS = frozenset({
@@ -780,6 +789,19 @@ DEFAULT_CONFIG = {
            "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
+        # cheap, capable model here (gemini-flash works well); the main
+        # model is overkill for short spec expansion.
+        "triage_specifier": {
+            "provider": "auto",
+            "model": "",
+            "base_url": "",
+            "api_key": "",
+            "timeout": 120,
+            "extra_body": {},
+        },
        # Curator — skill-usage review fork. Timeout is generous because the
        # review pass can take several minutes on reasoning models (umbrella
        # building over hundreds of candidate skills). "auto" = use main chat
@@ -1100,6 +1122,14 @@ DEFAULT_CONFIG = {
    # Empty string means use server-local time.
    "timezone": "",

+    # Slack platform settings (gateway mode)
+    "slack": {
+        "require_mention": True,       # Require @mention to respond in channels
+        "free_response_channels": "",  # Comma-separated channel IDs where bot responds without mention
+        "allowed_channels": "",        # If set, bot ONLY responds in these channel IDs (whitelist)
+        "channel_prompts": {},         # Per-channel ephemeral system prompts
+    },
+
    # Discord platform settings (gateway mode)
    "discord": {
        "require_mention": True,       # Require @mention to respond in server channels
@@ -1108,6 +1138,12 @@ DEFAULT_CONFIG = {
        "auto_thread": True,           # Auto-create threads on @mention in channels (like Slack)
        "reactions": True,             # Add 👀/✅/❌ reactions to messages during processing
        "channel_prompts": {},         # Per-channel ephemeral system prompts (forum parents apply to child threads)
+        # Opt-in DM role-based auth (#12136). By default, DISCORD_ALLOWED_ROLES
+        # authorizes only guild messages in the role's own guild — DMs require
+        # DISCORD_ALLOWED_USERS. Set dm_role_auth_guild to a guild ID to also
+        # authorize DMs from members of that one trusted guild holding the
+        # allowed role. Unset / empty / 0 = secure default (DM role-auth off).
+        "dm_role_auth_guild": "",
        # discord / discord_admin tools: restrict which actions the agent may call.
        # Default (empty) = all actions allowed (subject to bot privileged intents).
        # Accepts comma-separated string ("list_guilds,list_channels,fetch_messages")
@@ -1130,18 +1166,24 @@ DEFAULT_CONFIG = {
    "telegram": {
        "reactions": False,            # Add 👀/✅/❌ reactions to messages during processing
        "channel_prompts": {},         # Per-chat/topic ephemeral system prompts (topics inherit from parent group)
-    },
-
-    # Slack platform settings (gateway mode)
-    "slack": {
-        "channel_prompts": {},         # Per-channel ephemeral system prompts
+        "allowed_chats": "",           # If set, bot ONLY responds in these group/supergroup chat IDs (whitelist)
    },

    # Mattermost platform settings (gateway mode)
    "mattermost": {
+        "require_mention": True,       # Require @mention to respond in channels
+        "free_response_channels": "",  # Comma-separated channel IDs where bot responds without mention
+        "allowed_channels": "",        # If set, bot ONLY responds in these channel IDs (whitelist)
        "channel_prompts": {},         # Per-channel ephemeral system prompts
    },

+    # Matrix platform settings (gateway mode)
+    "matrix": {
+        "require_mention": True,       # Require @mention to respond in rooms
+        "free_response_rooms": "",     # Comma-separated room IDs where bot responds without mention
+        "allowed_rooms": "",           # If set, bot ONLY responds in these room IDs (whitelist)
+    },
+
    # Approval mode for dangerous commands:
    #   manual — always prompt the user (default)
    #   smart  — use auxiliary LLM to auto-approve low-risk commands, prompt for high-risk
@@ -1191,7 +1233,7 @@ DEFAULT_CONFIG = {
    # Pre-exec security scanning via tirith
    "security": {
        "allow_private_urls": False,  # Allow requests to private/internal IPs (for OpenWrt, proxies, VPNs)
-        "redact_secrets": False,
+        "redact_secrets": True,
        "tirith_enabled": True,
        "tirith_path": "tirith",
        "tirith_timeout": 5,
@@ -1230,6 +1272,10 @@ DEFAULT_CONFIG = {
        # Seconds between dispatcher ticks (idle or not). Lower = snappier
        # pickup of newly-ready tasks; higher = less SQL pressure.
        "dispatch_interval_seconds": 60,
+        # Auto-block after this many consecutive non-success attempts for the
+        # same task/profile (spawn_failed, timed_out, or crashed). Reassignment
+        # resets the streak for the new profile.
+        "failure_limit": 2,
    },

    # execute_code settings — controls the tool used for programmatic tool calls.
@@ -1840,6 +1886,14 @@ OPTIONAL_ENV_VARS = {
        "password": False,
        "category": "tool",
    },
+    "BRAVE_SEARCH_API_KEY": {
+        "description": "Brave Search API subscription token (free tier: 2,000 queries/mo)",
+        "prompt": "Brave Search subscription token",
+        "url": "https://brave.com/search/api/",
+        "tools": ["web_search"],
+        "password": True,
+        "category": "tool",
+    },
    "BROWSERBASE_API_KEY": {
        "description": "Browserbase API key for cloud browser (optional — local browser works without this)",
        "prompt": "Browserbase API key",
@@ -3896,28 +3950,29 @@ def read_raw_config() -> Dict[str, Any]:
    ``load_config()``. Returns a deepcopy on every call since some callers
    mutate the result before passing to ``save_config()``.
    """
-    try:
-        config_path = get_config_path()
-        st = config_path.stat()
-        cache_key = (st.st_mtime_ns, st.st_size)
-    except (FileNotFoundError, OSError):
-        return {}
+    with _CONFIG_LOCK:
+        try:
+            config_path = get_config_path()
+            st = config_path.stat()
+            cache_key = (st.st_mtime_ns, st.st_size)
+        except (FileNotFoundError, OSError):
+            return {}

-    path_key = str(config_path)
-    cached = _RAW_CONFIG_CACHE.get(path_key)
-    if cached is not None and cached[:2] == cache_key:
-        return copy.deepcopy(cached[2])
+        path_key = str(config_path)
+        cached = _RAW_CONFIG_CACHE.get(path_key)
+        if cached is not None and cached[:2] == cache_key:
+            return copy.deepcopy(cached[2])

-    try:
-        with open(config_path, encoding="utf-8") as f:
-            data = yaml.safe_load(f) or {}
-    except Exception:
-        return {}
+        try:
+            with open(config_path, encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+        except Exception:
+            return {}

-    if not isinstance(data, dict):
-        data = {}
-    _RAW_CONFIG_CACHE[path_key] = (cache_key[0], cache_key[1], copy.deepcopy(data))
-    return data
+        if not isinstance(data, dict):
+            data = {}
+        _RAW_CONFIG_CACHE[path_key] = (cache_key[0], cache_key[1], copy.deepcopy(data))
+        return data


 def load_config() -> Dict[str, Any]:
@@ -3930,54 +3985,55 @@ def load_config() -> Dict[str, Any]:
    (which change ``HERMES_HOME`` and therefore ``get_config_path()``)
    don't collide.
    """
-    ensure_hermes_home()
-    config_path = get_config_path()
-    path_key = str(config_path)
+    with _CONFIG_LOCK:
+        ensure_hermes_home()
+        config_path = get_config_path()
+        path_key = str(config_path)

-    try:
-        st = config_path.stat()
-        cache_key: Optional[Tuple[int, int]] = (st.st_mtime_ns, st.st_size)
-    except FileNotFoundError:
-        cache_key = None
-
-    cached = _LOAD_CONFIG_CACHE.get(path_key)
-    if cached is not None and cache_key is not None and cached[:2] == cache_key:
-        return copy.deepcopy(cached[2])
-
-    config = copy.deepcopy(DEFAULT_CONFIG)
-
-    if cache_key is not None:
        try:
-            with open(config_path, encoding="utf-8") as f:
-                user_config = yaml.safe_load(f) or {}
+            st = config_path.stat()
+            cache_key: Optional[Tuple[int, int]] = (st.st_mtime_ns, st.st_size)
+        except FileNotFoundError:
+            cache_key = None

-            if "max_turns" in user_config:
-                agent_user_config = dict(user_config.get("agent") or {})
-                if agent_user_config.get("max_turns") is None:
-                    agent_user_config["max_turns"] = user_config["max_turns"]
-                user_config["agent"] = agent_user_config
-                user_config.pop("max_turns", None)
+        cached = _LOAD_CONFIG_CACHE.get(path_key)
+        if cached is not None and cache_key is not None and cached[:2] == cache_key:
+            return copy.deepcopy(cached[2])

-            config = _deep_merge(config, user_config)
-        except Exception as e:
-            print(f"Warning: Failed to load config: {e}")
+        config = copy.deepcopy(DEFAULT_CONFIG)

-    normalized = _normalize_root_model_keys(_normalize_max_turns_config(config))
-    expanded = _expand_env_vars(normalized)
-    _LAST_EXPANDED_CONFIG_BY_PATH[path_key] = copy.deepcopy(expanded)
-    if cache_key is not None:
-        _LOAD_CONFIG_CACHE[path_key] = (cache_key[0], cache_key[1], copy.deepcopy(expanded))
-    else:
-        _LOAD_CONFIG_CACHE.pop(path_key, None)
-    return expanded
+        if cache_key is not None:
+            try:
+                with open(config_path, encoding="utf-8") as f:
+                    user_config = yaml.safe_load(f) or {}
+
+                if "max_turns" in user_config:
+                    agent_user_config = dict(user_config.get("agent") or {})
+                    if agent_user_config.get("max_turns") is None:
+                        agent_user_config["max_turns"] = user_config["max_turns"]
+                    user_config["agent"] = agent_user_config
+                    user_config.pop("max_turns", None)
+
+                config = _deep_merge(config, user_config)
+            except Exception as e:
+                print(f"Warning: Failed to load config: {e}")
+
+        normalized = _normalize_root_model_keys(_normalize_max_turns_config(config))
+        expanded = _expand_env_vars(normalized)
+        _LAST_EXPANDED_CONFIG_BY_PATH[path_key] = copy.deepcopy(expanded)
+        if cache_key is not None:
+            _LOAD_CONFIG_CACHE[path_key] = (cache_key[0], cache_key[1], copy.deepcopy(expanded))
+        else:
+            _LOAD_CONFIG_CACHE.pop(path_key, None)
+        return expanded


 _SECURITY_COMMENT = """
 # ── Security ──────────────────────────────────────────────────────────
-# Secret redaction is OFF by default — tool output (terminal stdout,
-# read_file results, web content) passes through unmodified. Set
-# redact_secrets to true to mask strings that look like API keys, tokens,
-# and passwords before they enter the model context and logs.
+# Secret redaction is ON by default — strings that look like API keys,
+# tokens, and passwords are masked in tool output, logs, and chat
+# responses before the model or user ever sees them. Set redact_secrets
+# to false to disable (e.g. when developing the redactor itself).
 # tirith pre-exec scanning is enabled by default when the tirith binary
 # is available. Configure via security.tirith_* keys or env vars
 # (TIRITH_ENABLED, TIRITH_BIN, TIRITH_TIMEOUT, TIRITH_FAIL_OPEN).
@@ -4017,8 +4073,8 @@ _FALLBACK_COMMENT = """

 _COMMENTED_SECTIONS = """
 # ── Security ──────────────────────────────────────────────────────────
-# Secret redaction is OFF by default. Set to true to mask strings that
-# look like API keys, tokens, and passwords in tool output and logs.
+# Secret redaction is ON by default. Set to false to pass tool output,
+# logs, and chat responses through unmodified (e.g. for redactor dev).
 #
 # security:
 #   redact_secrets: true
@@ -4049,45 +4105,46 @@ _COMMENTED_SECTIONS = """

 def save_config(config: Dict[str, Any]):
    """Save configuration to ~/.hermes/config.yaml."""
-    if is_managed():
-        managed_error("save configuration")
-        return
-    from utils import atomic_yaml_write
+    with _CONFIG_LOCK:
+        if is_managed():
+            managed_error("save configuration")
+            return
+        from utils import atomic_yaml_write

-    ensure_hermes_home()
-    config_path = get_config_path()
-    current_normalized = _normalize_root_model_keys(_normalize_max_turns_config(config))
-    normalized = current_normalized
-    raw_existing = _normalize_root_model_keys(_normalize_max_turns_config(read_raw_config()))
-    if raw_existing:
-        normalized = _preserve_env_ref_templates(
+        ensure_hermes_home()
+        config_path = get_config_path()
+        current_normalized = _normalize_root_model_keys(_normalize_max_turns_config(config))
+        normalized = current_normalized
+        raw_existing = _normalize_root_model_keys(_normalize_max_turns_config(read_raw_config()))
+        if raw_existing:
+            normalized = _preserve_env_ref_templates(
+                normalized,
+                raw_existing,
+                _LAST_EXPANDED_CONFIG_BY_PATH.get(str(config_path)),
+            )
+
+        # Build optional commented-out sections for features that are off by
+        # default or only relevant when explicitly configured.
+        parts = []
+        sec = normalized.get("security", {})
+        if not sec or sec.get("redact_secrets") is None:
+            parts.append(_SECURITY_COMMENT)
+        fb = normalized.get("fallback_model", {})
+        fb_is_valid = False
+        if isinstance(fb, list):
+            fb_is_valid = any(isinstance(e, dict) and e.get("provider") and e.get("model") for e in fb)
+        elif isinstance(fb, dict):
+            fb_is_valid = bool(fb.get("provider") and fb.get("model"))
+        if not fb_is_valid:
+            parts.append(_FALLBACK_COMMENT)
+
+        atomic_yaml_write(
+            config_path,
            normalized,
-            raw_existing,
-            _LAST_EXPANDED_CONFIG_BY_PATH.get(str(config_path)),
+            extra_content="".join(parts) if parts else None,
        )
-
-    # Build optional commented-out sections for features that are off by
-    # default or only relevant when explicitly configured.
-    parts = []
-    sec = normalized.get("security", {})
-    if not sec or sec.get("redact_secrets") is None:
-        parts.append(_SECURITY_COMMENT)
-    fb = normalized.get("fallback_model", {})
-    fb_is_valid = False
-    if isinstance(fb, list):
-        fb_is_valid = any(isinstance(e, dict) and e.get("provider") and e.get("model") for e in fb)
-    elif isinstance(fb, dict):
-        fb_is_valid = bool(fb.get("provider") and fb.get("model"))
-    if not fb_is_valid:
-        parts.append(_FALLBACK_COMMENT)
-
-    atomic_yaml_write(
-        config_path,
-        normalized,
-        extra_content="".join(parts) if parts else None,
-    )
-    _secure_file(config_path)
-    _LAST_EXPANDED_CONFIG_BY_PATH[str(config_path)] = copy.deepcopy(current_normalized)
+        _secure_file(config_path)
+        _LAST_EXPANDED_CONFIG_BY_PATH[str(config_path)] = copy.deepcopy(current_normalized)


 def load_env() -> Dict[str, str]:
@@ -4937,3 +4994,100 @@ def _inject_profile_env_vars() -> None:

 # Eagerly inject so that OPTIONAL_ENV_VARS is fully populated at import time.
 _inject_profile_env_vars()
+
+
+# ── Platform-plugin env var injection ────────────────────────────────────────
+# Bundled platform plugins under ``plugins/platforms/*/plugin.yaml`` declare
+# their required env vars via ``requires_env``.  This mirror of
+# ``_inject_profile_env_vars`` surfaces them in ``hermes config`` UI so users
+# can configure Teams / IRC / Google Chat without the core repo ever needing
+# to know they exist.
+#
+# Each ``requires_env`` entry may be a bare string (name only) or a dict:
+#
+#   requires_env:
+#     - TEAMS_CLIENT_ID                          # minimal
+#     - name: TEAMS_CLIENT_SECRET                # rich
+#       description: "Teams bot client secret"
+#       url: "https://portal.azure.com/"
+#       password: true
+#       prompt: "Teams client secret"
+#
+# An optional ``optional_env`` block surfaces non-required vars the same way
+# (e.g. allowlist, home channel).
+
+_platform_plugin_env_vars_injected = False
+
+
+def _inject_platform_plugin_env_vars() -> None:
+    """Populate OPTIONAL_ENV_VARS from bundled platform plugin manifests.
+
+    Called once at module load time. Idempotent — repeated calls are no-ops.
+    Failures are swallowed so a malformed plugin.yaml can't break CLI import.
+    """
+    global _platform_plugin_env_vars_injected
+    if _platform_plugin_env_vars_injected:
+        return
+    _platform_plugin_env_vars_injected = True
+    try:
+        import yaml  # type: ignore
+
+        # Resolve the bundled plugins dir from this file's location so the
+        # injector works regardless of CWD.
+        repo_root = Path(__file__).resolve().parents[1]
+        platforms_dir = repo_root / "plugins" / "platforms"
+        if not platforms_dir.is_dir():
+            return
+        for child in platforms_dir.iterdir():
+            if not child.is_dir():
+                continue
+            manifest_path = child / "plugin.yaml"
+            if not manifest_path.exists():
+                manifest_path = child / "plugin.yml"
+            if not manifest_path.exists():
+                continue
+            try:
+                with open(manifest_path, "r", encoding="utf-8") as f:
+                    manifest = yaml.safe_load(f) or {}
+            except Exception:
+                continue
+            label = manifest.get("label") or manifest.get("name") or child.name
+            # Merge required + optional env var declarations.
+            entries = list(manifest.get("requires_env") or [])
+            entries.extend(manifest.get("optional_env") or [])
+            for entry in entries:
+                if isinstance(entry, str):
+                    name = entry
+                    meta: dict = {}
+                elif isinstance(entry, dict) and entry.get("name"):
+                    name = entry["name"]
+                    meta = entry
+                else:
+                    continue
+                if name in OPTIONAL_ENV_VARS:
+                    continue  # hardcoded entry wins (back-compat)
+                # Heuristic: anything named *TOKEN, *SECRET, *KEY, *PASSWORD
+                # is a password field unless explicitly overridden.
+                name_upper = name.upper()
+                is_secret = bool(meta.get("password") or meta.get("secret"))
+                if not is_secret and not meta.get("password") is False:
+                    is_secret = any(
+                        name_upper.endswith(suf)
+                        for suf in ("_TOKEN", "_SECRET", "_KEY", "_PASSWORD", "_JSON")
+                    )
+                OPTIONAL_ENV_VARS[name] = {
+                    "description": (
+                        meta.get("description")
+                        or f"{label} configuration"
+                    ),
+                    "prompt": meta.get("prompt") or name,
+                    "url": meta.get("url") or None,
+                    "password": is_secret,
+                    "category": meta.get("category") or "messaging",
+                }
+    except Exception:
+        pass
+
+
+# Eagerly inject so that platform plugin env vars show up in the setup wizard.
+_inject_platform_plugin_env_vars()
@@ -212,9 +212,9 @@ def copilot_device_code_login(
    print("  Waiting for authorization...", end="", flush=True)

    # Step 3: Poll for completion
-    deadline = time.time() + timeout_seconds
+    deadline = time.monotonic() + timeout_seconds

-    while time.time() < deadline:
+    while time.monotonic() < deadline:
        time.sleep(interval + _DEVICE_CODE_POLL_SAFETY_MARGIN)

        poll_data = urllib.parse.urlencode({
@@ -12,6 +12,7 @@ from __future__ import annotations
 import argparse
 import sys
 from datetime import datetime, timezone
+from pathlib import Path
 from typing import Optional


@@ -57,7 +58,8 @@ def _cmd_status(args) -> int:
    print(f"  last summary:   {summary}")
    _report = state.get("last_report_path")
    if _report:
-        print(f"  last report:    {_report}")
+        suffix = "" if Path(_report).exists() else " (missing)"
+        print(f"  last report:    {_report}{suffix}")
    _ih = curator.get_interval_hours()
    _interval_label = (
        f"{_ih // 24}d" if _ih % 24 == 0 and _ih >= 24
@@ -161,6 +163,8 @@ def _cmd_run(args) -> int:
        return 1

    dry = bool(getattr(args, "dry_run", False))
+    background = bool(getattr(args, "background", False))
+    synchronous = bool(getattr(args, "synchronous", False)) or not background
    if dry:
        print("curator: running DRY-RUN (report only, no mutations)...")
    else:
@@ -171,7 +175,7 @@ def _cmd_run(args) -> int:

    result = curator.run_curator_review(
        on_summary=_on_summary,
-        synchronous=bool(args.synchronous),
+        synchronous=synchronous,
        dry_run=dry,
    )
    auto = result.get("auto_transitions", {})
@@ -188,13 +192,19 @@ def _cmd_run(args) -> int:
                f"archived={auto.get('archived', 0)} "
                f"reactivated={auto.get('reactivated', 0)}"
            )
-    if not args.synchronous:
+    if not synchronous:
        print("llm pass running in background — check `hermes curator status` later")
    if dry:
-        print(
-            "dry-run: no changes applied. When the report lands, read it with "
-            "`hermes curator status` and run `hermes curator run` (no flag) to apply."
-        )
+        if synchronous:
+            print(
+                "dry-run: no changes applied. Read the report with "
+                "`hermes curator status` and run `hermes curator run` (no flag) to apply."
+            )
+        else:
+            print(
+                "dry-run: no changes applied. When the report lands, read it with "
+                "`hermes curator status` and run `hermes curator run` (no flag) to apply."
+            )
    return 0


@@ -442,6 +452,18 @@ def _cmd_rollback(args) -> int:
    return 1


+def _cmd_list_archived(args) -> int:
+    """List archived (recoverable) skills."""
+    from tools import skill_usage
+    names = skill_usage.list_archived_skill_names()
+    if not names:
+        print("curator: no archived skills")
+        return 0
+    for name in names:
+        print(name)
+    return 0
+
+
 # ---------------------------------------------------------------------------
 # argparse wiring (called from hermes_cli.main)
 # ---------------------------------------------------------------------------
@@ -461,7 +483,11 @@ def register_cli(parent: argparse.ArgumentParser) -> None:
    p_run = subs.add_parser("run", help="Trigger a curator review now")
    p_run.add_argument(
        "--sync", "--synchronous", dest="synchronous", action="store_true",
-        help="Wait for the LLM review pass to finish (default: background thread)",
+        help="Wait for the LLM review pass to finish (default for manual runs)",
+    )
+    p_run.add_argument(
+        "--background", dest="background", action="store_true",
+        help="Start the LLM review pass in a background thread and return immediately",
    )
    p_run.add_argument(
        "--dry-run", dest="dry_run", action="store_true",
@@ -488,6 +514,9 @@ def register_cli(parent: argparse.ArgumentParser) -> None:
    p_restore.add_argument("skill", help="Skill name")
    p_restore.set_defaults(func=_cmd_restore)

+    subs.add_parser("list-archived", help="List archived skills") \
+        .set_defaults(func=_cmd_list_archived)
+
    p_archive = subs.add_parser(
        "archive",
        help="Manually archive a skill (move to .archive/, excluded from prompt)",
@@ -91,6 +91,15 @@ def _termux_browser_setup_steps(node_installed: bool) -> list[str]:
    return steps


+def _termux_install_all_fallback_notes() -> list[str]:
+    return [
+        "Termux install profile: use .[termux-all] for broad compatibility (installer default on Termux).",
+        "Matrix E2EE extra is excluded on Termux (python-olm currently fails to build).",
+        "Local faster-whisper extra is excluded on Termux (ctranslate2/av build path unavailable).",
+        "STT fallback: use Groq Whisper (set GROQ_API_KEY) or OpenAI Whisper (set VOICE_TOOLS_OPENAI_KEY).",
+    ]
+
+
 def _has_provider_env_config(content: str) -> bool:
    """Return True when ~/.hermes/.env contains provider auth/base URL settings."""
    return any(key in content for key in _PROVIDER_ENV_HINTS)
@@ -1084,6 +1093,11 @@ def run_doctor(args):
            except Exception:
                pass

+    if _is_termux():
+        check_info("Termux compatibility fallbacks:")
+        for note in _termux_install_all_fallback_notes():
+            check_info(note)
+
    # =========================================================================
    # Check: API connectivity
    # =========================================================================
@@ -1225,6 +1239,16 @@ def run_doctor(args):
                    headers=_headers,
                    timeout=10,
                )
+                if (
+                    _pname == "Alibaba/DashScope"
+                    and not _base
+                    and _resp.status_code == 401
+                ):
+                    _resp = httpx.get(
+                        "https://dashscope.aliyuncs.com/compatible-mode/v1/models",
+                        headers=_headers,
+                        timeout=10,
+                    )
                if _resp.status_code == 200:
                    print(f"\r  {color('✓', Colors.GREEN)} {_label}                          ")
                elif _resp.status_code == 401:
@@ -585,10 +585,10 @@ def _wait_for_systemd_service_restart(

    svc = get_service_name()
    scope_label = _service_scope_label(system).capitalize()
-    deadline = time.time() + timeout
+    deadline = time.monotonic() + timeout
    printed_runtime_wait = False

-    while time.time() < deadline:
+    while time.monotonic() < deadline:
        props = _read_systemd_unit_properties(system=system)
        active_state = props.get("ActiveState", "")
        sub_state = props.get("SubState", "")
@@ -830,6 +830,46 @@ def _print_other_profiles_gateway_status() -> None:
        pass


+def _gateway_list() -> None:
+    """List all profiles and their gateway running status.
+
+    Provides a single-command overview of every known profile and whether
+    its gateway is currently running, so multi-profile users don't have to
+    check each profile individually.
+    """
+    try:
+        from hermes_cli.profiles import list_profiles, get_active_profile_name
+    except Exception:
+        print("Unable to list profiles.")
+        return
+
+    profiles = list_profiles()
+    if not profiles:
+        print("No profiles found.")
+        return
+
+    current = get_active_profile_name()
+
+    print("Gateways:")
+    for prof in profiles:
+        marker = "✓" if prof.gateway_running else "✗"
+        label = prof.name
+        if prof.name == current:
+            label += " (current)"
+        parts = [f"  {marker} {label:<24s}"]
+        if prof.gateway_running:
+            try:
+                from gateway.status import get_running_pid
+                pid = get_running_pid(prof.path / "gateway.pid", cleanup_stale=False)
+                if pid:
+                    parts.append(f"PID {pid}")
+            except Exception:
+                pass
+        else:
+            parts.append("not running")
+        print(" — ".join(parts))
+
+
 def kill_gateway_processes(force: bool = False, exclude_pids: set | None = None,
                           all_profiles: bool = False) -> int:
    """Kill any running gateway processes. Returns count killed.
@@ -2730,6 +2770,42 @@ def launchd_status(deep: bool = False):
 # Gateway Runner
 # =============================================================================

+def _truthy_env(value: str | None) -> bool:
+    return str(value or "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _is_official_docker_checkout() -> bool:
+    return (
+        str(PROJECT_ROOT) == "/opt/hermes"
+        and (PROJECT_ROOT / "docker" / "entrypoint.sh").is_file()
+    )
+
+
+def _guard_official_docker_root_gateway() -> None:
+    """Refuse gateway startup when the official Docker privilege drop was bypassed."""
+    if not hasattr(os, "geteuid") or os.geteuid() != 0:
+        return
+    if _truthy_env(os.getenv("HERMES_ALLOW_ROOT_GATEWAY")):
+        return
+    if not _is_official_docker_checkout():
+        return
+
+    print_error(
+        "Refusing to run the Hermes gateway as root inside the official Docker image."
+    )
+    print(
+        "  The image entrypoint normally drops privileges to the 'hermes' user. "
+        "If you override entrypoint in Docker Compose, include "
+        "/opt/hermes/docker/entrypoint.sh before the Hermes command."
+    )
+    print(
+        "  Running the gateway as root can leave root-owned files in "
+        "$HERMES_HOME and break later non-root dashboard/gateway runs."
+    )
+    print("  Set HERMES_ALLOW_ROOT_GATEWAY=1 only if you intentionally accept this risk.")
+    sys.exit(1)
+
+
 def run_gateway(verbose: int = 0, quiet: bool = False, replace: bool = False):
    """Run the gateway in foreground.
    
@@ -2740,6 +2816,7 @@ def run_gateway(verbose: int = 0, quiet: bool = False, replace: bool = False):
                 This prevents systemd restart loops when the old process
                 hasn't fully exited yet.
    """
+    _guard_official_docker_root_gateway()
    sys.path.insert(0, str(PROJECT_ROOT))

    # Refresh the systemd unit definition on every boot so that restart
@@ -4798,6 +4875,9 @@ def _gateway_command_inner(args):
        # Show other profiles' gateway status for multi-profile awareness
        _print_other_profiles_gateway_status()

+    elif subcmd == "list":
+        _gateway_list()
+
    elif subcmd == "migrate-legacy":
        # Stop, disable, and remove legacy Hermes gateway unit files from
        # pre-rename installs (e.g. hermes.service). Profile units and
@@ -47,6 +47,14 @@ DEFAULT_MAX_TURNS = 20
 DEFAULT_JUDGE_TIMEOUT = 30.0
 # Cap how much of the last response + recent messages we send to the judge.
 _JUDGE_RESPONSE_SNIPPET_CHARS = 4000
+# After this many consecutive judge *parse* failures (empty output / non-JSON),
+# the loop auto-pauses and points the user at the goal_judge config. API /
+# transport errors do NOT count toward this — those are transient. This guards
+# against small models (e.g. deepseek-v4-flash) that cannot follow the strict
+# JSON reply contract; without it the loop runs until the turn budget is
+# exhausted with every reply shaped like `judge returned empty response` or
+# `judge reply was not JSON`.
+DEFAULT_MAX_CONSECUTIVE_PARSE_FAILURES = 3


 CONTINUATION_PROMPT_TEMPLATE = (
@@ -99,6 +107,7 @@ class GoalState:
    last_verdict: Optional[str] = None        # "done" | "continue" | "skipped"
    last_reason: Optional[str] = None
    paused_reason: Optional[str] = None       # why we auto-paused (budget, etc.)
+    consecutive_parse_failures: int = 0       # judge-output parse failures in a row

    def to_json(self) -> str:
        return json.dumps(asdict(self), ensure_ascii=False)
@@ -116,6 +125,7 @@ class GoalState:
            last_verdict=data.get("last_verdict"),
            last_reason=data.get("last_reason"),
            paused_reason=data.get("paused_reason"),
+            consecutive_parse_failures=int(data.get("consecutive_parse_failures", 0) or 0),
        )


@@ -220,13 +230,17 @@ def _truncate(text: str, limit: int) -> str:
 _JSON_OBJECT_RE = re.compile(r"\{.*?\}", re.DOTALL)


-def _parse_judge_response(raw: str) -> Tuple[bool, str]:
-    """Parse the judge's reply. Fail-open to ``(False, "<reason>")``.
+def _parse_judge_response(raw: str) -> Tuple[bool, str, bool]:
+    """Parse the judge's reply. Fail-open to ``(False, "<reason>", parse_failed)``.

-    Returns ``(done, reason)``.
+    Returns ``(done, reason, parse_failed)``. ``parse_failed`` is True when the
+    judge returned output that couldn't be interpreted as the expected JSON
+    verdict (empty body, prose, malformed JSON). Callers use that flag to
+    auto-pause after N consecutive parse failures so a weak judge model
+    doesn't silently burn the turn budget.
    """
    if not raw:
-        return False, "judge returned empty response"
+        return False, "judge returned empty response", True

    text = raw.strip()

@@ -252,7 +266,7 @@ def _parse_judge_response(raw: str) -> Tuple[bool, str]:
                data = None

    if not isinstance(data, dict):
-        return False, f"judge reply was not JSON: {_truncate(raw, 200)!r}"
+        return False, f"judge reply was not JSON: {_truncate(raw, 200)!r}", True

    done_val = data.get("done")
    if isinstance(done_val, str):
@@ -262,7 +276,7 @@ def _parse_judge_response(raw: str) -> Tuple[bool, str]:
    reason = str(data.get("reason") or "").strip()
    if not reason:
        reason = "no reason provided"
-    return done, reason
+    return done, reason, False


 def judge_goal(
@@ -270,36 +284,42 @@ def judge_goal(
    last_response: str,
    *,
    timeout: float = DEFAULT_JUDGE_TIMEOUT,
-) -> Tuple[str, str]:
+) -> Tuple[str, str, bool]:
    """Ask the auxiliary model whether the goal is satisfied.

-    Returns ``(verdict, reason)`` where verdict is ``"done"``, ``"continue"``,
-    or ``"skipped"`` (when the judge couldn't be reached).
+    Returns ``(verdict, reason, parse_failed)`` where verdict is ``"done"``,
+    ``"continue"``, or ``"skipped"`` (when the judge couldn't be reached).

-    This is deliberately fail-open: any error returns ``("continue", "...")``
-    so a broken judge doesn't wedge progress — the turn budget is the
-    backstop.
+    ``parse_failed`` is True only when the judge call succeeded but its output
+    was unusable (empty or non-JSON). API/transport errors return False — they
+    are transient and should fail-open silently. Callers use this flag to
+    auto-pause after N consecutive parse failures (see
+    ``DEFAULT_MAX_CONSECUTIVE_PARSE_FAILURES``).
+
+    This is deliberately fail-open: any error returns ``("continue", "...", False)``
+    so a broken judge doesn't wedge progress — the turn budget and the
+    consecutive-parse-failures auto-pause are the backstops.
    """
    if not goal.strip():
-        return "skipped", "empty goal"
+        return "skipped", "empty goal", False
    if not last_response.strip():
        # No substantive reply this turn — almost certainly not done yet.
-        return "continue", "empty response (nothing to evaluate)"
+        return "continue", "empty response (nothing to evaluate)", False

    try:
        from agent.auxiliary_client import get_text_auxiliary_client
    except Exception as exc:
        logger.debug("goal judge: auxiliary client import failed: %s", exc)
-        return "continue", "auxiliary client unavailable"
+        return "continue", "auxiliary client unavailable", False

    try:
        client, model = get_text_auxiliary_client("goal_judge")
    except Exception as exc:
        logger.debug("goal judge: get_text_auxiliary_client failed: %s", exc)
-        return "continue", "auxiliary client unavailable"
+        return "continue", "auxiliary client unavailable", False

    if client is None or not model:
-        return "continue", "no auxiliary client configured"
+        return "continue", "no auxiliary client configured", False

    prompt = JUDGE_USER_PROMPT_TEMPLATE.format(
        goal=_truncate(goal, 2000),
@@ -319,17 +339,17 @@ def judge_goal(
        )
    except Exception as exc:
        logger.info("goal judge: API call failed (%s) — falling through to continue", exc)
-        return "continue", f"judge error: {type(exc).__name__}"
+        return "continue", f"judge error: {type(exc).__name__}", False

    try:
        raw = resp.choices[0].message.content or ""
    except Exception:
        raw = ""

-    done, reason = _parse_judge_response(raw)
+    done, reason, parse_failed = _parse_judge_response(raw)
    verdict = "done" if done else "continue"
    logger.info("goal judge: verdict=%s reason=%s", verdict, _truncate(reason, 120))
-    return verdict, reason
+    return verdict, reason, parse_failed


 # ──────────────────────────────────────────────────────────────────────
@@ -473,10 +493,18 @@ class GoalManager:
        state.turns_used += 1
        state.last_turn_at = time.time()

-        verdict, reason = judge_goal(state.goal, last_response)
+        verdict, reason, parse_failed = judge_goal(state.goal, last_response)
        state.last_verdict = verdict
        state.last_reason = reason

+        # Track consecutive judge parse failures. Reset on any usable reply,
+        # including API / transport errors (parse_failed=False) so a flaky
+        # network doesn't trip the auto-pause meant for bad judge models.
+        if parse_failed:
+            state.consecutive_parse_failures += 1
+        else:
+            state.consecutive_parse_failures = 0
+
        if verdict == "done":
            state.status = "done"
            save_goal(self.session_id, state)
@@ -489,6 +517,36 @@ class GoalManager:
                "message": f"✓ Goal achieved: {reason}",
            }

+        # Auto-pause when the judge model can't produce the expected JSON
+        # verdict N turns in a row. Points the user at the goal_judge config
+        # so they can route this side task to a model that follows the
+        # contract (e.g. google/gemini-3-flash-preview). Without this guard,
+        # weak judge models burn the entire turn budget returning prose or
+        # empty strings.
+        if state.consecutive_parse_failures >= DEFAULT_MAX_CONSECUTIVE_PARSE_FAILURES:
+            state.status = "paused"
+            state.paused_reason = (
+                f"judge model returned unparseable output {state.consecutive_parse_failures} turns in a row"
+            )
+            save_goal(self.session_id, state)
+            return {
+                "status": "paused",
+                "should_continue": False,
+                "continuation_prompt": None,
+                "verdict": "continue",
+                "reason": reason,
+                "message": (
+                    f"⏸ Goal paused — the judge model ({state.consecutive_parse_failures} turns) "
+                    "isn't returning the required JSON verdict. Route the judge to a stricter "
+                    "model in ~/.hermes/config.yaml:\n"
+                    "  auxiliary:\n"
+                    "    goal_judge:\n"
+                    "      provider: openrouter\n"
+                    "      model: google/gemini-3-flash-preview\n"
+                    "Then /goal resume to continue."
+                ),
+            }
+
        if state.turns_used >= state.max_turns:
            state.status = "paused"
            state.paused_reason = f"turn budget exhausted ({state.turns_used}/{state.max_turns})"
@@ -70,6 +70,7 @@ def _task_to_dict(t: kb.Task) -> dict[str, Any]:
        "completed_at": t.completed_at,
        "result": t.result,
        "skills": list(t.skills) if t.skills else [],
+        "max_retries": t.max_retries,
    }


@@ -284,6 +285,15 @@ def build_parser(parent_subparsers: argparse._SubParsersAction) -> argparse.Argu
                               "(repeatable). Appended to the built-in "
                               "kanban-worker skill. Example: "
                               "--skill translation --skill github-code-review")
+    p_create.add_argument("--max-retries", type=int, default=None,
+                          metavar="N",
+                          help="Per-task override for the consecutive-failure "
+                               "circuit breaker. Trip on the Nth failure — "
+                               "e.g. --max-retries 1 blocks on the first "
+                               "failure (no retries), --max-retries 3 allows "
+                               "two retries. Omit to use the dispatcher's "
+                               "kanban.failure_limit config "
+                               f"(default {kb.DEFAULT_FAILURE_LIMIT}).")
    p_create.add_argument("--json", action="store_true", help="Emit JSON output")

    # --- list ---
@@ -443,8 +453,8 @@ def build_parser(parent_subparsers: argparse._SubParsersAction) -> argparse.Argu
                        help="Cap number of spawns this pass")
    p_disp.add_argument("--failure-limit", type=int,
                        default=kb.DEFAULT_SPAWN_FAILURE_LIMIT,
-                        help=f"Auto-block a task after this many consecutive spawn failures "
-                             f"(default: {kb.DEFAULT_SPAWN_FAILURE_LIMIT})")
+                        help=f"Auto-block a task after this many consecutive non-success attempts "
+                             f"(spawn_failed, timed_out, or crashed; default: {kb.DEFAULT_SPAWN_FAILURE_LIMIT})")
    p_disp.add_argument("--json", action="store_true")

    # --- daemon (deprecated) ---
@@ -560,6 +570,42 @@ def build_parser(parent_subparsers: argparse._SubParsersAction) -> argparse.Argu
    )
    p_ctx.add_argument("task_id")

+    # --- specify --- (triage → todo via auxiliary LLM)
+    p_specify = sub.add_parser(
+        "specify",
+        help="Flesh out a triage-column task into a concrete spec "
+             "(title + body) and promote it to todo. Uses the auxiliary "
+             "LLM configured under auxiliary.triage_specifier.",
+    )
+    p_specify.add_argument(
+        "task_id",
+        nargs="?",
+        default=None,
+        help="Task id to specify (required unless --all is given)",
+    )
+    p_specify.add_argument(
+        "--all",
+        dest="all_triage",
+        action="store_true",
+        help="Specify every task currently in the triage column",
+    )
+    p_specify.add_argument(
+        "--tenant",
+        default=None,
+        help="When used with --all, restrict the sweep to this tenant",
+    )
+    p_specify.add_argument(
+        "--author",
+        default=None,
+        help="Author name recorded on the audit comment "
+             "(default: $HERMES_PROFILE or 'specifier')",
+    )
+    p_specify.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit one JSON object per task on stdout",
+    )
+
    # --- gc ---
    p_gc = sub.add_parser(
        "gc", help="Garbage-collect archived-task workspaces, old events, and old logs",
@@ -674,6 +720,7 @@ def kanban_command(args: argparse.Namespace) -> int:
        "notify-list":        _cmd_notify_list,
        "notify-unsubscribe": _cmd_notify_unsubscribe,
        "context":  _cmd_context,
+        "specify":  _cmd_specify,
        "gc":       _cmd_gc,
    }
    handler = handlers.get(action)
@@ -982,6 +1029,14 @@ def _cmd_create(args: argparse.Namespace) -> int:
    except ValueError as exc:
        print(f"kanban: --max-runtime: {exc}", file=sys.stderr)
        return 2
+    max_retries = getattr(args, "max_retries", None)
+    if max_retries is not None and max_retries < 1:
+        print(
+            f"kanban: --max-retries must be >= 1 (got {max_retries}); "
+            "use 1 to trip on the first failure.",
+            file=sys.stderr,
+        )
+        return 2
    with kb.connect() as conn:
        task_id = kb.create_task(
            conn,
@@ -998,6 +1053,7 @@ def _cmd_create(args: argparse.Namespace) -> int:
            idempotency_key=getattr(args, "idempotency_key", None),
            max_runtime_seconds=max_runtime,
            skills=getattr(args, "skills", None) or None,
+            max_retries=max_retries,
        )
        task = kb.get_task(conn, task_id)
    if getattr(args, "json", False):
@@ -1125,6 +1181,23 @@ def _cmd_show(args: argparse.Namespace) -> int:
          (f" @ {task.workspace_path}" if task.workspace_path else ""))
    if task.skills:
        print(f"  skills:    {', '.join(task.skills)}")
+    # Effective retry threshold. Show the per-task override if set,
+    # otherwise the dispatcher's resolved value from config (or the
+    # default if config doesn't set it either). Helps operators see
+    # why a task auto-blocked earlier/later than they expected.
+    if task.max_retries is not None:
+        print(f"  max-retries: {task.max_retries} (task)")
+    else:
+        try:
+            from hermes_cli.config import load_config
+            cfg = load_config()
+            cfg_val = (cfg.get("kanban", {}) or {}).get("failure_limit")
+        except Exception:
+            cfg_val = None
+        if cfg_val is not None and int(cfg_val) != kb.DEFAULT_FAILURE_LIMIT:
+            print(f"  max-retries: {int(cfg_val)} (config kanban.failure_limit)")
+        else:
+            print(f"  max-retries: {kb.DEFAULT_FAILURE_LIMIT} (default)")
    print(f"  created:   {_fmt_ts(task.created_at)} by {task.created_by or '-'}")

    # Diagnostics section — surface active distress signals at the top
@@ -1657,6 +1730,7 @@ def _cmd_daemon(args: argparse.Namespace) -> int:
            "    kanban:\n"
            "      dispatch_in_gateway: true      # default\n"
            "      dispatch_interval_seconds: 60\n"
+            "      failure_limit: 2              # consecutive non-success attempts before auto-block\n"
            "\n"
            "Running both the gateway AND this standalone daemon will\n"
            "race for claims. If you truly need the old standalone\n"
@@ -1943,6 +2017,80 @@ def _cmd_context(args: argparse.Namespace) -> int:
    return 0


+def _cmd_specify(args: argparse.Namespace) -> int:
+    """Flesh out a triage task (or all of them) via auxiliary LLM,
+    then promote to todo. Thin wrapper over ``kanban_specify``."""
+    from hermes_cli import kanban_specify as spec
+
+    all_flag = bool(getattr(args, "all_triage", False))
+    tenant = getattr(args, "tenant", None)
+    author = getattr(args, "author", None) or _profile_author()
+    want_json = bool(getattr(args, "json", False))
+
+    if args.task_id and all_flag:
+        print(
+            "kanban: pass either a task id OR --all, not both",
+            file=sys.stderr,
+        )
+        return 2
+
+    if all_flag:
+        ids = spec.list_triage_ids(tenant=tenant)
+        if not ids:
+            msg = (
+                "No triage tasks"
+                + (f" for tenant {tenant!r}" if tenant else "")
+                + "."
+            )
+            if want_json:
+                print(json.dumps({"specified": 0, "total": 0}))
+            else:
+                print(msg)
+            return 0
+    elif args.task_id:
+        ids = [args.task_id]
+    else:
+        print(
+            "kanban: specify requires a task id or --all",
+            file=sys.stderr,
+        )
+        return 2
+
+    ok_count = 0
+    fail_count = 0
+    for tid in ids:
+        outcome = spec.specify_task(tid, author=author)
+        if outcome.ok:
+            ok_count += 1
+        else:
+            fail_count += 1
+        if want_json:
+            print(json.dumps({
+                "task_id": outcome.task_id,
+                "ok": outcome.ok,
+                "reason": outcome.reason,
+                "new_title": outcome.new_title,
+            }))
+        else:
+            if outcome.ok:
+                title_suffix = (
+                    f" — retitled: {outcome.new_title!r}"
+                    if outcome.new_title
+                    else ""
+                )
+                print(f"Specified {outcome.task_id} → todo{title_suffix}")
+            else:
+                print(
+                    f"kanban: specify {outcome.task_id}: {outcome.reason}",
+                    file=sys.stderr,
+                )
+    if not all_flag:
+        return 0 if ok_count == 1 else 1
+    # --all: succeed if at least one promotion landed; exit 1 only when
+    # every candidate failed (honest signal for scripts).
+    return 0 if (ok_count > 0 or not ids) else 1
+
+
 def _cmd_gc(args: argparse.Namespace) -> int:
    """Remove scratch workspaces of archived tasks, prune old events, and
    delete old worker logs."""
@@ -595,6 +595,14 @@ class Task:
    # JSON array of skill names. None = use only the defaults; empty
    # list = explicitly no extra skills.
    skills: Optional[list] = None
+    # Per-task override for the consecutive-failure circuit breaker.
+    # The value is the failure count at which the breaker trips — e.g.
+    # ``max_retries=1`` blocks on the first failure (zero retries),
+    # ``max_retries=3`` blocks on the third (two retries allowed).
+    # ``None`` (the common case) falls through to the dispatcher-level
+    # ``kanban.failure_limit`` config, and then to ``DEFAULT_FAILURE_LIMIT``.
+    # Name matches the ``--max-retries`` CLI flag on ``kanban create``.
+    max_retries: Optional[int] = None

    @classmethod
    def from_row(cls, row: sqlite3.Row) -> "Task":
@@ -656,6 +664,9 @@ class Task:
                row["current_step_key"] if "current_step_key" in keys else None
            ),
            skills=skills_value,
+            max_retries=(
+                row["max_retries"] if "max_retries" in keys else None
+            ),
        )


@@ -776,7 +787,13 @@ CREATE TABLE IF NOT EXISTS tasks (
    -- Force-loaded skills for the worker on this task, stored as JSON.
    -- Appended to the dispatcher's built-in `--skills kanban-worker`.
    -- NULL or empty array = no extras.
-    skills               TEXT
+    skills               TEXT,
+    -- Per-task override for the consecutive-failure circuit breaker.
+    -- The value is the failure count at which the breaker trips — e.g.
+    -- ``max_retries=1`` blocks on the first failure. NULL (the common
+    -- case) falls through to the dispatcher-level ``kanban.failure_limit``
+    -- config and then ``DEFAULT_FAILURE_LIMIT``.
+    max_retries          INTEGER
 );

 CREATE TABLE IF NOT EXISTS task_links (
@@ -1008,6 +1025,14 @@ def _migrate_add_optional_columns(conn: sqlite3.Connection) -> None:
        # for existing rows.
        conn.execute("ALTER TABLE tasks ADD COLUMN skills TEXT")

+    if "max_retries" not in cols:
+        # Per-task override for the consecutive-failure circuit breaker.
+        # NULL = fall through to the dispatcher-level ``kanban.failure_limit``
+        # config, then ``DEFAULT_FAILURE_LIMIT``. Existing rows get NULL,
+        # which is the correct default (they keep the global behaviour
+        # they were getting before the column existed).
+        conn.execute("ALTER TABLE tasks ADD COLUMN max_retries INTEGER")
+
    # task_events gained a run_id column; back-fill it as NULL for
    # historical events (they predate runs and can't be attributed).
    ev_cols = {row["name"] for row in conn.execute("PRAGMA table_info(task_events)")}
@@ -1163,6 +1188,7 @@ def create_task(
    idempotency_key: Optional[str] = None,
    max_runtime_seconds: Optional[int] = None,
    skills: Optional[Iterable[str]] = None,
+    max_retries: Optional[int] = None,
 ) -> str:
    """Create a new task and optionally link it under parent tasks.

@@ -1276,8 +1302,9 @@ def create_task(
                    INSERT INTO tasks (
                        id, title, body, assignee, status, priority,
                        created_by, created_at, workspace_kind, workspace_path,
-                        tenant, idempotency_key, max_runtime_seconds, skills
-                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                        tenant, idempotency_key, max_runtime_seconds, skills,
+                        max_retries
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                    """,
                    (
                        task_id,
@@ -1294,6 +1321,7 @@ def create_task(
                        idempotency_key,
                        int(max_runtime_seconds) if max_runtime_seconds else None,
                        json.dumps(skills_list) if skills_list is not None else None,
+                        int(max_retries) if max_retries is not None else None,
                    ),
                )
                for pid in parents:
@@ -1380,7 +1408,7 @@ def assign_task(conn: sqlite3.Connection, task_id: str, profile: Optional[str])
    profile = _canonical_assignee(profile)
    with write_txn(conn):
        row = conn.execute(
-            "SELECT status, claim_lock FROM tasks WHERE id = ?", (task_id,)
+            "SELECT status, claim_lock, assignee FROM tasks WHERE id = ?", (task_id,)
        ).fetchone()
        if not row:
            return False
@@ -1389,7 +1417,17 @@ def assign_task(conn: sqlite3.Connection, task_id: str, profile: Optional[str])
                f"cannot reassign {task_id}: currently running (claimed). "
                "Wait for completion or reclaim the stale lock first."
            )
-        conn.execute("UPDATE tasks SET assignee = ? WHERE id = ?", (profile, task_id))
+        if row["assignee"] != profile:
+            # The retry guard is scoped to the task/profile combination. A
+            # human reassigning the task is an explicit recovery action, so the
+            # new profile should not inherit the previous profile's streak.
+            conn.execute(
+                "UPDATE tasks SET assignee = ?, consecutive_failures = 0, "
+                "last_failure_error = NULL WHERE id = ?",
+                (profile, task_id),
+            )
+        else:
+            conn.execute("UPDATE tasks SET assignee = ? WHERE id = ?", (profile, task_id))
        _append_event(conn, task_id, "assigned", {"assignee": profile})
        return True

@@ -1859,34 +1897,47 @@ def heartbeat_claim(
        return False


-def release_stale_claims(conn: sqlite3.Connection) -> int:
+def release_stale_claims(
+    conn: sqlite3.Connection,
+    *,
+    signal_fn=None,
+) -> int:
    """Reset any ``running`` task whose claim has expired.

    Returns the number of stale claims reclaimed.  Safe to call often.
    """
    now = int(time.time())
    reclaimed = 0
-    with write_txn(conn):
-        stale = conn.execute(
-            "SELECT id, claim_lock FROM tasks "
-            "WHERE status = 'running' AND claim_expires IS NOT NULL AND claim_expires < ?",
-            (now,),
-        ).fetchall()
-        for row in stale:
-            conn.execute(
+    stale = conn.execute(
+        "SELECT id, claim_lock, worker_pid FROM tasks "
+        "WHERE status = 'running' AND claim_expires IS NOT NULL AND claim_expires < ?",
+        (now,),
+    ).fetchall()
+    for row in stale:
+        termination = _terminate_reclaimed_worker(
+            row["worker_pid"], row["claim_lock"], signal_fn=signal_fn,
+        )
+        with write_txn(conn):
+            cur = conn.execute(
                "UPDATE tasks SET status = 'ready', claim_lock = NULL, "
                "claim_expires = NULL, worker_pid = NULL "
-                "WHERE id = ? AND status = 'running'",
-                (row["id"],),
+                "WHERE id = ? AND status = 'running' AND claim_lock IS ? "
+                "AND claim_expires IS NOT NULL AND claim_expires < ?",
+                (row["id"], row["claim_lock"], now),
            )
+            if cur.rowcount != 1:
+                continue
            run_id = _end_run(
                conn, row["id"],
                outcome="reclaimed", status="reclaimed",
                error=f"stale_lock={row['claim_lock']}",
+                metadata=termination,
            )
+            payload = {"stale_lock": row["claim_lock"]}
+            payload.update(termination)
            _append_event(
                conn, row["id"], "reclaimed",
-                {"stale_lock": row["claim_lock"]},
+                payload,
                run_id=run_id,
            )
            reclaimed += 1
@@ -1898,6 +1949,7 @@ def reclaim_task(
    task_id: str,
    *,
    reason: Optional[str] = None,
+    signal_fn=None,
 ) -> bool:
    """Operator-driven reclaim: release the claim and reset to ``ready``.

@@ -1910,24 +1962,29 @@ def reclaim_task(
    Returns True if a reclaim happened, False if the task isn't in a
    reclaimable state (not running, or doesn't exist).
    """
+    row = conn.execute(
+        "SELECT status, claim_lock, worker_pid FROM tasks WHERE id = ?",
+        (task_id,),
+    ).fetchone()
+    if not row:
+        return False
+    if row["status"] != "running" and row["claim_lock"] is None:
+        # Nothing to reclaim — already ready / blocked / done.
+        return False
+    prev_lock = row["claim_lock"]
+    termination = _terminate_reclaimed_worker(
+        row["worker_pid"], prev_lock, signal_fn=signal_fn,
+    )
    with write_txn(conn):
-        row = conn.execute(
-            "SELECT status, claim_lock, worker_pid FROM tasks WHERE id = ?",
-            (task_id,),
-        ).fetchone()
-        if not row:
-            return False
-        if row["status"] != "running" and row["claim_lock"] is None:
-            # Nothing to reclaim — already ready / blocked / done.
-            return False
-        prev_lock = row["claim_lock"]
-        prev_pid = row["worker_pid"]
-        conn.execute(
+        cur = conn.execute(
            "UPDATE tasks SET status = 'ready', claim_lock = NULL, "
            "claim_expires = NULL, worker_pid = NULL "
-            "WHERE id = ? AND status IN ('running', 'ready', 'blocked')",
-            (task_id,),
+            "WHERE id = ? AND status IN ('running', 'ready', 'blocked') "
+            "AND claim_lock IS ?",
+            (task_id, prev_lock),
        )
+        if cur.rowcount != 1:
+            return False
        run_id = _end_run(
            conn, task_id,
            outcome="reclaimed", status="reclaimed",
@@ -1935,15 +1992,17 @@ def reclaim_task(
                f"manual_reclaim: {reason}" if reason
                else f"manual_reclaim lock={prev_lock}"
            ),
+            metadata=termination,
        )
+        payload = {
+            "manual": True,
+            "reason": reason,
+            "prev_lock": prev_lock,
+        }
+        payload.update(termination)
        _append_event(
            conn, task_id, "reclaimed",
-            {
-                "manual": True,
-                "reason": reason,
-                "prev_lock": prev_lock,
-                "prev_pid": prev_pid,
-            },
+            payload,
            run_id=run_id,
        )
    # Operator intervention — they've looked at the task, so the
@@ -2444,6 +2503,91 @@ def unblock_task(conn: sqlite3.Connection, task_id: str) -> bool:
        return True


+def specify_triage_task(
+    conn: sqlite3.Connection,
+    task_id: str,
+    *,
+    title: Optional[str] = None,
+    body: Optional[str] = None,
+    author: Optional[str] = None,
+) -> bool:
+    """Flesh out a triage task and promote it to ``todo``.
+
+    Atomically updates ``title`` / ``body`` (when provided) and transitions
+    ``status: triage -> todo`` in a single write txn. Returns False when
+    the task is missing or not in the ``triage`` column — callers should
+    surface that as "nothing to specify" rather than an error.
+
+    ``todo`` (not ``ready``) is the correct landing column: ``recompute_ready``
+    promotes parent-free / parent-done todos to ``ready`` on the next
+    dispatcher tick, which keeps the normal parent-gating behaviour intact
+    for specified tasks that happen to have open parents.
+
+    ``author`` is recorded on an audit comment only when at least one of
+    ``title`` / ``body`` actually changed — avoids noisy comment spam for
+    status-only promotions.
+    """
+    if title is not None and not title.strip():
+        raise ValueError("title cannot be blank")
+    with write_txn(conn):
+        existing = conn.execute(
+            "SELECT title, body FROM tasks WHERE id = ? AND status = 'triage'",
+            (task_id,),
+        ).fetchone()
+        if existing is None:
+            return False
+        sets: list[str] = ["status = 'todo'"]
+        params: list[Any] = []
+        changed_fields: list[str] = []
+        if title is not None and title.strip() != (existing["title"] or ""):
+            sets.append("title = ?")
+            params.append(title.strip())
+            changed_fields.append("title")
+        if body is not None and (body or "") != (existing["body"] or ""):
+            sets.append("body = ?")
+            params.append(body)
+            changed_fields.append("body")
+        params.append(task_id)
+        cur = conn.execute(
+            f"UPDATE tasks SET {', '.join(sets)} "
+            f"WHERE id = ? AND status = 'triage'",
+            tuple(params),
+        )
+        if cur.rowcount != 1:
+            return False
+        if changed_fields and author and author.strip():
+            # Inline INSERT (rather than ``add_comment``) because we're
+            # already inside this function's write_txn — nested BEGIN
+            # IMMEDIATE would raise OperationalError. We also skip the
+            # 'commented' event that ``add_comment`` emits, since the
+            # 'specified' event below already records the change.
+            conn.execute(
+                "INSERT INTO task_comments (task_id, author, body, created_at) "
+                "VALUES (?, ?, ?, ?)",
+                (
+                    task_id,
+                    author.strip(),
+                    "Specified — updated "
+                    + ", ".join(changed_fields)
+                    + " and promoted to todo.",
+                    int(time.time()),
+                ),
+            )
+        _append_event(
+            conn,
+            task_id,
+            "specified",
+            {"changed_fields": changed_fields} if changed_fields else None,
+        )
+    # Outside the write_txn above, so we don't nest BEGIN IMMEDIATE — the
+    # ready-promotion pass opens its own IMMEDIATE txn. This runs the same
+    # logic the dispatcher would on its next tick, so a specified task
+    # with no open parents flips straight to 'ready' here instead of
+    # idling in 'todo' until the next sweep.
+    recompute_ready(conn)
+    return True
+
+
 def archive_task(conn: sqlite3.Connection, task_id: str) -> bool:
    with write_txn(conn):
        cur = conn.execute(
@@ -2548,11 +2692,11 @@ def set_workspace_path(
 # Dispatcher (one-shot pass)
 # ---------------------------------------------------------------------------

-# After this many consecutive `spawn_failed` events on a task, the dispatcher
-# stops retrying and parks the task in ``blocked`` with a reason so a human
-# can investigate. Prevents the dispatcher from thrashing forever on a task
-# whose profile doesn't exist, whose workspace is unmountable, etc.
-DEFAULT_FAILURE_LIMIT = 5
+# After this many consecutive non-success attempts on a task/profile, the
+# dispatcher stops retrying and parks the task in ``blocked`` with a reason so
+# a human can investigate. Prevents retry storms when a worker repeatedly times
+# out, crashes, or cannot spawn.
+DEFAULT_FAILURE_LIMIT = 2
 # Legacy alias — callers / tests still reference the old name.
 DEFAULT_SPAWN_FAILURE_LIMIT = DEFAULT_FAILURE_LIMIT

@@ -2587,6 +2731,77 @@ class DispatchResult:
    """Task ids whose workers exceeded ``max_runtime_seconds``."""


+# Bounded registry of recently-reaped worker child exits, populated by the
+# reap loop at the top of ``dispatch_once`` and consulted by
+# ``detect_crashed_workers`` to classify a dead-pid task.
+#
+# Entry: ``pid -> (raw_wait_status, reaped_at_epoch)``. We keep raw status
+# so both ``os.WIFEXITED`` / ``os.WEXITSTATUS`` and ``os.WIFSIGNALED`` can
+# be consulted. Entries are trimmed by age (and total size cap as a
+# belt-and-braces against unbounded growth on exotic platforms).
+_RECENT_WORKER_EXIT_TTL_SECONDS = 600
+_RECENT_WORKER_EXITS_MAX = 4096
+_recent_worker_exits: "dict[int, tuple[int, float]]" = {}
+
+
+def _record_worker_exit(pid: int, raw_status: int) -> None:
+    """Record a reaped child's exit status for later classification.
+
+    Called from the reap loop in ``dispatch_once``. Safe to call many
+    times; duplicate pids overwrite (pids can cycle, latest wins).
+    """
+    if not pid or pid <= 0:
+        return
+    now = time.time()
+    _recent_worker_exits[int(pid)] = (int(raw_status), now)
+    # Age-based trim: drop entries older than the TTL.
+    if len(_recent_worker_exits) > _RECENT_WORKER_EXITS_MAX // 2:
+        cutoff = now - _RECENT_WORKER_EXIT_TTL_SECONDS
+        for _pid in [p for p, (_s, t) in _recent_worker_exits.items() if t < cutoff]:
+            _recent_worker_exits.pop(_pid, None)
+    # Size cap as a final guard.
+    if len(_recent_worker_exits) > _RECENT_WORKER_EXITS_MAX:
+        # Drop oldest half.
+        ordered = sorted(_recent_worker_exits.items(), key=lambda kv: kv[1][1])
+        for _pid, _ in ordered[: len(ordered) // 2]:
+            _recent_worker_exits.pop(_pid, None)
+
+
+def _classify_worker_exit(pid: int) -> "tuple[str, Optional[int]]":
+    """Classify a recently-reaped worker by pid.
+
+    Returns ``(kind, code)`` where ``kind`` is one of:
+
+    * ``"clean_exit"`` — ``WIFEXITED`` with ``WEXITSTATUS == 0``. When the
+      task is still ``running`` in the DB, this is a protocol violation
+      (worker exited without calling ``kanban_complete`` / ``kanban_block``)
+      and should be auto-blocked immediately — retrying will just loop.
+    * ``"nonzero_exit"`` — ``WIFEXITED`` with non-zero status. Real error.
+    * ``"signaled"`` — ``WIFSIGNALED`` (OOM killer, SIGKILL, etc). Real crash.
+    * ``"unknown"`` — pid was not in the reap registry (either reaped by
+      something else, or died between reap tick and liveness check). Fall
+      back to existing crashed-counter behavior.
+
+    ``code`` is the exit status (for ``clean_exit`` / ``nonzero_exit``) or
+    the signal number (for ``signaled``), or ``None`` for ``unknown``.
+    """
+    entry = _recent_worker_exits.get(int(pid))
+    if entry is None:
+        return ("unknown", None)
+    raw, _ = entry
+    try:
+        if os.WIFEXITED(raw):
+            code = os.WEXITSTATUS(raw)
+            if code == 0:
+                return ("clean_exit", 0)
+            return ("nonzero_exit", code)
+        if os.WIFSIGNALED(raw):
+            return ("signaled", os.WTERMSIG(raw))
+    except Exception:
+        pass
+    return ("unknown", None)
+
+
 def _pid_alive(pid: Optional[int]) -> bool:
    """Return True if ``pid`` is still running on this host.

@@ -2652,6 +2867,59 @@ def _pid_alive(pid: Optional[int]) -> bool:
    return True


+def _terminate_reclaimed_worker(
+    pid: Optional[int],
+    claim_lock: Optional[str],
+    *,
+    signal_fn=None,
+) -> dict[str, Any]:
+    """Best-effort host-local worker termination for reclaim paths."""
+    import signal
+
+    info: dict[str, Any] = {
+        "prev_pid": int(pid) if pid else None,
+        "host_local": False,
+        "termination_attempted": False,
+        "terminated": False,
+        "sigkill": False,
+    }
+    if not pid or pid <= 0 or not claim_lock:
+        return info
+
+    host_prefix = f"{_claimer_id().split(':', 1)[0]}:"
+    if not str(claim_lock).startswith(host_prefix):
+        return info
+    info["host_local"] = True
+
+    kill = signal_fn if signal_fn is not None else (
+        os.kill if hasattr(os, "kill") else None
+    )
+    if kill is None:
+        return info
+
+    info["termination_attempted"] = True
+    try:
+        kill(int(pid), signal.SIGTERM)
+    except (ProcessLookupError, OSError):
+        return info
+
+    for _ in range(10):
+        if not _pid_alive(pid):
+            info["terminated"] = True
+            return info
+        time.sleep(0.5)
+
+    if _pid_alive(pid):
+        try:
+            kill(int(pid), signal.SIGKILL)
+            info["sigkill"] = True
+        except (ProcessLookupError, OSError):
+            return info
+
+    info["terminated"] = not _pid_alive(pid)
+    return info
+
+
 def heartbeat_worker(
    conn: sqlite3.Connection,
    task_id: str,
@@ -2840,12 +3108,22 @@ def detect_crashed_workers(conn: sqlite3.Connection) -> list[str]:
    are meaningless here. The host-local check is enough because
    ``_default_spawn`` always runs the worker on the same host as the
    dispatcher (the whole design is single-host).
+
+    When the reap registry shows the worker exited cleanly (rc=0) but
+    the task was still ``running`` in the DB, treat it as a protocol
+    violation (worker answered conversationally without calling
+    ``kanban_complete`` / ``kanban_block``) and trip the circuit breaker
+    on the first occurrence — retrying a worker whose CLI keeps
+    returning 0 without a terminal transition just loops forever.
    """
    crashed: list[str] = []
    # Per-crash details collected inside the main txn, used after it
    # closes to run ``_record_task_failure`` (which needs its own
-    # write_txn so can't nest).
-    crash_details: list[tuple[str, int, str]] = []  # (task_id, pid, claimer)
+    # write_txn so can't nest). ``protocol_violation`` flags the
+    # clean-exit-but-still-running case so we can trip the breaker
+    # immediately instead of incrementing by 1.
+    crash_details: list[tuple[str, int, str, bool, str]] = []
+    # (task_id, pid, claimer, protocol_violation, error_text)
    with write_txn(conn):
        rows = conn.execute(
            "SELECT id, worker_pid, claim_lock FROM tasks "
@@ -2859,6 +3137,39 @@ def detect_crashed_workers(conn: sqlite3.Connection) -> list[str]:
                continue
            if _pid_alive(row["worker_pid"]):
                continue
+
+            pid = int(row["worker_pid"])
+            kind, code = _classify_worker_exit(pid)
+            if kind == "clean_exit":
+                # Worker subprocess returned 0 but its task is still
+                # ``running`` in the DB — it exited without calling
+                # ``kanban_complete`` / ``kanban_block``. Retrying won't
+                # help.
+                protocol_violation = True
+                error_text = (
+                    "worker exited cleanly (rc=0) without calling "
+                    "kanban_complete or kanban_block — protocol violation"
+                )
+                event_kind = "protocol_violation"
+                event_payload = {
+                    "pid": pid,
+                    "claimer": row["claim_lock"],
+                    "exit_code": code,
+                }
+            else:
+                protocol_violation = False
+                if kind == "nonzero_exit":
+                    error_text = f"pid {pid} exited with code {code}"
+                elif kind == "signaled":
+                    error_text = f"pid {pid} killed by signal {code}"
+                else:
+                    error_text = f"pid {pid} not alive"
+                event_kind = "crashed"
+                event_payload = {"pid": pid, "claimer": row["claim_lock"]}
+                if code is not None and kind != "unknown":
+                    event_payload["exit_kind"] = kind
+                    event_payload["exit_code"] = code
+
            cur = conn.execute(
                "UPDATE tasks SET status = 'ready', claim_lock = NULL, "
                "claim_expires = NULL, worker_pid = NULL "
@@ -2869,34 +3180,47 @@ def detect_crashed_workers(conn: sqlite3.Connection) -> list[str]:
                run_id = _end_run(
                    conn, row["id"],
                    outcome="crashed", status="crashed",
-                    error=f"pid {int(row['worker_pid'])} not alive",
-                    metadata={
-                        "pid": int(row["worker_pid"]),
-                        "claimer": row["claim_lock"],
-                    },
+                    error=error_text,
+                    metadata=dict(event_payload),
                )
                _append_event(
-                    conn, row["id"], "crashed",
-                    {"pid": int(row["worker_pid"]), "claimer": row["claim_lock"]},
+                    conn, row["id"], event_kind,
+                    event_payload,
                    run_id=run_id,
                )
                crashed.append(row["id"])
                crash_details.append(
-                    (row["id"], int(row["worker_pid"]), row["claim_lock"])
+                    (row["id"], pid, row["claim_lock"],
+                     protocol_violation, error_text)
                )
    # Outside the main txn: increment the unified failure counter for
    # each crashed task. If the breaker trips, the task transitions
    # ready → blocked with a ``gave_up`` event on top of the ``crashed``
    # event we already emitted.
-    for tid, pid, claimer in crash_details:
-        _record_task_failure(
+    #
+    # Protocol-violation crashes force an immediate trip (failure_limit=1)
+    # because clean-exit-without-transition is deterministic: the next
+    # respawn will do exactly the same thing. Better to surface to a
+    # human with a clear reason than to loop ``DEFAULT_FAILURE_LIMIT``
+    # times first.
+    auto_blocked: list[str] = []
+    for tid, pid, claimer, protocol_violation, error_text in crash_details:
+        tripped = _record_task_failure(
            conn, tid,
-            error=f"pid {pid} not alive",
+            error=error_text,
            outcome="crashed",
+            failure_limit=(1 if protocol_violation else None),
            release_claim=False,
            end_run=False,
            event_payload_extra={"pid": pid, "claimer": claimer},
        )
+        if tripped:
+            auto_blocked.append(tid)
+    # Stash auto-blocked ids on the function for the dispatch loop to pick up.
+    # Keeps the public return type (``list[str]``) stable for direct callers
+    # and tests that destructure the result; ``dispatch_once`` reads this
+    # side-channel attribute to populate ``DispatchResult.auto_blocked``.
+    detect_crashed_workers._last_auto_blocked = auto_blocked  # type: ignore[attr-defined]
    return crashed


@@ -2938,20 +3262,39 @@ def _record_task_failure(
    ``event_payload_extra`` merges into the ``gave_up`` event payload
    when the breaker trips, so callers can include outcome-specific
    context (e.g. pid on crash, elapsed on timeout).
+
+    Resolution order for the effective threshold:
+      1. per-task ``max_retries`` if set (nothing else overrides)
+      2. caller-supplied ``failure_limit`` (gateway passes the config
+         value from ``kanban.failure_limit``; tests pass fixed values)
+      3. ``DEFAULT_FAILURE_LIMIT``
    """
    if failure_limit is None:
        failure_limit = DEFAULT_FAILURE_LIMIT
    blocked = False
    with write_txn(conn):
        row = conn.execute(
-            "SELECT consecutive_failures, status FROM tasks WHERE id = ?", (task_id,),
+            "SELECT consecutive_failures, status, max_retries "
+            "FROM tasks WHERE id = ?", (task_id,),
        ).fetchone()
        if row is None:
            return False
        failures = int(row["consecutive_failures"]) + 1
        cur_status = row["status"]

-        if failures >= failure_limit:
+        # Per-task override wins over both caller-supplied and default
+        # thresholds. None (the common case) falls through.
+        task_override = (
+            row["max_retries"] if "max_retries" in row.keys() else None
+        )
+        if task_override is not None:
+            effective_limit = int(task_override)
+            limit_source = "task"
+        else:
+            effective_limit = int(failure_limit)
+            limit_source = "dispatcher"
+
+        if failures >= effective_limit:
            # Trip the breaker.
            if release_claim:
                # Spawn path: still running, also clear claim state.
@@ -2979,10 +3322,17 @@ def _record_task_failure(
                    conn, task_id,
                    outcome="gave_up", status="gave_up",
                    error=error[:500],
-                    metadata={"failures": failures, "trigger_outcome": outcome},
+                    metadata={
+                        "failures": failures,
+                        "trigger_outcome": outcome,
+                        "effective_limit": effective_limit,
+                        "limit_source": limit_source,
+                    },
                )
            payload = {
                "failures": failures,
+                "effective_limit": effective_limit,
+                "limit_source": limit_source,
                "error": error[:500],
                "trigger_outcome": outcome,
            }
@@ -3150,9 +3500,43 @@ def dispatch_once(
    ``board`` pins workspace/log/db resolution for this tick to a specific
    board. When omitted, the current-board resolution chain is used.
    """
+    # Reap zombie children from previously spawned workers.
+    # The gateway-embedded dispatcher is the parent of every worker spawned
+    # via _default_spawn (start_new_session=True only detaches the
+    # controlling tty, not the parent). Without an explicit waitpid, each
+    # completed worker becomes a <defunct> entry that lingers until gateway
+    # exit. WNOHANG keeps this non-blocking; ChildProcessError means no
+    # children to reap. Bounded: at most one tick's worth of completions
+    # can be in <defunct> at once.
+    #
+    # We also record the exit status keyed by pid, so
+    # ``detect_crashed_workers`` can distinguish a worker that exited
+    # cleanly without calling ``kanban_complete`` / ``kanban_block``
+    # (protocol violation — auto-block) from a real crash (OOM killer,
+    # SIGKILL, non-zero exit — existing counter behavior).
+    try:
+        while True:
+            try:
+                _pid, _status = os.waitpid(-1, os.WNOHANG)
+            except ChildProcessError:
+                break
+            if _pid == 0:
+                break
+            _record_worker_exit(_pid, _status)
+    except Exception:
+        pass
+
    result = DispatchResult()
    result.reclaimed = release_stale_claims(conn)
    result.crashed = detect_crashed_workers(conn)
+    # detect_crashed_workers stashes protocol-violation auto-blocks on
+    # itself so the public list-return stays stable. Pull them into the
+    # DispatchResult here so telemetry / tests see the trip.
+    _crash_auto_blocked = getattr(
+        detect_crashed_workers, "_last_auto_blocked", []
+    )
+    if _crash_auto_blocked:
+        result.auto_blocked.extend(_crash_auto_blocked)
    result.timed_out = enforce_max_runtime(conn)
    result.promoted = recompute_ready(conn)

@@ -0,0 +1,265 @@
+"""Kanban triage specifier — flesh out a one-liner into a real spec.
+
+Used by ``hermes kanban specify [task_id | --all]``. Takes a task that
+lives in the Triage column (a rough idea, typically only a title), calls
+the auxiliary LLM to produce:
+
+  * A tightened title (optional — only replaces if the model proposes a
+    materially different one)
+  * A concrete body: goal, proposed approach, acceptance criteria
+
+and then flips the task ``triage -> todo`` via
+``kanban_db.specify_triage_task``. The dispatcher promotes it to
+``ready`` on its next tick (or immediately if there are no open parents).
+
+Design notes
+------------
+
+* This module intentionally mirrors ``hermes_cli/goals.py`` — same aux
+  client pattern, same "empty config => skip, don't crash" tolerance.
+  Keeps the surface area tiny and the failure modes predictable.
+
+* The prompt is a short system + user pair. We ask for JSON with
+  ``{title, body}``; if parsing fails, we fall back to treating the
+  whole response as the body and leave the title untouched. No
+  retry loop — one shot, keep cost bounded.
+
+* Structured output / JSON mode is not requested explicitly so the
+  specifier works on providers that don't implement it. The parse
+  is lenient (tolerates markdown code fences around the JSON).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from hermes_cli import kanban_db as kb
+
+logger = logging.getLogger(__name__)
+
+
+_SYSTEM_PROMPT = """You are the Kanban triage specifier for the Hermes Agent board.
+A user dropped a rough idea into the Triage column. Your job is to turn it
+into a concrete, actionable task spec that an autonomous worker can pick up
+and execute without further clarification.
+
+Output a single JSON object with exactly two keys:
+
+  {
+    "title": "<tightened task title, <= 80 chars, imperative voice>",
+    "body":  "<multi-line spec, see structure below>"
+  }
+
+The body MUST include these sections, each prefixed with a bold markdown
+heading, in this order:
+
+  **Goal** — one sentence, user-facing outcome.
+  **Approach** — 2-5 bullets on how a worker should tackle it.
+  **Acceptance criteria** — checklist of concrete, verifiable conditions.
+  **Out of scope** — short list of things NOT to touch (omit if nothing
+      obvious; never invent scope creep).
+
+Rules:
+  - Keep the tightened title close in meaning to the original idea — do
+    NOT invent a different project.
+  - If the original idea is already detailed, preserve its substance and
+    just reformat into the sections above.
+  - Never add invented requirements the user didn't hint at.
+  - No preamble, no closing remarks, no code fences around the JSON.
+  - Output only the JSON object and nothing else.
+"""
+
+
+_USER_TEMPLATE = """Task id: {task_id}
+Current title: {title}
+Current body:
+{body}
+"""
+
+
+@dataclass
+class SpecifyOutcome:
+    """Result of specifying a single triage task."""
+
+    task_id: str
+    ok: bool
+    reason: str = ""
+    new_title: Optional[str] = None
+
+
+def _truncate(text: str, limit: int) -> str:
+    if len(text) <= limit:
+        return text
+    return text[: limit - 1] + "…"
+
+
+_FENCE_RE = re.compile(r"^\s*```(?:json)?\s*|\s*```\s*$", re.IGNORECASE)
+
+
+def _extract_json_blob(raw: str) -> Optional[dict]:
+    """Lenient JSON extraction — tolerates fenced code blocks and
+    leading/trailing whitespace. Returns None if nothing parses."""
+    if not raw:
+        return None
+    stripped = _FENCE_RE.sub("", raw.strip())
+    # Greedy: find the first `{` and last `}` and try that slice.
+    first = stripped.find("{")
+    last = stripped.rfind("}")
+    if first == -1 or last == -1 or last <= first:
+        return None
+    candidate = stripped[first : last + 1]
+    try:
+        val = json.loads(candidate)
+    except (ValueError, json.JSONDecodeError):
+        return None
+    if not isinstance(val, dict):
+        return None
+    return val
+
+
+def _profile_author() -> str:
+    """Mirror of ``hermes_cli.kanban._profile_author``. Kept local to
+    avoid a circular import when kanban.py imports this module."""
+    return (
+        os.environ.get("HERMES_PROFILE")
+        or os.environ.get("USER")
+        or "specifier"
+    )
+
+
+def specify_task(
+    task_id: str,
+    *,
+    author: Optional[str] = None,
+    timeout: Optional[int] = None,
+) -> SpecifyOutcome:
+    """Specify a single triage task and promote it to ``todo``.
+
+    Returns an outcome describing what happened. Never raises for expected
+    failure modes (task not in triage, no aux client configured, API
+    error, malformed response) — those surface via ``ok=False`` so the
+    ``--all`` sweep can continue past individual failures.
+    """
+    with kb.connect() as conn:
+        task = kb.get_task(conn, task_id)
+    if task is None:
+        return SpecifyOutcome(task_id, False, "unknown task id")
+    if task.status != "triage":
+        return SpecifyOutcome(
+            task_id, False, f"task is not in triage (status={task.status!r})"
+        )
+
+    try:
+        from agent.auxiliary_client import get_text_auxiliary_client
+    except Exception as exc:  # pragma: no cover — import smoke test
+        logger.debug("specify: auxiliary client import failed: %s", exc)
+        return SpecifyOutcome(task_id, False, "auxiliary client unavailable")
+
+    try:
+        client, model = get_text_auxiliary_client("triage_specifier")
+    except Exception as exc:
+        logger.debug("specify: get_text_auxiliary_client failed: %s", exc)
+        return SpecifyOutcome(task_id, False, "auxiliary client unavailable")
+
+    if client is None or not model:
+        return SpecifyOutcome(
+            task_id, False, "no auxiliary client configured"
+        )
+
+    user_msg = _USER_TEMPLATE.format(
+        task_id=task.id,
+        title=_truncate(task.title or "", 400),
+        body=_truncate(task.body or "(no body)", 4000),
+    )
+
+    try:
+        resp = client.chat.completions.create(
+            model=model,
+            messages=[
+                {"role": "system", "content": _SYSTEM_PROMPT},
+                {"role": "user", "content": user_msg},
+            ],
+            temperature=0.3,
+            max_tokens=1500,
+            timeout=timeout or 120,
+        )
+    except Exception as exc:
+        logger.info(
+            "specify: API call failed for %s (%s) — skipping",
+            task_id, exc,
+        )
+        return SpecifyOutcome(
+            task_id, False, f"LLM error: {type(exc).__name__}"
+        )
+
+    try:
+        raw = resp.choices[0].message.content or ""
+    except Exception:
+        raw = ""
+
+    parsed = _extract_json_blob(raw)
+
+    new_title: Optional[str]
+    new_body: Optional[str]
+    if parsed is None:
+        # Fall back: treat the whole reply as the body, leave title as-is.
+        # Worst case the user edits afterward — still better than stranding
+        # the task in triage on a malformed LLM reply.
+        stripped_raw = raw.strip()
+        if not stripped_raw:
+            return SpecifyOutcome(
+                task_id, False, "LLM returned an empty response"
+            )
+        new_title = None
+        new_body = stripped_raw
+    else:
+        title_val = parsed.get("title")
+        body_val = parsed.get("body")
+        new_title = (
+            title_val.strip()
+            if isinstance(title_val, str) and title_val.strip()
+            else None
+        )
+        new_body = (
+            body_val if isinstance(body_val, str) and body_val.strip() else None
+        )
+        if new_body is None and new_title is None:
+            return SpecifyOutcome(
+                task_id, False, "LLM response missing title and body"
+            )
+
+    with kb.connect() as conn:
+        ok = kb.specify_triage_task(
+            conn,
+            task_id,
+            title=new_title,
+            body=new_body,
+            author=author or _profile_author(),
+        )
+    if not ok:
+        # Race: someone else promoted / archived the task between our
+        # read above and the write. Report, don't crash.
+        return SpecifyOutcome(
+            task_id, False, "task moved out of triage before promotion"
+        )
+    return SpecifyOutcome(task_id, True, "specified", new_title=new_title)
+
+
+def list_triage_ids(*, tenant: Optional[str] = None) -> list[str]:
+    """Return task ids currently in the triage column.
+
+    ``tenant`` narrows the sweep; ``None`` returns every triage task.
+    """
+    with kb.connect() as conn:
+        tasks = kb.list_tasks(
+            conn,
+            status="triage",
+            tenant=tenant,
+            include_archived=False,
+        )
+    return [t.id for t in tasks]
@@ -43,12 +43,20 @@ Usage:
    hermes claw migrate --dry-run  # Preview migration without changes
 """

+import os
+import sys
+from utf8_bootstrap import ensure_windows_utf8_mode
+
+# Force UTF-8 defaults on Windows before any module-level file I/O.
+ensure_windows_utf8_mode(
+    module="hermes_cli.main",
+    entrypoint_markers=("hermes", "main.py"),
+)
+
 import argparse
 import json
-import os
 import shutil
 import subprocess
-import sys
 from pathlib import Path
 from typing import Optional

@@ -230,6 +238,7 @@ except Exception:
    pass  # best-effort — don't crash if config isn't available yet

 import logging
+import threading
 import time as _time
 from datetime import datetime

@@ -6445,6 +6454,45 @@ def _load_installable_optional_extras() -> list[str]:
    return referenced


+def _run_install_with_heartbeat(
+    cmd: list[str],
+    *,
+    env: dict[str, str] | None = None,
+    heartbeat_interval_seconds: int = 30,
+) -> None:
+    """Run dependency install command with periodic heartbeat output.
+
+    Some resolvers/build backends (especially when compiling Rust/C extensions)
+    can stay quiet for minutes. Emit a simple elapsed-time heartbeat so users
+    know ``hermes update`` is still progressing even if pip/uv itself is silent.
+    """
+    done = threading.Event()
+    start = _time.time()
+
+    def _heartbeat() -> None:
+        # Wait first, then print, so short installs don't emit noise.
+        while not done.wait(heartbeat_interval_seconds):
+            elapsed = int(_time.time() - start)
+            print(
+                f"  … still installing dependencies ({elapsed}s elapsed)"
+                " — compiling Rust/C extensions can take several minutes",
+                flush=True,
+            )
+
+    t = threading.Thread(target=_heartbeat, daemon=True)
+    t.start()
+    try:
+        subprocess.run(
+            cmd,
+            cwd=PROJECT_ROOT,
+            check=True,
+            env=env,
+        )
+    finally:
+        done.set()
+        t.join(timeout=0.2)
+
+
 def _install_python_dependencies_with_optional_fallback(
    install_cmd_prefix: list[str],
    *,
@@ -6461,12 +6509,13 @@ def _install_python_dependencies_with_optional_fallback(
    Collecting/Building/Installing step), so keeping it visible costs
    nothing on fast hardware and prevents the "hermes update hangs" reports
    on slow hardware.
+
+    We also add periodic heartbeat lines in case the resolver/build backend is
+    itself silent for long stretches.
    """
    try:
-        subprocess.run(
+        _run_install_with_heartbeat(
            install_cmd_prefix + ["install", "-e", ".[all]"],
-            cwd=PROJECT_ROOT,
-            check=True,
            env=env,
        )
        return
@@ -6475,10 +6524,8 @@ def _install_python_dependencies_with_optional_fallback(
            "  ⚠ Optional extras failed, reinstalling base dependencies and retrying extras individually..."
        )

-    subprocess.run(
+    _run_install_with_heartbeat(
        install_cmd_prefix + ["install", "-e", "."],
-        cwd=PROJECT_ROOT,
-        check=True,
        env=env,
    )

@@ -6486,10 +6533,8 @@ def _install_python_dependencies_with_optional_fallback(
    installed_extras: list[str] = []
    for extra in _load_installable_optional_extras():
        try:
-            subprocess.run(
+            _run_install_with_heartbeat(
                install_cmd_prefix + ["install", "-e", f".[{extra}]"],
-                cwd=PROJECT_ROOT,
-                check=True,
                env=env,
            )
            installed_extras.append(extra)
@@ -7331,7 +7376,9 @@ def _cmd_update_impl(args, gateway_mode: bool):
                for p in all_profiles:
                    try:
                        r = seed_profile_skills(p.path, quiet=True)
-                        if r:
+                        if r and r.get("skipped_opt_out"):
+                            status = "opted out (--no-skills)"
+                        elif r:
                            copied = len(r.get("copied", []))
                            updated = len(r.get("updated", []))
                            modified = len(r.get("user_modified", []))
@@ -7402,11 +7449,8 @@ def _cmd_update_impl(args, gateway_mode: bool):
                    .lower()
                )
            elif not (sys.stdin.isatty() and sys.stdout.isatty()):
-                print("  ℹ Non-interactive session — skipping config migration prompt.")
-                print(
-                    "    Run 'hermes config migrate' later to apply any new config/env options."
-                )
-                response = "n"
+                print("  ℹ Non-interactive session — applying safe config migrations.")
+                response = "auto"
            else:
                try:
                    response = (
@@ -7417,19 +7461,22 @@ def _cmd_update_impl(args, gateway_mode: bool):
                except EOFError:
                    response = "n"

-            if response in ("", "y", "yes"):
+            if response in ("", "y", "yes", "auto"):
                print()
-                # In gateway mode OR under --yes, run auto-migrations only (no
-                # input() prompts for API keys which would hang the detached
-                # process / defeat the point of --yes).
-                results = migrate_config(
-                    interactive=not (gateway_mode or assume_yes), quiet=False
+                # Gateway mode, --yes, and non-interactive update contexts
+                # (dashboard / web server actions) cannot prompt for API keys.
+                # Still run the non-interactive migration pass before restarting
+                # so new default config fields and version bumps are written
+                # before the freshly updated gateway validates config at startup.
+                interactive_migration = not (
+                    gateway_mode or assume_yes or response == "auto"
                )
+                results = migrate_config(interactive=interactive_migration, quiet=False)

                if results["env_added"] or results["config_added"]:
                    print()
                    print("✓ Configuration updated!")
-                if (gateway_mode or assume_yes) and missing_env:
+                if (gateway_mode or assume_yes or response == "auto") and missing_env:
                    print("  ℹ API keys require manual entry: hermes config migrate")
            else:
                print()
@@ -7733,6 +7780,23 @@ def _cmd_update_impl(args, gateway_mode: bool):
                            # when the graceful path failed (unit missing
                            # SIGUSR1 wiring, drain exceeded the budget,
                            # restart-policy mismatch).
+                            #
+                            # Always `reset-failed` first.  If systemd's own
+                            # auto-restart attempts already parked the unit
+                            # in a failed state (transient CHDIR / OOM /
+                            # filesystem race after our drain + exit-75),
+                            # a plain `systemctl restart` can wedge against
+                            # the RestartSec backoff and leave the unit
+                            # dead.  Clearing the failed state first makes
+                            # the restart idempotent.  Mirrors the recovery
+                            # path in `hermes gateway restart`
+                            # (`systemd_restart()`) as of PR #20949.
+                            subprocess.run(
+                                scope_cmd + ["reset-failed", svc_name],
+                                capture_output=True,
+                                text=True,
+                                timeout=10,
+                            )
                            restart = subprocess.run(
                                scope_cmd + ["restart", svc_name],
                                capture_output=True,
@@ -7752,10 +7816,19 @@ def _cmd_update_impl(args, gateway_mode: bool):
                                else:
                                    # Retry once — transient startup failures
                                    # (stale module cache, import race) often
-                                    # resolve on the second attempt.
+                                    # resolve on the second attempt.  Again
+                                    # clear any failed state first so the
+                                    # retry isn't blocked by the previous
+                                    # crash.
                                    print(
                                        f"  ⚠ {svc_name} died after restart, retrying..."
                                    )
+                                    subprocess.run(
+                                        scope_cmd + ["reset-failed", svc_name],
+                                        capture_output=True,
+                                        text=True,
+                                        timeout=10,
+                                    )
                                    subprocess.run(
                                        scope_cmd + ["restart", svc_name],
                                        capture_output=True,
@@ -7770,10 +7843,13 @@ def _cmd_update_impl(args, gateway_mode: bool):
                                        restarted_services.append(svc_name)
                                        print(f"  ✓ {svc_name} recovered on retry")
                                    else:
+                                        _scope_flag = "--user " if scope == "user" else ""
                                        print(
                                            f"  ✗ {svc_name} failed to stay running after restart.\n"
-                                            f"    Check logs: journalctl --user -u {svc_name} --since '2 min ago'\n"
-                                            f"    Restart manually: systemctl {'--user ' if scope == 'user' else ''}restart {svc_name}"
+                                            f"    Check logs: journalctl {_scope_flag}-u {svc_name} --since '2 min ago'\n"
+                                            f"    Recover manually:\n"
+                                            f"      systemctl {_scope_flag}reset-failed {svc_name}\n"
+                                            f"      systemctl {_scope_flag}restart {svc_name}"
                                        )
                            else:
                                print(
@@ -8124,6 +8200,7 @@ def cmd_profile(args):
        clone = getattr(args, "clone", False)
        clone_all = getattr(args, "clone_all", False)
        no_alias = getattr(args, "no_alias", False)
+        no_skills = getattr(args, "no_skills", False)

        try:
            clone_from = getattr(args, "clone_from", None)
@@ -8134,6 +8211,7 @@ def cmd_profile(args):
                clone_all=clone_all,
                clone_config=clone,
                no_alias=no_alias,
+                no_skills=no_skills,
            )
            print(f"\nProfile '{name}' created at {profile_dir}")

@@ -8158,10 +8236,17 @@ def cmd_profile(args):
                except Exception:
                    pass  # Honcho plugin not installed or not configured

-            # Seed bundled skills (skip if --clone-all already copied them)
+            # Seed bundled skills (skip if --clone-all already copied them, or
+            # if --no-skills was passed — in which case seed_profile_skills()
+            # honors the marker file and returns skipped_opt_out=True).
            if not clone_all:
                result = seed_profile_skills(profile_dir)
-                if result:
+                if result and result.get("skipped_opt_out"):
+                    print(
+                        "No bundled skills seeded (--no-skills). "
+                        "Delete .no-bundled-skills in the profile to opt back in."
+                    )
+                elif result:
                    copied = len(result.get("copied", []))
                    print(f"{copied} bundled skills synced.")
                else:
@@ -8679,6 +8764,9 @@ def main():
        help="Target the Linux system-level gateway service",
    )

+    # gateway list
+    gateway_subparsers.add_parser("list", help="List all profiles and their gateway status")
+
    # gateway setup
    gateway_subparsers.add_parser("setup", help="Configure messaging platforms")

@@ -9996,7 +10084,15 @@ Examples:
    )
    mcp_add_p.add_argument("name", help="Server name (used as config key)")
    mcp_add_p.add_argument("--url", help="HTTP/SSE endpoint URL")
-    mcp_add_p.add_argument("--command", help="Stdio command (e.g. npx)")
+    # dest="mcp_command" so this flag does not clobber the top-level
+    # subparser's args.command attribute, which the dispatcher reads to
+    # route to cmd_mcp.  Without an explicit dest, argparse derives
+    # dest="command" from the flag name and sets it to None when the
+    # flag is omitted, causing `hermes mcp add ...` to fall through to
+    # interactive chat.
+    mcp_add_p.add_argument(
+        "--command", dest="mcp_command", help="Stdio command (e.g. npx)"
+    )
    mcp_add_p.add_argument(
        "--args", nargs="*", default=[], help="Arguments for stdio command"
    )
@@ -10523,6 +10619,11 @@ Examples:
    profile_create.add_argument(
        "--no-alias", action="store_true", help="Skip wrapper script creation"
    )
+    profile_create.add_argument(
+        "--no-skills",
+        action="store_true",
+        help="Create an empty profile with no bundled skills (opts out of `hermes update` skill sync)",
+    )

    profile_delete = profile_subparsers.add_parser("delete", help="Delete a profile")
    profile_delete.add_argument("profile_name", help="Profile to delete")
@@ -221,7 +221,10 @@ def cmd_mcp_add(args):
    """Add a new MCP server with discovery-first tool selection."""
    name = args.name
    url = getattr(args, "url", None)
-    command = getattr(args, "command", None)
+    # Read from `mcp_command` (set by --command via explicit dest) — see
+    # mcp_add_p.add_argument("--command", dest="mcp_command", ...) in
+    # hermes_cli/main.py for why the dest is renamed.
+    command = getattr(args, "mcp_command", None)
    cmd_args = getattr(args, "args", None) or []
    auth_type = getattr(args, "auth", None)
    preset_name = getattr(args, "preset", None)
@@ -1637,7 +1637,8 @@ def list_authenticated_providers(
                        groups[group_key]["models"].append(m)

        _section4_emitted_slugs: set = set()
-        for grp in groups.values():
+        for grp_key, grp in groups.items():
+            api_url, api_key = grp_key
            slug = grp["slug"]
            # If the slug is already claimed by a built-in / overlay /
            # user-provider row (sections 1-3), skip this custom group
@@ -1675,6 +1676,18 @@ def list_authenticated_providers(
            _grp_url_norm = _pair_key[1]
            if _grp_url_norm and _grp_url_norm in _builtin_endpoints:
                continue
+            # Live model discovery from custom provider endpoints (matches
+            # Section 3 behavior for user ``providers:`` entries).
+            if api_url and api_key:
+                try:
+                    from hermes_cli.models import fetch_api_models
+
+                    live_models = fetch_api_models(api_key, api_url)
+                    if live_models:
+                        grp["models"] = live_models
+                        grp["total_models"] = len(live_models)
+                except Exception:
+                    pass
            results.append({
                "slug": slug,
                "name": grp["name"],
@@ -46,6 +46,7 @@ OPENROUTER_MODELS: list[tuple[str, str]] = [
    ("xiaomi/mimo-v2.5-pro",             ""),
    ("xiaomi/mimo-v2.5",                 ""),
    ("tencent/hy3-preview:free",         "free"),
+    ("tencent/hy3-preview",              ""),
    ("openai/gpt-5.3-codex",            ""),
    ("google/gemini-3-pro-image-preview", ""),
    ("google/gemini-3-flash-preview",   ""),
@@ -416,6 +417,18 @@ _PROVIDER_MODELS: dict[str, list[str]] = {
        "glm-4.7",
        "MiniMax-M2.5",
    ],
+    # Alibaba Coding Plan — same platform as alibaba (DashScope coding-intl),
+    # separate provider ID with its own base_url_env_var.
+    "alibaba-coding-plan": [
+        "qwen3.6-plus",
+        "qwen3.5-plus",
+        "qwen3-coder-plus",
+        "qwen3-coder-next",
+        "kimi-k2.5",
+        "glm-5",
+        "glm-4.7",
+        "MiniMax-M2.5",
+    ],
    # Curated HF model list — only agentic models that map to OpenRouter defaults.
    "huggingface": [
        "moonshotai/Kimi-K2.5",
@@ -73,6 +73,24 @@ def _cmd_approve(store, platform: str, code: str):
        display = f"{name} ({uid})" if name else uid
        print(f"\n  Approved! User {display} on {platform} can now use the bot~")
        print("  They'll be recognized automatically on their next message.\n")
+    elif store._is_locked_out(platform):
+        # Disambiguate: approve_code returns None for both invalid codes
+        # and lockout. Tell the operator it's lockout so they don't chase
+        # a "wrong code" rabbit hole (#10195).
+        import time as _time
+        limits = store._load_json(store._rate_limit_path())
+        lockout_until = limits.get(f"_lockout:{platform}", 0)
+        remaining = max(0, int(lockout_until - _time.time()))
+        mins = remaining // 60
+        print(
+            f"\n  Platform '{platform}' is locked out after too many failed "
+            f"approval attempts."
+        )
+        print(f"  Lockout clears in ~{mins} minute(s).")
+        print(
+            "  To reset sooner, delete the '_lockout:{0}' entry from "
+            "~/.hermes/platforms/pairing/_rate_limits.json\n".format(platform)
+        )
    else:
        print(f"\n  Code '{code}' not found or expired for platform '{platform}'.")
        print("  Run 'hermes pairing list' to see pending codes.\n")
@@ -80,6 +80,10 @@ VALID_HOOKS: Set[str] = {
    "post_tool_call",
    "transform_terminal_output",
    "transform_tool_result",
+    # Transform LLM output before it's returned to the user.
+    # Plugins return a string to replace the response text, or None/empty to leave unchanged.
+    # First non-None string wins. Useful for vocabulary/personality transformation.
+    "transform_llm_output",
    "pre_llm_call",
    "post_llm_call",
    "pre_api_request",
@@ -71,6 +71,22 @@ _CLONE_ALL_STRIP = [
    "processes.json",
 ]

+# Marker file written by `hermes profile create --no-skills`.  When present in
+# a profile's root, callers of seed_profile_skills() (fresh-create, `hermes
+# update`'s all-profile sync, the web dashboard) skip bundled-skill seeding
+# for that profile.  The user can still install skills manually via
+# `hermes skills install` or drop SKILL.md files into the profile's skills/.
+# Delete the marker file to opt back in.
+NO_BUNDLED_SKILLS_MARKER = ".no-bundled-skills"
+
+
+def has_bundled_skills_opt_out(profile_dir: Path) -> bool:
+    """Return True if the profile opted out of bundled-skill seeding."""
+    try:
+        return (profile_dir / NO_BUNDLED_SKILLS_MARKER).exists()
+    except OSError:
+        return False
+

 def _clone_all_copytree_ignore(source_dir: Path):
    """Ignore ``profiles/`` at the root of *source_dir* only.
@@ -427,6 +443,7 @@ def create_profile(
    clone_all: bool = False,
    clone_config: bool = False,
    no_alias: bool = False,
+    no_skills: bool = False,
 ) -> Path:
    """Create a new profile directory.

@@ -444,12 +461,22 @@ def create_profile(
        skills, and selected profile identity files from the source profile.
    no_alias:
        If True, skip wrapper script creation.
+    no_skills:
+        If True, create an empty profile with no bundled skills, and write
+        a marker file so ``hermes update`` skips re-seeding this profile's
+        skills. Mutually exclusive with ``clone_config``/``clone_all`` (those
+        explicitly copy skills from the source).

    Returns
    -------
    Path
        The newly created profile directory.
    """
+    if no_skills and (clone_config or clone_all):
+        raise ValueError(
+            "--no-skills is mutually exclusive with --clone / --clone-all "
+            "(cloning explicitly copies skills from the source profile)."
+        )
    canon = normalize_profile_name(name)
    validate_profile_name(canon)

@@ -527,6 +554,19 @@ def create_profile(
        except Exception:
            pass  # best-effort — don't fail profile creation over this

+    # Write the opt-out marker so seed_profile_skills() and `hermes update`'s
+    # all-profile sync loop both skip this profile for bundled-skill seeding.
+    if no_skills:
+        try:
+            (profile_dir / NO_BUNDLED_SKILLS_MARKER).write_text(
+                "This profile opted out of bundled-skill seeding "
+                "(`hermes profile create --no-skills`).\n"
+                "Delete this file to re-enable sync on the next `hermes update`.\n",
+                encoding="utf-8",
+            )
+        except OSError:
+            pass  # best-effort — the feature still works via the empty skills/ dir
+
    return profile_dir


@@ -535,7 +575,19 @@ def seed_profile_skills(profile_dir: Path, quiet: bool = False) -> Optional[dict

    Uses subprocess because sync_skills() caches HERMES_HOME at module level.
    Returns the sync result dict, or None on failure.
+
+    Profiles that opted out of bundled skills (via ``hermes profile create
+    --no-skills`` — which writes ``.no-bundled-skills`` to the profile root)
+    are skipped and get an empty-result dict so callers can report
+    "opted out" instead of "failed".
    """
+    if has_bundled_skills_opt_out(profile_dir):
+        return {
+            "copied": [],
+            "updated": [],
+            "user_modified": [],
+            "skipped_opt_out": True,
+        }
    project_root = Path(__file__).parent.parent.resolve()
    try:
        result = subprocess.run(
@@ -319,9 +319,10 @@ def _try_resolve_from_custom_pool(
    base_url: str,
    provider_label: str,
    api_mode_override: Optional[str] = None,
+    provider_name: Optional[str] = None,
 ) -> Optional[Dict[str, Any]]:
    """Check if a credential pool exists for a custom endpoint and return a runtime dict if so."""
-    pool_key = get_custom_provider_pool_key(base_url)
+    pool_key = get_custom_provider_pool_key(base_url, provider_name=provider_name)
    if not pool_key:
        return None
    try:
@@ -521,7 +522,7 @@ def _resolve_named_custom_runtime(
        return None

    # Check if a credential pool exists for this custom endpoint
-    pool_result = _try_resolve_from_custom_pool(base_url, "custom", custom_provider.get("api_mode"))
+    pool_result = _try_resolve_from_custom_pool(base_url, "custom", custom_provider.get("api_mode"), provider_name=custom_provider.get("name"))
    if pool_result:
        # Propagate the model name even when using pooled credentials —
        # the pool doesn't know about the custom_providers model field.
@@ -640,8 +641,11 @@ def _resolve_openrouter_runtime(

    # For custom endpoints, check if a credential pool exists
    if effective_provider == "custom" and base_url:
+        # Pass requested_provider so pool lookup prefers name match over base_url,
+        # fixing credential mix-ups when multiple custom providers share a base_url.
        pool_result = _try_resolve_from_custom_pool(
            base_url, effective_provider, _parse_api_mode(model_cfg.get("api_mode")),
+            provider_name=requested_provider if requested_norm != "custom" else None,
        )
        if pool_result:
            return pool_result
@@ -308,6 +308,23 @@ TOOL_CATEGORIES = {
                    {"key": "SEARXNG_URL", "prompt": "Your SearXNG instance URL (e.g., http://localhost:8080)", "url": "https://searxng.github.io/searxng/"},
                ],
            },
+            {
+                "name": "Brave Search (Free Tier)",
+                "badge": "free tier · search only",
+                "tag": "2,000 queries/mo free — search only (pair with any extract provider)",
+                "web_backend": "brave-free",
+                "env_vars": [
+                    {"key": "BRAVE_SEARCH_API_KEY", "prompt": "Brave Search subscription token", "url": "https://brave.com/search/api/"},
+                ],
+            },
+            {
+                "name": "DuckDuckGo (ddgs)",
+                "badge": "free · no key · search only",
+                "tag": "Search via the ddgs Python package — no API key (pair with any extract provider)",
+                "web_backend": "ddgs",
+                "env_vars": [],
+                "post_setup": "ddgs",
+            },
        ],
    },
    "image_gen": {
@@ -669,6 +686,32 @@ def _run_post_setup(post_setup_key: str):
        _print_info("    Full voice list: https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/VOICES.md")
        _print_info("    Switch voices by setting tts.piper.voice in ~/.hermes/config.yaml")

+    elif post_setup_key == "ddgs":
+        try:
+            __import__("ddgs")
+            _print_success("    ddgs is already installed")
+        except ImportError:
+            import subprocess
+            _print_info("    Installing ddgs (DuckDuckGo search package)...")
+            try:
+                result = subprocess.run(
+                    [sys.executable, "-m", "pip", "install", "-U", "ddgs", "--quiet"],
+                    capture_output=True, text=True, timeout=300,
+                )
+                if result.returncode == 0:
+                    _print_success("    ddgs installed")
+                else:
+                    _print_warning("    ddgs install failed:")
+                    _print_info(f"      {result.stderr.strip()[:300]}")
+                    _print_info("    Run manually: python -m pip install -U ddgs")
+                    return
+            except subprocess.TimeoutExpired:
+                _print_warning("    ddgs install timed out (>5min)")
+                _print_info("    Run manually: python -m pip install -U ddgs")
+                return
+        _print_info("    No API key required. DuckDuckGo enforces server-side rate limits.")
+        _print_info("    Pair with an extract provider if you also need web_extract.")
+
    elif post_setup_key == "spotify":
        # Run the full `hermes auth spotify` flow — if the user has no
        # client_id yet, this drops them into the interactive wizard
@@ -52,7 +52,7 @@ from gateway.status import get_running_pid, read_runtime_status
 try:
    from fastapi import FastAPI, HTTPException, Request, WebSocket, WebSocketDisconnect
    from fastapi.middleware.cors import CORSMiddleware
-    from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+    from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, Response
    from fastapi.staticfiles import StaticFiles
    from pydantic import BaseModel
 except ImportError:
@@ -1877,8 +1877,8 @@ async def _start_device_code_flow(provider_id: str) -> Dict[str, Any]:
            name=f"oauth-codex-{sid[:6]}",
        ).start()
        # Block briefly until the worker has populated the user_code, OR error.
-        deadline = time.time() + 10
-        while time.time() < deadline:
+        deadline = time.monotonic() + 10
+        while time.monotonic() < deadline:
            with _oauth_sessions_lock:
                s = _oauth_sessions.get(sid)
            if s and (s.get("user_code") or s["status"] != "pending"):
@@ -2012,10 +2012,10 @@ def _codex_full_login_worker(session_id: str) -> None:
            sess["expires_at"] = time.time() + sess["expires_in"]

        # Step 2: poll until authorized
-        deadline = time.time() + sess["expires_in"]
+        deadline = time.monotonic() + sess["expires_in"]
        code_resp = None
        with httpx.Client(timeout=httpx.Timeout(15.0)) as client:
-            while time.time() < deadline:
+            while time.monotonic() < deadline:
                time.sleep(poll_interval)
                poll = client.post(
                    f"{issuer}/api/accounts/deviceauth/token",
@@ -2173,6 +2173,83 @@ async def cancel_oauth_session(session_id: str, request: Request):
 # ---------------------------------------------------------------------------


+
+def _session_latest_descendant(session_id: str):
+    """Resolve a session id to the newest child leaf session.
+
+    /model may create child sessions. Dashboard refresh should continue the
+    newest child instead of reopening the old parent.
+    """
+    from hermes_state import SessionDB
+
+    def row_get(row, key, index):
+        if isinstance(row, dict):
+            return row.get(key)
+        try:
+            return row[key]
+        except Exception:
+            try:
+                return row[index]
+            except Exception:
+                return None
+
+    db = SessionDB()
+    try:
+        sid = db.resolve_session_id(session_id)
+        if not sid or not db.get_session(sid):
+            return None, []
+
+        conn = (
+            getattr(db, "conn", None)
+            or getattr(db, "_conn", None)
+            or getattr(db, "connection", None)
+            or getattr(db, "_connection", None)
+        )
+
+        rows = []
+        if conn is not None:
+            raw_rows = conn.execute(
+                "SELECT id, parent_session_id, started_at FROM sessions"
+            ).fetchall()
+            for row in raw_rows:
+                rows.append({
+                    "id": row_get(row, "id", 0),
+                    "parent_session_id": row_get(row, "parent_session_id", 1),
+                    "started_at": row_get(row, "started_at", 2),
+                })
+        else:
+            rows = db.list_sessions_rich(limit=10000, offset=0)
+
+        children = {}
+        for row in rows:
+            rid = row.get("id")
+            parent = row.get("parent_session_id")
+            if rid and parent:
+                children.setdefault(parent, []).append(row)
+
+        def started(row):
+            try:
+                return float(row.get("started_at") or 0)
+            except Exception:
+                return 0.0
+
+        current = sid
+        path = [sid]
+        seen = {sid}
+
+        while children.get(current):
+            candidates = [r for r in children[current] if r.get("id") not in seen]
+            if not candidates:
+                break
+            candidates.sort(key=started, reverse=True)
+            current = candidates[0]["id"]
+            path.append(current)
+            seen.add(current)
+
+        return current, path
+    finally:
+        db.close()
+
@app.get("/api/sessions/{session_id}")
 async def get_session_detail(session_id: str):
    from hermes_state import SessionDB
@@ -2187,6 +2264,19 @@ async def get_session_detail(session_id: str):
        db.close()


+
+@app.get("/api/sessions/{session_id}/latest-descendant")
+async def get_session_latest_descendant(session_id: str):
+    latest, path = _session_latest_descendant(session_id)
+    if not latest:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return {
+        "requested_session_id": path[0] if path else session_id,
+        "session_id": latest,
+        "path": path,
+        "changed": bool(path and latest != path[0]),
+    }
+
@app.get("/api/sessions/{session_id}/messages")
 async def get_session_messages(session_id: str):
    from hermes_state import SessionDB
@@ -2366,6 +2456,7 @@ async def delete_cron_job(job_id: str):
 class ProfileCreate(BaseModel):
    name: str
    clone_from_default: bool = False
+    no_skills: bool = False


 class ProfileRename(BaseModel):
@@ -2471,11 +2562,13 @@ async def create_profile_endpoint(body: ProfileCreate):
            name=body.name,
            clone_from="default" if body.clone_from_default else None,
            clone_config=body.clone_from_default,
+            no_skills=body.no_skills,
        )
        # Match the CLI's profile-create flow: fresh named profiles get the
        # bundled skills installed. When cloning from default, create_profile()
        # has already copied the source profile's skills, including any
-        # user-installed skills.
+        # user-installed skills. When no_skills=True, create_profile() wrote
+        # the opt-out marker and seed_profile_skills() will no-op.
        if not body.clone_from_default:
            profiles_mod.seed_profile_skills(path, quiet=True)

@@ -2946,8 +3039,18 @@ def _resolve_chat_argv(
    argv, cwd = _make_tui_argv(PROJECT_ROOT / "ui-tui", tui_dev=False)
    env = os.environ.copy()
    env.setdefault("NODE_ENV", "production")
+    # Browser-embedded chat should prefer stable wheel-based scrollback over
+    # native terminal mouse tracking. When mouse tracking is enabled, wheel
+    # events are consumed by the TUI and forwarded as terminal input, which
+    # makes browser-side transcript scrolling feel broken. Keep the terminal
+    # build unchanged for native CLI usage; only disable mouse tracking for
+    # the dashboard PTY path.
+    env.setdefault("HERMES_TUI_DISABLE_MOUSE", "1")

    if resume:
+        latest_resume, _latest_path = _session_latest_descendant(resume)
+        if latest_resume:
+            resume = latest_resume
        env["HERMES_TUI_RESUME"] = resume

    if sidecar_url:
@@ -3205,12 +3308,42 @@ async def events_ws(ws: WebSocket) -> None:
                    _event_channels.pop(channel, None)


+def _normalise_prefix(raw: Optional[str]) -> str:
+    """Normalise an X-Forwarded-Prefix header value.
+
+    Returns a string like ``"/hermes"`` (no trailing slash) or ``""`` when
+    no prefix is set / the header is malformed. We deliberately reject
+    anything containing ``..`` or non-printable bytes so a hostile proxy
+    can't inject HTML via the prefix.
+    """
+    if not raw:
+        return ""
+    p = raw.strip()
+    if not p:
+        return ""
+    if not p.startswith("/"):
+        p = "/" + p
+    p = p.rstrip("/")
+    if "//" in p or ".." in p or any(c in p for c in ('"', "'", "<", ">", " ", "\n", "\r", "\t")):
+        return ""
+    if len(p) > 64:
+        return ""
+    return p
+
+
 def mount_spa(application: FastAPI):
    """Mount the built SPA. Falls back to index.html for client-side routing.

    The session token is injected into index.html via a ``<script>`` tag so
    the SPA can authenticate against protected API endpoints without a
    separate (unauthenticated) token-dispensing endpoint.
+
+    When served behind a path-prefix reverse proxy (e.g.
+    ``mission-control.tilos.com/hermes/*`` -> local Caddy -> :9119), the
+    proxy injects ``X-Forwarded-Prefix: /hermes`` on every request. We
+    rewrite the served ``index.html`` so absolute asset URLs (``/assets/...``)
+    and the SPA's runtime ``__HERMES_BASE_PATH__`` honour that prefix
+    without rebuilding the bundle.
    """
    if not WEB_DIST.exists():
        @application.get("/{full_path:path}")
@@ -3223,24 +3356,62 @@ def mount_spa(application: FastAPI):

    _index_path = WEB_DIST / "index.html"

-    def _serve_index():
-        """Return index.html with the session token injected."""
+    def _serve_index(prefix: str = ""):
+        """Return index.html with the session token + base-path injected.
+
+        ``prefix`` is the normalised ``X-Forwarded-Prefix`` (e.g. ``/hermes``)
+        or empty string when served at root.
+        """
        html = _index_path.read_text()
        chat_js = "true" if _DASHBOARD_EMBEDDED_CHAT_ENABLED else "false"
        token_script = (
            f'<script>window.__HERMES_SESSION_TOKEN__="{_SESSION_TOKEN}";'
-            f"window.__HERMES_DASHBOARD_EMBEDDED_CHAT__={chat_js};</script>"
+            f"window.__HERMES_DASHBOARD_EMBEDDED_CHAT__={chat_js};"
+            f'window.__HERMES_BASE_PATH__="{prefix}";</script>'
        )
+        if prefix:
+            # Rewrite absolute asset URLs baked into the Vite build so the
+            # browser fetches them through the same proxy prefix.
+            html = html.replace('href="/assets/', f'href="{prefix}/assets/')
+            html = html.replace('src="/assets/', f'src="{prefix}/assets/')
+            html = html.replace('href="/favicon.ico"', f'href="{prefix}/favicon.ico"')
+            html = html.replace('href="/fonts/', f'href="{prefix}/fonts/')
+            html = html.replace('href="/ds-assets/', f'href="{prefix}/ds-assets/')
+            html = html.replace('src="/ds-assets/', f'src="{prefix}/ds-assets/')
        html = html.replace("</head>", f"{token_script}</head>", 1)
        return HTMLResponse(
            html,
            headers={"Cache-Control": "no-store, no-cache, must-revalidate"},
        )

+    # When served behind a path-prefix proxy, the built CSS contains
+    # absolute ``url(/fonts/...)`` and ``url(/ds-assets/...)`` references.
+    # Browsers resolve those against the document origin, which means
+    # under ``/hermes`` they'd hit ``mission-control.tilos.com/fonts/...``
+    # (the MC Pages app), not the Hermes backend. Intercept CSS asset
+    # requests BEFORE the StaticFiles mount and rewrite the absolute paths
+    # when a prefix is in play.
+    @application.get("/assets/{filename}.css")
+    async def serve_css(filename: str, request: Request):
+        css_path = WEB_DIST / "assets" / f"{filename}.css"
+        if not css_path.is_file() or not css_path.resolve().is_relative_to(
+            WEB_DIST.resolve()
+        ):
+            return JSONResponse({"error": "not found"}, status_code=404)
+        prefix = _normalise_prefix(request.headers.get("x-forwarded-prefix"))
+        css = css_path.read_text()
+        if prefix:
+            for asset_dir in ("/fonts/", "/fonts-terminal/", "/ds-assets/", "/assets/"):
+                css = css.replace(f"url({asset_dir}", f"url({prefix}{asset_dir}")
+                css = css.replace(f"url(\"{asset_dir}", f"url(\"{prefix}{asset_dir}")
+                css = css.replace(f"url('{asset_dir}", f"url('{prefix}{asset_dir}")
+        return Response(content=css, media_type="text/css")
+
    application.mount("/assets", StaticFiles(directory=WEB_DIST / "assets"), name="assets")

    @application.get("/{full_path:path}")
-    async def serve_spa(full_path: str):
+    async def serve_spa(full_path: str, request: Request):
+        prefix = _normalise_prefix(request.headers.get("x-forwarded-prefix"))
        file_path = WEB_DIST / full_path
        # Prevent path traversal via url-encoded sequences (%2e%2e/)
        if (
@@ -3250,7 +3421,7 @@ def mount_spa(application: FastAPI):
            and file_path.is_file()
        ):
            return FileResponse(file_path)
-        return _serve_index()
+        return _serve_index(prefix)


 # ---------------------------------------------------------------------------
@@ -612,6 +612,11 @@ class SessionDB:
        the caller already holds cumulative totals (gateway path, where the
        cached agent accumulates across messages).
        """
+        # Ensure the session row exists so the UPDATE doesn't silently affect
+        # 0 rows.  Under concurrent load (cron + kanban + delegate_task) the
+        # initial create_session() may have failed due to SQLite locking.
+        # INSERT OR IGNORE is cheap and idempotent.
+        self._insert_session_row(session_id, "unknown", model=model)
        if absolute:
            sql = """UPDATE sessions SET
                   input_tokens = ?,
@@ -115,6 +115,25 @@ def _load_channel_directory() -> dict:
        return {}


+def _coerce_int(
+    value,
+    *,
+    default: int,
+    minimum: int,
+    maximum: int,
+) -> int:
+    """Coerce value to int with fallback and clamping.
+
+    Used at MCP tool boundaries to handle invalid types from external clients.
+    Returns default if value cannot be converted to int.
+    """
+    try:
+        coerced = int(value)
+    except (TypeError, ValueError):
+        coerced = default
+    return max(minimum, min(coerced, maximum))
+
+
 def _extract_message_content(msg: dict) -> str:
    """Extract text content from a message, handling multi-part content."""
    content = msg.get("content", "")
@@ -465,6 +484,7 @@ def create_mcp_server(event_bridge: Optional[EventBridge] = None) -> "FastMCP":
            limit: Maximum number of conversations to return (default 50)
            search: Optional text to filter conversations by name
        """
+        limit = _coerce_int(limit, default=50, minimum=1, maximum=200)
        entries = _load_sessions_index()
        conversations = []

@@ -552,6 +572,7 @@ def create_mcp_server(event_bridge: Optional[EventBridge] = None) -> "FastMCP":
            session_key: The session key from conversations_list
            limit: Maximum number of messages to return (default 50, most recent)
        """
+        limit = _coerce_int(limit, default=50, minimum=1, maximum=200)
        entries = _load_sessions_index()
        entry = entries.get(session_key)
        if not entry:
@@ -664,6 +685,8 @@ def create_mcp_server(event_bridge: Optional[EventBridge] = None) -> "FastMCP":
            session_key: Optional filter to one conversation
            limit: Maximum events to return (default 20)
        """
+        after_cursor = _coerce_int(after_cursor, default=0, minimum=0, maximum=10**18)
+        limit = _coerce_int(limit, default=20, minimum=1, maximum=200)
        result = bridge.poll_events(
            after_cursor=after_cursor,
            session_key=session_key,
@@ -689,10 +712,17 @@ def create_mcp_server(event_bridge: Optional[EventBridge] = None) -> "FastMCP":
            session_key: Optional filter to one conversation
            timeout_ms: Maximum wait time in milliseconds (default 30000)
        """
+        after_cursor = _coerce_int(after_cursor, default=0, minimum=0, maximum=10**18)
+        timeout_ms = _coerce_int(
+            timeout_ms,
+            default=30000,
+            minimum=0,
+            maximum=300000,
+        )  # Cap at 5 minutes
        event = bridge.wait_for_event(
            after_cursor=after_cursor,
            session_key=session_key,
-            timeout_ms=min(timeout_ms, 300000),  # Cap at 5 minutes
+            timeout_ms=timeout_ms,
        )
        if event:
            return json.dumps({"event": event}, indent=2)
@@ -772,7 +802,7 @@ def create_mcp_server(event_bridge: Optional[EventBridge] = None) -> "FastMCP":
            return json.dumps({"count": len(targets), "channels": targets}, indent=2)

        channels = []
-        for plat, entries_list in directory.items():
+        for plat, entries_list in directory.get("platforms", {}).items():
            if platform and plat.lower() != platform.lower():
                continue
            if isinstance(entries_list, list):
@@ -730,8 +730,8 @@ def handle_function_call(
                    session_id=session_id or "",
                    tool_call_id=tool_call_id or "",
                )
-            except Exception:
-                pass
+            except Exception as _hook_err:
+                logger.debug("pre_tool_call hook error: %s", _hook_err)

            if block_message is not None:
                return json.dumps({"error": block_message}, ensure_ascii=False)
@@ -782,8 +782,8 @@ def handle_function_call(
                tool_call_id=tool_call_id or "",
                duration_ms=duration_ms,
            )
-        except Exception:
-            pass
+        except Exception as _hook_err:
+            logger.debug("post_tool_call hook error: %s", _hook_err)

        # Generic tool-result canonicalization seam: plugins receive the
        # final result string (JSON, usually) and may replace it by
@@ -807,8 +807,8 @@ def handle_function_call(
                if isinstance(hook_result, str):
                    result = hook_result
                    break
-        except Exception:
-            pass
+        except Exception as _hook_err:
+            logger.debug("transform_tool_result hook error: %s", _hook_err)

        return result

@@ -0,0 +1,432 @@
+---
+name: 3-statement-model
+description: Build fully-integrated 3-statement models (IS, BS, CF) in Excel with working capital schedules, D&A roll-forwards, debt schedule, and the plugs that make cash and retained earnings tie. Pairs with excel-author.
+version: 1.0.0
+author: Anthropic (adapted by Nous Research)
+license: Apache-2.0
+metadata:
+  hermes:
+    tags: [finance, three-statement, income-statement, balance-sheet, cash-flow, excel, openpyxl, modeling]
+    related_skills: [excel-author, pptx-author, dcf-model, lbo-model]
+---
+
+## Environment
+
+This skill assumes **headless openpyxl** — you are producing an .xlsx file on disk.
+Follow the `excel-author` skill's conventions for cell coloring, formulas, named ranges, and sensitivity tables.
+Recalculate before delivery: `python /path/to/excel-author/scripts/recalc.py ./out/model.xlsx`.
+
+# 3-Statement Financial Model Template Completion
+
+Complete and populate integrated financial model templates with proper linkages between Income Statement, Balance Sheet, and Cash Flow Statement.
+
+## ⚠️ CRITICAL PRINCIPLES — Read Before Populating Any Template
+
+**Formulas over hardcodes (non-negotiable):**
+- Every projection cell, roll-forward, linkage, and subtotal MUST be an Excel formula — never a pre-computed value
+- When using Python/openpyxl: write formula strings (`ws["D15"] = "=D14*(1+Assumptions!$B$5)"`), NOT computed results (`ws["D15"] = 12500`)
+- The ONLY cells that should contain hardcoded numbers are: (1) historical actuals, (2) assumption drivers in the Assumptions tab
+- If you find yourself computing a value in Python and writing the result to a cell — STOP. Write the formula instead.
+- Why: the model must flex when scenarios toggle or assumptions change. Hardcodes break every downstream integrity check silently.
+
+**Verify step-by-step with the user:**
+1. **After mapping the template** → show the user which tabs/sections you've identified and confirm before touching any cells
+2. **After populating historicals** → show the user the historical block and confirm values/periods match source data
+3. **After building IS projections** → run the subtotal checks, show the user the projected IS, confirm before moving to BS
+4. **After building BS** → show the user the balance check (Assets = L+E) for every period, confirm before moving to CF
+5. **After building CF** → show the user the cash tie-out (CF ending cash = BS cash), confirm before finalizing
+6. **Do NOT populate the entire model end-to-end and present it complete** — break at each statement, show the work, catch errors early
+
+## Formatting — Professional Blue/Grey Palette (Default unless template/user specifies otherwise)
+
+**Keep colors minimal.** Use only blues and greys for cell fills. Do NOT introduce greens, yellows, oranges, or multiple accent colors — a clean model uses restraint.
+
+| Element | Fill | Font |
+|---|---|---|
+| Section headers (IS / BS / CF titles) | Dark blue `#1F4E79` | White bold |
+| Column headers (FY2024A, FY2025E, etc.) | Light blue `#D9E1F2` | Black bold |
+| Input cells (historicals, assumption drivers) | Light grey `#F2F2F2` or white | Blue `#0000FF` |
+| Formula cells | White | Black |
+| Cross-tab links | White | Green `#008000` |
+| Check rows / key totals | Medium blue `#BDD7EE` | Black bold |
+
+**That's 3 blues + 1 grey + white.** If the template has its own color scheme, follow the template instead.
+
+Font color signals *what* a cell is (input/formula/link). Fill color signals *where* you are (header/data/check).
+
+## Model Structure
+
+### Identifying Template Tab Organization
+
+Templates vary in their tab naming conventions and organization. Before populating, review all tabs to understand the template's structure. Below are common tab names and their typical contents:
+
+| Common Tab Names | Contents to Look For |
+|------------------|----------------------|
+| IS, P&L, Income Statement | Income Statement |
+| BS, Balance Sheet | Balance Sheet |
+| CF, CFS, Cash Flow | Cash Flow Statement |
+| WC, Working Capital | Working Capital Schedule |
+| DA, D&A, Depreciation, PP&E | Depreciation & Amortization Schedule |
+| Debt, Debt Schedule | Debt Schedule |
+| NOL, Tax, DTA | Net Operating Loss Schedule |
+| Assumptions, Inputs, Drivers | Driver assumptions and inputs |
+| Checks, Audit, Validation | Error-checking dashboard |
+
+**Template Review Checklist**
+- Identify which tabs exist in the template (not all templates include every schedule)
+- Note any template-specific tabs not listed above
+- Understand tab dependencies (e.g., which schedules feed into the main statements)
+- Locate input cells vs. formula cells on each tab
+
+### Understanding Template Structure
+
+Before populating a template, familiarize yourself with its existing layout to ensure data is entered in the correct locations and formulas remain intact.
+
+**Identifying Row Structure**
+- Locate the model title at top of each tab
+- Identify section headers and their visual separation
+- Find the units row indicating $ millions, %, x, etc.
+- Note column headers distinguishing Actuals vs. Estimates periods
+- Confirm period labels (e.g., FY2024A, FY2025E)
+- Identify input cells vs. formula cells (typically distinguished by font color)
+
+**Identifying Column Structure**
+- Confirm line item labels in leftmost column
+- Verify historical years precede projection years
+- Note the visual border separating historical from projected periods
+- Check for consistent column order across all tabs
+
+**Working with Named Ranges**
+Templates often use named ranges for key inputs and outputs. Before entering data:
+- Review existing named ranges in the template (Formulas → Name Manager in Excel)
+- Common named ranges include: Revenue growth rates, cost percentages, key outputs (Net Income, EBITDA, Total Debt, Cash), scenario selector cell
+- Ensure inputs are entered in cells that feed into these named ranges
+
+### Projection Period
+- Templates typically project 5 years forward from last historical year
+- Verify historical (A) vs. projected (E) columns are clearly separated
+- Confirm columns use fiscal year notation (e.g., FY2024A, FY2025E)
+
+## Margin Analysis
+
+**Note: The following margin analysis should only be performed if prompted by the user or if the template explicitly requires it. If no prompt is given, skip this section.**
+
+Calculate and display profitability margins on the Income Statement (IS) tab to track operational efficiency and enable peer comparison.
+
+### Core Margins to Include
+
+| Margin | Formula | What It Measures |
+|--------|---------|------------------|
+| Gross Margin | Gross Profit / Revenue | Pricing power, production efficiency |
+| EBITDA Margin | EBITDA / Revenue | Core operating profitability |
+| EBIT Margin | EBIT / Revenue | Operating profitability after D&A |
+| Net Income Margin | Net Income / Revenue | Bottom-line profitability |
+
+### Income Statement Layout with Margins
+
+Display margin percentages directly below each profit line item:
+- Gross Margin % below Gross Profit
+- EBIT Margin % below EBIT
+- EBITDA Margin % below EBITDA
+- Net Income Margin % below Net Income
+
+## Credit Metrics
+
+**Note: The following Credit analysis should only be performed if prompted by the user or if the template explicitly requires it. If no prompt is given, skip this section.**
+
+Calculate and display credit/leverage metrics on the Balance Sheet (BS) tab to assess financial health, debt capacity, and covenant compliance.
+
+### Core Credit Metrics to Include
+
+| Metric | Formula | What It Measures |
+|--------|---------|------------------|
+| Total Debt / EBITDA | Total Debt / LTM EBITDA | Leverage multiple |
+| Net Debt / EBITDA | (Total Debt - Cash) / LTM EBITDA | Leverage net of cash |
+| Interest Coverage | EBITDA / Interest Expense | Ability to service debt |
+| Debt / Total Cap | Total Debt / (Total Debt + Equity) | Capital structure |
+| Debt / Equity | Total Debt / Total Equity | Financial leverage |
+| Current Ratio | Current Assets / Current Liabilities | Short-term liquidity |
+| Quick Ratio | (Current Assets - Inventory) / Current Liabilities | Immediate liquidity |
+
+### Credit Metric Hierarchy Checks
+
+Validate that Upside shows strongest credit profile:
+- Leverage: Upside < Base < Downside (lower is better)
+- Coverage: Upside > Base > Downside (higher is better)
+- Liquidity: Upside > Base > Downside (higher is better)
+
+### Covenant Compliance Tracking
+
+If debt covenants are known, add explicit compliance checks comparing actual metrics to covenant thresholds.
+
+## Scenario Analysis (Base / Upside / Downside)
+
+Use a scenario toggle (dropdown) in the Assumptions tab with CHOOSE or INDEX/MATCH formulas.
+
+| Scenario | Description |
+|----------|-------------|
+| Base Case | Management guidance or consensus estimates |
+| Upside Case | Above-guidance growth, margin expansion |
+| Downside Case | Below-trend growth, margin compression |
+
+**Key Drivers to Sensitize**: Revenue growth, Gross margin, SG&A %, DSO/DIO/DPO, CapEx %, Interest rate, Tax rate.
+
+**Scenario Audit Checks**: Toggle switches all statements, BS balances in all scenarios, Cash ties out, Hierarchy holds (Upside > Base > Downside for NI, EBITDA, FCF, margins).
+
+## SEC Filings Data Extraction
+
+If the template specifically requires pulling data from SEC filings (10-K, 10-Q), see [references/sec-filings.md](references/sec-filings.md) for detailed extraction guidance. This reference is only needed when populating templates with public company data from regulatory filings.
+
+## Completing Model Templates
+
+This section provides general guidance for completing any 3-statement financial model template while preserving existing formulas and ensuring data integrity.
+
+### Step 1: Analyze the Template Structure
+
+Before entering any data, thoroughly review the template to understand its architecture:
+
+**Identify Input vs. Formula Cells**
+- Look for visual cues (font color, cell shading) that distinguish input cells from formula cells
+- Common conventions: Blue font = inputs, Black font = formulas, Green font = links to other sheets
+- Use Excel's Trace Precedents/Dependents (Formulas → Trace Precedents) to understand cell relationships
+- Check for named ranges that may control key inputs (Formulas → Name Manager)
+
+**Map the Template's Flow**
+- Identify which tabs feed into others (e.g., Assumptions → IS → BS → CF)
+- Note any supporting schedules and their linkages to main statements
+- Document the template's specific line items and structure before populating
+
+### Step 2: Filling in Data Without Breaking Formulas
+
+**Golden Rules for Data Entry**
+
+| Rule | Description |
+|------|-------------|
+| Only edit input cells | Never overwrite cells containing formulas unless intentionally replacing the formula |
+| Preserve cell references | When copying data, use Paste Values (Ctrl+Shift+V) to avoid overwriting formulas with source formatting |
+| Match the template's units | Verify if template uses thousands, millions, or actual values before entering data |
+| Respect sign conventions | Follow the template's existing sign convention (e.g., expenses as positive or negative) |
+| Check for circular references | If the template uses iterative calculations, ensure Enable Iterative Calculation is turned on |
+
+**Safe Data Entry Process**
+1. Identify the exact cells designated for input (usually highlighted or labeled)
+2. Enter historical data first, then verify formulas are calculating correctly for those periods
+3. Enter assumption drivers that feed forecast calculations
+4. Review calculated outputs to confirm formulas are working as intended
+5. If a formula cell must be modified, document the original formula before making changes
+
+**Handling Pre-Built Formulas**
+- If formulas reference cells you haven't populated yet, expect temporary errors (#REF!, #DIV/0!) until all inputs are complete
+- When formulas produce unexpected results, trace precedents to identify missing or incorrect inputs
+- Never delete rows/columns without checking for formula dependencies across all tabs
+
+### Step 3: Validating Formulas
+
+**Formula Integrity Checks**
+
+Before relying on template outputs, validate that formulas are functioning correctly:
+
+| Check Type | Method |
+|------------|--------|
+| Trace precedents | Select a formula cell → Formulas → Trace Precedents to verify it references correct inputs |
+| Trace dependents | Verify key inputs flow to expected output cells |
+| Evaluate formula | Use Formulas → Evaluate Formula to step through complex calculations |
+| Check for hardcodes | Projection formulas should reference assumptions, not contain hardcoded values |
+| Test with known values | Input simple test values to verify formulas produce expected results |
+| Cross-tab consistency | Ensure the same formula logic applies across all projection periods |
+
+**Common Formula Issues to Watch For**
+- Mixed absolute/relative references causing incorrect results when copied across periods
+- Broken links to external files or deleted ranges (#REF! errors)
+- Division by zero in early periods before revenue ramps (#DIV/0! errors)
+- Circular reference warnings (may be intentional for interest calculations)
+- Inconsistent formulas across projection columns (use Ctrl+\ to find differences)
+
+**Validating Cross-Tab Linkages**
+- Confirm values that appear on multiple tabs are linked (not duplicated)
+- Verify schedule totals tie to corresponding line items on main statements
+- Check that period labels align across all tabs
+
+### Step 4: Quality Checks by Sheet
+
+Perform these validation checks on each sheet after populating the template:
+
+**Income Statement (IS) Quality Checks**
+- Revenue figures match source data for historical periods
+- All expense line items sum to reported totals
+- Subtotals (Gross Profit, EBIT, EBT, Net Income) calculate correctly
+- Tax calculation logic is appropriate (handles losses correctly)
+- Forecast drivers reference assumptions tab (no hardcodes)
+- Period-over-period changes are directionally reasonable
+
+**Balance Sheet (BS) Quality Checks**
+- Assets = Liabilities + Equity for every period (primary check)
+- Cash balance matches Cash Flow Statement ending cash
+- Working capital accounts tie to supporting schedules (if applicable)
+- Retained Earnings rolls forward correctly: Prior RE + Net Income - Dividends +/- Adjustments = Ending RE
+- Debt balances tie to debt schedule (if applicable)
+- All balance sheet items have appropriate signs (assets positive, most liabilities positive)
+
+**Cash Flow Statement (CF) Quality Checks**
+- Net Income at top of CFO matches Income Statement Net Income
+- Non-cash add-backs (D&A, SBC, etc.) tie to their source schedules/statements
+- Working capital changes have correct signs (increase in asset = use of cash = negative)
+- CapEx ties to PP&E schedule or fixed asset roll-forward
+- Financing activities tie to changes in debt and equity accounts on BS
+- Ending Cash matches Balance Sheet Cash
+- Beginning Cash equals prior period Ending Cash
+
+**Supporting Schedule Quality Checks**
+- Opening balances equal prior period closing balances
+- Roll-forward logic is complete (Beginning + Additions - Deductions = Ending)
+- Schedule totals tie to main statement line items
+- Assumptions used in calculations match Assumptions tab
+
+### Step 5: Cross-Statement Integrity Checks
+
+After validating individual sheets, confirm the three statements are properly integrated:
+
+| Check | Formula | Expected Result |
+|-------|---------|-----------------|
+| Balance Sheet Balance | Assets - Liabilities - Equity | = 0 |
+| Cash Tie-Out | CF Ending Cash - BS Cash | = 0 |
+| Net Income Link | IS Net Income - CF Starting Net Income | = 0 |
+| Retained Earnings | Prior RE + NI - Dividends - BS Ending RE | = 0 (adjust for SBC/other items as needed) |
+
+### Step 6: Final Review
+
+Before considering the model complete:
+- Toggle through all scenarios (if applicable) to verify checks pass in each case
+- Review all #REF!, #DIV/0!, #VALUE!, and #NAME? errors and resolve or document
+- Confirm all input cells have been populated (search for placeholder values)
+- Verify units are consistent across all tabs
+- Save a clean version before making any additional modifications
+
+## Model Validation and Audit
+
+This section consolidates all validation checks and audit procedures for completed templates.
+
+### Core Linkages (Must Always Hold)
+
+See [references/formulas.md](references/formulas.md) for all formula details.
+
+| Check | Formula | Expected Result |
+|-------|---------|-----------------|
+| Balance Sheet Balance | Assets - Liabilities - Equity | = 0 |
+| Cash Tie-Out | CF Ending Cash - BS Cash | = 0 |
+| Cash Monthly vs Annual | Closing Cash (Monthly) - Closing Cash (Annual) | = 0 |
+| Net Income Link | IS Net Income - CF Starting Net Income | = 0 |
+| Retained Earnings | Prior RE + NI + SBC - Dividends - BS Ending RE | = 0 |
+| Equity Financing | ΔCommon Stock/APIC (BS) - Equity Issuance (CFF) | = 0 |
+| Year 0 Equity | Equity Raised (Year 0) - Beginning Equity Capital (Year 1) | = 0 |
+
+### Sign Convention Reference
+
+| Statement | Item | Sign Convention |
+|-----------|------|-----------------|
+| CFO | D&A, SBC | Positive (add-back) |
+| CFO | ΔAR (increase) | Negative (use of cash) |
+| CFO | ΔAP (increase) | Positive (source of cash) |
+| CFI | CapEx | Negative |
+| CFF | Debt issuance | Positive |
+| CFF | Debt repayments | Negative |
+| CFF | Dividends | Negative |
+
+### Circular Reference Handling
+
+Interest expense creates circularity: Interest → Net Income → Cash → Debt Balance → Interest
+
+Enable iterative calculation in Excel: File → Options → Formulas → Enable iterative calculation. Set maximum iterations to 100, maximum change to 0.001. Add a circuit breaker toggle in Assumptions tab.
+
+### Check Categories
+
+**Section 1: Currency Consistency**
+- Currency identified and documented in Assumptions
+- All tabs use consistent currency symbol and scale
+- Units row matches model currency
+
+**Section 2: Balance Sheet Integrity**
+- Assets = Liabilities + Equity (for each period)
+- Formula: Assets - Liabilities - Equity (must = 0)
+
+**Section 3: Cash Flow Integrity**
+- Cash ties to BS (CF Ending Cash = BS Cash)
+- Cash Monthly vs Annual: Closing Cash (Monthly) = Closing Cash (Annual)
+- NI ties to IS (CF Net Income = IS Net Income)
+- D&A ties to schedule
+- SBC ties to IS
+- ΔAR, ΔInventory, ΔAP tie to WC schedule
+- CapEx ties to DA schedule
+
+**Section 4: Retained Earnings**
+- RE roll-forward check: Prior RE + NI + SBC - Dividends = Ending RE
+- Show component breakdown for debugging
+
+**Section 5: Working Capital**
+- AR, Inventory, AP tie to BS
+- DSO, DIO, DPO reasonability checks (flag if outside normal ranges)
+
+**Section 6: Debt Schedule**
+- Total Debt ties to BS (Current + LT Debt)
+- Interest calculation ties to IS
+
+**Section 6b: Equity Financing**
+- Equity issuance proceeds tie to BS Common Stock/APIC increase
+- Cash increase from equity = Equity account increase (must balance)
+- Equity Raise Tie-Out: ΔCommon Stock/APIC (BS) = Equity Issuance (CFF) (must = 0)
+- Year 0 Equity Tie-Out: Equity Raised (Year 0) = Beginning Equity Capital (Year 1)
+
+**Section 6c: NOL Schedule**
+- Beginning NOL (Year 1 / Formation) = 0 (new business starts with zero NOL)
+- NOL increases only when EBT < 0 (losses must be realized to generate NOL)
+- DTA ties to BS (NOL Schedule DTA = BS Deferred Tax Asset)
+- NOL utilization ≤ 80% of EBT (post-2017 federal limitation)
+- NOL balance is non-negative (cannot utilize more than available)
+- NOL generated only when EBT < 0
+- Tax expense = 0 when taxable income ≤ 0
+
+**Section 7: Scenario Hierarchy**
+- Absolute metrics: Upside > Base > Downside (NI, EBITDA, FCF)
+- Margins: Upside > Base > Downside (GM%, EBITDA%, NI%)
+- Credit metrics: Upside < Base < Downside for leverage (inverted)
+
+**Section 8: Formula Integrity**
+- COGS, S&M, G&A, R&D, SBC driven by % of Revenue (no hardcodes)
+- Consistent formulas across projection years
+- No #REF!, #DIV/0!, #VALUE! errors
+
+**Section 9: Credit Metric Thresholds**
+- Flag metrics as Green/Yellow/Red based on covenant thresholds
+- Summary of any red flags
+
+### Master Check Formula
+
+Aggregate all section statuses into a single master check:
+- If all sections pass → "✓ ALL CHECKS PASS"
+- If any section fails → "✗ ERRORS DETECTED - REVIEW BELOW"
+
+### Quick Debug Workflow
+
+When Master Status shows errors:
+1. Scroll to find red-highlighted sections
+2. Identify which check category has failures
+3. Navigate to source tab to investigate
+4. Fix the underlying issue
+5. Return to Checks tab to verify resolution
+
+
+## Data sources — MCP first, web fallback
+
+Many passages below say "use the S&P Kensho MCP / Daloopa MCP / FactSet MCP". Those are commercial financial-data MCPs from the original Cowork plugin context. In Hermes:
+
+- **If you have any structured financial-data MCP configured** (Hermes supports MCP — see `native-mcp` skill), prefer it for point-in-time comps, precedent transactions, and filings.
+- **Otherwise**, fall back to:
+  - `web_search` / `web_extract` against SEC EDGAR (`https://www.sec.gov/cgi-bin/browse-edgar`) for US filings
+  - Company IR pages for press releases, earnings decks
+  - `browser_navigate` for interactive data portals
+  - User-provided data (explicitly ask when the context doesn't have it)
+- **Never fabricate**. If a multiple, precedent, or filing number can't be sourced, flag the cell as `[UNSOURCED]` and surface it to the user.
+
+## Attribution
+
+This skill is adapted from Anthropic's Claude for Financial Services plugin suite (Apache-2.0). The Office-JS / Cowork live-Excel paths have been removed; this version targets headless openpyxl via the `excel-author` skill's conventions. Original: https://github.com/anthropics/financial-services
@@ -0,0 +1,118 @@
+# Formatting Standards Reference
+
+| Element | Format |
+|---------|--------|
+| Hard-coded inputs | Blue font |
+| Formulas | Black font |
+| Links to other sheets | Green font |
+| Check cells | Red if error, green if balanced |
+| Negative values | Parentheses, not minus signs |
+| Currency | No decimals for large figures, 2 decimals for per-share |
+| Percentages | 1 decimal place |
+| Headers | Bold, bottom border |
+| Units row | Include units row below headers ($ millions, %, etc.) |
+
+## Visual Separation Guidelines
+
+- Thin vertical border between historical and projected columns
+- Thick bottom border after section totals (e.g., Total Assets)
+- Single bottom border for subtotals
+- Double bottom border for grand totals
+
+## Total and Subtotal Row Formatting
+
+All total and subtotal rows must use **bold font formatting** for their numerical values to clearly distinguish aggregated figures from individual line items.
+
+### Income Statement (P&L) Tab
+| Row | Formatting |
+|-----|------------|
+| Gross Revenue | Bold |
+| Total Cost of Revenue | Bold |
+| Gross Profit | Bold |
+| Total SG&A | Bold |
+| EBITDA | Bold |
+| EBIT | Bold |
+| EBT | Bold |
+| Net Profit After Tax | Bold |
+
+### Balance Sheet Tab
+| Row | Formatting |
+|-----|------------|
+| Total Current Assets | Bold |
+| Total Non-Current Assets | Bold |
+| Total Other Assets | Bold |
+| Total Assets | Bold |
+| Total Current Liabilities | Bold |
+| Total Non-Current Liabilities | Bold |
+| Total Equity | Bold |
+| Total Liabilities and Equity | Bold |
+
+### Cash Flow Statement Tab
+| Row | Formatting |
+|-----|------------|
+| Cash Generated from Operations Before Working Capital Changes | Bold |
+| Total Working Capital Changes | Bold |
+| Net Cash Generated from Operations | Bold |
+| Net Cash Flow from Investing Activities | Bold |
+| Net Cash Flow from Financing Activities | Bold |
+| Closing Cash Balance | Bold |
+
+**Note:** This list is non-exhaustive. Apply bold formatting to any row that represents a total, subtotal, or summary calculation across the model.
+
+## Balance Sheet Check Row Formatting
+
+The Balance Sheet check row (below Total Liabilities and Equity) uses conditional number formatting that displays non-zero values in red. When the balance sheet balances correctly (check = 0), the values display in black or standard formatting.
+
+| Check Value | Font Color |
+|-------------|------------|
+| = 0 (balanced) | Black (standard) |
+| ≠ 0 (error) | Red |
+
+**Implementation:** Apply custom number format `[Red][<>0]0.00;[Red][<>0](0.00);0.00` or use Excel conditional formatting with the rule "Cell Value ≠ 0" → Red font.
+
+## Margin Row Formatting
+
+| Element | Format |
+|---------|--------|
+| Margin % rows | Indent, italics, 1 decimal place |
+| Positive trend | No special formatting (or subtle green) |
+| Negative trend | Flag for review (subtle yellow) |
+| Below peer average | Consider highlighting for discussion |
+
+## Credit Metric Formatting
+
+| Element | Format |
+|---------|--------|
+| Leverage multiples | 1 decimal with "x" suffix (e.g., 2.5x) |
+| Percentages | 1 decimal with "%" suffix |
+| Net Debt negative | Parentheses, indicates net cash position |
+| Section header | Bold, "CREDIT METRICS" |
+| Separator line | Thin border above credit metrics section |
+
+## Credit Metric Threshold Colors
+
+| Metric | Green | Yellow | Red |
+|--------|-------|--------|-----|
+| Total Debt / EBITDA | < 2.5x | 2.5x-4.0x | > 4.0x |
+| Net Debt / EBITDA | < 2.0x | 2.0x-3.5x | > 3.5x |
+| Interest Coverage | > 4.0x | 2.5x-4.0x | < 2.5x |
+| Debt / Total Cap | < 40% | 40%-60% | > 60% |
+| Current Ratio | > 1.5x | 1.0x-1.5x | < 1.0x |
+| Quick Ratio | > 1.0x | 0.75x-1.0x | < 0.75x |
+
+## Conditional Formatting for Checks Tab
+
+- Cell contains pass indicator → Green fill
+- Cell contains fail indicator → Red fill
+- Cell contains warning → Yellow fill
+- Difference cells = 0 → Light green fill
+- Difference cells ≠ 0 → Light red fill
+
+## Margin Reasonability Flags
+
+- Gross Margin < 0% → ERROR: Review COGS
+- Gross Margin > 80% → WARNING: Verify revenue/COGS
+- EBITDA Margin < 0% → FLAG: Operating losses
+- EBITDA Margin > 50% → WARNING: Unusually high
+- Net Margin < 0% → FLAG: Net losses (may be acceptable in growth phase)
+- Net Margin > Gross Margin → ERROR: Formula issue
@@ -0,0 +1,292 @@
+# Formula Reference
+
+**IMPORTANT:** Use the formulas outlined in this reference document unless otherwise specified by the user.
+
+---
+
+## Core Linkages
+
+```
+Balance Sheet:        Assets = Liabilities + Equity
+Net Income:           IS Net Income → CF Operations (starting point)
+Cash Flow:            ΔCash = CFO + CFI + CFF
+Cash Tie-Out:         Ending Cash (CF) = Cash (BS Asset)
+Cash Monthly/Annual:  Closing Cash (Monthly) = Closing Cash (Annual)
+Retained Earnings:    Prior RE + Net Income - Dividends = Ending RE
+Equity Raise:         ΔCommon Stock/APIC (BS) = Equity Issuance (CFF)
+Year 0 Equity:        Equity Raised (Year 0) = Beginning Equity (Year 1)
+```
+
+## Gross Profit Calculation
+
+**IMPORTANT:** Gross Profit must be calculated from Net Revenue, not Gross Revenue.
+
+```
+Net Revenue - Cost of Revenue = Gross Profit
+```
+
+| Term | Definition |
+|------|------------|
+| Gross Revenue | Total revenue before any deductions |
+| Net Revenue | Gross Revenue - Returns - Allowances - Discounts |
+| Cost of Revenue | Direct costs attributable to production of goods/services sold |
+| Gross Profit | Net Revenue - Cost of Revenue |
+
+**Note:** Always use Net Revenue (also called "Net Sales" or simply "Revenue" on most financial statements) as the starting point for profitability calculations. Gross Revenue overstates the true top-line performance.
+
+## Margin Formulas
+
+```
+Gross Margin %      = Gross Profit / Net Revenue
+EBITDA              = EBIT + D&A  (or = Gross Profit - OpEx)
+EBITDA Margin %     = EBITDA / Net Revenue
+EBIT Margin %       = EBIT / Net Revenue
+Net Income Margin % = Net Income / Net Revenue
+```
+
+## Credit Metric Formulas
+
+```
+Total Debt            = Current Portion of Debt + Long-Term Debt
+Net Debt              = Total Debt - Cash
+Total Debt / EBITDA   = Total Debt / EBITDA (from IS)
+Net Debt / EBITDA     = Net Debt / EBITDA (from IS)
+Interest Coverage     = EBITDA / Interest Expense (from IS)
+Net Int Exp % Debt    = Net Interest Expense / Long-Term Debt
+Debt / Total Cap      = Total Debt / (Total Debt + Total Equity)
+Debt / Equity         = Total Debt / Total Equity
+Current Ratio         = Total Current Assets / Total Current Liabilities
+Quick Ratio           = (Total Current Assets - Inventory) / Total Current Liabilities
+```
+
+## Forecast Formulas (% of Net Revenue Method)
+
+```
+Cost of Revenue (Forecast) = Net Revenue × Cost of Revenue % Assumption
+S&M (Forecast)             = Net Revenue × S&M % Assumption
+G&A (Forecast)             = Net Revenue × G&A % Assumption
+R&D (Forecast)             = Net Revenue × R&D % Assumption
+SBC (Forecast)             = Net Revenue × SBC % Assumption
+```
+
+## Working Capital Formulas
+
+```
+Accounts Receivable
+  Prior AR
+  + Revenue (from IS)
+  - Cash Collections (plug)
+  = Ending AR
+  DSO = (AR / Revenue) × 365
+
+Inventory
+  Prior Inventory
+  + Purchases (plug)
+  - COGS (from IS)
+  = Ending Inventory
+  DIO = (Inventory / COGS) × 365
+
+Accounts Payable
+  Prior AP
+  + Purchases (from Inventory calc)
+  - Cash Payments (plug)
+  = Ending AP
+  DPO = (AP / COGS) × 365
+
+Net Working Capital = AR + Inventory - AP
+ΔWC = Current NWC - Prior NWC
+```
+
+## D&A Schedule Formulas
+
+```
+Beginning PP&E (Gross)
+ CapEx
+= Ending PP&E (Gross)
+
+Beginning Accumulated Depreciation
+ Depreciation Expense
+= Ending Accumulated Depreciation
+
+PP&E (Net) = Gross PP&E - Accumulated Depreciation
+```
+
+## Debt Schedule Formulas
+
+```
+Beginning Debt Balance
+ New Borrowings
+- Repayments
+= Ending Debt Balance
+
+Interest Expense = Avg Debt Balance × Interest Rate
+  (Use beginning balance to avoid circularity, or iterate if circular refs enabled)
+```
+
+## Retained Earnings Formula
+
+```
+Beginning Retained Earnings
+ Net Income (from IS)
+ Stock-Based Compensation (SBC) (from IS)
+- Dividends
+= Ending Retained Earnings
+```
+
+## NOL (Net Operating Loss) Schedule Formulas
+
+```
+NOL CARRYFORWARD SCHEDULE
+
+Beginning NOL Balance (Year 1 / Formation = 0)
+ NOL Generated (if EBT < 0, then ABS(EBT), else 0)
+- NOL Utilized (limited by taxable income and utilization cap)
+= Ending NOL Balance
+
+STARTING BALANCE RULE
+
+For a new business or first modeled period:
+  Beginning NOL Balance = 0
+  NOL can only increase through realized losses (EBT < 0)
+  NOL cannot be created from thin air or assumed
+
+NOL UTILIZATION CALCULATION
+
+Pre-Tax Income (EBT)
+  If EBT > 0:
+    NOL Available = Beginning NOL Balance
+    Utilization Limit = EBT × 80%  (post-2017 federal limit)
+    NOL Utilized = MIN(NOL Available, Utilization Limit)
+    Taxable Income = EBT - NOL Utilized
+  If EBT ≤ 0:
+    NOL Utilized = 0
+    Taxable Income = 0
+    NOL Generated = ABS(EBT)
+
+TAX CALCULATION WITH NOL
+
+Taxes Payable = MAX(0, Taxable Income × Tax Rate)
+  (Taxes cannot be negative; losses create NOL asset instead)
+
+DEFERRED TAX ASSET (DTA) FOR NOL
+
+DTA - NOL Carryforward = Ending NOL Balance × Tax Rate
+ΔDTA = Current DTA - Prior DTA
+  (Increase in DTA = non-cash benefit on CF)
+  (Decrease in DTA = non-cash expense on CF)
+```
+
+## Balance Sheet Structure
+
+```
+ASSETS
+  Cash (from CF ending cash)
+  Accounts Receivable (from WC)
+  Inventory (from WC)
+  Total Current Assets
+  
+  PP&E, Net (from DA)
+  Deferred Tax Asset - NOL (from NOL schedule)
+  Total Non-Current Assets
+  Total Assets
+
+LIABILITIES
+  Accounts Payable (from WC)
+  Current Portion of Debt (from Debt)
+  Total Current Liabilities
+  
+  Long-Term Debt (from Debt)
+  Total Liabilities
+
+EQUITY
+  Common Stock
+  Retained Earnings (from RE schedule)
+  Total Equity
+
+CHECK: Assets - Liabilities - Equity = 0
+```
+
+## Cash Flow Statement Structure
+
+```
+CASH FROM OPERATIONS (CFO)
+  Net Income (LINK: IS)
+  + D&A (LINK: DA schedule)
+  + Stock-Based Compensation (SBC) (LINK: IS or Assumptions)
+  - ΔDTA (Deferred Tax Asset) (LINK: NOL schedule; increase in DTA = use of cash)
+  - ΔAR (LINK: WC)
+  - ΔInventory (LINK: WC)
+  + ΔAP (LINK: WC)
+  = CFO
+
+CASH FROM INVESTING (CFI)
+  - CapEx (LINK: DA schedule)
+  = CFI
+
+CASH FROM FINANCING (CFF)
+  + Debt Issuance (LINK: Debt)
+  - Debt Repayment (LINK: Debt)
+  + Equity Issuance (LINK: BS Common Stock/APIC)
+  - Dividends (LINK: RE schedule)
+  = CFF
+
+Net Change in Cash = CFO + CFI + CFF
+Beginning Cash
+ Net Change in Cash
+= Ending Cash (LINK TO: BS Cash)
+```
+
+## Income Statement Structure
+
+```
+Net Revenue
+  Growth %
+(-) Cost of Revenue
+  % of Net Revenue
+────────────────
+Gross Profit (= Net Revenue - Cost of Revenue)
+  Gross Margin %
+
+(-) S&M
+  % of Net Revenue
+(-) G&A
+  % of Net Revenue
+(-) R&D
+  % of Net Revenue
+(-) D&A
+(-) SBC
+  % of Net Revenue
+────────────────
+EBIT
+  EBIT Margin %
+
+EBITDA
+  EBITDA Margin %
+
+(-) Interest Expense
+────────────────
+EBT (Pre-Tax Income)
+(-) NOL Utilization (from NOL schedule, reduces taxable income)
+────────────────
+Taxable Income
+(-) Taxes (Taxable Income × Tax Rate)
+────────────────
+Net Income
+  Net Income Margin %
+```
+
+## Check Formulas
+
+```
+BS Balance Check:       = Assets - Liabilities - Equity  (must = 0)
+Cash Tie-Out:           = BS Cash - CF Ending Cash       (must = 0)
+RE Roll-Forward:        = Prior RE + NI + SBC - Div - BS RE  (must = 0)
+DTA Tie-Out:            = NOL Schedule DTA - BS DTA      (must = 0)
+Equity Raise Tie-Out:   = ΔCommon Stock/APIC (BS) - Equity Issuance (CFF)  (must = 0)
+Year 0 Equity Tie-Out:  = Equity Raised (Year 0) - Beginning Equity (Year 1)  (must = 0)
+Cash Monthly vs Annual: = Closing Cash (Monthly) - Closing Cash (Annual)  (must = 0)
+NOL Utilization Cap:    = NOL Utilized ≤ EBT × 80%       (must be TRUE for post-2017)
+NOL Non-Negative:       = Ending NOL Balance ≥ 0         (must be TRUE)
+NOL Starting Balance:   = Beginning NOL (Year 1) = 0     (must be TRUE for new business)
+NOL Accumulation:       = NOL increases only when EBT < 0 (losses generate NOL)
+```
@@ -0,0 +1,125 @@
+# SEC Filings Data Extraction Reference
+
+**When to Use:** Only reference this file when a model template specifically requires pulling data from SEC filings (10-K, 10-Q). For templates that provide data directly or use other data sources, this reference is not needed.
+
+---
+
+## Extracting Data from SEC Filings (10-K / 10-Q)
+
+When populating a model template with public company data, extract financials directly from SEC filings.
+
+### Step 1: Locate the Filing
+
+1. Use SEC EDGAR: `https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=[TICKER]&type=10-K`
+2. For quarterly data, use `type=10-Q`
+
+### Step 2: Identify Filing Currency
+
+Before extracting data, identify the reporting currency:
+- Check the cover page or header for reporting currency
+- Look at statement headers (e.g., "in thousands of U.S. dollars")
+- Review Note 1 (Summary of Significant Accounting Policies)
+
+**Common Currency Indicators**
+
+| Indicator | Currency |
+|-----------|----------|
+| $, USD | US Dollar |
+| €, EUR | Euro |
+| £, GBP | British Pound |
+| ¥, JPY | Japanese Yen |
+| ¥, CNY, RMB | Chinese Yuan |
+| CHF | Swiss Franc |
+| CAD, C$ | Canadian Dollar |
+
+Set model currency to match filing; document in Assumptions tab.
+
+### Step 3: Navigate to Financial Statements
+
+Within the 10-K or 10-Q, locate:
+- **Item 8** (10-K) or **Item 1** (10-Q): Financial Statements
+- Key sections to extract:
+  - Consolidated Statements of Operations (Income Statement)
+  - Consolidated Balance Sheets
+  - Consolidated Statements of Cash Flows
+  - Notes to Financial Statements (for schedule details)
+
+### Step 4: Data Extraction Mapping
+
+**Income Statement (from Consolidated Statements of Operations)**
+
+| Filing Line Item | Model Line Item |
+|------------------|-----------------|
+| Net revenues / Net sales | Revenue |
+| Cost of goods sold | COGS |
+| Selling, general and administrative | SG&A |
+| Depreciation and amortization | D&A |
+| Interest expense, net | Interest Expense |
+| Income tax expense | Taxes |
+| Net income | Net Income |
+
+**Balance Sheet (from Consolidated Balance Sheets)**
+
+| Filing Line Item | Model Line Item |
+|------------------|-----------------|
+| Cash and cash equivalents | Cash |
+| Accounts receivable, net | AR |
+| Inventories | Inventory |
+| Property, plant and equipment, net | PP&E (Net) |
+| Total assets | Total Assets |
+| Accounts payable | AP |
+| Short-term debt / Current portion of LT debt | Current Debt |
+| Long-term debt | LT Debt |
+| Retained earnings | Retained Earnings |
+| Total stockholders' equity | Total Equity |
+
+**Cash Flow Statement (from Consolidated Statements of Cash Flows)**
+
+| Filing Line Item | Model Line Item |
+|------------------|-----------------|
+| Net income | Net Income |
+| Depreciation and amortization | D&A |
+| Changes in accounts receivable | ΔAR |
+| Changes in inventories | ΔInventory |
+| Changes in accounts payable | ΔAP |
+| Capital expenditures | CapEx |
+| Proceeds from issuance of common stock | Equity Issuance |
+| Proceeds from / Repayments of debt | Debt activity |
+| Dividends paid | Dividends |
+
+### Step 5: Extract Supporting Detail from Notes
+
+For schedules, pull from Notes to Financial Statements:
+- **Note: Debt** → Maturity schedule, interest rates, covenants
+- **Note: Property, Plant & Equipment** → Gross PP&E, accumulated depreciation, useful lives
+- **Note: Revenue** → Segment breakdowns, geographic splits
+- **Note: Leases** → Operating vs. finance lease obligations
+
+### Step 6: Historical Data Requirements
+
+Extract 3 years of historical data minimum:
+- 10-K provides 3 years of IS/CF, 2 years of BS
+- For 3rd year BS, pull from prior year's 10-K
+- Use 10-Qs to fill in quarterly granularity if needed
+
+### Data Extraction Checklist
+
+- Identify reporting currency and scale (thousands, millions)
+- 3 years historical Income Statement
+- 3 years historical Cash Flow Statement
+- 3 years historical Balance Sheet
+- Verify IS Net Income = CF starting Net Income (each year)
+- Verify BS Cash = CF Ending Cash (each year)
+- Extract debt maturity schedule from notes
+- Extract D&A detail or useful life assumptions
+- Note any non-recurring / one-time items to normalize
+
+### Handling Common Filing Variations
+
+| Variation | How to Handle |
+|-----------|---------------|
+| D&A embedded in COGS/SG&A | Pull D&A from Cash Flow Statement |
+| "Other" line items are material | Check notes for breakdown |
+| Restatements | Use restated figures, note in assumptions |
+| Fiscal year ≠ calendar year | Label with fiscal year end (e.g., FYE Jan 2025) |
+| Non-USD reporting currency | Adapt model currency to match filing |
@@ -0,0 +1,661 @@
+---
+name: comps-analysis
+description: Build comparable company analysis in Excel — operating metrics, valuation multiples, statistical benchmarking vs peer sets. Pairs with excel-author. Use for public-company valuation, IPO pricing, sector benchmarking, or outlier detection.
+version: 1.0.0
+author: Anthropic (adapted by Nous Research)
+license: Apache-2.0
+metadata:
+  hermes:
+    tags: [finance, valuation, comps, excel, openpyxl, modeling, investment-banking]
+    related_skills: [excel-author, pptx-author, dcf-model, lbo-model]
+---
+
+## Environment
+
+This skill assumes **headless openpyxl** — you are producing an .xlsx file on disk.
+Follow the `excel-author` skill's conventions for cell coloring, formulas, named ranges, and sensitivity tables.
+Recalculate before delivery: `python /path/to/excel-author/scripts/recalc.py ./out/model.xlsx`.
+
+# Comparable Company Analysis
+
+## ⚠️ CRITICAL: Data Source Priority (READ FIRST)
+
+**ALWAYS follow this data source hierarchy:**
+
+1. **FIRST: Check for MCP data sources** - If S&P Kensho MCP, FactSet MCP, or Daloopa MCP are available, use them exclusively for financial and trading information
+2. **DO NOT use web search** if the above MCP data sources are available
+3. **ONLY if MCPs are unavailable:** Then use Bloomberg Terminal, SEC EDGAR filings, or other institutional sources
+4. **NEVER use web search as a primary data source** - it lacks the accuracy, audit trails, and reliability required for institutional-grade analysis
+
+**Why this matters:** MCP sources provide verified, institutional-grade data with proper citations. Web search results can be outdated, inaccurate, or unreliable for financial analysis.
+
+---
+
+## Overview
+This skill teaches the agent to build institutional-grade comparable company analyses that combine operating metrics, valuation multiples, and statistical benchmarking. The output is a structured Excel/spreadsheet that enables informed investment decisions through peer comparison.
+
+**Reference Material & Contextualization:**
+
+An example comparable company analysis is provided in `examples/comps_example.xlsx`. When using this or other example files in this skill directory, use them intelligently:
+
+**DO use examples for:**
+- Understanding structural hierarchy (how sections flow)
+- Grasping the level of rigor expected (statistical depth, documentation standards)
+- Learning principles (clear headers, transparent formulas, audit trails)
+
+**DO NOT use examples for:**
+- Exact reproduction of format or metrics
+- Copying layout without considering context
+- Applying the same visual style regardless of audience
+
+**ALWAYS ask yourself first:**
+1. **"Do you have a preferred format or should I adapt the template style?"**
+2. **"Who is the audience?"** (Investment committee, board presentation, quick reference, detailed memo)
+3. **"What's the key question?"** (Valuation, growth analysis, competitive positioning, efficiency)
+4. **"What's the context?"** (M&A evaluation, investment decision, sector benchmarking, performance review)
+
+**Adapt based on specifics:**
+- **Industry context**: Big tech mega-caps need different metrics than emerging SaaS startups
+- **Sector-specific needs**: Add relevant metrics early (e.g., cloud ARR, enterprise customers, developer ecosystem for tech)
+- **Company familiarity**: Well-known companies may need less background, more focus on delta analysis
+- **Decision type**: M&A requires different emphasis than ongoing portfolio monitoring
+
+**Core principle:** Use template principles (clear structure, statistical rigor, transparent formulas) but vary execution based on context. The goal is institutional-quality analysis, not institutional-looking templates.
+
+User-provided examples and explicit preferences always take precedence over defaults.
+
+## Core Philosophy
+**"Build the right structure first, then let the data tell the story."**
+
+Start with headers that force strategic thinking about what matters, input clean data, build transparent formulas, and let statistics emerge automatically. A good comp should be immediately readable by someone who didn't build it.
+
+---
+
+## ⚠️ CRITICAL: Formulas Over Hardcodes + Step-by-Step Verification
+
+**Formulas, not hardcodes:**
+- Every derived value (margin, multiple, statistic) MUST be an Excel formula referencing input cells — never a pre-computed number pasted in
+- When using Python/openpyxl to build the sheet: write `cell.value = "=E7/C7"` (formula string), NOT `cell.value = 0.687` (computed result)
+- The only hardcoded values should be raw input data (revenue, EBITDA, share price, etc.) — and every one of those gets a cell comment with its source
+- Why: the model must update automatically when an input changes. A hardcoded margin is a silent bug waiting to happen.
+
+**Verify step-by-step with the user:**
+- After setting up the structure → show the user the header layout before filling data
+- After entering raw inputs → show the user the input block and confirm sources/periods before building formulas
+- After building operating metrics formulas → show the calculated margins and sanity-check with the user before moving to valuation
+- After building valuation multiples → show the multiples and confirm they look reasonable before adding statistics
+- Do NOT build the entire sheet end-to-end and then present it — catch errors early by confirming each section
+
+---
+
+## Section 1: Document Structure & Setup
+
+### Header Block (Rows 1-3)
+```
+Row 1: [ANALYSIS TITLE] - COMPARABLE COMPANY ANALYSIS
+Row 2: [List of Companies with Tickers] • [Company 1 (TICK1)] • [Company 2 (TICK2)] • [Company 3 (TICK3)]
+Row 3: As of [Period] | All figures in [USD Millions/Billions] except per-share amounts and ratios
+```
+
+**Why this matters:** Establishes context immediately. Anyone opening this file knows what they're looking at, when it was created, and how to interpret the numbers.
+
+### Visual Convention Standards (OPTIONAL - User preferences and uploaded templates always override)
+
+**IMPORTANT: These are suggested defaults only. Always prioritize:**
+1. User's explicit formatting preferences
+2. Formatting from any uploaded template files
+3. Company/team style guides
+4. These defaults (only if no other guidance provided)
+
+**Suggested Font & Typography:**
+- **Font family**: Times New Roman (professional, readable, industry standard)
+- **Font size**: 11pt for data cells, 12pt for headers
+- **Bold text**: Section headers, company names, statistic labels
+
+**Default Color & Shading — Professional Blue/Grey Palette (minimal is better):**
+- **Keep it restrained** — only blues and greys. Do NOT introduce greens, oranges, reds, or multiple accent colors. A clean comps sheet uses 3-4 colors total.
+- **Section headers** (e.g., "OPERATING STATISTICS & FINANCIAL METRICS"):
+  - Dark blue background (`#1F4E79` or `#17365D` navy)
+  - White bold text
+  - Full row shading across all columns
+- **Column headers** (e.g., "Company", "Revenue", "Margin"):
+  - Light blue background (`#D9E1F2` or similar pale blue)
+  - Black bold text
+  - Centered alignment
+- **Data rows**:
+  - White background for company data
+  - Black text for formulas; blue text for hardcoded inputs
+- **Statistics rows** (Maximum, 75th Percentile, etc.):
+  - Light grey background (`#F2F2F2`)
+  - Black text, left-aligned labels
+- **That's the whole palette**: dark blue + light blue + light grey + white. Nothing else unless the user's template says otherwise.
+
+**Suggested Formatting Conventions:**
+- **Decimal precision**:
+  - Percentages: 1 decimal (12.3%)
+  - Multiples: 1 decimal (13.5x)
+  - Dollar amounts: No decimals, thousands separator (69,632)
+  - Margins shown as percentages: 1 decimal (68.7%)
+- **Borders**: No borders (clean, minimal appearance)
+- **Alignment**: All metrics center-aligned for clean, uniform appearance
+- **Cell dimensions**: All column widths should be uniform/even, all row heights should be consistent (creates clean, professional grid)
+
+**Note:** If the user provides a template file or specifies different formatting, use that instead.
+
+---
+
+## Section 2: Operating Statistics & Financial Metrics
+
+### Core Columns (Start with these)
+1. **Company** - Names with consistent formatting
+2. **Revenue** - Size metric (can be LTM, quarterly, or annual depending on context)
+3. **Revenue Growth** - Year-over-year percentage change
+4. **Gross Profit** - Revenue minus cost of goods sold
+5. **Gross Margin** - GP/Revenue (fundamental profitability)
+6. **EBITDA** - Earnings before interest, tax, depreciation, amortization
+7. **EBITDA Margin** - EBITDA/Revenue (operating efficiency)
+
+### Optional Additions (Choose based on industry/purpose)
+- **Quarterly vs LTM** - Include both if seasonality matters
+- **Free Cash Flow** - For capital-intensive or SaaS businesses
+- **FCF Margin** - FCF/Revenue (cash generation efficiency)
+- **Net Income** - For mature, profitable companies
+- **Operating Income** - For businesses with varying D&A
+- **CapEx metrics** - For asset-heavy industries
+- **Rule of 40** - Specifically for SaaS (Growth % + Margin %)
+- **FCF Conversion** - For quality of earnings analysis (advanced)
+
+### Formula Examples (Using Row 7 as example)
+```excel
+// Core ratios - these are always calculated
+Gross Margin (F7): =E7/C7
+EBITDA Margin (H7): =G7/C7
+
+// Optional ratios - include if relevant
+FCF Margin: =[FCF]/[Revenue]
+Net Margin: =[Net Income]/[Revenue]
+Rule of 40: =[Growth %]+[FCF Margin %]
+```
+
+**Golden Rule:** Every ratio should be [Something] / [Revenue] or [Something] / [Something from this sheet]. Keep it simple.
+
+### Statistics Block (After company data)
+
+**CRITICAL: Add statistics formulas for all comparable metrics (ratios, margins, growth rates, multiples).**
+
+```
+[Leave one blank row for visual separation]
+- Maximum: =MAX(B7:B9)
+- 75th Percentile: =QUARTILE(B7:B9,3)
+- Median: =MEDIAN(B7:B9)
+- 25th Percentile: =QUARTILE(B7:B9,1)
+- Minimum: =MIN(B7:B9)
+```
+
+**Columns that NEED statistics (comparable metrics):**
+- Revenue Growth %, Gross Margin %, EBITDA Margin %, EPS
+- EV/Revenue, EV/EBITDA, P/E, Dividend Yield %, Beta
+
+**Columns that DON'T need statistics (size metrics):**
+- Revenue, EBITDA, Net Income (absolute size varies by company scale)
+- Market Cap, Enterprise Value (not comparable across different-sized companies)
+
+**Note:** Add one blank row between company data and statistics rows for visual separation. Do NOT add a "SECTOR STATISTICS" or "VALUATION STATISTICS" header row.
+
+**Why quartiles matter:** They show distribution, not just average. A 75th percentile multiple tells you what "premium" companies trade at.
+
+---
+
+## Section 3: Valuation Multiples & Investment Metrics
+
+### Core Valuation Columns (Start with these)
+1. **Company** - Same order as operating section
+2. **Market Cap** - Current market valuation
+3. **Enterprise Value** - Market Cap ± Net Debt/Cash
+4. **EV/Revenue** - How much market pays per dollar of sales
+5. **EV/EBITDA** - How much market pays per dollar of earnings
+6. **P/E Ratio** - Price relative to net earnings
+
+### Optional Valuation Metrics (Choose based on context)
+- **FCF Yield** - FCF/Market Cap (for cash-focused analysis)
+- **PEG Ratio** - P/E/Growth Rate (for growth companies)
+- **Price/Book** - Market value vs. book value (for asset-heavy businesses)
+- **ROE/ROA** - Return metrics (for profitability comparison)
+- **Revenue/EBITDA CAGR** - Historical growth rates (for trend analysis)
+- **Asset Turnover** - Revenue/Assets (for operational efficiency)
+- **Debt/Equity** - Leverage (for capital structure analysis)
+
+**Key Principle:** Include 3-5 core multiples that matter for your industry. Don't include every possible metric just because you can.
+
+### Formula Examples
+```excel
+// Core multiples - always include these
+EV/Revenue: =[Enterprise Value]/[LTM Revenue]
+EV/EBITDA: =[Enterprise Value]/[LTM EBITDA]
+P/E Ratio: =[Market Cap]/[Net Income]
+
+// Optional multiples - include if data available
+FCF Yield: =[LTM FCF]/[Market Cap]
+PEG Ratio: =[P/E]/[Growth Rate %]
+```
+
+### Cross-Reference Rule
+**CRITICAL:** Valuation multiples MUST reference the operating metrics section. Never input the same raw data twice. If revenue is in C7, then EV/Revenue formula should reference C7.
+
+### Statistics Block
+Same structure as operating section: Max, 75th, Median, 25th, Min for every metric. Add one blank row for visual separation between company data and statistics. Do NOT add a "VALUATION STATISTICS" header row.
+
+---
+
+## Section 4: Notes & Methodology Documentation
+
+### Required Components
+
+**Data Sources & Quality:**
+- Where did the data come from? (S&P Kensho MCP, FactSet MCP, Daloopa MCP, Bloomberg, SEC filings)
+- What period does it cover? (Q4 2024, audited figures)
+- How was it verified? (Cross-checked against 10-K/10-Q)
+- Note: Prioritize MCP data sources (S&P Kensho, FactSet, Daloopa) if available for better accuracy and traceability
+
+**Key Definitions:**
+- EBITDA calculation method (Gross Profit + D&A, or Operating Income + D&A)
+- Free Cash Flow formula (Operating CF - CapEx)
+- Special metrics explained (Rule of 40, FCF Conversion)
+- Time period definitions (LTM, CAGR calculation periods)
+
+**Valuation Methodology:**
+- How was Enterprise Value calculated? (Market Cap + Net Debt)
+- What growth rates were used? (Historical CAGR, forward estimates)
+- Any adjustments made? (One-time items excluded, normalized margins)
+
+**Analysis Framework:**
+- What's the investment thesis? (Cloud/SaaS efficiency)
+- What metrics matter most? (Cash generation, capital efficiency)
+- How should readers interpret the statistics? (Quartiles provide context)
+
+---
+
+## Section 5: Choosing the Right Metrics (Decision Framework)
+
+### Start with "What question am I answering?"
+
+**"Which company is undervalued?"**
+→ Focus on: EV/Revenue, EV/EBITDA, P/E, Market Cap
+→ Skip: Operational details, growth metrics
+
+**"Which company is most efficient?"**
+→ Focus on: Gross Margin, EBITDA Margin, FCF Margin, Asset Turnover
+→ Skip: Size metrics, absolute dollar amounts
+
+**"Which company is growing fastest?"**
+→ Focus on: Revenue Growth %, EBITDA CAGR, User/Customer Growth
+→ Skip: Margin metrics, leverage ratios
+
+**"Which is the best cash generator?"**
+→ Focus on: FCF, FCF Margin, FCF Conversion, CapEx intensity
+→ Skip: EBITDA, P/E ratios
+
+### Industry-Specific Metric Selection
+
+**Software/SaaS:**
+Must have: Revenue Growth, Gross Margin, Rule of 40
+Optional: ARR, Net Dollar Retention, CAC Payback
+Skip: Asset Turnover, Inventory metrics
+
+**Manufacturing/Industrials:**
+Must have: EBITDA Margin, Asset Turnover, CapEx/Revenue
+Optional: ROA, Inventory Turns, Backlog
+Skip: Rule of 40, SaaS metrics
+
+**Financial Services:**
+Must have: ROE, ROA, Efficiency Ratio, P/E
+Optional: Net Interest Margin, Loan Loss Reserves
+Skip: Gross Margin, EBITDA (not meaningful for banks)
+
+**Retail/E-commerce:**
+Must have: Revenue Growth, Gross Margin, Inventory Turnover
+Optional: Same-Store Sales, Customer Acquisition Cost
+Skip: Heavy R&D or CapEx metrics
+
+### The "5-10 Rule"
+
+**5 operating metrics** - Revenue, Growth, 2-3 margins/efficiency metrics
+**5 valuation metrics** - Market Cap, EV, 3 multiples
+**= 10 total columns** - Enough to tell the story, not so many you lose the thread
+
+If you have more than 15 metrics, you're probably including noise. Edit ruthlessly.
+
+---
+
+## Section 6: Best Practices & Quality Checks
+
+### Before You Start
+1. **Define the peer group** - Companies must be truly comparable (similar business model, scale, geography)
+2. **Choose the right period** - LTM smooths seasonality; quarterly shows trends
+3. **Standardize units upfront** - Millions vs. billions decision affects everything
+4. **Map data sources** - Know where each number comes from
+
+### As You Build
+1. **Input all raw data first** - Complete the blue text before writing formulas
+2. **Add cell comments to ALL hard-coded inputs** - Right-click cell → Insert Comment → Document source OR assumption
+
+   **For sourced data, cite exactly where it came from:**
+   - Example: "Bloomberg Terminal - MSFT Equity DES, accessed 2024-10-02"
+   - Example: "Q4 2024 10-K filing, page 42, line item 'Total Revenue'"
+   - Example: "FactSet consensus estimate as of 2024-10-02"
+   - **Include hyperlinks when possible**: Right-click cell → Link → paste URL to SEC filing, data source, or report
+
+   **For assumptions, explain the reasoning:**
+   - Example: "Assumed 15% EBITDA margin based on peer median, company does not disclose"
+   - Example: "Estimated Enterprise Value as Market Cap + $50M net debt (from Q3 balance sheet, Q4 not yet available)"
+   - Example: "Forward P/E based on street consensus EPS of $3.45 (average of 12 analyst estimates)"
+
+   **Why this matters**: Enables audit trails, data verification, assumption transparency, and future updates
+3. **Build formulas row by row** - Test each calculation before moving on
+4. **Use absolute references for headers** - $C$6 locks the header row
+5. **Format consistently** - Percentages as percentages, not decimals
+6. **Add conditional formatting** - Highlight outliers automatically
+
+### Sanity Checks
+- **Margin test**: Gross margin > EBITDA margin > Net margin (always true by definition)
+- **Multiple reasonableness**: 
+  - EV/Revenue: typically 0.5-20x (varies widely by industry)
+  - EV/EBITDA: typically 8-25x (fairly consistent across industries)
+  - P/E: typically 10-50x (depends on growth rate)
+- **Growth-multiple correlation**: Higher growth usually means higher multiples
+- **Size-efficiency trade-off**: Larger companies often have better margins (scale benefits)
+
+### Common Mistakes to Avoid
+❌ Mixing market cap and enterprise value in formulas
+❌ Using different time periods for numerator and denominator (LTM vs quarterly)
+❌ Hardcoding numbers into formulas instead of cell references
+❌ **Hard-coded inputs without cell comments citing the source OR explaining the assumption**
+❌ Missing hyperlinks to SEC filings or data sources when available
+❌ Including too many metrics without clear purpose
+❌ Including non-comparable companies (different business models)
+❌ Using outdated data without disclosure
+❌ Calculating averages of percentages incorrectly (should be median)
+
+---
+
+## Section 6: Advanced Features
+
+### Dynamic Headers
+For columns showing calculations, use clear unit labels:
+```
+Revenue Growth (YoY) % | EBITDA Margin | FCF Margin | Rule of 40
+```
+
+### Quartile Analysis Benefits
+Instead of just mean/median, quartiles show:
+- **75th percentile** = "Premium" companies trade here
+- **Median** = Typical market valuation
+- **25th percentile** = "Discount" territory
+
+This helps answer: "Is our target company trading rich or cheap vs. peers?"
+
+### Industry-Specific Modifications
+
+**Software/SaaS:**
+- Add: ARR, Net Dollar Retention, CAC Payback Period
+- Emphasize: Rule of 40, FCF margins, gross margins >70%
+
+**Healthcare:**
+- Add: R&D/Revenue, Pipeline value, Regulatory status
+- Emphasize: EBITDA margins, growth rates, reimbursement risk
+
+**Industrials:**
+- Add: Backlog, Order book trends, Geographic mix
+- Emphasize: ROIC, asset turnover, cyclical adjustments
+
+**Consumer:**
+- Add: Same-store sales, Customer acquisition cost, Brand value
+- Emphasize: Revenue growth, gross margins, inventory turns
+
+---
+
+## Section 7: Workflow & Practical Tips
+
+### Step-by-Step Process
+1. **Set up structure** (30 minutes)
+   - Create all headers
+   - Format cells (blue for inputs, black for formulas)
+   - Lock in units and date references
+
+2. **Gather data** (60-90 minutes)
+   - Pull from primary sources (S&P Kensho MCP, FactSet MCP, Daloopa MCP if available; otherwise Bloomberg, SEC)
+   - Input all raw numbers in blue
+   - Document sources in notes section
+
+3. **Build formulas** (30 minutes)
+   - Start with simple ratios (margins)
+   - Progress to multiples (EV/Revenue)
+   - Add cross-checks (do margins make sense?)
+
+4. **Add statistics** (15 minutes)
+   - Copy formula structure for all columns
+   - Verify ranges are correct (B7:B9, not B7:B10)
+   - Check quartile logic
+
+5. **Quality control** (30 minutes)
+   - Run sanity checks
+   - Verify formula references
+   - Check for #DIV/0! or #REF! errors
+   - Compare against known benchmarks
+
+6. **Documentation** (15 minutes)
+   - Complete notes section
+   - Add data sources
+   - Define methodologies
+   - Date-stamp the analysis
+
+### Pro Tips
+- **Save templates**: Build once, reuse forever
+- **Color-code outliers**: Conditional formatting for values >2 standard deviations
+- **Link to source files**: Hyperlink to Bloomberg screenshots or SEC filings
+- **Version control**: Save as "Comps_v1_2024-12-15" with clear dating
+- **Collaborative reviews**: Have someone else check your formulas
+
+### Excel Formatting Checklist (Optional - adapt to user preferences)
+- [ ] Font set to user's preferred style (default: Times New Roman, 11pt data, 12pt headers)
+- [ ] Section headers formatted per user's template (default: dark blue #17365D with white bold text)
+- [ ] Column headers formatted per user's template (default: light blue/gray #D9E2F3 with black bold text)
+- [ ] Statistics rows formatted per user's template (default: light gray #F2F2F2)
+- [ ] No borders applied (clean, minimal appearance)
+- [ ] **Column widths set to uniform/even width** (creates clean, professional appearance)
+- [ ] **Row heights set to consistent height** (typically 20-25pt for data rows)
+- [ ] Numbers formatted with proper decimal precision and thousands separators
+- [ ] **All metrics center-aligned** for clean, uniform appearance
+- [ ] **One blank row for separation between company data and statistics rows**
+- [ ] **No separate "SECTOR STATISTICS" or "VALUATION STATISTICS" header rows**
+- [ ] **Every hard-coded input cell has a comment with either: (1) exact data source, OR (2) assumption explanation**
+- [ ] **Hyperlinks added to cells where applicable** (SEC filings, data provider pages, reports)
+
+---
+
+## Section 8: Example Template Layout
+
+**Simple Version (Start here):**
+```
+┌─────────────────────────────────────────────────────────────┐
+│ TECHNOLOGY - COMPARABLE COMPANY ANALYSIS                    │
+│ Microsoft • Alphabet • Amazon                               │
+│ As of Q4 2024 | All figures in USD Millions                │
+├─────────────────────────────────────────────────────────────┤
+│ OPERATING METRICS                                           │
+├──────────┬─────────┬─────────┬──────────┬──────────────────┤
+│ Company  │ Revenue │ Growth  │ Gross    │ EBITDA  │ EBITDA │
+│          │ (LTM)   │ (YoY)   │ Margin   │ (LTM)   │ Margin │
+├──────────┼─────────┼─────────┼──────────┼─────────┼────────┤
+│ MSFT     │ 261,400 │ 12.3%   │ 68.7%    │ 205,100 │ 78.4%  │
+│ GOOGL    │ 349,800 │ 11.8%   │ 57.9%    │ 239,300 │ 68.4%  │
+│ AMZN     │ 638,100 │ 10.5%   │ 47.3%    │ 152,600 │ 23.9%  │
+│          │         │         │          │         │        │ [blank row]
+│ Median   │ =MEDIAN │ =MEDIAN │ =MEDIAN  │ =MEDIAN │=MEDIAN │
+│ 75th %   │ =QUART  │ =QUART  │ =QUART   │ =QUART  │=QUART  │
+│ 25th %   │ =QUART  │ =QUART  │ =QUART   │ =QUART  │=QUART  │
+├─────────────────────────────────────────────────────────────┤
+│ VALUATION MULTIPLES                                         │
+├──────────┬──────────┬──────────┬──────────┬────────────────┤
+│ Company  │ Mkt Cap  │ EV       │ EV/Rev   │ EV/EBITDA │ P/E│
+├──────────┼──────────┼──────────┼──────────┼───────────┼────┤
+│ MSFT     │3,550,000 │3,530,000 │ 13.5x    │ 17.2x     │36.0│
+│ GOOGL    │2,030,000 │1,960,000 │  5.6x    │  8.2x     │24.5│
+│ AMZN     │2,226,000 │2,320,000 │  3.6x    │ 15.2x     │58.3│
+│          │          │          │          │           │    │ [blank row]
+│ Median   │ =MEDIAN  │ =MEDIAN  │ =MEDIAN  │ =MEDIAN   │=MED│
+│ 75th %   │ =QUART   │ =QUART   │ =QUART   │ =QUART    │=QRT│
+│ 25th %   │ =QUART   │ =QUART   │ =QUART   │ =QUART    │=QRT│
+└──────────┴──────────┴──────────┴──────────┴───────────┴────┘
+```
+
+**Add complexity only when needed:**
+- Include quarterly AND LTM if seasonality matters
+- Add FCF metrics if cash generation is key story
+- Include industry-specific metrics (Rule of 40 for SaaS, etc.)
+- Add more statistics rows if you have >5 companies
+
+---
+
+## Section 9: Industry-Specific Additions (Optional)
+
+Only add these if they're critical to your analysis. Most comps work fine with just core metrics.
+
+**Software/SaaS:**
+Add if relevant: ARR, Net Dollar Retention, Rule of 40
+
+**Financial Services:**
+Add if relevant: ROE, Net Interest Margin, Efficiency Ratio
+
+**E-commerce:**
+Add if relevant: GMV, Take Rate, Active Buyers
+
+**Healthcare:**
+Add if relevant: R&D/Revenue, Pipeline Value, Patent Timeline
+
+**Manufacturing:**
+Add if relevant: Asset Turnover, Inventory Turns, Backlog
+
+---
+
+## Section 10: Red Flags & Warning Signs
+
+### Data Quality Issues
+🚩 Inconsistent time periods (mixing quarterly and annual)  
+🚩 Missing data without explanation  
+🚩 Significant differences between data sources (>10% variance)
+
+### Valuation Red Flags
+🚩 Negative EBITDA companies being valued on EBITDA multiples (use revenue multiples instead)  
+🚩 P/E ratios >100x without hypergrowth story  
+🚩 Margins that don't make sense for the industry
+
+### Comparability Issues
+🚩 Different fiscal year ends (causes timing problems)  
+🚩ixing pure-play and conglomerates  
+🚩 Materially different business models labeled as "comps"
+
+**When in doubt, exclude the company.** Better to have 3 perfect comps than 6 questionable ones.
+
+---
+
+## Section 11: Formulas Reference Guide
+
+### Essential Excel Formulas
+```excel
+// Statistical Functions
+=AVERAGE(range)          // Simple mean
+=MEDIAN(range)           // Middle value
+=QUARTILE(range, 1)      // 25th percentile
+=QUARTILE(range, 3)      // 75th percentile
+=MAX(range)              // Maximum value
+=MIN(range)              // Minimum value
+=STDEV.P(range)          // Standard deviation
+
+// Financial Calculations
+=B7/C7                   // Simple ratio (Margin)
+=SUM(B7:B9)/3            // Average of multiple companies
+=IF(B7>0, C7/B7, "N/A")  // Conditional calculation
+=IFERROR(C7/D7, 0)       // Handle divide by zero
+
+// Cross-Sheet References
+='Sheet1'!B7             // Reference another sheet
+=VLOOKUP(A7, Table1, 2)  // Lookup from data table
+=INDEX(MATCH())          // Advanced lookup
+
+// Formatting
+=TEXT(B7, "0.0%")        // Format as percentage
+=TEXT(C7, "#,##0")       // Thousands separator
+```
+
+### Common Ratio Formulas
+```excel
+Gross Margin = Gross Profit / Revenue
+EBITDA Margin = EBITDA / Revenue
+FCF Margin = Free Cash Flow / Revenue
+FCF Conversion = FCF / Operating Cash Flow
+ROE = Net Income / Shareholders' Equity
+ROA = Net Income / Total Assets
+Asset Turnover = Revenue / Total Assets
+Debt/Equity = Total Debt / Shareholders' Equity
+```
+
+---
+
+## Key Principles Summary
+
+1. **Structure drives insight** - Right headers force right thinking
+2. **Less is more** - 5-10 metrics that matter beat 20 that don't
+3. **Choose metrics for your question** - Valuation analysis ≠ efficiency analysis
+4. **Statistics show patterns** - Median/quartiles reveal more than average
+5. **Transparency beats complexity** - Simple formulas everyone understands
+6. **Comparability is king** - Better to exclude than force a bad comp
+7. **Document your choices** - Explain which metrics and why in notes section
+
+---
+
+## Output Checklist
+
+Before delivering a comp analysis, verify:
+- [ ] All companies are truly comparable
+- [ ] Data is from consistent time periods
+- [ ] Units are clearly labeled (millions/billions)
+- [ ] Formulas reference cells, not hardcoded values
+- [ ] **All hard-coded input cells have comments with either: (1) exact data source with citation, OR (2) clear assumption with explanation**
+- [ ] **Hyperlinks added where relevant** (SEC EDGAR filings, Bloomberg pages, research reports)
+- [ ] Statistics include at least 5 metrics (Max, 75th, Med, 25th, Min)
+- [ ] Notes section documents sources and methodology
+- [ ] Visual formatting follows conventions (blue = input, black = formula)
+- [ ] Sanity checks pass (margins logical, multiples reasonable)
+- [ ] Date stamp is current ("As of [Date]")
+- [ ] Formula auditing shows no errors (#DIV/0!, #REF!, #N/A)
+
+---
+
+## Continuous Improvement
+
+After completing a comp analysis, ask:
+1. Did the statistics reveal unexpected insights?
+2. Were there any data gaps that limited analysis?
+3. Did stakeholders ask for metrics you didn't include?
+4. How long did it take vs. how long should it take?
+5. What would make this more useful next time?
+
+The best comp analyses evolve with each iteration. Save templates, learn from feedback, and refine the structure based on what decision-makers actually use.
+
+
+## Data sources — MCP first, web fallback
+
+Many passages below say "use the S&P Kensho MCP / Daloopa MCP / FactSet MCP". Those are commercial financial-data MCPs from the original Cowork plugin context. In Hermes:
+
+- **If you have any structured financial-data MCP configured** (Hermes supports MCP — see `native-mcp` skill), prefer it for point-in-time comps, precedent transactions, and filings.
+- **Otherwise**, fall back to:
+  - `web_search` / `web_extract` against SEC EDGAR (`https://www.sec.gov/cgi-bin/browse-edgar`) for US filings
+  - Company IR pages for press releases, earnings decks
+  - `browser_navigate` for interactive data portals
+  - User-provided data (explicitly ask when the context doesn't have it)
+- **Never fabricate**. If a multiple, precedent, or filing number can't be sourced, flag the cell as `[UNSOURCED]` and surface it to the user.
+
+## Attribution
+
+This skill is adapted from Anthropic's Claude for Financial Services plugin suite (Apache-2.0). The Office-JS / Cowork live-Excel paths have been removed; this version targets headless openpyxl via the `excel-author` skill's conventions. Original: https://github.com/anthropics/financial-services
@@ -0,0 +1,40 @@
+# DCF Model Troubleshooting Guide
+
+**When to read this file:** If recalc.py shows errors OR valuation results seem unreasonable OR case selector not working properly.
+
+## Model Returns Error Values
+
+### #REF! Errors
+- Usually caused by formulas referencing wrong rows after headers were inserted
+- Solution: Rebuild with correct row references, or start over following layout planning
+- Prevention: Define all row positions BEFORE writing formulas
+
+### #DIV/0! Errors
+- Division by zero or empty cells
+- Solution: Add IF statements to handle zeros: `=IF([Divisor]=0,0,[Numerator]/[Divisor])`
+
+### #VALUE! Errors
+- Wrong data type in calculation (text instead of number)
+- Solution: Verify all inputs are formatted as numbers
+
+## Valuation Seems Unreasonable
+
+### Implied price far too high
+- Check terminal value isn't >80% of EV
+- Verify terminal growth < WACC
+- Review if growth assumptions are realistic
+- Consider if margins are too optimistic
+
+### Implied price far too low
+- Verify net debt vs net cash is correct
+- Check if WACC is too high
+- Review if projections are too conservative
+- Consider if terminal growth is too low
+
+## Case Selector Not Working
+
+### Consolidation column not updating when switching scenarios
+- Verify case selector cell contains 1, 2, or 3
+- Check INDEX/OFFSET formulas reference correct row range and selector cell
+- Ensure absolute references ($B$6) are used for selector
+- Test by manually changing the selector cell and verifying projection values update
@@ -0,0 +1,7 @@
+# DCF Model Builder - Python Dependencies
+
+# Excel file handling
+openpyxl>=3.0.0
+
+# HTTP requests
+requests>=2.28.0
@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""
+DCF Model Validation Script
+Validates Excel DCF models for formula errors and common DCF mistakes
+"""
+
+import sys
+import json
+from pathlib import Path
+from typing import Optional
+
+
+class DCFModelValidator:
+    """Validates DCF models for errors and quality issues"""
+
+    def __init__(self, excel_path: str):
+        try:
+            import openpyxl
+        except ImportError:
+            raise ImportError("openpyxl not installed. Run: pip install openpyxl")
+
+        self.excel_path = excel_path
+        self.openpyxl = openpyxl
+
+        if not Path(excel_path).exists():
+            raise FileNotFoundError(f"File not found: {excel_path}")
+
+        self.workbook_formulas = openpyxl.load_workbook(excel_path, data_only=False)
+        self.workbook_values = openpyxl.load_workbook(excel_path, data_only=True)
+        self.errors = []
+        self.warnings = []
+        self.info = []
+        
+    def validate_all(self) -> dict:
+        """
+        Run all validation checks
+
+        Returns:
+            Dict with validation results
+        """
+        from datetime import datetime
+
+        self.check_sheet_structure()
+        self.check_formula_errors()
+        self.check_dcf_logic()
+
+        results = {
+            'file': self.excel_path,
+            'validation_date': datetime.now().isoformat(),
+            'status': 'PASS' if len(self.errors) == 0 else 'FAIL',
+            'error_count': len(self.errors),
+            'warning_count': len(self.warnings),
+            'errors': self.errors,
+            'warnings': self.warnings,
+            'info': self.info
+        }
+
+        return results
+    
+    def check_sheet_structure(self):
+        """Verify required sheets exist"""
+        required_sheets = ['DCF', 'WACC', 'Sensitivity']
+        sheet_names = self.workbook_values.sheetnames
+
+        for sheet in required_sheets:
+            if sheet not in sheet_names:
+                self.warnings.append(f"Recommended sheet missing: {sheet}")
+            else:
+                self.info.append(f"Found sheet: {sheet}")
+
+    def check_formula_errors(self):
+        """Check for Excel formula errors in all sheets"""
+        excel_errors = ['#VALUE!', '#DIV/0!', '#REF!', '#NAME?', '#NULL!', '#NUM!', '#N/A']
+        error_details = {err: [] for err in excel_errors}
+        total_errors = 0
+        total_formulas = 0
+
+        for sheet_name in self.workbook_values.sheetnames:
+            ws_values = self.workbook_values[sheet_name]
+            ws_formulas = self.workbook_formulas[sheet_name]
+
+            for row in ws_values.iter_rows():
+                for cell in row:
+                    formula_cell = ws_formulas[cell.coordinate]
+
+                    # Count formulas
+                    if formula_cell.value and isinstance(formula_cell.value, str) and formula_cell.value.startswith('='):
+                        total_formulas += 1
+
+                    # Check for errors
+                    if cell.value is not None and isinstance(cell.value, str):
+                        for err in excel_errors:
+                            if err in cell.value:
+                                location = f"{sheet_name}!{cell.coordinate}"
+                                error_details[err].append(location)
+                                total_errors += 1
+                                self.errors.append(f"{err} at {location}")
+                                break
+
+        # Add summary info
+        self.info.append(f"Total formulas: {total_formulas}")
+        if total_errors == 0:
+            self.info.append("✓ No formula errors found")
+        else:
+            self.errors.append(f"Total formula errors: {total_errors}")
+
+        return error_details, total_errors
+    
+    def check_dcf_logic(self):
+        """Validate DCF-specific logic and calculations"""
+        self._check_terminal_growth_vs_wacc()
+        self._check_wacc_range()
+        self._check_terminal_value_proportion()
+
+    def _check_terminal_growth_vs_wacc(self):
+        """Critical check: Terminal growth must be less than WACC"""
+        try:
+            dcf_sheet = self.workbook_values['DCF']
+
+            terminal_growth = None
+            wacc = None
+
+            # Search for terminal growth and WACC values
+            for row in dcf_sheet.iter_rows(max_row=100, max_col=20):
+                for cell in row:
+                    if cell.value and isinstance(cell.value, str):
+                        cell_str = cell.value.lower()
+                        if 'terminal' in cell_str and 'growth' in cell_str:
+                            # Look for value in adjacent cells
+                            for offset in range(1, 5):
+                                adjacent = dcf_sheet.cell(cell.row, cell.column + offset).value
+                                if isinstance(adjacent, (int, float)) and 0 < adjacent < 1:
+                                    terminal_growth = adjacent
+                                    break
+                        if 'wacc' in cell_str and wacc is None:
+                            for offset in range(1, 5):
+                                adjacent = dcf_sheet.cell(cell.row, cell.column + offset).value
+                                if isinstance(adjacent, (int, float)) and 0 < adjacent < 1:
+                                    wacc = adjacent
+                                    break
+
+            if terminal_growth is not None and wacc is not None:
+                if terminal_growth >= wacc:
+                    self.errors.append(
+                        f"CRITICAL: Terminal growth ({terminal_growth:.2%}) >= WACC ({wacc:.2%}). "
+                        "This creates infinite value and is mathematically invalid."
+                    )
+                else:
+                    self.info.append(
+                        f"✓ Terminal growth ({terminal_growth:.2%}) < WACC ({wacc:.2%})"
+                    )
+            else:
+                self.warnings.append("Could not locate terminal growth and WACC values")
+
+        except KeyError:
+            self.warnings.append("DCF sheet not found")
+        except Exception as e:
+            self.warnings.append(f"Could not validate terminal growth vs WACC: {str(e)}")
+
+    def _check_wacc_range(self):
+        """Check if WACC is in reasonable range"""
+        try:
+            wacc_sheet = self.workbook_values.get('WACC') or self.workbook_values['DCF']
+            wacc = None
+
+            for row in wacc_sheet.iter_rows(max_row=100, max_col=20):
+                for cell in row:
+                    if cell.value and isinstance(cell.value, str):
+                        if 'wacc' in cell.value.lower():
+                            for offset in range(1, 5):
+                                adjacent = wacc_sheet.cell(cell.row, cell.column + offset).value
+                                if isinstance(adjacent, (int, float)) and 0 < adjacent < 1:
+                                    wacc = adjacent
+                                    break
+
+            if wacc is not None:
+                if wacc < 0.05 or wacc > 0.20:
+                    self.warnings.append(
+                        f"WACC ({wacc:.2%}) is outside typical range (5%-20%). Verify calculation."
+                    )
+                else:
+                    self.info.append(f"✓ WACC ({wacc:.2%}) in reasonable range")
+            else:
+                self.warnings.append("Could not locate WACC value")
+
+        except Exception as e:
+            self.warnings.append(f"Could not validate WACC range: {str(e)}")
+
+    def _check_terminal_value_proportion(self):
+        """Check if terminal value is reasonable proportion of enterprise value"""
+        try:
+            dcf_sheet = self.workbook_values['DCF']
+
+            terminal_value = None
+            enterprise_value = None
+
+            for row in dcf_sheet.iter_rows(max_row=200, max_col=20):
+                for cell in row:
+                    if cell.value and isinstance(cell.value, str):
+                        cell_str = cell.value.lower()
+                        if 'terminal' in cell_str and 'value' in cell_str and 'pv' in cell_str:
+                            for offset in range(1, 5):
+                                adjacent = dcf_sheet.cell(cell.row, cell.column + offset).value
+                                if isinstance(adjacent, (int, float)) and adjacent > 0:
+                                    terminal_value = adjacent
+                                    break
+                        if 'enterprise' in cell_str and 'value' in cell_str:
+                            for offset in range(1, 5):
+                                adjacent = dcf_sheet.cell(cell.row, cell.column + offset).value
+                                if isinstance(adjacent, (int, float)) and adjacent > 0:
+                                    enterprise_value = adjacent
+                                    break
+
+            if terminal_value is not None and enterprise_value is not None and enterprise_value > 0:
+                proportion = terminal_value / enterprise_value
+                if proportion > 0.80:
+                    self.warnings.append(
+                        f"Terminal value is {proportion:.1%} of EV (typically should be 50-70%). "
+                        "Model may be over-reliant on terminal assumptions."
+                    )
+                elif proportion < 0.40:
+                    self.warnings.append(
+                        f"Terminal value is {proportion:.1%} of EV (typically should be 50-70%). "
+                        "Check if terminal assumptions are too conservative."
+                    )
+                else:
+                    self.info.append(f"✓ Terminal value is {proportion:.1%} of EV")
+            else:
+                self.warnings.append("Could not locate terminal value and enterprise value")
+
+        except Exception as e:
+            self.warnings.append(f"Could not validate terminal value proportion: {str(e)}")
+    
+
+
+def validate_dcf_model(excel_path: str) -> dict:
+    """
+    Validate a DCF model Excel file
+
+    Args:
+        excel_path: Path to Excel DCF model
+
+    Returns:
+        Dict with validation results
+    """
+    validator = DCFModelValidator(excel_path)
+    return validator.validate_all()
+
+
+def main():
+    """Command-line interface"""
+    if len(sys.argv) < 2:
+        print("Usage: python validate_dcf.py <excel_file> [output.json]")
+        print("\nValidates DCF model for:")
+        print("  - Formula errors (#REF!, #DIV/0!, etc.)")
+        print("  - Terminal growth < WACC (critical)")
+        print("  - WACC in reasonable range (5-20%)")
+        print("  - Terminal value proportion of EV (40-80%)")
+        print("\nReturns JSON with errors, warnings, and info")
+        print("\nExample: python validate_dcf.py model.xlsx")
+        print("Example: python validate_dcf.py model.xlsx results.json")
+        sys.exit(1)
+
+    excel_file = sys.argv[1]
+    output_file = sys.argv[2] if len(sys.argv) > 2 else None
+
+    try:
+        results = validate_dcf_model(excel_file)
+
+        # Print results
+        print(json.dumps(results, indent=2))
+
+        # Save to file if requested
+        if output_file:
+            with open(output_file, 'w') as f:
+                json.dump(results, f, indent=2)
+
+        # Exit with error code if validation failed
+        sys.exit(0 if results['status'] == 'PASS' else 1)
+
+    except Exception as e:
+        error_result = {
+            'file': excel_file,
+            'status': 'ERROR',
+            'error': str(e)
+        }
+        print(json.dumps(error_result, indent=2))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,243 @@
+---
+name: excel-author
+description: Build auditable Excel workbooks headless with openpyxl — blue/black/green cell conventions, formulas over hardcodes, named ranges, balance checks, sensitivity tables. Use for financial models, audit outputs, reconciliations.
+version: 1.0.0
+author: Anthropic (adapted by Nous Research)
+license: Apache-2.0
+metadata:
+  hermes:
+    tags: [excel, openpyxl, finance, spreadsheet, modeling]
+    related_skills: [pptx-author, dcf-model, comps-analysis, lbo-model, 3-statement-model]
+---
+
+# excel-author
+
+Produce an .xlsx file on disk using `openpyxl`. Follow the banker-grade conventions below so the model is auditable, flexible, and reviewable by someone other than the person who built it.
+
+Adapted from Anthropic's `xlsx-author` and `audit-xls` skills in the [anthropics/financial-services](https://github.com/anthropics/financial-services) repo. The MCP / Office-JS / Cowork-specific branches of the originals are dropped — this skill assumes headless Python.
+
+## Output contract
+
+- Write to `./out/<name>.xlsx`. Create `./out/` if it does not exist.
+- Return the relative path in your final message so downstream tools can pick it up.
+- One logical model per file. Do not append to an existing workbook unless explicitly asked.
+
+## Setup
+
+```bash
+pip install "openpyxl>=3.0"
+```
+
+## Core conventions (non-negotiable)
+
+### Blue / black / green cell color
+- **Blue** (`Font(color="0000FF")`) — hardcoded input a human entered. Revenue drivers, WACC inputs, terminal growth, market data.
+- **Black** (default) — formula. Every derived cell is a live Excel formula.
+- **Green** (`Font(color="006100")`) — link to another sheet or external file.
+
+A reviewer can then scan the sheet and immediately see what's an assumption vs. what's computed.
+
+### Formulas over hardcodes
+Every calculation cell MUST be a formula string, never a number computed in Python and pasted as a value.
+
+```python
+# WRONG — silent bug waiting to happen
+ws["D20"] = revenue_prior_year * (1 + growth)
+
+# CORRECT — flexes when the user changes the assumption
+ws["D20"] = "=D19*(1+$B$8)"
+```
+
+The only hardcoded numbers permitted:
+1. Raw historical inputs (actual revenues, reported EBITDA, etc.)
+2. Assumption drivers the user is meant to flex (growth rates, WACC inputs, terminal g)
+3. Current market data (share price, debt balance) — with a cell comment documenting source + date
+
+If you catch yourself computing a value in Python and writing the result, stop.
+
+### Named ranges for cross-sheet references
+Use named ranges for any figure referenced from another sheet, a deck, or a memo.
+
+```python
+from openpyxl.workbook.defined_name import DefinedName
+wb.defined_names["WACC"] = DefinedName("WACC", attr_text="Inputs!$C$8")
+# then elsewhere:
+calc["D30"] = "=D29/WACC"
+```
+
+### Balance checks tab
+Include a `Checks` tab that ties everything and surfaces TRUE/FALSE:
+- Balance sheet balances (assets = liabilities + equity)
+- Cash flow ties to period-over-period cash change on the BS
+- Sum-of-parts ties to consolidated totals
+- No rogue hardcodes inside calc ranges
+
+Example:
+```python
+checks = wb.create_sheet("Checks")
+checks["A2"] = "BS balances"
+checks["B2"] = "=IS!D20-IS!D21-IS!D22"
+checks["C2"] = "=ABS(B2)<0.01"  # TRUE/FALSE
+```
+
+### Cell comments on every hardcoded input
+Add the comment AS you create the cell, not later.
+
+```python
+from openpyxl.comments import Comment
+ws["C2"] = 1_250_000_000
+ws["C2"].font = Font(color="0000FF")
+ws["C2"].comment = Comment("Source: 10-K FY2024, p.47, revenue line", "analyst")
+```
+
+Format: `Source: [System/Document], [Date], [Reference], [URL if applicable]`.
+
+Never defer sourcing. Never write `TODO: add source`.
+
+## Skeleton: typical financial model
+
+```python
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill, Alignment, Border, Side
+from openpyxl.comments import Comment
+from openpyxl.utils import get_column_letter
+from pathlib import Path
+
+BLUE = Font(color="0000FF")
+BLACK = Font(color="000000")
+GREEN = Font(color="006100")
+BOLD = Font(bold=True)
+HEADER_FILL = PatternFill("solid", fgColor="1F4E79")
+HEADER_FONT = Font(color="FFFFFF", bold=True)
+
+wb = Workbook()
+
+# --- Inputs tab ---
+inp = wb.active
+inp.title = "Inputs"
+inp["A1"] = "MARKET DATA & KEY INPUTS"
+inp["A1"].font = HEADER_FONT
+inp["A1"].fill = HEADER_FILL
+inp.merge_cells("A1:C1")
+
+inp["B3"] = "Revenue FY2024"
+inp["C3"] = 1_250_000_000
+inp["C3"].font = BLUE
+inp["C3"].comment = Comment("Source: 10-K FY2024 p.47", "model")
+
+inp["B4"] = "Growth Rate"
+inp["C4"] = 0.12
+inp["C4"].font = BLUE
+
+# --- Calc tab ---
+calc = wb.create_sheet("DCF")
+calc["B2"] = "Projected Revenue"
+calc["C2"] = "=Inputs!C3*(1+Inputs!C4)"   # formula, black
+
+# --- Checks tab ---
+chk = wb.create_sheet("Checks")
+chk["A2"] = "BS balances"
+chk["B2"] = "=ABS(BS!D20-BS!D21-BS!D22)<0.01"
+
+Path("./out").mkdir(exist_ok=True)
+wb.save("./out/model.xlsx")
+```
+
+## Section headers with merged cells
+
+openpyxl quirk: when you merge, set the value on the top-left cell and style the full range separately.
+
+```python
+ws["A7"] = "CASH FLOW PROJECTION"
+ws["A7"].font = HEADER_FONT
+ws.merge_cells("A7:H7")
+for col in range(1, 9):  # A..H
+    ws.cell(row=7, column=col).fill = HEADER_FILL
+```
+
+## Sensitivity tables
+
+Build with loops, not hardcoded formulas per cell. Rules:
+
+- **Odd number of rows/cols** (5×5 or 7×7) — guarantees a true center cell.
+- **Center cell = base case.** The middle row/col header must equal the model's actual WACC and terminal g so the center output equals the base-case implied share price. That's the sanity check.
+- **Highlight the center cell** with medium-blue fill (`"BDD7EE"`) and bold.
+- Populate every cell with a full recalculation formula — never an approximation.
+
+```python
+# 5x5 WACC (rows) x terminal growth (cols) sensitivity
+wacc_axis = [0.08, 0.085, 0.09, 0.095, 0.10]        # center row = base 9.0%
+term_axis = [0.02, 0.025, 0.03, 0.035, 0.04]        # center col = base 3.0%
+
+start_row = 40
+ws.cell(row=start_row, column=1).value = "Implied Share Price ($)"
+ws.cell(row=start_row, column=1).font = BOLD
+
+for j, g in enumerate(term_axis):
+    ws.cell(row=start_row+1, column=2+j).value = g
+    ws.cell(row=start_row+1, column=2+j).font = BLUE
+
+for i, w in enumerate(wacc_axis):
+    r = start_row + 2 + i
+    ws.cell(row=r, column=1).value = w
+    ws.cell(row=r, column=1).font = BLUE
+    for j, g in enumerate(term_axis):
+        c = 2 + j
+        # Full DCF recalc formula (simplified for illustration).
+        # In a real model this references the full projection block.
+        ws.cell(row=r, column=c).value = (
+            f"=SUMPRODUCT(FCF_range,1/(1+{w})^year_offset) + "
+            f"FCF_terminal*(1+{g})/({w}-{g})/(1+{w})^terminal_year"
+        )
+
+# Highlight center cell (base case)
+center = ws.cell(row=start_row+2+len(wacc_axis)//2,
+                 column=2+len(term_axis)//2)
+center.fill = PatternFill("solid", fgColor="BDD7EE")
+center.font = BOLD
+```
+
+## Recalculating before delivery
+
+openpyxl writes formula strings but does not compute them. Excel recalculates on open, but downstream consumers (auto-check scripts, CI) need computed values.
+
+Run LibreOffice or a dedicated recalc step before delivery:
+
+```bash
+# LibreOffice headless recalc
+libreoffice --headless --calc --convert-to xlsx ./out/model.xlsx --outdir ./out/
+```
+
+Or use a Python recalc helper (see `scripts/recalc.py` in this skill).
+
+## Model layout planning
+
+Before writing any formula:
+1. Define ALL section row positions
+2. Write ALL headers and labels
+3. Write ALL section dividers and blank rows
+4. THEN write formulas using the locked row positions
+
+This prevents the cascading-formula-breakage pattern where inserting a header row after formulas are written shifts every downstream reference.
+
+## Verify step-by-step with the user
+
+For large models (DCFs, 3-statement, LBO), stop and show the user intermediate artifacts before continuing. Catching a wrong margin assumption before you've built downstream sensitivity tables saves an hour.
+
+Checkpoint pattern:
+- After Inputs block → show raw inputs, confirm before projecting
+- After Revenue projections → confirm top line + growth
+- After FCF build → confirm the full schedule
+- After WACC → confirm inputs
+- After valuation → confirm the equity bridge
+- THEN build sensitivity tables
+
+## When NOT to use this skill
+
+- Users in a live Excel session with an Office MCP available — drive their live workbook instead.
+- Pure tabular data export with no formulas — `csv` or `pandas.to_excel` is simpler.
+- Dashboards / charts with heavy interactivity — use a real BI tool.
+
+## Attribution
+
+Conventions (blue/black/green, formulas-over-hardcodes, named ranges, sensitivity rules) adapted from Anthropic's Claude for Financial Services plugin suite, Apache-2.0 licensed. Original: https://github.com/anthropics/financial-services/tree/main/plugins/vertical-plugins/financial-analysis/skills/xlsx-author
@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Recalculate an .xlsx file's formulas using LibreOffice headless.
+
+Usage: python recalc.py <path.xlsx> [timeout_seconds]
+
+openpyxl writes formula strings but does not compute them. Downstream scripts
+that open the file with data_only=True get None for every formula cell until
+something has actually calculated the workbook. Excel does this on open;
+headless pipelines need LibreOffice (or similar) to do it explicitly.
+
+Exits 0 on success (workbook recomputed and resaved in place), non-zero on
+failure. Writes status JSON to stdout either way.
+"""
+
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def find_libreoffice() -> str | None:
+    for cmd in ("libreoffice", "soffice"):
+        path = shutil.which(cmd)
+        if path:
+            return path
+    return None
+
+
+def recalc(xlsx_path: str, timeout: int = 60) -> dict:
+    src = Path(xlsx_path).resolve()
+    if not src.exists():
+        return {"status": "error", "error": f"File not found: {src}"}
+
+    lo = find_libreoffice()
+    if lo is None:
+        return {
+            "status": "error",
+            "error": "libreoffice not found on PATH — install it or recalc in a real Excel session",
+        }
+
+    with tempfile.TemporaryDirectory() as td:
+        try:
+            subprocess.run(
+                [
+                    lo,
+                    "--headless",
+                    "--calc",
+                    "--convert-to",
+                    "xlsx",
+                    str(src),
+                    "--outdir",
+                    td,
+                ],
+                check=True,
+                capture_output=True,
+                timeout=timeout,
+            )
+        except subprocess.TimeoutExpired:
+            return {"status": "error", "error": f"libreoffice timed out after {timeout}s"}
+        except subprocess.CalledProcessError as e:
+            return {
+                "status": "error",
+                "error": f"libreoffice exited {e.returncode}: {e.stderr.decode(errors='replace')[:500]}",
+            }
+
+        produced = Path(td) / src.name
+        if not produced.exists():
+            return {"status": "error", "error": "libreoffice did not produce output file"}
+
+        shutil.copy(produced, src)
+
+    return {"status": "success", "file": str(src)}
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python recalc.py <path.xlsx> [timeout_seconds]", file=sys.stderr)
+        sys.exit(2)
+    timeout = int(sys.argv[2]) if len(sys.argv) > 2 else 60
+    result = recalc(sys.argv[1], timeout=timeout)
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["status"] == "success" else 1)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,290 @@
+---
+name: lbo-model
+description: Build leveraged buyout models in Excel — sources & uses, debt schedule, cash sweep, exit multiple, IRR/MOIC sensitivity. Pairs with excel-author. Use for PE screening, sponsor-case valuation, or illustrative LBO in a pitch.
+version: 1.0.0
+author: Anthropic (adapted by Nous Research)
+license: Apache-2.0
+metadata:
+  hermes:
+    tags: [finance, valuation, lbo, private-equity, excel, openpyxl, modeling]
+    related_skills: [excel-author, pptx-author, dcf-model, 3-statement-model]
+---
+
+## Environment
+
+This skill assumes **headless openpyxl** — you are producing an .xlsx file on disk.
+Follow the `excel-author` skill's conventions for cell coloring, formulas, named ranges, and sensitivity tables.
+Recalculate before delivery: `python /path/to/excel-author/scripts/recalc.py ./out/model.xlsx`.
+
+---
+
+## TEMPLATE REQUIREMENT
+
+**This skill uses templates for LBO models. Always check for an attached template file first.**
+
+Before starting any LBO model:
+1. **If a template file is attached/provided**: Use that template's structure exactly - copy it and populate with the user's data
+2. **If no template is attached**: Ask the user: *"Do you have a specific LBO template you'd like me to use? If not, I can use the standard template which includes Sources & Uses, Operating Model, Debt Schedule, and Returns Analysis."*
+3. **If using the standard template**: Copy `examples/LBO_Model.xlsx` as your starting point and populate it with the user's assumptions
+
+**IMPORTANT**: When a file like `LBO_Model.xlsx` is attached, you MUST use it as your template - do not build from scratch. Even if the template seems complex or has more features than needed, copy it and adapt it to the user's requirements. Never decide to "build from scratch" when a template is provided.
+
+---
+
+## CRITICAL INSTRUCTIONS — READ FIRST
+
+Use Python/openpyxl. Write formula strings (`ws["D20"] = "=B5*B6"`), then run the `excel-author` skill's `recalc.py` helper before delivery.
+
+### Core Principles
+* **Every calculation must be an Excel formula** - NEVER compute values in Python and hardcode results into cells. When using openpyxl, write `cell.value = "=B5*B6"` (formula string), NOT `cell.value = 1250` (computed result). The model must be dynamic and update when inputs change.
+* **Use the template structure** - Follow the organization in `examples/LBO_Model.xlsx` or the user's provided template. Do not invent your own layout.
+* **Use proper cell references** - All formulas should reference the appropriate cells. Never type numbers that should come from other cells.
+* **Maintain sign convention consistency** - Follow whatever sign convention the template uses (some use negative for outflows, some use positive). Be consistent throughout.
+* **Work section by section, verify with user at each step** - Complete one section fully, show the user what was built, run the section's verification checks, and get confirmation BEFORE moving to the next section. Do NOT build the entire model end-to-end and then present it — later sections depend on earlier ones, so catching a mistake in Sources & Uses after the returns are already built means rework everywhere.
+
+### Formula Color Conventions
+* **Blue (0000FF)**: Hardcoded inputs - typed numbers that don't reference other cells
+* **Black (000000)**: Formulas with calculations - any formula using operators or functions (`=B4*B5`, `=SUM()`, `=-MAX(0,B4)`)
+* **Purple (800080)**: Links to cells on the **same tab** - direct references with no calculation (`=B9`, `=B45`)
+* **Green (008000)**: Links to cells on **different tabs** - cross-sheet references (`=Assumptions!B5`, `='Operating Model'!C10`)
+
+### Fill Color Palette — Professional Blues & Greys (Default unless user/template specifies otherwise)
+* **Keep it minimal** — only use blues and greys for cell fills. Do NOT introduce greens, yellows, reds, or multiple accents. A professional LBO model uses restraint.
+* **Default fill palette:**
+  * **Section headers** (Sources & Uses, Operating Model, etc.): Dark blue `#1F4E79` with white bold text
+  * **Column headers** (Year 1, Year 2, etc.): Light blue `#D9E1F2` with black bold text
+  * **Input cells**: Light grey `#F2F2F2` (or just white) — the blue *font* is the signal, fill is secondary
+  * **Formula/calculated cells**: White, no fill
+  * **Key outputs** (IRR, MOIC, Exit Equity): Medium blue `#BDD7EE` with black bold text
+* **That's the whole palette.** 3 blues + 1 grey + white. If the template uses its own colors, follow the template instead.
+* Note: The blue/black/purple/green **font** colors above are for distinguishing inputs vs formulas vs links. Those are separate from the **fill** palette here — both work together.
+
+### Number Formatting Standards
+* **Currency**: `$#,##0;($#,##0);"-"` or `$#,##0.0` depending on template
+* **Percentages**: `0.0%` (one decimal)
+* **Multiples**: `0.0"x"` (one decimal)
+* **MOIC/Detailed Ratios**: `0.00"x"` (two decimals for precision)
+* **All numeric cells**: Right-aligned
+
+---
+
+### Clarify Requirements First
+
+Before filling any formulas:
+
+* **Examine the template structure** - Identify all sections, understand the timeline (which columns are which periods), note any existing formulas
+* **Ask the user if anything is unclear** - If the template structure, calculation methods, or requirements are ambiguous, ask before proceeding
+* **Confirm key assumptions** - Any key inputs, calculation preferences, or specific requirements
+* **ONLY AFTER understanding the template**, proceed to fill in formulas
+
+---
+
+## TEMPLATE ANALYSIS PHASE - DO THIS FIRST
+
+Before filling any formulas, examine the template thoroughly:
+
+1. **Map the structure** - Identify where each section lives and how they relate to each other. Note which sections feed into others.
+
+2. **Understand the timeline** - Which columns represent which periods? Is there a "Closing" or "Pro Forma" column? Where does the projection period start?
+
+3. **Identify input vs formula cells** - Templates often use color coding, borders, or shading to indicate which cells need inputs vs formulas. Respect these conventions.
+
+4. **Read existing labels carefully** - The row labels tell you exactly what calculation is expected. Don't assume - read what the template is asking for.
+
+5. **Check for existing formulas** - Some templates come partially filled. Don't overwrite working formulas unless specifically asked.
+
+6. **Note template-specific conventions** - Sign conventions, subtotal structures, how sections are organized, whether there are separate tabs for different components, etc.
+
+---
+
+## FILLING FORMULAS - GENERAL APPROACH
+
+For each cell that needs a formula, follow this hierarchy:
+
+### Step 1: Check the Template
+* Does the cell already have a formula? If yes, verify it's correct and move on.
+* Is there a comment or note indicating the expected calculation?
+* Does the row/column label make the calculation obvious?
+* Do neighboring cells show a pattern you should follow?
+
+### Step 2: Check the User's Instructions
+* Did the user specify a particular calculation method?
+* Are there stated assumptions that affect this formula?
+* Any special requirements mentioned?
+
+### Step 3: Apply Standard Practice
+* If neither template nor user specifies, use standard LBO modeling conventions
+* Document any assumptions you make
+* If genuinely uncertain, ask the user
+
+---
+
+## COMMON PROBLEM AREAS
+
+The following calculation patterns frequently cause issues across LBO models. Pay special attention when you encounter these:
+
+### Balancing Sections
+* When two sections must equal (e.g., Sources = Uses), one item is typically the "plug" (balancing figure)
+* Identify which item is the plug and calculate it as the difference
+
+### Tax Calculations
+* Tax formulas should only reference the relevant income line and tax rate
+* Should NOT reference unrelated sections (e.g., debt schedules)
+* Consider whether losses create tax shields or are simply ignored
+
+### Interest and Circular References
+* Interest calculations can create circularity if they reference balances affected by cash flows
+* Use **Beginning Balance** (not average or ending) to break circular references
+* Pattern: Interest → Cash Flow → Paydown → Ending Balance (if interest uses ending balance, this circles back)
+
+### Debt Paydown / Cash Sweeps
+* When multiple debt tranches exist, there's usually a priority order
+* Cash sweep should respect the priority waterfall
+* Balances cannot go negative - use MAX or MIN functions appropriately
+
+### Returns Calculations (IRR/MOIC)
+* Cash flows must have correct signs: Investment = negative, Proceeds = positive
+* If using XIRR, need corresponding dates
+* If using IRR, cash flows should be in consecutive periods
+* MOIC = Total Proceeds / Total Investment
+
+### Sensitivity Tables
+* **Use ODD dimensions** (5×5 or 7×7) — never 4×4 or 6×6. Odd dimensions guarantee a true center cell.
+* **Center cell = base case.** Build the row and column axis values symmetrically around the model's actual assumptions (e.g., if base entry multiple = 10.0x, axis = `[8.0x, 9.0x, 10.0x, 11.0x, 12.0x]`). The center cell's IRR/MOIC MUST then equal the model's actual IRR/MOIC output — this is the proof the table is wired correctly.
+* **Highlight the center cell** — medium-blue fill (`#BDD7EE`) + bold font so the base case is visually anchored.
+* Excel's DATA TABLE function may not work with openpyxl — instead write explicit formulas that reference row/column headers
+* Each cell should show a DIFFERENT value — if all same, formulas aren't varying correctly
+* Use mixed references (e.g., `$A5` for row input, `B$4` for column input)
+
+---
+
+## VERIFICATION CHECKLIST - RUN AFTER COMPLETION
+
+### Run Formula Validation
+```bash
+python /path/to/excel-author/scripts/recalc.py model.xlsx
+```
+Must return success with zero errors.
+
+### Section Balancing
+- [ ] Any sections that must balance (Sources/Uses, Assets/Liabilities) balance exactly
+- [ ] Plug items are calculated correctly as the balancing figure
+- [ ] Amounts that should match across sections are consistent
+
+### Income/Operating Projections
+- [ ] Revenue/top-line builds correctly from drivers or growth rates
+- [ ] All cost and expense items calculated appropriately
+- [ ] Subtotals and totals sum correctly
+- [ ] Margins and ratios are reasonable
+- [ ] Links to assumptions are correct
+
+### Balance Sheet (if applicable)
+- [ ] Assets = Liabilities + Equity (must balance)
+- [ ] All items link to appropriate schedules or roll-forwards
+- [ ] Beginning balances = prior period ending balances
+- [ ] Check row included and shows zero
+
+### Cash Flow (if applicable)
+- [ ] Starts with correct income figure
+- [ ] Non-cash items added/subtracted appropriately
+- [ ] Working capital changes have correct signs
+- [ ] Ending Cash = Beginning Cash + Net Cash Flow
+- [ ] Cash balances are consistent across statements
+
+### Supporting Schedules
+- [ ] Roll-forward schedules balance (Beginning + Changes = Ending)
+- [ ] Schedules link correctly to main statements
+- [ ] Calculated items use appropriate drivers
+- [ ] All periods are calculated consistently
+
+### Debt/Financing Schedules (if applicable)
+- [ ] Beginning balances tie to sources or prior period
+- [ ] Interest calculated on appropriate balance (typically beginning)
+- [ ] Paydowns respect cash availability and priority
+- [ ] Ending balances cannot be negative
+- [ ] Totals sum tranches correctly
+
+### Returns/Output Analysis
+- [ ] Exit/terminal values calculated correctly
+- [ ] All relevant adjustments included
+- [ ] Cash flow signs are correct (negative for investment, positive for proceeds)
+- [ ] IRR/MOIC formulas reference complete ranges
+- [ ] Results are reasonable for the scenario
+
+### Sensitivity Tables (if applicable)
+- [ ] Grid dimensions are ODD (5×5 or 7×7) — there is a true center cell
+- [ ] Row and column axis values are symmetric around the base case (`[base-2Δ, base-Δ, base, base+Δ, base+2Δ]`)
+- [ ] Center cell output equals the model's actual IRR/MOIC — confirms the table is wired correctly
+- [ ] Center cell is highlighted (medium-blue fill `#BDD7EE`, bold font)
+- [ ] Row and column headers contain appropriate input values
+- [ ] Each data cell contains a formula (not hardcoded)
+- [ ] Each data cell shows a DIFFERENT value
+- [ ] Values move in expected directions (higher exit multiple → higher IRR, etc.)
+
+### Formatting
+- [ ] Hardcoded inputs are blue (0000FF)
+- [ ] Calculated formulas are black (000000)
+- [ ] Same-tab links are purple (800080)
+- [ ] Cross-tab links are green (008000)
+- [ ] All numbers are right-aligned
+- [ ] Appropriate number formats applied throughout
+- [ ] No cells show error values (#REF!, #DIV/0!, #VALUE!, #NAME?)
+
+### Logical Sanity Checks
+- [ ] Numbers are reasonable order of magnitude
+- [ ] Trends make sense (growth, decline, stabilization as expected)
+- [ ] No obviously wrong values (negative where should be positive, impossible percentages, etc.)
+- [ ] Key outputs are within reasonable ranges for the type of analysis
+
+---
+
+## COMMON ERRORS TO AVOID
+
+| Error | What Goes Wrong | How to Fix |
+|-------|-----------------|------------|
+| Hardcoding calculated values | Model doesn't update when inputs change | Always use formulas that reference source cells |
+| Wrong cell references after copying | Formulas point to wrong cells | Verify all links, use appropriate $ anchoring |
+| Circular reference errors | Model can't calculate | Use beginning balances for interest-type calcs, break the circle |
+| Sections don't balance | Totals that should match don't | Ensure one item is the plug (calculated as difference) |
+| Negative balances where impossible | Paying/using more than available | Use MAX(0, ...) or MIN functions appropriately |
+| IRR/return errors | Wrong signs or incomplete ranges | Check cash flow signs and ensure formula covers all periods |
+| Sensitivity table shows same value | Formula not varying with inputs | Check cell references - need mixed references ($A5, B$4) |
+| Roll-forwards don't tie | Beginning ≠ prior ending | Verify links between periods |
+| Inconsistent sign conventions | Additions become subtractions or vice versa | Follow template's convention consistently throughout |
+
+---
+
+## WORKING WITH THE USER — SECTION-BY-SECTION CHECKPOINTS
+
+* **If the template structure is unclear**, ask before proceeding
+* **If the user's requirements conflict with the template**, confirm their preference
+* **After completing each major section**, STOP and verify with the user before continuing:
+  - **After Sources & Uses** → show the balanced table, confirm the plug is correct, get sign-off before building the operating model
+  - **After Operating Model / Projections** → show the projected P&L, confirm growth rates and margins look right, get sign-off before the debt schedule
+  - **After Debt Schedule** → show beginning/ending balances and interest, confirm the waterfall logic, get sign-off before returns
+  - **After Returns (IRR/MOIC)** → show the cash flow series and outputs, confirm signs and ranges, get sign-off before sensitivity tables
+  - **After Sensitivity Tables** → show that each cell varies, confirm the base case lands where expected
+* **If errors are found during verification**, fix them before moving to the next section
+* **Show your work** - explain key formulas or assumptions when helpful
+* **Never present a completed model without having checked in at each section** — it's faster to catch a wrong cell reference at the source than to trace it backwards from a broken IRR
+
+---
+
+**This skill produces investment banking-quality LBO models by filling templates with correct formulas, proper formatting, and validated calculations. The skill adapts to any template structure while ensuring financial accuracy and professional presentation standards.**
+
+
+## Data sources — MCP first, web fallback
+
+Many passages below say "use the S&P Kensho MCP / Daloopa MCP / FactSet MCP". Those are commercial financial-data MCPs from the original Cowork plugin context. In Hermes:
+
+- **If you have any structured financial-data MCP configured** (Hermes supports MCP — see `native-mcp` skill), prefer it for point-in-time comps, precedent transactions, and filings.
+- **Otherwise**, fall back to:
+  - `web_search` / `web_extract` against SEC EDGAR (`https://www.sec.gov/cgi-bin/browse-edgar`) for US filings
+  - Company IR pages for press releases, earnings decks
+  - `browser_navigate` for interactive data portals
+  - User-provided data (explicitly ask when the context doesn't have it)
+- **Never fabricate**. If a multiple, precedent, or filing number can't be sourced, flag the cell as `[UNSOURCED]` and surface it to the user.
+
+## Attribution
+
+This skill is adapted from Anthropic's Claude for Financial Services plugin suite (Apache-2.0). The Office-JS / Cowork live-Excel paths have been removed; this version targets headless openpyxl via the `excel-author` skill's conventions. Original: https://github.com/anthropics/financial-services
@@ -0,0 +1,143 @@
+---
+name: merger-model
+description: Build accretion/dilution (merger) models in Excel — pro-forma P&L, synergies, financing mix, EPS impact. Pairs with excel-author. Use for M&A pitches, board materials, or deal evaluation.
+version: 1.0.0
+author: Anthropic (adapted by Nous Research)
+license: Apache-2.0
+metadata:
+  hermes:
+    tags: [finance, m-and-a, merger, accretion-dilution, excel, openpyxl, modeling, investment-banking]
+    related_skills: [excel-author, pptx-author, dcf-model, 3-statement-model]
+---
+
+## Environment
+
+This skill assumes **headless openpyxl** — you are producing an .xlsx file on disk.
+Follow the `excel-author` skill's conventions for cell coloring, formulas, named ranges, and sensitivity tables.
+Recalculate before delivery: `python /path/to/excel-author/scripts/recalc.py ./out/model.xlsx`.
+
+# Merger Model
+
+Build accretion/dilution analysis for M&A transactions. Models pro forma EPS impact, synergy sensitivities, and purchase price allocation. Use when evaluating a potential acquisition, preparing merger consequences analysis for a pitch, or advising on deal terms.
+
+## Workflow
+
+### Step 1: Gather Inputs
+
+**Acquirer:**
+- Company name, current share price, shares outstanding
+- LTM and NTM EPS (GAAP and adjusted)
+- P/E multiple
+- Pre-tax cost of debt, tax rate
+- Cash on balance sheet, existing debt
+
+**Target:**
+- Company name, current share price, shares outstanding (if public)
+- LTM and NTM EPS or net income
+- Enterprise value or equity value
+
+**Deal Terms:**
+- Offer price per share (or premium to current)
+- Consideration mix: % cash vs. % stock
+- New debt raised to fund cash portion
+- Expected synergies (revenue and cost) and phase-in timeline
+- Transaction fees and financing costs
+- Expected close date
+
+### Step 2: Purchase Price Analysis
+
+| Item | Value |
+|------|-------|
+| Offer price per share | |
+| Premium to current | |
+| Equity value | |
+| Plus: net debt assumed | |
+| Enterprise value | |
+| EV / EBITDA implied | |
+| P/E implied | |
+
+### Step 3: Sources & Uses
+
+| Sources | $ | Uses | $ |
+|---------|---|------|---|
+| New debt | | Equity purchase price | |
+| Cash on hand | | Refinance target debt | |
+| New equity issued | | Transaction fees | |
+| | | Financing fees | |
+| **Total** | | **Total** | |
+
+### Step 4: Pro Forma EPS (Accretion / Dilution)
+
+Calculate year-by-year (Year 1-3):
+
+| | Standalone | Pro Forma | Accretion/(Dilution) |
+|---|-----------|-----------|---------------------|
+| Acquirer net income | | | |
+| Target net income | | | |
+| Synergies (after tax) | | | |
+| Foregone interest on cash (after tax) | | | |
+| New debt interest (after tax) | | | |
+| Intangible amortization (after tax) | | | |
+| Pro forma net income | | | |
+| Pro forma shares | | | |
+| **Pro forma EPS** | | | |
+| **Accretion / (Dilution) %** | | | |
+
+### Step 5: Sensitivity Analysis
+
+**Accretion/Dilution vs. Synergies and Offer Premium:**
+
+| | $0M syn | $25M syn | $50M syn | $75M syn | $100M syn |
+|---|---------|----------|----------|----------|-----------|
+| 15% premium | | | | | |
+| 20% premium | | | | | |
+| 25% premium | | | | | |
+| 30% premium | | | | | |
+
+**Accretion/Dilution vs. Cash/Stock Mix:**
+
+| | 100% cash | 75/25 | 50/50 | 25/75 | 100% stock |
+|---|-----------|-------|-------|-------|------------|
+| Year 1 | | | | | |
+| Year 2 | | | | | |
+
+### Step 6: Breakeven Synergies
+
+Calculate the minimum synergies needed for the deal to be EPS-neutral in Year 1.
+
+### Step 7: Output
+
+- Excel workbook with:
+  - Assumptions tab
+  - Sources & uses
+  - Pro forma income statement
+  - Accretion/dilution summary
+  - Sensitivity tables
+  - Breakeven analysis
+- One-page merger consequences summary for pitch book
+
+## Important Notes
+
+- Always show both GAAP and adjusted (cash) EPS where relevant
+- Stock deals: use acquirer's current price for exchange ratio, note dilution from new shares
+- Include purchase price allocation — goodwill and intangible amortization matter for GAAP EPS
+- Synergy phase-in is critical — Year 1 is often only 25-50% of run-rate synergies
+- Don't forget foregone interest income on cash used and new interest expense on debt raised
+- Tax rate on synergies and interest adjustments should match the acquirer's marginal rate
+
+
+## Data sources — MCP first, web fallback
+
+Many passages below say "use the S&P Kensho MCP / Daloopa MCP / FactSet MCP". Those are commercial financial-data MCPs from the original Cowork plugin context. In Hermes:
+
+- **If you have any structured financial-data MCP configured** (Hermes supports MCP — see `native-mcp` skill), prefer it for point-in-time comps, precedent transactions, and filings.
+- **Otherwise**, fall back to:
+  - `web_search` / `web_extract` against SEC EDGAR (`https://www.sec.gov/cgi-bin/browse-edgar`) for US filings
+  - Company IR pages for press releases, earnings decks
+  - `browser_navigate` for interactive data portals
+  - User-provided data (explicitly ask when the context doesn't have it)
+- **Never fabricate**. If a multiple, precedent, or filing number can't be sourced, flag the cell as `[UNSOURCED]` and surface it to the user.
+
+## Attribution
+
+This skill is adapted from Anthropic's Claude for Financial Services plugin suite (Apache-2.0). The Office-JS / Cowork live-Excel paths have been removed; this version targets headless openpyxl via the `excel-author` skill's conventions. Original: https://github.com/anthropics/financial-services
@@ -0,0 +1,172 @@
+---
+name: pptx-author
+description: Build PowerPoint decks headless with python-pptx. Pairs with excel-author for model-backed decks where every number traces to a workbook cell. Use for pitch decks, IC memos, earnings notes.
+version: 1.0.0
+author: Anthropic (adapted by Nous Research)
+license: Apache-2.0
+metadata:
+  hermes:
+    tags: [powerpoint, pptx, python-pptx, presentation, finance]
+    related_skills: [excel-author, powerpoint]
+---
+
+# pptx-author
+
+Produce a .pptx file on disk using `python-pptx`. Use when you need to deliver a deck as a file artifact, not drive a live PowerPoint session.
+
+Adapted from Anthropic's `pptx-author` and `pitch-deck` skills in [anthropics/financial-services](https://github.com/anthropics/financial-services). The MCP / Office-JS branches of the originals are dropped — this assumes headless Python.
+
+For the broader, already-shipped PowerPoint authoring skill (slides, speaker notes, embeds, media), see the built-in `powerpoint` skill. This skill is a lighter-weight pattern tuned for model-backed decks (pitch decks, IC memos, earnings notes) where every number must trace to a source workbook.
+
+## Output contract
+
+- Write to `./out/<name>.pptx`. Create `./out/` if it does not exist.
+- Return the relative path in your final message.
+
+## Setup
+
+```bash
+pip install "python-pptx>=0.6"
+```
+
+## Core conventions
+
+### One idea per slide
+Title states the takeaway; body supports it. A slide titled "Q3 Revenue" is weak; "Revenue growth accelerated to 14% Y/Y in Q3" is strong.
+
+### Every number traces to the model
+If a figure on a slide came from `./out/model.xlsx`, footnote the sheet and cell.
+
+```
+Revenue: $1,250M  (Source: model.xlsx, Inputs!C3)
+```
+
+Never transcribe numbers from memory or from a summary — open the workbook, read the named range, and bind the deck value to it programmatically when you can.
+
+### Use the firm template when one is mounted
+If `./templates/firm-template.pptx` exists, load it so the deck inherits branded colors, fonts, and master layouts.
+
+```python
+from pptx import Presentation
+from pathlib import Path
+
+template = Path("./templates/firm-template.pptx")
+prs = Presentation(str(template)) if template.exists() else Presentation()
+```
+
+### Charts: PNG-from-model beats native pptx charts
+When fidelity matters (the model's chart styling must match the deck exactly), render the chart to PNG from the source workbook and embed the image. Native `pptx.chart` charts are fragile and often don't match firm conventions.
+
+```python
+from pptx.util import Inches
+slide.shapes.add_picture("./out/charts/football_field.png",
+                         Inches(1), Inches(2),
+                         width=Inches(8))
+```
+
+### No external sends
+This skill writes a file. It never emails, uploads, or posts. Orchestration layers handle delivery.
+
+## Skeleton
+
+```python
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.dml.color import RGBColor
+from pathlib import Path
+
+template = Path("./templates/firm-template.pptx")
+prs = Presentation(str(template)) if template.exists() else Presentation()
+
+# Title slide
+slide = prs.slides.add_slide(prs.slide_layouts[0])
+slide.shapes.title.text = "Project Aurora — Strategic Alternatives"
+slide.placeholders[1].text = "Preliminary Discussion Materials"
+
+# Valuation summary slide (title-only layout)
+slide = prs.slides.add_slide(prs.slide_layouts[5])
+slide.shapes.title.text = "Valuation implies $38–$52 per share across methodologies"
+
+# Add a table bound to model outputs
+rows, cols = 5, 4
+tbl_shape = slide.shapes.add_table(rows, cols,
+                                   Inches(0.5), Inches(1.5),
+                                   Inches(9), Inches(3))
+tbl = tbl_shape.table
+headers = ["Methodology", "Low ($)", "Mid ($)", "High ($)"]
+for c, h in enumerate(headers):
+    tbl.cell(0, c).text = h
+
+# In a real deck, read these from the model workbook with openpyxl
+data = [
+    ("Trading comps",     "35", "41", "48"),
+    ("Precedent M&A",     "39", "45", "52"),
+    ("DCF (base)",        "36", "43", "51"),
+    ("LBO (10% IRR)",     "33", "38", "44"),
+]
+for r, row in enumerate(data, start=1):
+    for c, val in enumerate(row):
+        tbl.cell(r, c).text = val
+
+# Embed a chart rendered from the model
+slide = prs.slides.add_slide(prs.slide_layouts[5])
+slide.shapes.title.text = "Football field — current price $42"
+slide.shapes.add_picture("./out/charts/football_field.png",
+                         Inches(1), Inches(1.8), width=Inches(8))
+
+Path("./out").mkdir(exist_ok=True)
+prs.save("./out/pitch-aurora.pptx")
+```
+
+## Binding deck numbers to the source workbook
+
+Read named ranges or specific cells from your Excel model so deck numbers never drift.
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook("./out/model.xlsx", data_only=True)
+def nr(name):
+    """Resolve a named range to its current computed value."""
+    rng = wb.defined_names[name]
+    sheet, coord = next(rng.destinations)
+    return wb[sheet][coord].value
+
+revenue_fy24 = nr("RevenueFY24")
+implied_mid  = nr("ImpliedSharePriceBase")
+```
+
+Then build deck content using those values:
+```python
+slide.shapes.title.text = f"Implied share price of ${implied_mid:.2f} (base case)"
+```
+
+Remember to recalculate the workbook before reading it — openpyxl only sees computed values if something has already calculated the sheet. Run the recalc helper in the `excel-author` skill first, or open/save through a real Excel session.
+
+## Slide-type checklist for pitch decks
+
+A typical banking pitch deck follows this structure. Not prescriptive, but useful as a starting skeleton:
+
+1. Cover / title
+2. Disclaimer
+3. Table of contents
+4. Situation overview
+5. Company snapshot (the target)
+6. Market / sector context
+7. Valuation summary (football field) — the money slide
+8. Trading comps detail
+9. Precedent transactions detail
+10. DCF summary
+11. Illustrative LBO / sponsor case
+12. Process considerations
+13. Appendix
+
+## When NOT to use this skill
+
+- Users in a live PowerPoint session with an Office MCP available — drive their live doc instead.
+- Non-financial slideware (quarterly all-hands, marketing decks) — use the broader `powerpoint` skill.
+- Decks with heavy animation, transitions, or speaker notes — use the broader `powerpoint` skill.
+
+## Attribution
+
+Conventions adapted from Anthropic's Claude for Financial Services plugin suite, Apache-2.0 licensed. Original: https://github.com/anthropics/financial-services/tree/main/plugins/agent-plugins/pitch-agent/skills/pptx-author
@@ -97,6 +97,12 @@
  const API = "/api/plugins/kanban";
  const MIME_TASK = "text/x-hermes-task";

+  // Docs link — surfaced as a `?` icon next to the board switcher and as
+  // `title=` hints on unlabelled controls. Kept in one place so rebrands or
+  // path changes are a single edit.
+  const DOCS_URL = "https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban";
+  const DOCS_TUTORIAL_URL = "https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban-tutorial";
+
  // localStorage key for the user's selected board. Independent of the
  // CLI's on-disk ``<root>/kanban/current`` pointer so browser users
  // can inspect any board without shifting the CLI's active board out
@@ -112,17 +118,30 @@

  function writeSelectedBoard(slug) {
    try {
-      if (slug && slug !== "default") window.localStorage.setItem(LS_BOARD_KEY, slug);
+      // Persist the user's dashboard-side board pin even for "default".
+      // Previously this stripped "default" to keep localStorage empty,
+      // but the fetch layer read that absence as "no opinion" and fell
+      // through to the server-side ``current`` file — which the board
+      // switcher also writes. Result: selecting the default tab after
+      // creating a new board with "switch" checked showed the new
+      // board's (wrong) data because the URL omitted ``?board=`` and
+      // the backend happily returned whichever board was "current".
+      // Persisting every selection keeps the dashboard's board opinion
+      // independent of the CLI's active board, which was the original
+      // design intent. Regression: #20879.
+      if (slug) window.localStorage.setItem(LS_BOARD_KEY, slug);
      else window.localStorage.removeItem(LS_BOARD_KEY);
    } catch (_e) { /* ignore quota / private mode */ }
  }

  function withBoard(url, board) {
-    // Append ?board=<slug> when a non-default board is active. Omitted
-    // for default so the URL stays clean and the backend falls through
-    // to its own resolution chain (env var → ``current`` file →
-    // default) which is already correct.
-    if (!board || board === "default") return url;
+    // Always append ?board=<slug> when we have one picked — including
+    // "default". Omitting the param would fall through to the backend's
+    // resolution chain (env var → ``current`` file → default), which
+    // means the dashboard's tab selection gets silently overridden by
+    // whatever board the CLI or "switch" checkbox last activated.
+    // Regression: #20879.
+    if (!board) return url;
    const sep = url.indexOf("?") >= 0 ? "&" : "?";
    return `${url}${sep}board=${encodeURIComponent(board)}`;
  }
@@ -447,9 +466,11 @@
          token: token,
        };
        // Pin the WS stream to the currently-selected board so events
-        // from other boards don't bleed in. Only set for non-default so
-        // single-board installs keep the cleaner URL.
-        if (board && board !== "default") qsParams.board = board;
+        // from other boards don't bleed in. Includes "default" so the
+        // dashboard's own board pin always wins over the server-side
+        // ``current`` file — same rationale as ``withBoard()`` above.
+        // Regression: #20879.
+        if (board) qsParams.board = board;
        const qs = new URLSearchParams(qsParams);
        const url = `${proto}//${window.location.host}${API}/events?${qs}`;
        let ws;
@@ -496,6 +517,7 @@
      if (!boardData) return null;
      const q = search.trim().toLowerCase();
      const filterTask = function (t) {
+        if (tenantFilter && t.tenant !== tenantFilter) return false;
        if (assigneeFilter && t.assignee !== assigneeFilter) return false;
        if (q) {
          const hay = `${t.id} ${t.title || ""} ${t.assignee || ""} ${t.tenant || ""}`.toLowerCase();
@@ -508,7 +530,7 @@
          return Object.assign({}, col, { tasks: col.tasks.filter(filterTask) });
        }),
      });
-    }, [boardData, assigneeFilter, search]);
+    }, [boardData, tenantFilter, assigneeFilter, search]);

    // --- actions ------------------------------------------------------------
    const moveTask = useCallback(function (taskId, newStatus) {
@@ -1112,6 +1134,20 @@
  // Board switcher (multi-project)
  // -------------------------------------------------------------------------

+  // Small `?` affordance next to the board controls. Opens the kanban docs
+  // page in a new tab so users can look up what any of the widgets mean
+  // without losing the current board view.
+  function DocsLink() {
+    return h("a", {
+      href: DOCS_URL,
+      target: "_blank",
+      rel: "noopener noreferrer",
+      className: "hermes-kanban-docs-link",
+      title: "Open Hermes Kanban docs in a new tab",
+      "aria-label": "Hermes Kanban documentation",
+    }, "?");
+  }
+
  function BoardSwitcher(props) {
    const list = props.boardList || [];
    const current = list.find(function (b) { return b.slug === props.board; });
@@ -1136,6 +1172,7 @@
          size: "sm",
          className: "h-7 text-xs",
        }, "+ New board"),
+        h(DocsLink, null),
      );
    }

@@ -1149,6 +1186,7 @@
              value: props.board,
              className: "h-8 min-w-[220px]",
              "aria-label": "Switch kanban board",
+              title: "Boards are independent work streams. Each board has its own tasks, tenants, and assignees.",
            }, selectChangeHandler(function (v) { if (v) props.onSwitch(v); })),
              list.map(function (b) {
                const label = b.total > 0
@@ -1162,10 +1200,12 @@
          ),
        ),
        h("div", { className: "flex-1" }),
+        h(DocsLink, null),
        h(Button, {
          onClick: props.onNewClick,
          size: "sm",
          className: "h-8",
+          title: "Create a new board. Useful when you want an unrelated work stream (different project, different team, isolated scratch area).",
        }, "+ New board"),
        props.board !== "default"
          ? h(Button, {
@@ -1310,7 +1350,8 @@
    const tenants = (props.board && props.board.tenants) || [];
    const assignees = (props.board && props.board.assignees) || [];
    return h("div", { className: "flex flex-wrap items-end gap-3" },
-      h("div", { className: "flex flex-col gap-1" },
+      h("div", { className: "flex flex-col gap-1",
+                 title: "Fuzzy-match tasks by id, title, or description. Matches across all columns." },
        h(Label, { className: "text-xs text-muted-foreground" }, "Search"),
        h(Input, {
          placeholder: "Filter cards…",
@@ -1319,7 +1360,8 @@
          className: "w-56 h-8",
        }),
      ),
-      h("div", { className: "flex flex-col gap-1" },
+      h("div", { className: "flex flex-col gap-1",
+                 title: "Tenants are free-form tags on a task (e.g. customer, project, team). Set them via the task drawer or kanban_create." },
        h(Label, { className: "text-xs text-muted-foreground" }, "Tenant"),
        h(Select, Object.assign({
          value: props.tenantFilter,
@@ -1331,7 +1373,8 @@
          }),
        ),
      ),
-      h("div", { className: "flex flex-col gap-1" },
+      h("div", { className: "flex flex-col gap-1",
+                 title: "Filter by assigned Hermes profile. Profiles are the named agent identities that claim and work on tasks." },
        h(Label, { className: "text-xs text-muted-foreground" }, "Assignee"),
        h(Select, Object.assign({
          value: props.assigneeFilter,
@@ -1343,7 +1386,8 @@
          }),
        ),
      ),
-      h("label", { className: "flex items-center gap-2 text-xs" },
+      h("label", { className: "flex items-center gap-2 text-xs",
+                   title: "Include archived tasks in the board view. Archived tasks are hidden by default." },
        h("input", {
          type: "checkbox",
          checked: props.includeArchived,
@@ -1364,10 +1408,12 @@
      h(Button, {
        onClick: props.onNudgeDispatch,
        size: "sm",
+        title: "Wake the dispatcher to claim ready tasks now instead of waiting for the next tick. Use this after adding tasks if you want them picked up immediately.",
      }, "Nudge dispatcher"),
      h(Button, {
        onClick: props.onRefresh,
        size: "sm",
+        title: "Reload the board from the database. The board auto-refreshes on task events; this is for forcing a re-read.",
      }, "Refresh"),
    );
  }
@@ -1384,6 +1430,7 @@
      h(Button, {
        onClick: function () { props.onApply({ status: "ready" }); },
        size: "sm",
+        title: "Move selected tasks to Ready. Ready tasks are picked up by the dispatcher on the next tick.",
      }, "→ ready"),
      h(Button, {
        onClick: function () {
@@ -1391,6 +1438,7 @@
            `Mark ${props.count} task(s) as done?`);
        },
        size: "sm",
+        title: "Mark selected tasks as done. Releases any claims and unblocks dependent children. You'll be asked for a completion summary.",
      }, "Complete"),
      h(Button, {
        onClick: function () {
@@ -1398,8 +1446,10 @@
            `Archive ${props.count} task(s)?`);
        },
        size: "sm",
+        title: "Archive selected tasks. They disappear from the default board view but remain in the database.",
      }, "Archive"),
-      h("div", { className: "hermes-kanban-bulk-reassign" },
+      h("div", { className: "hermes-kanban-bulk-reassign",
+                 title: "Reassign selected tasks to a different Hermes profile. Pick a profile (or unassign) and click Apply." },
        h(Select, {
          value: assignee,
          onChange: function (e) { setAssignee(e.target.value); },
@@ -1419,12 +1469,14 @@
          },
          disabled: !assignee,
          size: "sm",
+          title: "Apply the selected assignee to all selected tasks.",
        }, "Apply"),
      ),
      h("div", { className: "flex-1" }),
      h(Button, {
        onClick: props.onClear,
        size: "sm",
+        title: "Deselect all tasks and hide this bar.",
      }, "Clear"),
    );
  }
@@ -1505,11 +1557,13 @@
      onDragLeave: handleDragLeave,
      onDrop: handleDrop,
    },
-      h("div", { className: "hermes-kanban-column-header" },
+      h("div", { className: "hermes-kanban-column-header",
+                 title: COLUMN_HELP[props.column.name] || "" },
        h("span", { className: cn("hermes-kanban-dot", COLUMN_DOT[props.column.name]) }),
        h("span", { className: "hermes-kanban-column-label" },
          COLUMN_LABEL[props.column.name] || props.column.name),
-        h("span", { className: "hermes-kanban-column-count" },
+        h("span", { className: "hermes-kanban-column-count",
+                    title: `${props.column.tasks.length} task${props.column.tasks.length === 1 ? "" : "s"} in this column` },
          props.column.tasks.length),
        h("button", {
          type: "button",
@@ -1636,7 +1690,8 @@
              onClick: function (e) { e.stopPropagation(); },
              title: "Select for bulk actions",
            }),
-            h("span", { className: "hermes-kanban-card-id" }, t.id),
+            h("span", { className: "hermes-kanban-card-id",
+                        title: `Task id: ${t.id}. Use this id with kanban_show, /kanban show, or hermes kanban show.` }, t.id),
            t.warnings && t.warnings.count > 0
              ? h("span", {
                  className: cn(
@@ -1653,10 +1708,12 @@
                   t.warnings.highest_severity === "error" ? "!!" : "⚠")
              : null,
            t.priority > 0
-              ? h(Badge, { className: "hermes-kanban-priority" }, `P${t.priority}`)
+              ? h(Badge, { className: "hermes-kanban-priority",
+                           title: `Priority ${t.priority}. Higher-priority tasks are claimed first by the dispatcher.` }, `P${t.priority}`)
              : null,
            t.tenant
-              ? h(Badge, { variant: "outline", className: "hermes-kanban-tag" }, t.tenant)
+              ? h(Badge, { variant: "outline", className: "hermes-kanban-tag",
+                           title: `Tenant: ${t.tenant}. Free-form tag for grouping tasks (customer, project, team).` }, t.tenant)
              : null,
            progress
              ? h("span", {
@@ -1671,16 +1728,21 @@
          h("div", { className: "hermes-kanban-card-title" }, t.title || "(untitled)"),
          h("div", { className: "hermes-kanban-card-row hermes-kanban-card-meta" },
            t.assignee
-              ? h("span", { className: "hermes-kanban-assignee" }, "@", t.assignee)
-              : h("span", { className: "hermes-kanban-unassigned" }, "unassigned"),
+              ? h("span", { className: "hermes-kanban-assignee",
+                            title: `Assigned to Hermes profile @${t.assignee}` }, "@", t.assignee)
+              : h("span", { className: "hermes-kanban-unassigned",
+                            title: "No profile assigned. The dispatcher will pick one from available profiles when the task is Ready." }, "unassigned"),
            t.comment_count > 0
-              ? h("span", { className: "hermes-kanban-count" }, "💬 ", t.comment_count)
+              ? h("span", { className: "hermes-kanban-count",
+                            title: `${t.comment_count} comment${t.comment_count === 1 ? "" : "s"} on this task` }, "💬 ", t.comment_count)
              : null,
            t.link_counts && (t.link_counts.parents + t.link_counts.children) > 0
-              ? h("span", { className: "hermes-kanban-count" },
+              ? h("span", { className: "hermes-kanban-count",
+                            title: `${t.link_counts.parents} parent${t.link_counts.parents === 1 ? "" : "s"}, ${t.link_counts.children} child${t.link_counts.children === 1 ? "" : "ren"}. Children stay blocked until their parent is done.` },
                  "↔ ", t.link_counts.parents + t.link_counts.children)
              : null,
-            h("span", { className: "hermes-kanban-ago" },
+            h("span", { className: "hermes-kanban-ago",
+                        title: t.created_at ? `Created ${t.created_at}` : "" },
              timeAgo ? timeAgo(t.created_at) : ""),
          ),
        ),
@@ -1741,18 +1803,19 @@
      : "workspace path (optional, derived from assignee if blank)";

    return h("div", { className: "hermes-kanban-inline-create" },
-      h(Input, {
+      h("textarea", {
        value: title,
        onChange: function (e) { setTitle(e.target.value); },
        onKeyDown: function (e) {
-          if (e.key === "Enter") { e.preventDefault(); submit(); }
+          if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); submit(); }
          if (e.key === "Escape") props.onCancel();
        },
        placeholder: props.columnName === "triage"
          ? "Rough idea — AI will spec it…"
          : "New task title…",
        autoFocus: true,
-        className: "h-8 text-sm",
+        className: "text-sm min-h-[2rem] max-h-32 resize-y w-full border border-input bg-transparent px-2 py-1 rounded-md focus:outline-none focus:ring-2 focus:ring-ring",
+        rows: 2,
      }),
      h("div", { className: "flex gap-2" },
        h(Input, {
@@ -1760,6 +1823,9 @@
          onChange: function (e) { setAssignee(e.target.value); },
          placeholder: props.columnName === "triage" ? "specifier" : "assignee",
          className: "h-7 text-xs flex-1",
+          title: props.columnName === "triage"
+            ? "Hermes profile that will spec this task (default: the dispatcher's configured specifier). Leave blank to let the dispatcher pick."
+            : "Hermes profile to assign. Leave blank and the dispatcher will pick from available profiles when the task is Ready.",
        }),
        h(Input, {
          type: "number",
@@ -1767,6 +1833,7 @@
          onChange: function (e) { setPriority(e.target.value); },
          placeholder: "pri",
          className: "h-7 text-xs w-16",
+          title: "Priority. Higher-priority tasks are claimed first by the dispatcher. 0 = default.",
        }),
      ),
      h(Input, {
@@ -1798,6 +1865,7 @@
        value: parent,
        onChange: function (e) { setParent(e.target.value); },
        className: "h-7 text-xs",
+        title: "Optional parent task. A child stays blocked in its current column until the parent is marked done.",
      },
        h(SelectOption, { value: "" }, "— no parent —"),
        (props.allTasks || []).map(function (t) {
@@ -1888,6 +1956,29 @@
      }).then(function () { load(); props.onRefresh(); });
    };

+    // Triage specifier — calls the auxiliary LLM to flesh out a rough
+    // idea in the Triage column into a concrete spec (title + body with
+    // goal, approach, acceptance criteria) and promotes it to todo.
+    // Not a PATCH: runs through a dedicated POST endpoint because the
+    // LLM call can take tens of seconds, and its outcome is richer than
+    // a status flip (may update title AND body AND emit an audit
+    // comment — or fail with a human-readable reason that the UI
+    // surfaces inline without treating it as an HTTP error).
+    const doSpecify = function () {
+      return SDK.fetchJSON(
+        withBoard(`${API}/tasks/${encodeURIComponent(props.taskId)}/specify`, boardSlug),
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({}),
+        }
+      ).then(function (res) {
+        load();
+        props.onRefresh();
+        return res;
+      });
+    };
+
    const addLink = function (parentId) {
      return SDK.fetchJSON(withBoard(`${API}/links`, boardSlug), {
        method: "POST",
@@ -1977,6 +2068,7 @@
          assignees: props.assignees || [],
          boardSlug: boardSlug,
          onPatch: doPatch,
+          onSpecify: doSpecify,
          onAddParent: addLink,
          onRemoveParent: removeLink,
          onAddChild: addChild,
@@ -2045,7 +2137,11 @@
        }) : null,
        t.created_by ? h(MetaRow, { label: "Created by", value: t.created_by }) : null,
      ),
-      h(StatusActions, { task: t, onPatch: props.onPatch }),
+      h(StatusActions, {
+        task: t,
+        onPatch: props.onPatch,
+        onSpecify: props.onSpecify,
+      }),
      h(DiagnosticsSection, {
        task: t,
        boardSlug: props.boardSlug,
@@ -2478,6 +2574,8 @@

  function StatusActions(props) {
    const t = props.task;
+    const [specifyBusy, setSpecifyBusy] = useState(false);
+    const [specifyMsg, setSpecifyMsg] = useState(null);
    const b = function (label, patch, enabled, confirmMsg) {
      return h(Button, {
        onClick: function () { if (enabled !== false) props.onPatch(patch, { confirm: confirmMsg }); },
@@ -2485,22 +2583,67 @@
        size: "sm",
      }, label);
    };
-    return h("div", { className: "hermes-kanban-actions" },
-      b("→ triage",  { status: "triage" },   t.status !== "triage"),
-      b("→ ready",   { status: "ready" },    t.status !== "ready"),
-      // No direct → running button: /tasks/:id PATCH rejects status=running
-      // with 400 (issue #19535). Tasks enter running only through the
-      // dispatcher's claim_task path, which atomically creates the run row,
-      // claim lock, and worker process metadata.
-      b("Block",     { status: "blocked" },
-        t.status === "running" || t.status === "ready",
-        DESTRUCTIVE_TRANSITIONS.blocked),
-      b("Unblock",   { status: "ready" },    t.status === "blocked"),
-      b("Complete",  { status: "done" },
-        t.status === "running" || t.status === "ready" || t.status === "blocked",
-        DESTRUCTIVE_TRANSITIONS.done),
-      b("Archive",   { status: "archived" }, t.status !== "archived",
-        DESTRUCTIVE_TRANSITIONS.archived),
+
+    // "Specify" appears only when the task is in the Triage column — the
+    // one column where an auxiliary LLM pass is meaningful. Elsewhere
+    // the backend would return ok:false with "not in triage" anyway,
+    // so hiding the button keeps the action row uncluttered.
+    const specifyButton = (t.status === "triage" && props.onSpecify)
+      ? h(Button, {
+          onClick: function () {
+            if (specifyBusy) return;
+            setSpecifyBusy(true);
+            setSpecifyMsg(null);
+            props.onSpecify().then(function (res) {
+              if (res && res.ok) {
+                const suffix = res.new_title
+                  ? ` — retitled: ${res.new_title}`
+                  : "";
+                setSpecifyMsg({ ok: true, text: `Specified${suffix}` });
+              } else {
+                setSpecifyMsg({
+                  ok: false,
+                  text: "Specify failed: " + ((res && res.reason) || "unknown error"),
+                });
+              }
+            }).catch(function (err) {
+              setSpecifyMsg({
+                ok: false,
+                text: "Specify failed: " + (err.message || String(err)),
+              });
+            }).then(function () {
+              setSpecifyBusy(false);
+            });
+          },
+          disabled: specifyBusy,
+          size: "sm",
+        }, specifyBusy ? "Specifying…" : "✨ Specify")
+      : null;
+
+    return h("div", null,
+      h("div", { className: "hermes-kanban-actions" },
+        specifyButton,
+        b("→ triage",  { status: "triage" },   t.status !== "triage"),
+        b("→ ready",   { status: "ready" },    t.status !== "ready"),
+        // No direct → running button: /tasks/:id PATCH rejects status=running
+        // with 400 (issue #19535). Tasks enter running only through the
+        // dispatcher's claim_task path, which atomically creates the run row,
+        // claim lock, and worker process metadata.
+        b("Block",     { status: "blocked" },
+          t.status === "running" || t.status === "ready",
+          DESTRUCTIVE_TRANSITIONS.blocked),
+        b("Unblock",   { status: "ready" },    t.status === "blocked"),
+        b("Complete",  { status: "done" },
+          t.status === "running" || t.status === "ready" || t.status === "blocked",
+          DESTRUCTIVE_TRANSITIONS.done),
+        b("Archive",   { status: "archived" }, t.status !== "archived",
+          DESTRUCTIVE_TRANSITIONS.archived),
+      ),
+      specifyMsg ? h("div", {
+        className: specifyMsg.ok
+          ? "hermes-kanban-msg-ok"
+          : "hermes-kanban-msg-err",
+      }, specifyMsg.text) : null,
    );
  }

@@ -9,14 +9,56 @@
  width: 100%;
 }

-/* Override the Nous DS global `code { background: var(--midground) }` rule
-   which paints an opaque cream/yellow fill on every <code> inside the board,
-   hiding the text underneath. Kanban uses <code> for event payloads, run-meta,
-   and log panes — those need transparent backgrounds. */
-.hermes-kanban code {
-  background: transparent;
+/* ---- Code/pre reset (theme-immune default) --------------------------- *
+ *
+ * Themes (shipped AND user-installable) routinely paint every <code> and
+ * <pre> on the page with an opaque accent-color fill. That's fine for a
+ * Markdown doc page; it's wrong for the kanban plugin, which uses <code>
+ * for event payloads, run metadata, log panes, and similar raw-data
+ * surfaces that must read as plain text on the board's own background.
+ *
+ * Rather than play whack-a-mole with theme rules (the pre-#21086 approach
+ * was a single ``.hermes-kanban code { background: transparent }`` rule
+ * that lost specificity fights in the drawer context), reset EVERY
+ * <code>/<pre> inside the kanban plugin container to transparent with
+ * ``!important``, then opt back in ONLY on the class that carries
+ * intentional styling (``.hermes-kanban-md code``, the inline code pill
+ * inside rendered task-body Markdown).
+ *
+ * Net effect: any new theme, shipped or third-party, can introduce
+ * whatever global code-fill rule it wants — kanban surfaces stay clean
+ * unless the theme deliberately targets our internal class names.
+ * Regression coverage: #21086 (task-drawer event payloads unreadable
+ * across every shipped theme).
+ */
+.hermes-kanban code,
+.hermes-kanban pre,
+.hermes-kanban-drawer code,
+.hermes-kanban-drawer pre {
+  background: transparent !important;
  color: inherit;
 }
+/* The Markdown renderer intentionally paints a subtle code pill behind
+ * inline ``<code>`` inside task-body prose — but NOT inside a fenced
+ * block (those are a ``<pre class="hermes-kanban-md-code">`` with a
+ * bare ``<code>`` inside, and the pill would double up with the pre
+ * background). ``:not()`` scopes this opt-back-in to inline code only.
+ *
+ * Uses ``color-mix(currentColor ...)`` rather than ``--color-foreground``
+ * so the pill renders consistently even when a theme forgets to set
+ * ``--color-foreground`` (pre-existing safeguard from #18576).
+ */
+.hermes-kanban .hermes-kanban-md code:not(.hermes-kanban-md-code *) {
+  background: color-mix(in srgb, currentColor 8%, transparent) !important;
+}
+/* Tighten contrast on the drawer-specific payload class — it lives on
+ * its own line in the events list, so matching the muted-foreground
+ * color keeps it visually distinct from the event title without
+ * screaming for attention. */
+.hermes-kanban-event-payload,
+.hermes-kanban-drawer .hermes-kanban-event-payload {
+  color: var(--color-muted-foreground) !important;
+}

 /* ---- Columns layout -------------------------------------------------- */

@@ -360,6 +402,26 @@
  gap: 0.3rem;
 }

+/* Specifier result banner — sits directly under the status action row. */
+.hermes-kanban-msg-ok,
+.hermes-kanban-msg-err {
+  margin-top: 0.4rem;
+  padding: 0.35rem 0.55rem;
+  border-radius: 0.375rem;
+  font-size: 0.85rem;
+  line-height: 1.3;
+}
+.hermes-kanban-msg-ok {
+  background: rgba(46, 160, 67, 0.12);
+  color: #2ea043;
+  border: 1px solid rgba(46, 160, 67, 0.35);
+}
+.hermes-kanban-msg-err {
+  background: rgba(248, 81, 73, 0.12);
+  color: #f85149;
+  border: 1px solid rgba(248, 81, 73, 0.35);
+}
+
 /* ---- Home channel subscription toggles (per-platform, per-task) ----- */

 .hermes-kanban-home-subs {
@@ -668,7 +730,9 @@
  font-family: var(--font-mono, ui-monospace, monospace);
  font-size: 0.8rem;
  padding: 0.05rem 0.3rem;
-  background: color-mix(in srgb, var(--color-foreground) 8%, transparent);
+  /* Background is set in the code/pre reset block at the top of this
+   * file with !important, so theme-level global code rules can't knock
+   * out this intentional pill. See #21086. */
  border-radius: 3px;
  color: inherit;
 }
@@ -678,10 +742,15 @@
 * UA default on <code> elements — otherwise themes that don't set
 * --color-foreground leave code text rendering near-black on dark themes
 * (see issue #18576). */
-.hermes-kanban-md-code {
+.hermes-kanban pre.hermes-kanban-md-code {
  margin: 0.35rem 0;
  padding: 0.5rem 0.6rem;
-  background: color-mix(in srgb, currentColor 6%, transparent);
+  /* Higher specificity (``.hermes-kanban pre.hermes-kanban-md-code`` vs
+   * the reset's ``.hermes-kanban pre``) so this intentional pill wins
+   * over our own ``<pre>`` reset. ``!important`` also needed so theme
+   * rules that drop their own ``code``/``pre`` fill don't knock it out
+   * either. #21086. */
+  background: color-mix(in srgb, currentColor 6%, transparent) !important;
  border: 1px solid var(--color-border);
  border-radius: var(--radius-sm, 0.25rem);
  overflow-x: auto;
@@ -822,6 +891,32 @@
  display: flex;
  justify-content: flex-end;
  padding: 0 0.25rem;
+  gap: 0.5rem;
+  align-items: center;
+}
+.hermes-kanban-docs-link {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  border-radius: 9999px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  line-height: 1;
+  color: var(--color-muted-foreground, rgba(180, 180, 200, 0.8));
+  background: var(--color-card-subtle, rgba(255, 255, 255, 0.04));
+  border: 1px solid var(--color-border, rgba(120, 120, 140, 0.25));
+  text-decoration: none;
+  cursor: help;
+  transition: color 0.15s, background 0.15s, border-color 0.15s;
+}
+.hermes-kanban-docs-link:hover,
+.hermes-kanban-docs-link:focus-visible {
+  color: var(--color-foreground, #e7e7ee);
+  background: var(--color-card, rgba(255, 255, 255, 0.08));
+  border-color: var(--color-border, rgba(160, 160, 190, 0.45));
+  outline: none;
 }
 .hermes-kanban-dialog-backdrop {
  position: fixed;
@@ -30,6 +30,7 @@ import asyncio
 import hmac
 import json
 import logging
+import os
 import sqlite3
 import time
 from dataclasses import asdict
@@ -1011,6 +1012,61 @@ def reclaim_task_endpoint(
        conn.close()


+class SpecifyBody(BaseModel):
+    """Optional author override. Nothing else is configurable from the
+    dashboard — model + prompt come from ``auxiliary.triage_specifier``
+    in config.yaml, same as the CLI."""
+
+    author: Optional[str] = None
+
+
+@router.post("/tasks/{task_id}/specify")
+def specify_task_endpoint(
+    task_id: str,
+    payload: SpecifyBody,
+    board: Optional[str] = Query(None),
+):
+    """Flesh out a triage-column task via the auxiliary LLM and promote
+    it to ``todo``. Maps 1:1 to ``hermes kanban specify <task_id>``.
+
+    Returns the outcome shape used by the CLI: ``{ok, task_id, reason,
+    new_title}``. A non-OK outcome is NOT an HTTP error — the UI renders
+    the reason inline (e.g. "no auxiliary client configured") so the
+    operator knows what to fix, and retries without a page reload.
+
+    This endpoint runs in FastAPI's threadpool (sync ``def``) because
+    the underlying LLM call can take tens of seconds to minutes on
+    reasoning models, which would block the event loop if we used
+    ``async def`` without an explicit ``run_in_executor``.
+    """
+    board = _resolve_board(board)
+    # Pin the board for the duration of this call so the specifier module
+    # (which calls ``kb.connect()`` with no args) hits the right DB.
+    prev_env = os.environ.get("HERMES_KANBAN_BOARD")
+    try:
+        os.environ["HERMES_KANBAN_BOARD"] = board or kanban_db.DEFAULT_BOARD
+        # Import lazily so a missing auxiliary client at import time
+        # doesn't break plugin load.
+        from hermes_cli import kanban_specify  # noqa: WPS433 (intentional)
+
+        outcome = kanban_specify.specify_task(
+            task_id,
+            author=(payload.author or None),
+        )
+    finally:
+        if prev_env is None:
+            os.environ.pop("HERMES_KANBAN_BOARD", None)
+        else:
+            os.environ["HERMES_KANBAN_BOARD"] = prev_env
+
+    return {
+        "ok": bool(outcome.ok),
+        "task_id": outcome.task_id,
+        "reason": outcome.reason,
+        "new_title": outcome.new_title,
+    }
+
+
 class ReassignBody(BaseModel):
    profile: Optional[str] = None  # "" or None = unassign
    reclaim_first: bool = False
@@ -1521,6 +1577,13 @@ async def stream_events(ws: WebSocket):
            await asyncio.sleep(_EVENT_POLL_SECONDS)
    except WebSocketDisconnect:
        return
+    except asyncio.CancelledError:
+        # Normal shutdown path: dashboard process exit (Ctrl-C) cancels the
+        # websocket task while it is sleeping in the poll loop.
+        # CancelledError is a BaseException in 3.8+ so the bare Exception
+        # handler below would not catch it; without this clause Uvicorn
+        # surfaces the cancellation as an application traceback. Quiet it.
+        return
    except Exception as exc:  # defensive: never crash the dashboard worker
        log.warning("Kanban event stream error: %s", exc)
        try:
@@ -27,9 +27,16 @@ from __future__ import annotations
 import atexit
 import json
 import logging
+import mimetypes
 import os
+import tempfile
 import threading
+import uuid
+import zipfile
+from pathlib import Path
 from typing import Any, Dict, List, Optional
+from urllib.parse import urlparse
+from urllib.request import url2pathname

 from agent.memory_provider import MemoryProvider
 from tools.registry import tool_error
@@ -38,6 +45,7 @@ logger = logging.getLogger(__name__)

 _DEFAULT_ENDPOINT = "http://127.0.0.1:1933"
 _TIMEOUT = 30.0
+_REMOTE_RESOURCE_PREFIXES = ("http://", "https://", "git@", "ssh://", "git://")


 # ---------------------------------------------------------------------------
@@ -92,38 +100,94 @@ class _VikingClient:
            raise ImportError("httpx is required for OpenViking: pip install httpx")

    def _headers(self) -> dict:
+        # Only send tenant headers when the user actually configured them.
+        # Legacy installs had account/user defaulted to the literal string
+        # "default" — treat that as unset so authenticated remote servers
+        # that derive tenancy from the Bearer key aren't overridden by a
+        # bogus tenant value.
        h = {
            "Content-Type": "application/json",
-            "X-OpenViking-Account": self._account,
-            "X-OpenViking-User": self._user,
            "X-OpenViking-Agent": self._agent,
        }
+        if self._account and self._account != "default":
+            h["X-OpenViking-Account"] = self._account
+        if self._user and self._user != "default":
+            h["X-OpenViking-User"] = self._user
        if self._api_key:
            h["X-API-Key"] = self._api_key
+            h["Authorization"] = "Bearer " + self._api_key
        return h

    def _url(self, path: str) -> str:
        return f"{self._endpoint}{path}"

+    def _multipart_headers(self) -> dict:
+        headers = self._headers()
+        headers.pop("Content-Type", None)
+        return headers
+
+    def _parse_response(self, resp) -> dict:
+        try:
+            data = resp.json()
+        except Exception:
+            data = None
+
+        if resp.status_code >= 400:
+            if isinstance(data, dict):
+                error = data.get("error")
+                if isinstance(error, dict):
+                    code = error.get("code", "HTTP_ERROR")
+                    message = error.get("message", resp.text)
+                    raise RuntimeError(f"{code}: {message}")
+                if data.get("status") == "error":
+                    raise RuntimeError(str(data))
+            resp.raise_for_status()
+
+        if isinstance(data, dict) and data.get("status") == "error":
+            error = data.get("error")
+            if isinstance(error, dict):
+                code = error.get("code", "OPENVIKING_ERROR")
+                message = error.get("message", "")
+                raise RuntimeError(f"{code}: {message}")
+            raise RuntimeError(str(data))
+
+        if data is None:
+            return {}
+        return data
+
    def get(self, path: str, **kwargs) -> dict:
        resp = self._httpx.get(
            self._url(path), headers=self._headers(), timeout=_TIMEOUT, **kwargs
        )
-        resp.raise_for_status()
-        return resp.json()
+        return self._parse_response(resp)

    def post(self, path: str, payload: dict = None, **kwargs) -> dict:
        resp = self._httpx.post(
            self._url(path), json=payload or {}, headers=self._headers(),
            timeout=_TIMEOUT, **kwargs
        )
-        resp.raise_for_status()
-        return resp.json()
+        return self._parse_response(resp)
+
+    def upload_temp_file(self, file_path: Path) -> str:
+        mime_type = mimetypes.guess_type(file_path.name)[0] or "application/octet-stream"
+        with file_path.open("rb") as f:
+            resp = self._httpx.post(
+                self._url("/api/v1/resources/temp_upload"),
+                files={"file": (file_path.name, f, mime_type)},
+                headers=self._multipart_headers(),
+                timeout=_TIMEOUT,
+            )
+        data = self._parse_response(resp)
+        result = data.get("result", {})
+        temp_file_id = result.get("temp_file_id", "")
+        if not temp_file_id:
+            raise RuntimeError("OpenViking temp upload did not return temp_file_id")
+        return temp_file_id

    def health(self) -> bool:
        try:
            resp = self._httpx.get(
-                self._url("/health"), timeout=3.0
+                self._url("/health"), headers=self._headers(), timeout=3.0
            )
            return resp.status_code == 200
        except Exception:
@@ -230,24 +294,90 @@ REMEMBER_SCHEMA = {
 ADD_RESOURCE_SCHEMA = {
    "name": "viking_add_resource",
    "description": (
-        "Add a URL or document to the OpenViking knowledge base. "
-        "Supports web pages, GitHub repos, PDFs, markdown, code files. "
+        "Add a remote URL or local file/directory to the OpenViking knowledge base. "
+        "Remote resources must be public http(s), git, or ssh URLs. "
+        "Local files are uploaded first using OpenViking temp_upload. "
        "The system automatically parses, indexes, and generates summaries."
    ),
    "parameters": {
        "type": "object",
        "properties": {
-            "url": {"type": "string", "description": "URL or path of the resource to add."},
+            "url": {"type": "string", "description": "Remote URL or local file/directory path to add."},
            "reason": {
                "type": "string",
                "description": "Why this resource is relevant (improves search).",
            },
+            "to": {
+                "type": "string",
+                "description": "Optional target viking:// URI for the resource.",
+            },
+            "parent": {
+                "type": "string",
+                "description": "Optional parent viking:// URI. Cannot be used with to.",
+            },
+            "instruction": {
+                "type": "string",
+                "description": "Optional processing instruction for semantic extraction.",
+            },
+            "wait": {
+                "type": "boolean",
+                "description": "Whether to wait for processing to complete.",
+            },
+            "timeout": {
+                "type": "number",
+                "description": "Timeout in seconds when wait is true.",
+            },
        },
        "required": ["url"],
    },
 }


+def _zip_directory(dir_path: Path) -> Path:
+    """Create a temporary zip file containing a directory tree."""
+    zip_path = Path(tempfile.gettempdir()) / f"openviking_upload_{uuid.uuid4().hex}.zip"
+    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zipf:
+        for file_path in dir_path.rglob("*"):
+            if file_path.is_file():
+                arcname = str(file_path.relative_to(dir_path)).replace("\\", "/")
+                zipf.write(file_path, arcname=arcname)
+    return zip_path
+
+
+def _is_windows_absolute_path(value: str) -> bool:
+    return (
+        len(value) >= 3
+        and value[0].isalpha()
+        and value[1] == ":"
+        and value[2] in ("/", "\\")
+    )
+
+
+def _is_remote_resource_source(value: str) -> bool:
+    return value.startswith(_REMOTE_RESOURCE_PREFIXES)
+
+
+def _is_local_path_reference(value: str) -> bool:
+    if not value or "\n" in value or "\r" in value:
+        return False
+    if _is_remote_resource_source(value):
+        return False
+    if _is_windows_absolute_path(value):
+        return True
+    return (
+        value.startswith(("/", "./", "../", "~/", ".\\", "..\\", "~\\"))
+        or "/" in value
+        or "\\" in value
+    )
+
+
+def _path_from_file_uri(uri: str) -> Path | str:
+    parsed = urlparse(uri)
+    if parsed.netloc not in ("", "localhost"):
+        return f"Unsupported non-local file URI: {uri}"
+    return Path(url2pathname(parsed.path)).expanduser()
+
+
 # ---------------------------------------------------------------------------
 # MemoryProvider implementation
 # ---------------------------------------------------------------------------
@@ -744,12 +874,52 @@ class OpenVikingMemoryProvider(MemoryProvider):
        if not url:
            return tool_error("url is required")

-        payload: Dict[str, Any] = {"path": url}
-        if args.get("reason"):
-            payload["reason"] = args["reason"]
+        if args.get("to") and args.get("parent"):
+            return tool_error("Cannot specify both 'to' and 'parent'")

-        resp = self._client.post("/api/v1/resources", payload)
-        result = resp.get("result", {})
+        payload: Dict[str, Any] = {}
+        for key in ("reason", "to", "parent", "instruction", "wait", "timeout"):
+            if key in args and args[key] not in (None, ""):
+                payload[key] = args[key]
+
+        parsed_url = urlparse(url)
+        if _is_remote_resource_source(url):
+            source_path = None
+        elif parsed_url.scheme == "file":
+            source_path = _path_from_file_uri(url)
+            if isinstance(source_path, str):
+                return tool_error(source_path)
+        elif parsed_url.scheme and not _is_windows_absolute_path(url):
+            source_path = None
+        else:
+            source_path = Path(url).expanduser()
+
+        cleanup_path: Optional[Path] = None
+        try:
+            if source_path is not None:
+                if source_path.exists():
+                    if source_path.is_dir():
+                        payload["source_name"] = source_path.name
+                        cleanup_path = _zip_directory(source_path)
+                        upload_path = cleanup_path
+                    elif source_path.is_file():
+                        payload["source_name"] = source_path.name
+                        upload_path = source_path
+                    else:
+                        return tool_error(f"Unsupported local resource path: {url}")
+                    payload["temp_file_id"] = self._client.upload_temp_file(upload_path)
+                elif _is_local_path_reference(url):
+                    return tool_error(f"Local resource path does not exist: {url}")
+                else:
+                    payload["path"] = url
+            else:
+                payload["path"] = url
+
+            resp = self._client.post("/api/v1/resources", payload)
+            result = resp.get("result", {})
+        finally:
+            if cleanup_path:
+                cleanup_path.unlink(missing_ok=True)

        return json.dumps({
            "status": "added",
@@ -0,0 +1,3 @@
+from .adapter import register
+
+__all__ = ["register"]
@@ -0,0 +1,638 @@
+"""User OAuth helper for the Google Chat gateway adapter.
+
+Google Chat's ``media.upload`` REST endpoint hard-rejects service-account
+authentication:
+
+    "This method doesn't support app authentication with a service
+     account. Authenticate with a user account."
+
+(See https://developers.google.com/workspace/chat/api/reference/rest/v1/media/upload
+and https://developers.google.com/chat/api/guides/auth/users.)
+
+For the bot to deliver native file attachments — the same drag-and-drop
+file widget the user gets when they upload manually — each user must
+grant the bot the ``chat.messages.create`` scope ONCE in their own DM.
+The bot stores per-user refresh tokens and calls ``media.upload`` plus
+the subsequent ``messages.create`` *as the requesting user* whenever a
+file needs sending.
+
+This module is BOTH a CLI tool (driven by the agent via slash commands or
+terminal commands) AND a library imported by ``google_chat.py``:
+
+    Library functions (called from the adapter at runtime):
+        load_user_credentials(email=None) -> Credentials | None
+        refresh_or_none(creds, email=None) -> Credentials | None
+        build_user_chat_service(creds) -> chat_v1.Resource
+        list_authorized_emails() -> List[str]
+
+    CLI commands (driven by the agent through the /setup-files slash
+    command, modeled on skills/productivity/google-workspace/scripts/setup.py):
+        --check                          Exit 0 if auth is valid, else 1
+        --client-secret /path/to.json    Persist OAuth client credentials
+        --auth-url                       Print the OAuth URL for the user
+        --auth-code CODE                 Exchange auth code for token
+        --revoke                         Revoke and delete stored token
+        --install-deps                   Install Python dependencies
+        --email EMAIL                    Scope CLI ops to a specific user
+                                         (defaults to legacy single-user
+                                         mode when omitted)
+
+The flow mirrors the existing google-workspace skill exactly so anyone
+familiar with that flow can read this without surprises.
+
+Token storage layout
+--------------------
+- Per-user tokens (keyed by sender email):
+    ``${HERMES_HOME}/google_chat_user_tokens/<sanitized_email>.json``
+- Legacy single-user token (fallback, untouched for backward compat):
+    ``${HERMES_HOME}/google_chat_user_token.json``
+- Per-user pending OAuth state during /setup-files start → exchange:
+    ``${HERMES_HOME}/google_chat_user_oauth_pending/<sanitized_email>.json``
+- Legacy pending state:
+    ``${HERMES_HOME}/google_chat_user_oauth_pending.json``
+- Shared OAuth client (one per host):
+    ``${HERMES_HOME}/google_chat_user_client_secret.json``
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, List, Optional, Tuple
+
+# Pin the legacy logger name so operator-side log filters keep matching
+# after the in-tree → plugin migration. See adapter.py for context.
+logger = logging.getLogger("gateway.platforms.google_chat_user_oauth")
+
+# Use the project's HERMES_HOME helper so the token follows the user's
+# profile (e.g. tests can override via HERMES_HOME=/tmp/...).
+try:
+    from hermes_constants import display_hermes_home, get_hermes_home
+except (ModuleNotFoundError, ImportError):
+    # Fallback for environments where hermes_constants isn't importable
+    # (mirrors the same fallback used by the google-workspace skill's
+    # _hermes_home.py shim).
+    def get_hermes_home() -> Path:
+        val = os.environ.get("HERMES_HOME", "").strip()
+        return Path(val) if val else Path.home() / ".hermes"
+
+    def display_hermes_home() -> str:
+        home = get_hermes_home()
+        try:
+            return "~/" + str(home.relative_to(Path.home()))
+        except ValueError:
+            return str(home)
+
+
+def _hermes_home() -> Path:
+    """Resolve HERMES_HOME at call time (NOT module import).
+
+    Tests and ``HERMES_HOME=...`` env overrides need this to be late-
+    binding. If we cached the path at import time, switching profiles
+    or tweaking env vars in tests would silently keep using the old
+    path."""
+    return get_hermes_home()
+
+
+# Filesystem-safe key: lowercase, allow ``[a-z0-9._-@]``, replace anything
+# else with ``_``. ``ramon.fernandez@nttdata.com`` stays human-readable
+# (``ramon.fernandez@nttdata.com.json``) which makes admin debugging by
+# ``ls ~/.hermes/google_chat_user_tokens/`` trivial.
+_EMAIL_FS_RE = re.compile(r"[^a-z0-9._@-]+")
+
+
+def _sanitize_email(email: str) -> str:
+    cleaned = _EMAIL_FS_RE.sub("_", (email or "").strip().lower())
+    return cleaned or "_unknown_"
+
+
+def _legacy_token_path() -> Path:
+    return _hermes_home() / "google_chat_user_token.json"
+
+
+def _user_tokens_dir() -> Path:
+    return _hermes_home() / "google_chat_user_tokens"
+
+
+def _legacy_pending_path() -> Path:
+    return _hermes_home() / "google_chat_user_oauth_pending.json"
+
+
+def _user_pending_dir() -> Path:
+    return _hermes_home() / "google_chat_user_oauth_pending"
+
+
+def _token_path(email: Optional[str] = None) -> Path:
+    """Return the on-disk token path for ``email`` or the legacy path."""
+    if email:
+        return _user_tokens_dir() / f"{_sanitize_email(email)}.json"
+    return _legacy_token_path()
+
+
+def _client_secret_path() -> Path:
+    return _hermes_home() / "google_chat_user_client_secret.json"
+
+
+def _pending_auth_path(email: Optional[str] = None) -> Path:
+    if email:
+        return _user_pending_dir() / f"{_sanitize_email(email)}.json"
+    return _legacy_pending_path()
+
+
+# Minimum scope for native Chat attachment delivery.
+# `chat.messages.create` covers BOTH `media.upload` and the subsequent
+# `messages.create` that references the attachmentDataRef. We deliberately
+# do NOT request drive.file or other scopes — least privilege.
+SCOPES: List[str] = [
+    "https://www.googleapis.com/auth/chat.messages.create",
+]
+
+# Pip packages required for the OAuth flow.
+_REQUIRED_PACKAGES = [
+    "google-api-python-client",
+    "google-auth-oauthlib",
+    "google-auth-httplib2",
+]
+
+# Out-of-band redirect: Google deprecated the ``urn:ietf:wg:oauth:2.0:oob``
+# flow, so we use a localhost redirect that's expected to FAIL. The user
+# copies the auth code from the failed browser URL bar back into chat.
+# Same trick used by skills/productivity/google-workspace/scripts/setup.py.
+_REDIRECT_URI = "http://localhost:1"
+
+
+# =============================================================================
+# Library API — called from the adapter at runtime
+# =============================================================================
+
+
+def load_user_credentials(email: Optional[str] = None) -> Optional[Any]:
+    """Load + validate persisted user OAuth credentials.
+
+    ``email`` selects the per-user token file; ``None`` falls back to the
+    legacy single-user path (left in place for installs that ran the
+    pre-multi-user flow). Returns a ``google.oauth2.credentials.Credentials``
+    instance ready for use, or ``None`` if no token is stored, the token
+    is corrupt, or refresh fails. Adapter callers should treat ``None``
+    as "user has not run /setup-files yet" and surface the setup-instructions
+    fallback to the user.
+
+    Does NOT raise on the no-token case — that's expected.
+    """
+    token_path = _token_path(email)
+    if not token_path.exists():
+        return None
+
+    try:
+        from google.oauth2.credentials import Credentials
+        from google.auth.transport.requests import Request
+    except ImportError:
+        logger.warning(
+            "[google_chat_user_oauth] google-auth not installed; user-OAuth "
+            "attachment delivery is disabled. Install hermes-agent[google_chat]."
+        )
+        return None
+
+    try:
+        # Don't pass scopes — user may have authorized only a subset, and
+        # passing scopes makes refresh validate them strictly. Same logic
+        # as the google-workspace skill.
+        creds = Credentials.from_authorized_user_file(str(token_path))
+    except Exception as exc:
+        logger.warning(
+            "[google_chat_user_oauth] token at %s is corrupt: %s",
+            token_path, exc,
+        )
+        return None
+
+    if creds.valid:
+        return creds
+
+    if creds.expired and creds.refresh_token:
+        try:
+            creds.refresh(Request())
+        except Exception as exc:
+            logger.warning(
+                "[google_chat_user_oauth] token refresh failed (user "
+                "should re-run /setup-files): %s", exc,
+            )
+            return None
+        # Persist refreshed token so next start picks up the new access
+        # token without an unnecessary refresh round-trip.
+        _persist_credentials(creds, token_path)
+        return creds
+
+    # Token exists but is unusable (e.g. revoked, no refresh token).
+    return None
+
+
+def refresh_or_none(creds: Any, email: Optional[str] = None) -> Optional[Any]:
+    """Refresh ``creds`` if expired. Returns the credentials or ``None``.
+
+    Used by the adapter just before calling media.upload to ensure the
+    token is current. Returns ``None`` if refresh fails — caller falls
+    back to the text-notice path. ``email`` controls where the refreshed
+    token is written back; ``None`` keeps the legacy single-file path.
+    """
+    if creds is None:
+        return None
+
+    if creds.valid:
+        return creds
+
+    try:
+        from google.auth.transport.requests import Request
+    except ImportError:
+        return None
+
+    if creds.expired and creds.refresh_token:
+        try:
+            creds.refresh(Request())
+            _persist_credentials(creds, _token_path(email))
+            return creds
+        except Exception as exc:
+            logger.warning(
+                "[google_chat_user_oauth] refresh failed: %s", exc,
+            )
+            return None
+
+    return None
+
+
+def build_user_chat_service(creds: Any) -> Any:
+    """Build a Google Chat API client authenticated as the user.
+
+    Used for media.upload + the subsequent messages.create that
+    references the attachmentDataRef. The bot's separate SA-authed
+    client (``self._chat_api`` in the adapter) is for everything else.
+    """
+    from googleapiclient.discovery import build as build_service
+    return build_service("chat", "v1", credentials=creds, cache_discovery=False)
+
+
+def list_authorized_emails() -> List[str]:
+    """Return the set of user emails that have stored per-user tokens.
+
+    Lists files in the per-user tokens dir; does NOT include the legacy
+    single-user token (its owner is unknown). Sanitized filenames lose
+    the ``+suffix`` part of plus-addressed emails — accept that and use
+    this list only for admin display, not for trust decisions.
+    """
+    d = _user_tokens_dir()
+    if not d.exists():
+        return []
+    out: List[str] = []
+    for f in d.iterdir():
+        if f.is_file() and f.suffix == ".json":
+            out.append(f.stem)
+    out.sort()
+    return out
+
+
+def _persist_credentials(creds: Any, token_path: Path) -> None:
+    """Atomic-ish JSON write of refreshed credentials."""
+    try:
+        token_path.parent.mkdir(parents=True, exist_ok=True)
+        token_path.write_text(
+            json.dumps(
+                _normalize_authorized_user_payload(json.loads(creds.to_json())),
+                indent=2,
+            )
+        )
+    except Exception:
+        logger.debug(
+            "[google_chat_user_oauth] failed to persist credentials at %s",
+            token_path, exc_info=True,
+        )
+
+
+# =============================================================================
+# CLI commands — driven by the agent via /setup-files
+# =============================================================================
+
+
+def _normalize_authorized_user_payload(payload: dict) -> dict:
+    """Ensure the persisted token JSON has the type field google-auth expects."""
+    normalized = dict(payload)
+    if not normalized.get("type"):
+        normalized["type"] = "authorized_user"
+    return normalized
+
+
+def _ensure_deps() -> None:
+    """Check deps available; install if not; exit on failure."""
+    try:
+        import googleapiclient  # noqa: F401
+        import google_auth_oauthlib  # noqa: F401
+    except ImportError:
+        if not install_deps():
+            sys.exit(1)
+
+
+def install_deps() -> bool:
+    try:
+        import googleapiclient  # noqa: F401
+        import google_auth_oauthlib  # noqa: F401
+        print("Dependencies already installed.")
+        return True
+    except ImportError:
+        pass
+
+    print("Installing Google Chat OAuth dependencies...")
+    try:
+        subprocess.check_call(
+            [sys.executable, "-m", "pip", "install", "--quiet"] + _REQUIRED_PACKAGES,
+            stdout=subprocess.DEVNULL,
+        )
+        print("Dependencies installed.")
+        return True
+    except subprocess.CalledProcessError as exc:
+        print(f"ERROR: Failed to install dependencies: {exc}")
+        print("Or install via the optional extra:")
+        print("  pip install 'hermes-agent[google_chat]'")
+        return False
+
+
+def check_auth(email: Optional[str] = None) -> bool:
+    """Print status; return True if creds are usable.
+
+    Per-user when ``email`` given, legacy single-user when omitted.
+    """
+    token_path = _token_path(email)
+    if not token_path.exists():
+        print(f"NOT_AUTHENTICATED: No token at {token_path}")
+        return False
+
+    creds = load_user_credentials(email)
+    if creds is None:
+        print(f"TOKEN_INVALID: Re-run /setup-files (path: {token_path})")
+        return False
+
+    print(f"AUTHENTICATED: Token valid at {token_path}")
+    return True
+
+
+def store_client_secret(path: str) -> None:
+    """Validate and copy the user's OAuth client_secret.json into HERMES_HOME."""
+    src = Path(path).expanduser().resolve()
+    if not src.exists():
+        print(f"ERROR: File not found: {src}")
+        sys.exit(1)
+
+    try:
+        data = json.loads(src.read_text())
+    except json.JSONDecodeError:
+        print("ERROR: File is not valid JSON.")
+        sys.exit(1)
+
+    if "installed" not in data and "web" not in data:
+        print(
+            "ERROR: Not a Google OAuth client secret file (missing "
+            "'installed' or 'web' key)."
+        )
+        print(
+            "Download from: https://console.cloud.google.com/apis/credentials"
+        )
+        sys.exit(1)
+
+    target = _client_secret_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(data, indent=2))
+    print(f"OK: Client secret saved to {target}")
+
+
+def _save_pending_auth(*, state: str, code_verifier: str,
+                      email: Optional[str] = None) -> None:
+    pending = _pending_auth_path(email)
+    pending.parent.mkdir(parents=True, exist_ok=True)
+    pending.write_text(
+        json.dumps(
+            {
+                "state": state,
+                "code_verifier": code_verifier,
+                "redirect_uri": _REDIRECT_URI,
+                "email": email or "",
+            },
+            indent=2,
+        )
+    )
+
+
+def _load_pending_auth(email: Optional[str] = None) -> dict:
+    pending = _pending_auth_path(email)
+    if not pending.exists():
+        print("ERROR: No pending OAuth session found. Run --auth-url first.")
+        sys.exit(1)
+    try:
+        data = json.loads(pending.read_text())
+    except Exception as exc:
+        print(f"ERROR: Could not read pending OAuth session: {exc}")
+        print("Run --auth-url again to start a fresh session.")
+        sys.exit(1)
+    if not data.get("state") or not data.get("code_verifier"):
+        print("ERROR: Pending OAuth session is missing PKCE data.")
+        print("Run --auth-url again.")
+        sys.exit(1)
+    return data
+
+
+def _extract_code_and_state(code_or_url: str) -> Tuple[str, Optional[str]]:
+    """Accept a raw auth code OR the full failed-redirect URL the user pastes."""
+    if not code_or_url.startswith("http"):
+        return code_or_url, None
+
+    from urllib.parse import parse_qs, urlparse
+
+    parsed = urlparse(code_or_url)
+    params = parse_qs(parsed.query)
+    if "code" not in params:
+        print("ERROR: No 'code' parameter found in URL.")
+        sys.exit(1)
+    state = params.get("state", [None])[0]
+    return params["code"][0], state
+
+
+def get_auth_url(email: Optional[str] = None) -> None:
+    """Print the OAuth URL for the user to visit. Persists PKCE state.
+
+    ``email`` namespaces the pending state so two users can be mid-flow
+    in parallel without trampling each other's PKCE verifier.
+    """
+    if not _client_secret_path().exists():
+        print("ERROR: No client secret stored. Run --client-secret first.")
+        sys.exit(1)
+
+    _ensure_deps()
+    from google_auth_oauthlib.flow import Flow
+
+    flow = Flow.from_client_secrets_file(
+        str(_client_secret_path()),
+        scopes=SCOPES,
+        redirect_uri=_REDIRECT_URI,
+        autogenerate_code_verifier=True,
+    )
+    auth_url, state = flow.authorization_url(
+        access_type="offline",
+        prompt="consent",
+    )
+    _save_pending_auth(state=state, code_verifier=flow.code_verifier, email=email)
+    print(auth_url)
+
+
+def exchange_auth_code(code: str, email: Optional[str] = None) -> None:
+    """Exchange an auth code (or pasted redirect URL) for a refresh token.
+
+    ``email`` selects the destination token path. ``None`` writes to the
+    legacy single-user path (kept for the existing CLI entrypoint and for
+    pre-multi-user installs).
+    """
+    if not _client_secret_path().exists():
+        print("ERROR: No client secret stored. Run --client-secret first.")
+        sys.exit(1)
+
+    pending_auth = _load_pending_auth(email)
+    raw_callback = code
+    code, returned_state = _extract_code_and_state(code)
+    if returned_state and returned_state != pending_auth["state"]:
+        print(
+            "ERROR: OAuth state mismatch. Run --auth-url again to start a "
+            "fresh session."
+        )
+        sys.exit(1)
+
+    _ensure_deps()
+    from google_auth_oauthlib.flow import Flow
+    from urllib.parse import parse_qs, urlparse
+
+    granted_scopes = list(SCOPES)
+    if isinstance(raw_callback, str) and raw_callback.startswith("http"):
+        params = parse_qs(urlparse(raw_callback).query)
+        scope_val = (params.get("scope") or [""])[0].strip()
+        if scope_val:
+            granted_scopes = scope_val.split()
+
+    flow = Flow.from_client_secrets_file(
+        str(_client_secret_path()),
+        scopes=granted_scopes,
+        redirect_uri=pending_auth.get("redirect_uri", _REDIRECT_URI),
+        state=pending_auth["state"],
+        code_verifier=pending_auth["code_verifier"],
+    )
+
+    try:
+        # Accept partial scopes — user may deselect items in the consent screen.
+        os.environ["OAUTHLIB_RELAX_TOKEN_SCOPE"] = "1"
+        flow.fetch_token(code=code)
+    except Exception as exc:
+        print(f"ERROR: Token exchange failed: {exc}")
+        print("The code may have expired. Run --auth-url to get a fresh URL.")
+        sys.exit(1)
+
+    creds = flow.credentials
+    token_payload = _normalize_authorized_user_payload(json.loads(creds.to_json()))
+
+    actually_granted = (
+        list(creds.granted_scopes or [])
+        if hasattr(creds, "granted_scopes") and creds.granted_scopes
+        else []
+    )
+    if actually_granted:
+        token_payload["scopes"] = actually_granted
+    elif granted_scopes != SCOPES:
+        token_payload["scopes"] = granted_scopes
+
+    token_path = _token_path(email)
+    token_path.parent.mkdir(parents=True, exist_ok=True)
+    token_path.write_text(json.dumps(token_payload, indent=2))
+    _pending_auth_path(email).unlink(missing_ok=True)
+
+    print(f"OK: Authenticated. Token saved to {token_path}")
+    rel_label = (
+        f"{display_hermes_home()}/google_chat_user_tokens/{_sanitize_email(email)}.json"
+        if email
+        else f"{display_hermes_home()}/google_chat_user_token.json"
+    )
+    print(f"Profile path: {rel_label}")
+
+
+def revoke(email: Optional[str] = None) -> None:
+    """Revoke the stored token with Google and delete it locally.
+
+    Per-user when ``email`` given, legacy single-user when omitted.
+    """
+    token_path = _token_path(email)
+    if not token_path.exists():
+        print("No token to revoke.")
+        return
+
+    _ensure_deps()
+    from google.oauth2.credentials import Credentials
+    from google.auth.transport.requests import Request
+
+    try:
+        creds = Credentials.from_authorized_user_file(str(token_path), SCOPES)
+        if creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+
+        import urllib.request
+        urllib.request.urlopen(
+            urllib.request.Request(
+                f"https://oauth2.googleapis.com/revoke?token={creds.token}",
+                method="POST",
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+        )
+        print("Token revoked with Google.")
+    except Exception as exc:
+        print(f"Remote revocation failed (token may already be invalid): {exc}")
+
+    token_path.unlink(missing_ok=True)
+    _pending_auth_path(email).unlink(missing_ok=True)
+    print(f"Deleted {token_path}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Google Chat user-OAuth setup for Hermes (native attachment delivery)"
+    )
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--check", action="store_true",
+                       help="Check if auth is valid (exit 0=yes, 1=no)")
+    group.add_argument("--client-secret", metavar="PATH",
+                       help="Store OAuth client_secret.json")
+    group.add_argument("--auth-url", action="store_true",
+                       help="Print OAuth URL for user to visit")
+    group.add_argument("--auth-code", metavar="CODE",
+                       help="Exchange auth code for token")
+    group.add_argument("--revoke", action="store_true",
+                       help="Revoke and delete stored token")
+    group.add_argument("--install-deps", action="store_true",
+                       help="Install Python dependencies")
+    parser.add_argument("--email", metavar="EMAIL", default=None,
+                       help="Scope operation to a specific user's token "
+                            "(default: legacy single-user path)")
+    args = parser.parse_args()
+
+    email = args.email or None
+    if args.check:
+        sys.exit(0 if check_auth(email) else 1)
+    elif args.client_secret:
+        store_client_secret(args.client_secret)
+    elif args.auth_url:
+        get_auth_url(email)
+    elif args.auth_code:
+        exchange_auth_code(args.auth_code, email)
+    elif args.revoke:
+        revoke(email)
+    elif args.install_deps:
+        sys.exit(0 if install_deps() else 1)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,39 @@
+name: google_chat-platform
+label: Google Chat
+kind: platform
+version: 1.0.0
+description: >
+  Google Chat gateway adapter for Hermes Agent.
+  Connects via Cloud Pub/Sub pull subscription for inbound events and the
+  Google Chat REST API for outbound messages — same ergonomics as Slack
+  Socket Mode or Telegram long-polling, no public URL required. Native
+  file attachments are delivered via per-user OAuth (each user runs
+  /setup-files once in their own DM).
+author: Ramón Fernández
+# ``requires_env`` entries are surfaced in ``hermes config`` UI via the
+# platform-plugin env var injector in ``hermes_cli/config.py``.  Using the
+# rich-dict form lets us contribute description/url/prompt metadata so users
+# see helpful guidance instead of the auto-generated fallback text.
+requires_env:
+  - name: GOOGLE_CHAT_PROJECT_ID
+    description: "GCP project ID hosting the Pub/Sub topic for Chat events. Falls back to GOOGLE_CLOUD_PROJECT."
+    prompt: "GCP project ID"
+    url: "https://console.cloud.google.com/"
+    password: false
+  - name: GOOGLE_CHAT_SUBSCRIPTION_NAME
+    description: "Full Pub/Sub subscription path: projects/<proj>/subscriptions/<sub>. Legacy alias: GOOGLE_CHAT_SUBSCRIPTION."
+    prompt: "Pub/Sub subscription name"
+    password: false
+  - name: GOOGLE_CHAT_SERVICE_ACCOUNT_JSON
+    description: "Path to Service Account JSON key (or inline JSON). Leave empty to use Application Default Credentials on Cloud Run / GCE. Falls back to GOOGLE_APPLICATION_CREDENTIALS."
+    prompt: "Path to SA JSON (or empty for ADC)"
+    password: true
+optional_env:
+  - name: GOOGLE_CHAT_ALLOWED_USERS
+    description: "Comma-separated user emails allowed to interact with the bot."
+    prompt: "Allowed user emails (comma-separated)"
+    password: false
+  - name: GOOGLE_CHAT_HOME_CHANNEL
+    description: "Default space for cron / notification delivery (e.g. spaces/AAAA...)."
+    prompt: "Home space ID (or empty)"
+    password: false
@@ -653,6 +653,57 @@ def is_connected(config) -> bool:
    return bool(server and channel)


+def _env_enablement() -> dict | None:
+    """Seed ``PlatformConfig.extra`` from env vars during gateway config load.
+
+    Called by the platform registry's env-enablement hook (landed in the
+    generic-plugin-interface migration) BEFORE adapter construction, so
+    ``gateway status`` and ``get_connected_platforms()`` reflect env-only
+    configuration without instantiating the IRC client.  Returns ``None``
+    when IRC isn't minimally configured; the caller skips auto-enabling.
+
+    The special ``home_channel`` key in the returned dict is handled by
+    the core hook — it becomes a proper ``HomeChannel`` dataclass on the
+    ``PlatformConfig`` rather than being merged into ``extra``.
+    """
+    server = os.getenv("IRC_SERVER", "").strip()
+    channel = os.getenv("IRC_CHANNEL", "").strip()
+    if not (server and channel):
+        return None
+    seed: dict = {
+        "server": server,
+        "channel": channel,
+    }
+    port = os.getenv("IRC_PORT", "").strip()
+    if port:
+        try:
+            seed["port"] = int(port)
+        except ValueError:
+            pass
+    nickname = os.getenv("IRC_NICKNAME", "").strip()
+    if nickname:
+        seed["nickname"] = nickname
+    use_tls = os.getenv("IRC_USE_TLS", "").strip().lower()
+    if use_tls:
+        seed["use_tls"] = use_tls in ("1", "true", "yes")
+    # Passwords live in PlatformConfig.extra as well for back-compat with
+    # existing config.yaml users; env-reads at construct time still win.
+    if os.getenv("IRC_SERVER_PASSWORD"):
+        seed["server_password"] = os.getenv("IRC_SERVER_PASSWORD")
+    if os.getenv("IRC_NICKSERV_PASSWORD"):
+        seed["nickserv_password"] = os.getenv("IRC_NICKSERV_PASSWORD")
+    # Optional home-channel (usually the same as IRC_CHANNEL, but can be a
+    # dedicated reports channel).  Defaults to IRC_CHANNEL so cron jobs
+    # with ``deliver=irc`` have a sensible target without extra config.
+    home = os.getenv("IRC_HOME_CHANNEL") or channel
+    if home:
+        seed["home_channel"] = {
+            "chat_id": home,
+            "name": os.getenv("IRC_HOME_CHANNEL_NAME", home),
+        }
+    return seed
+
+
 def register(ctx):
    """Plugin entry point — called by the Hermes plugin system."""
    ctx.register_platform(
@@ -665,6 +716,14 @@ def register(ctx):
        required_env=["IRC_SERVER", "IRC_CHANNEL", "IRC_NICKNAME"],
        install_hint="No extra packages needed (stdlib only)",
        setup_fn=interactive_setup,
+        # Env-driven auto-configuration — seeds PlatformConfig.extra with
+        # server/channel/port/tls + home_channel so env-only setups show
+        # up in gateway status without instantiating the adapter.
+        env_enablement_fn=_env_enablement,
+        # Cron home-channel delivery support.  IRC_HOME_CHANNEL defaults to
+        # IRC_CHANNEL (see _env_enablement), so cron jobs with
+        # deliver=irc route to the joined channel by default.
+        cron_deliver_env_var="IRC_HOME_CHANNEL",
        # Auth env vars for _is_user_authorized() integration
        allowed_users_env="IRC_ALLOWED_USERS",
        allow_all_env="IRC_ALLOW_ALL_USERS",
@@ -1,4 +1,5 @@
 name: irc-platform
+label: IRC
 kind: platform
 version: 1.0.0
 description: >
@@ -7,7 +8,47 @@ description: >
  (or DMs) and the Hermes agent.  No external dependencies — uses
  Python's stdlib asyncio for the IRC protocol.
 author: Nous Research
+# ``requires_env`` entries are surfaced in ``hermes config`` UI via the
+# platform-plugin env var injector in ``hermes_cli/config.py``.
 requires_env:
-  - IRC_SERVER
-  - IRC_CHANNEL
-  - IRC_NICKNAME
+  - name: IRC_SERVER
+    description: "IRC server hostname (e.g. irc.libera.chat)"
+    prompt: "IRC server"
+    password: false
+  - name: IRC_CHANNEL
+    description: "Channel to join (e.g. #hermes — comma-separate for multiple)"
+    prompt: "IRC channel"
+    password: false
+  - name: IRC_NICKNAME
+    description: "Bot nickname on IRC (default: hermes-bot)"
+    prompt: "Bot nickname"
+    password: false
+optional_env:
+  - name: IRC_PORT
+    description: "IRC server port (default: 6697 with TLS, 6667 without)"
+    prompt: "IRC port"
+    password: false
+  - name: IRC_USE_TLS
+    description: "Use TLS for the IRC connection (1/true/yes to enable, default: true on port 6697)"
+    prompt: "Use TLS? (true/false)"
+    password: false
+  - name: IRC_SERVER_PASSWORD
+    description: "Server password for the IRC PASS command (optional)"
+    prompt: "Server password (optional)"
+    password: true
+  - name: IRC_NICKSERV_PASSWORD
+    description: "NickServ password for automatic IDENTIFY on connect (optional)"
+    prompt: "NickServ password (optional)"
+    password: true
+  - name: IRC_ALLOWED_USERS
+    description: "Comma-separated IRC nicks allowed to talk to the bot"
+    prompt: "Allowed nicks (comma-separated)"
+    password: false
+  - name: IRC_ALLOW_ALL_USERS
+    description: "Allow anyone in the channel to talk to the bot (dev only)"
+    prompt: "Allow all users? (true/false)"
+    password: false
+  - name: IRC_HOME_CHANNEL
+    description: "Channel for cron / notification delivery (defaults to IRC_CHANNEL)"
+    prompt: "Home channel (or empty)"
+    password: false
@@ -152,6 +152,42 @@ def is_connected(config) -> bool:
    return validate_config(config)


+def _env_enablement() -> dict | None:
+    """Seed ``PlatformConfig.extra`` from env vars during gateway config load.
+
+    Called by the platform registry's env-enablement hook BEFORE adapter
+    construction, so ``gateway status`` and ``get_connected_platforms()``
+    reflect env-only configuration without instantiating the Teams SDK.
+    Returns ``None`` when Teams isn't minimally configured.
+
+    The special ``home_channel`` key in the returned dict becomes a proper
+    ``HomeChannel`` dataclass on the ``PlatformConfig`` via the core hook.
+    """
+    client_id = os.getenv("TEAMS_CLIENT_ID", "").strip()
+    client_secret = os.getenv("TEAMS_CLIENT_SECRET", "").strip()
+    tenant_id = os.getenv("TEAMS_TENANT_ID", "").strip()
+    if not (client_id and client_secret and tenant_id):
+        return None
+    seed: dict = {
+        "client_id": client_id,
+        "client_secret": client_secret,
+        "tenant_id": tenant_id,
+    }
+    port = os.getenv("TEAMS_PORT", "").strip()
+    if port:
+        try:
+            seed["port"] = int(port)
+        except ValueError:
+            pass
+    home = os.getenv("TEAMS_HOME_CHANNEL", "").strip()
+    if home:
+        seed["home_channel"] = {
+            "chat_id": home,
+            "name": os.getenv("TEAMS_HOME_CHANNEL_NAME", "Home"),
+        }
+    return seed
+
+
 # Keep the old name as an alias so existing test imports don't break.
 check_teams_requirements = check_requirements

@@ -371,8 +407,25 @@ class TeamsAdapter(BasePlatformAdapter):
            )

        # Only authorized users may click approval buttons.
+        # Default-deny: require either TEAMS_ALLOWED_USERS or an explicit
+        # TEAMS_ALLOW_ALL_USERS=true opt-in. Without one of these set, the
+        # bot silently treated every clicker as authorized — meaning any
+        # Teams user who could message the bot could approve dangerous commands.
        allowed_csv = os.getenv("TEAMS_ALLOWED_USERS", "").strip()
-        if allowed_csv:
+        allow_all = os.getenv("TEAMS_ALLOW_ALL_USERS", "").strip().lower() in ("1", "true", "yes")
+
+        if not allow_all:
+            if not allowed_csv:
+                logger.warning(
+                    "[teams] card action rejected: TEAMS_ALLOWED_USERS not configured "
+                    "and TEAMS_ALLOW_ALL_USERS not set — default deny"
+                )
+                return InvokeResponse(
+                    status=200,
+                    body=AdaptiveCardActionMessageResponse(
+                        value="⛔ Approval buttons require TEAMS_ALLOWED_USERS to be configured."
+                    ),
+                )
            from_account = ctx.activity.from_
            clicker_id = getattr(from_account, "aad_object_id", None) or getattr(from_account, "id", "")
            allowed_ids = {uid.strip() for uid in allowed_csv.split(",") if uid.strip()}
@@ -685,6 +738,14 @@ def register(ctx) -> None:
        required_env=["TEAMS_CLIENT_ID", "TEAMS_CLIENT_SECRET", "TEAMS_TENANT_ID"],
        install_hint="pip install microsoft-teams-apps aiohttp",
        setup_fn=interactive_setup,
+        # Env-driven auto-configuration — seeds PlatformConfig.extra with
+        # client_id/secret/tenant + port + home_channel so env-only setups
+        # show up in gateway status without instantiating the Teams SDK.
+        env_enablement_fn=_env_enablement,
+        # Cron home-channel delivery support.  Lets deliver=teams cron
+        # jobs route to the configured Teams chat/channel without editing
+        # cron/scheduler.py's hardcoded sets.
+        cron_deliver_env_var="TEAMS_HOME_CHANNEL",
        # Auth env vars for _is_user_authorized() integration
        allowed_users_env="TEAMS_ALLOWED_USERS",
        allow_all_env="TEAMS_ALLOW_ALL_USERS",
@@ -1,4 +1,5 @@
 name: teams-platform
+label: Microsoft Teams
 kind: platform
 version: 1.0.0
 description: >
@@ -7,7 +8,41 @@ description: >
  between Teams chats (personal DMs, group chats, channel posts) and
  the Hermes agent. Supports Adaptive Card approval prompts.
 author: Aamir Jawaid
+# ``requires_env`` entries are surfaced in ``hermes config`` UI via the
+# platform-plugin env var injector in ``hermes_cli/config.py``.
 requires_env:
-  - TEAMS_CLIENT_ID
-  - TEAMS_CLIENT_SECRET
-  - TEAMS_TENANT_ID
+  - name: TEAMS_CLIENT_ID
+    description: "Azure AD application (Bot Framework) client ID"
+    prompt: "Teams / Azure AD client ID"
+    url: "https://portal.azure.com/"
+    password: false
+  - name: TEAMS_CLIENT_SECRET
+    description: "Azure AD application client secret"
+    prompt: "Teams / Azure AD client secret"
+    url: "https://portal.azure.com/"
+    password: true
+  - name: TEAMS_TENANT_ID
+    description: "Azure AD tenant ID hosting the bot application"
+    prompt: "Teams / Azure AD tenant ID"
+    password: false
+optional_env:
+  - name: TEAMS_PORT
+    description: "Webhook listen port (Bot Framework default: 3978)"
+    prompt: "Webhook port"
+    password: false
+  - name: TEAMS_ALLOWED_USERS
+    description: "Comma-separated Teams user IDs / UPNs allowed to talk to the bot"
+    prompt: "Allowed users (comma-separated)"
+    password: false
+  - name: TEAMS_ALLOW_ALL_USERS
+    description: "Allow any Teams user to trigger the bot (dev only)"
+    prompt: "Allow all users? (true/false)"
+    password: false
+  - name: TEAMS_HOME_CHANNEL
+    description: "Default chat/channel ID for cron / notification delivery"
+    prompt: "Home channel (or empty)"
+    password: false
+  - name: TEAMS_HOME_CHANNEL_NAME
+    description: "Display name for the Teams home channel"
+    prompt: "Home channel display name"
+    password: false
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

 [project]
 name = "hermes-agent"
-version = "0.12.0"
+version = "0.13.0"
 description = "The self-improving AI agent — creates skills from experience, improves them during use, and runs anywhere"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -68,9 +68,7 @@ acp = ["agent-client-protocol>=0.9.0,<1.0"]
 mistral = ["mistralai>=2.3.0,<3"]
 bedrock = ["boto3>=1.35.0,<2"]
 termux = [
-  # Tested Android / Termux path: keeps the core CLI feature-rich while
-  # avoiding extras that currently depend on non-Android wheels (notably
-  # faster-whisper -> ctranslate2 via the voice extra).
+  # Baseline Android / Termux path for reliable fresh installs.
  "python-telegram-bot[webhooks]>=22.6,<23",
  "hermes-agent[cron]",
  "hermes-agent[cli]",
@@ -79,6 +77,27 @@ termux = [
  "hermes-agent[honcho]",
  "hermes-agent[acp]",
 ]
+termux-all = [
+  # Best-effort "install all" profile for Termux: include broad extras that
+  # are known to resolve on Android, while intentionally excluding extras that
+  # currently hard-fail from missing/broken Android wheels/toolchains.
+  #
+  # Excluded for now:
+  # - matrix (mautrix[encryption] -> python-olm build failures on Termux)
+  # - voice  (faster-whisper chain requires ctranslate2/av builds not packaged)
+  "hermes-agent[termux]",
+  "hermes-agent[messaging]",
+  "hermes-agent[slack]",
+  "hermes-agent[tts-premium]",
+  "hermes-agent[dingtalk]",
+  "hermes-agent[feishu]",
+  "hermes-agent[google]",
+  "hermes-agent[mistral]",
+  "hermes-agent[bedrock]",
+  "hermes-agent[homeassistant]",
+  "hermes-agent[sms]",
+  "hermes-agent[web]",
+]
 dingtalk = ["dingtalk-stream>=0.20,<1", "alibabacloud-dingtalk>=2.0.0", "qrcode>=7.0,<8"]
 feishu = ["lark-oapi>=1.5.3,<2", "qrcode>=7.0,<8"]
 google = [
@@ -135,7 +154,7 @@ hermes-agent = "run_agent:main"
 hermes-acp = "acp_adapter.entry:main"

 [tool.setuptools]
-py-modules = ["run_agent", "model_tools", "toolsets", "batch_runner", "trajectory_compressor", "toolset_distributions", "cli", "hermes_constants", "hermes_state", "hermes_time", "hermes_logging", "rl_cli", "utils"]
+py-modules = ["run_agent", "model_tools", "toolsets", "batch_runner", "trajectory_compressor", "toolset_distributions", "cli", "hermes_constants", "hermes_state", "hermes_time", "hermes_logging", "rl_cli", "utils", "utf8_bootstrap"]

 [tool.setuptools.package-data]
 hermes_cli = ["web_dist/**/*"]
@@ -58,6 +58,7 @@ from datetime import datetime
 from pathlib import Path

 from hermes_constants import get_hermes_home
+from utf8_bootstrap import ensure_windows_utf8_mode


 _OPENAI_CLS_CACHE: Optional[type] = None
@@ -1901,8 +1902,35 @@ class AIAgent:
                _aux_context_config = None
        self._aux_compression_context_length_config = _aux_context_config

-        # Read explicit context_length override from model config
+        # Read explicit model output-token override from config when the
+        # caller did not pass one directly.
        _model_cfg = _agent_cfg.get("model", {})
+        if self.max_tokens is None and isinstance(_model_cfg, dict):
+            _config_max_tokens = _model_cfg.get("max_tokens")
+            if _config_max_tokens is not None:
+                try:
+                    if isinstance(_config_max_tokens, bool):
+                        raise ValueError
+                    _parsed_max_tokens = int(_config_max_tokens)
+                    if _parsed_max_tokens <= 0:
+                        raise ValueError
+                    self.max_tokens = _parsed_max_tokens
+                except (TypeError, ValueError):
+                    logger.warning(
+                        "Invalid model.max_tokens in config.yaml: %r — "
+                        "must be a positive integer (e.g. 4096). "
+                        "Falling back to provider default.",
+                        _config_max_tokens,
+                    )
+                    print(
+                        f"\n⚠ Invalid model.max_tokens in config.yaml: {_config_max_tokens!r}\n"
+                        f"  Must be a positive integer (e.g. 4096).\n"
+                        f"  Falling back to provider default.\n",
+                        file=sys.stderr,
+                    )
+        self._session_init_model_config["max_tokens"] = self.max_tokens
+
+        # Read explicit context_length override from model config
        if isinstance(_model_cfg, dict):
            _config_context_length = _model_cfg.get("context_length")
        else:
@@ -2852,6 +2880,16 @@ class AIAgent:
            url = getattr(self, "_base_url_lower", "") or ""
        return "openai.azure.com" in url

+    def _is_github_copilot_url(self, base_url: str = None) -> bool:
+        """Return True when a base URL targets GitHub Copilot's OpenAI-compatible API."""
+        if base_url is not None:
+            hostname = base_url_hostname(base_url)
+        else:
+            hostname = getattr(self, "_base_url_hostname", "") or base_url_hostname(
+                getattr(self, "_base_url_lower", "")
+            )
+        return hostname == "api.githubcopilot.com"
+
    def _resolved_api_call_timeout(self) -> float:
        """Resolve the effective per-call request timeout in seconds.

@@ -3028,6 +3066,10 @@ class AIAgent:
    ) -> bool:
        """Return True when this provider/model pair should use Responses API."""
        normalized_provider = (provider or "").strip().lower()
+        # Nous serves GPT-5.x models via its OpenAI-compatible chat
+        # completions endpoint; its /v1/responses endpoint returns 404.
+        if normalized_provider == "nous":
+            return False
        if normalized_provider == "copilot":
            try:
                from hermes_cli.models import _should_use_copilot_responses_api
@@ -3047,7 +3089,7 @@ class AIAgent:
        OpenAI-compatible endpoint. OpenRouter, local models, and older
        OpenAI models use 'max_tokens'.
        """
-        if self._is_direct_openai_url() or self._is_azure_openai_url():
+        if self._is_direct_openai_url() or self._is_azure_openai_url() or self._is_github_copilot_url():
            return {"max_completion_tokens": value}
        return {"max_tokens": value}

@@ -3792,11 +3834,165 @@ class AIAgent:

        Ensures conversations are never lost, even on errors or early returns.
        """
+        self._drop_trailing_empty_response_scaffolding(messages)
        self._apply_persist_user_message_override(messages)
        self._session_messages = messages
        self._save_session_log(messages)
        self._flush_messages_to_session_db(messages, conversation_history)

+    def _drop_trailing_empty_response_scaffolding(self, messages: List[Dict]) -> None:
+        """Remove private empty-response retry/failure scaffolding from transcript tails.
+
+        Also rewinds past any trailing tool-result / assistant(tool_calls) pair
+        that the failed iteration left hanging. Without this, the tail ends at
+        a raw ``tool`` message and the next user turn lands as
+        ``...tool, user, user`` — a protocol-invalid sequence that most
+        providers silently reject (returns empty content), causing the
+        empty-retry loop to fire forever. See #<TBD>.
+        """
+        # Pass 1: strip the flagged scaffolding messages themselves.
+        dropped_scaffolding = False
+        while (
+            messages
+            and isinstance(messages[-1], dict)
+            and (
+                messages[-1].get("_empty_recovery_synthetic")
+                or messages[-1].get("_empty_terminal_sentinel")
+            )
+        ):
+            messages.pop()
+            dropped_scaffolding = True
+
+        # Pass 2: if we stripped scaffolding, rewind through any trailing
+        # tool-result messages plus the assistant(tool_calls) message that
+        # produced them. This preserves role alternation so the next user
+        # message follows a user or assistant message, not an orphan tool
+        # result. Only runs when scaffolding was actually present — normal
+        # conversation tails (real tool loops mid-progress) are untouched.
+        if not dropped_scaffolding:
+            return
+
+        # Drop any trailing tool-result messages
+        while (
+            messages
+            and isinstance(messages[-1], dict)
+            and messages[-1].get("role") == "tool"
+        ):
+            messages.pop()
+
+        # Drop the assistant message that issued the tool calls, if the tail
+        # now ends in an assistant-with-tool_calls (the pair that owned the
+        # just-popped tool results). Without this, the tail is
+        # ``assistant(tool_calls=...)`` with no tool answers, which some
+        # providers also reject.
+        if (
+            messages
+            and isinstance(messages[-1], dict)
+            and messages[-1].get("role") == "assistant"
+            and messages[-1].get("tool_calls")
+        ):
+            messages.pop()
+
+    def _repair_message_sequence(self, messages: List[Dict]) -> int:
+        """Collapse malformed role-alternation left in the live history.
+
+        Providers (OpenAI, OpenRouter, Anthropic) expect strict alternation:
+        after the system message, user/tool alternates with assistant, with
+        no two consecutive user messages and no tool-result that doesn't
+        follow an assistant-with-tool_calls. Violations cause silent empty
+        responses on most providers, which triggers the empty-retry loop.
+
+        This runs right before the API call as a defensive belt — by the
+        time it fires, the scaffolding strip should already have prevented
+        most shapes, but external callers (gateway multi-queue replay,
+        session resume, cron, explicit conversation_history passed in by
+        host code) can feed in already-broken histories.
+
+        Repairs applied:
+          1. Stray ``tool`` messages whose ``tool_call_id`` doesn't match
+             any preceding assistant tool_call — dropped.
+          2. Consecutive ``user`` messages — merged with newline separator
+             so no user input is lost.
+
+        Deliberately does NOT rewind orphan ``assistant(tool_calls)+tool``
+        pairs that precede a user message — that pattern IS valid when the
+        previous turn completed normally and the user jumped in to redirect
+        before the model got a continuation turn (the ongoing dialog
+        pattern). The empty-response scaffolding stripper handles the
+        genuinely-broken variant via its flag-gated rewind.
+
+        Returns the number of repairs made (for logging/telemetry).
+        """
+        if not messages:
+            return 0
+
+        repairs = 0
+
+        # Pass 1: drop stray tool messages that don't follow a known
+        # assistant tool_call_id. Uses a rolling set of known ids refreshed
+        # on each assistant message.
+        known_tool_ids: set = set()
+        filtered: List[Dict] = []
+        for msg in messages:
+            if not isinstance(msg, dict):
+                filtered.append(msg)
+                continue
+            role = msg.get("role")
+            if role == "assistant":
+                known_tool_ids = set()
+                for tc in (msg.get("tool_calls") or []):
+                    tc_id = tc.get("id") if isinstance(tc, dict) else None
+                    if tc_id:
+                        known_tool_ids.add(tc_id)
+                filtered.append(msg)
+            elif role == "tool":
+                tc_id = msg.get("tool_call_id")
+                if tc_id and tc_id in known_tool_ids:
+                    filtered.append(msg)
+                else:
+                    repairs += 1
+            else:
+                if role == "user":
+                    # A user turn closes the tool-result run; subsequent
+                    # tool messages without a fresh assistant tool_call
+                    # are orphans.
+                    known_tool_ids = set()
+                filtered.append(msg)
+
+        # Pass 2: merge consecutive user messages. Preserves all user input
+        # so nothing the user typed is lost.
+        merged: List[Dict] = []
+        for msg in filtered:
+            if (
+                merged
+                and isinstance(msg, dict)
+                and msg.get("role") == "user"
+                and isinstance(merged[-1], dict)
+                and merged[-1].get("role") == "user"
+            ):
+                prev = merged[-1]
+                prev_content = prev.get("content", "")
+                new_content = msg.get("content", "")
+                # Only merge plain-text content; leave multimodal (list)
+                # content alone — collapsing image/audio blocks risks
+                # mangling the attachment structure.
+                if isinstance(prev_content, str) and isinstance(new_content, str):
+                    prev["content"] = (
+                        (prev_content + "\n\n" + new_content)
+                        if prev_content and new_content
+                        else (prev_content or new_content)
+                    )
+                    repairs += 1
+                    continue
+            merged.append(msg)
+
+        if repairs > 0:
+            # Rewrite in place so downstream paths (persistence, return
+            # value, session DB flush) see the repaired sequence.
+            messages[:] = merged
+
+        return repairs
+
    def _flush_messages_to_session_db(self, messages: List[Dict], conversation_history: List[Dict] = None):
        """Persist any un-flushed messages to the SQLite session store.

@@ -11083,6 +11279,21 @@ class AIAgent:
                    self.session_id or "-",
                )

+            # Defensive: repair malformed role-alternation before API call.
+            # Catches cases where the history got wedged into a
+            # ``tool → user`` or ``user → user`` tail (e.g. after empty-
+            # response scaffolding was stripped and a new user message
+            # landed after an orphan tool result). Most providers return
+            # empty content on malformed sequences, which would otherwise
+            # retrigger the empty-retry loop indefinitely.
+            repaired_seq = self._repair_message_sequence(messages)
+            if repaired_seq > 0:
+                request_logger.info(
+                    "Repaired %s message-alternation violations before request (session=%s)",
+                    repaired_seq,
+                    self.session_id or "-",
+                )
+
            api_messages = []
            for idx, msg in enumerate(messages):
                api_msg = msg.copy()
@@ -11921,6 +12132,14 @@ class AIAgent:
                        # deltas instead of double-counting them.
                        if self._session_db and self.session_id:
                            try:
+                                # Ensure the session row exists before attempting UPDATE.
+                                # Under concurrent load (cron/kanban), the initial
+                                # _ensure_db_session() may have failed due to SQLite
+                                # locking.  Retry here so per-call token deltas are
+                                # not silently lost (UPDATE on a non-existent row
+                                # affects 0 rows without error).
+                                if not self._session_db_created:
+                                    self._ensure_db_session()
                                self._session_db.update_token_counts(
                                    self.session_id,
                                    input_tokens=canonical_usage.input_tokens,
@@ -11939,8 +12158,14 @@ class AIAgent:
                                    model=self.model,
                                    api_call_count=1,
                                )
-                            except Exception:
-                                pass  # never block the agent loop
+                            except Exception as e:
+                                # Log token persistence failures so they're
+                                # visible in agent.log — silent loss here is
+                                # the root cause of undercounted analytics.
+                                logger.debug(
+                                    "Token persistence failed (session=%s, tokens=%d): %s",
+                                    self.session_id, total_tokens, e,
+                                )
                        
                        if self.verbose_logging:
                            logging.debug(f"Token usage: prompt={usage_dict['prompt_tokens']:,}, completion={usage_dict['completion_tokens']:,}, total={usage_dict['total_tokens']:,}")
@@ -13706,6 +13931,7 @@ class AIAgent:
                            # APIs reject as an invalid sequence.
                            _nudge_msg = self._build_assistant_message(assistant_message, finish_reason)
                            _nudge_msg["content"] = "(empty)"
+                            _nudge_msg["_empty_recovery_synthetic"] = True
                            messages.append(_nudge_msg)
                            messages.append({
                                "role": "user",
@@ -13714,6 +13940,7 @@ class AIAgent:
                                    "empty response. Please process the tool "
                                    "results above and continue with the task."
                                ),
+                                "_empty_recovery_synthetic": True,
                            })
                            continue

@@ -13816,8 +14043,15 @@ class AIAgent:
                        # "(empty)" terminal.
                        _turn_exit_reason = "empty_response_exhausted"
                        reasoning_text = self._extract_reasoning(assistant_message)
+                        self._drop_trailing_empty_response_scaffolding(messages)
                        assistant_msg = self._build_assistant_message(assistant_message, finish_reason)
                        assistant_msg["content"] = "(empty)"
+                        # This is a user-facing failure sentinel for the gateway,
+                        # not real assistant content. Persisting it makes later
+                        # "continue" turns replay assistant("(empty)") as if it
+                        # were a meaningful model response, which can keep long
+                        # tool-heavy sessions stuck in empty-response loops.
+                        assistant_msg["_empty_terminal_sentinel"] = True
                        messages.append(assistant_msg)

                        if reasoning_text:
@@ -13890,14 +14124,18 @@ class AIAgent:
                    
                    final_msg = self._build_assistant_message(assistant_message, finish_reason)

-                    # Pop thinking-only prefill message(s) before appending
-                    # the final response.  This avoids consecutive assistant
-                    # messages which break strict-alternation providers
-                    # (Anthropic Messages API) and keeps history clean.
+                    # Pop thinking-only prefill and empty-response retry
+                    # scaffolding before appending the final response.  These
+                    # internal turns are only for the next API retry and should
+                    # not become durable transcript context.
                    while (
                        messages
                        and isinstance(messages[-1], dict)
-                        and messages[-1].get("_thinking_prefill")
+                        and (
+                            messages[-1].get("_thinking_prefill")
+                            or messages[-1].get("_empty_recovery_synthetic")
+                            or messages[-1].get("_empty_terminal_sentinel")
+                        )
                    ):
                        messages.pop()

@@ -13988,7 +14226,11 @@ class AIAgent:
        # Clean up VM and browser for this task after conversation completes
        self._cleanup_task_resources(effective_task_id)

-        # Persist session to both JSON log and SQLite
+        # Persist session to both JSON log and SQLite only after private retry
+        # scaffolding has been removed. Otherwise a later user "continue" turn
+        # can replay assistant("(empty)") / recovery nudges and fall into the
+        # same empty-response loop again.
+        self._drop_trailing_empty_response_scaffolding(messages)
        self._persist_session(messages, conversation_history)

        # ── Turn-exit diagnostic log ─────────────────────────────────────
@@ -14035,6 +14277,27 @@ class AIAgent:
        else:
            logger.info(_diag_msg, *_diag_args)

+        # Plugin hook: transform_llm_output
+        # Fired once per turn after the tool-calling loop completes.
+        # Plugins can transform the LLM's output text before it's returned.
+        # First hook to return a string wins; None/empty return leaves text unchanged.
+        if final_response and not interrupted:
+            try:
+                from hermes_cli.plugins import invoke_hook as _invoke_hook
+                _transform_results = _invoke_hook(
+                    "transform_llm_output",
+                    response_text=final_response,
+                    session_id=self.session_id or "",
+                    model=self.model,
+                    platform=getattr(self, "platform", None) or "",
+                )
+                for _hook_result in _transform_results:
+                    if isinstance(_hook_result, str) and _hook_result:
+                        final_response = _hook_result
+                        break  # First non-empty string wins
+            except Exception as exc:
+                logger.warning("transform_llm_output hook failed: %s", exc)
+
        # Plugin hook: post_llm_call
        # Fired once per turn after the tool-calling loop completes.
        # Plugins can use this to persist conversation data (e.g. sync
@@ -14221,6 +14484,11 @@ def main(
    Toolset Examples:
        - "research": Web search, extract, crawl + vision tools
    """
+    ensure_windows_utf8_mode(
+        module="run_agent",
+        entrypoint_markers=("hermes-agent", "run_agent.py"),
+    )
+
    print("🤖 AI Agent with Tool Calling")
    print("=" * 50)
    
--- a/Show More
+++ b/Show More