fix: respect disabled auto-compaction on context overflow

Port from anomalyco/opencode#30749.

When compression.enabled is false, NO automatic compaction trigger may
fire. The proactive token-threshold paths (preflight + post-response
should_compress gate) already honoured the setting, but the three
provider-overflow recovery paths in the agent loop — long-context-tier
429, 413 payload-too-large, and context-overflow — called
_compress_context() unconditionally, silently compressing and rotating
the session against the user's explicit choice.

Add a single guard at the top of the overflow-recovery dispatch: when
compression is disabled and the error is one of those three overflow
classes, surface a terminal error (compaction_disabled: True) telling the
user to /compress manually, /new, switch to a larger-context model, or
reduce attachments. Manual /compress (force=True) is unaffected — it never
enters this loop.

Tests: new TestOverflowWithCompactionDisabled (413 + 400 overflow don't
compress when disabled; control case still compresses when enabled).
Existing overflow-recovery tests updated to enable compaction explicitly
(they verify the recovery fires); fixture defaults flipped to True to
match production (compression.enabled defaults to True).

.dockerignore

@@ -3,6 +3,21 @@
 .gitignore
 .gitmodules
 
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+venv/
+env/
+ENV/
+
 # Dependencies
 node_modules
 **/node_modules
@@ -24,7 +39,20 @@ ui-tui/packages/hermes-ink/dist/
 
 # Environment files
 .env
+.env.*
 
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Documentation
 *.md
 
 # Runtime data (bind-mounted at /opt/data; must not leak into build context)

.gitattributes

@@ -1,2 +1,10 @@
 # Auto-generated files — collapse diffs and exclude from language stats
 web/package-lock.json linguist-generated=true
+
+# Enforce LF for scripts that run inside Linux containers.
+# Without this, Windows checkout converts to CRLF and breaks `exec` in the
+# container entrypoint with "no such file or directory".
+*.sh        text eol=lf
+Dockerfile  text eol=lf
+*.dockerfile text eol=lf
+docker/entrypoint.sh text eol=lf

.github/workflows/tests.yml

@@ -171,6 +171,11 @@ jobs:
           source .venv/bin/activate
           uv pip install -e ".[all,dev]"
 
+      - name: Packaged-wheel i18n smoke test
+        run: |
+          source .venv/bin/activate
+          python -m pytest -m integration tests/test_wheel_locales_e2e.py -v
+
       - name: Run e2e tests
         run: |
           source .venv/bin/activate

.gitignore

@@ -1,5 +1,6 @@
 .DS_Store
 /venv/
+/venv.old/
 /_pycache/
 *.pyc*
 __pycache__/

AGENTS.md

@@ -283,6 +283,21 @@ The dashboard embeds the real `hermes --tui` — **not** a rewrite.  See `hermes
 
 **Structured React UI around the TUI is allowed when it is not a second chat surface.** Sidebar widgets, inspectors, summaries, status panels, and similar supporting views (e.g. `ChatSidebar`, `ModelPickerDialog`, `ToolCall`) are fine when they complement the embedded TUI rather than replacing the transcript / composer / terminal. Keep their state independent of the PTY child's session and surface their failures non-destructively so the terminal pane keeps working unimpaired.
 
+### Electron Desktop Chat App (`apps/desktop/`)
+
+A **separate** chat surface from both the classic CLI and the dashboard's embedded TUI. It is an Electron + React + nanostore renderer (`@assistant-ui/react`) that talks to a `tui_gateway` backend over JSON-RPC (`requestGateway(method, params)`). It does NOT embed `hermes --tui` — it has its own composer, transcript, and slash-command pipeline. Route desktop bugs to the `hermes-desktop-app-work` skill, not `hermes-dashboard-work`.
+
+**Slash commands in the desktop app are curated client-side, then dispatched to the backend.** The pipeline:
+
+- **Backend already provides everything.** `tui_gateway/server.py` `commands.catalog` (empty-query list) and `complete.slash` (typed-query completions) both include built-in commands, user `quick_commands`, AND skill-derived commands (`scan_skill_commands()` / `get_skill_commands()`). The desktop app does not need a new RPC to see skills.
+- **The renderer curates via `apps/desktop/src/lib/desktop-slash-commands.ts`.** This is the load-bearing file. It holds `DESKTOP_COMMANDS` (the ~19 built-ins shown in the palette) plus block-lists for terminal-only / messaging-only / picker-owned / settings-owned / advanced commands that should NOT clutter the desktop popover.
+  - `isDesktopSlashCommand(name)` — gates **execution**. Returns true for built-ins AND for any non-built-in (skill / quick command), so typed extension commands run.
+  - `isDesktopSlashSuggestion(name)` — gates **discovery/completion**. Used by BOTH completion paths in `app/chat/composer/hooks/use-slash-completions.ts` (empty-query catalog filter + typed-query `complete.slash` filter) and by `filterDesktopCommandsCatalog`.
+  - `isDesktopSlashExtensionCommand(name)` — true when the command is NOT a known Hermes built-in (i.e. a skill or user quick command). Both suggestion and catalog-filter paths allow extensions through so skill commands surface in the palette. (Added when fixing "skill commands missing from the desktop slash palette" — the curated allow-list was silently dropping every skill/quick command from completions even though they executed fine when typed.)
+- **Dispatch** lives in `app/session/hooks/use-prompt-actions.ts` (`runSlash`): built-ins that the desktop owns (`/skin`, `/help`, `/new`, …) are handled locally or via `commands.catalog`; everything else goes to `slash.exec`, falling back to `command.dispatch` (which the gateway resolves into skill / alias / exec directives). A skill command resolves to `{type: "skill", message}` and is submitted as a normal prompt.
+
+**Rule:** the desktop slash palette's curation is about hiding noise (terminal-only / messaging-only built-ins), NOT about hiding user-activated extensions. Skill commands and `quick_commands` are extensions the backend surfaces — they belong in completions. If you tighten `desktop-slash-commands.ts`, keep `isDesktopSlashExtensionCommand` flowing into both the suggestion and catalog-filter paths. Tests: `apps/desktop/src/lib/desktop-slash-commands.test.ts` (run via the repo-root `vitest`, since `apps/desktop` resolves deps from the root workspace install).
+
 ---
 
 ## Adding New Tools

CONTRIBUTING.md

@@ -73,7 +73,7 @@ This isn't a quality bar — it's a coupling-and-maintenance decision. Memory pr
 
 | Requirement | Notes |
 |-------------|-------|
-| **Git** | With `--recurse-submodules` support, and the `git-lfs` extension installed |
+| **Git** | With the `git-lfs` extension installed |
 | **Python 3.11+** | uv will install it if missing |
 | **uv** | Fast Python package manager ([install](https://docs.astral.sh/uv/)) |
 | **Node.js 20+** | Optional — needed for browser tools and WhatsApp bridge (matches root `package.json` engines) |

Dockerfile

@@ -25,7 +25,7 @@ ENV PLAYWRIGHT_BROWSERS_PATH=/opt/hermes/.playwright
 # hermes process, the dashboard, and per-profile gateways.
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
-    ca-certificates curl iputils-ping python3 python-is-python3 ripgrep ffmpeg gcc python3-dev python3-venv libffi-dev procps git openssh-client docker-cli xz-utils && \
+    ca-certificates curl iputils-ping python3 python-is-python3 ripgrep ffmpeg gcc python3-dev python3-venv libffi-dev libolm-dev procps git openssh-client docker-cli xz-utils && \
     rm -rf /var/lib/apt/lists/*
 
 # ---------- s6-overlay install ----------
@@ -157,10 +157,17 @@ RUN npm install --prefer-offline --no-audit && \
 # so Docker users can use these providers without requiring runtime
 # lazy-install access to PyPI (often blocked in containerized envs).
 #
+# The hindsight memory provider's client (hindsight-client) is baked in
+# for the same reason: it lazy-installs into /opt/hermes/.venv at first
+# use, which lives inside the (immutable) image layer rather than the
+# mounted /opt/data volume, so it is lost on every container recreate /
+# image update and recall/retain then fails with
+# `ModuleNotFoundError: No module named 'hindsight_client'` (#38128).
+#
 # The editable link is created after the source copy below.
 COPY pyproject.toml uv.lock ./
 RUN touch ./README.md
-RUN uv sync --frozen --no-install-project --extra all --extra messaging --extra anthropic --extra bedrock --extra azure-identity
+RUN uv sync --frozen --no-install-project --extra all --extra messaging --extra anthropic --extra bedrock --extra azure-identity --extra hindsight
 
 # ---------- Source code ----------
 # .dockerignore excludes node_modules, so the installs above survive.
@@ -178,13 +185,16 @@ RUN cd web && npm run build && \
 # 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.
+# /opt/hermes/gateway is runtime-writable: Python may create __pycache__ and
+# gateway state artifacts beneath the package after services drop privileges,
+# especially when the hermes UID is remapped at boot (#27221).
 # The .venv MUST remain hermes-writable so lazy_deps.py can install
 # remaining optional platform packages and future pin bumps at first use.
 # Without this, `uv pip install` fails with EACCES and adapters silently
 # fail to load.  See tools/lazy_deps.py.
 USER root
 RUN chmod -R a+rX /opt/hermes && \
-    chown -R hermes:hermes /opt/hermes/.venv /opt/hermes/ui-tui /opt/hermes/node_modules
+    chown -R hermes:hermes /opt/hermes/.venv /opt/hermes/ui-tui /opt/hermes/gateway /opt/hermes/node_modules
 # Start as root so the s6-overlay stage2 hook can usermod/groupmod and chown
 # the data volume. Each supervised service then drops to the hermes user via
 # `s6-setuidgid hermes` in its run script. If HERMES_UID is unset, services

MANIFEST.in

@@ -1,5 +1,6 @@
 graft skills
 graft optional-skills
+graft locales
 # Bundled plugin manifests (plugin.yaml / plugin.yml). Without these the
 # PluginManager scan (hermes_cli/plugins.py) finds zero plugins on installs
 # built from the sdist (e.g. Homebrew, downstream packagers). package-data

README.md

@@ -94,7 +94,7 @@ One command from a fresh install:
 hermes setup --portal
 ```
 
-That logs you in via OAuth, sets Nous as your provider, and turns on the Tool Gateway. Check what's wired up any time with `hermes portal status`. Full details on the [Tool Gateway docs page](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway).
+That logs you in via OAuth, sets Nous as your provider, and turns on the Tool Gateway. Check what's wired up any time with `hermes portal info`. Full details on the [Tool Gateway docs page](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway).
 
 You can still bring your own keys per-tool whenever you want — the gateway is per-backend, not all-or-nothing.
 

README.zh-CN.md

@@ -80,7 +80,7 @@ Hermes 始终允许你使用任意服务商，这点不会改变。但如果你
 hermes setup --portal
 ```
 
-它会通过 OAuth 登录、把 Nous 设为推理服务商，并启用 Tool Gateway。随时用 `hermes portal status` 查看路由状态。完整说明见 [Tool Gateway 文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway)。
+它会通过 OAuth 登录、把 Nous 设为推理服务商，并启用 Tool Gateway。随时用 `hermes portal info` 查看路由状态。完整说明见 [Tool Gateway 文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway)。
 
 你随时可以按工具单独切回自己的 API Key — Gateway 是按工具粒度生效的，不是一刀切。
 

agent/agent_runtime_helpers.py

@@ -47,6 +47,20 @@ def _ra():
     return run_agent
 
 
+AGENT_RUNTIME_POST_HOOK_TOOL_NAMES = frozenset(
+    {"todo", "session_search", "memory", "clarify", "delegate_task"}
+)
+
+
+def agent_runtime_owns_post_tool_hook(agent: Any, function_name: str) -> bool:
+    """Return True when an agent-level tool path emits its own post hook."""
+    if function_name in AGENT_RUNTIME_POST_HOOK_TOOL_NAMES:
+        return True
+    if getattr(agent, "_context_engine_tool_names", None) and function_name in agent._context_engine_tool_names:
+        return True
+    memory_manager = getattr(agent, "_memory_manager", None)
+    return bool(memory_manager and memory_manager.has_tool(function_name))
+
 
 def convert_to_trajectory_format(agent, messages: List[Dict[str, Any]], user_query: str, completed: bool) -> List[Dict[str, Any]]:
     """
@@ -1618,36 +1632,84 @@ def invoke_tool(agent, function_name: str, function_args: dict, effective_task_i
         try:
             from hermes_cli.plugins import get_pre_tool_call_block_message
             block_message = get_pre_tool_call_block_message(
-                function_name, function_args, task_id=effective_task_id or "",
+                function_name,
+                function_args,
+                task_id=effective_task_id or "",
+                session_id=getattr(agent, "session_id", "") or "",
+                tool_call_id=tool_call_id or "",
+                turn_id=getattr(agent, "_current_turn_id", "") or "",
+                api_request_id=getattr(agent, "_current_api_request_id", "") or "",
             )
         except Exception:
             pass
     if block_message is not None:
-        return json.dumps({"error": block_message}, ensure_ascii=False)
+        result = json.dumps({"error": block_message}, ensure_ascii=False)
+        try:
+            from model_tools import _emit_post_tool_call_hook
+            _emit_post_tool_call_hook(
+                function_name=function_name,
+                function_args=function_args,
+                result=result,
+                task_id=effective_task_id or "",
+                session_id=getattr(agent, "session_id", "") or "",
+                tool_call_id=tool_call_id or "",
+                turn_id=getattr(agent, "_current_turn_id", "") or "",
+                api_request_id=getattr(agent, "_current_api_request_id", "") or "",
+                status="blocked",
+                error_type="plugin_block",
+                error_message=block_message,
+            )
+        except Exception:
+            pass
+        return result
+
+    tool_start_time = time.monotonic()
+
+    def _finish_agent_tool(result: Any) -> Any:
+        try:
+            from model_tools import _emit_post_tool_call_hook
+            _emit_post_tool_call_hook(
+                function_name=function_name,
+                function_args=function_args,
+                result=result,
+                task_id=effective_task_id or "",
+                session_id=getattr(agent, "session_id", "") or "",
+                tool_call_id=tool_call_id or "",
+                turn_id=getattr(agent, "_current_turn_id", "") or "",
+                api_request_id=getattr(agent, "_current_api_request_id", "") or "",
+                duration_ms=int((time.monotonic() - tool_start_time) * 1000),
+            )
+        except Exception:
+            pass
+        return result
 
     if function_name == "todo":
         from tools.todo_tool import todo_tool as _todo_tool
-        return _todo_tool(
-            todos=function_args.get("todos"),
-            merge=function_args.get("merge", False),
-            store=agent._todo_store,
+        return _finish_agent_tool(
+            _todo_tool(
+                todos=function_args.get("todos"),
+                merge=function_args.get("merge", False),
+                store=agent._todo_store,
+            )
         )
     elif function_name == "session_search":
         session_db = agent._get_session_db_for_recall()
         if not session_db:
             from hermes_state import format_session_db_unavailable
-            return json.dumps({"success": False, "error": format_session_db_unavailable()})
+            return _finish_agent_tool(json.dumps({"success": False, "error": format_session_db_unavailable()}))
         from tools.session_search_tool import session_search as _session_search
-        return _session_search(
-            query=function_args.get("query", ""),
-            role_filter=function_args.get("role_filter"),
-            limit=function_args.get("limit", 3),
-            session_id=function_args.get("session_id"),
-            around_message_id=function_args.get("around_message_id"),
-            window=function_args.get("window", 5),
-            sort=function_args.get("sort"),
-            db=session_db,
-            current_session_id=agent.session_id,
+        return _finish_agent_tool(
+            _session_search(
+                query=function_args.get("query", ""),
+                role_filter=function_args.get("role_filter"),
+                limit=function_args.get("limit", 3),
+                session_id=function_args.get("session_id"),
+                around_message_id=function_args.get("around_message_id"),
+                window=function_args.get("window", 5),
+                sort=function_args.get("sort"),
+                db=session_db,
+                current_session_id=agent.session_id,
+            )
         )
     elif function_name == "memory":
         target = function_args.get("target", "memory")
@@ -1673,23 +1735,27 @@ def invoke_tool(agent, function_name: str, function_args: dict, effective_task_i
                 )
             except Exception:
                 pass
-        return result
+        return _finish_agent_tool(result)
     elif agent._memory_manager and agent._memory_manager.has_tool(function_name):
-        return agent._memory_manager.handle_tool_call(function_name, function_args)
+        return _finish_agent_tool(agent._memory_manager.handle_tool_call(function_name, function_args))
     elif function_name == "clarify":
         from tools.clarify_tool import clarify_tool as _clarify_tool
-        return _clarify_tool(
-            question=function_args.get("question", ""),
-            choices=function_args.get("choices"),
-            callback=agent.clarify_callback,
+        return _finish_agent_tool(
+            _clarify_tool(
+                question=function_args.get("question", ""),
+                choices=function_args.get("choices"),
+                callback=agent.clarify_callback,
+            )
         )
     elif function_name == "delegate_task":
-        return agent._dispatch_delegate_task(function_args)
+        return _finish_agent_tool(agent._dispatch_delegate_task(function_args))
     else:
         return _ra().handle_function_call(
             function_name, function_args, effective_task_id,
             tool_call_id=tool_call_id,
             session_id=agent.session_id or "",
+            turn_id=getattr(agent, "_current_turn_id", "") or "",
+            api_request_id=getattr(agent, "_current_api_request_id", "") or "",
             enabled_tools=list(agent.valid_tool_names) if agent.valid_tool_names else None,
             skip_pre_tool_call_hook=True,
             enabled_toolsets=getattr(agent, "enabled_toolsets", None),

agent/auxiliary_client.py

@@ -265,9 +265,6 @@ _API_KEY_PROVIDER_AUX_MODELS_FALLBACK: Dict[str, str] = {
     "stepfun": "step-3.5-flash",
     "kimi-coding-cn": "kimi-k2-turbo-preview",
     "gmi": "google/gemini-3.1-flash-lite-preview",
-    "minimax": "MiniMax-M2.7",
-    "minimax-oauth": "MiniMax-M2.7-highspeed",
-    "minimax-cn": "MiniMax-M2.7",
     "anthropic": "claude-haiku-4-5-20251001",
     "opencode-zen": "gemini-3-flash",
     "opencode-go": "glm-5",
@@ -4756,10 +4753,14 @@ def _is_anthropic_compat_endpoint(provider: str, base_url: str) -> bool:
 
 
 def _convert_openai_images_to_anthropic(messages: list) -> list:
-    """Convert OpenAI ``image_url`` content blocks to Anthropic ``image`` blocks.
+    """Convert OpenAI ``image_url``/``video_url`` blocks to Anthropic format.
 
-    Only touches messages that have list-type content with ``image_url`` blocks;
-    plain text messages pass through unchanged.
+    Converts:
+    - ``image_url`` blocks to Anthropic ``image`` blocks
+    - ``video_url`` blocks to Anthropic ``video`` blocks (MiniMax M3 compat)
+
+    Only touches messages that have list-type content with ``image_url`` or
+    ``video_url`` blocks; plain text messages pass through unchanged.
     """
     converted = []
     for msg in messages:
@@ -4796,6 +4797,39 @@ def _convert_openai_images_to_anthropic(messages: list) -> list:
                         },
                     })
                 changed = True
+            elif block.get("type") == "video_url":
+                # MiniMax's Anthropic-compatible endpoint expects a "video"
+                # block (not OpenAI's "video_url", and not "input_video").
+                # See https://platform.minimax.io/docs/api-reference/text-anthropic-api
+                # — the Messages-field table lists type="video" (M3 only,
+                # URL/base64/mm_file://). The source shape mirrors the "image"
+                # block: base64 → {type:"base64", media_type, data}, URL →
+                # {type:"url", url}.
+                video_url_val = (block.get("video_url") or {}).get("url", "")
+                if video_url_val.startswith("data:"):
+                    # Parse data URI: data:<media_type>;base64,<data>
+                    header, _, b64data = video_url_val.partition(",")
+                    media_type = "video/mp4"
+                    if ":" in header and ";" in header:
+                        media_type = header.split(":", 1)[1].split(";", 1)[0]
+                    new_content.append({
+                        "type": "video",
+                        "source": {
+                            "type": "base64",
+                            "media_type": media_type,
+                            "data": b64data,
+                        },
+                    })
+                else:
+                    # URL-based video
+                    new_content.append({
+                        "type": "video",
+                        "source": {
+                            "type": "url",
+                            "url": video_url_val,
+                        },
+                    })
+                changed = True
             else:
                 new_content.append(block)
         converted.append({**msg, "content": new_content} if changed else msg)

agent/chat_completion_helpers.py

@@ -1296,7 +1296,7 @@ def handle_max_iterations(agent, messages: list, api_call_count: int) -> str:
             for internal_key in [k for k in api_msg if isinstance(k, str) and k.startswith("_")]:
                 api_msg.pop(internal_key, None)
             if _needs_sanitize:
-                agent._sanitize_tool_calls_for_strict_api(api_msg)
+                agent._sanitize_tool_calls_for_strict_api(api_msg, model=agent.model)
             api_messages.append(api_msg)
 
         effective_system = agent._cached_system_prompt or ""

agent/conversation_compression.py

@@ -646,6 +646,11 @@ def try_shrink_image_parts_in_messages(api_messages: list) -> bool:
     # much larger; shrinking to 4 MB here loses quality but only fires
     # after a confirmed provider rejection, so the alternative is failure.
     target_bytes = 4 * 1024 * 1024
+    # Anthropic enforces an 8000px per-side dimension cap independently of
+    # the 5 MB byte cap.  A tall screenshot can be well under 5 MB yet far
+    # over 8000px (e.g. 1200×12000 at 0.06 MB).  We check pixel dimensions
+    # even when the byte budget is fine.
+    max_dimension = 8000
     changed_count = 0
     # Track parts that are over the target but could NOT be shrunk under it.
     # If any survive, retrying is pointless — the same oversized payload will
@@ -658,9 +663,30 @@ def try_shrink_image_parts_in_messages(api_messages: list) -> bool:
         """Return a smaller data URL, or None if shrink can't help."""
         if not isinstance(url, str) or not url.startswith("data:"):
             return None
-        if len(url) <= target_bytes:
-            # This specific image wasn't the oversized one.
-            return None
+
+        # Check both byte size AND pixel dimensions.
+        needs_shrink = len(url) > target_bytes  # over byte budget
+        if not needs_shrink:
+            # Even if bytes are fine, check pixel dimensions against
+            # Anthropic's 8000px cap.  A tall image can be tiny in bytes
+            # yet huge in pixels.
+            try:
+                import base64 as _b64_dim
+                header_d, _, data_d = url.partition(",")
+                if not data_d:
+                    return None
+                raw_d = _b64_dim.b64decode(data_d)
+                from PIL import Image as _PILImage
+                import io as _io_dim
+                with _PILImage.open(_io_dim.BytesIO(raw_d)) as _img:
+                    if max(_img.size) <= max_dimension:
+                        return None  # both bytes and pixels are fine
+                needs_shrink = True  # pixels exceed limit, force shrink
+            except Exception:
+                # If we can't check dimensions (Pillow unavailable, corrupt
+                # image, etc.), fall back to byte-only check.
+                return None
+
         try:
             header, _, data = url.partition(",")
             mime = "image/jpeg"
@@ -684,6 +710,7 @@ def try_shrink_image_parts_in_messages(api_messages: list) -> bool:
                     Path(tmp.name),
                     mime_type=mime,
                     max_base64_bytes=target_bytes,
+                    max_dimension=max_dimension,
                 )
             finally:
                 try:

agent/conversation_loop.py

@@ -435,6 +435,9 @@ def run_conversation(
     # state registry.  Set BEFORE any tool dispatch so snapshots taken at
     # child-launch time see the parent's real id, not None.
     agent._current_task_id = effective_task_id
+    turn_id = f"{agent.session_id or 'session'}:{effective_task_id}:{uuid.uuid4().hex[:8]}"
+    agent._current_turn_id = turn_id
+    agent._current_api_request_id = ""
     
     # Reset retry counters and iteration budget at the start of each turn
     # so subagent usage from a previous turn doesn't eat into the next one.
@@ -702,6 +705,8 @@ def run_conversation(
         _pre_results = _invoke_hook(
             "pre_llm_call",
             session_id=agent.session_id,
+            task_id=effective_task_id,
+            turn_id=turn_id,
             user_message=original_user_message,
             conversation_history=list(messages),
             is_first_turn=(not bool(conversation_history)),
@@ -977,7 +982,7 @@ def run_conversation(
             # Uses new dicts so the internal messages list retains the fields
             # for Codex Responses compatibility.
             if agent._should_sanitize_tool_calls():
-                agent._sanitize_tool_calls_for_strict_api(api_msg)
+                agent._sanitize_tool_calls_for_strict_api(api_msg, model=agent.model)
             # Keep 'reasoning_details' - OpenRouter uses this for multi-turn reasoning context
             # The signature field helps maintain reasoning continuity
             api_messages.append(api_msg)
@@ -1153,6 +1158,8 @@ def run_conversation(
         finish_reason = "stop"
         response = None  # Guard against UnboundLocalError if all retries fail
         api_kwargs = None  # Guard against UnboundLocalError in except handler
+        api_request_id = f"{turn_id}:api:{api_call_count}"
+        agent._current_api_request_id = api_request_id
 
         while retry_count < max_retries:
             # ── Nous Portal rate limit guard ──────────────────────
@@ -1220,37 +1227,58 @@ def run_conversation(
                     api_kwargs = agent._get_transport().preflight_kwargs(api_kwargs, allow_stream=False)
 
                 try:
-                    from hermes_cli.plugins import invoke_hook as _invoke_hook
-                    request_messages = api_kwargs.get("messages")
-                    if not isinstance(request_messages, list):
-                        request_messages = api_kwargs.get("input")
-                    if not isinstance(request_messages, list):
-                        request_messages = api_messages
-                    # Shallow-copy the outer list so plugins that retain the
-                    # reference for async snapshotting don't observe later
-                    # mutations of api_messages.  The inner dicts are not
-                    # mutated by the agent loop, so a shallow copy is
-                    # sufficient; a deepcopy would walk every tool result
-                    # and base64 image on every API call.
-                    _invoke_hook(
-                        "pre_api_request",
-                        task_id=effective_task_id,
-                        session_id=agent.session_id or "",
-                        user_message=original_user_message,
-                        conversation_history=list(messages),
-                        platform=agent.platform or "",
-                        model=agent.model,
-                        provider=agent.provider,
-                        base_url=agent.base_url,
-                        api_mode=agent.api_mode,
-                        api_call_count=api_call_count,
-                        request_messages=list(request_messages) if isinstance(request_messages, list) else [],
-                        message_count=len(api_messages),
-                        tool_count=len(agent.tools or []),
-                        approx_input_tokens=approx_tokens,
-                        request_char_count=total_chars,
-                        max_tokens=agent.max_tokens,
+                    from hermes_cli.plugins import (
+                        has_hook,
+                        invoke_hook as _invoke_hook,
                     )
+                    if has_hook("pre_api_request"):
+                        request_messages = api_kwargs.get("messages")
+                        if not isinstance(request_messages, list):
+                            request_messages = api_kwargs.get("input")
+                        if not isinstance(request_messages, list):
+                            request_messages = api_messages
+                        # Shallow-copy the outer list so plugins that retain the
+                        # reference for async snapshotting don't observe later
+                        # mutations of api_messages.  The inner dicts are not
+                        # mutated by the agent loop, so a shallow copy is
+                        # sufficient; a deepcopy would walk every tool result
+                        # and base64 image on every API call.
+                        #
+                        # The ``request_messages`` and ``conversation_history``
+                        # kwargs below are pre-existing raw passthroughs
+                        # consumed by the bundled langfuse plugin
+                        # (``plugins/observability/langfuse/__init__.py:_coerce_request_messages``).
+                        # They predate ``request`` and are intentionally NOT
+                        # sanitised — secrets are not expected here because
+                        # ``api_kwargs`` is the same object passed to the
+                        # provider client.  New consumers should read the
+                        # sanitised view from ``request["body"]["messages"]``.
+                        _request_payload = agent._api_request_payload_for_hook(api_kwargs)
+                        _invoke_hook(
+                            "pre_api_request",
+                            task_id=effective_task_id,
+                            turn_id=turn_id,
+                            api_request_id=api_request_id,
+                            session_id=agent.session_id or "",
+                            user_message=original_user_message,
+                            conversation_history=list(messages),
+                            platform=agent.platform or "",
+                            model=agent.model,
+                            provider=agent.provider,
+                            base_url=agent.base_url,
+                            api_mode=agent.api_mode,
+                            api_call_count=api_call_count,
+                            request_messages=list(request_messages)
+                            if isinstance(request_messages, list)
+                            else [],
+                            message_count=len(api_messages),
+                            tool_count=len(agent.tools or []),
+                            approx_input_tokens=approx_tokens,
+                            request_char_count=total_chars,
+                            max_tokens=agent.max_tokens,
+                            started_at=api_start_time,
+                            request=_request_payload,
+                        )
                 except Exception:
                     pass
 
@@ -1300,12 +1328,14 @@ def run_conversation(
                     if isinstance(getattr(agent, "client", None), Mock):
                         _use_streaming = False
 
-                if _use_streaming:
-                    response = agent._interruptible_streaming_api_call(
-                        api_kwargs, on_first_delta=_stop_spinner
-                    )
-                else:
-                    response = agent._interruptible_api_call(api_kwargs)
+                def _perform_api_call(next_api_kwargs):
+                    if _use_streaming:
+                        return agent._interruptible_streaming_api_call(
+                            next_api_kwargs, on_first_delta=_stop_spinner
+                        )
+                    return agent._interruptible_api_call(next_api_kwargs)
+
+                response = _perform_api_call(api_kwargs)
                 
                 api_duration = time.time() - api_start_time
                 
@@ -1406,6 +1436,21 @@ def run_conversation(
                             error_details.append("response.choices is empty")
 
                 if response_invalid:
+                    agent._invoke_api_request_error_hook(
+                        task_id=effective_task_id,
+                        turn_id=turn_id,
+                        api_request_id=api_request_id,
+                        api_call_count=api_call_count,
+                        api_start_time=api_start_time,
+                        api_kwargs=api_kwargs,
+                        error_type="InvalidAPIResponse",
+                        error_message=", ".join(error_details) or "Invalid API response",
+                        status_code=getattr(getattr(response, "error", None), "code", None),
+                        retry_count=retry_count,
+                        max_retries=max_retries,
+                        retryable=True,
+                        reason="invalid_response",
+                    )
                     # Stop spinner silently — retry status is now buffered
                     # and only surfaced if every retry+fallback exhausts.
                     if thinking_spinner:
@@ -2278,6 +2323,21 @@ def run_conversation(
                     classified.retryable, classified.should_compress,
                     classified.should_rotate_credential, classified.should_fallback,
                 )
+                agent._invoke_api_request_error_hook(
+                    task_id=effective_task_id,
+                    turn_id=turn_id,
+                    api_request_id=api_request_id,
+                    api_call_count=api_call_count,
+                    api_start_time=api_start_time,
+                    api_kwargs=api_kwargs,
+                    error_type=type(api_error).__name__,
+                    error_message=str(api_error),
+                    status_code=status_code,
+                    retry_count=retry_count,
+                    max_retries=max_retries,
+                    retryable=classified.retryable,
+                    reason=classified.reason.value,
+                )
 
                 if (
                     classified.reason == FailoverReason.billing
@@ -2660,6 +2720,61 @@ def run_conversation(
                 # compress history and retry, not abort immediately.
                 status_code = getattr(api_error, "status_code", None)
 
+                # ── Respect disabled auto-compaction on overflow ──────
+                # Ported from anomalyco/opencode#30749.  When the user has
+                # turned auto-compaction off (``compression.enabled: false``),
+                # NO automatic compaction trigger may fire — including the
+                # provider/request-size overflow recovery paths below
+                # (long-context-tier 429, 413 payload-too-large, and
+                # context-overflow).  Without this guard the proactive
+                # threshold path correctly honours the setting (see the
+                # preflight check and the post-response ``should_compress``
+                # gate) but a provider overflow error would still silently
+                # compress + rotate the session, bypassing the user's
+                # explicit choice.  Surface a terminal error instead so the
+                # user can compact manually (``/compress``), start fresh
+                # (``/new``), switch to a larger-context model, or reduce
+                # attachments.  Forced compaction via ``/compress``
+                # (``force=True``) is unaffected — it never reaches this loop.
+                _overflow_reasons = {
+                    FailoverReason.long_context_tier,
+                    FailoverReason.payload_too_large,
+                    FailoverReason.context_overflow,
+                }
+                if (
+                    classified.reason in _overflow_reasons
+                    and not getattr(agent, "compression_enabled", True)
+                ):
+                    agent._flush_status_buffer()
+                    agent._vprint(
+                        f"{agent.log_prefix}❌ Context overflow, but auto-compaction is disabled "
+                        f"(compression.enabled: false).",
+                        force=True,
+                    )
+                    agent._vprint(
+                        f"{agent.log_prefix}   💡 Run /compress to compact manually, /new to start fresh, "
+                        f"switch to a larger-context model, or reduce attachments.",
+                        force=True,
+                    )
+                    logger.error(
+                        f"{agent.log_prefix}Context overflow ({classified.reason.value}) with "
+                        f"auto-compaction disabled — not compressing."
+                    )
+                    agent._persist_session(messages, conversation_history)
+                    return {
+                        "messages": messages,
+                        "completed": False,
+                        "api_calls": api_call_count,
+                        "error": (
+                            "Context overflow and auto-compaction is disabled "
+                            "(compression.enabled: false). Run /compress to compact manually, "
+                            "/new to start fresh, or switch to a larger-context model."
+                        ),
+                        "partial": True,
+                        "failed": True,
+                        "compaction_disabled": True,
+                    }
+
                 # ── Anthropic Sonnet long-context tier gate ───────────
                 # Anthropic returns HTTP 429 "Extra usage is required for
                 # long context requests" when a Claude Max (or similar)
@@ -3195,7 +3310,7 @@ def run_conversation(
                             else:  # nous
                                 agent._vprint(f"{agent.log_prefix}   💡 Nous Portal OAuth token was rejected (HTTP 401). Your token may be", force=True)
                                 agent._vprint(f"{agent.log_prefix}      expired, revoked, or your account may be out of credits. To fix:", force=True)
-                                agent._vprint(f"{agent.log_prefix}      1. Re-authenticate: hermes auth add nous --type oauth", force=True)
+                                agent._vprint(f"{agent.log_prefix}      1. Re-authenticate: hermes portal", force=True)
                                 agent._vprint(f"{agent.log_prefix}      2. Check your portal account: https://portal.nousresearch.com", force=True)
                                 # ``:free`` is OpenRouter slug syntax; Nous Portal will reject
                                 # the model name even after a successful re-auth.
@@ -3378,6 +3493,12 @@ def run_conversation(
                         "completed": False,
                         "failed": True,
                         "error": _final_summary,
+                        # Surface the classified reason so callers (notably the
+                        # kanban worker path in cli.py) can distinguish a
+                        # transient throttle from a real failure and choose a
+                        # different exit code. ``rate_limit`` / ``billing`` here
+                        # mean "quota wall, not a task error".
+                        "failure_reason": classified.reason.value,
                     }
 
                 # For rate limits, respect the Retry-After header if present
@@ -3501,29 +3622,44 @@ def run_conversation(
                     assistant_message.content = str(raw)
 
             try:
-                from hermes_cli.plugins import invoke_hook as _invoke_hook
-                _assistant_tool_calls = getattr(assistant_message, "tool_calls", None) or []
-                _assistant_text = assistant_message.content or ""
-                _invoke_hook(
-                    "post_api_request",
-                    task_id=effective_task_id,
-                    session_id=agent.session_id or "",
-                    platform=agent.platform or "",
-                    model=agent.model,
-                    provider=agent.provider,
-                    base_url=agent.base_url,
-                    api_mode=agent.api_mode,
-                    api_call_count=api_call_count,
-                    api_duration=api_duration,
-                    finish_reason=finish_reason,
-                    message_count=len(api_messages),
-                    response_model=getattr(response, "model", None),
-                    response=response,
-                    usage=agent._usage_summary_for_api_request_hook(response),
-                    assistant_message=assistant_message,
-                    assistant_content_chars=len(_assistant_text),
-                    assistant_tool_call_count=len(_assistant_tool_calls),
+                from hermes_cli.plugins import (
+                    has_hook,
+                    invoke_hook as _invoke_hook,
                 )
+                if has_hook("post_api_request"):
+                    _assistant_tool_calls = (
+                        getattr(assistant_message, "tool_calls", None) or []
+                    )
+                    _assistant_text = assistant_message.content or ""
+                    _api_ended_at = api_start_time + api_duration
+                    _invoke_hook(
+                        "post_api_request",
+                        task_id=effective_task_id,
+                        turn_id=turn_id,
+                        api_request_id=api_request_id,
+                        session_id=agent.session_id or "",
+                        platform=agent.platform or "",
+                        model=agent.model,
+                        provider=agent.provider,
+                        base_url=agent.base_url,
+                        api_mode=agent.api_mode,
+                        api_call_count=api_call_count,
+                        api_duration=api_duration,
+                        started_at=api_start_time,
+                        ended_at=_api_ended_at,
+                        finish_reason=finish_reason,
+                        message_count=len(api_messages),
+                        response_model=getattr(response, "model", None),
+                        response=agent._api_response_payload_for_hook(
+                            response,
+                            assistant_message,
+                            finish_reason=finish_reason,
+                        ),
+                        usage=agent._usage_summary_for_api_request_hook(response),
+                        assistant_message=assistant_message,
+                        assistant_content_chars=len(_assistant_text),
+                        assistant_tool_call_count=len(_assistant_tool_calls),
+                    )
             except Exception:
                 pass
 
@@ -4617,6 +4753,8 @@ def run_conversation(
             _invoke_hook(
                 "post_llm_call",
                 session_id=agent.session_id,
+                task_id=effective_task_id,
+                turn_id=turn_id,
                 user_message=original_user_message,
                 assistant_response=final_response,
                 conversation_history=list(messages),
@@ -4736,6 +4874,8 @@ def run_conversation(
         _invoke_hook(
             "on_session_end",
             session_id=agent.session_id,
+            task_id=effective_task_id,
+            turn_id=turn_id,
             completed=completed,
             interrupted=interrupted,
             model=agent.model,

agent/error_classifier.py

@@ -171,6 +171,9 @@ _IMAGE_TOO_LARGE_PATTERNS = [
     "image too large",      # generic
     "image_too_large",      # error_code variant
     "image size exceeds",   # variant
+    "image dimensions exceed",  # Anthropic: "image dimensions exceed max allowed size: 8000 pixels"
+    "dimensions exceed max allowed size",  # Anthropic dimension-cap (wording variant)
+    "max allowed size: 8000",  # Anthropic dimension-cap (explicit pixel ceiling)
     # "request_too_large" on a request known to contain an image → image is
     # the likely culprit; we still try the shrink path before giving up.
 ]

agent/i18n.py

@@ -32,6 +32,7 @@ from __future__ import annotations
 
 import logging
 import os
+import sysconfig
 import threading
 from functools import lru_cache
 from pathlib import Path
@@ -87,11 +88,54 @@ _catalog_lock = threading.Lock()
 def _locales_dir() -> Path:
     """Return the directory containing locale YAML files.
 
-    Lives next to the repo root so both the bundled install and editable
-    checkouts find it without PYTHONPATH gymnastics.
+    Resolution order, first existing wins:
+
+    1. ``HERMES_BUNDLED_LOCALES`` env var -- set by the Nix wrapper (or any
+       sealed-packaging system) to point at the installed catalog directory.
+    2. ``<repo-root>/locales`` -- source checkouts and ``pip install -e .``,
+       where the working tree sits next to ``agent/``.
+    3. ``<sysconfig data|purelib|platlib>/locales`` -- pip wheel installs.
+       setuptools ``data-files`` extracts ``locales/*.yaml`` under the
+       interpreter's ``data`` scheme; the other schemes are checked as a
+       safety net for nonstandard layouts.
+
+    Falling through to the source-style path (even when missing) keeps
+    ``_load_catalog`` error messages informative -- it logs the path it
+    looked at -- rather than raising.
     """
-    # agent/i18n.py -> agent/ -> repo root
-    return Path(__file__).resolve().parent.parent / "locales"
+    override = os.getenv("HERMES_BUNDLED_LOCALES", "").strip()
+    if override:
+        candidate = Path(override)
+        if candidate.is_dir():
+            return candidate
+        logger.warning(
+            "HERMES_BUNDLED_LOCALES points to a non-directory path (%s); "
+            "falling back to bundled/source locale resolution",
+            override,
+        )
+
+    # agent/i18n.py -> agent/ -> repo root (source checkout, editable install)
+    source_dir = Path(__file__).resolve().parent.parent / "locales"
+    if source_dir.is_dir():
+        return source_dir
+
+    # pip wheel install: data-files lands under the interpreter data scheme.
+    # ``data`` (== sys.prefix in a venv) is where setuptools data-files extract
+    # and is checked first. ``purelib``/``platlib`` (site-packages) are a safety
+    # net for nonstandard layouts. NOTE: this does NOT cover ``pip install
+    # --user`` (user scheme, ~/.local/locales) or ``pip install --target`` --
+    # both are out of scope; see the plan header.
+    for scheme in ("data", "purelib", "platlib"):
+        raw = sysconfig.get_path(scheme)
+        if not raw:
+            continue
+        candidate = Path(raw) / "locales"
+        if candidate.is_dir():
+            return candidate
+
+    # Last resort: return the source-style path so _load_catalog's catalog-missing
+    # log (logger.debug "i18n catalog missing for %s at %s") stays informative.
+    return source_dir
 
 
 def _normalize_lang(value: Any) -> str:

agent/model_metadata.py

@@ -1140,6 +1140,18 @@ def _model_name_suggests_minimax_m3(model: str) -> bool:
     return "minimax-m3" in model.lower()
 
 
+def _model_name_suggests_grok_4_3(model: str) -> bool:
+    """Return True if the model name looks like a Grok 4.3 variant.
+
+    Catches ``grok-4.3``, ``grok-4.3-latest``, and similar slugs.
+    Used as a guard against stale cache entries seeded by pre-catalog builds
+    that resolved grok-4.3 via the generic ``grok-4`` catch-all (256,000)
+    before the ``grok-4.3`` (1M) entry was added to DEFAULT_CONTEXT_LENGTHS
+    on 2026-05-15.
+    """
+    return "grok-4.3" in model.lower()
+
+
 def _query_local_context_length(model: str, base_url: str, api_key: str = "") -> Optional[int]:
     """Query a local server for the model's context length."""
     import httpx
@@ -1564,6 +1576,19 @@ def get_model_context_length(
                     model, base_url, f"{cached:,}",
                 )
                 _invalidate_cached_context_length(model, base_url)
+            # Invalidate stale ≤256,000 cache entries for Grok-4.3.  The
+            # ``grok-4.3`` (1M) entry was added to DEFAULT_CONTEXT_LENGTHS on
+            # 2026-05-15; prior to that, grok-4.3 slugs resolved via the
+            # ``grok-4`` catch-all (256,000) and that value was persisted.
+            # grok-4.3 is 1M, so any sub-262K cached value is a pre-catalog
+            # leftover — drop it and fall through to the hardcoded default.
+            elif cached <= 256_000 and _model_name_suggests_grok_4_3(model):
+                logger.info(
+                    "Dropping stale Grok-4.3 cache entry %s@%s -> %s (pre-catalog value); "
+                    "re-resolving via hardcoded defaults",
+                    model, base_url, f"{cached:,}",
+                )
+                _invalidate_cached_context_length(model, base_url)
             # Nous Portal: the portal /v1/models endpoint is authoritative.
             # Bypass the persistent cache so step 5b can always reconcile
             # against it — this corrects pre-fix entries seeded from the

agent/prompt_builder.py

@@ -22,6 +22,7 @@ from agent.skill_utils import (
     get_disabled_skill_names,
     iter_skill_index_files,
     parse_frontmatter,
+    skill_matches_environment,
     skill_matches_platform,
 )
 from utils import atomic_json_write
@@ -129,9 +130,14 @@ DEFAULT_AGENT_IDENTITY = (
 )
 
 HERMES_AGENT_HELP_GUIDANCE = (
-    "If the user asks about configuring, setting up, or using Hermes Agent "
-    "itself, load the `hermes-agent` skill with skill_view(name='hermes-agent') "
-    "before answering. Docs: https://hermes-agent.nousresearch.com/docs"
+    "You run on Hermes Agent (by Nous Research). When the user needs help with "
+    "Hermes itself — configuring, setting up, using, extending, or troubleshooting "
+    "it — or when you need to understand your own features, tools, or capabilities, "
+    "the documentation at https://hermes-agent.nousresearch.com/docs is your "
+    "authoritative reference and always holds the latest, most up-to-date "
+    "information. Load the `hermes-agent` skill with skill_view(name='hermes-agent') "
+    "for additional guidance and proven workflows, but treat the docs as the source "
+    "of truth when the two differ."
 )
 
 MEMORY_GUIDANCE = (
@@ -1000,6 +1006,13 @@ def _parse_skill_file(skill_file: Path) -> tuple[bool, dict, str]:
         if not skill_matches_platform(frontmatter):
             return False, frontmatter, ""
 
+        # Environment relevance gate (offer-time only): hide skills tagged for
+        # a runtime environment that isn't active (e.g. kanban-only skills for
+        # non-kanban users, s6-only skills outside the container). Explicit
+        # loads (skill_view / --skills) bypass this — see skill_matches_environment.
+        if not skill_matches_environment(frontmatter):
+            return False, frontmatter, ""
+
         return True, frontmatter, extract_skill_description(frontmatter)
     except Exception as e:
         logger.warning("Failed to parse skill file %s: %s", skill_file, e)

agent/skill_commands.py

@@ -270,7 +270,7 @@ def scan_skill_commands() -> Dict[str, Dict[str, Any]]:
     _skill_commands_platform = _resolve_skill_commands_platform()
     _skill_commands = {}
     try:
-        from tools.skills_tool import SKILLS_DIR, _parse_frontmatter, skill_matches_platform, _get_disabled_skill_names
+        from tools.skills_tool import SKILLS_DIR, _parse_frontmatter, skill_matches_platform, skill_matches_environment, _get_disabled_skill_names
         from agent.skill_utils import get_external_skills_dirs, iter_skill_index_files
         disabled = _get_disabled_skill_names()
         seen_names: set = set()
@@ -291,6 +291,10 @@ def scan_skill_commands() -> Dict[str, Dict[str, Any]]:
                     # Skip skills incompatible with the current OS platform
                     if not skill_matches_platform(frontmatter):
                         continue
+                    # Skip skills not relevant to the current runtime env
+                    # (kanban/docker/s6). Offer-time only; explicit load bypasses.
+                    if not skill_matches_environment(frontmatter):
+                        continue
                     name = frontmatter.get('name', skill_md.parent.name)
                     if name in seen_names:
                         continue

agent/skill_utils.py

@@ -169,6 +169,106 @@ def skill_matches_platform(frontmatter: Dict[str, Any]) -> bool:
     return False
 
 
+# ── Environment matching ──────────────────────────────────────────────────
+
+# Recognized environment tags and how each is detected. An environment tag is
+# a *relevance* gate, not a hard-compatibility gate (that is what ``platforms:``
+# is for). A skill tagged for an environment it isn't relevant to is hidden from
+# the skills index / offer surfaces so it does not add noise for users who will
+# never need it — but it can ALWAYS still be loaded explicitly (``skill_view``,
+# ``--skills``), because an explicit request is explicit consent.
+#
+# Detection is cached for the process lifetime via ``_ENV_DETECT_CACHE``.
+_KNOWN_ENVIRONMENTS = frozenset({"kanban", "docker", "s6"})
+
+_ENV_DETECT_CACHE: Dict[str, bool] = {}
+
+
+def _detect_environment(env: str) -> bool:
+    """Return True when the named runtime environment is currently active.
+
+    Cached per process. Unknown env names return True (fail-open: never hide a
+    skill because of a tag we don't understand).
+    """
+    if env in _ENV_DETECT_CACHE:
+        return _ENV_DETECT_CACHE[env]
+
+    result = True
+    if env == "kanban":
+        # Kanban is "active" either as a dispatcher-spawned worker (the
+        # dispatcher sets ``HERMES_KANBAN_TASK`` / ``HERMES_KANBAN_BOARD`` in the
+        # worker env) or as an orchestrator profile that has opted into the
+        # kanban toolset. Mirror the same signals the kanban tools themselves
+        # gate on (``tools/kanban_tools.py``) so the offer filter agrees with
+        # tool availability.
+        if os.getenv("HERMES_KANBAN_TASK") or os.getenv("HERMES_KANBAN_BOARD"):
+            result = True
+        else:
+            try:
+                from tools.kanban_tools import _profile_has_kanban_toolset
+
+                result = bool(_profile_has_kanban_toolset())
+            except Exception:
+                result = False
+    elif env == "docker":
+        try:
+            from hermes_constants import is_container
+
+            result = is_container()
+        except Exception:
+            result = False
+    elif env == "s6":
+        # The Hermes Docker image runs s6-overlay as PID 1 (/init). s6 plants
+        # its runtime scaffolding under /run/s6 and ships its admin tree under
+        # /package/admin/s6-overlay. Either marker means we're inside an
+        # s6-supervised container.
+        result = os.path.isdir("/run/s6") or os.path.isdir(
+            "/package/admin/s6-overlay"
+        )
+
+    _ENV_DETECT_CACHE[env] = result
+    return result
+
+
+def skill_matches_environment(frontmatter: Dict[str, Any]) -> bool:
+    """Return True when the skill is relevant to the current runtime environment.
+
+    Skills may declare an ``environments`` list in their YAML frontmatter::
+
+        environments: [kanban]        # only relevant when kanban is active
+        environments: [s6]            # only relevant inside the s6 Docker image
+        environments: [docker]        # only relevant inside any container
+
+    If the field is absent or empty the skill is relevant in **all**
+    environments (backward-compatible default).
+
+    This is an OFFER-time filter: it controls whether a skill shows up in the
+    skills index / autocomplete / slash-command list. It is intentionally NOT
+    enforced by ``skill_view`` or ``--skills`` preloading — an explicit load is
+    explicit consent, and load-bearing force-loads (e.g. the kanban dispatcher
+    injecting ``--skills kanban-worker``) must always succeed regardless of how
+    the offer surfaces filter the skill.
+
+    A skill matches when ANY of its declared environments is currently active
+    (OR semantics, mirroring ``platforms``). Unknown env tags fail open.
+    """
+    environments = frontmatter.get("environments")
+    if not environments:
+        return True
+    if not isinstance(environments, list):
+        environments = [environments]
+    for env in environments:
+        normalized = str(env).lower().strip()
+        if not normalized:
+            continue
+        if normalized not in _KNOWN_ENVIRONMENTS:
+            # Tag we don't understand — don't hide the skill over it.
+            return True
+        if _detect_environment(normalized):
+            return True
+    return False
+
+
 # ── Disabled skills ───────────────────────────────────────────────────────
 
 

agent/tool_executor.py

@@ -19,7 +19,7 @@ import os
 import random
 import threading
 import time
-from typing import Optional
+from typing import Any, Optional
 
 from agent.display import (
     KawaiiSpinner,
@@ -58,6 +58,76 @@ def _ra():
     return run_agent
 
 
+def _emit_terminal_post_tool_call(
+    agent,
+    *,
+    function_name: str,
+    function_args: dict,
+    result: Any,
+    effective_task_id: str,
+    tool_call_id: str,
+    duration_ms: int = 0,
+    status: str | None = None,
+    error_type: str | None = None,
+    error_message: str | None = None,
+) -> None:
+    try:
+        from model_tools import _emit_post_tool_call_hook
+        _emit_post_tool_call_hook(
+            function_name=function_name,
+            function_args=function_args,
+            result=result,
+            task_id=effective_task_id or "",
+            session_id=getattr(agent, "session_id", "") or "",
+            tool_call_id=tool_call_id or "",
+            turn_id=getattr(agent, "_current_turn_id", "") or "",
+            api_request_id=getattr(agent, "_current_api_request_id", "") or "",
+            duration_ms=duration_ms,
+            status=status,
+            error_type=error_type,
+            error_message=error_message,
+        )
+    except Exception:
+        pass
+
+
+def _cancelled_tool_result(reason: str = "user interrupt") -> str:
+    return json.dumps(
+        {
+            "error": f"Tool execution cancelled by {reason}",
+            "status": "cancelled",
+        },
+        ensure_ascii=False,
+    )
+
+
+def _emit_cancelled_terminal_post_tool_call(
+    agent,
+    *,
+    function_name: str,
+    function_args: dict,
+    effective_task_id: str,
+    tool_call_id: str,
+    start_time: float,
+    reason: str = "user interrupt",
+    error_type: str = "keyboard_interrupt",
+) -> str:
+    result = _cancelled_tool_result(reason)
+    _emit_terminal_post_tool_call(
+        agent,
+        function_name=function_name,
+        function_args=function_args,
+        result=result,
+        effective_task_id=effective_task_id,
+        tool_call_id=tool_call_id,
+        duration_ms=int((time.time() - start_time) * 1000),
+        status="cancelled",
+        error_type=error_type,
+        error_message=f"Tool execution cancelled by {reason}",
+    )
+    return result
+
+
 def _tool_search_scoped_names(agent) -> frozenset:
     """Return the deferrable tool names the session may invoke via tool_call.
 
@@ -188,22 +258,61 @@ def execute_tool_calls_concurrent(agent, assistant_message, messages: list, effe
         if _ts_scope_block is not None:
             # Out-of-scope tool_call: reject before hooks/guardrails/dispatch.
             block_result = _ts_scope_block
+            _emit_terminal_post_tool_call(
+                agent,
+                function_name=function_name,
+                function_args=function_args,
+                result=block_result,
+                effective_task_id=effective_task_id,
+                tool_call_id=getattr(tool_call, "id", "") or "",
+                status="blocked",
+                error_type="tool_scope_block",
+                error_message=_ts_scope_block,
+            )
         else:
             try:
                 from hermes_cli.plugins import get_pre_tool_call_block_message
                 block_message = get_pre_tool_call_block_message(
-                    function_name, function_args, task_id=effective_task_id or "",
+                    function_name,
+                    function_args,
+                    task_id=effective_task_id or "",
+                    session_id=getattr(agent, "session_id", "") or "",
+                    tool_call_id=getattr(tool_call, "id", "") or "",
+                    turn_id=getattr(agent, "_current_turn_id", "") or "",
+                    api_request_id=getattr(agent, "_current_api_request_id", "") or "",
                 )
             except Exception:
                 block_message = None
 
             if block_message is not None:
                 block_result = json.dumps({"error": block_message}, ensure_ascii=False)
+                _emit_terminal_post_tool_call(
+                    agent,
+                    function_name=function_name,
+                    function_args=function_args,
+                    result=block_result,
+                    effective_task_id=effective_task_id,
+                    tool_call_id=getattr(tool_call, "id", "") or "",
+                    status="blocked",
+                    error_type="plugin_block",
+                    error_message=block_message,
+                )
             else:
                 guardrail_decision = agent._tool_guardrails.before_call(function_name, function_args)
                 if not guardrail_decision.allows_execution:
                     block_result = agent._guardrail_block_result(guardrail_decision)
                     blocked_by_guardrail = True
+                    _emit_terminal_post_tool_call(
+                        agent,
+                        function_name=function_name,
+                        function_args=function_args,
+                        result=block_result,
+                        effective_task_id=effective_task_id,
+                        tool_call_id=getattr(tool_call, "id", "") or "",
+                        status="blocked",
+                        error_type="guardrail_block",
+                        error_message=getattr(guardrail_decision, "message", None) or "Tool blocked by guardrail policy",
+                    )
 
         # ── Checkpoint preflight (only for tools that will execute) ──
         if block_result is None:
@@ -315,6 +424,23 @@ def execute_tool_calls_concurrent(agent, assistant_message, messages: list, effe
                     messages=messages,
                     pre_tool_block_checked=True,
                 )
+            except KeyboardInterrupt:
+                try:
+                    agent.interrupt("keyboard interrupt")
+                except Exception:
+                    pass
+                result = _emit_cancelled_terminal_post_tool_call(
+                    agent,
+                    function_name=function_name,
+                    function_args=function_args,
+                    effective_task_id=effective_task_id,
+                    tool_call_id=getattr(tool_call, "id", "") or "",
+                    start_time=start,
+                )
+                duration = time.time() - start
+                logger.info("tool %s cancelled (%.2fs)", function_name, duration)
+                results[index] = (function_name, function_args, result, duration, True, False)
+                return
             except Exception as tool_error:
                 result = f"Error executing tool '{function_name}': {tool_error}"
                 logger.error("_invoke_tool raised for %s: %s", function_name, tool_error, exc_info=True)
@@ -426,8 +552,30 @@ def execute_tool_calls_concurrent(agent, assistant_message, messages: list, effe
             # Tool was cancelled (interrupt) or thread didn't return
             if agent._interrupt_requested:
                 function_result = f"[Tool execution cancelled — {name} was skipped due to user interrupt]"
+                _emit_terminal_post_tool_call(
+                    agent,
+                    function_name=name,
+                    function_args=args,
+                    result=function_result,
+                    effective_task_id=effective_task_id,
+                    tool_call_id=getattr(tc, "id", "") or "",
+                    status="cancelled",
+                    error_type="keyboard_interrupt",
+                    error_message="Tool execution cancelled by user interrupt",
+                )
             else:
                 function_result = f"Error executing tool '{name}': thread did not return a result"
+                _emit_terminal_post_tool_call(
+                    agent,
+                    function_name=name,
+                    function_args=args,
+                    result=function_result,
+                    effective_task_id=effective_task_id,
+                    tool_call_id=getattr(tc, "id", "") or "",
+                    status="error",
+                    error_type="thread_missing_result",
+                    error_message=function_result,
+                )
             tool_duration = 0.0
         else:
             function_name, function_args, function_result, tool_duration, is_error, blocked = r
@@ -592,13 +740,21 @@ def execute_tool_calls_sequential(agent, assistant_message, messages: list, effe
 
         # Check plugin hooks for a block directive before executing.
         _block_msg: Optional[str] = None
+        _block_error_type = "plugin_block"
         if _ts_scope_block is not None:
             _block_msg = _ts_scope_block
+            _block_error_type = "tool_scope_block"
         else:
             try:
                 from hermes_cli.plugins import get_pre_tool_call_block_message
                 _block_msg = get_pre_tool_call_block_message(
-                    function_name, function_args, task_id=effective_task_id or "",
+                    function_name,
+                    function_args,
+                    task_id=effective_task_id or "",
+                    session_id=getattr(agent, "session_id", "") or "",
+                    tool_call_id=getattr(tool_call, "id", "") or "",
+                    turn_id=getattr(agent, "_current_turn_id", "") or "",
+                    api_request_id=getattr(agent, "_current_api_request_id", "") or "",
                 )
             except Exception:
                 pass
@@ -687,11 +843,33 @@ def execute_tool_calls_sequential(agent, assistant_message, messages: list, effe
             # Tool blocked by plugin policy — return error without executing.
             function_result = json.dumps({"error": _block_msg}, ensure_ascii=False)
             tool_duration = 0.0
+            _emit_terminal_post_tool_call(
+                agent,
+                function_name=function_name,
+                function_args=function_args,
+                result=function_result,
+                effective_task_id=effective_task_id,
+                tool_call_id=getattr(tool_call, "id", "") or "",
+                status="blocked",
+                error_type=_block_error_type,
+                error_message=_block_msg,
+            )
         elif _guardrail_block_decision is not None:
             # Tool blocked by tool-loop guardrail — synthesize exactly one
             # tool result for the original tool_call_id without executing.
             function_result = agent._guardrail_block_result(_guardrail_block_decision)
             tool_duration = 0.0
+            _emit_terminal_post_tool_call(
+                agent,
+                function_name=function_name,
+                function_args=function_args,
+                result=function_result,
+                effective_task_id=effective_task_id,
+                tool_call_id=getattr(tool_call, "id", "") or "",
+                status="blocked",
+                error_type="guardrail_block",
+                error_message=getattr(_guardrail_block_decision, "message", None) or "Tool blocked by guardrail policy",
+            )
         elif function_name == "todo":
             from tools.todo_tool import todo_tool as _todo_tool
             function_result = _todo_tool(
@@ -850,12 +1028,29 @@ def execute_tool_calls_sequential(agent, assistant_message, messages: list, effe
                     function_name, function_args, effective_task_id,
                     tool_call_id=tool_call.id,
                     session_id=agent.session_id or "",
+                    turn_id=getattr(agent, "_current_turn_id", "") or "",
+                    api_request_id=getattr(agent, "_current_api_request_id", "") or "",
                     enabled_tools=list(agent.valid_tool_names) if agent.valid_tool_names else None,
                     skip_pre_tool_call_hook=True,
                     enabled_toolsets=getattr(agent, "enabled_toolsets", None),
                     disabled_toolsets=getattr(agent, "disabled_toolsets", None),
                 )
                 _spinner_result = function_result
+            except KeyboardInterrupt:
+                function_result = _emit_cancelled_terminal_post_tool_call(
+                    agent,
+                    function_name=function_name,
+                    function_args=function_args,
+                    effective_task_id=effective_task_id,
+                    tool_call_id=getattr(tool_call, "id", "") or "",
+                    start_time=tool_start_time,
+                )
+                _spinner_result = function_result
+                try:
+                    agent.interrupt("keyboard interrupt")
+                except Exception:
+                    pass
+                raise
             except Exception as tool_error:
                 function_result = f"Error executing tool '{function_name}': {tool_error}"
                 logger.error("handle_function_call raised for %s: %s", function_name, tool_error, exc_info=True)
@@ -872,11 +1067,27 @@ def execute_tool_calls_sequential(agent, assistant_message, messages: list, effe
                     function_name, function_args, effective_task_id,
                     tool_call_id=tool_call.id,
                     session_id=agent.session_id or "",
+                    turn_id=getattr(agent, "_current_turn_id", "") or "",
+                    api_request_id=getattr(agent, "_current_api_request_id", "") or "",
                     enabled_tools=list(agent.valid_tool_names) if agent.valid_tool_names else None,
                     skip_pre_tool_call_hook=True,
                     enabled_toolsets=getattr(agent, "enabled_toolsets", None),
                     disabled_toolsets=getattr(agent, "disabled_toolsets", None),
                 )
+            except KeyboardInterrupt:
+                _emit_cancelled_terminal_post_tool_call(
+                    agent,
+                    function_name=function_name,
+                    function_args=function_args,
+                    effective_task_id=effective_task_id,
+                    tool_call_id=getattr(tool_call, "id", "") or "",
+                    start_time=tool_start_time,
+                )
+                try:
+                    agent.interrupt("keyboard interrupt")
+                except Exception:
+                    pass
+                raise
             except Exception as tool_error:
                 function_result = f"Error executing tool '{function_name}': {tool_error}"
                 logger.error("handle_function_call raised for %s: %s", function_name, tool_error, exc_info=True)
@@ -895,6 +1106,27 @@ def execute_tool_calls_sequential(agent, assistant_message, messages: list, effe
         # Log tool errors to the persistent error log so [error] tags
         # in the UI always have a corresponding detailed entry on disk.
         _is_error_result, _ = _detect_tool_failure(function_name, function_result)
+        # The agent-runtime tools above (todo, session_search, memory,
+        # context-engine, memory-manager, clarify, delegate_task) are
+        # dispatched inline — they never reach handle_function_call, so the
+        # executor is the one that has to fire post_tool_call. For
+        # registry-dispatched tools the else-branch above invoked
+        # handle_function_call, which already fires the hook.
+        from agent.agent_runtime_helpers import agent_runtime_owns_post_tool_hook
+        _executor_must_emit_post_hook = (
+            not _execution_blocked
+            and agent_runtime_owns_post_tool_hook(agent, function_name)
+        )
+        if _executor_must_emit_post_hook:
+            _emit_terminal_post_tool_call(
+                agent,
+                function_name=function_name,
+                function_args=function_args,
+                result=function_result,
+                effective_task_id=effective_task_id,
+                tool_call_id=getattr(tool_call, "id", "") or "",
+                duration_ms=int(tool_duration * 1000),
+            )
         if not _execution_blocked:
             function_result = agent._append_guardrail_observation(
                 function_name,

agent/transports/chat_completions.py

@@ -99,6 +99,22 @@ def _is_gemini_openai_compat_base_url(base_url: Any) -> bool:
     return normalized.endswith("/openai")
 
 
+def _model_consumes_thought_signature(model: Any) -> bool:
+    """True when the outgoing model is a Gemini family model that requires
+    ``extra_content`` (thought_signature) to be replayed on tool calls.
+
+    Gemini 3 thinking models attach ``extra_content`` to each tool call and
+    reject subsequent requests with HTTP 400 if it is missing. Every other
+    strict OpenAI-compatible provider (Fireworks, Mistral, ...) rejects the
+    request with 400 if ``extra_content`` *is* present. So the field must be
+    kept only when the target model is itself Gemini-family, and stripped
+    otherwise — including when a non-Gemini model inherits stale Gemini
+    ``extra_content`` from earlier in a mixed-provider session.
+    """
+    m = str(model or "").lower()
+    return "gemini" in m or "gemma" in m
+
+
 class ChatCompletionsTransport(ProviderTransport):
     """Transport for api_mode='chat_completions'.
 
@@ -119,6 +135,14 @@ class ChatCompletionsTransport(ProviderTransport):
         - Codex Responses API fields: ``codex_reasoning_items`` /
           ``codex_message_items`` on the message, ``call_id`` /
           ``response_item_id`` on ``tool_calls`` entries.
+        - ``extra_content`` on ``tool_calls`` (Gemini thought_signature) —
+          stripped unless the outgoing ``model`` is itself Gemini-family.
+          Gemini 3 thinking models attach it for replay, but strict providers
+          (Fireworks, Mistral) reject any payload containing it with
+          ``Extra inputs are not permitted, field: 'messages[N].tool_calls[M].extra_content'``.
+          It must be kept for Gemini targets (replay required) and dropped for
+          everyone else, including non-Gemini models that inherited stale
+          Gemini ``extra_content`` earlier in a mixed-provider session.
         - ``tool_name`` on tool-result messages — written by
           ``make_tool_result_message()`` for the SQLite FTS index, but not
           part of the Chat Completions schema. Strict providers (Fireworks,
@@ -137,6 +161,9 @@ class ChatCompletionsTransport(ProviderTransport):
           ``Extra inputs are not permitted, field: 'messages[N]._empty_recovery_synthetic'``,
           which then poisons every subsequent request in the session.
         """
+        strip_extra_content = not _model_consumes_thought_signature(
+            kwargs.get("model")
+        )
         needs_sanitize = False
         for msg in messages:
             if not isinstance(msg, dict):
@@ -155,7 +182,9 @@ class ChatCompletionsTransport(ProviderTransport):
             if isinstance(tool_calls, list):
                 for tc in tool_calls:
                     if isinstance(tc, dict) and (
-                        "call_id" in tc or "response_item_id" in tc
+                        "call_id" in tc
+                        or "response_item_id" in tc
+                        or (strip_extra_content and "extra_content" in tc)
                     ):
                         needs_sanitize = True
                         break
@@ -183,6 +212,8 @@ class ChatCompletionsTransport(ProviderTransport):
                     if isinstance(tc, dict):
                         tc.pop("call_id", None)
                         tc.pop("response_item_id", None)
+                        if strip_extra_content:
+                            tc.pop("extra_content", None)
         return sanitized
 
     def convert_tools(self, tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
@@ -240,8 +271,10 @@ class ChatCompletionsTransport(ProviderTransport):
             anthropic_max_output: int | None
             extra_body_additions: dict | None
         """
-        # Codex sanitization: drop reasoning_items / call_id / response_item_id
-        sanitized = self.convert_messages(messages)
+        # Codex sanitization: drop reasoning_items / call_id / response_item_id.
+        # Pass model so the Gemini thought_signature (extra_content) is kept for
+        # Gemini targets and stripped for strict non-Gemini providers.
+        sanitized = self.convert_messages(messages, model=model)
 
         # ── Provider profile: single-path when present ──────────────────
         _profile = params.get("provider_profile")

apps/bootstrap-installer/src-tauri/src/bootstrap.rs

@@ -21,7 +21,7 @@ use serde::{Deserialize, Serialize};
 use tauri::{AppHandle, Emitter, State};
 use tokio::sync::{mpsc, Mutex};
 
-use crate::events::{BootstrapEvent, Manifest, StageState};
+use crate::events::{BootstrapEvent, LogStream, Manifest, StageState};
 use crate::install_script::{self, Pin, ScriptKind, ScriptSource};
 use crate::powershell::{self, StreamSink};
 use crate::AppState;
@@ -179,9 +179,11 @@ pub async fn launch_hermes_desktop(
 
     tracing::info!(?exe_path, "launching Hermes desktop");
 
-    // Detach from us — the installer is about to exit.
-    let mut cmd = tokio::process::Command::new(&exe_path);
-    cmd.current_dir(exe_path.parent().unwrap_or(&install_root));
+    // Detach from us — the installer is about to exit. On macOS launch the
+    // bundle through LaunchServices instead of exec'ing Contents/MacOS/Hermes
+    // directly; this matches user double-click/open behavior and avoids cwd /
+    // quarantine oddities after a self-update rebuild.
+    let mut cmd = desktop_launch_command(&exe_path, &install_root);
     #[cfg(target_os = "windows")]
     {
         use std::os::windows::process::CommandExt;
@@ -232,6 +234,24 @@ pub(crate) fn resolve_hermes_desktop_exe(install_root: &std::path::Path) -> Opti
     None
 }
 
+pub(crate) fn resolve_hermes_desktop_app(install_root: &std::path::Path) -> Option<PathBuf> {
+    let exe = resolve_hermes_desktop_exe(install_root)?;
+    #[cfg(target_os = "macos")]
+    {
+        // .../Hermes.app/Contents/MacOS/Hermes -> .../Hermes.app
+        let app = exe.parent()?.parent()?.parent()?.to_path_buf();
+        if app.extension().and_then(|e| e.to_str()) == Some("app") && app.is_dir() {
+            return Some(app);
+        }
+    }
+    #[cfg(not(target_os = "macos"))]
+    {
+        return Some(exe);
+    }
+    #[allow(unreachable_code)]
+    None
+}
+
 /// True when a prior install completed (bootstrap-complete marker present) AND a
 /// launchable desktop app exists on disk. Used by the installer's launcher fast
 /// path so a bare re-open just opens Hermes instead of re-running setup.
@@ -247,8 +267,7 @@ pub(crate) fn spawn_installed_desktop(install_root: &std::path::Path) -> std::io
     let exe = resolve_hermes_desktop_exe(install_root).ok_or_else(|| {
         std::io::Error::new(std::io::ErrorKind::NotFound, "no built Hermes desktop app")
     })?;
-    let mut cmd = std::process::Command::new(&exe);
-    cmd.current_dir(exe.parent().unwrap_or(install_root));
+    let mut cmd = desktop_launch_command_std(&exe, install_root);
     #[cfg(target_os = "windows")]
     {
         use std::os::windows::process::CommandExt;
@@ -261,6 +280,62 @@ pub(crate) fn spawn_installed_desktop(install_root: &std::path::Path) -> std::io
     cmd.spawn().map(|_child| ())
 }
 
+#[cfg(target_os = "macos")]
+pub(crate) fn open_macos_app_detached(app_bundle: &std::path::Path) -> std::io::Result<()> {
+    let mut cmd = std::process::Command::new("/usr/bin/open");
+    cmd.arg(app_bundle);
+    cmd.current_dir(crate::paths::hermes_home());
+    cmd.spawn().map(|_child| ())
+}
+
+#[cfg(target_os = "macos")]
+fn app_bundle_for_exe(exe: &std::path::Path) -> Option<PathBuf> {
+    let app = exe.parent()?.parent()?.parent()?.to_path_buf();
+    if app.extension().and_then(|e| e.to_str()) == Some("app") && app.is_dir() {
+        Some(app)
+    } else {
+        None
+    }
+}
+
+fn desktop_launch_command(
+    exe_path: &std::path::Path,
+    install_root: &std::path::Path,
+) -> tokio::process::Command {
+    #[cfg(target_os = "macos")]
+    {
+        if let Some(app_bundle) = app_bundle_for_exe(exe_path) {
+            let mut cmd = tokio::process::Command::new("/usr/bin/open");
+            cmd.arg(app_bundle);
+            cmd.current_dir(crate::paths::hermes_home());
+            return cmd;
+        }
+    }
+
+    let mut cmd = tokio::process::Command::new(exe_path);
+    cmd.current_dir(exe_path.parent().unwrap_or(install_root));
+    cmd
+}
+
+fn desktop_launch_command_std(
+    exe_path: &std::path::Path,
+    install_root: &std::path::Path,
+) -> std::process::Command {
+    #[cfg(target_os = "macos")]
+    {
+        if let Some(app_bundle) = app_bundle_for_exe(exe_path) {
+            let mut cmd = std::process::Command::new("/usr/bin/open");
+            cmd.arg(app_bundle);
+            cmd.current_dir(crate::paths::hermes_home());
+            return cmd;
+        }
+    }
+
+    let mut cmd = std::process::Command::new(exe_path);
+    cmd.current_dir(exe_path.parent().unwrap_or(install_root));
+    cmd
+}
+
 // ---------------------------------------------------------------------------
 // Bootstrap implementation
 // ---------------------------------------------------------------------------
@@ -291,6 +366,7 @@ async fn run_bootstrap(
             BootstrapEvent::Log {
                 stage: None,
                 line: line.to_string(),
+                stream: LogStream::Stdout,
             },
         );
         // Bump to info-level so the line shows in bootstrap-installer.log
@@ -625,6 +701,7 @@ async fn run_install_script(
                 BootstrapEvent::Log {
                     stage: stage_for_stdout.clone(),
                     line: line.to_string(),
+                    stream: LogStream::Stdout,
                 },
             );
             // Tee to the rolling installer log so we have a persistent
@@ -643,7 +720,8 @@ async fn run_install_script(
                 &app_for_stderr,
                 BootstrapEvent::Log {
                     stage: stage_for_stderr.clone(),
-                    line: format!("stderr: {line}"),
+                    line: line.to_string(),
+                    stream: LogStream::Stderr,
                 },
             );
             // stderr-level lines get warn! so they're visually distinct
@@ -739,3 +817,90 @@ fn truncate(s: &str, max: usize) -> String {
         format!("{}...", &s[..max])
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+    use std::path::Path;
+
+    fn unique_tmp_dir(tag: &str) -> PathBuf {
+        let base = std::env::temp_dir().join(format!(
+            "hermes-bootstrap-test-{tag}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&base).unwrap();
+        base
+    }
+
+    // Build a fake built-desktop release tree at the platform's expected path
+    // and return (install_root, expected_app_bundle_or_exe).
+    fn make_release_tree(install_root: &Path) -> PathBuf {
+        let release = install_root.join("apps").join("desktop").join("release");
+        if cfg!(target_os = "macos") {
+            let macos_dir = release
+                .join("mac-arm64")
+                .join("Hermes.app")
+                .join("Contents")
+                .join("MacOS");
+            std::fs::create_dir_all(&macos_dir).unwrap();
+            std::fs::write(macos_dir.join("Hermes"), b"#!/bin/sh\n").unwrap();
+            macos_dir.parent().unwrap().parent().unwrap().to_path_buf() // .../Hermes.app
+        } else if cfg!(target_os = "windows") {
+            let dir = release.join("win-unpacked");
+            std::fs::create_dir_all(&dir).unwrap();
+            let exe = dir.join("Hermes.exe");
+            std::fs::write(&exe, b"stub").unwrap();
+            exe
+        } else {
+            let dir = release.join("linux-unpacked");
+            std::fs::create_dir_all(&dir).unwrap();
+            let exe = dir.join("hermes");
+            std::fs::write(&exe, b"stub").unwrap();
+            exe
+        }
+    }
+
+    // The relaunch / install target is derived from the rebuilt desktop app.
+    // On macOS this MUST resolve to the .app bundle (what `open` relaunches and
+    // what the updater ditto's over /Applications/Hermes.app). A regression in
+    // this derivation breaks the post-update auto-relaunch, so guard it.
+    #[test]
+    fn resolve_hermes_desktop_app_finds_built_bundle() {
+        let root = unique_tmp_dir("app-ok");
+        let expected = make_release_tree(&root);
+
+        let resolved = resolve_hermes_desktop_app(&root)
+            .expect("should resolve the freshly-built desktop app");
+
+        #[cfg(target_os = "macos")]
+        {
+            assert_eq!(resolved, expected, "must resolve to the .app bundle");
+            assert_eq!(
+                resolved.extension().and_then(|e| e.to_str()),
+                Some("app"),
+                "relaunch target must be a .app bundle on macOS"
+            );
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            assert_eq!(resolved, expected);
+        }
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn resolve_hermes_desktop_app_is_none_without_a_build() {
+        let root = unique_tmp_dir("app-none");
+        // No release tree created.
+        assert!(
+            resolve_hermes_desktop_app(&root).is_none(),
+            "no resolved app when nothing has been built"
+        );
+        let _ = std::fs::remove_dir_all(&root);
+    }
+}

apps/bootstrap-installer/src-tauri/src/events.rs

@@ -51,6 +51,16 @@ pub enum StageState {
     Failed,
 }
 
+/// Which pipe a raw log line came from. Reported as structured metadata so
+/// the UI can style stderr subtly rather than mislabeling it as an error:
+/// uv/pip/git/npm write normal progress to stderr by design.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum LogStream {
+    Stdout,
+    Stderr,
+}
+
 /// The single event channel `bootstrap` emits these. `type` discriminates.
 #[derive(Debug, Clone, Serialize)]
 #[serde(tag = "type", rename_all = "lowercase")]
@@ -72,11 +82,14 @@ pub enum BootstrapEvent {
         #[serde(skip_serializing_if = "Option::is_none")]
         error: Option<String>,
     },
-    /// Raw stdout/stderr line from install.ps1 (or our wrapper).
+    /// Raw stdout/stderr line from install.ps1 (or our wrapper). `stream`
+    /// tells the UI which pipe it came from so stderr can be styled subtly
+    /// instead of being mislabeled as an error.
     Log {
         #[serde(skip_serializing_if = "Option::is_none")]
         stage: Option<String>,
         line: String,
+        stream: LogStream,
     },
     /// Sent once when all stages complete successfully.
     Complete {

apps/bootstrap-installer/src-tauri/src/powershell.rs

@@ -45,6 +45,14 @@ pub async fn run_script(
 ) -> Result<ScriptResult> {
     let mut cmd = build_command(script_path, args);
 
+    // The installer can be launched from a .app bundle that is later replaced
+    // during self-update. Pin child scripts to a stable directory so bash/zsh
+    // never starts from a deleted cwd and emits getcwd/job-working-directory
+    // errors at the end of an otherwise successful install.
+    if let Some(cwd) = stable_script_cwd(script_path, hermes_home_override) {
+        cmd.current_dir(cwd);
+    }
+
     if let Some(home) = hermes_home_override {
         cmd.env("HERMES_HOME", home);
     }
@@ -146,6 +154,16 @@ pub async fn run_script(
     })
 }
 
+fn stable_script_cwd<'a>(script_path: &'a Path, hermes_home_override: Option<&'a str>) -> Option<&'a Path> {
+    if let Some(home) = hermes_home_override {
+        let path = Path::new(home);
+        if path.is_dir() {
+            return Some(path);
+        }
+    }
+    script_path.parent().filter(|p| p.is_dir())
+}
+
 async fn recv_cancel(rx: &mut Option<CancelRx>) {
     match rx {
         Some(r) => {
@@ -264,4 +282,11 @@ info line
         assert!(parse_stage_result("just banner\n").is_none());
         assert!(parse_manifest("just banner\n").is_none());
     }
+
+    #[test]
+    fn stable_script_cwd_prefers_existing_hermes_home() {
+        let script = Path::new("/tmp/install.sh");
+        let cwd = stable_script_cwd(script, Some("/"));
+        assert_eq!(cwd, Some(Path::new("/")));
+    }
 }

apps/bootstrap-installer/src-tauri/src/update.rs

@@ -19,8 +19,11 @@
 //! the no-window creation flag — both already cfg-gated. Keep new logic
 //! OS-agnostic so the mac/linux port stays "fill in the paths".
 
+use std::env;
+use std::ffi::OsString;
 use std::path::{Path, PathBuf};
 use std::process::Stdio;
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::time::{Duration, Instant};
 
 use anyhow::{anyhow, Result};
@@ -28,7 +31,7 @@ use tauri::{AppHandle, Emitter};
 use tokio::io::{AsyncBufReadExt, BufReader};
 use tokio::process::Command;
 
-use crate::events::{BootstrapEvent, StageInfo, StageState};
+use crate::events::{BootstrapEvent, LogStream, StageInfo, StageState};
 
 /// `hermes update` exit code meaning "another hermes process is holding the
 /// venv shim open / dirty precondition" — see _cmd_update_impl in
@@ -40,10 +43,48 @@ const UPDATE_EXIT_CONCURRENT: i32 = 2;
 const DESKTOP_EXIT_WAIT: Duration = Duration::from_secs(20);
 const DESKTOP_EXIT_POLL: Duration = Duration::from_millis(500);
 
+/// Guards against concurrent update runs. The frontend kicks `startUpdate()`
+/// from a mount effect, which can fire more than once (React strict-mode
+/// double-invokes effects in dev; a window reload or stray re-init can do it
+/// in prod). Two `run_update` tasks racing on `git stash` corrupt the working
+/// tree — one stashes the changes the other then can't find. Exactly one task
+/// may hold this flag at a time.
+static UPDATE_RUNNING: AtomicBool = AtomicBool::new(false);
+
 /// Frontend → Rust: kick off the update flow. Mirrors `start_bootstrap`'s
 /// fire-and-forget shape; progress arrives on the `bootstrap` event channel.
 #[tauri::command]
 pub async fn start_update(app: AppHandle) -> Result<(), String> {
+    // Re-entrancy guard (see UPDATE_RUNNING). compare_exchange lets exactly one
+    // caller flip false→true; any concurrent caller no-ops instead of spawning
+    // a second racing update.
+    if UPDATE_RUNNING
+        .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
+        .is_err()
+    {
+        // Already running: re-emit the manifest so a duplicate startUpdate()
+        // call (which resets the frontend store) can recover its stage list.
+        let target_app = if cfg!(target_os = "macos") {
+            target_app_from_args(std::env::args().skip(1))
+        } else {
+            None
+        };
+        let mut stages = vec![
+            stage_info("update", "Updating Hermes"),
+            stage_info("rebuild", "Rebuilding the desktop app"),
+        ];
+        if cfg!(target_os = "macos") && target_app.is_some() {
+            stages.push(stage_info("install", "Installing the updated app"));
+        }
+        emit(
+            &app,
+            BootstrapEvent::Manifest {
+                stages,
+                protocol_version: None,
+            },
+        );
+        return Ok(());
+    }
     tokio::spawn(async move {
         if let Err(err) = run_update(app.clone()).await {
             // run_update already emits a Failed event on the paths that matter;
@@ -56,6 +97,7 @@ pub async fn start_update(app: AppHandle) -> Result<(), String> {
                 },
             );
         }
+        UPDATE_RUNNING.store(false, Ordering::SeqCst);
     });
     Ok(())
 }
@@ -63,6 +105,14 @@ pub async fn start_update(app: AppHandle) -> Result<(), String> {
 async fn run_update(app: AppHandle) -> Result<()> {
     let hermes_home = crate::paths::hermes_home();
     let install_root = hermes_home.join("hermes-agent");
+    let update_branch = update_branch_from_args(std::env::args().skip(1))
+        .or_else(|| option_env_string("BUILD_PIN_BRANCH"))
+        .unwrap_or_else(|| "main".to_string());
+    let target_app = if cfg!(target_os = "macos") {
+        target_app_from_args(std::env::args().skip(1))
+    } else {
+        None
+    };
 
     let hermes = resolve_hermes(&install_root).ok_or_else(|| {
         let msg = format!(
@@ -81,13 +131,18 @@ async fn run_update(app: AppHandle) -> Result<()> {
     })?;
 
     // Synthetic manifest so the existing progress UI renders our two stages.
+    let mut stages = vec![
+        stage_info("update", "Updating Hermes"),
+        stage_info("rebuild", "Rebuilding the desktop app"),
+    ];
+    if cfg!(target_os = "macos") && target_app.is_some() {
+        stages.push(stage_info("install", "Installing the updated app"));
+    }
+
     emit(
         &app,
         BootstrapEvent::Manifest {
-            stages: vec![
-                stage_info("update", "Updating Hermes"),
-                stage_info("rebuild", "Rebuilding the desktop app"),
-            ],
+            stages,
             protocol_version: None,
         },
     );
@@ -107,12 +162,17 @@ async fn run_update(app: AppHandle) -> Result<()> {
     // reports "already up to date" against the wrong branch. The desktop
     // detected the update against this same branch, so we must update against
     // it too.
-    let pin_branch = option_env_string("BUILD_PIN_BRANCH");
-    let mut update_args: Vec<&str> = vec!["update", "--yes", "--gateway"];
-    if let Some(b) = pin_branch.as_deref() {
-        update_args.push("--branch");
-        update_args.push(b);
-    }
+    emit_log(
+        &app,
+        Some("update"),
+        LogStream::Stdout,
+        &format!("[update] updating against branch {update_branch}"),
+    );
+    let child_env = update_child_env(&install_root);
+    let mut update_args: Vec<String> =
+        vec!["update".into(), "--yes".into(), "--gateway".into()];
+    update_args.push("--branch".into());
+    update_args.push(update_branch);
 
     emit_stage(&app, "update", StageState::Running, None, None);
     let started = Instant::now();
@@ -121,6 +181,7 @@ async fn run_update(app: AppHandle) -> Result<()> {
         &hermes,
         &update_args,
         &install_root,
+        &child_env,
         Some("update"),
     )
     .await?;
@@ -182,11 +243,13 @@ async fn run_update(app: AppHandle) -> Result<()> {
     // repo-root deps with --workspaces=false). This is the rebuild it skips.
     emit_stage(&app, "rebuild", StageState::Running, None, None);
     let started = Instant::now();
+    let rebuild_args: Vec<String> = vec!["desktop".into(), "--build-only".into()];
     let rebuild = run_streamed(
         &app,
         &hermes,
-        &["desktop", "--build-only"],
+        &rebuild_args,
         &install_root,
+        &child_env,
         Some("rebuild"),
     )
     .await?;
@@ -217,6 +280,43 @@ async fn run_update(app: AppHandle) -> Result<()> {
     }
     emit_stage(&app, "rebuild", StageState::Succeeded, Some(rebuild_ms), None);
 
+    let launch_target = if let Some(target_app) = target_app {
+        let started = Instant::now();
+        emit_stage(&app, "install", StageState::Running, None, None);
+        match install_macos_app_update(&app, &install_root, &target_app).await {
+            Ok(installed_app) => {
+                emit_stage(
+                    &app,
+                    "install",
+                    StageState::Succeeded,
+                    Some(started.elapsed().as_millis() as u64),
+                    None,
+                );
+                Some(installed_app)
+            }
+            Err(err) => {
+                let msg = format!("{err:#}");
+                emit_stage(
+                    &app,
+                    "install",
+                    StageState::Failed,
+                    Some(started.elapsed().as_millis() as u64),
+                    Some(msg.clone()),
+                );
+                emit(
+                    &app,
+                    BootstrapEvent::Failed {
+                        stage: Some("install".into()),
+                        error: msg.clone(),
+                    },
+                );
+                return Err(anyhow!(msg));
+            }
+        }
+    } else {
+        None
+    };
+
     // ---- done: signal complete, then launch the fresh desktop ------------
     emit(
         &app,
@@ -226,10 +326,17 @@ async fn run_update(app: AppHandle) -> Result<()> {
         },
     );
 
-    // Reuse the same detached-launch + app.exit(0) used post-install.
-    if let Err(err) =
-        crate::bootstrap::launch_hermes_desktop(app.clone(), install_root.to_string_lossy().into_owned())
-            .await
+    if let Some(target_app) = launch_target {
+        if let Err(err) = launch_macos_app_and_exit(&app, &target_app).await {
+            emit_log(
+                &app,
+                None,
+                LogStream::Stderr,
+                &format!("[update] could not auto-launch desktop: {err}. Launch Hermes manually."),
+            );
+        }
+    } else if let Err(err) =
+        crate::bootstrap::launch_hermes_desktop(app.clone(), install_root.to_string_lossy().into_owned()).await
     {
         // Launch failed: don't hard-fail the update (it succeeded); surface a
         // log line so the success screen can still tell the user to launch
@@ -237,6 +344,7 @@ async fn run_update(app: AppHandle) -> Result<()> {
         emit_log(
             &app,
             None,
+            LogStream::Stdout,
             &format!("[update] could not auto-launch desktop: {err}. Launch Hermes manually."),
         );
     }
@@ -251,7 +359,7 @@ async fn wait_for_venv_free(install_root: &Path, app: &AppHandle) {
     let shim = venv_hermes(install_root);
     let deadline = Instant::now() + DESKTOP_EXIT_WAIT;
 
-    emit_log(app, Some("update"), "[update] waiting for Hermes to exit…");
+    emit_log(app, Some("update"), LogStream::Stdout, "[update] waiting for Hermes to exit…");
 
     loop {
         if !is_locked(&shim) {
@@ -261,6 +369,7 @@ async fn wait_for_venv_free(install_root: &Path, app: &AppHandle) {
             emit_log(
                 app,
                 Some("update"),
+                LogStream::Stdout,
                 "[update] timed out waiting for Hermes to exit; proceeding anyway",
             );
             return;
@@ -289,8 +398,9 @@ fn is_locked(path: &Path) -> bool {
 async fn run_streamed(
     app: &AppHandle,
     program: &Path,
-    args: &[&str],
+    args: &[String],
     cwd: &Path,
+    envs: &[(String, OsString)],
     stage: Option<&str>,
 ) -> Result<CmdResult> {
     let mut cmd = Command::new(program);
@@ -299,6 +409,9 @@ async fn run_streamed(
         .stdin(Stdio::null())
         .stdout(Stdio::piped())
         .stderr(Stdio::piped());
+    for (key, value) in envs {
+        cmd.env(key, value);
+    }
 
     #[cfg(target_os = "windows")]
     {
@@ -320,22 +433,22 @@ async fn run_streamed(
     loop {
         tokio::select! {
             line = out.next_line() => match line {
-                Ok(Some(l)) => emit_log(app, stage_owned.as_deref(), &l),
+                Ok(Some(l)) => emit_log(app, stage_owned.as_deref(), LogStream::Stdout, &l),
                 Ok(None) => break,
                 Err(e) => { tracing::warn!("stdout read error: {e}"); break; }
             },
             line = err.next_line() => match line {
-                Ok(Some(l)) => emit_log(app, stage_owned.as_deref(), &format!("stderr: {l}")),
+                Ok(Some(l)) => emit_log(app, stage_owned.as_deref(), LogStream::Stderr, &l),
                 Ok(None) => {}
                 Err(e) => { tracing::warn!("stderr read error: {e}"); }
             },
         }
     }
     while let Ok(Some(l)) = out.next_line().await {
-        emit_log(app, stage_owned.as_deref(), &l);
+        emit_log(app, stage_owned.as_deref(), LogStream::Stdout, &l);
     }
     while let Ok(Some(l)) = err.next_line().await {
-        emit_log(app, stage_owned.as_deref(), &format!("stderr: {l}"));
+        emit_log(app, stage_owned.as_deref(), LogStream::Stderr, &l);
     }
 
     let status = child.wait().await.map_err(|e| anyhow!("waiting for child: {e}"))?;
@@ -378,6 +491,225 @@ fn resolve_hermes(install_root: &Path) -> Option<PathBuf> {
     None
 }
 
+fn update_child_env(install_root: &Path) -> Vec<(String, OsString)> {
+    let hermes_home = crate::paths::hermes_home();
+    let mut envs = vec![(
+        "HERMES_HOME".to_string(),
+        hermes_home.as_os_str().to_os_string(),
+    )];
+    if let Some(path) = path_with_prepended_entries(&[
+        hermes_home.join("node").join("bin"),
+        venv_bin_dir(install_root),
+    ]) {
+        envs.push(("PATH".to_string(), path));
+    }
+    envs
+}
+
+fn venv_bin_dir(install_root: &Path) -> PathBuf {
+    if cfg!(target_os = "windows") {
+        install_root.join("venv").join("Scripts")
+    } else {
+        install_root.join("venv").join("bin")
+    }
+}
+
+fn path_with_prepended_entries(entries: &[PathBuf]) -> Option<OsString> {
+    let mut parts: Vec<PathBuf> = entries.to_vec();
+    if let Some(existing) = env::var_os("PATH") {
+        parts.extend(env::split_paths(&existing));
+    }
+    env::join_paths(parts).ok()
+}
+
+fn update_branch_from_args<I, S>(args: I) -> Option<String>
+where
+    I: IntoIterator<Item = S>,
+    S: AsRef<str>,
+{
+    arg_value_from_args(args, "--branch")
+        .map(|s| s.trim().to_string())
+        .filter(|s| !s.is_empty())
+}
+
+fn target_app_from_args<I, S>(args: I) -> Option<PathBuf>
+where
+    I: IntoIterator<Item = S>,
+    S: AsRef<str>,
+{
+    arg_value_from_args(args, "--target-app")
+        .map(PathBuf::from)
+        .filter(|p| p.extension().and_then(|e| e.to_str()) == Some("app"))
+}
+
+fn arg_value_from_args<I, S>(args: I, name: &str) -> Option<String>
+where
+    I: IntoIterator<Item = S>,
+    S: AsRef<str>,
+{
+    let mut iter = args.into_iter().map(|s| s.as_ref().to_string()).peekable();
+    while let Some(arg) = iter.next() {
+        if arg == name {
+            return iter.next();
+        }
+        if let Some(value) = arg.strip_prefix(&format!("{name}=")) {
+            return Some(value.to_string());
+        }
+    }
+    None
+}
+
+#[cfg(target_os = "macos")]
+async fn install_macos_app_update(
+    app: &AppHandle,
+    install_root: &Path,
+    target_app: &Path,
+) -> Result<PathBuf> {
+    if target_app.extension().and_then(|e| e.to_str()) != Some("app") {
+        return Err(anyhow!(
+            "refusing to install update into non-app path: {}",
+            target_app.display()
+        ));
+    }
+
+    let rebuilt_app = crate::bootstrap::resolve_hermes_desktop_app(install_root).ok_or_else(|| {
+        anyhow!(
+            "desktop rebuild succeeded but no Hermes.app was found under {}",
+            install_root.join("apps").join("desktop").join("release").display()
+        )
+    })?;
+
+    let same = match (rebuilt_app.canonicalize(), target_app.canonicalize()) {
+        (Ok(a), Ok(b)) => a == b,
+        _ => rebuilt_app == target_app,
+    };
+    if same {
+        emit_log(
+            app,
+            Some("install"),
+            LogStream::Stdout,
+            &format!(
+                "[update] rebuilt app is already the launch target: {}",
+                target_app.display()
+            ),
+        );
+        return Ok(target_app.to_path_buf());
+    }
+
+    emit_log(
+        app,
+        Some("install"),
+        LogStream::Stdout,
+        &format!(
+            "[update] installing rebuilt app {} -> {}",
+            rebuilt_app.display(),
+            target_app.display()
+        ),
+    );
+
+    if let Some(parent) = target_app.parent() {
+        tokio::fs::create_dir_all(parent).await?;
+    }
+    let tmp = PathBuf::from(format!("{}.hermes-update-new", target_app.display()));
+    let old = PathBuf::from(format!("{}.hermes-update-old", target_app.display()));
+    remove_dir_if_exists(&tmp).await;
+    remove_dir_if_exists(&old).await;
+
+    let ditto = Command::new("/usr/bin/ditto")
+        .arg(&rebuilt_app)
+        .arg(&tmp)
+        .current_dir(crate::paths::hermes_home())
+        .status()
+        .await
+        .map_err(|e| anyhow!("running ditto: {e}"))?;
+    if !ditto.success() {
+        return Err(anyhow!(
+            "ditto failed while copying updated app into {}",
+            tmp.display()
+        ));
+    }
+
+    // Atomic-as-possible swap with rollback. Extracted so the invariant
+    // (target is never left deleted-with-no-replacement) can be unit-tested
+    // without ditto / a real .app bundle.
+    swap_in_new_bundle(&tmp, target_app, &old).await?;
+
+    let _ = Command::new("/usr/bin/xattr")
+        .arg("-dr")
+        .arg("com.apple.quarantine")
+        .arg(target_app)
+        .current_dir(crate::paths::hermes_home())
+        .status()
+        .await;
+
+    Ok(target_app.to_path_buf())
+}
+
+/// Move a freshly-staged bundle (`tmp`) into place at `target`, parking any
+/// existing bundle at `old` so the move can succeed (macOS `rename` won't
+/// overwrite a non-empty directory).
+///
+/// Invariant: on ANY failure path, `target` is left pointing at a working
+/// bundle — either the original (rolled back from `old`) or untouched — and we
+/// never delete the running app with no replacement in place. The staged `tmp`
+/// copy is cleaned up on failure.
+async fn swap_in_new_bundle(tmp: &Path, target: &Path, old: &Path) -> Result<()> {
+    let moved_old = if target.exists() {
+        if let Err(err) = tokio::fs::rename(target, old).await {
+            // Could not move the existing app aside. Leave it untouched and
+            // bail — a failed update must not brick the install.
+            remove_dir_if_exists(tmp).await;
+            return Err(anyhow!(
+                "could not move existing app aside at {} (leaving it in place): {err}",
+                target.display()
+            ));
+        }
+        true
+    } else {
+        false
+    };
+    if let Err(err) = tokio::fs::rename(tmp, target).await {
+        // Restore the original app from the backup so the user keeps a working
+        // install, and clean up the staged copy.
+        if moved_old {
+            let _ = tokio::fs::rename(old, target).await;
+        }
+        remove_dir_if_exists(tmp).await;
+        return Err(anyhow!("installing updated app at {}: {err}", target.display()));
+    }
+    remove_dir_if_exists(old).await;
+    Ok(())
+}
+
+#[cfg(not(target_os = "macos"))]
+async fn install_macos_app_update(
+    _app: &AppHandle,
+    _install_root: &Path,
+    target_app: &Path,
+) -> Result<PathBuf> {
+    Ok(target_app.to_path_buf())
+}
+
+async fn remove_dir_if_exists(path: &Path) {
+    if path.exists() {
+        let _ = tokio::fs::remove_dir_all(path).await;
+    }
+}
+
+#[cfg(target_os = "macos")]
+async fn launch_macos_app_and_exit(app: &AppHandle, target_app: &Path) -> Result<()> {
+    crate::bootstrap::open_macos_app_detached(target_app)
+        .map_err(|e| anyhow!("launching {}: {e}", target_app.display()))?;
+    tokio::time::sleep(std::time::Duration::from_millis(150)).await;
+    app.exit(0);
+    Ok(())
+}
+
+#[cfg(not(target_os = "macos"))]
+async fn launch_macos_app_and_exit(_app: &AppHandle, _target_app: &Path) -> Result<()> {
+    Ok(())
+}
+
 // ---------------------------------------------------------------------------
 // Event helpers — keep emit shape identical to bootstrap.rs so the UI is reused
 // ---------------------------------------------------------------------------
@@ -429,7 +761,7 @@ fn emit_stage(
     );
 }
 
-fn emit_log(app: &AppHandle, stage: Option<&str>, line: &str) {
+fn emit_log(app: &AppHandle, stage: Option<&str>, stream: LogStream, line: &str) {
     match stage {
         Some(s) => tracing::info!(target: "bootstrap.log", stage = %s, "{line}"),
         None => tracing::info!(target: "bootstrap.log", "{line}"),
@@ -439,6 +771,7 @@ fn emit_log(app: &AppHandle, stage: Option<&str>, line: &str) {
         BootstrapEvent::Log {
             stage: stage.map(|s| s.to_string()),
             line: line.to_string(),
+            stream,
         },
     );
 }
@@ -459,4 +792,118 @@ mod tests {
     fn missing_file_is_not_locked() {
         assert!(!is_locked(Path::new("/nonexistent/does/not/exist/xyz")));
     }
+
+    #[test]
+    fn parses_update_branch_from_space_or_equals_args() {
+        assert_eq!(
+            update_branch_from_args(["--update", "--branch", "bb/test"]),
+            Some("bb/test".to_string())
+        );
+        assert_eq!(
+            update_branch_from_args(["--update", "--branch=main"]),
+            Some("main".to_string())
+        );
+        assert_eq!(update_branch_from_args(["--update"]), None);
+    }
+
+    #[test]
+    fn parses_only_app_targets() {
+        assert_eq!(
+            target_app_from_args(["--update", "--target-app", "/Applications/Hermes.app"]),
+            Some(PathBuf::from("/Applications/Hermes.app"))
+        );
+        assert_eq!(target_app_from_args(["--target-app", "/tmp/not-an-app"]), None);
+    }
+
+    // Helpers for the swap tests: make a throwaway dir tree we can rename.
+    fn unique_tmp_dir(tag: &str) -> PathBuf {
+        let base = std::env::temp_dir().join(format!(
+            "hermes-swap-test-{tag}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&base).unwrap();
+        base
+    }
+
+    fn write_marker(dir: &Path, contents: &str) {
+        std::fs::create_dir_all(dir).unwrap();
+        std::fs::write(dir.join("marker.txt"), contents).unwrap();
+    }
+
+    #[tokio::test]
+    async fn swap_installs_new_bundle_and_cleans_up() {
+        let base = unique_tmp_dir("ok");
+        let target = base.join("Hermes.app");
+        let tmp = base.join("Hermes.app.hermes-update-new");
+        let old = base.join("Hermes.app.hermes-update-old");
+        write_marker(&target, "OLD");
+        write_marker(&tmp, "NEW");
+
+        swap_in_new_bundle(&tmp, &target, &old).await.unwrap();
+
+        // New bundle is now at target; staging + backup dirs are gone.
+        assert_eq!(
+            std::fs::read_to_string(target.join("marker.txt")).unwrap(),
+            "NEW"
+        );
+        assert!(!tmp.exists(), "staged copy should be cleaned up");
+        assert!(!old.exists(), "backup should be cleaned up on success");
+        let _ = std::fs::remove_dir_all(&base);
+    }
+
+    #[tokio::test]
+    async fn swap_failure_never_leaves_target_missing() {
+        // Regression guard for the catastrophic path: the move-aside of the
+        // existing app fails AND the staged bundle can't be installed. The
+        // buggy version deleted `target` when move-aside failed and then
+        // skipped rollback, bricking the install. The fixed version must leave
+        // the original app intact on disk.
+        //
+        // Trigger both failures deterministically:
+        //  - `old` is a NON-EMPTY dir  -> rename(target, old) fails
+        //  - `tmp` does not exist       -> rename(tmp, target) fails
+        let base = unique_tmp_dir("fail");
+        let target = base.join("Hermes.app");
+        let tmp = base.join("Hermes.app.hermes-update-new"); // intentionally absent
+        let old = base.join("Hermes.app.hermes-update-old");
+        write_marker(&target, "OLD");
+        write_marker(&old, "OCCUPIED"); // non-empty => rename(target,old) fails
+
+        let result = swap_in_new_bundle(&tmp, &target, &old).await;
+
+        assert!(result.is_err(), "swap should fail when neither move can complete");
+        assert!(target.exists(), "original app must NOT be deleted on failure");
+        assert_eq!(
+            std::fs::read_to_string(target.join("marker.txt")).unwrap(),
+            "OLD",
+            "original app contents must be intact after a failed swap"
+        );
+        let _ = std::fs::remove_dir_all(&base);
+    }
+
+    #[tokio::test]
+    async fn swap_rolls_back_when_install_step_fails() {
+        // Move-aside succeeds but installing the staged bundle fails (tmp
+        // absent). The original must be rolled back from `old` to `target`.
+        let base = unique_tmp_dir("rollback");
+        let target = base.join("Hermes.app");
+        let tmp = base.join("Hermes.app.hermes-update-new"); // absent
+        let old = base.join("Hermes.app.hermes-update-old");
+        write_marker(&target, "OLD");
+
+        let result = swap_in_new_bundle(&tmp, &target, &old).await;
+
+        assert!(result.is_err());
+        assert!(target.exists(), "original must be restored after failed install");
+        assert_eq!(
+            std::fs::read_to_string(target.join("marker.txt")).unwrap(),
+            "OLD"
+        );
+        assert!(!old.exists(), "backup should be rolled back, not left behind");
+        let _ = std::fs::remove_dir_all(&base);
+    }
 }

apps/bootstrap-installer/src/routes/failure.tsx

@@ -3,8 +3,10 @@ import { useStore } from '@nanostores/react'
 import { Button } from '../components/button'
 import {
   $logPath,
+  $mode,
   openLogDir,
   startInstall,
+  startUpdate,
   type BootstrapStateModel
 } from '../store'
 import { RefreshCw, FileText } from 'lucide-react'
@@ -22,6 +24,8 @@ interface FailureProps {
  */
 export default function Failure({ bootstrap }: FailureProps) {
   const logPath = useStore($logPath)
+  const mode = useStore($mode)
+  const isUpdate = mode === 'update'
 
   return (
     <div className="hermes-fade-in flex h-full flex-col items-center justify-center gap-6 px-12 py-10">
@@ -37,24 +41,27 @@ export default function Failure({ bootstrap }: FailureProps) {
           }
         >
           <span>
-            <span>Install didn&rsquo;t finish</span>
+            <span>{isUpdate ? 'Update didn\u2019t finish' : 'Install didn\u2019t finish'}</span>
           </span>
-          <span aria-hidden="true">Install didn&rsquo;t finish</span>
+          <span aria-hidden="true">{isUpdate ? 'Update didn\u2019t finish' : 'Install didn\u2019t finish'}</span>
         </p>
 
         <p className="m-0 mx-auto max-w-xl text-center text-sm leading-normal tracking-tight text-muted-foreground">
-          {bootstrap.error ?? 'Something went wrong during installation.'}
+          {bootstrap.error ??
+            (isUpdate
+              ? 'Something went wrong during the update.'
+              : 'Something went wrong during installation.')}
         </p>
       </div>
 
       <div className="flex items-center gap-3">
         <Button
-          onClick={() => void startInstall()}
+          onClick={() => void (isUpdate ? startUpdate() : startInstall())}
           size="lg"
           className="inline-flex items-center gap-2 px-6"
         >
           <RefreshCw size={16} />
-          Retry install
+          {isUpdate ? 'Retry update' : 'Retry install'}
         </Button>
         <Button
           variant="outline"

apps/bootstrap-installer/src/routes/progress.tsx

@@ -115,9 +115,7 @@ export default function ProgressScreen({ bootstrap }: ProgressProps) {
                   key={idx}
                   className={clsx(
                     'whitespace-pre-wrap',
-                    entry.line.startsWith('stderr:')
-                      ? 'text-destructive'
-                      : 'text-foreground/70'
+                    entry.stream === 'stderr' ? 'text-foreground/45' : 'text-foreground/70'
                   )}
                 >
                   {entry.line}

apps/bootstrap-installer/src/store.ts

@@ -42,7 +42,7 @@ export interface BootstrapStateModel {
   currentStage: string | null
   installRoot: string | null
   error: string | null
-  logs: Array<{ stage?: string; line: string }>
+  logs: Array<{ stage?: string; line: string; stream?: 'stdout' | 'stderr' }>
 }
 
 const INITIAL: BootstrapStateModel = {
@@ -106,6 +106,7 @@ interface BootstrapLogEvent {
   type: 'log'
   stage?: string
   line: string
+  stream?: 'stdout' | 'stderr'
 }
 
 interface BootstrapCompleteEvent {
@@ -192,7 +193,7 @@ export async function initialize(): Promise<void> {
         break
       }
       case 'log': {
-        const logs = [...cur.logs, { stage: payload.stage, line: payload.line }]
+        const logs = [...cur.logs, { stage: payload.stage, line: payload.line, stream: payload.stream }]
         // Keep the rolling buffer bounded so the UI doesn't get OOM'd
         // during a long install (playwright chromium download is ~10k lines).
         const trimmed = logs.length > 2000 ? logs.slice(-2000) : logs

apps/desktop/README.md

@@ -94,7 +94,7 @@ Installers are built and uploaded to GitHub Releases manually. macOS/Windows sig
 
 ### How it works
 
-The packaged app ships only the Electron shell. On first launch it installs the Hermes Agent runtime into `HERMES_HOME` (`~/.hermes`, or `%LOCALAPPDATA%\hermes` on Windows) — the **same layout a CLI install uses**, so the two are interchangeable. The renderer (React, in `src/`) talks to a `hermes dashboard --tui` backend over the standard gateway APIs and reuses the embedded TUI rather than reimplementing chat. The install, backend-resolution, and self-update logic all live in `electron/main.cjs`.
+The packaged app ships only the Electron shell. On first launch it installs the Hermes Agent runtime into `HERMES_HOME` (`~/.hermes`, or `%LOCALAPPDATA%\hermes` on Windows) — the **same layout a CLI install uses**, so the two are interchangeable. The renderer (React, in `src/`) talks to a `hermes dashboard` backend over the standard gateway APIs and reuses the embedded TUI rather than reimplementing chat. The install, backend-resolution, and self-update logic all live in `electron/main.cjs`.
 
 ### Verification
 

apps/desktop/electron/backend-probes.test.cjs

@@ -67,7 +67,9 @@ test('verifyHermesCli returns true when --version exits 0', () => {
   } finally {
     try {
       fs.unlinkSync(scriptPath)
-    } catch {}
+    } catch {
+      void 0
+    }
   }
 })
 

apps/desktop/electron/bootstrap-platform.cjs

@@ -52,7 +52,9 @@ function detectRemoteDisplay(options = {}) {
   const env = options.env ?? process.env
   const platform = options.platform ?? process.platform
 
-  const override = String(env.HERMES_DESKTOP_DISABLE_GPU || '').trim().toLowerCase()
+  const override = String(env.HERMES_DESKTOP_DISABLE_GPU || '')
+    .trim()
+    .toLowerCase()
   if (GPU_OVERRIDE_ON.has(override)) return 'override (HERMES_DESKTOP_DISABLE_GPU)'
   if (GPU_OVERRIDE_OFF.has(override)) return null
 

apps/desktop/electron/bootstrap-platform.test.cjs

@@ -45,11 +45,17 @@ test('detectRemoteDisplay does not treat WSLg as remote', () => {
   // WSLg renders locally via vGPU and doesn't show the flicker, so a WSL
   // session with a local DISPLAY keeps hardware acceleration on.
   assert.equal(detectRemoteDisplay({ env: { WSL_DISTRO_NAME: 'Ubuntu', DISPLAY: ':0' }, platform: 'linux' }), null)
-  assert.equal(detectRemoteDisplay({ env: { WSL_INTEROP: '/run/WSL/1_interop', DISPLAY: ':0' }, platform: 'linux' }), null)
+  assert.equal(
+    detectRemoteDisplay({ env: { WSL_INTEROP: '/run/WSL/1_interop', DISPLAY: ':0' }, platform: 'linux' }),
+    null
+  )
 })
 
 test('detectRemoteDisplay flags SSH sessions on any platform', () => {
-  assert.equal(detectRemoteDisplay({ env: { SSH_CONNECTION: '1.2.3.4 5 6.7.8.9 22' }, platform: 'linux' }), 'ssh-session')
+  assert.equal(
+    detectRemoteDisplay({ env: { SSH_CONNECTION: '1.2.3.4 5 6.7.8.9 22' }, platform: 'linux' }),
+    'ssh-session'
+  )
   assert.equal(detectRemoteDisplay({ env: { SSH_CLIENT: '1.2.3.4 5 22' }, platform: 'darwin' }), 'ssh-session')
   assert.equal(detectRemoteDisplay({ env: { SSH_TTY: '/dev/pts/0' }, platform: 'win32' }), 'ssh-session')
 })

apps/desktop/electron/bootstrap-runner.cjs

@@ -22,7 +22,7 @@
  *   { type: 'manifest',  stages: [{name, title, category, needs_user_input}, ...] }
  *   { type: 'stage',     name, state: 'running'|'succeeded'|'skipped'|'failed',
  *                        json?, durationMs?, error? }
- *   { type: 'log',       stage?, line }      // raw line from install.ps1
+ *   { type: 'log',       stage?, line, stream: 'stdout'|'stderr' } // raw line from install.ps1
  *   { type: 'complete',  marker: <written marker payload> }
  *   { type: 'failed',    stage?, error }     // bootstrap aborted
  *
@@ -101,7 +101,9 @@ function downloadInstallScript(commit, destPath) {
             .get(res.headers.location, res2 => {
               if (res2.statusCode !== 200) {
                 reject(
-                  new Error(`Failed to download ${scriptName}: HTTP ${res2.statusCode} from redirect ${res.headers.location}`)
+                  new Error(
+                    `Failed to download ${scriptName}: HTTP ${res2.statusCode} from redirect ${res.headers.location}`
+                  )
                 )
                 return
               }
@@ -121,7 +123,9 @@ function downloadInstallScript(commit, destPath) {
           out.close()
           try {
             fs.unlinkSync(tmpPath)
-          } catch {}
+          } catch {
+            void 0
+          }
           reject(new Error(`Failed to download ${scriptName}: HTTP ${res.statusCode} from ${url}`))
           return
         }
@@ -134,14 +138,18 @@ function downloadInstallScript(commit, destPath) {
         out.on('error', err => {
           try {
             fs.unlinkSync(tmpPath)
-          } catch {}
+          } catch {
+            void 0
+          }
           reject(err)
         })
       })
       .on('error', err => {
         try {
           fs.unlinkSync(tmpPath)
-        } catch {}
+        } catch {
+          void 0
+        }
         reject(err)
       })
   })
@@ -168,13 +176,19 @@ async function resolveInstallScript({ installStamp, sourceRepoRoot, hermesHome,
   const cached = cachedScriptPath(hermesHome, installStamp.commit)
   try {
     await fsp.access(cached, fs.constants.R_OK)
-    emit({ type: 'log', line: `[bootstrap] using cached ${installScriptName()} for ${installStamp.commit.slice(0, 12)}` })
+    emit({
+      type: 'log',
+      line: `[bootstrap] using cached ${installScriptName()} for ${installStamp.commit.slice(0, 12)}`
+    })
     return { path: cached, source: 'cache', commit: installStamp.commit, kind: installScriptKind() }
   } catch {
     // not cached; download
   }
 
-  emit({ type: 'log', line: `[bootstrap] fetching ${installScriptName()} for ${installStamp.commit.slice(0, 12)} from GitHub` })
+  emit({
+    type: 'log',
+    line: `[bootstrap] fetching ${installScriptName()} for ${installStamp.commit.slice(0, 12)} from GitHub`
+  })
   await downloadInstallScript(installStamp.commit, cached)
   emit({ type: 'log', line: `[bootstrap] saved to ${cached}` })
   return { path: cached, source: 'download', commit: installStamp.commit, kind: installScriptKind() }
@@ -207,7 +221,9 @@ function spawnPowerShell(scriptPath, args, { emit, stageName, abortSignal, herme
       killed = true
       try {
         child.kill('SIGTERM')
-      } catch {}
+      } catch {
+        void 0
+      }
     }
     if (abortSignal) {
       if (abortSignal.aborted) {
@@ -229,7 +245,7 @@ function spawnPowerShell(scriptPath, args, { emit, stageName, abortSignal, herme
       while ((nl = stdoutBuf.indexOf('\n')) !== -1) {
         const line = stdoutBuf.slice(0, nl).replace(/\r$/, '')
         stdoutBuf = stdoutBuf.slice(nl + 1)
-        if (line) emit && emit({ type: 'log', stage: stageName, line })
+        if (line) emit && emit({ type: 'log', stage: stageName, line, stream: 'stdout' })
       }
     })
 
@@ -241,7 +257,7 @@ function spawnPowerShell(scriptPath, args, { emit, stageName, abortSignal, herme
       while ((nl = stderrBuf.indexOf('\n')) !== -1) {
         const line = stderrBuf.slice(0, nl).replace(/\r$/, '')
         stderrBuf = stderrBuf.slice(nl + 1)
-        if (line) emit && emit({ type: 'log', stage: stageName, line: `stderr: ${line}` })
+        if (line) emit && emit({ type: 'log', stage: stageName, line, stream: 'stderr' })
       }
     })
 
@@ -253,8 +269,8 @@ function spawnPowerShell(scriptPath, args, { emit, stageName, abortSignal, herme
     child.on('close', (code, signal) => {
       if (abortSignal) abortSignal.removeEventListener('abort', onAbort)
       // Flush any trailing bytes
-      if (stdoutBuf) emit && emit({ type: 'log', stage: stageName, line: stdoutBuf })
-      if (stderrBuf) emit && emit({ type: 'log', stage: stageName, line: `stderr: ${stderrBuf}` })
+      if (stdoutBuf) emit && emit({ type: 'log', stage: stageName, line: stdoutBuf, stream: 'stdout' })
+      if (stderrBuf) emit && emit({ type: 'log', stage: stageName, line: stderrBuf, stream: 'stderr' })
       resolve({ stdout, stderr, code, signal, killed })
     })
   })
@@ -278,7 +294,9 @@ function spawnBash(scriptPath, args, { emit, stageName, abortSignal, hermesHome
       killed = true
       try {
         child.kill('SIGTERM')
-      } catch {}
+      } catch {
+        void 0
+      }
     }
     if (abortSignal) {
       if (abortSignal.aborted) {
@@ -299,7 +317,7 @@ function spawnBash(scriptPath, args, { emit, stageName, abortSignal, hermesHome
       while ((nl = stdoutBuf.indexOf('\n')) !== -1) {
         const line = stdoutBuf.slice(0, nl).replace(/\r$/, '')
         stdoutBuf = stdoutBuf.slice(nl + 1)
-        if (line) emit && emit({ type: 'log', stage: stageName, line })
+        if (line) emit && emit({ type: 'log', stage: stageName, line, stream: 'stdout' })
       }
     })
 
@@ -311,7 +329,7 @@ function spawnBash(scriptPath, args, { emit, stageName, abortSignal, hermesHome
       while ((nl = stderrBuf.indexOf('\n')) !== -1) {
         const line = stderrBuf.slice(0, nl).replace(/\r$/, '')
         stderrBuf = stderrBuf.slice(nl + 1)
-        if (line) emit && emit({ type: 'log', stage: stageName, line: `stderr: ${line}` })
+        if (line) emit && emit({ type: 'log', stage: stageName, line, stream: 'stderr' })
       }
     })
 
@@ -322,8 +340,8 @@ function spawnBash(scriptPath, args, { emit, stageName, abortSignal, hermesHome
 
     child.on('close', (code, signal) => {
       if (abortSignal) abortSignal.removeEventListener('abort', onAbort)
-      if (stdoutBuf) emit && emit({ type: 'log', stage: stageName, line: stdoutBuf })
-      if (stderrBuf) emit && emit({ type: 'log', stage: stageName, line: `stderr: ${stderrBuf}` })
+      if (stdoutBuf) emit && emit({ type: 'log', stage: stageName, line: stdoutBuf, stream: 'stdout' })
+      if (stderrBuf) emit && emit({ type: 'log', stage: stageName, line: stderrBuf, stream: 'stderr' })
       resolve({ stdout, stderr, code, signal, killed })
     })
   })
@@ -369,7 +387,9 @@ async function fetchManifest({ scriptPath, installerKind, emit, hermesHome, acti
     hermesHome
   })
   if (result.code !== 0) {
-    throw new Error(`${isPosix ? 'install.sh --manifest' : 'install.ps1 -Manifest'} failed: exit ${result.code}\n${result.stderr || result.stdout}`)
+    throw new Error(
+      `${isPosix ? 'install.sh --manifest' : 'install.ps1 -Manifest'} failed: exit ${result.code}\n${result.stderr || result.stdout}`
+    )
   }
   // The manifest is the LAST JSON line on stdout (install.ps1 may print
   // banner / info lines first depending on Console.OutputEncoding effects).
@@ -381,9 +401,13 @@ async function fetchManifest({ scriptPath, installerKind, emit, hermesHome, acti
       if (parsed && Array.isArray(parsed.stages)) {
         return parsed
       }
-    } catch {}
+    } catch {
+      void 0
+    }
   }
-  throw new Error(`${isPosix ? 'install.sh --manifest' : 'install.ps1 -Manifest'} produced no parseable JSON payload\n${result.stdout}`)
+  throw new Error(
+    `${isPosix ? 'install.sh --manifest' : 'install.ps1 -Manifest'} produced no parseable JSON payload\n${result.stdout}`
+  )
 }
 
 // Parse the JSON result frame from a stage run. The protocol guarantees
@@ -397,7 +421,9 @@ function parseStageResult(stdout) {
       if (parsed && typeof parsed.ok === 'boolean' && typeof parsed.stage === 'string') {
         return parsed
       }
-    } catch {}
+    } catch {
+      void 0
+    }
   }
   return null
 }
@@ -408,13 +434,20 @@ async function runStage({ scriptPath, installerKind, stage, emit, hermesHome, ac
 
   const isPosix = installerKind === 'posix'
   const args = isPosix
-    ? ['--stage', stage.name, '--non-interactive', '--json', ...buildPosixPinArgs({ installStamp, activeRoot, hermesHome })]
+    ? [
+        '--stage',
+        stage.name,
+        '--non-interactive',
+        '--json',
+        ...buildPosixPinArgs({ installStamp, activeRoot, hermesHome })
+      ]
     : ['-Stage', stage.name, '-NonInteractive', '-Json', ...buildPinArgs(installStamp)]
-  const result = await (isPosix ? spawnBash : spawnPowerShell)(
-    scriptPath,
-    args,
-    { emit, stageName: stage.name, abortSignal, hermesHome }
-  )
+  const result = await (isPosix ? spawnBash : spawnPowerShell)(scriptPath, args, {
+    emit,
+    stageName: stage.name,
+    abortSignal,
+    hermesHome
+  })
 
   const durationMs = Date.now() - startedAt
 
@@ -449,7 +482,14 @@ async function runStage({ scriptPath, installerKind, stage, emit, hermesHome, ac
     emit(ev)
     return ev
   }
-  const ev = { type: 'stage', name: stage.name, state: 'failed', durationMs, json, error: json.reason || `exit code ${result.code}` }
+  const ev = {
+    type: 'stage',
+    name: stage.name,
+    state: 'failed',
+    durationMs,
+    json,
+    error: json.reason || `exit code ${result.code}`
+  }
   emit(ev)
   return ev
 }
@@ -489,7 +529,9 @@ async function runBootstrap(opts) {
     if (typeof onEvent === 'function') {
       try {
         onEvent({ type: 'failed', error: 'bootstrap cancelled by user' })
-      } catch {}
+      } catch {
+        void 0
+      }
     }
     return { ok: false, cancelled: true }
   }
@@ -501,7 +543,9 @@ async function runBootstrap(opts) {
   const emit = ev => {
     try {
       runLog.stream.write(JSON.stringify(ev) + '\n')
-    } catch {}
+    } catch {
+      void 0
+    }
     try {
       if (typeof onEvent === 'function') onEvent(ev)
     } catch (err) {
@@ -578,7 +622,9 @@ async function runBootstrap(opts) {
   } finally {
     try {
       runLog.stream.end()
-    } catch {}
+    } catch {
+      void 0
+    }
   }
 }
 

apps/desktop/electron/connection-config.cjs

@@ -0,0 +1,118 @@
+/**
+ * connection-config.cjs
+ *
+ * Pure, electron-free helpers for the desktop's remote-gateway connection
+ * config: URL normalization, WS-URL construction (token vs OAuth ticket),
+ * auth-mode classification, and the auth-mode coercion rules.
+ *
+ * Kept standalone (no `require('electron')`) so it can be unit-tested with
+ * `node --test` — same pattern as backend-probes.cjs / bootstrap-platform.cjs.
+ * main.cjs requires these and wires them into the electron-coupled IPC layer.
+ *
+ * Background on the two auth models a remote gateway can use:
+ *   - 'token': legacy static dashboard session token. REST uses an
+ *     `X-Hermes-Session-Token` header; WS uses `?token=`.
+ *   - 'oauth': hosted gateways gate behind an OAuth provider. REST is authed
+ *     by an HttpOnly session cookie; WS upgrades require a single-use
+ *     `?ticket=` minted at POST /api/auth/ws-ticket. The gateway advertises
+ *     this via the public `/api/status` field `auth_required: true`.
+ */
+
+// Bare + prefixed variants of the access-token cookie the gateway may set,
+// depending on its deploy shape (HTTPS direct → __Host-, behind a path prefix
+// → __Secure-, loopback HTTP → bare). Mirrors
+// hermes_cli/dashboard_auth/cookies.py.
+const AT_COOKIE_VARIANTS = ['__Host-hermes_session_at', '__Secure-hermes_session_at', 'hermes_session_at']
+
+function normalizeRemoteBaseUrl(rawUrl) {
+  const value = String(rawUrl || '').trim()
+
+  if (!value) {
+    throw new Error('Remote gateway URL is required.')
+  }
+
+  let parsed
+  try {
+    parsed = new URL(value)
+  } catch (error) {
+    throw new Error(`Remote gateway URL is not valid: ${error.message}`)
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`Remote gateway URL must be http:// or https://, got ${parsed.protocol}`)
+  }
+
+  parsed.hash = ''
+  parsed.search = ''
+  parsed.pathname = parsed.pathname.replace(/\/+$/, '')
+
+  return parsed.toString().replace(/\/+$/, '')
+}
+
+function buildGatewayWsUrl(baseUrl, token) {
+  const parsed = new URL(baseUrl)
+  const wsScheme = parsed.protocol === 'https:' ? 'wss' : 'ws'
+  const prefix = parsed.pathname.replace(/\/+$/, '')
+
+  return `${wsScheme}://${parsed.host}${prefix}/api/ws?token=${encodeURIComponent(token)}`
+}
+
+function buildGatewayWsUrlWithTicket(baseUrl, ticket) {
+  const parsed = new URL(baseUrl)
+  const wsScheme = parsed.protocol === 'https:' ? 'wss' : 'ws'
+  const prefix = parsed.pathname.replace(/\/+$/, '')
+
+  return `${wsScheme}://${parsed.host}${prefix}/api/ws?ticket=${encodeURIComponent(ticket)}`
+}
+
+function tokenPreview(value) {
+  const raw = String(value || '')
+
+  if (!raw) {
+    return null
+  }
+
+  return raw.length <= 8 ? 'set' : `...${raw.slice(-6)}`
+}
+
+/**
+ * Classify a gateway's auth mode from its public /api/status body.
+ * `auth_required: true` → OAuth gate engaged; otherwise legacy token auth.
+ * Returns 'oauth' | 'token'.
+ */
+function authModeFromStatus(statusBody) {
+  return statusBody && statusBody.auth_required ? 'oauth' : 'token'
+}
+
+/**
+ * Resolve the effective auth mode for a coerce/save operation.
+ * Explicit input wins; otherwise inherit the saved value; default 'token'.
+ * Returns 'oauth' | 'token'.
+ */
+function resolveAuthMode(inputAuthMode, existingAuthMode) {
+  if (inputAuthMode === 'oauth') return 'oauth'
+  if (inputAuthMode === 'token') return 'token'
+  if (existingAuthMode === 'oauth') return 'oauth'
+  return 'token'
+}
+
+/**
+ * True if any cookie in `cookies` is a hermes session access-token cookie
+ * with a non-empty value. `cookies` is an array of {name, value} (the shape
+ * Electron's session.cookies.get returns).
+ */
+function cookiesHaveSession(cookies) {
+  if (!Array.isArray(cookies)) return false
+  return cookies.some(c => c && AT_COOKIE_VARIANTS.includes(c.name) && c.value)
+}
+
+module.exports = {
+  AT_COOKIE_VARIANTS,
+  authModeFromStatus,
+  buildGatewayWsUrl,
+  buildGatewayWsUrlWithTicket,
+  cookiesHaveSession,
+  normalizeRemoteBaseUrl,
+  resolveAuthMode,
+  tokenPreview
+}

apps/desktop/electron/connection-config.test.cjs

@@ -0,0 +1,161 @@
+/**
+ * Tests for electron/connection-config.cjs.
+ *
+ * Run with: node --test electron/connection-config.test.cjs
+ * (Wire into npm test:desktop:platforms in package.json.)
+ *
+ * These are the pure helpers behind the remote-gateway connection settings:
+ * URL normalization, WS-URL construction (token vs OAuth ticket), auth-mode
+ * classification from /api/status, the coerce-time auth-mode resolution rules,
+ * and the OAuth session-cookie detector.
+ */
+
+const test = require('node:test')
+const assert = require('node:assert/strict')
+
+const {
+  AT_COOKIE_VARIANTS,
+  authModeFromStatus,
+  buildGatewayWsUrl,
+  buildGatewayWsUrlWithTicket,
+  cookiesHaveSession,
+  normalizeRemoteBaseUrl,
+  resolveAuthMode,
+  tokenPreview
+} = require('./connection-config.cjs')
+
+// --- normalizeRemoteBaseUrl ---
+
+test('normalizeRemoteBaseUrl strips trailing slashes, hash, and query', () => {
+  assert.equal(normalizeRemoteBaseUrl('https://gw.example.com/'), 'https://gw.example.com')
+  assert.equal(normalizeRemoteBaseUrl('https://gw.example.com/hermes/'), 'https://gw.example.com/hermes')
+  assert.equal(normalizeRemoteBaseUrl('https://gw.example.com/hermes?x=1#frag'), 'https://gw.example.com/hermes')
+})
+
+test('normalizeRemoteBaseUrl preserves a path prefix', () => {
+  assert.equal(normalizeRemoteBaseUrl('https://host/hermes'), 'https://host/hermes')
+})
+
+test('normalizeRemoteBaseUrl rejects empty input', () => {
+  assert.throws(() => normalizeRemoteBaseUrl(''), /required/)
+  assert.throws(() => normalizeRemoteBaseUrl('   '), /required/)
+})
+
+test('normalizeRemoteBaseUrl rejects non-http(s) protocols', () => {
+  assert.throws(() => normalizeRemoteBaseUrl('ftp://host'), /http:\/\/ or https:\/\//)
+  assert.throws(() => normalizeRemoteBaseUrl('file:///etc/passwd'), /http:\/\/ or https:\/\//)
+})
+
+test('normalizeRemoteBaseUrl rejects garbage', () => {
+  assert.throws(() => normalizeRemoteBaseUrl('not a url'), /not valid/)
+})
+
+// --- buildGatewayWsUrl (token) ---
+
+test('buildGatewayWsUrl uses wss for https and bakes the token', () => {
+  assert.equal(buildGatewayWsUrl('https://gw.example.com', 'tok123'), 'wss://gw.example.com/api/ws?token=tok123')
+})
+
+test('buildGatewayWsUrl uses ws for http', () => {
+  assert.equal(buildGatewayWsUrl('http://127.0.0.1:9119', 'abc'), 'ws://127.0.0.1:9119/api/ws?token=abc')
+})
+
+test('buildGatewayWsUrl honors a path prefix', () => {
+  assert.equal(buildGatewayWsUrl('https://host/hermes', 't'), 'wss://host/hermes/api/ws?token=t')
+})
+
+test('buildGatewayWsUrl url-encodes the token', () => {
+  assert.equal(buildGatewayWsUrl('https://host', 'a/b c+d'), 'wss://host/api/ws?token=a%2Fb%20c%2Bd')
+})
+
+// --- buildGatewayWsUrlWithTicket (oauth) ---
+
+test('buildGatewayWsUrlWithTicket uses ?ticket= not ?token=', () => {
+  const url = buildGatewayWsUrlWithTicket('https://gw.example.com/hermes', 'tkt-9')
+  assert.equal(url, 'wss://gw.example.com/hermes/api/ws?ticket=tkt-9')
+  assert.ok(!url.includes('token='))
+})
+
+test('buildGatewayWsUrlWithTicket url-encodes the ticket', () => {
+  assert.equal(buildGatewayWsUrlWithTicket('https://host', 'a+b/c'), 'wss://host/api/ws?ticket=a%2Bb%2Fc')
+})
+
+// --- authModeFromStatus ---
+
+test('authModeFromStatus returns oauth when auth_required is true', () => {
+  assert.equal(authModeFromStatus({ auth_required: true, auth_providers: ['nous'] }), 'oauth')
+})
+
+test('authModeFromStatus returns token when auth_required is false/missing', () => {
+  assert.equal(authModeFromStatus({ auth_required: false }), 'token')
+  assert.equal(authModeFromStatus({}), 'token')
+  assert.equal(authModeFromStatus(null), 'token')
+  assert.equal(authModeFromStatus(undefined), 'token')
+})
+
+// --- resolveAuthMode ---
+
+test('resolveAuthMode: explicit input wins over existing', () => {
+  assert.equal(resolveAuthMode('oauth', 'token'), 'oauth')
+  assert.equal(resolveAuthMode('token', 'oauth'), 'token')
+})
+
+test('resolveAuthMode: falls back to existing when input absent', () => {
+  assert.equal(resolveAuthMode(undefined, 'oauth'), 'oauth')
+  assert.equal(resolveAuthMode(undefined, 'token'), 'token')
+  assert.equal(resolveAuthMode('', 'oauth'), 'oauth')
+})
+
+test('resolveAuthMode: defaults to token when nothing is set', () => {
+  assert.equal(resolveAuthMode(undefined, undefined), 'token')
+  assert.equal(resolveAuthMode(null, null), 'token')
+})
+
+test('resolveAuthMode: ignores unknown values, defaults to token', () => {
+  assert.equal(resolveAuthMode('bogus', 'also-bogus'), 'token')
+})
+
+// --- cookiesHaveSession ---
+
+test('cookiesHaveSession detects the bare access-token cookie', () => {
+  assert.equal(cookiesHaveSession([{ name: 'hermes_session_at', value: 'x' }]), true)
+})
+
+test('cookiesHaveSession detects the __Host- and __Secure- prefixed variants', () => {
+  assert.equal(cookiesHaveSession([{ name: '__Host-hermes_session_at', value: 'x' }]), true)
+  assert.equal(cookiesHaveSession([{ name: '__Secure-hermes_session_at', value: 'x' }]), true)
+})
+
+test('cookiesHaveSession is false for an empty value', () => {
+  assert.equal(cookiesHaveSession([{ name: 'hermes_session_at', value: '' }]), false)
+})
+
+test('cookiesHaveSession ignores unrelated cookies', () => {
+  assert.equal(cookiesHaveSession([{ name: 'hermes_session_rt', value: 'x' }]), false)
+  assert.equal(cookiesHaveSession([{ name: 'other', value: 'x' }]), false)
+})
+
+test('cookiesHaveSession handles non-arrays', () => {
+  assert.equal(cookiesHaveSession(null), false)
+  assert.equal(cookiesHaveSession(undefined), false)
+  assert.equal(cookiesHaveSession([]), false)
+})
+
+test('AT_COOKIE_VARIANTS covers all three deploy shapes', () => {
+  assert.deepEqual(AT_COOKIE_VARIANTS, ['__Host-hermes_session_at', '__Secure-hermes_session_at', 'hermes_session_at'])
+})
+
+// --- tokenPreview ---
+
+test('tokenPreview returns null for empty', () => {
+  assert.equal(tokenPreview(''), null)
+  assert.equal(tokenPreview(null), null)
+})
+
+test('tokenPreview returns set for short tokens', () => {
+  assert.equal(tokenPreview('12345678'), 'set')
+})
+
+test('tokenPreview returns a masked suffix for long tokens', () => {
+  assert.equal(tokenPreview('abcdefghijklmnop'), '...klmnop')
+})

apps/desktop/electron/preload.cjs

@@ -2,11 +2,15 @@ const { contextBridge, ipcRenderer, webUtils } = require('electron')
 
 contextBridge.exposeInMainWorld('hermesDesktop', {
   getConnection: () => ipcRenderer.invoke('hermes:connection'),
+  getGatewayWsUrl: () => ipcRenderer.invoke('hermes:gateway:ws-url'),
   getBootProgress: () => ipcRenderer.invoke('hermes:boot-progress:get'),
   getConnectionConfig: () => ipcRenderer.invoke('hermes:connection-config:get'),
   saveConnectionConfig: payload => ipcRenderer.invoke('hermes:connection-config:save', payload),
   applyConnectionConfig: payload => ipcRenderer.invoke('hermes:connection-config:apply', payload),
   testConnectionConfig: payload => ipcRenderer.invoke('hermes:connection-config:test', payload),
+  probeConnectionConfig: remoteUrl => ipcRenderer.invoke('hermes:connection-config:probe', remoteUrl),
+  oauthLoginConnectionConfig: remoteUrl => ipcRenderer.invoke('hermes:connection-config:oauth-login', remoteUrl),
+  oauthLogoutConnectionConfig: remoteUrl => ipcRenderer.invoke('hermes:connection-config:oauth-logout', remoteUrl),
   api: request => ipcRenderer.invoke('hermes:api', request),
   notify: payload => ipcRenderer.invoke('hermes:notify', payload),
   requestMicrophoneAccess: () => ipcRenderer.invoke('hermes:requestMicrophoneAccess'),
@@ -83,6 +87,11 @@ contextBridge.exposeInMainWorld('hermesDesktop', {
     ipcRenderer.on('hermes:backend-exit', listener)
     return () => ipcRenderer.removeListener('hermes:backend-exit', listener)
   },
+  onPowerResume: callback => {
+    const listener = () => callback()
+    ipcRenderer.on('hermes:power-resume', listener)
+    return () => ipcRenderer.removeListener('hermes:power-resume', listener)
+  },
   onBootProgress: callback => {
     const listener = (_event, payload) => callback(payload)
     ipcRenderer.on('hermes:boot-progress', listener)

apps/desktop/package.json

@@ -7,6 +7,9 @@
   "author": "Nous Research",
   "type": "module",
   "main": "electron/main.cjs",
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
   "scripts": {
     "dev": "concurrently -k \"npm:dev:renderer\" \"npm:dev:electron\"",
     "dev:fake-boot": "cross-env HERMES_DESKTOP_BOOT_FAKE=1 HERMES_DESKTOP_BOOT_FAKE_STEP_MS=650 npm run dev",
@@ -32,7 +35,7 @@
     "test:desktop:nsis": "node scripts/test-desktop.mjs nsis",
     "test:desktop:existing": "node scripts/test-desktop.mjs existing",
     "test:desktop:fresh": "node scripts/test-desktop.mjs fresh",
-    "test:desktop:platforms": "node --test electron/bootstrap-platform.test.cjs electron/hardening.test.cjs electron/backend-probes.test.cjs electron/bootstrap-runner.test.cjs",
+    "test:desktop:platforms": "node --test electron/bootstrap-platform.test.cjs electron/hardening.test.cjs electron/backend-probes.test.cjs electron/bootstrap-runner.test.cjs electron/connection-config.test.cjs",
     "type-check": "tsc -b",
     "lint": "eslint src/ electron/",
     "lint:fix": "eslint src/ electron/ --fix",
@@ -97,6 +100,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
+    "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.3.2",
     "@types/hast": "^3.0.4",
     "@types/node": "^24.12.2",
@@ -142,6 +146,7 @@
       "package.json"
     ],
     "beforeBuild": "scripts/before-build.cjs",
+    "beforePack": "scripts/before-pack.cjs",
     "afterPack": "scripts/after-pack.cjs",
     "extraResources": [
       {

apps/desktop/scripts/before-pack.cjs

@@ -0,0 +1,78 @@
+'use strict'
+
+/**
+ * before-pack.cjs — electron-builder beforePack hook.
+ *
+ * Removes any stale unpacked app directory (`appOutDir`) before
+ * electron-builder stages the Electron binaries into it.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * electron-builder's final packaging step copies the stock `electron`
+ * binary into `release/<platform>-unpacked/` and then renames it to the
+ * product name (`Hermes`). If a PREVIOUS `npm run pack` was interrupted
+ * (Ctrl-C, OOM kill, crash, full disk) the unpacked directory is left in a
+ * corrupted partial state: it keeps the already-renamed `LICENSE.electron.txt`
+ * and the Chromium payload (.pak/.so/icudtl.dat/chrome-sandbox) but is MISSING
+ * the `electron` binary itself.
+ *
+ * On the next run, electron-builder sees the destination directory already
+ * populated, skips re-copying the binary it thinks is present, then tries to
+ * rename a `electron` file that no longer exists. The build dies with:
+ *
+ *   ENOENT: no such file or directory, rename
+ *   '.../release/linux-unpacked/electron' -> '.../release/linux-unpacked/Hermes'
+ *
+ * This is a hard failure with no obvious cause for the user — `hermes desktop`
+ * just prints "Desktop GUI build failed" and the only fix is to manually
+ * `rm -rf` the release directory, which a normal user has no way to know.
+ *
+ * The packaging step is not idempotent across an interrupted run, so we make
+ * it idempotent ourselves: wipe the target unpacked directory up front so
+ * electron-builder always stages into a clean tree. This is safe — the
+ * directory is a pure build artifact that electron-builder fully recreates
+ * on every pack; nothing else depends on its prior contents.
+ *
+ * Cross-platform: the same partial-state trap exists on macOS
+ * (the mac-unpacked Hermes.app bundle) and Windows (win-unpacked), so we
+ * clean whatever `appOutDir` electron-builder hands us regardless of platform.
+ *
+ * Best-effort: a cleanup failure must never mask the real build. We log and
+ * resolve rather than throw — worst case electron-builder hits the original
+ * ENOENT, which is no worse than not having this hook at all.
+ *
+ * electron-builder passes a context with:
+ *   - appOutDir:            the unpacked app directory about to be staged
+ *   - electronPlatformName: 'win32' | 'darwin' | 'linux'
+ */
+
+const fs = require('node:fs')
+
+function cleanStaleAppOutDir(appOutDir) {
+  if (!appOutDir || typeof appOutDir !== 'string') {
+    return false
+  }
+  if (!fs.existsSync(appOutDir)) {
+    return false
+  }
+  // Recursive + force so a half-written tree (read-only bits, partial files)
+  // can't block the wipe. retry/maxRetries rides out transient EBUSY on
+  // Windows where an AV/indexer may briefly hold a handle.
+  fs.rmSync(appOutDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
+  return true
+}
+
+exports.cleanStaleAppOutDir = cleanStaleAppOutDir
+
+exports.default = async function beforePack(context) {
+  const appOutDir = context && context.appOutDir
+  try {
+    if (cleanStaleAppOutDir(appOutDir)) {
+      console.log(`[before-pack] removed stale unpacked dir before staging: ${appOutDir}`)
+    }
+  } catch (err) {
+    // Never fail the build over cleanup; surface why so a genuinely stuck
+    // directory (permissions, mount) is still diagnosable.
+    console.warn(`[before-pack] could not clean ${appOutDir} (${err.message}); continuing`)
+  }
+}

apps/desktop/scripts/before-pack.test.cjs

@@ -0,0 +1,53 @@
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const test = require('node:test')
+
+const { cleanStaleAppOutDir } = require('../scripts/before-pack.cjs')
+
+test('cleanStaleAppOutDir removes a populated unpacked directory', () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-before-pack-'))
+  try {
+    const appOutDir = path.join(tempRoot, 'linux-unpacked')
+    fs.mkdirSync(appOutDir, { recursive: true })
+    // Reproduce the corrupted partial state: license + payload present,
+    // electron binary missing — exactly what trips the ENOENT rename.
+    fs.writeFileSync(path.join(appOutDir, 'LICENSE.electron.txt'), 'x', 'utf8')
+    fs.writeFileSync(path.join(appOutDir, 'resources.pak'), 'x', 'utf8')
+    fs.mkdirSync(path.join(appOutDir, 'resources'), { recursive: true })
+    fs.writeFileSync(path.join(appOutDir, 'resources', 'app.asar'), 'x', 'utf8')
+
+    const removed = cleanStaleAppOutDir(appOutDir)
+
+    assert.equal(removed, true)
+    assert.equal(fs.existsSync(appOutDir), false)
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true })
+  }
+})
+
+test('cleanStaleAppOutDir is a no-op when the directory is absent', () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-before-pack-'))
+  try {
+    const missing = path.join(tempRoot, 'does-not-exist')
+    assert.equal(cleanStaleAppOutDir(missing), false)
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true })
+  }
+})
+
+test('cleanStaleAppOutDir ignores empty or invalid input', () => {
+  assert.equal(cleanStaleAppOutDir(''), false)
+  assert.equal(cleanStaleAppOutDir(undefined), false)
+  assert.equal(cleanStaleAppOutDir(null), false)
+  assert.equal(cleanStaleAppOutDir(42), false)
+})
+
+test('beforePack default export resolves even when cleanup throws', async () => {
+  const { default: beforePack } = require('../scripts/before-pack.cjs')
+  // A directory path that rmSync can't remove is simulated by passing a
+  // context whose appOutDir is a file the hook will try (and be allowed) to
+  // remove; the contract under test is that the hook never rejects.
+  await assert.doesNotReject(beforePack({ appOutDir: '', electronPlatformName: 'linux' }))
+})

apps/desktop/src/app/artifacts/index.tsx

@@ -5,7 +5,6 @@ import { useNavigate } from 'react-router-dom'
 import { ZoomableImage } from '@/components/chat/zoomable-image'
 import { PageLoader } from '@/components/page-loader'
 import { Button } from '@/components/ui/button'
-import { Codicon } from '@/components/ui/codicon'
 import { CopyButton } from '@/components/ui/copy-button'
 import {
   Pagination,
@@ -25,7 +24,9 @@ import { cn } from '@/lib/utils'
 import { notifyError } from '@/store/notifications'
 import type { SessionInfo, SessionMessage } from '@/types/hermes'
 
+import { useRefreshHotkey } from '../hooks/use-refresh-hotkey'
 import { useRouteEnumParam } from '../hooks/use-route-enum-param'
+import { PAGE_INSET_NEG_X, PAGE_INSET_X } from '../layout-constants'
 import { PageSearchShell } from '../page-search-shell'
 import { sessionRoute } from '../routes'
 import type { SetStatusbarItemGroup } from '../shell/statusbar-controls'
@@ -372,14 +373,11 @@ export function ArtifactsView({ setStatusbarItemGroup: _setStatusbarItemGroup, .
 
   const [kindFilter, setKindFilter] = useRouteEnumParam('tab', ARTIFACT_FILTERS, 'all')
 
-  const [refreshing, setRefreshing] = useState(false)
   const [failedImageIds, setFailedImageIds] = useState<Set<string>>(() => new Set())
   const [imagePage, setImagePage] = useState(1)
   const [filePage, setFilePage] = useState(1)
 
   const refreshArtifacts = useCallback(async () => {
-    setRefreshing(true)
-
     try {
       const sessions = (await listSessions(30, 1)).sessions
       const results = await Promise.allSettled(sessions.map(session => getSessionMessages(session.id)))
@@ -398,11 +396,11 @@ export function ArtifactsView({ setStatusbarItemGroup: _setStatusbarItemGroup, .
     } catch (err) {
       notifyError(err, 'Artifacts failed to load')
       setArtifacts([])
-    } finally {
-      setRefreshing(false)
     }
   }, [])
 
+  useRefreshHotkey(refreshArtifacts)
+
   useEffect(() => {
     void refreshArtifacts()
   }, [refreshArtifacts])
@@ -502,7 +500,11 @@ export function ArtifactsView({ setStatusbarItemGroup: _setStatusbarItemGroup, .
   return (
     <PageSearchShell
       {...props}
-      filters={
+      onSearchChange={setQuery}
+      searchHidden={counts.all === 0}
+      searchPlaceholder="Search artifacts..."
+      searchValue={query}
+      tabs={
         <>
           <TextTab active={kindFilter === 'all'} onClick={() => setKindFilter('all')}>
             All <TextTabMeta>({counts.all})</TextTabMeta>
@@ -518,23 +520,6 @@ export function ArtifactsView({ setStatusbarItemGroup: _setStatusbarItemGroup, .
           </TextTab>
         </>
       }
-      onSearchChange={setQuery}
-      searchPlaceholder="Search artifacts..."
-      searchTrailingAction={
-        <Button
-          aria-label={refreshing ? 'Refreshing artifacts' : 'Refresh artifacts'}
-          className="text-(--ui-text-tertiary) hover:bg-transparent hover:text-foreground"
-          disabled={refreshing}
-          onClick={() => void refreshArtifacts()}
-          size="icon-xs"
-          title={refreshing ? 'Refreshing artifacts' : 'Refresh artifacts'}
-          type="button"
-          variant="ghost"
-        >
-          <Codicon name="refresh" size="0.875rem" spinning={refreshing} />
-        </Button>
-      }
-      searchValue={query}
     >
       {!artifacts ? (
         <PageLoader label="Indexing recent session artifacts" />
@@ -549,10 +534,16 @@ export function ArtifactsView({ setStatusbarItemGroup: _setStatusbarItemGroup, .
         </div>
       ) : (
         <div className="h-full overflow-y-auto">
-          <div className="flex flex-col gap-3 px-2 pb-2">
+          <div className={cn('flex flex-col gap-3 pb-2', PAGE_INSET_X)}>
             {visibleImageArtifacts.length > 0 && (
               <section className="flex flex-col">
-                <div className="sticky top-0 z-10 -mx-2 flex h-7 items-center gap-3 overflow-x-auto bg-background px-3">
+                <div
+                  className={cn(
+                    'sticky top-0 z-10 flex h-7 items-center gap-3 overflow-x-auto bg-background',
+                    PAGE_INSET_NEG_X,
+                    PAGE_INSET_X
+                  )}
+                >
                   <ArtifactsPagination
                     className="ml-auto justify-end px-0"
                     itemLabel="images"
@@ -578,7 +569,13 @@ export function ArtifactsView({ setStatusbarItemGroup: _setStatusbarItemGroup, .
 
             {visibleFileArtifacts.length > 0 && (
               <section className="flex flex-col">
-                <div className="sticky top-0 z-10 -mx-2 flex h-7 items-center gap-3 overflow-x-auto bg-background px-3">
+                <div
+                  className={cn(
+                    'sticky top-0 z-10 flex h-7 items-center gap-3 overflow-x-auto bg-background',
+                    PAGE_INSET_NEG_X,
+                    PAGE_INSET_X
+                  )}
+                >
                   <ArtifactsPagination
                     className="ml-auto justify-end px-0"
                     itemLabel={itemsLabel(kindFilter)}
@@ -588,7 +585,7 @@ export function ArtifactsView({ setStatusbarItemGroup: _setStatusbarItemGroup, .
                     total={visibleFileArtifacts.length}
                   />
                 </div>
-                <div className="overflow-x-auto rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-chat-bubble-background) shadow-sm">
+                <div className="overflow-x-auto rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-chat-bubble-background)">
                   <ArtifactTable artifacts={pagedFileArtifacts} ctx={cellCtx} filter={kindFilter} />
                 </div>
               </section>
@@ -660,11 +657,7 @@ interface ArtifactImageCardProps {
 
 function ArtifactImageCard({ artifact, failedImage, onImageError, onOpenChat }: ArtifactImageCardProps) {
   return (
-    <article
-      className={cn(
-        'group/artifact overflow-hidden rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-chat-bubble-background) shadow-sm'
-      )}
-    >
+    <article className="group/artifact overflow-hidden rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-chat-bubble-background)">
       <div
         className={cn(
           'relative flex h-40 w-full items-center justify-center overflow-hidden border-b border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) p-1.5',
@@ -674,7 +667,7 @@ function ArtifactImageCard({ artifact, failedImage, onImageError, onOpenChat }:
         {!failedImage && (
           <ZoomableImage
             alt={artifact.label}
-            className="max-h-40 max-w-full cursor-zoom-in rounded-md object-contain shadow-sm"
+            className="max-h-40 max-w-full cursor-zoom-in rounded-md object-contain"
             containerClassName="max-h-full"
             decoding="async"
             loading="lazy"
@@ -702,7 +695,7 @@ function ArtifactImageCard({ artifact, failedImage, onImageError, onOpenChat }:
         </div>
 
         <div className="flex flex-wrap gap-1.5">
-          <Button onClick={() => onOpenChat(artifact.sessionId)} size="xs" type="button" variant="outline">
+          <Button onClick={() => onOpenChat(artifact.sessionId)} size="xs" type="button" variant="textStrong">
             <FolderOpen className="size-3" />
             Chat
           </Button>
@@ -741,10 +734,7 @@ function ArtifactCellAction({
 
   return (
     <button
-      className={cn(
-        'flex h-full w-full min-w-0 items-center gap-2 px-2.5 py-1.5 text-left text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) font-normal text-(--ui-text-secondary) no-underline underline-offset-4 decoration-current/20 transition-colors hover:text-foreground hover:underline',
-        'cursor-pointer'
-      )}
+      className="flex h-full w-full min-w-0 items-center gap-2 px-2.5 py-1.5 text-left text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) font-normal text-(--ui-text-secondary) no-underline underline-offset-4 decoration-current/20 transition-colors hover:text-foreground hover:underline"
       onClick={onClick}
       title={title}
       type="button"
@@ -863,7 +853,7 @@ function ArtifactTable({
           ))}
         </tr>
       </thead>
-      <tbody className="divide-y divide-(--ui-stroke-quaternary)">
+      <tbody>
         {artifacts.map(artifact => (
           <tr className="group/artifact" key={artifact.id}>
             {ARTIFACT_COLUMNS.map(col => {

apps/desktop/src/app/chat/composer/context-menu.tsx

@@ -2,13 +2,7 @@ import { useState } from 'react'
 
 import { Button } from '@/components/ui/button'
 import { Codicon } from '@/components/ui/codicon'
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogHeader,
-  DialogTitle
-} from '@/components/ui/dialog'
+import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from '@/components/ui/dialog'
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -104,8 +98,8 @@ export function ContextMenu({
           <DropdownMenuSeparator />
 
           <div className="px-2 py-1 text-[0.7rem] text-muted-foreground/80">
-            Tip: type <kbd className="rounded bg-muted/70 px-1 py-px font-mono text-[0.65rem]">@</kbd> to reference files
-            inline.
+            Tip: type <kbd className="rounded bg-muted/70 px-1 py-px font-mono text-[0.65rem]">@</kbd> to reference
+            files inline.
           </div>
         </DropdownMenuContent>
       </DropdownMenu>
@@ -120,12 +114,7 @@ export function ContextMenu({
   )
 }
 
-function PromptSnippetsDialog({
-  onInsertText,
-  onOpenChange,
-  open,
-  snippets
-}: PromptSnippetsDialogProps) {
+function PromptSnippetsDialog({ onInsertText, onOpenChange, open, snippets }: PromptSnippetsDialogProps) {
   return (
     <Dialog onOpenChange={onOpenChange} open={open}>
       <DialogContent className="max-w-md gap-3">
@@ -137,7 +126,7 @@ function PromptSnippetsDialog({
           {snippets.map(snippet => (
             <li key={snippet.label}>
               <button
-                className="group/snippet flex w-full cursor-pointer items-start gap-2.5 rounded-md border border-transparent px-2.5 py-2 text-left transition-colors hover:border-(--ui-stroke-tertiary) hover:bg-(--ui-control-hover-background) focus-visible:border-(--ui-stroke-tertiary) focus-visible:bg-(--ui-control-hover-background) focus-visible:outline-none"
+                className="group/snippet flex w-full items-start gap-2.5 rounded-md border border-transparent px-2.5 py-2 text-left transition-colors hover:border-(--ui-stroke-tertiary) hover:bg-(--ui-control-hover-background) focus-visible:border-(--ui-stroke-tertiary) focus-visible:bg-(--ui-control-hover-background) focus-visible:outline-none"
                 onClick={() => {
                   onInsertText(snippet.text)
                   onOpenChange(false)
@@ -160,12 +149,7 @@ function PromptSnippetsDialog({
   )
 }
 
-export function ContextMenuItem({
-  children,
-  disabled,
-  icon: Icon,
-  onSelect
-}: ContextMenuItemProps) {
+export function ContextMenuItem({ children, disabled, icon: Icon, onSelect }: ContextMenuItemProps) {
   return (
     <DropdownMenuItem disabled={disabled} onSelect={onSelect}>
       <Icon />

apps/desktop/src/app/chat/composer/hooks/use-slash-completions.ts

@@ -16,6 +16,7 @@ interface SlashItemMetadata extends Record<string, string> {
   command: string
   display: string
   meta: string
+  rawText: string
 }
 
 function textValue(value: unknown, fallback = ''): string {
@@ -91,7 +92,13 @@ export function useSlashCompletions(options: { gateway: HermesGateway | null }):
     const metadata: SlashItemMetadata = {
       command,
       display,
-      meta
+      meta,
+      // Provide rawText so hermesDirectiveFormatter.serialize uses the
+      // direct-insertion path instead of the legacy @type:id fallback.
+      // Without this, the item.id (which includes a "|index" suffix for
+      // trigger-adapter uniqueness) leaks into the serialized chip text
+      // and the submitted command.
+      rawText: command
     }
 
     return {

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

@@ -18,14 +18,11 @@ import { Button } from '@/components/ui/button'
 import { useMediaQuery } from '@/hooks/use-media-query'
 import { useResizeObserver } from '@/hooks/use-resize-observer'
 import { chatMessageText } from '@/lib/chat-messages'
+import { SLASH_COMMAND_RE } from '@/lib/chat-runtime'
 import { DATA_IMAGE_URL_RE } from '@/lib/embedded-images'
 import { triggerHaptic } from '@/lib/haptics'
 import { cn } from '@/lib/utils'
-import {
-  $composerAttachments,
-  clearComposerAttachments,
-  type ComposerAttachment
-} from '@/store/composer'
+import { $composerAttachments, clearComposerAttachments, type ComposerAttachment } from '@/store/composer'
 import {
   $queuedPromptsBySession,
   enqueueQueuedPrompt,
@@ -34,7 +31,7 @@ import {
   shouldAutoDrainOnSettle,
   updateQueuedPrompt
 } from '@/store/composer-queue'
-import { $messages } from '@/store/session'
+import { $gatewayState, $messages } from '@/store/session'
 import { $threadScrolledUp } from '@/store/thread-scroll'
 
 import { extractDroppedFiles, HERMES_PATHS_MIME } from '../hooks/use-composer-actions'
@@ -73,9 +70,39 @@ import { VoiceActivity, VoicePlaybackActivity } from './voice-activity'
 
 const COMPOSER_STACK_BREAKPOINT_PX = 320
 
+// A single editor line is ~28px (--composer-input-min-height 1.625rem + 0.5rem
+// vertical padding). Anything taller means the text wrapped to a second line,
+// which is when the composer should expand to the stacked layout.
+const COMPOSER_SINGLE_LINE_MAX_PX = 36
+
 const COMPOSER_FADE_BACKGROUND =
   'linear-gradient(to bottom, transparent, color-mix(in srgb, var(--dt-background) 10%, transparent))'
 
+// Resting composer placeholders. New sessions get open-ended starters; an
+// existing chat gets phrasings that read as a continuation of the thread.
+// One is picked at random per session (stable until the session changes).
+const NEW_SESSION_PLACEHOLDERS = [
+  'What are we building?',
+  'Give Hermes a task',
+  "What's on your mind?",
+  'Describe what you need',
+  'What should we tackle?',
+  'Ask anything',
+  'Start with a goal'
+]
+
+const FOLLOW_UP_PLACEHOLDERS = [
+  'Send a follow-up',
+  'Add more context',
+  'Refine the request',
+  "What's next?",
+  'Keep it going',
+  'Push it further',
+  'Adjust or continue'
+]
+
+const pickPlaceholder = (pool: readonly string[]) => pool[Math.floor(Math.random() * pool.length)]
+
 interface QueueEditState {
   attachments: ComposerAttachment[]
   draft: string
@@ -142,6 +169,7 @@ export function ChatBar({
   const [queueEdit, setQueueEdit] = useState<QueueEditState | null>(null)
   const [focusRequestId, setFocusRequestId] = useState(0)
   const dragDepthRef = useRef(0)
+  const composingRef = useRef(false) // true during IME composition (CJK input)
   const lastSpokenIdRef = useRef<string | null>(null)
 
   const narrow = useMediaQuery('(max-width: 30rem)')
@@ -156,7 +184,44 @@ export function ChatBar({
   const busyAction = busy && hasComposerPayload ? 'queue' : 'stop'
   const showHelpHint = draft === '?'
 
-  const placeholder = disabled ? 'Starting Hermes...' : 'Send follow-up'
+  const gatewayState = useStore($gatewayState)
+
+  // Resting placeholder: a starter for brand-new sessions, a continuation for
+  // existing ones. Picked once and only re-rolled when we genuinely move to a
+  // *different* conversation. Critically, the first id assignment of a freshly
+  // started session (null → id, on the first send) is treated as the same
+  // conversation so the placeholder doesn't visibly flip mid-stream.
+  const [restingPlaceholder, setRestingPlaceholder] = useState(() =>
+    pickPlaceholder(sessionId ? FOLLOW_UP_PLACEHOLDERS : NEW_SESSION_PLACEHOLDERS)
+  )
+
+  const prevSessionIdRef = useRef(sessionId)
+
+  useEffect(() => {
+    const prev = prevSessionIdRef.current
+    prevSessionIdRef.current = sessionId
+
+    if (prev === sessionId) {
+      return
+    }
+
+    // null → id: the new session we're already in just got persisted. Keep the
+    // starter we showed instead of swapping to a follow-up under the user.
+    if (prev == null && sessionId) {
+      return
+    }
+
+    setRestingPlaceholder(pickPlaceholder(sessionId ? FOLLOW_UP_PLACEHOLDERS : NEW_SESSION_PLACEHOLDERS))
+  }, [sessionId])
+
+  // When the bar is disabled it's because the gateway isn't open. Distinguish a
+  // cold start ("Starting Hermes...") from a dropped connection we're trying to
+  // restore (e.g. after the Mac slept) so the stuck state reads as recoverable.
+  const placeholder = disabled
+    ? gatewayState === 'closed' || gatewayState === 'error'
+      ? 'Reconnecting to Hermes…'
+      : 'Starting Hermes...'
+    : restingPlaceholder
 
   const focusInput = useCallback(() => {
     focusComposerInput(editorRef.current)
@@ -247,14 +312,13 @@ export function ChatBar({
     }
   }, [urlOpen])
 
-  // Track expansion via cheap heuristics (newline or length threshold) instead
-  // of reading editor.scrollHeight on every keystroke. scrollHeight forces a
-  // synchronous layout flush — measured at 2.27 layouts per character typed
-  // (see scripts/leak-typing.mjs). With ~30 chars before a typical wrap on
-  // composer-default-width, this heuristic flips at roughly the right time
-  // and the user only notices if they type far past the wrap boundary
-  // without a newline; in that case the ResizeObserver below catches it via
-  // a height delta and we still expand.
+  // Expansion (input on its own full-width row, controls below) is driven by
+  // the editor's *actual* rendered height via the ResizeObserver in
+  // syncComposerMetrics — it only fires when the text genuinely wraps to a
+  // second line, so the layout flips exactly at the wrap point rather than at
+  // a guessed character count. We only handle the two cases the observer
+  // can't: an explicit newline (expand before layout settles) and an emptied
+  // draft (collapse back). We never read scrollHeight per keystroke.
   useEffect(() => {
     if (!draft) {
       setExpanded(false)
@@ -266,7 +330,7 @@ export function ChatBar({
       return
     }
 
-    if (draft.includes('\n') || draft.length > 60) {
+    if (draft.includes('\n')) {
       setExpanded(true)
     }
   }, [draft, expanded])
@@ -302,6 +366,18 @@ export function ChatBar({
       }
     }
 
+    // Expand once the input has actually wrapped past a single line. The
+    // observer only fires on real size changes, so this reads scrollHeight at
+    // most once per wrap (not per keystroke). One line ≈ 28px (1.625rem
+    // min-height + padding); a second line clears ~36px. We only ever expand
+    // here — collapse is handled by the emptied-draft effect to avoid
+    // oscillating across the wrap boundary as the input switches widths.
+    const editor = editorRef.current
+
+    if (editor && editor.scrollHeight > COMPOSER_SINGLE_LINE_MAX_PX) {
+      setExpanded(true)
+    }
+
     if (height > 0) {
       const bucket = Math.round(height / 8) * 8
 
@@ -321,7 +397,7 @@ export function ChatBar({
     }
   }, [])
 
-  useResizeObserver(syncComposerMetrics, composerRef, composerSurfaceRef)
+  useResizeObserver(syncComposerMetrics, composerRef, composerSurfaceRef, editorRef)
 
   useEffect(() => {
     return () => {
@@ -399,13 +475,19 @@ export function ChatBar({
       return
     }
 
-    const pastedText = event.clipboardData.getData('text')
+    // Trim surrounding whitespace so a copy that dragged along leading/trailing
+    // blank lines (common when selecting from terminals, code blocks, web pages)
+    // doesn't dump multiline padding into the composer. Internal newlines are
+    // preserved — only the edges are cleaned up.
+    const pastedText = event.clipboardData.getData('text').trim()
 
     if (!pastedText) {
+      event.preventDefault()
+
       return
     }
 
-    if (DATA_IMAGE_URL_RE.test(pastedText.trim())) {
+    if (DATA_IMAGE_URL_RE.test(pastedText)) {
       event.preventDefault()
 
       return
@@ -468,6 +550,13 @@ export function ChatBar({
   }, [trigger])
 
   const handleEditorInput = (event: FormEvent<HTMLDivElement>) => {
+    // During IME composition the DOM contains uncommitted preedit text
+    // mixed with real content.  Skip state writes — compositionend will
+    // deliver the finalized text via a clean input event.
+    if (composingRef.current) {
+      return
+    }
+
     const editor = event.currentTarget
 
     if (editor.childNodes.length === 1 && editor.firstChild?.nodeName === 'BR') {
@@ -567,7 +656,18 @@ export function ChatBar({
   }
 
   const handleEditorKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
-    if ((event.metaKey || event.ctrlKey) && !event.altKey && !event.shiftKey && event.key.toLowerCase() === 'k') {
+    // IME composition: Enter confirms composed text, not a message submission.
+    // We check both composingRef (set by compositionstart/compositionend, robust
+    // across browsers) and nativeEvent.isComposing (Chromium fallback).  Without
+    // this guard, pressing Enter to finalise a Korean/Japanese/Chinese IME
+    // preedit fires submitDraft() and splits the message mid-word.
+    if (composingRef.current || event.nativeEvent.isComposing) {
+      return
+    }
+
+    // Cmd/Ctrl+Shift+K drains the next queued message. Plain Cmd/Ctrl+K is
+    // reserved for the global command palette.
+    if ((event.metaKey || event.ctrlKey) && !event.altKey && event.shiftKey && event.key.toLowerCase() === 'k') {
       event.preventDefault()
 
       if (!busy) {
@@ -938,7 +1038,19 @@ export function ChatBar({
     if (queueEdit) {
       exitQueuedEdit('save')
     } else if (busy) {
-      if (hasComposerPayload) {
+      // Slash commands should execute immediately even while the agent is
+      // busy — they're client-side operations (/yolo, /skin, /new, /help,
+      // etc.) or self-contained gateway RPCs (/status, /compress).  onSubmit
+      // routes them to executeSlashCommand, which has its own per-command
+      // busy guard for commands that genuinely need an idle session (skill
+      // /send directives).  Queuing them would make every slash command wait
+      // for the current turn to finish, which is how the TUI never behaves.
+      if (!attachments.length && SLASH_COMMAND_RE.test(draft.trim())) {
+        const submitted = draft
+        triggerHaptic('submit')
+        clearDraft()
+        void onSubmit(submitted)
+      } else if (hasComposerPayload) {
         queueCurrentDraft()
       } else {
         // Stop button: an explicit interrupt must actually halt the running
@@ -956,7 +1068,8 @@ export function ChatBar({
       const submitted = draft
       triggerHaptic('submit')
       clearDraft()
-      void onSubmit(submitted)
+      clearComposerAttachments()
+      void onSubmit(submitted, { attachments })
     }
 
     focusInput()
@@ -1082,10 +1195,10 @@ export function ChatBar({
     <div className={cn('relative', stacked ? 'w-full' : 'min-w-(--composer-input-inline-min-width) flex-1')}>
       <div
         aria-label="Message"
-        autoCorrect="off"
         autoCapitalize="off"
+        autoCorrect="off"
         className={cn(
-          'min-h-(--composer-input-min-height) max-h-(--composer-input-max-height) overflow-y-auto bg-transparent pb-1 pr-1 pt-1 leading-normal text-foreground outline-none disabled:cursor-not-allowed',
+          'min-h-(--composer-input-min-height) max-h-(--composer-input-max-height) overflow-y-auto whitespace-pre-wrap break-words [overflow-wrap:anywhere] bg-transparent pb-1 pr-1 pt-1 leading-normal text-foreground outline-none disabled:cursor-not-allowed',
           'empty:before:content-[attr(data-placeholder)] empty:before:text-muted-foreground/60',
           '**:data-ref-text:cursor-default',
           stacked && 'pl-3',
@@ -1095,6 +1208,12 @@ export function ChatBar({
         data-placeholder={placeholder}
         data-slot={RICH_INPUT_SLOT}
         onBlur={() => window.setTimeout(closeTrigger, 80)}
+        onCompositionEnd={() => {
+          composingRef.current = false
+        }}
+        onCompositionStart={() => {
+          composingRef.current = true
+        }}
         onDragOver={handleInputDragOver}
         onDrop={handleInputDrop}
         onFocus={() => markActiveComposer('main')}
@@ -1123,7 +1242,7 @@ export function ChatBar({
 
         `asChild` swaps TextareaAutosize for a Radix Slot wrapping our
         plain <textarea>, which carries the binding but skips autosize. */}
-      <ComposerPrimitive.Input asChild tabIndex={-1} unstable_focusOnScrollToBottom={false}>
+      <ComposerPrimitive.Input asChild submitMode="ctrlEnter" tabIndex={-1} unstable_focusOnScrollToBottom={false}>
         <textarea aria-hidden className="sr-only" tabIndex={-1} />
       </ComposerPrimitive.Input>
     </div>
@@ -1143,6 +1262,11 @@ export function ChatBar({
           onDrop={handleDrop}
           onSubmit={e => {
             e.preventDefault()
+
+            if (composingRef.current) {
+              return
+            }
+
             submitDraft()
           }}
           ref={composerRef}
@@ -1245,7 +1369,7 @@ export function ChatBar({
                     'grid w-full',
                     stacked
                       ? 'grid-cols-[auto_1fr] gap-(--composer-row-gap) [grid-template-areas:"input_input"_"menu_controls"]'
-                      : 'grid-cols-[auto_1fr_auto] items-end gap-(--composer-control-gap) [grid-template-areas:"menu_input_controls"]'
+                      : 'grid-cols-[auto_1fr_auto] items-center gap-(--composer-control-gap) [grid-template-areas:"menu_input_controls"]'
                   )}
                 >
                   <div className="flex items-center [grid-area:menu]">{contextMenu}</div>

apps/desktop/src/app/chat/composer/slash-nav-dom-repro.test.tsx

@@ -37,7 +37,10 @@ function Harness({
   const refreshTrigger = useCallback(() => {
     const editor = editorRef.current
 
-    if (!editor) {return}
+    if (!editor) {
+      return
+    }
+
     const raw = editor.textContent ?? ''
 
     if (!raw.includes('@') && !raw.includes('/')) {

apps/desktop/src/app/chat/composer/text-utils.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
-import { detectTrigger } from './text-utils'
+import { blobDedupeKey, detectTrigger, extractClipboardImageBlobs } from './text-utils'
 
 describe('detectTrigger', () => {
   it('detects a bare slash trigger with an empty query', () => {
@@ -23,3 +23,55 @@ describe('detectTrigger', () => {
     expect(detectTrigger('hello there')).toBeNull()
   })
 })
+
+describe('extractClipboardImageBlobs', () => {
+  it('dedupes the same image exposed on both items and files', () => {
+    const image = new File([new Uint8Array([1, 2, 3])], 'paste.png', {
+      type: 'image/png',
+      lastModified: 1_700_000_000_000
+    })
+
+    const clipboard = {
+      files: {
+        length: 1,
+        item: (index: number) => (index === 0 ? image : null)
+      },
+      getData: () => '',
+      items: [
+        {
+          kind: 'file',
+          type: 'image/png',
+          getAsFile: () => image
+        }
+      ]
+    } as unknown as DataTransfer
+
+    expect(extractClipboardImageBlobs(clipboard)).toEqual([image])
+  })
+
+  it('falls back to files when items has no image', () => {
+    const image = new File([new Uint8Array([4, 5])], 'shot.jpg', {
+      type: 'image/jpeg',
+      lastModified: 1_700_000_000_001
+    })
+
+    const clipboard = {
+      files: {
+        length: 1,
+        item: (index: number) => (index === 0 ? image : null)
+      },
+      getData: () => '',
+      items: []
+    } as unknown as DataTransfer
+
+    expect(extractClipboardImageBlobs(clipboard)).toEqual([image])
+  })
+})
+
+describe('blobDedupeKey', () => {
+  it('uses file metadata for File blobs', () => {
+    const file = new File([], 'a.png', { type: 'image/png', lastModified: 42 })
+
+    expect(blobDedupeKey(file)).toBe('file:a.png:0:image/png:42')
+  })
+})

apps/desktop/src/app/chat/composer/text-utils.ts

@@ -8,16 +8,31 @@ export interface TriggerState {
 
 const TRIGGER_RE = /(?:^|[\s])([@/])([^\s@/]*)$/
 
+/** Stable key for paste dedupe — `items` and `files` often mirror the same image as different objects. */
+export function blobDedupeKey(blob: Blob): string {
+  if (blob instanceof File) {
+    return `file:${blob.name}:${blob.size}:${blob.type}:${blob.lastModified}`
+  }
+
+  return `blob:${blob.size}:${blob.type}`
+}
+
 export function extractClipboardImageBlobs(clipboard: DataTransfer): Blob[] {
   const blobs: Blob[] = []
-  const seen = new Set<Blob>()
+  const seen = new Set<string>()
 
   const push = (blob: Blob | null) => {
-    if (!blob || blob.size === 0 || seen.has(blob)) {
+    if (!blob || blob.size === 0) {
       return
     }
 
-    seen.add(blob)
+    const key = blobDedupeKey(blob)
+
+    if (seen.has(key)) {
+      return
+    }
+
+    seen.add(key)
     blobs.push(blob)
   }
 
@@ -29,7 +44,8 @@ export function extractClipboardImageBlobs(clipboard: DataTransfer): Blob[] {
     }
   }
 
-  if (clipboard.files?.length) {
+  // Chromium/Electron expose the same pasted image on both `items` and `files`.
+  if (blobs.length === 0 && clipboard.files?.length) {
     for (let i = 0; i < clipboard.files.length; i += 1) {
       const file = clipboard.files.item(i)
 

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

@@ -13,6 +13,7 @@ import { useLocation } from 'react-router-dom'
 import { Thread } from '@/components/assistant-ui/thread'
 import { Backdrop } from '@/components/Backdrop'
 import { NotificationStack } from '@/components/notifications'
+import { PromptOverlays } from '@/components/prompt-overlays'
 import { Button } from '@/components/ui/button'
 import { Codicon } from '@/components/ui/codicon'
 import { getGlobalModelOptions, type HermesGateway } from '@/hermes'
@@ -36,7 +37,8 @@ import {
   $introSeed,
   $messages,
   $selectedStoredSessionId,
-  $sessions
+  $sessions,
+  sessionPinId
 } from '@/store/session'
 import type { ModelOptionsResponse } from '@/types/hermes'
 
@@ -96,9 +98,27 @@ function ChatHeader({
 }: ChatHeaderProps) {
   const sessions = useStore($sessions)
   const pinnedSessionIds = useStore($pinnedSessionIds)
-  const activeStoredSession = sessions.find(session => session.id === selectedSessionId) || null
+
+  const activeStoredSession =
+    sessions.find(session => session.id === selectedSessionId || session._lineage_root_id === selectedSessionId) || null
+
   const title = activeStoredSession ? sessionTitle(activeStoredSession) : 'New session'
-  const selectedIsPinned = selectedSessionId ? pinnedSessionIds.includes(selectedSessionId) : false
+
+  // Pins live on the durable lineage-root id, but selectedSessionId is the live
+  // (tip) id — resolve through the loaded row so the menu reflects the pin
+  // state after auto-compression rotates the id.
+  const selectedIsPinned = activeStoredSession
+    ? pinnedSessionIds.includes(sessionPinId(activeStoredSession))
+    : selectedSessionId
+      ? pinnedSessionIds.includes(selectedSessionId)
+      : false
+
+  // A brand-new session has no session to pin/delete/rename, so the header is
+  // just a dead "New session" label + chevron. Drop it (and its border)
+  // entirely until there's a real session to act on.
+  if (!selectedSessionId && !activeSessionId && !isRoutedSessionView) {
+    return null
+  }
 
   return (
     <header className={cn(titlebarHeaderBaseClass, isRoutedSessionView && titlebarHeaderShadowClass)}>
@@ -113,7 +133,7 @@ function ChatHeader({
           title={title}
         >
           <Button
-            className="pointer-events-auto h-6 min-w-0 gap-1 rounded-md border border-transparent bg-transparent px-2 py-0 text-(--ui-text-secondary) hover:border-(--ui-stroke-tertiary) hover:bg-(--ui-control-hover-background) hover:text-foreground data-[state=open]:border-(--ui-stroke-tertiary) data-[state=open]:bg-(--ui-control-active-background) [-webkit-app-region:no-drag]"
+            className="pointer-events-auto h-6 min-w-0 gap-1 border border-transparent bg-transparent px-2 py-0 text-(--ui-text-secondary) hover:border-(--ui-stroke-tertiary) hover:bg-(--ui-control-hover-background) hover:text-foreground data-[state=open]:border-(--ui-stroke-tertiary) data-[state=open]:bg-(--ui-control-active-background) [-webkit-app-region:no-drag]"
             type="button"
             variant="ghost"
           >
@@ -306,6 +326,7 @@ export function ChatView({
       />
 
       <NotificationStack />
+      <PromptOverlays />
 
       <div
         className="relative min-h-0 max-w-full flex-1 overflow-hidden bg-(--ui-chat-surface-background) contain-[layout_paint]"

apps/desktop/src/app/chat/perf-probe.tsx

@@ -1,6 +1,6 @@
 import { Profiler, type ProfilerOnRenderCallback, type ReactNode } from 'react'
 
-import { $messages, setMessages, setBusy } from '@/store/session'
+import { $messages, setBusy, setMessages } from '@/store/session'
 
 type Sample = {
   id: string
@@ -40,13 +40,16 @@ if (typeof window !== 'undefined' && !window.__PERF_PROBE__) {
     },
     summary: () => {
       const byId = new Map<string, number[]>()
+
       for (const s of samples) {
         const k = `${s.id}:${s.phase}`
         const arr = byId.get(k) ?? []
         arr.push(s.actualDuration)
         byId.set(k, arr)
       }
+
       const out: Record<string, { count: number; total: number; max: number; p50: number; p95: number }> = {}
+
       for (const [k, arr] of byId) {
         arr.sort((a, b) => a - b)
         const total = arr.reduce((a, b) => a + b, 0)
@@ -55,19 +58,27 @@ if (typeof window !== 'undefined' && !window.__PERF_PROBE__) {
           total: Math.round(total * 100) / 100,
           max: Math.round(arr[arr.length - 1] * 100) / 100,
           p50: Math.round(arr[Math.floor(arr.length * 0.5)] * 100) / 100,
-          p95: Math.round(arr[Math.floor(arr.length * 0.95)] * 100) / 100,
+          p95: Math.round(arr[Math.floor(arr.length * 0.95)] * 100) / 100
         }
       }
+
       return out
-    },
+    }
   }
 }
 
 const onRender: ProfilerOnRenderCallback = (id, phase, actualDuration, baseDuration, startTime, commitTime) => {
   const probe = typeof window !== 'undefined' ? window.__PERF_PROBE__ : undefined
-  if (!probe || !probe.enabled) return
+
+  if (!probe || !probe.enabled) {
+    return
+  }
+
   probe.samples.push({ id, phase, actualDuration, baseDuration, startTime, commitTime })
-  if (probe.samples.length > 5000) probe.samples.splice(0, probe.samples.length - 5000)
+
+  if (probe.samples.length > 5000) {
+    probe.samples.splice(0, probe.samples.length - 5000)
+  }
 }
 
 if (typeof window !== 'undefined' && !window.__PERF_DRIVE__) {
@@ -86,7 +97,11 @@ if (typeof window !== 'undefined' && !window.__PERF_DRIVE__) {
     snapshotMsgs: () => $messages.get().length,
     reset: () => {
       activeHandle?.stop()
-      if (baseline) setMessages(baseline)
+
+      if (baseline) {
+        setMessages(baseline)
+      }
+
       baseline = null
       setBusy(false)
     },
@@ -104,7 +119,11 @@ if (typeof window !== 'undefined' && !window.__PERF_DRIVE__) {
     }: { chunk?: string; intervalMs?: number; totalTokens?: number; flushMinMs?: number } = {}) => {
       activeHandle?.stop()
       const current = $messages.get()
-      if (!baseline) baseline = current
+
+      if (!baseline) {
+        baseline = current
+      }
+
       const msgId = `synthetic-${Date.now()}`
       // Seed an empty assistant message — assistant-ui will see it grow.
       setMessages([
@@ -126,13 +145,20 @@ if (typeof window !== 'undefined' && !window.__PERF_DRIVE__) {
       let flushHandle: number | null = null
 
       const applyDelta = (delta: string) => {
-        if (!delta) return
+        if (!delta) {
+          return
+        }
+
         setMessages(prev =>
           prev.map(m => {
-            if (m.id !== msgId) return m
+            if (m.id !== msgId) {
+              return m
+            }
+
             const head = m.parts.slice(0, -1)
             const last = m.parts.at(-1)
             const lastText = last && last.type === 'text' ? last.text : ''
+
             return {
               ...m,
               parts: [...head, { type: 'text', text: lastText + delta }]
@@ -150,8 +176,16 @@ if (typeof window !== 'undefined' && !window.__PERF_DRIVE__) {
       }
 
       const scheduleFlush = () => {
-        if (flushHandle !== null) return
-        if (flushMinMs <= 0) { flushNow(); return }
+        if (flushHandle !== null) {
+          return
+        }
+
+        if (flushMinMs <= 0) {
+          flushNow()
+
+          return
+        }
+
         const since = performance.now() - lastFlushAt
         const wait = Math.max(0, flushMinMs - since)
         flushHandle =
@@ -162,48 +196,62 @@ if (typeof window !== 'undefined' && !window.__PERF_DRIVE__) {
 
       const handle: SyntheticDriverHandle = {
         stop: () => {
-          if (timer) clearTimeout(timer)
+          if (timer) {
+            clearTimeout(timer)
+          }
+
           timer = null
+
           if (flushHandle !== null) {
             clearTimeout(flushHandle)
             cancelAnimationFrame?.(flushHandle)
           }
+
           flushHandle = null
+
           if (pendingDelta) {
             applyDelta(pendingDelta)
             pendingDelta = ''
           }
+
           activeHandle = null
           // Mark message finalized.
-          setMessages(prev =>
-            prev.map(m =>
-              m.id === msgId
-                ? { ...m, pending: false }
-                : m
-            )
-          )
+          setMessages(prev => prev.map(m => (m.id === msgId ? { ...m, pending: false } : m)))
           setBusy(false)
         }
       }
+
       activeHandle = handle
 
       const tick = () => {
-        if (activeHandle !== handle) return
-        if (pushed >= totalTokens) {
-          if (pendingDelta) flushNow()
-          handle.stop()
+        if (activeHandle !== handle) {
           return
         }
+
+        if (pushed >= totalTokens) {
+          if (pendingDelta) {
+            flushNow()
+          }
+
+          handle.stop()
+
+          return
+        }
+
         pushed += 1
+
         if (flushMinMs > 0) {
           pendingDelta += chunk
           scheduleFlush()
         } else {
           applyDelta(chunk)
         }
+
         timer = setTimeout(tick, intervalMs)
       }
+
       timer = setTimeout(tick, intervalMs)
+
       return handle
     }
   }

apps/desktop/src/app/chat/right-rail/preview-console.tsx

@@ -82,7 +82,7 @@ function ConsoleRow({ copyText, log, onSend, onToggleSelect, selected }: Console
     >
       <button
         className={cn(
-          'mt-0.5 cursor-pointer text-left uppercase opacity-70 transition-colors hover:opacity-100',
+          'mt-0.5 text-left uppercase opacity-70 transition-colors hover:opacity-100',
           consoleLevelClass[log.level] ?? consoleLevelClass[0]
         )}
         onClick={onToggleSelect}

apps/desktop/src/app/chat/right-rail/preview-file.tsx

@@ -11,6 +11,7 @@ import ShikiHighlighter from 'react-shiki'
 import { Streamdown } from 'streamdown'
 
 import { HERMES_PATHS_MIME } from '@/app/chat/hooks/use-composer-actions'
+import { PageLoader } from '@/components/page-loader'
 import { cn } from '@/lib/utils'
 import type { PreviewTarget } from '@/store/preview'
 
@@ -481,7 +482,7 @@ export function LocalFilePreview({ reloadKey, target }: { reloadKey: number; tar
   }, [blockedByTarget, filePath, forcePreview, isImage, isText, reloadKey, target.language])
 
   if (state.loading) {
-    return <div className="grid h-full place-items-center text-xs text-muted-foreground">Loading preview…</div>
+    return <PageLoader label="Loading preview" />
   }
 
   if (state.error) {

apps/desktop/src/app/chat/right-rail/preview-pane.tsx

@@ -83,7 +83,7 @@ function PreviewLoadError({
       body={
         <>
           <a
-            className="pointer-events-auto block cursor-pointer font-mono text-muted-foreground/90 underline decoration-current/20 underline-offset-4 transition-colors hover:text-foreground"
+            className="pointer-events-auto block font-mono text-muted-foreground/90 underline decoration-current/20 underline-offset-4 transition-colors hover:text-foreground"
             href={error.url}
             onClick={event => {
               event.preventDefault()
@@ -608,7 +608,7 @@ export function PreviewPane({
           <div className="pointer-events-none flex min-h-(--titlebar-height) items-center gap-1.5 border-b border-border/60 bg-background px-2 py-1">
             <div className="min-w-0 flex-1">
               <a
-                className="pointer-events-auto inline max-w-full cursor-pointer truncate text-left text-xs font-medium text-foreground underline-offset-4 decoration-current/20 transition-colors hover:text-primary hover:underline"
+                className="pointer-events-auto inline max-w-full truncate text-left text-xs font-medium text-foreground underline-offset-4 decoration-current/20 transition-colors hover:text-primary hover:underline"
                 href={currentUrl}
                 rel="noreferrer"
                 target="_blank"

apps/desktop/src/app/chat/right-rail/preview.tsx

@@ -101,12 +101,17 @@ export function ChatPreviewRail({ onRestartServer, setTitlebarToolGroup }: ChatP
                 // memory. `onMouseDown` swallows the middle-button press so
                 // Chromium doesn't switch into autoscroll mode.
                 onAuxClick={event => {
-                  if (event.button !== 1) return
+                  if (event.button !== 1) {
+                    return
+                  }
+
                   event.preventDefault()
                   closeRightRailTab(tab.id)
                 }}
                 onMouseDown={event => {
-                  if (event.button === 1) event.preventDefault()
+                  if (event.button === 1) {
+                    event.preventDefault()
+                  }
                 }}
               >
                 {active && (

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

@@ -23,6 +23,7 @@ import { Button } from '@/components/ui/button'
 import { Codicon } from '@/components/ui/codicon'
 import { DisclosureCaret } from '@/components/ui/disclosure-caret'
 import { KbdGroup } from '@/components/ui/kbd'
+import { SearchField } from '@/components/ui/search-field'
 import {
   Sidebar,
   SidebarContent,
@@ -34,8 +35,10 @@ import {
 } from '@/components/ui/sidebar'
 import { Skeleton } from '@/components/ui/skeleton'
 import { searchSessions, type SessionInfo, type SessionSearchResult } from '@/hermes'
+import { sessionMatchesSearch } from '@/lib/session-search'
 import { cn } from '@/lib/utils'
 import {
+  $panesFlipped,
   $pinnedSessionIds,
   $sidebarAgentsGrouped,
   $sidebarOpen,
@@ -143,6 +146,7 @@ function searchResultToSession(result: SessionSearchResult): SessionInfo {
     cwd: null,
     ended_at: null,
     id: result.session_id,
+    _lineage_root_id: result.lineage_root ?? null,
     input_tokens: 0,
     is_active: false,
     last_active: ts,
@@ -213,6 +217,7 @@ export function ChatSidebar({
   onNewSessionInWorkspace
 }: ChatSidebarProps) {
   const sidebarOpen = useStore($sidebarOpen)
+  const panesFlipped = useStore($panesFlipped)
   const agentsGrouped = useStore($sidebarAgentsGrouped)
   const pinnedSessionIds = useStore($pinnedSessionIds)
   const pinsOpen = useStore($sidebarPinsOpen)
@@ -226,8 +231,28 @@ export function ChatSidebar({
   const [workspaceOrderIds, setWorkspaceOrderIds] = useState<string[]>([])
   const [searchQuery, setSearchQuery] = useState('')
   const [serverMatches, setServerMatches] = useState<SessionSearchResult[]>([])
+  const [newSessionKbdFlash, setNewSessionKbdFlash] = useState(false)
   const trimmedQuery = searchQuery.trim()
 
+  // Flash the ⌘N hint full-opacity (no transition) for the press, so hitting
+  // the shortcut visibly pings its affordance in the sidebar.
+  useEffect(() => {
+    let timeout: ReturnType<typeof setTimeout> | undefined
+
+    const onShortcut = () => {
+      setNewSessionKbdFlash(true)
+      clearTimeout(timeout)
+      timeout = setTimeout(() => setNewSessionKbdFlash(false), 140)
+    }
+
+    window.addEventListener('hermes:new-session-shortcut', onShortcut)
+
+    return () => {
+      window.removeEventListener('hermes:new-session-shortcut', onShortcut)
+      clearTimeout(timeout)
+    }
+  }, [])
+
   const activeSidebarSessionId = currentView === 'chat' ? selectedSessionId : null
 
   const dndSensors = useSensors(
@@ -306,11 +331,10 @@ export function ChatSidebar({
       return []
     }
 
-    const needle = trimmedQuery.toLowerCase()
     const out = new Map<string, SessionInfo>()
 
     for (const s of sortedSessions) {
-      if (`${s.title ?? ''} ${s.preview ?? ''} ${s.cwd ?? ''}`.toLowerCase().includes(needle)) {
+      if (sessionMatchesSearch(s, trimmedQuery)) {
         out.set(s.id, s)
       }
     }
@@ -405,7 +429,8 @@ export function ChatSidebar({
   return (
     <Sidebar
       className={cn(
-        'relative h-full min-w-0 overflow-hidden border-r border-t-0 border-b-0 border-l-0 text-foreground transition-none',
+        'relative h-full min-w-0 overflow-hidden border-t-0 border-b-0 text-foreground transition-none',
+        panesFlipped ? 'border-l border-r-0' : 'border-r border-l-0',
         sidebarOpen
           ? 'border-(--sidebar-edge-border) bg-(--ui-sidebar-surface-background) opacity-100'
           : 'pointer-events-none border-transparent bg-transparent opacity-0'
@@ -429,7 +454,7 @@ export function ChatSidebar({
                     <SidebarMenuButton
                       aria-disabled={!isInteractive}
                       className={cn(
-                        'flex h-7 w-full cursor-pointer justify-start gap-2 rounded-md border border-transparent px-2 text-left text-[0.8125rem] font-medium text-(--ui-text-secondary) transition-colors duration-100 ease-out hover:bg-(--ui-control-hover-background) hover:text-foreground hover:transition-none',
+                        'flex h-7 w-full justify-start gap-2 rounded-md border border-transparent px-2 text-left text-[0.8125rem] font-medium text-(--ui-text-secondary) transition-colors duration-100 ease-out hover:bg-(--ui-control-hover-background) hover:text-foreground hover:transition-none',
                         active &&
                           'border-(--ui-stroke-tertiary) bg-(--ui-control-active-background) text-foreground shadow-none hover:border-(--ui-stroke-tertiary)!',
                         !isInteractive &&
@@ -444,7 +469,10 @@ export function ChatSidebar({
                         <>
                           <span className="min-w-0 flex-1 truncate max-[46.25rem]:hidden">{item.label}</span>
                           {item.id === 'new-session' && (
-                            <KbdGroup className="ml-auto max-[46.25rem]:hidden" keys={[...NEW_SESSION_KBD]} />
+                            <KbdGroup
+                              className={cn('ml-auto max-[46.25rem]:hidden', newSessionKbdFlash && 'opacity-100!')}
+                              keys={[...NEW_SESSION_KBD]}
+                            />
                           )}
                         </>
                       )}
@@ -457,28 +485,13 @@ export function ChatSidebar({
         </SidebarGroup>
 
         {sidebarOpen && showSessionSections && (
-          <div className="shrink-0 pb-1 pt-1">
-            <div className="flex items-center gap-1.5 rounded-md border border-transparent bg-transparent px-2 transition-colors focus-within:border-(--ui-stroke-tertiary)">
-              <Codicon className="shrink-0 text-(--ui-text-tertiary)" name="search" size="0.75rem" />
-              <input
-                aria-label="Search sessions"
-                className="h-6 min-w-0 flex-1 bg-transparent text-[0.8125rem] text-foreground placeholder:text-(--ui-text-tertiary) focus:outline-none"
-                onChange={event => setSearchQuery(event.target.value)}
-                placeholder="Search sessions…"
-                type="text"
-                value={searchQuery}
-              />
-              {searchQuery && (
-                <button
-                  aria-label="Clear search"
-                  className="grid size-4 shrink-0 cursor-pointer place-items-center rounded-sm text-(--ui-text-tertiary) hover:bg-(--ui-control-active-background) hover:text-foreground"
-                  onClick={() => setSearchQuery('')}
-                  type="button"
-                >
-                  <Codicon name="close" size="0.75rem" />
-                </button>
-              )}
-            </div>
+          <div className="shrink-0 px-2 pb-1 pt-1">
+            <SearchField
+              aria-label="Search sessions"
+              onChange={setSearchQuery}
+              placeholder="Search sessions…"
+              value={searchQuery}
+            />
           </div>
         )}
 
@@ -553,7 +566,7 @@ export function ChatSidebar({
                 <Button
                   aria-label={agentsGrouped ? 'Show sessions as a single list' : 'Group sessions by workspace'}
                   className={cn(
-                    'cursor-pointer text-(--ui-text-tertiary) opacity-70 hover:bg-(--ui-control-hover-background) hover:text-foreground hover:opacity-100 focus-visible:opacity-100',
+                    'text-(--ui-text-tertiary) opacity-70 hover:bg-(--ui-control-hover-background) hover:text-foreground hover:opacity-100 focus-visible:opacity-100',
                     agentsGrouped && 'bg-(--ui-control-active-background) text-foreground opacity-100'
                   )}
                   onClick={event => {
@@ -603,7 +616,7 @@ function SidebarSectionHeader({ label, open, onToggle, action, meta }: SidebarSe
   return (
     <div className="group/section flex shrink-0 items-center justify-between pb-1 pt-1.5">
       <button
-        className="group/section-label flex w-fit cursor-pointer items-center gap-1 bg-transparent text-left leading-none"
+        className="group/section-label flex w-fit items-center gap-1 bg-transparent text-left leading-none"
         onClick={onToggle}
         type="button"
       >
@@ -644,7 +657,7 @@ function SidebarPinnedEmptyState() {
       <span className="grid w-3.5 shrink-0 place-items-center text-(--ui-text-quaternary)">
         <Codicon name="pin" size="0.75rem" />
       </span>
-      <span>Shift-click a chat to pin · drag to reorder</span>
+      <span>Shift-click a chat to pin</span>
     </div>
   )
 }
@@ -847,7 +860,7 @@ function SidebarWorkspaceGroup({
     <div className={cn('grid gap-px', dragging && 'z-10 opacity-60', className)} ref={ref} style={style} {...rest}>
       <div className="group/workspace flex min-h-6 items-center gap-1 px-2 pt-1 text-[0.6875rem] font-medium text-(--ui-text-tertiary)">
         <button
-          className="flex min-w-0 cursor-pointer items-center gap-1 bg-transparent text-left hover:text-(--ui-text-secondary)"
+          className="flex min-w-0 items-center gap-1 bg-transparent text-left hover:text-(--ui-text-secondary)"
           onClick={() => setOpen(value => !value)}
           title={group.path ?? undefined}
           type="button"
@@ -862,7 +875,7 @@ function SidebarWorkspaceGroup({
         {onNewSession && (
           <button
             aria-label={`New session in ${group.label}`}
-            className="grid size-4 shrink-0 cursor-pointer place-items-center rounded-sm bg-transparent text-(--ui-text-quaternary) opacity-0 transition-opacity hover:bg-(--ui-control-hover-background) hover:text-foreground group-hover/workspace:opacity-100"
+            className="grid size-4 shrink-0 place-items-center rounded-sm bg-transparent text-(--ui-text-quaternary) opacity-0 transition-opacity hover:bg-(--ui-control-hover-background) hover:text-foreground group-hover/workspace:opacity-100"
             onClick={() => onNewSession(group.path)}
             title={`New session in ${group.label}`}
             type="button"
@@ -894,7 +907,7 @@ function SidebarWorkspaceGroup({
           {hiddenCount > 0 && (
             <button
               aria-label={`Show ${nextCount} more in ${group.label}`}
-              className="ml-auto grid size-5 cursor-pointer place-items-center rounded-sm bg-transparent text-(--ui-text-tertiary) transition-colors hover:bg-(--ui-control-hover-background) hover:text-foreground"
+              className="ml-auto grid size-5 place-items-center rounded-sm bg-transparent text-(--ui-text-tertiary) transition-colors hover:bg-(--ui-control-hover-background) hover:text-foreground"
               onClick={() => setVisibleCount(count => count + WORKSPACE_PAGE)}
               title={`Show ${nextCount} more in ${group.label}`}
               type="button"
@@ -948,7 +961,7 @@ function SidebarLoadMoreRow({ loading, onClick, step }: SidebarLoadMoreRowProps)
 
   return (
     <button
-      className="flex min-h-5 cursor-pointer items-center gap-1 self-start bg-transparent pl-2 text-left text-[0.6875rem] text-(--ui-text-tertiary) transition-colors duration-100 ease-out hover:text-foreground hover:transition-none disabled:cursor-default disabled:opacity-60 disabled:hover:text-(--ui-text-tertiary)"
+      className="flex min-h-5 items-center gap-1 self-start bg-transparent pl-2 text-left text-[0.6875rem] text-(--ui-text-tertiary) transition-colors duration-100 ease-out hover:text-foreground hover:transition-none disabled:cursor-default disabled:opacity-60 disabled:hover:text-(--ui-text-tertiary)"
       disabled={loading}
       onClick={onClick}
       type="button"

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

@@ -1,3 +1,4 @@
+import { useStore } from '@nanostores/react'
 import type * as React from 'react'
 
 import { Button } from '@/components/ui/button'
@@ -6,6 +7,7 @@ import type { SessionInfo } from '@/hermes'
 import { sessionTitle } from '@/lib/chat-runtime'
 import { triggerHaptic } from '@/lib/haptics'
 import { cn } from '@/lib/utils'
+import { $attentionSessionIds } from '@/store/session'
 
 import { SessionActionsMenu, SessionContextMenu } from './session-actions-menu'
 
@@ -61,6 +63,10 @@ export function SidebarSessionRow({
   const title = sessionTitle(session)
   const age = formatAge(session.last_active || session.started_at)
   const handleLabel = `Reorder ${title}`
+  // Subscribe per-row (the leaf) instead of drilling a set through the list —
+  // the atom is tiny and rarely non-empty. True when a clarify prompt in this
+  // session is waiting on the user.
+  const needsInput = useStore($attentionSessionIds).includes(session.id)
 
   return (
     <SessionContextMenu
@@ -84,9 +90,9 @@ export function SidebarSessionRow({
         style={style}
         {...rest}
       >
-        {isWorking && <span aria-hidden="true" className="arc-border" />}
+        {isWorking && !needsInput && <span aria-hidden="true" className="arc-border" />}
         <button
-          className="z-0 flex min-w-0 cursor-pointer items-center gap-1.5 bg-transparent py-0.5 pl-2 pr-1 text-left group-hover:pr-12"
+          className="z-0 flex min-w-0 items-center gap-1.5 bg-transparent py-0.5 pl-2 pr-1 text-left group-hover:pr-12"
           onClick={event => {
             if (event.shiftKey) {
               event.preventDefault()
@@ -114,16 +120,25 @@ export function SidebarSessionRow({
             <span
               {...dragHandleProps}
               aria-label={handleLabel}
-              className="relative -my-0.5 grid w-4 shrink-0 cursor-grab touch-none place-items-center self-stretch overflow-hidden active:cursor-grabbing"
+              className={cn(
+                // Scope the dot↔grabber swap to a local group so the grabber
+                // only reveals when hovering/focusing the handle itself, not
+                // anywhere on the row.
+                'group/handle relative -my-0.5 grid w-4 shrink-0 cursor-grab touch-none place-items-center self-stretch overflow-hidden active:cursor-grabbing',
+                // The quest-glow box-shadow extends past the dot; let it bleed
+                // out instead of being clipped by this handle's overflow-hidden.
+                needsInput && 'overflow-visible'
+              )}
               onClick={event => event.stopPropagation()}
             >
               <SidebarRowDot
-                className="transition-opacity group-hover:opacity-0 group-focus-within:opacity-0"
+                className="transition-opacity group-hover/handle:opacity-0 group-focus-within/handle:opacity-0"
                 isWorking={isWorking}
+                needsInput={needsInput}
               />
               <Codicon
                 className={cn(
-                  'absolute text-(--ui-text-quaternary) opacity-0 transition-opacity group-hover:opacity-80 group-focus-within:opacity-80 hover:text-(--ui-text-secondary)',
+                  'absolute text-(--ui-text-quaternary) opacity-0 transition-opacity group-hover/handle:opacity-80 group-focus-within/handle:opacity-80 hover:text-(--ui-text-secondary)',
                   dragging && 'text-(--ui-text-secondary) opacity-100'
                 )}
                 name="grabber"
@@ -131,8 +146,13 @@ export function SidebarSessionRow({
               />
             </span>
           ) : (
-            <span className="grid w-3.5 shrink-0 place-items-center overflow-hidden">
-              <SidebarRowDot isWorking={isWorking} />
+            <span
+              className={cn(
+                'grid w-3.5 shrink-0 place-items-center',
+                needsInput ? 'overflow-visible' : 'overflow-hidden'
+              )}
+            >
+              <SidebarRowDot isWorking={isWorking} needsInput={needsInput} />
             </span>
           )}
           <span className="truncate text-[0.8125rem] font-normal text-(--ui-text-secondary) group-hover:text-foreground group-data-[working=true]:text-foreground/90">
@@ -155,7 +175,7 @@ export function SidebarSessionRow({
           >
             <Button
               aria-label={`Actions for ${title}`}
-              className="size-5 rounded-md bg-transparent text-transparent transition-colors duration-100 hover:bg-(--ui-control-active-background) hover:text-foreground focus-visible:bg-(--ui-control-active-background) focus-visible:text-foreground focus-visible:ring-0 data-[state=open]:bg-(--ui-control-active-background) data-[state=open]:text-foreground group-hover:text-(--ui-text-tertiary) [&_svg]:size-3.5!"
+              className="size-5 rounded-[4px] bg-transparent text-transparent transition-colors duration-100 hover:bg-(--ui-control-active-background) hover:text-foreground focus-visible:bg-(--ui-control-active-background) focus-visible:text-foreground focus-visible:ring-0 data-[state=open]:bg-(--ui-control-active-background) data-[state=open]:text-foreground group-hover:text-(--ui-text-tertiary) [&_svg]:size-3.5!"
               size="icon"
               title="Session actions"
               variant="ghost"
@@ -169,7 +189,30 @@ export function SidebarSessionRow({
   )
 }
 
-function SidebarRowDot({ isWorking, className }: { isWorking: boolean; className?: string }) {
+function SidebarRowDot({
+  isWorking,
+  needsInput = false,
+  className
+}: {
+  isWorking: boolean
+  needsInput?: boolean
+  className?: string
+}) {
+  // "Needs input" wins over "working": a clarify-blocked session is technically
+  // still running, but the actionable state is that it's waiting on the user.
+  // Amber + steady (no ping) reads as "your turn", distinct from the accent
+  // pulse of an active turn.
+  if (needsInput) {
+    return (
+      <span
+        aria-label="Needs your input"
+        className={cn('quest-glow relative size-1.5 rounded-full bg-amber-500', className)}
+        role="status"
+        title="Waiting for your answer"
+      />
+    )
+  }
+
   return (
     <span
       aria-label={isWorking ? 'Session running' : undefined}

apps/desktop/src/app/command-palette/index.tsx

@@ -0,0 +1,487 @@
+import { useStore } from '@nanostores/react'
+import { useQuery } from '@tanstack/react-query'
+import { Dialog as DialogPrimitive } from 'radix-ui'
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+
+import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList } from '@/components/ui/command'
+import { getHermesConfigRecord, listSessions } from '@/hermes'
+import { sessionTitle } from '@/lib/chat-runtime'
+import {
+  Activity,
+  Archive,
+  BarChart3,
+  Check,
+  ChevronLeft,
+  ChevronRight,
+  Clock,
+  Cpu,
+  Globe,
+  type IconComponent,
+  Info,
+  KeyRound,
+  MessageCircle,
+  Monitor,
+  Moon,
+  Package,
+  Palette,
+  Plus,
+  Settings,
+  Settings2,
+  Sun,
+  Users,
+  Wrench,
+  Zap
+} from '@/lib/icons'
+import { cn } from '@/lib/utils'
+import { $commandPaletteOpen, closeCommandPalette, setCommandPaletteOpen } from '@/store/command-palette'
+import { type ThemeMode, useTheme } from '@/themes/context'
+
+import {
+  AGENTS_ROUTE,
+  ARTIFACTS_ROUTE,
+  COMMAND_CENTER_ROUTE,
+  CRON_ROUTE,
+  MESSAGING_ROUTE,
+  NEW_CHAT_ROUTE,
+  PROFILES_ROUTE,
+  sessionRoute,
+  SETTINGS_ROUTE,
+  SKILLS_ROUTE
+} from '../routes'
+import { FIELD_LABELS, SECTIONS } from '../settings/constants'
+import { prettyName } from '../settings/helpers'
+
+interface PaletteItem {
+  active?: boolean
+  icon: IconComponent
+  id: string
+  /** Keep the palette open after running (live-preview pickers like theme/mode). */
+  keepOpen?: boolean
+  keywords?: string[]
+  label: string
+  /** Action to run when selected. Mutually exclusive with `to`. */
+  run?: () => void
+  /** Open a nested palette page (VS Code-style "choose X → options"). */
+  to?: string
+}
+
+interface PaletteGroup {
+  heading: string
+  items: PaletteItem[]
+}
+
+/** A nested page reachable from a root item via `to`. */
+interface PalettePage {
+  groups: PaletteGroup[]
+  placeholder: string
+  title: string
+}
+
+interface SessionEntry {
+  id: string
+  preview?: string
+  title: string
+}
+
+type SessionRow = Awaited<ReturnType<typeof listSessions>>['sessions'][number]
+
+const toSessionEntry = (session: SessionRow): SessionEntry => ({
+  id: session.id,
+  preview: session.preview ?? undefined,
+  title: sessionTitle(session)
+})
+
+const NON_CONFIG_SETTINGS: ReadonlyArray<{ icon: IconComponent; keywords?: string[]; label: string; tab: string }> = [
+  {
+    icon: Zap,
+    keywords: ['accounts', 'sign in', 'oauth', 'login', 'subscription', 'models', 'anthropic', 'openai'],
+    label: 'Providers',
+    tab: 'providers&pview=accounts'
+  },
+  {
+    icon: KeyRound,
+    keywords: ['providers', 'api key', 'keys', 'secrets', 'tokens'],
+    label: 'Provider API keys',
+    tab: 'providers&pview=keys'
+  },
+  { icon: Globe, keywords: ['connection', 'messaging'], label: 'Gateway', tab: 'gateway' },
+  {
+    icon: KeyRound,
+    keywords: ['api', 'secrets', 'tokens', 'credentials', 'browser', 'search'],
+    label: 'Tools & Keys',
+    tab: 'keys&kview=tools'
+  },
+  {
+    icon: Settings2,
+    keywords: ['gateway', 'proxy', 'server', 'webhook', 'env'],
+    label: 'Tools & Keys settings',
+    tab: 'keys&kview=settings'
+  },
+  { icon: Wrench, keywords: ['servers', 'tools'], label: 'MCP', tab: 'mcp' },
+  { icon: Archive, keywords: ['history', 'archived'], label: 'Archived Chats', tab: 'sessions' },
+  { icon: Info, keywords: ['version', 'about'], label: 'About', tab: 'about' }
+]
+
+const THEME_MODES: ReadonlyArray<{ icon: IconComponent; label: string; mode: ThemeMode }> = [
+  { icon: Sun, label: 'Light', mode: 'light' },
+  { icon: Moon, label: 'Dark', mode: 'dark' },
+  { icon: Monitor, label: 'System', mode: 'system' }
+]
+
+function fieldLabel(key: string): string {
+  return FIELD_LABELS[key] ?? prettyName(key.split('.').pop() ?? key)
+}
+
+export function CommandPalette() {
+  const open = useStore($commandPaletteOpen)
+  const navigate = useNavigate()
+  const { availableThemes, mode, resolvedMode, setMode, setTheme, themeName } = useTheme()
+  const [search, setSearch] = useState('')
+  const [page, setPage] = useState<string | null>(null)
+
+  // Server-backed sources for the type-to-search groups, fetched lazily while
+  // the palette is open. react-query handles caching/dedup/staleness.
+  const configQuery = useQuery({
+    queryKey: ['command-palette', 'config'],
+    queryFn: getHermesConfigRecord,
+    enabled: open
+  })
+
+  const sessionsQuery = useQuery({
+    queryKey: ['command-palette', 'sessions'],
+    queryFn: () => listSessions(200, 1, 'exclude'),
+    enabled: open
+  })
+
+  const archivedQuery = useQuery({
+    queryKey: ['command-palette', 'archived'],
+    queryFn: () => listSessions(200, 0, 'only'),
+    enabled: open
+  })
+
+  const mcpServers = useMemo(() => {
+    const raw = configQuery.data?.mcp_servers
+
+    return raw && typeof raw === 'object' && !Array.isArray(raw)
+      ? Object.keys(raw as Record<string, unknown>).sort()
+      : []
+  }, [configQuery.data])
+
+  const sessions = useMemo(() => (sessionsQuery.data?.sessions ?? []).map(toSessionEntry), [sessionsQuery.data])
+  const archivedSessions = useMemo(() => (archivedQuery.data?.sessions ?? []).map(toSessionEntry), [archivedQuery.data])
+
+  // Reset the query/sub-page on close so it reopens clean.
+  useEffect(() => {
+    if (!open) {
+      setSearch('')
+      setPage(null)
+    }
+  }, [open])
+
+  const go = useCallback((path: string) => () => navigate(path), [navigate])
+
+  const baseGroups = useMemo<PaletteGroup[]>(() => {
+    const settingsTab = (tab: string) => `${SETTINGS_ROUTE}?tab=${tab}`
+
+    return [
+      {
+        heading: 'Go to',
+        items: [
+          { icon: Plus, id: 'nav-new', keywords: ['chat', 'create'], label: 'New session', run: go(NEW_CHAT_ROUTE) },
+          { icon: Settings, id: 'nav-settings', label: 'Settings', run: go(SETTINGS_ROUTE) },
+          {
+            icon: Wrench,
+            id: 'nav-skills',
+            keywords: ['tools', 'toolsets'],
+            label: 'Skills & Tools',
+            run: go(SKILLS_ROUTE)
+          },
+          { icon: MessageCircle, id: 'nav-messaging', label: 'Messaging', run: go(MESSAGING_ROUTE) },
+          { icon: Package, id: 'nav-artifacts', label: 'Artifacts', run: go(ARTIFACTS_ROUTE) },
+          { icon: Clock, id: 'nav-cron', keywords: ['schedule', 'jobs'], label: 'Cron', run: go(CRON_ROUTE) },
+          { icon: Users, id: 'nav-profiles', label: 'Profiles', run: go(PROFILES_ROUTE) },
+          { icon: Cpu, id: 'nav-agents', label: 'Agents', run: go(AGENTS_ROUTE) }
+        ]
+      },
+      {
+        heading: 'Command Center',
+        items: [
+          {
+            icon: Archive,
+            id: 'cc-sessions',
+            keywords: ['command center', 'sessions', 'pin'],
+            label: 'Sessions',
+            run: go(`${COMMAND_CENTER_ROUTE}?section=sessions`)
+          },
+          {
+            icon: Activity,
+            id: 'cc-system',
+            keywords: ['command center', 'system', 'status', 'logs'],
+            label: 'System',
+            run: go(`${COMMAND_CENTER_ROUTE}?section=system`)
+          },
+          {
+            icon: BarChart3,
+            id: 'cc-usage',
+            keywords: ['command center', 'usage', 'tokens', 'cost'],
+            label: 'Usage',
+            run: go(`${COMMAND_CENTER_ROUTE}?section=usage`)
+          }
+        ]
+      },
+      {
+        // Declared before Settings: cmdk keeps group order, so this keeps the
+        // theme/mode pickers on top for "theme"/"color" queries instead of
+        // buried under a fuzzy Settings match.
+        heading: 'Appearance',
+        items: [
+          {
+            icon: Palette,
+            id: 'appearance-theme',
+            keywords: ['theme', 'appearance', 'color', 'palette', 'skin', 'dark', 'light', 'look'],
+            label: 'Change theme…',
+            to: 'theme'
+          },
+          {
+            icon: Sun,
+            id: 'appearance-mode',
+            keywords: ['appearance', 'color mode', 'brightness', 'dark', 'light', 'system'],
+            label: 'Change color mode…',
+            to: 'color-mode'
+          }
+        ]
+      },
+      {
+        heading: 'Settings',
+        items: [
+          ...SECTIONS.map(section => ({
+            icon: section.icon,
+            id: `set-config-${section.id}`,
+            keywords: ['settings', section.label],
+            label: section.label,
+            run: go(settingsTab(`config:${section.id}`))
+          })),
+          ...NON_CONFIG_SETTINGS.map(entry => ({
+            icon: entry.icon,
+            id: `set-${entry.tab}`,
+            keywords: ['settings', ...(entry.keywords ?? [])],
+            label: entry.label,
+            run: go(settingsTab(entry.tab))
+          }))
+        ]
+      }
+    ]
+  }, [go])
+
+  // The long, granular lists (settings fields, API keys, MCP servers, archived
+  // chats) only surface once the user types — otherwise they'd bury the
+  // navigation entries on an empty palette.
+  const searchGroups = useMemo<PaletteGroup[]>(() => {
+    if (!search.trim()) {
+      return []
+    }
+
+    const result: PaletteGroup[] = []
+
+    if (sessions.length > 0) {
+      result.push({
+        heading: 'Sessions',
+        items: sessions.map(session => ({
+          icon: MessageCircle,
+          id: `session-${session.id}`,
+          keywords: ['chat', 'session', ...(session.preview ? [session.preview] : [])],
+          label: session.title,
+          run: go(sessionRoute(session.id))
+        }))
+      })
+    }
+
+    const fieldItems = SECTIONS.flatMap(section =>
+      section.keys.map(key => ({
+        icon: section.icon,
+        id: `field-${key}`,
+        keywords: ['settings', key, section.label],
+        label: `${section.label}: ${fieldLabel(key)}`,
+        run: go(`${SETTINGS_ROUTE}?tab=config:${section.id}&field=${encodeURIComponent(key)}`)
+      }))
+    )
+
+    result.push({ heading: 'Settings fields', items: fieldItems })
+
+    if (mcpServers.length > 0) {
+      result.push({
+        heading: 'MCP servers',
+        items: mcpServers.map(name => ({
+          icon: Wrench,
+          id: `mcp-${name}`,
+          keywords: ['mcp', 'server', 'tool'],
+          label: name,
+          run: go(`${SETTINGS_ROUTE}?tab=mcp&server=${encodeURIComponent(name)}`)
+        }))
+      })
+    }
+
+    if (archivedSessions.length > 0) {
+      result.push({
+        heading: 'Archived chats',
+        items: archivedSessions.map(session => ({
+          icon: Archive,
+          id: `archived-${session.id}`,
+          keywords: ['archived', 'chat', 'session', ...(session.preview ? [session.preview] : [])],
+          label: session.title,
+          run: go(`${SETTINGS_ROUTE}?tab=sessions&session=${encodeURIComponent(session.id)}`)
+        }))
+      })
+    }
+
+    return result
+  }, [archivedSessions, go, mcpServers, search, sessions])
+
+  const groups = useMemo(() => [...baseGroups, ...searchGroups], [baseGroups, searchGroups])
+
+  // Nested palette pages (VS Code-style submenus). Reusable: add an entry here
+  // and point a root item at it via `to`.
+  const subPages = useMemo<Record<string, PalettePage>>(
+    () => ({
+      theme: {
+        title: 'Theme',
+        placeholder: 'Choose a theme…',
+        // Skins aren't inherently light/dark — the same skin renders in either
+        // mode. Group by appearance so picking an entry sets skin + mode at
+        // once, and keep the palette open so each pick previews live.
+        groups: (['light', 'dark'] as const).map(groupMode => ({
+          heading: groupMode === 'light' ? 'Light' : 'Dark',
+          items: availableThemes.map(theme => ({
+            active: themeName === theme.name && resolvedMode === groupMode,
+            icon: groupMode === 'light' ? Sun : Moon,
+            id: `theme-${theme.name}-${groupMode}`,
+            keepOpen: true,
+            keywords: ['theme', 'appearance', 'palette', groupMode, theme.label, theme.description ?? ''],
+            label: theme.label,
+            run: () => {
+              setTheme(theme.name)
+              setMode(groupMode)
+            }
+          }))
+        }))
+      },
+      'color-mode': {
+        title: 'Color mode',
+        placeholder: 'Choose color mode…',
+        groups: [
+          {
+            heading: 'Color mode',
+            items: THEME_MODES.map(entry => ({
+              active: mode === entry.mode,
+              icon: entry.icon,
+              id: `mode-${entry.mode}`,
+              keepOpen: true,
+              keywords: ['appearance', 'brightness', entry.label],
+              label: entry.label,
+              run: () => setMode(entry.mode)
+            }))
+          }
+        ]
+      }
+    }),
+    [availableThemes, mode, resolvedMode, setMode, setTheme, themeName]
+  )
+
+  const activePage = page ? subPages[page] : null
+  const visibleGroups = activePage ? activePage.groups : groups
+  const placeholder = activePage ? activePage.placeholder : 'Search commands and settings...'
+
+  const handleSelect = (item: PaletteItem) => {
+    if (item.to) {
+      setPage(item.to)
+      setSearch('')
+
+      return
+    }
+
+    item.run?.()
+
+    if (!item.keepOpen) {
+      closeCommandPalette()
+    }
+  }
+
+  return (
+    <DialogPrimitive.Root onOpenChange={setCommandPaletteOpen} open={open}>
+      <DialogPrimitive.Portal>
+        <DialogPrimitive.Overlay className="fixed inset-0 z-[200] bg-black/15 backdrop-blur-[1px] data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0" />
+        <DialogPrimitive.Content
+          aria-describedby={undefined}
+          className="fixed left-1/2 top-[14vh] z-[210] w-[min(40rem,calc(100vw-2rem))] -translate-x-1/2 overflow-hidden rounded-xl border border-(--ui-stroke-secondary) bg-(--ui-chat-bubble-background) shadow-lg duration-150 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:slide-in-from-top-2 data-[state=open]:zoom-in-95"
+        >
+          <DialogPrimitive.Title className="sr-only">Command palette</DialogPrimitive.Title>
+          <Command className="bg-transparent" loop>
+            {activePage && (
+              <button
+                className="flex w-full items-center gap-1.5 border-b border-border px-3 py-1.5 text-left text-xs text-muted-foreground transition-colors hover:text-foreground"
+                onClick={() => setPage(null)}
+                type="button"
+              >
+                <ChevronLeft className="size-3.5" />
+                <span>Back</span>
+                <span className="text-muted-foreground/50">/</span>
+                <span className="font-medium text-foreground">{activePage.title}</span>
+              </button>
+            )}
+            <CommandInput
+              onKeyDown={event => {
+                if (!activePage) {
+                  return
+                }
+
+                // In a submenu: Esc and empty-input Backspace step back out
+                // instead of closing the whole palette.
+                if (event.key === 'Escape' || (event.key === 'Backspace' && search === '')) {
+                  event.preventDefault()
+                  event.stopPropagation()
+                  setPage(null)
+                }
+              }}
+              onValueChange={setSearch}
+              placeholder={placeholder}
+              value={search}
+            />
+            <CommandList className="max-h-[min(24rem,60vh)]">
+              <CommandEmpty>No results found.</CommandEmpty>
+              {visibleGroups.map(group => (
+                <CommandGroup
+                  className="**:[[cmdk-group-heading]]:uppercase **:[[cmdk-group-heading]]:tracking-wider **:[[cmdk-group-heading]]:text-[0.6875rem] **:[[cmdk-group-heading]]:text-muted-foreground/70"
+                  heading={group.heading}
+                  key={group.heading}
+                >
+                  {group.items.map(item => {
+                    const Icon = item.icon
+
+                    return (
+                      <CommandItem
+                        className="gap-2.5"
+                        key={item.id}
+                        keywords={item.keywords}
+                        onSelect={() => handleSelect(item)}
+                        value={`${item.label} ${item.keywords?.join(' ') ?? ''} ${item.id}`}
+                      >
+                        <Icon className="size-4 shrink-0 text-muted-foreground" />
+                        <span className="truncate">{item.label}</span>
+                        {item.to ? (
+                          <ChevronRight className="ml-auto size-4 shrink-0 text-muted-foreground/70" />
+                        ) : (
+                          <Check className={cn('ml-auto size-4 text-foreground', !item.active && 'invisible')} />
+                        )}
+                      </CommandItem>
+                    )
+                  })}
+                </CommandGroup>
+              ))}
+            </CommandList>
+          </Command>
+        </DialogPrimitive.Content>
+      </DialogPrimitive.Portal>
+    </DialogPrimitive.Root>
+  )
+}

apps/desktop/src/app/cron/cron-job-actions-menu.tsx

@@ -0,0 +1,108 @@
+import type * as React from 'react'
+
+import { Button } from '@/components/ui/button'
+import { Codicon } from '@/components/ui/codicon'
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '@/components/ui/dropdown-menu'
+import { triggerHaptic } from '@/lib/haptics'
+
+interface CronJobActions {
+  busy?: boolean
+  isPaused: boolean
+  title: string
+  onDelete: () => void
+  onEdit: () => void
+  onPauseResume: () => void
+  onTrigger: () => void
+}
+
+interface CronJobActionsMenuProps
+  extends CronJobActions, Pick<React.ComponentProps<typeof DropdownMenuContent>, 'align' | 'sideOffset'> {
+  children: React.ReactNode
+}
+
+export function CronJobActionsMenu({
+  align = 'end',
+  busy = false,
+  children,
+  isPaused,
+  onDelete,
+  onEdit,
+  onPauseResume,
+  onTrigger,
+  sideOffset = 6,
+  title
+}: CronJobActionsMenuProps) {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>{children}</DropdownMenuTrigger>
+      <DropdownMenuContent
+        align={align}
+        aria-label={`Actions for ${title}`}
+        className="w-44"
+        sideOffset={sideOffset}
+      >
+        <DropdownMenuItem
+          disabled={busy}
+          onSelect={() => {
+            triggerHaptic('selection')
+            onPauseResume()
+          }}
+        >
+          <Codicon name={isPaused ? 'play' : 'debug-pause'} size="0.875rem" />
+          <span>{isPaused ? 'Resume' : 'Pause'}</span>
+        </DropdownMenuItem>
+
+        <DropdownMenuItem
+          disabled={busy}
+          onSelect={() => {
+            triggerHaptic('selection')
+            onTrigger()
+          }}
+        >
+          <Codicon name="zap" size="0.875rem" />
+          <span>Trigger now</span>
+        </DropdownMenuItem>
+
+        <DropdownMenuItem
+          onSelect={() => {
+            triggerHaptic('selection')
+            onEdit()
+          }}
+        >
+          <Codicon name="edit" size="0.875rem" />
+          <span>Edit</span>
+        </DropdownMenuItem>
+
+        <DropdownMenuItem
+          onSelect={() => {
+            triggerHaptic('warning')
+            onDelete()
+          }}
+          variant="destructive"
+        >
+          <Codicon name="trash" size="0.875rem" />
+          <span>Delete</span>
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+interface CronJobActionsTriggerProps extends Omit<React.ComponentProps<typeof Button>, 'size' | 'variant'> {
+  title: string
+}
+
+export function CronJobActionsTrigger({ className, title, ...props }: CronJobActionsTriggerProps) {
+  return (
+    <Button
+      aria-label={`Actions for ${title}`}
+      className={className}
+      size="icon-sm"
+      title="Cron job actions"
+      variant="ghost"
+      {...props}
+    >
+      <Codicon className="text-muted-foreground" name="ellipsis" size="0.875rem" />
+    </Button>
+  )
+}

apps/desktop/src/app/cron/index.tsx

@@ -1,7 +1,7 @@
-import type * as React from 'react'
 import { useCallback, useEffect, useMemo, useState } from 'react'
 
 import { PageLoader } from '@/components/page-loader'
+import { Badge, type BadgeProps } from '@/components/ui/badge'
 import { Button } from '@/components/ui/button'
 import { Codicon } from '@/components/ui/codicon'
 import {
@@ -13,6 +13,7 @@ import {
   DialogTitle
 } from '@/components/ui/dialog'
 import { Input } from '@/components/ui/input'
+import { SearchField } from '@/components/ui/search-field'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
 import { Textarea } from '@/components/ui/textarea'
 import {
@@ -25,12 +26,13 @@ import {
   triggerCronJob,
   updateCronJob
 } from '@/hermes'
-import { AlertTriangle, Clock, Pause, Pencil, Play, Trash2, Zap } from '@/lib/icons'
-import { cn } from '@/lib/utils'
+import { AlertTriangle, Clock } from '@/lib/icons'
 import { notify, notifyError } from '@/store/notifications'
 
-import { PageSearchShell } from '../page-search-shell'
-import type { SetStatusbarItemGroup } from '../shell/statusbar-controls'
+import { useRefreshHotkey } from '../hooks/use-refresh-hotkey'
+import { OverlayView } from '../overlays/overlay-view'
+
+import { CronJobActionsMenu, CronJobActionsTrigger } from './cron-job-actions-menu'
 
 const DEFAULT_DELIVER = 'local'
 
@@ -86,23 +88,16 @@ const SCHEDULE_OPTIONS: ReadonlyArray<ScheduleOption> = [
   }
 ]
 
-const STATE_TONE: Record<string, 'good' | 'muted' | 'warn' | 'bad'> = {
-  enabled: 'good',
-  scheduled: 'good',
-  running: 'good',
+const STATE_VARIANT: Record<string, BadgeProps['variant']> = {
+  enabled: 'default',
+  scheduled: 'default',
+  running: 'default',
   paused: 'warn',
   disabled: 'muted',
-  error: 'bad',
+  error: 'destructive',
   completed: 'muted'
 }
 
-const PILL_TONE: Record<'good' | 'muted' | 'warn' | 'bad', string> = {
-  good: 'bg-primary/10 text-primary',
-  muted: 'bg-muted text-muted-foreground',
-  warn: 'bg-amber-500/10 text-amber-600 dark:text-amber-300',
-  bad: 'bg-destructive/10 text-destructive'
-}
-
 const asText = (value: unknown): string => (typeof value === 'string' ? value : '')
 
 const truncate = (value: string, max = 80): string => (value.length > max ? `${value.slice(0, max)}…` : value)
@@ -305,14 +300,13 @@ function matchesQuery(job: CronJob, q: string): boolean {
   )
 }
 
-interface CronViewProps extends React.ComponentProps<'section'> {
-  setStatusbarItemGroup?: SetStatusbarItemGroup
+interface CronViewProps {
+  onClose: () => void
 }
 
-export function CronView({ setStatusbarItemGroup: _setStatusbarItemGroup, ...props }: CronViewProps) {
+export function CronView({ onClose }: CronViewProps) {
   const [jobs, setJobs] = useState<CronJob[] | null>(null)
   const [query, setQuery] = useState('')
-  const [refreshing, setRefreshing] = useState(false)
   const [busyJobId, setBusyJobId] = useState<null | string>(null)
 
   const [editor, setEditor] = useState<EditorState>({ mode: 'closed' })
@@ -320,18 +314,16 @@ export function CronView({ setStatusbarItemGroup: _setStatusbarItemGroup, ...pro
   const [deleting, setDeleting] = useState(false)
 
   const refresh = useCallback(async () => {
-    setRefreshing(true)
-
     try {
       const result = await getCronJobs()
       setJobs(result)
     } catch (err) {
       notifyError(err, 'Failed to load cron jobs')
-    } finally {
-      setRefreshing(false)
     }
   }, [])
 
+  useRefreshHotkey(refresh)
+
   useEffect(() => {
     void refresh()
   }, [refresh])
@@ -426,73 +418,66 @@ export function CronView({ setStatusbarItemGroup: _setStatusbarItemGroup, ...pro
   }
 
   return (
-    <PageSearchShell
-      {...props}
-      onSearchChange={setQuery}
-      searchPlaceholder="Search cron jobs..."
-      searchTrailingAction={
-        <Button
-          aria-label={refreshing ? 'Refreshing cron jobs' : 'Refresh cron jobs'}
-          className="text-(--ui-text-tertiary) hover:bg-(--chrome-action-hover) hover:text-foreground"
-          disabled={refreshing}
-          onClick={() => void refresh()}
-          size="icon-xs"
-          title={refreshing ? 'Refreshing cron jobs' : 'Refresh cron jobs'}
-          type="button"
-          variant="ghost"
-        >
-          <Codicon name="refresh" size="0.875rem" spinning={refreshing} />
-        </Button>
-      }
-      searchValue={query}
-    >
-      {!jobs ? (
-        <PageLoader label="Loading cron jobs..." />
-      ) : visibleJobs.length === 0 ? (
-        // Empty state owns the primary "create" CTA — we used to also have
-        // one in the filters bar but it was redundant. Only show the button
-        // when there are zero jobs total; the search-empty case ("No
-        // matches") just asks the user to broaden their query.
-        <EmptyState
-          actionLabel={totalCount === 0 ? 'Create first cron' : undefined}
-          description={
-            totalCount === 0
-              ? 'Schedule a prompt to run on a cron expression. Hermes will run it and deliver results to the destination you pick.'
-              : 'Try a broader search query.'
-          }
-          onAction={totalCount === 0 ? () => setEditor({ mode: 'create' }) : undefined}
-          title={totalCount === 0 ? 'No scheduled jobs yet' : 'No matches'}
-        />
-      ) : (
-        <div className="h-full overflow-y-auto px-4 py-3">
-          {/* Inline header replaces the old top-bar "New cron" button. We
-              still need a single, always-visible affordance to add a job
-              when the list is non-empty (rows themselves only expose
-              edit/pause/trigger/delete). */}
-          <div className="mb-2 flex items-center justify-between">
-            <span className="text-[0.7rem] uppercase tracking-wide text-muted-foreground">
-              {enabledCount}/{totalCount} active
-            </span>
-            <Button onClick={() => setEditor({ mode: 'create' })} size="sm">
-              <Codicon name="add" />
-              New cron
-            </Button>
+    <OverlayView closeLabel="Close cron" onClose={onClose}>
+      <div className="flex min-h-0 flex-1 flex-col pt-[calc(var(--titlebar-height)+0.5rem)]">
+        {totalCount > 0 && (
+          <div className="mx-auto flex w-full max-w-4xl items-center gap-2 px-4 pb-2">
+            <SearchField
+              containerClassName="max-w-[60vw]"
+              onChange={setQuery}
+              placeholder="Search cron jobs…"
+              value={query}
+            />
           </div>
-          <div className="divide-y divide-border/40 rounded-lg border border-border/40 bg-background/70">
-            {visibleJobs.map(job => (
-              <CronJobRow
-                busy={busyJobId === job.id}
-                job={job}
-                key={job.id}
-                onDelete={() => setPendingDelete(job)}
-                onEdit={() => setEditor({ mode: 'edit', job })}
-                onPauseResume={() => void handlePauseResume(job)}
-                onTrigger={() => void handleTrigger(job)}
-              />
-            ))}
+        )}
+        {!jobs ? (
+          <PageLoader label="Loading cron jobs..." />
+        ) : visibleJobs.length === 0 ? (
+          // Empty state owns the primary "create" CTA — we used to also have
+          // one in the filters bar but it was redundant. Only show the button
+          // when there are zero jobs total; the search-empty case ("No
+          // matches") just asks the user to broaden their query.
+          <EmptyState
+            actionLabel={totalCount === 0 ? 'Create first cron' : undefined}
+            description={
+              totalCount === 0
+                ? 'Schedule a prompt to run on a cron expression. Hermes will run it and deliver results to the destination you pick.'
+                : 'Try a broader search query.'
+            }
+            onAction={totalCount === 0 ? () => setEditor({ mode: 'create' }) : undefined}
+            title={totalCount === 0 ? 'No scheduled jobs yet' : 'No matches'}
+          />
+        ) : (
+          <div className="mx-auto w-full max-w-4xl min-h-0 flex-1 overflow-y-auto px-4 py-3">
+            {/* Inline header replaces the old top-bar "New cron" button. We
+                still need a single, always-visible affordance to add a job
+                when the list is non-empty (rows themselves only expose
+                edit/pause/trigger/delete). */}
+            <div className="mb-2 flex items-center justify-between">
+              <span className="text-[0.7rem] uppercase tracking-wide text-muted-foreground">
+                {enabledCount}/{totalCount} active
+              </span>
+              <Button onClick={() => setEditor({ mode: 'create' })} size="sm">
+                <Codicon name="add" />
+                New cron
+              </Button>
+            </div>
+            <div>
+              {visibleJobs.map(job => (
+                <CronJobRow
+                  busy={busyJobId === job.id}
+                  job={job}
+                  key={job.id}
+                  onDelete={() => setPendingDelete(job)}
+                  onEdit={() => setEditor({ mode: 'edit', job })}
+                  onPauseResume={() => void handlePauseResume(job)}
+                  onTrigger={() => void handleTrigger(job)}
+                />
+              ))}
+            </div>
           </div>
-        </div>
-      )}
+        )}
+      </div>
       <CronEditorDialog editor={editor} onClose={() => setEditor({ mode: 'closed' })} onSave={handleEditorSave} />
 
       <Dialog onOpenChange={open => !open && !deleting && setPendingDelete(null)} open={pendingDelete !== null}>
@@ -519,7 +504,7 @@ export function CronView({ setStatusbarItemGroup: _setStatusbarItemGroup, ...pro
           </DialogFooter>
         </DialogContent>
       </Dialog>
-    </PageSearchShell>
+    </OverlayView>
   )
 }
 
@@ -547,14 +532,20 @@ function CronJobRow({
   return (
     <div className="grid gap-3 px-3 py-2.5 sm:grid-cols-[minmax(0,1fr)_auto] sm:items-start">
       <button
-        className="min-w-0 cursor-pointer rounded-md text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40"
+        className="min-w-0 rounded-md text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40"
         onClick={onEdit}
         type="button"
       >
         <div className="flex flex-wrap items-center gap-2">
           <span className="truncate text-sm font-medium">{jobTitle(job)}</span>
-          <StatePill tone={STATE_TONE[state] ?? 'muted'}>{state}</StatePill>
-          {deliver && deliver !== DEFAULT_DELIVER && <StatePill tone="muted">{deliver}</StatePill>}
+          <Badge className="capitalize" variant={STATE_VARIANT[state] ?? 'muted'}>
+            {state}
+          </Badge>
+          {deliver && deliver !== DEFAULT_DELIVER && (
+            <Badge className="capitalize" variant="muted">
+              {deliver}
+            </Badge>
+          )}
         </div>
         {hasName && prompt && <p className="mt-1 truncate text-xs text-muted-foreground">{truncate(prompt, 120)}</p>}
         <div className="mt-1 flex flex-wrap items-center gap-x-4 gap-y-1 text-[0.68rem] text-muted-foreground">
@@ -573,57 +564,27 @@ function CronJobRow({
         )}
       </button>
 
-      <div className="flex shrink-0 items-center gap-0.5">
-        <IconAction
-          aria-label={isPaused ? 'Resume cron' : 'Pause cron'}
-          disabled={busy}
-          onClick={onPauseResume}
-          title={isPaused ? 'Resume' : 'Pause'}
+      <div className="flex shrink-0 items-center">
+        <CronJobActionsMenu
+          busy={busy}
+          isPaused={isPaused}
+          onDelete={onDelete}
+          onEdit={onEdit}
+          onPauseResume={onPauseResume}
+          onTrigger={onTrigger}
+          title={jobTitle(job)}
         >
-          {isPaused ? <Play className="size-3.5" /> : <Pause className="size-3.5" />}
-        </IconAction>
-        <IconAction aria-label="Trigger now" disabled={busy} onClick={onTrigger} title="Trigger now">
-          <Zap className="size-3.5" />
-        </IconAction>
-        <IconAction aria-label="Edit cron" onClick={onEdit} title="Edit">
-          <Pencil className="size-3.5" />
-        </IconAction>
-        <IconAction
-          aria-label="Delete cron"
-          className="text-muted-foreground hover:bg-destructive/10 hover:text-destructive"
-          onClick={onDelete}
-          title="Delete"
-        >
-          <Trash2 className="size-3.5" />
-        </IconAction>
+          <CronJobActionsTrigger
+            className="text-muted-foreground hover:text-foreground"
+            onClick={event => event.stopPropagation()}
+            title={jobTitle(job)}
+          />
+        </CronJobActionsMenu>
       </div>
     </div>
   )
 }
 
-function IconAction({ children, className, ...props }: Omit<React.ComponentProps<typeof Button>, 'size' | 'variant'>) {
-  return (
-    <Button
-      className={cn('size-7 text-muted-foreground hover:text-foreground', className)}
-      size="icon"
-      variant="ghost"
-      {...props}
-    >
-      {children}
-    </Button>
-  )
-}
-
-function StatePill({ children, tone }: { children: string; tone: keyof typeof PILL_TONE }) {
-  return (
-    <span
-      className={cn('inline-flex items-center rounded-full px-1.5 py-0.5 text-[0.64rem] capitalize', PILL_TONE[tone])}
-    >
-      {children}
-    </span>
-  )
-}
-
 function EmptyState({
   actionLabel,
   description,
@@ -768,7 +729,7 @@ function CronEditorDialog({
           <div className="grid items-start gap-4 sm:grid-cols-2">
             <Field htmlFor="cron-frequency" label="Frequency">
               <Select onValueChange={handleSchedulePresetChange} value={schedulePreset}>
-                <SelectTrigger className="h-9 rounded-md" id="cron-frequency">
+                <SelectTrigger id="cron-frequency">
                   <SelectValue />
                 </SelectTrigger>
                 <SelectContent>
@@ -783,7 +744,7 @@ function CronEditorDialog({
 
             <Field htmlFor="cron-deliver" label="Deliver to">
               <Select onValueChange={setDeliver} value={deliver}>
-                <SelectTrigger className="h-9 rounded-md" id="cron-deliver">
+                <SelectTrigger id="cron-deliver">
                   <SelectValue />
                 </SelectTrigger>
                 <SelectContent>

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

@@ -13,7 +13,9 @@ import { useSkinCommand } from '@/themes/use-skin-command'
 import { formatRefValue } from '../components/assistant-ui/directive-text'
 import { getSessionMessages, listSessions } from '../hermes'
 import { preserveLocalAssistantErrors, toChatMessages } from '../lib/chat-messages'
+import { toggleCommandPalette } from '../store/command-palette'
 import {
+  $panesFlipped,
   $pinnedSessionIds,
   $sessionsLimit,
   bumpSessionsLimit,
@@ -34,7 +36,7 @@ import {
   $selectedStoredSessionId,
   $sessions,
   $workingSessionIds,
-  mergeWorkingSessions,
+  mergeSessionPage,
   sessionPinId,
   setAwaitingResponse,
   setBusy,
@@ -58,6 +60,7 @@ import {
   PREVIEW_RAIL_PANE_WIDTH
 } from './chat/right-rail'
 import { ChatSidebar } from './chat/sidebar'
+import { CommandPalette } from './command-palette'
 import { useGatewayBoot } from './gateway/hooks/use-gateway-boot'
 import { useGatewayRequest } from './gateway/hooks/use-gateway-request'
 import { ModelPickerOverlay } from './model-picker-overlay'
@@ -112,6 +115,7 @@ export function DesktopController() {
   const previewTarget = useStore($previewTarget)
   const selectedStoredSessionId = useStore($selectedStoredSessionId)
   const terminalTakeover = useStore($terminalTakeover)
+  const panesFlipped = useStore($panesFlipped)
 
   const routedSessionId = routeSessionId(location.pathname)
   const routeToken = `${location.pathname}:${location.search}:${location.hash}`
@@ -125,9 +129,11 @@ export function DesktopController() {
     closeOverlayToPreviousRoute,
     commandCenterInitialSection,
     commandCenterOpen,
+    cronOpen,
     currentView,
     openAgents,
     openCommandCenterSection,
+    profilesOpen,
     settingsOpen,
     toggleCommandCenter
   } = useOverlayRouting()
@@ -195,6 +201,31 @@ export function DesktopController() {
     }
   }, [])
 
+  // Global chrome shortcuts (plain Cmd/Ctrl, no alt/shift): Cmd+K → command
+  // palette (the composer's "drain next queued" moved to Cmd+Shift+K), Cmd+. →
+  // command center (sessions / system / usage).
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (!(event.metaKey || event.ctrlKey) || event.altKey || event.shiftKey) {
+        return
+      }
+
+      const key = event.key.toLowerCase()
+
+      if (key === 'k') {
+        event.preventDefault()
+        toggleCommandPalette()
+      } else if (key === '.') {
+        event.preventDefault()
+        toggleCommandCenter()
+      }
+    }
+
+    window.addEventListener('keydown', onKeyDown)
+
+    return () => window.removeEventListener('keydown', onKeyDown)
+  }, [toggleCommandCenter])
+
   const refreshSessions = useCallback(async () => {
     const requestId = refreshSessionsRequestRef.current + 1
     refreshSessionsRequestRef.current = requestId
@@ -208,12 +239,13 @@ export function DesktopController() {
       const result = await listSessions(limit, 1)
 
       if (refreshSessionsRequestRef.current === requestId) {
-        // Don't hard-replace: a session whose first turn is still in flight has
-        // message_count 0 in the DB, so min_messages=1 omits it. Since every
-        // message.complete refreshes the list, a plain replace would drop the
-        // other still-running new chats the moment one of them finishes. Keep
-        // any working session the server hasn't surfaced yet.
-        setSessions(prev => mergeWorkingSessions(prev, result.sessions, $workingSessionIds.get()))
+        // Don't hard-replace. Two kinds of rows must survive a refresh the
+        // server didn't return: (1) sessions whose first turn is still in
+        // flight (message_count 0, so min_messages=1 omits them) and (2)
+        // pinned sessions that have aged off the most-recent page — otherwise
+        // the pin "disappears until you refresh". mergeSessionPage keeps both.
+        const keepIds = new Set<string>([...$workingSessionIds.get(), ...$pinnedSessionIds.get()])
+        setSessions(prev => mergeSessionPage(prev, result.sessions, keepIds))
         setSessionsTotal(typeof result.total === 'number' ? result.total : result.sessions.length)
       }
     } finally {
@@ -284,7 +316,7 @@ export function DesktopController() {
   })
 
   const openProviderSettings = useCallback(() => {
-    navigate(`${SETTINGS_ROUTE}?tab=keys`)
+    navigate(`${SETTINGS_ROUTE}?tab=providers`)
   }, [navigate])
 
   const modelMenuContent = useMemo(
@@ -413,6 +445,8 @@ export function DesktopController() {
 
       event.preventDefault()
       startFreshSessionDraft()
+      // Briefly light up the sidebar's ⌘N hint so the shortcut is discoverable.
+      window.dispatchEvent(new CustomEvent('hermes:new-session-shortcut'))
     }
 
     window.addEventListener('keydown', onKeyDown)
@@ -524,7 +558,9 @@ export function DesktopController() {
     inferenceStatus,
     modelMenuContent,
     openAgents,
+    freshDraftReady,
     openCommandCenterSection,
+    requestGateway,
     statusSnapshot,
     toggleCommandCenter
   })
@@ -561,6 +597,7 @@ export function DesktopController() {
       <UpdatesOverlay />
       <GatewayConnectingOverlay />
       <BootFailureOverlay />
+      <CommandPalette />
 
       {settingsOpen && (
         <Suspense fallback={null}>
@@ -589,7 +626,6 @@ export function DesktopController() {
             initialSection={commandCenterInitialSection}
             onClose={closeOverlayToPreviousRoute}
             onDeleteSession={removeSession}
-            onNavigateRoute={path => navigate(path)}
             onOpenSession={sessionId => navigate(sessionRoute(sessionId))}
           />
         </Suspense>
@@ -600,6 +636,18 @@ export function DesktopController() {
           <AgentsView onClose={closeOverlayToPreviousRoute} />
         </Suspense>
       )}
+
+      {cronOpen && (
+        <Suspense fallback={null}>
+          <CronView onClose={closeOverlayToPreviousRoute} />
+        </Suspense>
+      )}
+
+      {profilesOpen && (
+        <Suspense fallback={null}>
+          <ProfilesView onClose={closeOverlayToPreviousRoute} />
+        </Suspense>
+      )}
     </>
   )
 
@@ -611,7 +659,7 @@ export function DesktopController() {
       onAddUrl={url => composer.addContextRefAttachment(`@url:${formatRefValue(url)}`, url)}
       onAttachDroppedItems={composer.attachDroppedItems}
       onAttachImageBlob={composer.attachImageBlob}
-      onBranchInNewChat={messageId => void branchInNewChat(messageId)}
+      onBranchInNewChat={branchInNewChat}
       onCancel={cancelRun}
       onDeleteSelectedSession={() => {
         if (selectedStoredSessionId) {
@@ -638,12 +686,52 @@ export function DesktopController() {
     </div>
   )
 
+  // Flipped layout mirrors the default: sessions sidebar → right, file
+  // browser + preview rail → left. Same panes, swapped sides.
+  const sidebarSide = panesFlipped ? 'right' : 'left'
+  const railSide = panesFlipped ? 'left' : 'right'
+
+  const previewPane = (
+    <Pane
+      disabled={!chatOpen || (!previewTarget && !filePreviewTarget)}
+      id="preview"
+      key="preview"
+      maxWidth={PREVIEW_RAIL_MAX_WIDTH}
+      minWidth={PREVIEW_RAIL_MIN_WIDTH}
+      resizable
+      side={railSide}
+      width={PREVIEW_RAIL_PANE_WIDTH}
+    >
+      {chatOpen ? (
+        <ChatPreviewRail onRestartServer={restartPreviewServer} setTitlebarToolGroup={setTitlebarToolGroup} />
+      ) : null}
+    </Pane>
+  )
+
+  const fileBrowserPane = (
+    <Pane
+      defaultOpen={false}
+      disabled={!chatOpen}
+      id="file-browser"
+      key="file-browser"
+      maxWidth={FILE_BROWSER_MAX_WIDTH}
+      minWidth={FILE_BROWSER_MIN_WIDTH}
+      resizable
+      side={railSide}
+      width={FILE_BROWSER_DEFAULT_WIDTH}
+    >
+      <RightSidebarPane
+        onActivateFile={composer.attachContextFilePath}
+        onActivateFolder={composer.attachContextFolderPath}
+        onChangeCwd={changeSessionCwd}
+      />
+    </Pane>
+  )
+
   return (
     <AppShell
-      commandCenterOpen={commandCenterOpen}
       leftStatusbarItems={leftStatusbarItems}
       leftTitlebarTools={titlebarToolGroups.flat.left}
-      onOpenSearch={() => openCommandCenterSection('sessions')}
       onOpenSettings={openSettings}
       overlays={overlays}
       statusbarItems={statusbarItems}
@@ -655,7 +743,7 @@ export function DesktopController() {
         maxWidth={SIDEBAR_MAX_WIDTH}
         minWidth={SIDEBAR_DEFAULT_WIDTH}
         resizable
-        side="left"
+        side={sidebarSide}
         width={`${SIDEBAR_DEFAULT_WIDTH}px`}
       >
         {sidebar}
@@ -688,25 +776,8 @@ export function DesktopController() {
             }
             path="artifacts"
           />
-          <Route
-            element={
-              <Suspense fallback={null}>
-                <CronView setStatusbarItemGroup={setStatusbarItemGroup} />
-              </Suspense>
-            }
-            path="cron"
-          />
-          <Route
-            element={
-              <Suspense fallback={null}>
-                <ProfilesView
-                  setStatusbarItemGroup={setStatusbarItemGroup}
-                  setTitlebarToolGroup={setTitlebarToolGroup}
-                />
-              </Suspense>
-            }
-            path="profiles"
-          />
+          <Route element={null} path="cron" />
+          <Route element={null} path="profiles" />
           <Route element={null} path="settings" />
           <Route element={null} path="command-center" />
           <Route element={null} path="agents" />
@@ -715,35 +786,13 @@ export function DesktopController() {
           <Route element={<Navigate replace to={NEW_CHAT_ROUTE} />} path="*" />
         </Routes>
       </PaneMain>
-      <Pane
-        disabled={!chatOpen || (!previewTarget && !filePreviewTarget)}
-        id="preview"
-        maxWidth={PREVIEW_RAIL_MAX_WIDTH}
-        minWidth={PREVIEW_RAIL_MIN_WIDTH}
-        resizable
-        side="right"
-        width={PREVIEW_RAIL_PANE_WIDTH}
-      >
-        {chatOpen ? (
-          <ChatPreviewRail onRestartServer={restartPreviewServer} setTitlebarToolGroup={setTitlebarToolGroup} />
-        ) : null}
-      </Pane>
-      <Pane
-        defaultOpen={false}
-        disabled={!chatOpen}
-        id="file-browser"
-        maxWidth={FILE_BROWSER_MAX_WIDTH}
-        minWidth={FILE_BROWSER_MIN_WIDTH}
-        resizable
-        side="right"
-        width={FILE_BROWSER_DEFAULT_WIDTH}
-      >
-        <RightSidebarPane
-          onActivateFile={composer.attachContextFilePath}
-          onActivateFolder={composer.attachContextFolderPath}
-          onChangeCwd={changeSessionCwd}
-        />
-      </Pane>
+      {/*
+        Order within a side maps to column order. Default (rail on the right):
+        main | preview | file-browser. Flipped (rail on the left): mirror it to
+        file-browser | preview | main so preview stays adjacent to the chat.
+      */}
+      {panesFlipped ? fileBrowserPane : previewPane}
+      {panesFlipped ? previewPane : fileBrowserPane}
     </AppShell>
   )
 }

apps/desktop/src/app/gateway/hooks/use-gateway-boot.ts

@@ -2,6 +2,7 @@ import { useEffect, useRef } from 'react'
 
 import type { HermesConnection } from '@/global'
 import { HermesGateway } from '@/hermes'
+import { isGatewayReauthRequired, resolveGatewayWsUrl } from '@/lib/gateway-ws-url'
 import {
   $desktopBoot,
   applyDesktopBootProgress,
@@ -63,6 +64,108 @@ export function useGatewayBoot({
       return () => void (cancelled = true)
     }
 
+    // --- Reconnect-after-sleep machinery -------------------------------------
+    // macOS sleep silently drops the renderer's WebSocket. The backend Python
+    // process keeps running, but nothing re-opened the socket on wake, so the
+    // composer stayed disabled forever on "Starting Hermes...". Once the
+    // initial boot succeeds we treat any non-open state as recoverable and
+    // reconnect with backoff, and we nudge a reconnect on the OS/browser
+    // signals that fire around wake (power resume, network online, the window
+    // becoming visible).
+    let bootCompleted = false
+    let reconnecting = false
+    let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+    let reconnectAttempt = 0
+
+    // Wrap the live getter in a call so TS control-flow analysis doesn't narrow
+    // `connectionState` to a constant across the early-return guards (the state
+    // genuinely changes between reads).
+    const gatewayOpen = () => gateway.connectionState === 'open'
+
+    const clearReconnectTimer = () => {
+      if (reconnectTimer !== null) {
+        clearTimeout(reconnectTimer)
+        reconnectTimer = null
+      }
+    }
+
+    const attemptReconnect = async () => {
+      if (cancelled || reconnecting || gatewayOpen()) {
+        return
+      }
+
+      reconnecting = true
+
+      try {
+        const conn = await desktop.getConnection()
+
+        if (cancelled) {
+          return
+        }
+
+        publish(conn)
+        // Re-mint the WS URL before reconnecting. OAuth tickets are single-use
+        // with a short TTL, so the ticket baked into the cached conn.wsUrl is
+        // dead on every reconnect after the initial boot — reusing it surfaces
+        // as an opaque "Could not connect to Hermes gateway". resolveGatewayWsUrl
+        // mints a fresh ticket (or throws a reauth error in OAuth mode rather
+        // than connecting with a stale one). For local/token gateways the URL
+        // carries a long-lived token and the re-mint is a cheap no-op.
+        const wsUrl = await resolveGatewayWsUrl(desktop, conn)
+        await gateway.connect(wsUrl)
+
+        if (cancelled) {
+          return
+        }
+
+        reconnectAttempt = 0
+        // Resync state that may have moved on the backend while we were asleep.
+        await callbacksRef.current.refreshHermesConfig().catch(() => undefined)
+        await callbacksRef.current.refreshSessions().catch(() => undefined)
+      } catch (err) {
+        // OAuth session expired mid-reconnect: surface the actionable "sign in
+        // again" message once instead of silently looping the backoff against a
+        // ticket that can never succeed. Transport failures fall through to the
+        // backoff in the finally block below.
+        if (!cancelled && isGatewayReauthRequired(err)) {
+          notifyError(err, 'Gateway sign-in required')
+        }
+      } finally {
+        reconnecting = false
+
+        if (!cancelled && !gatewayOpen()) {
+          scheduleReconnect()
+        }
+      }
+    }
+
+    function scheduleReconnect() {
+      if (cancelled || reconnecting || reconnectTimer !== null || gatewayOpen()) {
+        return
+      }
+
+      // 1s, 2s, 4s … capped at 15s.
+      const delay = Math.min(15_000, 1_000 * 2 ** Math.min(reconnectAttempt, 4))
+      reconnectAttempt += 1
+      reconnectTimer = setTimeout(() => {
+        reconnectTimer = null
+        void attemptReconnect()
+      }, delay)
+    }
+
+    const reconnectNow = () => {
+      if (cancelled || !bootCompleted) {
+        return
+      }
+
+      clearReconnectTimer()
+      reconnectAttempt = 0
+
+      if (!gatewayOpen()) {
+        void attemptReconnect()
+      }
+    }
+
     const offBootProgress = desktop.onBootProgress(payload => applyDesktopBootProgress(payload))
     void desktop
       .getBootProgress()
@@ -79,9 +182,36 @@ export function useGatewayBoot({
     callbacksRef.current.onGatewayReady(gateway)
     setGateway(gateway)
 
-    const offState = gateway.onState(st => void setGatewayState(st))
+    const offState = gateway.onState(st => {
+      setGatewayState(st)
+
+      if (st === 'open') {
+        reconnectAttempt = 0
+        clearReconnectTimer()
+      } else if (bootCompleted && (st === 'closed' || st === 'error')) {
+        // The socket dropped after a healthy boot (typically sleep/wake). Try
+        // to bring it back instead of leaving the composer stuck disabled.
+        scheduleReconnect()
+      }
+    })
+
     const offEvent = gateway.onEvent(event => callbacksRef.current.handleGatewayEvent(event))
 
+    // Wake signals: power resume (macOS/Windows), network coming back, and the
+    // window regaining focus/visibility. Each nudges an immediate reconnect.
+    const offPowerResume = desktop.onPowerResume?.(() => reconnectNow())
+
+    const onOnline = () => reconnectNow()
+
+    const onVisible = () => {
+      if (document.visibilityState === 'visible') {
+        reconnectNow()
+      }
+    }
+
+    window.addEventListener('online', onOnline)
+    document.addEventListener('visibilitychange', onVisible)
+
     const offWindowState = desktop.onWindowStateChanged?.(payload => {
       const current = $connection.get()
 
@@ -117,7 +247,13 @@ export function useGatewayBoot({
           progress: 95
         })
         publish(conn)
-        await gateway.connect(conn.wsUrl)
+        // Mint a fresh WS URL right before connecting. For OAuth gateways the
+        // ticket is single-use with a short TTL, so the ticket baked into
+        // conn.wsUrl is stale; resolveGatewayWsUrl() re-mints it and, on
+        // failure, throws a reauth error rather than connecting with a dead
+        // ticket (which would surface as an opaque "connection closed").
+        const wsUrl = await resolveGatewayWsUrl(desktop, conn)
+        await gateway.connect(wsUrl)
 
         if (cancelled) {
           return
@@ -141,6 +277,7 @@ export function useGatewayBoot({
         })
         await callbacksRef.current.refreshSessions()
         completeDesktopBoot()
+        bootCompleted = true
       } catch (err) {
         if (!cancelled) {
           const message = err instanceof Error ? err.message : String(err)
@@ -155,6 +292,10 @@ export function useGatewayBoot({
 
     return () => {
       cancelled = true
+      clearReconnectTimer()
+      window.removeEventListener('online', onOnline)
+      document.removeEventListener('visibilitychange', onVisible)
+      offPowerResume?.()
       offState()
       offEvent()
       offExit()

apps/desktop/src/app/gateway/hooks/use-gateway-request.ts

@@ -2,6 +2,7 @@ import { useStore } from '@nanostores/react'
 import { useCallback, useEffect, useRef } from 'react'
 
 import type { HermesGateway } from '@/hermes'
+import { isGatewayReauthRequired, resolveGatewayWsUrl } from '@/lib/gateway-ws-url'
 import { $gatewayState, setConnection } from '@/store/session'
 
 export function useGatewayRequest() {
@@ -14,6 +15,10 @@ export function useGatewayRequest() {
 
   const gatewayStateRef = useRef(gatewayState)
   const reconnectingRef = useRef<Promise<HermesGateway | null> | null>(null)
+  // Holds the reauth error from the most recent failed reconnect so
+  // requestGateway can surface the gateway's "session expired, sign in again"
+  // message instead of the opaque "connection closed" that triggered the retry.
+  const reauthErrorRef = useRef<unknown>(null)
 
   useEffect(() => {
     gatewayStateRef.current = gatewayState
@@ -41,14 +46,26 @@ export function useGatewayRequest() {
         return null
       }
 
+      reauthErrorRef.current = null
+
       try {
         const conn = await desktop.getConnection()
         connectionRef.current = conn
         setConnection(conn)
-        await existing.connect(conn.wsUrl)
+        // Re-mint the WS URL before reconnecting. OAuth tickets are single-use
+        // and short-lived, so the cached conn.wsUrl ticket is dead here;
+        // resolveGatewayWsUrl() throws a reauth error in OAuth mode rather than
+        // connecting with a stale ticket. Stash it so requestGateway can show
+        // the actionable "sign in again" message.
+        const wsUrl = await resolveGatewayWsUrl(desktop, conn)
+        await existing.connect(wsUrl)
 
         return existing
-      } catch {
+      } catch (error) {
+        if (isGatewayReauthRequired(error)) {
+          reauthErrorRef.current = error
+        }
+
         connectionRef.current = null
         setConnection(null)
 
@@ -81,6 +98,15 @@ export function useGatewayRequest() {
         const recovered = await ensureGatewayOpen()
 
         if (!recovered) {
+          // Prefer the reauth error from the failed reconnect (OAuth session
+          // expired) over the generic transport error that triggered the retry.
+          const reauthError = reauthErrorRef.current
+          reauthErrorRef.current = null
+
+          if (reauthError) {
+            throw reauthError
+          }
+
           throw error
         }
 

apps/desktop/src/app/hooks/use-refresh-hotkey.ts

@@ -0,0 +1,45 @@
+import { useEffect, useRef } from 'react'
+
+/**
+ * Binds the bare `r` key to a refresh action while the calling view is mounted.
+ * Ignored when a modifier is held, the event repeats, or focus is in an
+ * editable field (so typing "r" in a search/input never triggers it).
+ */
+export function useRefreshHotkey(onRefresh: () => void, enabled = true) {
+  const ref = useRef(onRefresh)
+  ref.current = onRefresh
+
+  useEffect(() => {
+    if (!enabled) {
+      return
+    }
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'r' && event.key !== 'R') {
+        return
+      }
+
+      if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey || event.repeat) {
+        return
+      }
+
+      const target = event.target as HTMLElement | null
+
+      if (
+        target?.isContentEditable ||
+        target instanceof HTMLInputElement ||
+        target instanceof HTMLTextAreaElement ||
+        target instanceof HTMLSelectElement
+      ) {
+        return
+      }
+
+      event.preventDefault()
+      ref.current()
+    }
+
+    window.addEventListener('keydown', onKeyDown)
+
+    return () => window.removeEventListener('keydown', onKeyDown)
+  }, [enabled])
+}

apps/desktop/src/app/layout-constants.ts

@@ -0,0 +1,13 @@
+// Responsive horizontal gutter for primary content bodies (settings right side,
+// skills, artifacts, command center / sessions). Ratio-based so it scales with
+// the window, but clamped so it never collapses on narrow widths or runs away
+// on ultrawide displays. Headers/tabs intentionally keep their own tighter
+// padding.
+//
+// NOTE: these must stay literal strings — Tailwind's scanner only picks up
+// complete class names, so do not build them via template interpolation.
+export const PAGE_INSET_X = 'px-[clamp(1.25rem,4vw,4rem)]'
+
+// Matching negative inline-margin to bleed an element (e.g. a sticky header bar)
+// out to the gutter edges before re-applying PAGE_INSET_X.
+export const PAGE_INSET_NEG_X = '-mx-[clamp(1.25rem,4vw,4rem)]'

apps/desktop/src/app/messaging/index.tsx

@@ -3,6 +3,7 @@ import { useCallback, useEffect, useMemo, useState } from 'react'
 
 import { PageLoader } from '@/components/page-loader'
 import { StatusDot, type StatusTone } from '@/components/status-dot'
+import { Badge, type BadgeProps } from '@/components/ui/badge'
 import { Button } from '@/components/ui/button'
 import { DisclosureCaret } from '@/components/ui/disclosure-caret'
 import { Input } from '@/components/ui/input'
@@ -17,6 +18,9 @@ import { AlertTriangle, ExternalLink, Save, Trash2 } from '@/lib/icons'
 import { cn } from '@/lib/utils'
 import { notify, notifyError } from '@/store/notifications'
 
+import { CREDENTIAL_CONTROL_CLASS } from '../settings/credential-key-ui'
+import { ListRow } from '../settings/primitives'
+import { useRefreshHotkey } from '../hooks/use-refresh-hotkey'
 import { useRouteEnumParam } from '../hooks/use-route-enum-param'
 import { PageSearchShell } from '../page-search-shell'
 import type { SetStatusbarItemGroup } from '../shell/statusbar-controls'
@@ -41,11 +45,11 @@ const STATE_LABELS: Record<string, string> = {
   startup_failed: 'Startup failed'
 }
 
-const PILL_TONE: Record<StatusTone, string> = {
-  good: 'bg-primary/10 text-primary',
-  muted: 'bg-muted text-muted-foreground',
-  warn: 'bg-amber-500/10 text-amber-600 dark:text-amber-300',
-  bad: 'bg-destructive/10 text-destructive'
+const TONE_VARIANT: Record<StatusTone, BadgeProps['variant']> = {
+  good: 'default',
+  muted: 'muted',
+  warn: 'warn',
+  bad: 'destructive'
 }
 
 const HINT_BY_STATE: Record<string, string> = {
@@ -106,6 +110,47 @@ const FIELD_COPY: Record<string, { advanced?: boolean; help?: string; label: str
     help: 'first, all, or off.',
     advanced: true
   },
+  DISCORD_ALLOW_ALL_USERS: {
+    label: 'Allow all Discord users',
+    help: 'Development only. When true, anyone can DM the bot without an allowlist.',
+    advanced: true
+  },
+  DISCORD_HOME_CHANNEL: {
+    label: 'Home channel ID',
+    help: 'Channel where the bot sends proactive messages (cron output, reminders).',
+    advanced: true
+  },
+  DISCORD_HOME_CHANNEL_NAME: {
+    label: 'Home channel name',
+    help: 'Display name for the home channel in logs and status output.',
+    advanced: true
+  },
+  BLUEBUBBLES_ALLOW_ALL_USERS: {
+    label: 'Allow all iMessage users',
+    help: 'When true, skip the BlueBubbles allowlist.',
+    advanced: true
+  },
+  MATTERMOST_ALLOW_ALL_USERS: {
+    label: 'Allow all Mattermost users',
+    advanced: true
+  },
+  MATTERMOST_HOME_CHANNEL: {
+    label: 'Home channel',
+    advanced: true
+  },
+  QQ_ALLOW_ALL_USERS: {
+    label: 'Allow all QQ users',
+    advanced: true
+  },
+  QQBOT_HOME_CHANNEL: {
+    label: 'QQ home channel',
+    help: 'Default channel or group for cron delivery.',
+    advanced: true
+  },
+  QQBOT_HOME_CHANNEL_NAME: {
+    label: 'QQ home channel name',
+    advanced: true
+  },
   SLACK_BOT_TOKEN: {
     label: 'Slack bot token',
     help: 'Starts with xoxb-. Found under OAuth & Permissions after installing your Slack app.',
@@ -213,6 +258,8 @@ export function MessagingView({ setStatusbarItemGroup: _setStatusbarItemGroup, .
     }
   }, [])
 
+  useRefreshHotkey(() => void refreshPlatforms())
+
   useEffect(() => {
     void refreshPlatforms()
   }, [refreshPlatforms])
@@ -343,15 +390,15 @@ export function MessagingView({ setStatusbarItemGroup: _setStatusbarItemGroup, .
     <PageSearchShell
       {...props}
       onSearchChange={setQuery}
+      searchHidden={(platforms?.length ?? 0) === 0}
       searchPlaceholder="Search messaging..."
-      searchTrailingAction={null}
       searchValue={query}
     >
       {!platforms ? (
         <PageLoader label="Loading messaging platforms..." />
       ) : (
         <div className="grid h-full min-h-0 grid-cols-1 lg:grid-cols-[14rem_minmax(0,1fr)]">
-          <aside className="min-h-0 overflow-y-auto border-b border-(--ui-stroke-tertiary) p-2 lg:border-b-0 lg:border-r">
+          <aside className="min-h-0 overflow-y-auto p-2">
             <ul className="space-y-1">
               {visiblePlatforms.map(platform => (
                 <li key={platform.id}>
@@ -406,8 +453,8 @@ function PlatformRow({
       className={cn(
         'flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-left transition-colors',
         active
-          ? 'bg-(--ui-bg-tertiary) text-foreground'
-          : 'text-(--ui-text-secondary) hover:bg-(--chrome-action-hover) hover:text-foreground'
+          ? 'bg-(--ui-row-active-background) text-foreground'
+          : 'text-(--ui-text-secondary) hover:bg-(--ui-row-hover-background) hover:text-foreground'
       )}
       onClick={onSelect}
       type="button"
@@ -482,7 +529,7 @@ function PlatformDetail({
               {introCopy(platform)}
             </p>
             <div className="mt-3">
-              <Button asChild size="sm" variant="outline">
+              <Button asChild size="sm" variant="textStrong">
                 <a href={platform.docs_url} rel="noreferrer" target="_blank">
                   Open setup guide
                   <ExternalLink className="size-3.5" />
@@ -493,7 +540,7 @@ function PlatformDetail({
 
           <section>
             <SectionTitle>Required</SectionTitle>
-            <div className="mt-3 space-y-4">
+            <div className="mt-3 grid gap-1">
               {requiredFields.length > 0 ? (
                 requiredFields.map(field => (
                   <MessagingField
@@ -516,7 +563,7 @@ function PlatformDetail({
           {optionalFields.length > 0 && (
             <section>
               <SectionTitle>Recommended</SectionTitle>
-              <div className="mt-3 space-y-4">
+              <div className="mt-3 grid gap-1">
                 {optionalFields.map(field => (
                   <MessagingField
                     edits={edits}
@@ -542,7 +589,7 @@ function PlatformDetail({
                 <DisclosureCaret open={showAdvanced} size="0.875rem" />
               </button>
               {showAdvanced && (
-                <div className="mt-3 space-y-4">
+                <div className="mt-3 grid gap-1">
                   {advancedFields.map(field => (
                     <MessagingField
                       edits={edits}
@@ -560,19 +607,15 @@ function PlatformDetail({
         </div>
       </div>
 
-      <footer className="border-t border-(--ui-stroke-tertiary) bg-(--ui-chat-surface-background) px-5 py-2.5">
+      <footer className="bg-(--ui-chat-surface-background) px-5 py-2.5">
         <div className="mx-auto flex max-w-2xl flex-wrap items-center gap-2">
-          <label className="flex shrink-0 items-center gap-2 rounded-md border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) px-2.5 py-1.5 text-[length:var(--conversation-text-font-size)]">
-            <Switch
-              aria-label={platform.enabled ? `Disable ${platform.name}` : `Enable ${platform.name}`}
-              checked={platform.enabled}
-              disabled={saving === `enabled:${platform.id}`}
-              onCheckedChange={onToggle}
-            />
-            <span className="text-xs font-medium text-muted-foreground">
-              {platform.enabled ? 'Enabled' : 'Disabled'}
-            </span>
-          </label>
+          <Switch
+            aria-label={platform.enabled ? `Disable ${platform.name}` : `Enable ${platform.name}`}
+            checked={platform.enabled}
+            disabled={saving === `enabled:${platform.id}`}
+            onCheckedChange={onToggle}
+            size="xs"
+          />
 
           <div className="ml-auto flex items-center gap-2">
             {hasEdits && <span className="text-xs text-muted-foreground">Unsaved changes</span>}
@@ -640,45 +683,48 @@ function MessagingField({
   saving: string | null
 }) {
   const copy = fieldCopy(field)
+  const fieldId = `messaging-field-${field.key}`
 
   return (
-    <div className="space-y-1.5">
-      <div className="flex flex-wrap items-baseline gap-2">
-        <label className="text-sm font-medium text-foreground" htmlFor={`messaging-field-${field.key}`}>
-          {copy.label}
-        </label>
-        {field.is_set && <span className="text-[0.66rem] font-medium text-primary">Saved</span>}
-      </div>
-      <div className="flex items-center gap-2">
-        <Input
-          className="h-9 rounded-lg font-mono text-sm"
-          id={`messaging-field-${field.key}`}
-          onChange={event => onEdit(field.key, event.target.value)}
-          placeholder={field.is_set ? field.redacted_value || 'Replace current value' : copy.placeholder}
-          type={field.is_password ? 'password' : 'text'}
-          value={edits[field.key] || ''}
-        />
-        {field.url && (
-          <Button asChild size="icon-sm" title="Open docs" variant="ghost">
-            <a href={field.url} rel="noreferrer" target="_blank">
-              <ExternalLink className="size-3.5" />
-            </a>
-          </Button>
-        )}
-        {field.is_set && (
-          <Button
-            disabled={saving === `clear:${field.key}`}
-            onClick={() => onClear(field.key)}
-            size="icon-sm"
-            title={`Clear ${field.key}`}
-            variant="ghost"
-          >
-            <Trash2 className="size-3.5" />
-          </Button>
-        )}
-      </div>
-      {copy.help && <p className="text-xs leading-5 text-muted-foreground">{copy.help}</p>}
-    </div>
+    <ListRow
+      action={
+        <div className="flex items-center gap-2">
+          <Input
+            className={CREDENTIAL_CONTROL_CLASS}
+            id={fieldId}
+            onChange={event => onEdit(field.key, event.target.value)}
+            placeholder={field.is_set ? field.redacted_value || 'Replace current value' : copy.placeholder}
+            type={field.is_password ? 'password' : 'text'}
+            value={edits[field.key] || ''}
+          />
+          {field.url && (
+            <Button asChild className="size-8 shrink-0" title="Open docs" variant="ghost">
+              <a href={field.url} rel="noreferrer" target="_blank">
+                <ExternalLink className="size-3.5" />
+              </a>
+            </Button>
+          )}
+          {field.is_set && (
+            <Button
+              className="size-8 shrink-0"
+              disabled={saving === `clear:${field.key}`}
+              onClick={() => onClear(field.key)}
+              title={`Clear ${field.key}`}
+              variant="ghost"
+            >
+              <Trash2 className="size-3.5" />
+            </Button>
+          )}
+        </div>
+      }
+      description={copy.help}
+      title={
+        <span className="flex flex-wrap items-center gap-2">
+          <label htmlFor={fieldId}>{copy.label}</label>
+          {field.is_set && <span className="text-[0.66rem] font-medium text-primary">Saved</span>}
+        </span>
+      }
+    />
   )
 }
 
@@ -698,27 +744,13 @@ function PlatformHint({ platform }: { platform: MessagingPlatformInfo }) {
 
 function StatePill({ children, tone }: { children: string; tone: StatusTone }) {
   return (
-    <span
-      className={cn(
-        'inline-flex shrink-0 items-center gap-1.5 rounded-full px-2 py-0.5 text-[0.66rem] font-medium',
-        PILL_TONE[tone]
-      )}
-    >
+    <Badge variant={TONE_VARIANT[tone]}>
       <StatusDot tone={tone} />
       {children}
-    </span>
+    </Badge>
   )
 }
 
 function SetupPill({ active, children }: { active: boolean; children: string }) {
-  return (
-    <span
-      className={cn(
-        'inline-flex items-center rounded-full px-2 py-0.5 text-[0.66rem] font-medium',
-        PILL_TONE[active ? 'good' : 'muted']
-      )}
-    >
-      {children}
-    </span>
-  )
+  return <Badge variant={active ? 'default' : 'muted'}>{children}</Badge>
 }

apps/desktop/src/app/messaging/platform-icon.tsx

@@ -1,5 +1,3 @@
-import type { ComponentType, SVGProps } from 'react'
-
 import {
   SiApple,
   SiBilibili,
@@ -14,6 +12,7 @@ import {
   SiWechat,
   SiWhatsapp
 } from '@icons-pack/react-simple-icons'
+import type { ComponentType, SVGProps } from 'react'
 
 import { Globe, Link as LinkIcon, MessageSquareText } from '@/lib/icons'
 import { cn } from '@/lib/utils'
@@ -69,10 +68,7 @@ export function PlatformAvatar({ className, platformId, platformName }: Platform
 
   if (!spec) {
     return (
-      <span
-        aria-hidden="true"
-        className={cn(baseClass, 'bg-(--ui-bg-tertiary) text-(--ui-text-tertiary)')}
-      >
+      <span aria-hidden="true" className={cn(baseClass, 'bg-(--ui-bg-tertiary) text-(--ui-text-tertiary)')}>
         {platformName.charAt(0).toUpperCase()}
       </span>
     )

apps/desktop/src/app/overlays/overlay-search-input.tsx

@@ -1,77 +0,0 @@
-import type { ReactNode, RefObject } from 'react'
-
-import { Button } from '@/components/ui/button'
-import { Codicon } from '@/components/ui/codicon'
-import { Input } from '@/components/ui/input'
-import { Loader2, Search } from '@/lib/icons'
-import { cn } from '@/lib/utils'
-
-interface OverlaySearchInputProps {
-  placeholder: string
-  value: string
-  onChange: (value: string) => void
-  containerClassName?: string
-  inputClassName?: string
-  loading?: boolean
-  onClear?: () => void
-  inputRef?: RefObject<HTMLInputElement | null>
-  trailingAction?: ReactNode
-}
-
-export function OverlaySearchInput({
-  placeholder,
-  value,
-  onChange,
-  containerClassName,
-  inputClassName,
-  loading = false,
-  onClear,
-  inputRef,
-  trailingAction
-}: OverlaySearchInputProps) {
-  const clear = onClear ?? (() => onChange(''))
-  const hasTrailing = Boolean(trailingAction)
-
-  return (
-    <div className={cn('relative', containerClassName)}>
-      <Search className="pointer-events-none absolute left-3 top-1/2 z-1 size-3.5 -translate-y-1/2 text-muted-foreground/80" />
-      <Input
-        className={cn(
-          'relative z-0 h-8 rounded-lg py-2 pl-8 text-[length:var(--conversation-text-font-size)]',
-          hasTrailing || loading || value ? 'pr-16' : 'pr-8',
-          inputClassName
-        )}
-        onChange={event => onChange(event.target.value)}
-        placeholder={placeholder}
-        ref={inputRef}
-        value={value}
-      />
-      <div className="absolute right-1.5 top-1/2 z-1 flex -translate-y-1/2 items-center gap-0.5">
-        {trailingAction}
-        {loading ? (
-          <Loader2 className="pointer-events-none size-3.5 animate-spin text-muted-foreground/70" />
-        ) : value ? (
-          <Button
-            aria-label="Clear search"
-            className="text-muted-foreground/85 hover:bg-accent/60 hover:text-foreground"
-            onClick={clear}
-            size="icon-xs"
-            variant="ghost"
-          >
-            <Codicon name="close" size="0.875rem" />
-          </Button>
-        ) : null}
-      </div>
-    </div>
-  )
-}
-
-export function PageSearchInput(props: OverlaySearchInputProps) {
-  return (
-    <OverlaySearchInput
-      {...props}
-      containerClassName={cn('mx-auto w-[min(36rem,calc(100%-2rem))] min-w-0', props.containerClassName)}
-      inputClassName={cn('h-8 rounded-lg py-2 pl-8', props.inputClassName)}
-    />
-  )
-}

apps/desktop/src/app/overlays/overlay-split-layout.tsx

@@ -3,6 +3,8 @@ import type { ReactNode } from 'react'
 import type { IconComponent } from '@/lib/icons'
 import { cn } from '@/lib/utils'
 
+import { PAGE_INSET_X } from '../layout-constants'
+
 interface OverlaySplitLayoutProps {
   children: ReactNode
   className?: string
@@ -22,6 +24,9 @@ interface OverlayNavItemProps {
   active: boolean
   icon: IconComponent
   label: string
+  // Renders as an indented child of another nav item: smaller icon and a
+  // lighter active state so it never competes with the boxed parent item.
+  nested?: boolean
   onClick: () => void
   trailing?: ReactNode
 }
@@ -43,7 +48,9 @@ export function OverlaySidebar({ children, className }: OverlaySidebarProps) {
   return (
     <aside
       className={cn(
-        'flex min-h-0 flex-col gap-0.5 overflow-y-auto bg-(--ui-sidebar-surface-background) px-2.5 py-3',
+        // pt clears the floating titlebar/header; the bg itself fills from the
+        // card's top edge so there's no surface-colored gap above the sidebar.
+        'flex min-h-0 flex-col gap-0.5 overflow-y-auto bg-(--ui-sidebar-surface-background) px-2.5 pb-3 pt-[calc(var(--titlebar-height)+1rem)]',
         className
       )}
     >
@@ -54,23 +61,41 @@ export function OverlaySidebar({ children, className }: OverlaySidebarProps) {
 
 export function OverlayMain({ children, className }: OverlayMainProps) {
   return (
-    <main className={cn('flex min-h-0 flex-1 flex-col overflow-hidden bg-transparent p-3', className)}>{children}</main>
+    <main
+      className={cn(
+        'flex min-h-0 flex-1 flex-col overflow-hidden bg-transparent pb-3 pt-[calc(var(--titlebar-height)+1rem)]',
+        PAGE_INSET_X,
+        className
+      )}
+    >
+      {children}
+    </main>
   )
 }
 
-export function OverlayNavItem({ active, icon: Icon, label, onClick, trailing }: OverlayNavItemProps) {
+export function OverlayNavItem({ active, icon: Icon, label, nested, onClick, trailing }: OverlayNavItemProps) {
   return (
     <button
       className={cn(
         'flex h-7 w-full items-center justify-start gap-2 rounded-md border px-2 text-left text-[length:var(--conversation-text-font-size)] font-normal transition-colors',
-        active
-          ? 'border-(--ui-stroke-tertiary) bg-(--ui-bg-tertiary) text-foreground'
-          : 'border-transparent bg-transparent text-(--ui-text-secondary) hover:bg-(--chrome-action-hover) hover:text-foreground'
+        nested
+          ? active
+            ? 'border-transparent bg-(--chrome-action-hover) font-medium text-foreground'
+            : 'border-transparent bg-transparent text-(--ui-text-tertiary) hover:bg-(--chrome-action-hover) hover:text-foreground'
+          : active
+            ? 'border-(--ui-stroke-tertiary) bg-(--ui-bg-tertiary) text-foreground'
+            : 'border-transparent bg-transparent text-(--ui-text-secondary) hover:bg-(--chrome-action-hover) hover:text-foreground'
       )}
       onClick={onClick}
       type="button"
     >
-      <Icon className={cn('size-4 shrink-0', active ? 'text-foreground/80' : 'text-muted-foreground/80')} />
+      <Icon
+        className={cn(
+          'shrink-0',
+          nested ? 'size-3.5' : 'size-4',
+          active ? 'text-foreground/80' : 'text-muted-foreground/80'
+        )}
+      />
       <span className="min-w-0 flex-1 truncate">{label}</span>
       {trailing}
     </button>

apps/desktop/src/app/overlays/overlay-view.tsx

@@ -64,23 +64,26 @@ export function OverlayView({
       >
         <div className="pointer-events-none absolute inset-x-0 top-0 z-10 h-[calc(var(--titlebar-height)+0.1875rem)] [-webkit-app-region:drag]">
           {headerContent && (
-            <div className="pointer-events-auto absolute left-1/2 top-[calc(1rem+var(--titlebar-height)/2)] -translate-x-1/2 -translate-y-1/2 [-webkit-app-region:no-drag]">
+            <div className="pointer-events-auto absolute left-1/2 top-[calc(0.5rem+var(--titlebar-height)/2)] -translate-x-1/2 -translate-y-1/2 [-webkit-app-region:no-drag]">
               {headerContent}
             </div>
           )}
 
           <Button
             aria-label={closeLabel}
-            className="pointer-events-auto absolute right-3 top-[calc(0.1875rem+var(--titlebar-height)/2)] h-7 w-7 -translate-y-1/2 rounded-md text-(--ui-text-tertiary) hover:bg-(--chrome-action-hover) hover:text-foreground [-webkit-app-region:no-drag]"
+            className="pointer-events-auto absolute right-3 top-[calc(0.1875rem+var(--titlebar-height)/2)] -translate-y-1/2 text-(--ui-text-tertiary) hover:bg-(--chrome-action-hover) hover:text-foreground [-webkit-app-region:no-drag]"
             onClick={closeOverlay}
-            size="icon"
+            size="icon-titlebar"
             variant="ghost"
           >
             <Codicon name="close" size="1rem" />
           </Button>
         </div>
 
-        <div className={cn('min-h-0 flex flex-1 flex-col pt-(--titlebar-height)', contentClassName)}>{children}</div>
+        {/* No top padding here: the split-layout columns own their own
+            titlebar clearance so their backgrounds run flush to the card top
+            (otherwise the card surface shows as a gap above the sidebar). */}
+        <div className={cn('min-h-0 flex flex-1 flex-col', contentClassName)}>{children}</div>
       </div>
     </div>
   )

apps/desktop/src/app/page-search-shell.tsx

@@ -1,26 +1,30 @@
 import type { ReactNode } from 'react'
 
+import { SearchField } from '@/components/ui/search-field'
 import { cn } from '@/lib/utils'
 
-import { PageSearchInput } from './overlays/overlay-search-input'
-
 interface PageSearchShellProps extends React.ComponentProps<'section'> {
   children: ReactNode
+  /** Primary tabs shown on the top row, beside the search. */
+  tabs?: ReactNode
+  /** Secondary filters shown full-width on their own row below (expands). */
   filters?: ReactNode
   onSearchChange: (value: string) => void
   searchPlaceholder: string
-  searchTrailingAction?: ReactNode
   searchValue: string
+  /** Hide the search field when there's nothing to search (empty dataset). */
+  searchHidden?: boolean
 }
 
 export function PageSearchShell({
   children,
   className,
+  tabs,
   filters,
   onSearchChange,
   searchPlaceholder,
-  searchTrailingAction,
   searchValue,
+  searchHidden = false,
   ...props
 }: PageSearchShellProps) {
   return (
@@ -29,29 +33,38 @@ export function PageSearchShell({
       className={cn('flex h-full min-w-0 flex-col overflow-hidden bg-(--ui-chat-surface-background)', className)}
     >
       {/*
-        This header sits in the titlebar row, so it overlaps the OS window-drag
-        region painted by the shell. Without `-webkit-app-region: no-drag` on
-        the search row, mousedown on the input gets intercepted as a window-
-        drag start and the input never receives focus (visible as "I can't
-        click the search box" on the messaging/cron/etc pages).
+        Header lives in the page body, below the window chrome (the shell floats
+        traffic lights over the top titlebar-height strip, which the `pt` clears
+        and leaves draggable). Top row: primary tabs + search. Second row:
+        secondary filters, full-width so they expand. Interactive bits opt out
+        of the drag region.
       */}
-      <div className="relative z-10 grid gap-2 border-b border-(--ui-stroke-tertiary) px-3 py-2.5 [-webkit-app-region:no-drag]">
-        {/* Reserve the top-right titlebar tools + native window-controls
-            footprint so the full-width search input never slides under them. */}
-        <div
-          style={{
-            paddingRight:
-              'max(0px, calc(var(--titlebar-tools-right, 0px) + var(--titlebar-tools-width, 0px) - 0.75rem))'
-          }}
-        >
-          <PageSearchInput
-            onChange={onSearchChange}
-            placeholder={searchPlaceholder}
-            trailingAction={searchTrailingAction}
-            value={searchValue}
-          />
-        </div>
-        {filters ? <div className="flex flex-wrap items-center justify-center gap-1.5">{filters}</div> : null}
+      {/*
+        IMPORTANT: do NOT put `-webkit-app-region: drag` on this header. It spans
+        full width over the band where the floating titlebar icon clusters live,
+        and an overlapping OS drag region eats their clicks at the compositor
+        level (pointer-events / no-drag carve-outs across separate stacking
+        contexts don't reliably fix it on macOS). The shell already supplies a
+        draggable titlebar strip that is `calc()`'d around the icon clusters
+        (see app-shell.tsx), so window dragging still works here.
+      */}
+      <div className="shrink-0">
+        {(tabs || !searchHidden) && (
+          <div className="flex items-center gap-3 px-3 pb-2 pt-[calc(var(--titlebar-height)+0.5rem)]">
+            {tabs ? <div className="flex min-w-0 flex-1 flex-wrap items-center gap-x-2 gap-y-1">{tabs}</div> : null}
+            {!searchHidden && (
+              <div className={cn('flex shrink-0 items-center', !tabs && 'flex-1')}>
+                <SearchField
+                  containerClassName="max-w-[45vw]"
+                  onChange={onSearchChange}
+                  placeholder={searchPlaceholder}
+                  value={searchValue}
+                />
+              </div>
+            )}
+          </div>
+        )}
+        {filters ? <div className="flex flex-wrap items-center gap-x-2 gap-y-1 px-3 pb-2">{filters}</div> : null}
       </div>
       <div className="min-h-0 flex-1 overflow-hidden bg-(--ui-chat-surface-background)">{children}</div>
     </section>

apps/desktop/src/app/profiles/index.tsx

@@ -1,7 +1,7 @@
-import type * as React from 'react'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 
 import { PageLoader } from '@/components/page-loader'
+import { Badge } from '@/components/ui/badge'
 import { Button } from '@/components/ui/button'
 import { Codicon } from '@/components/ui/codicon'
 import {
@@ -28,9 +28,9 @@ import { AlertTriangle, Pencil, Save, Terminal, Trash2, Users } from '@/lib/icon
 import { cn } from '@/lib/utils'
 import { notify, notifyError } from '@/store/notifications'
 
-import type { SetStatusbarItemGroup } from '../shell/statusbar-controls'
-import { titlebarHeaderBaseClass } from '../shell/titlebar'
-import type { SetTitlebarToolGroup } from '../shell/titlebar-controls'
+import { useRefreshHotkey } from '../hooks/use-refresh-hotkey'
+import { OverlayMain, OverlaySidebar, OverlaySplitLayout } from '../overlays/overlay-split-layout'
+import { OverlayView } from '../overlays/overlay-view'
 
 const PROFILE_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/
 
@@ -40,26 +40,18 @@ function isValidProfileName(name: string): boolean {
   return PROFILE_NAME_RE.test(name.trim())
 }
 
-interface ProfilesViewProps extends React.ComponentProps<'section'> {
-  setStatusbarItemGroup?: SetStatusbarItemGroup
-  setTitlebarToolGroup?: SetTitlebarToolGroup
+interface ProfilesViewProps {
+  onClose: () => void
 }
 
-export function ProfilesView({
-  setStatusbarItemGroup: _setStatusbarItemGroup,
-  setTitlebarToolGroup,
-  ...props
-}: ProfilesViewProps) {
+export function ProfilesView({ onClose }: ProfilesViewProps) {
   const [profiles, setProfiles] = useState<null | ProfileInfo[]>(null)
-  const [refreshing, setRefreshing] = useState(false)
   const [selectedName, setSelectedName] = useState<null | string>(null)
   const [createOpen, setCreateOpen] = useState(false)
   const [pendingDelete, setPendingDelete] = useState<null | ProfileInfo>(null)
   const [deleting, setDeleting] = useState(false)
 
   const refresh = useCallback(async () => {
-    setRefreshing(true)
-
     try {
       const { profiles: list } = await getProfiles()
       setProfiles(list)
@@ -72,33 +64,15 @@ export function ProfilesView({
       })
     } catch (err) {
       notifyError(err, 'Failed to load profiles')
-    } finally {
-      setRefreshing(false)
     }
   }, [])
 
+  useRefreshHotkey(refresh)
+
   useEffect(() => {
     void refresh()
   }, [refresh])
 
-  useEffect(() => {
-    if (!setTitlebarToolGroup) {
-      return
-    }
-
-    setTitlebarToolGroup('profiles', [
-      {
-        disabled: refreshing,
-        icon: <Codicon name="refresh" spinning={refreshing} />,
-        id: 'refresh-profiles',
-        label: refreshing ? 'Refreshing profiles' : 'Refresh profiles',
-        onSelect: () => void refresh()
-      }
-    ])
-
-    return () => setTitlebarToolGroup('profiles', [])
-  }, [refresh, refreshing, setTitlebarToolGroup])
-
   const selected = useMemo(() => {
     if (!profiles) {
       return null
@@ -164,62 +138,56 @@ export function ProfilesView({
   }, [pendingDelete, refresh])
 
   return (
-    <section {...props} className="flex h-full min-w-0 flex-col overflow-hidden rounded-b-[0.9375rem] bg-background">
-      <header className={titlebarHeaderBaseClass}>
-        <h2 className="pointer-events-auto text-base font-semibold leading-none tracking-tight">Profiles</h2>
-        <span className="pointer-events-auto text-xs text-muted-foreground">
-          {profiles ? `${profiles.length} ${profiles.length === 1 ? 'profile' : 'profiles'}` : ''}
-        </span>
-      </header>
+    <OverlayView closeLabel="Close profiles" onClose={onClose}>
+      {!profiles ? (
+        <PageLoader label="Loading profiles..." />
+      ) : (
+        <OverlaySplitLayout>
+          <OverlaySidebar>
+            <div className="mb-1 flex items-center justify-between gap-2 pl-1.5 pr-0.5">
+              <span className="text-[0.7rem] font-semibold uppercase tracking-wider text-(--ui-text-tertiary)">
+                Profiles
+              </span>
+              <Button
+                aria-label="New profile"
+                className="text-(--ui-text-tertiary) hover:bg-(--ui-control-hover-background) hover:text-foreground"
+                onClick={() => setCreateOpen(true)}
+                size="icon-xs"
+                variant="ghost"
+              >
+                <Codicon name="add" size="0.875rem" />
+              </Button>
+            </div>
+            {profiles.map(profile => (
+              <ProfileRow
+                active={selected?.name === profile.name}
+                key={profile.name}
+                onSelect={() => setSelectedName(profile.name)}
+                profile={profile}
+              />
+            ))}
+            {profiles.length === 0 && <p className="px-1.5 py-3 text-xs text-muted-foreground">No profiles yet.</p>}
+          </OverlaySidebar>
 
-      <div className="min-h-0 flex-1 overflow-hidden rounded-b-[1.0625rem] border border-border/50 bg-background/85">
-        {!profiles ? (
-          <PageLoader label="Loading profiles..." />
-        ) : (
-          <div className="grid h-full min-h-0 grid-cols-1 lg:grid-cols-[16rem_minmax(0,1fr)]">
-            <aside className="flex min-h-0 flex-col overflow-hidden border-b border-border/50 lg:border-b-0 lg:border-r">
-              <div className="border-b border-border/40 p-2">
-                <Button className="w-full" onClick={() => setCreateOpen(true)} size="sm">
-                  <Codicon name="add" />
-                  New profile
-                </Button>
-              </div>
-              <ul className="min-h-0 flex-1 space-y-1 overflow-y-auto p-2">
-                {profiles.map(profile => (
-                  <li key={profile.name}>
-                    <ProfileRow
-                      active={selected?.name === profile.name}
-                      onSelect={() => setSelectedName(profile.name)}
-                      profile={profile}
-                    />
-                  </li>
-                ))}
-                {profiles.length === 0 && (
-                  <li className="px-2 py-4 text-center text-xs text-muted-foreground">No profiles yet.</li>
-                )}
-              </ul>
-            </aside>
-
-            <main className="min-h-0 overflow-hidden">
-              {selected ? (
-                <ProfileDetail
-                  key={selected.name}
-                  onDelete={() => setPendingDelete(selected)}
-                  onRename={newName => handleRename(selected.name, newName)}
-                  profile={selected}
-                />
-              ) : (
-                <div className="grid h-full place-items-center px-6 py-12 text-center text-sm text-muted-foreground">
-                  <div>
-                    <Users className="mx-auto size-6 text-muted-foreground/60" />
-                    <p className="mt-3">Select a profile to view its details.</p>
-                  </div>
+          <OverlayMain className="px-0">
+            {selected ? (
+              <ProfileDetail
+                key={selected.name}
+                onDelete={() => setPendingDelete(selected)}
+                onRename={newName => handleRename(selected.name, newName)}
+                profile={selected}
+              />
+            ) : (
+              <div className="grid h-full place-items-center px-6 py-12 text-center text-sm text-muted-foreground">
+                <div>
+                  <Users className="mx-auto size-6 text-muted-foreground/60" />
+                  <p className="mt-3">Select a profile to view its details.</p>
                 </div>
-              )}
-            </main>
-          </div>
-        )}
-      </div>
+              </div>
+            )}
+          </OverlayMain>
+        </OverlaySplitLayout>
+      )}
 
       <CreateProfileDialog
         onClose={() => setCreateOpen(false)}
@@ -250,7 +218,7 @@ export function ProfilesView({
           </DialogFooter>
         </DialogContent>
       </Dialog>
-    </section>
+    </OverlayView>
   )
 }
 
@@ -258,8 +226,10 @@ function ProfileRow({ active, onSelect, profile }: { active: boolean; onSelect:
   return (
     <button
       className={cn(
-        'flex w-full flex-col items-start gap-1 rounded-lg px-2.5 py-2 text-left transition-colors',
-        active ? 'bg-accent text-foreground' : 'text-foreground/85 hover:bg-accent/60'
+        'flex w-full flex-col items-start gap-0.5 rounded-md px-2 py-1.5 text-left transition-colors',
+        active
+          ? 'bg-(--ui-row-active-background) text-foreground'
+          : 'text-(--ui-text-secondary) hover:bg-(--ui-row-hover-background) hover:text-foreground'
       )}
       onClick={onSelect}
       type="button"
@@ -311,38 +281,30 @@ function ProfileDetail({
               <div className="min-w-0">
                 <div className="flex flex-wrap items-center gap-2">
                   <h3 className="text-xl font-semibold tracking-tight">{profile.name}</h3>
-                  {profile.is_default && (
-                    <span className="rounded-full bg-primary/10 px-2 py-0.5 text-[0.65rem] font-medium text-primary">
-                      Default
-                    </span>
-                  )}
-                  {profile.has_env && (
-                    <span className="rounded-full bg-muted px-2 py-0.5 text-[0.65rem] font-medium text-muted-foreground">
-                      .env
-                    </span>
-                  )}
+                  {profile.is_default && <Badge>Default</Badge>}
+                  {profile.has_env && <Badge variant="muted">.env</Badge>}
                 </div>
                 <p className="mt-1 font-mono text-[0.7rem] text-muted-foreground" title={profile.path}>
                   {profile.path}
                 </p>
               </div>
-              <div className="flex shrink-0 items-center gap-1">
+              <div className="flex shrink-0 items-center gap-3">
                 {!profile.is_default && (
-                  <Button onClick={() => setRenameOpen(true)} size="sm" variant="outline">
+                  <Button onClick={() => setRenameOpen(true)} size="sm" variant="text">
                     <Pencil />
                     Rename
                   </Button>
                 )}
-                <Button disabled={copying} onClick={() => void handleCopySetup()} size="sm" variant="outline">
+                <Button disabled={copying} onClick={() => void handleCopySetup()} size="sm" variant="text">
                   <Terminal />
                   {copying ? 'Copying...' : 'Copy setup'}
                 </Button>
                 {!profile.is_default && (
                   <Button
-                    className="text-muted-foreground hover:bg-destructive/10 hover:text-destructive"
+                    className="hover:text-destructive hover:no-underline"
                     onClick={onDelete}
                     size="sm"
-                    variant="ghost"
+                    variant="text"
                   >
                     <Trash2 />
                     Delete
@@ -351,7 +313,7 @@ function ProfileDetail({
               </div>
             </div>
 
-            <dl className="grid gap-2 rounded-lg border border-border/40 bg-background/70 px-3 py-3 text-xs sm:grid-cols-2">
+            <dl className="grid gap-2 text-xs sm:grid-cols-2">
               <DetailRow label="Model">
                 {profile.model ? (
                   <>
@@ -387,7 +349,7 @@ function DetailRow({ children, label }: { children: React.ReactNode; label: stri
   return (
     <div className="flex flex-wrap items-baseline gap-2">
       <dt className="text-[0.65rem] font-semibold uppercase tracking-[0.12em] text-muted-foreground">{label}</dt>
-      <dd className="text-sm text-foreground">{children}</dd>
+      <dd className="text-xs text-foreground">{children}</dd>
     </div>
   )
 }
@@ -458,9 +420,7 @@ function SoulEditor({ profileName }: { profileName: string }) {
       </div>
 
       {loading ? (
-        <div className="grid h-44 place-items-center rounded-md border border-border/40 bg-background/60 text-xs text-muted-foreground">
-          Loading SOUL.md...
-        </div>
+        <PageLoader className="min-h-44" label="Loading SOUL.md" />
       ) : (
         <Textarea
           className="min-h-72 font-mono text-xs leading-5"

apps/desktop/src/app/right-sidebar/files/tree.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useRef, useState } from 'react'
 import { type NodeApi, type NodeRendererProps, Tree, type TreeApi } from 'react-arborist'
 
+import { PageLoader } from '@/components/page-loader'
 import { Codicon } from '@/components/ui/codicon'
 import { useResizeObserver } from '@/hooks/use-resize-observer'
 import { cn } from '@/lib/utils'
@@ -121,11 +122,7 @@ export function ProjectTree({
 }
 
 function TreeSizingState() {
-  return (
-    <div className="flex h-full min-h-24 items-center justify-center px-3 text-[0.68rem] text-(--ui-text-tertiary)">
-      Loading files...
-    </div>
-  )
+  return <PageLoader aria-label="Loading files" className="min-h-24 px-3" />
 }
 
 function ProjectTreeRow({

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

@@ -7,6 +7,7 @@ import { Codicon } from '@/components/ui/codicon'
 import { Loader } from '@/components/ui/loader'
 import { normalizeOrLocalPreviewTarget } from '@/lib/local-preview'
 import { cn } from '@/lib/utils'
+import { $panesFlipped } from '@/store/layout'
 import { notifyError } from '@/store/notifications'
 import { setCurrentSessionPreviewTarget } from '@/store/preview'
 import { $currentBranch, $currentCwd } from '@/store/session'
@@ -31,17 +32,14 @@ interface RightSidebarTab {
 }
 
 const RIGHT_SIDEBAR_TABS: readonly RightSidebarTab[] = [
-  { id: 'files', label: 'File system', icon: 'files' },
+  { id: 'files', label: 'File system', icon: 'list-tree' },
   { id: 'terminal', label: 'Terminal', icon: 'terminal' }
 ]
 
-export function RightSidebarPane({
-  onActivateFile,
-  onActivateFolder,
-  onChangeCwd
-}: RightSidebarPaneProps) {
+export function RightSidebarPane({ onActivateFile, onActivateFolder, onChangeCwd }: RightSidebarPaneProps) {
   const activeTab = useStore($rightSidebarTab)
   const terminalTakeover = useStore($terminalTakeover)
+  const panesFlipped = useStore($panesFlipped)
   const currentBranch = useStore($currentBranch).trim()
   const currentCwd = useStore($currentCwd).trim()
   const hasCwd = currentCwd.length > 0
@@ -53,8 +51,17 @@ export function RightSidebarPane({
         .pop() ?? currentCwd)
     : 'No folder selected'
 
-  const { collapseAll, collapseNonce, data, loadChildren, openState, refreshRoot, rootError, rootLoading, setNodeOpen } =
-    useProjectTree(currentCwd)
+  const {
+    collapseAll,
+    collapseNonce,
+    data,
+    loadChildren,
+    openState,
+    refreshRoot,
+    rootError,
+    rootLoading,
+    setNodeOpen
+  } = useProjectTree(currentCwd)
 
   const canCollapse = Object.values(openState).some(Boolean)
   const effectiveTab: RightSidebarTabId = terminalTakeover ? 'files' : activeTab
@@ -86,14 +93,17 @@ export function RightSidebarPane({
     }
   }
 
-  const tabs = terminalTakeover
-    ? RIGHT_SIDEBAR_TABS.filter(tab => tab.id !== 'terminal')
-    : RIGHT_SIDEBAR_TABS
+  const tabs = terminalTakeover ? RIGHT_SIDEBAR_TABS.filter(tab => tab.id !== 'terminal') : RIGHT_SIDEBAR_TABS
 
   return (
     <aside
       aria-label="Right sidebar"
-      className="before:pointer-events-none relative flex h-full w-full min-w-0 flex-col overflow-hidden border-l border-(--ui-stroke-secondary) bg-(--ui-sidebar-surface-background) pt-(--titlebar-height) text-(--ui-text-tertiary) shadow-[inset_0.0625rem_0_0_color-mix(in_srgb,white_18%,transparent)] before:absolute before:inset-x-0 before:top-(--titlebar-height) before:z-1 before:h-px before:bg-(--ui-stroke-tertiary)"
+      className={cn(
+        'before:pointer-events-none relative flex h-full w-full min-w-0 flex-col overflow-hidden border-(--ui-stroke-secondary) bg-(--ui-sidebar-surface-background) pt-(--titlebar-height) text-(--ui-text-tertiary)',
+        panesFlipped
+          ? 'border-r shadow-[inset_-0.0625rem_0_0_color-mix(in_srgb,white_18%,transparent)]'
+          : 'border-l shadow-[inset_0.0625rem_0_0_color-mix(in_srgb,white_18%,transparent)]'
+      )}
     >
       <RightSidebarChrome activeTab={effectiveTab} branch={currentBranch} tabs={tabs} />
 
@@ -135,26 +145,27 @@ function RightSidebarChrome({
 }) {
   return (
     <header className="shrink-0 bg-transparent text-[0.75rem]">
-      <div className="flex items-center gap-2 border-b border-(--ui-stroke-tertiary) px-2.5 py-1">
+      <div className="flex items-center gap-2 px-2.5 py-1">
         <nav aria-label="Right sidebar panels" className="flex min-w-0 items-center gap-1">
           {tabs.map(tab => (
-            <button
+            <Button
               aria-label={tab.label}
               aria-pressed={tab.id === activeTab}
               className={cn(
-                'grid size-6 shrink-0 place-items-center rounded-lg text-(--ui-text-tertiary) transition-colors hover:bg-(--ui-control-hover-background) hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sidebar-ring active:bg-(--ui-control-active-background) active:text-foreground',
-                'data-[active=true]:bg-(--ui-control-active-background) data-[active=true]:text-foreground'
+                'text-(--ui-text-tertiary) hover:bg-(--ui-control-hover-background) hover:text-foreground',
+                tab.id === activeTab && 'bg-(--ui-control-active-background) text-foreground'
               )}
-              data-active={tab.id === activeTab}
               key={tab.id}
               onClick={() => setRightSidebarTab(tab.id)}
+              size="icon-xs"
               title={tab.label}
-              type="button"
+              variant="ghost"
             >
               <Codicon name={tab.icon} size="0.875rem" />
-            </button>
+            </Button>
           ))}
         </nav>
+
         {branch && (
           <span className="ml-auto flex min-w-0 items-center gap-1 text-[0.6875rem] text-(--ui-text-tertiary)">
             <Codicon className="shrink-0" name="git-branch" size="0.75rem" />
@@ -175,8 +186,11 @@ interface FilesystemTabProps extends FileTreeBodyProps {
   onRefresh: () => void
 }
 
+// Sidebar-specific color/hover treatment only — size, radius, cursor and the
+// base focus ring come from <Button size="icon-xs">. This constant exists
+// purely to share the sidebar palette + the hover-reveal behavior below.
 const HEADER_ACTION_CLASS =
-  'size-6 shrink-0 rounded-md text-sidebar-foreground/70 transition-colors hover:bg-sidebar-accent! hover:text-sidebar-accent-foreground! focus-visible:ring-2 focus-visible:ring-sidebar-ring'
+  'text-sidebar-foreground/70 hover:bg-sidebar-accent! hover:text-sidebar-accent-foreground! focus-visible:ring-sidebar-ring'
 
 const HEADER_ACTION_REVEAL_CLASS = `${HEADER_ACTION_CLASS} pointer-events-none opacity-0 transition-opacity focus-visible:opacity-100 group-focus-within/project-header:pointer-events-auto group-focus-within/project-header:opacity-100 group-hover/project-header:pointer-events-auto group-hover/project-header:opacity-100`
 
@@ -210,11 +224,22 @@ function FilesystemTab({
         >
           <SidebarPanelLabel>{cwdName}</SidebarPanelLabel>
         </button>
+        <Button
+          aria-label="Refresh tree"
+          className={HEADER_ACTION_CLASS}
+          disabled={!hasCwd || loading}
+          onClick={onRefresh}
+          size="icon-xs"
+          title="Refresh tree"
+          variant="ghost"
+        >
+          <Codicon name="refresh" size="0.8125rem" spinning={loading} />
+        </Button>
         <Button
           aria-label="Open folder"
           className={HEADER_ACTION_CLASS}
           onClick={() => void onChangeFolder()}
-          size="icon"
+          size="icon-xs"
           title={hasCwd ? 'Open a different folder' : 'Open a folder'}
           variant="ghost"
         >
@@ -225,23 +250,12 @@ function FilesystemTab({
           className={HEADER_ACTION_REVEAL_CLASS}
           disabled={!hasCwd || !canCollapse}
           onClick={onCollapseAll}
-          size="icon"
+          size="icon-xs"
           title="Collapse all folders"
           variant="ghost"
         >
           <Codicon name="collapse-all" size="0.8125rem" />
         </Button>
-        <Button
-          aria-label="Refresh tree"
-          className={HEADER_ACTION_REVEAL_CLASS}
-          disabled={!hasCwd || loading}
-          onClick={onRefresh}
-          size="icon"
-          title="Refresh tree"
-          variant="ghost"
-        >
-          <Codicon name="refresh" size="0.8125rem" spinning={loading} />
-        </Button>
       </RightSidebarSectionHeader>
       <FileTreeBody
         collapseNonce={collapseNonce}
@@ -261,7 +275,7 @@ function FilesystemTab({
 }
 
 export function RightSidebarSectionHeader({ children }: { children: ReactNode }) {
-  return <div className="flex h-7 shrink-0 items-center px-2">{children}</div>
+  return <div className="flex h-7 shrink-0 items-center px-2.5">{children}</div>
 }
 
 interface FileTreeBodyProps {

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

@@ -31,6 +31,7 @@ export function TerminalTab({ cwd, onAddSelectionToChat }: TerminalTabProps) {
     if (takeover) {
       setRightSidebarTab('terminal')
     }
+
     setTerminalTakeover(!takeover)
   }
 

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

@@ -1,9 +1,10 @@
 import { useStore } from '@nanostores/react'
 import { atom } from 'nanostores'
-import { useEffect, useLayoutEffect, useRef, useState, type CSSProperties } from 'react'
+import { type CSSProperties, useEffect, useLayoutEffect, useRef, useState } from 'react'
+
+import { TERMINAL_BG } from './selection'
 
 import { TerminalTab } from './index'
-import { TERMINAL_BG } from './selection'
 
 /**
  * One xterm Terminal mounted at the layout root and CSS-overlayed onto
@@ -21,11 +22,17 @@ export function TerminalSlot({ className = SLOT_CLASS }: { className?: string })
 
   useEffect(() => {
     const el = ref.current
-    if (!el) return
+
+    if (!el) {
+      return
+    }
 
     $slot.set(el)
+
     return () => {
-      if ($slot.get() === el) $slot.set(null)
+      if ($slot.get() === el) {
+        $slot.set(null)
+      }
     }
   }, [])
 
@@ -55,6 +62,7 @@ export function PersistentTerminal({ cwd, onAddSelectionToChat }: PersistentTerm
   useLayoutEffect(() => {
     if (!slot) {
       setRect(null)
+
       return
     }
 
@@ -72,13 +80,17 @@ export function PersistentTerminal({ cwd, onAddSelectionToChat }: PersistentTerm
       if (!sameRect(prev, next)) {
         prev = next
         setRect(next)
-        if (next.width > 0 && next.height > 0) setReady(true)
+
+        if (next.width > 0 && next.height > 0) {
+          setReady(true)
+        }
       }
 
       frame = requestAnimationFrame(tick)
     }
 
     tick()
+
     return () => cancelAnimationFrame(frame)
   }, [slot])
 

apps/desktop/src/app/right-sidebar/terminal/use-terminal-session.ts

@@ -96,11 +96,18 @@ interface UseTerminalSessionOptions {
 }
 
 function transferHasDropCandidates(t: DataTransfer): boolean {
-  if (t.types?.includes(HERMES_PATHS_MIME)) return true
-  if ((t.files?.length ?? 0) > 0) return true
+  if (t.types?.includes(HERMES_PATHS_MIME)) {
+    return true
+  }
+
+  if ((t.files?.length ?? 0) > 0) {
+    return true
+  }
 
   for (let i = 0; i < (t.items?.length ?? 0); i += 1) {
-    if (t.items[i]?.kind === 'file') return true
+    if (t.items[i]?.kind === 'file') {
+      return true
+    }
   }
 
   return false
@@ -108,22 +115,38 @@ function transferHasDropCandidates(t: DataTransfer): boolean {
 
 function collectDroppedPaths(t: DataTransfer): string[] {
   const seen = new Set<string>()
+
   const push = (value: unknown) => {
-    if (typeof value !== 'string') return
+    if (typeof value !== 'string') {
+      return
+    }
+
     const path = value.trim()
-    if (path) seen.add(path)
+
+    if (path) {
+      seen.add(path)
+    }
   }
 
   try {
     const raw = t.getData(HERMES_PATHS_MIME)
-    if (raw) for (const entry of JSON.parse(raw) as { path?: unknown }[]) push(entry?.path)
+
+    if (raw) {
+      for (const entry of JSON.parse(raw) as { path?: unknown }[]) {
+        push(entry?.path)
+      }
+    }
   } catch {
     // Malformed in-app drag payload — fall through to OS files.
   }
 
   const getPath = window.hermesDesktop?.getPathForFile
+
   const addFile = (file: File | null) => {
-    if (!file || !getPath) return
+    if (!file || !getPath) {
+      return
+    }
+
     try {
       push(getPath(file))
     } catch {
@@ -131,10 +154,16 @@ function collectDroppedPaths(t: DataTransfer): string[] {
     }
   }
 
-  for (let i = 0; i < (t.files?.length ?? 0); i += 1) addFile(t.files.item(i))
+  for (let i = 0; i < (t.files?.length ?? 0); i += 1) {
+    addFile(t.files.item(i))
+  }
+
   for (let i = 0; i < (t.items?.length ?? 0); i += 1) {
     const item = t.items[i]
-    if (item?.kind === 'file') addFile(item.getAsFile())
+
+    if (item?.kind === 'file') {
+      addFile(item.getAsFile())
+    }
   }
 
   return [...seen]
@@ -142,8 +171,15 @@ function collectDroppedPaths(t: DataTransfer): string[] {
 
 function quotePathForShell(path: string, shellName: string): string {
   const shell = shellName.toLowerCase()
-  if (shell.includes('powershell') || shell.includes('pwsh')) return `'${path.replace(/'/g, "''")}'`
-  if (shell.includes('cmd')) return `"${path.replace(/"/g, '""')}"`
+
+  if (shell.includes('powershell') || shell.includes('pwsh')) {
+    return `'${path.replace(/'/g, "''")}'`
+  }
+
+  if (shell.includes('cmd')) {
+    return `"${path.replace(/"/g, '""')}"`
+  }
+
   return `'${path.replace(/'/g, "'\\''")}'`
 }
 
@@ -250,12 +286,14 @@ export function useTerminalSession({ cwd, onAddSelectionToChat }: UseTerminalSes
       webgl.onContextLoss(() => webgl.dispose())
       term.loadAddon(webgl)
     } catch (err) {
-      // eslint-disable-next-line no-console
       console.warn('[hermes-terminal] WebGL unavailable; falling back to DOM', err)
     }
 
     const onDragOver = (e: DragEvent) => {
-      if (!e.dataTransfer || !transferHasDropCandidates(e.dataTransfer)) return
+      if (!e.dataTransfer || !transferHasDropCandidates(e.dataTransfer)) {
+        return
+      }
+
       e.preventDefault()
       e.stopPropagation()
       e.dataTransfer.dropEffect = 'copy'
@@ -263,11 +301,19 @@ export function useTerminalSession({ cwd, onAddSelectionToChat }: UseTerminalSes
 
     const onDrop = (e: DragEvent) => {
       const id = sessionIdRef.current
-      if (!id || !e.dataTransfer || !transferHasDropCandidates(e.dataTransfer)) return
+
+      if (!id || !e.dataTransfer || !transferHasDropCandidates(e.dataTransfer)) {
+        return
+      }
+
       e.preventDefault()
       e.stopPropagation()
       const paths = collectDroppedPaths(e.dataTransfer)
-      if (!paths.length) return
+
+      if (!paths.length) {
+        return
+      }
+
       void terminalApi.write(id, `${paths.map(p => quotePathForShell(p, shellNameRef.current)).join(' ')} `)
       term.focus()
       triggerHaptic('selection')
@@ -305,11 +351,18 @@ export function useTerminalSession({ cwd, onAddSelectionToChat }: UseTerminalSes
     // synchronously while sibling panes are mid-transition (e.g. file browser
     // collapsing to 0px) crashes the WebGL renderer mid texture-atlas rebuild.
     let pendingFrame = 0
+
     const scheduleResize = () => {
-      if (pendingFrame) return
+      if (pendingFrame) {
+        return
+      }
+
       pendingFrame = window.requestAnimationFrame(() => {
         pendingFrame = 0
-        if (!disposed) fitAndResize()
+
+        if (!disposed) {
+          fitAndResize()
+        }
       })
     }
 
@@ -317,7 +370,10 @@ export function useTerminalSession({ cwd, onAddSelectionToChat }: UseTerminalSes
     resizeObserver.observe(host)
     cleanup.push(() => {
       resizeObserver.disconnect()
-      if (pendingFrame) window.cancelAnimationFrame(pendingFrame)
+
+      if (pendingFrame) {
+        window.cancelAnimationFrame(pendingFrame)
+      }
     })
 
     const dataDisposable = term.onData(data => {

apps/desktop/src/app/routes.ts

@@ -52,6 +52,15 @@ export const APP_ROUTES = [
 const APP_VIEW_BY_PATH = new Map<string, AppView>(APP_ROUTES.map(route => [route.path, route.view]))
 const RESERVED_PATHS: ReadonlySet<string> = new Set(APP_ROUTES.map(route => route.path))
 
+// Views that render as a full-screen modal card (OverlayView) over the shell.
+// While one is open the app's titlebar control clusters must hide so they don't
+// bleed over the overlay (they sit at a higher z-index than the overlay card).
+export const OVERLAY_VIEWS: ReadonlySet<AppView> = new Set(['agents', 'command-center', 'cron', 'profiles', 'settings'])
+
+export function isOverlayView(view: AppView): boolean {
+  return OVERLAY_VIEWS.has(view)
+}
+
 export function isNewChatRoute(pathname: string): boolean {
   return pathname === NEW_CHAT_ROUTE
 }

apps/desktop/src/app/session/hooks/use-message-stream.ts

@@ -19,6 +19,7 @@ import { isProviderSetupErrorMessage } from '@/lib/provider-setup-errors'
 import { setClarifyRequest } from '@/store/clarify'
 import { notify } from '@/store/notifications'
 import { requestDesktopOnboarding } from '@/store/onboarding'
+import { clearAllPrompts, setApprovalRequest, setSecretRequest, setSudoRequest } from '@/store/prompts'
 import {
   setCurrentBranch,
   setCurrentCwd,
@@ -29,7 +30,8 @@ import {
   setCurrentReasoningEffort,
   setCurrentServiceTier,
   setCurrentUsage,
-  setTurnStartedAt
+  setTurnStartedAt,
+  setYoloActive
 } from '@/store/session'
 import { clearSessionSubagents, pruneDelegateFallbackSubagents, upsertSubagent } from '@/store/subagents'
 import { recordToolDiff } from '@/store/tool-diffs'
@@ -311,6 +313,7 @@ export function useMessageStream({
     // commit and the synthetic harness shows longtask counts drop from ~5/5s
     // to ~1/5s on big sessions (see scripts/profile-typing-lag.md).
     const sinceLast = performance.now() - lastFlushAtRef.current
+
     const runFlush = () => {
       flushHandleRef.current = null
       lastFlushAtRef.current = performance.now()
@@ -323,10 +326,7 @@ export function useMessageStream({
       return
     }
 
-    flushHandleRef.current = window.setTimeout(
-      runFlush,
-      Math.max(0, STREAM_DELTA_FLUSH_MS - sinceLast)
-    )
+    flushHandleRef.current = window.setTimeout(runFlush, Math.max(0, STREAM_DELTA_FLUSH_MS - sinceLast))
   }, [flushQueuedDeltas])
 
   const queueDelta = useCallback(
@@ -529,7 +529,8 @@ export function useMessageStream({
           streamId: null,
           pendingBranchGroup: null,
           awaitingResponse: false,
-          busy: false
+          busy: false,
+          needsInput: false
         }
       })
 
@@ -586,7 +587,8 @@ export function useMessageStream({
           pendingBranchGroup: null,
           sawAssistantPayload: true,
           awaitingResponse: false,
-          busy: false
+          busy: false,
+          needsInput: false
         }
       })
     },
@@ -655,6 +657,10 @@ export function useMessageStream({
             setCurrentFastMode(payload.fast)
           }
 
+          if (typeof payload?.yolo === 'boolean') {
+            setYoloActive(payload.yolo)
+          }
+
           if (runningChanged && sessionId) {
             updateSessionState(sessionId, state => {
               const busy = Boolean(payload!.running)
@@ -746,6 +752,13 @@ export function useMessageStream({
           return
         }
 
+        // Turn ended — drop any blocking prompt that's still open (e.g. the
+        // agent was interrupted, or the approval already resolved). Prevents a
+        // stale overlay from outliving the turn that raised it.
+        if (isActiveEvent) {
+          clearAllPrompts()
+        }
+
         flushQueuedDeltas(sessionId)
 
         if (isActiveEvent) {
@@ -773,6 +786,11 @@ export function useMessageStream({
         if (sessionId) {
           flushQueuedDeltas(sessionId)
           upsertToolCall(sessionId, toTodoPayload(payload) ?? payload, 'complete', event.type)
+          // A pending clarify blocks the turn, so the first tool.complete after
+          // one is the clarify resolving — drop the "needs input" flag here so
+          // the sidebar indicator clears as soon as it's answered, not only at
+          // message.complete.
+          updateSessionState(sessionId, state => (state.needsInput ? { ...state, needsInput: false } : state))
         }
 
         if (typeof payload?.inline_diff === 'string' && payload.inline_diff.trim()) {
@@ -793,13 +811,16 @@ export function useMessageStream({
           )
         }
       } else if (event.type === 'clarify.request') {
-        if (!isActiveEvent) {
-          return
-        }
-
         // Surface the clarify tool's overlay. The Python side is blocked on
         // `clarify.respond`, so without this handler the agent would hang
         // forever (see tools/clarify_tool.py + tui_gateway/server.py:_block).
+        //
+        // Store the request for whichever session raised it — even a background
+        // one. clarify.request is a one-shot event; if we dropped it for an
+        // unfocused session, that session would block on `clarify.respond`
+        // indefinitely and re-focusing it could never recover (the event is
+        // gone). Parking it per-session lets the user answer once they switch
+        // over; the inline ClarifyTool reads the active session's entry.
         const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
         const question = typeof payload?.question === 'string' ? payload.question : ''
 
@@ -810,11 +831,70 @@ export function useMessageStream({
             choices: Array.isArray(payload?.choices) ? payload!.choices!.filter(c => typeof c === 'string') : null,
             sessionId: sessionId ?? null
           })
+
+          // The transcript only renders the active session, so a background
+          // clarify is otherwise invisible (the row just keeps spinning like
+          // it's working). Flag the session so the sidebar shows a persistent
+          // "needs input" indicator on its row — works for the active session
+          // too, and survives alt-tab / window blur (unlike a toast).
+          if (sessionId) {
+            updateSessionState(sessionId, state => ({ ...state, needsInput: true }))
+          }
+        }
+      } else if (event.type === 'approval.request') {
+        if (!isActiveEvent) {
+          return
+        }
+
+        // Dangerous-command / execute_code approval. The Python side is
+        // blocked in _await_gateway_decision() until approval.respond lands;
+        // without this the agent stalls until its 5-min timeout and the tool
+        // is BLOCKED. Approval is session-keyed (no request_id) — the overlay
+        // sends back {choice, session_id}.
+        setApprovalRequest({
+          command: typeof payload?.command === 'string' ? payload.command : '',
+          description: typeof payload?.description === 'string' ? payload.description : 'dangerous command',
+          sessionId: sessionId ?? null
+        })
+      } else if (event.type === 'sudo.request') {
+        if (!isActiveEvent) {
+          return
+        }
+
+        // Sudo password capture (tools/terminal_tool.py). Blocked on
+        // sudo.respond {request_id, password}.
+        const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
+
+        if (requestId) {
+          setSudoRequest({ requestId })
+        }
+      } else if (event.type === 'secret.request') {
+        if (!isActiveEvent) {
+          return
+        }
+
+        // Skill credential capture (tools/skills_tool.py). Blocked on
+        // secret.respond {request_id, value}.
+        const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
+
+        if (requestId) {
+          setSecretRequest({
+            requestId,
+            envVar: typeof payload?.env_var === 'string' ? payload.env_var : '',
+            prompt: typeof payload?.prompt === 'string' ? payload.prompt : ''
+          })
         }
       } else if (event.type === 'error') {
         const errorMessage = payload?.message || 'Hermes reported an error'
         const looksLikeProviderSetup = isProviderSetupErrorMessage(errorMessage)
 
+        // A turn that errors out has also ended — drop any open blocking
+        // prompt so an approval/sudo/secret overlay can't linger past the
+        // failed turn (same intent as the message.complete clear).
+        if (isActiveEvent) {
+          clearAllPrompts()
+        }
+
         if (looksLikeProviderSetup) {
           requestDesktopOnboarding(errorMessage)
         } else if (isActiveEvent) {

apps/desktop/src/app/session/hooks/use-prompt-actions.ts

@@ -18,7 +18,9 @@ import {
   isDesktopSlashCommand
 } from '@/lib/desktop-slash-commands'
 import { triggerHaptic } from '@/lib/haptics'
+import { setMutableRef } from '@/lib/mutable-ref'
 import { isProviderSetupErrorMessage } from '@/lib/provider-setup-errors'
+import { setSessionYolo } from '@/lib/yolo-session'
 import {
   $composerAttachments,
   addComposerAttachment,
@@ -28,7 +30,15 @@ import {
 } from '@/store/composer'
 import { clearNotifications, notify, notifyError } from '@/store/notifications'
 import { requestDesktopOnboarding } from '@/store/onboarding'
-import { $busy, $messages, setAwaitingResponse, setBusy, setMessages } from '@/store/session'
+import {
+  $busy,
+  $messages,
+  $yoloActive,
+  setAwaitingResponse,
+  setBusy,
+  setMessages,
+  setYoloActive
+} from '@/store/session'
 
 import type { ClientSessionState, ImageAttachResponse, SlashExecResponse } from '../../types'
 
@@ -237,7 +247,7 @@ export function usePromptActions({
       }
 
       const releaseBusy = () => {
-        busyRef.current = false
+        setMutableRef(busyRef, false)
         setBusy(false)
         setAwaitingResponse(false)
       }
@@ -281,7 +291,7 @@ export function usePromptActions({
         )
       }
 
-      busyRef.current = true
+      setMutableRef(busyRef, true)
       setBusy(true)
       setAwaitingResponse(true)
       clearNotifications()
@@ -400,6 +410,30 @@ export function usePromptActions({
           return
         }
 
+        // /yolo maps to the status-bar YOLO control — a per-session approval
+        // bypass, same scope as the TUI's Shift+Tab. With no session yet we arm
+        // it locally; the session-create path applies it on the first message.
+        if (normalizedName === 'yolo') {
+          const sid = sessionHint || activeSessionIdRef.current
+          const next = !$yoloActive.get()
+
+          if (!sid) {
+            setYoloActive(next)
+            notify({ kind: 'success', message: next ? 'YOLO armed for this chat' : 'YOLO off' })
+
+            return
+          }
+
+          try {
+            const active = await setSessionYolo(requestGateway, sid, next)
+            appendSessionTextMessage(sid, 'system', `YOLO ${active ? 'on' : 'off'} for this session`)
+          } catch {
+            notify({ kind: 'error', title: 'YOLO', message: 'Could not toggle YOLO' })
+          }
+
+          return
+        }
+
         if (normalizedName === 'skin' && !sessionHint && !activeSessionIdRef.current) {
           notify({ kind: 'success', message: handleSkinCommand(arg) })
 
@@ -561,7 +595,7 @@ export function usePromptActions({
   const cancelRun = useCallback(async () => {
     const sessionId = activeSessionId || activeSessionIdRef.current
 
-    busyRef.current = false
+    setMutableRef(busyRef, false)
     setBusy(false)
     setAwaitingResponse(false)
 
@@ -720,7 +754,7 @@ export function usePromptActions({
       const editedMessage: ChatMessage = { ...source, parts: [textPart(text)] }
 
       clearNotifications()
-      busyRef.current = true
+      setMutableRef(busyRef, true)
       setBusy(true)
       setAwaitingResponse(true)
       updateSessionState(sessionId, state => ({
@@ -758,7 +792,7 @@ export function usePromptActions({
           }
         }
 
-        busyRef.current = false
+        setMutableRef(busyRef, false)
         setBusy(false)
         setAwaitingResponse(false)
         updateSessionState(sessionId, state => ({ ...state, busy: false, awaitingResponse: false }))

apps/desktop/src/app/session/hooks/use-session-actions.ts

@@ -6,6 +6,7 @@ import { deleteSession, getSessionMessages, setSessionArchived } from '@/hermes'
 import { type ChatMessage, chatMessageText, preserveLocalAssistantErrors, toChatMessages } from '@/lib/chat-messages'
 import { normalizePersonalityValue } from '@/lib/chat-runtime'
 import { embeddedImageUrls, textWithoutEmbeddedImages } from '@/lib/embedded-images'
+import { setSessionYolo } from '@/lib/yolo-session'
 import { clearComposerAttachments, clearComposerDraft } from '@/store/composer'
 import { clearQueuedPrompts } from '@/store/composer-queue'
 import { $pinnedSessionIds } from '@/store/layout'
@@ -15,7 +16,9 @@ import {
   $currentCwd,
   $messages,
   $sessions,
+  $yoloActive,
   getRememberedWorkspaceCwd,
+  sessionPinId,
   setActiveSessionId,
   setAwaitingResponse,
   setBusy,
@@ -33,9 +36,10 @@ import {
   setMessages,
   setSelectedStoredSessionId,
   setSessions,
-  setSessionsTotal,
   setSessionStartedAt,
-  setTurnStartedAt
+  setSessionsTotal,
+  setTurnStartedAt,
+  setYoloActive
 } from '@/store/session'
 import { reportBackendContract } from '@/store/updates'
 import type { SessionCreateResponse, SessionInfo, SessionResumeResponse, UsageStats } from '@/types/hermes'
@@ -247,6 +251,10 @@ function applyRuntimeInfo(
     setCurrentFastMode(info.fast)
   }
 
+  if (typeof info.yolo === 'boolean') {
+    setYoloActive(info.yolo)
+  }
+
   if (info.usage) {
     setCurrentUsage(current => ({ ...current, ...info.usage }))
   }
@@ -303,67 +311,77 @@ export function useSessionActions({
     [activeSessionIdRef, busyRef, navigate, selectedStoredSessionIdRef]
   )
 
-  const createBackendSessionForSend = useCallback(async (preview: string | null = null): Promise<string | null> => {
-    const startingActiveSessionId = activeSessionIdRef.current
-    const startingStoredSessionId = selectedStoredSessionIdRef.current
-    const startingRouteToken = getRouteToken()
+  const createBackendSessionForSend = useCallback(
+    async (preview: string | null = null): Promise<string | null> => {
+      const startingActiveSessionId = activeSessionIdRef.current
+      const startingStoredSessionId = selectedStoredSessionIdRef.current
+      const startingRouteToken = getRouteToken()
 
-    creatingSessionRef.current = true
+      creatingSessionRef.current = true
 
-    try {
-      const cwd = $currentCwd.get().trim() || getRememberedWorkspaceCwd()
-      const created = await requestGateway<SessionCreateResponse>('session.create', { cols: 96, ...(cwd && { cwd }) })
-      const stored = created.stored_session_id ?? null
+      try {
+        const cwd = $currentCwd.get().trim() || getRememberedWorkspaceCwd()
+        const created = await requestGateway<SessionCreateResponse>('session.create', { cols: 96, ...(cwd && { cwd }) })
+        const stored = created.stored_session_id ?? null
 
-      if (
-        activeSessionIdRef.current !== startingActiveSessionId ||
-        selectedStoredSessionIdRef.current !== startingStoredSessionId ||
-        getRouteToken() !== startingRouteToken
-      ) {
-        await requestGateway('session.close', { session_id: created.session_id }).catch(() => undefined)
+        if (
+          activeSessionIdRef.current !== startingActiveSessionId ||
+          selectedStoredSessionIdRef.current !== startingStoredSessionId ||
+          getRouteToken() !== startingRouteToken
+        ) {
+          await requestGateway('session.close', { session_id: created.session_id }).catch(() => undefined)
 
-        return null
+          return null
+        }
+
+        activeSessionIdRef.current = created.session_id
+        selectedStoredSessionIdRef.current = stored
+        ensureSessionState(created.session_id, stored)
+
+        if (stored) {
+          // Seed the sidebar preview with the user's first message so the row
+          // reads meaningfully while the turn is in flight, instead of flashing
+          // "Untitled session" until the turn persists and auto-title runs. The
+          // server later returns its own preview/title and supersedes this.
+          upsertOptimisticSession(created, stored, null, preview?.trim() || null)
+          navigate(sessionRoute(stored), { replace: true })
+        }
+
+        setFreshDraftReady(false)
+        setActiveSessionId(created.session_id)
+        setSelectedStoredSessionId(stored)
+        setSessionStartedAt(Date.now())
+        const yoloArmed = $yoloActive.get()
+        const runtimeInfo = applyRuntimeInfo(created.info)
+
+        if (runtimeInfo) {
+          updateSessionState(created.session_id, state => ({ ...state, ...runtimeInfo }), stored)
+        }
+
+        // User may have armed YOLO on the new-chat draft before the runtime
+        // session existed — apply it to the freshly created session.
+        if (yoloArmed) {
+          await setSessionYolo(requestGateway, created.session_id, true).catch(() => undefined)
+        }
+
+        return created.session_id
+      } finally {
+        window.setTimeout(() => {
+          creatingSessionRef.current = false
+        }, 0)
       }
-
-      activeSessionIdRef.current = created.session_id
-      selectedStoredSessionIdRef.current = stored
-      ensureSessionState(created.session_id, stored)
-
-      if (stored) {
-        // Seed the sidebar preview with the user's first message so the row
-        // reads meaningfully while the turn is in flight, instead of flashing
-        // "Untitled session" until the turn persists and auto-title runs. The
-        // server later returns its own preview/title and supersedes this.
-        upsertOptimisticSession(created, stored, null, preview?.trim() || null)
-        navigate(sessionRoute(stored), { replace: true })
-      }
-
-      setFreshDraftReady(false)
-      setActiveSessionId(created.session_id)
-      setSelectedStoredSessionId(stored)
-      setSessionStartedAt(Date.now())
-      const runtimeInfo = applyRuntimeInfo(created.info)
-
-      if (runtimeInfo) {
-        updateSessionState(created.session_id, state => ({ ...state, ...runtimeInfo }), stored)
-      }
-
-      return created.session_id
-    } finally {
-      window.setTimeout(() => {
-        creatingSessionRef.current = false
-      }, 0)
-    }
-  }, [
-    activeSessionIdRef,
-    creatingSessionRef,
-    ensureSessionState,
-    getRouteToken,
-    navigate,
-    requestGateway,
-    selectedStoredSessionIdRef,
-    updateSessionState
-  ])
+    },
+    [
+      activeSessionIdRef,
+      creatingSessionRef,
+      ensureSessionState,
+      getRouteToken,
+      navigate,
+      requestGateway,
+      selectedStoredSessionIdRef,
+      updateSessionState
+    ]
+  )
 
   const selectSidebarItem = useCallback(
     (item: SidebarNavItem) => {
@@ -692,12 +710,15 @@ export function useSessionActions({
       const closingRuntimeId = wasSelected ? activeSessionId : null
       const previousMessages = $messages.get()
       const previousPinned = $pinnedSessionIds.get()
+      // Pins are keyed on the durable lineage-root id; the stored id may be the
+      // live tip after compression. Drop both so the pin can't linger.
+      const removedPinId = removed ? sessionPinId(removed) : storedSessionId
 
       setSessions(prev => prev.filter(s => s.id !== storedSessionId))
       // Keep $sessionsTotal in sync so the sidebar's "Load N more" footer
       // doesn't keep claiming the removed row is still on the server.
       setSessionsTotal(prev => Math.max(0, prev - 1))
-      $pinnedSessionIds.set(previousPinned.filter(id => id !== storedSessionId))
+      $pinnedSessionIds.set(previousPinned.filter(id => id !== storedSessionId && id !== removedPinId))
 
       // Tear down before awaiting so the route effect can't resume the
       // doomed session via the stale /<sid> URL.
@@ -769,6 +790,9 @@ export function useSessionActions({
       const archived = $sessions.get().find(s => s.id === storedSessionId)
       const wasSelected = selectedStoredSessionId === storedSessionId
       const previousPinned = $pinnedSessionIds.get()
+      // Pins are keyed on the durable lineage-root id; the stored id may be the
+      // live tip after compression. Drop both so the pin can't linger.
+      const archivedPinId = archived ? sessionPinId(archived) : storedSessionId
 
       // Soft-hide: drop from the sidebar immediately, keep the data.
       setSessions(prev => prev.filter(s => s.id !== storedSessionId))
@@ -776,7 +800,7 @@ export function useSessionActions({
       // on the next refresh, so they count as "removed" for the load-more
       // footer math.
       setSessionsTotal(prev => Math.max(0, prev - 1))
-      $pinnedSessionIds.set(previousPinned.filter(id => id !== storedSessionId))
+      $pinnedSessionIds.set(previousPinned.filter(id => id !== storedSessionId && id !== archivedPinId))
 
       if (wasSelected) {
         startFreshSessionDraft(true)

apps/desktop/src/app/session/hooks/use-session-state-cache.ts

@@ -4,7 +4,8 @@ import { type MutableRefObject, useCallback, useEffect, useRef } from 'react'
 import type { ChatMessage } from '@/lib/chat-messages'
 import { preserveLocalAssistantErrors } from '@/lib/chat-messages'
 import { createClientSessionState } from '@/lib/chat-runtime'
-import { $busy, $messages, noteSessionActivity, setSessionWorking } from '@/store/session'
+import { setMutableRef } from '@/lib/mutable-ref'
+import { $busy, $messages, noteSessionActivity, setSessionAttention, setSessionWorking } from '@/store/session'
 
 import type { ClientSessionState } from '../../types'
 
@@ -38,7 +39,7 @@ export function useSessionStateCache({
   }, [activeSessionId])
 
   useEffect(() => {
-    busyRef.current = busy
+    setMutableRef(busyRef, busy)
   }, [busy, busyRef])
 
   useEffect(() => {
@@ -89,7 +90,7 @@ export function useSessionStateCache({
 
     setMessages(preserveLocalAssistantErrors(pending.state.messages, $messages.get()))
     setBusy(pending.state.busy)
-    busyRef.current = pending.state.busy
+    setMutableRef(busyRef, pending.state.busy)
     setAwaitingResponse(pending.state.awaitingResponse)
   }, [busyRef, setAwaitingResponse, setBusy, setMessages])
 
@@ -152,7 +153,13 @@ export function useSessionStateCache({
         setSessionWorking(previous.storedSessionId, false)
       }
 
+      if (previous.storedSessionId !== next.storedSessionId || !next.needsInput) {
+        setSessionAttention(previous.storedSessionId, false)
+      }
+
       setSessionWorking(next.storedSessionId, next.busy)
+      setSessionAttention(next.storedSessionId, next.needsInput)
+
       // Every state update is effectively a "still alive" heartbeat for
       // streaming events. The session-store watchdog uses this to keep the
       // working flag alive during long-running turns and to clear it once
@@ -160,6 +167,7 @@ export function useSessionStateCache({
       if (next.busy) {
         noteSessionActivity(next.storedSessionId)
       }
+
       syncSessionStateToView(sessionId, next)
 
       return next

apps/desktop/src/app/settings/about-settings.tsx

@@ -2,7 +2,7 @@ import { useStore } from '@nanostores/react'
 import { useEffect, useState } from 'react'
 
 import { Button } from '@/components/ui/button'
-import { CheckCircle2, ExternalLink, Loader2, RefreshCw, Sparkles } from '@/lib/icons'
+import { Loader2, RefreshCw, Sparkles } from '@/lib/icons'
 import { cn } from '@/lib/utils'
 import {
   $desktopVersion,
@@ -111,29 +111,22 @@ export function AboutSettings() {
             statusTone === 'idle' && 'border-border/70 bg-muted/20 text-foreground'
           )}
         >
-          <div className="flex items-start gap-2">
-            {statusTone === 'available' ? (
-              <Sparkles className="mt-0.5 size-4 shrink-0 text-primary" />
-            ) : statusTone === 'error' ? null : (
-              <CheckCircle2 className="mt-0.5 size-4 shrink-0 text-emerald-600 dark:text-emerald-400" />
-            )}
-            <div className="min-w-0">
-              <p className="font-medium">{statusLine}</p>
-              <p className="mt-1 text-xs text-muted-foreground">
-                Last checked {relativeTime(status?.fetchedAt)}
-                {justChecked && !checking ? ' · just now' : ''}
-              </p>
-            </div>
+          <div className="min-w-0">
+            <p className="font-medium">{statusLine}</p>
+            <p className="mt-1 text-xs text-muted-foreground">
+              Last checked {relativeTime(status?.fetchedAt)}
+              {justChecked && !checking ? ' · just now' : ''}
+            </p>
           </div>
 
-          <div className="mt-3 flex flex-wrap items-center gap-2">
+          <div className="mt-3 flex flex-wrap items-center gap-4">
             <Button
               disabled={checking || applying || !supported}
               onClick={() => void handleCheck()}
               size="sm"
-              variant="outline"
+              variant="textStrong"
             >
-              {checking ? <Loader2 className="size-3 animate-spin" /> : <RefreshCw className="size-3" />}
+              {checking && <Loader2 className="size-3 animate-spin" />}
               {checking ? 'Checking…' : 'Check now'}
             </Button>
 
@@ -143,12 +136,7 @@ export function AboutSettings() {
               </Button>
             )}
 
-            <Button
-              asChild
-              className="ml-auto text-xs text-muted-foreground hover:text-foreground"
-              size="sm"
-              variant="ghost"
-            >
+            <Button asChild className="ml-auto" size="sm" variant="text">
               <a
                 href={RELEASE_NOTES_URL}
                 onClick={event => {
@@ -158,7 +146,6 @@ export function AboutSettings() {
                 rel="noreferrer"
                 target="_blank"
               >
-                <ExternalLink className="size-3" />
                 Release notes
               </a>
             </Button>

apps/desktop/src/app/settings/appearance-settings.tsx

@@ -1,15 +1,16 @@
 import { useStore } from '@nanostores/react'
+import type { ReactNode } from 'react'
 
+import { SegmentedControl } from '@/components/ui/segmented-control'
 import { triggerHaptic } from '@/lib/haptics'
-import { Check, Palette } from '@/lib/icons'
+import { Check } from '@/lib/icons'
 import { cn } from '@/lib/utils'
 import { $toolViewMode, setToolViewMode } from '@/store/tool-view'
 import { useTheme } from '@/themes/context'
 import { BUILTIN_THEMES } from '@/themes/presets'
 
 import { MODE_OPTIONS } from './constants'
-import { prettyName } from './helpers'
-import { Pill, SectionHeading, SettingsContent } from './primitives'
+import { SettingsContent } from './primitives'
 
 function ThemePreview({ name }: { name: string }) {
   const t = BUILTIN_THEMES[name]
@@ -51,146 +52,80 @@ function ThemePreview({ name }: { name: string }) {
   )
 }
 
+function SectionHead({ title, description, control }: { title: string; description: string; control?: ReactNode }) {
+  return (
+    <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between sm:gap-4">
+      <div className="min-w-0">
+        <div className="text-[length:var(--conversation-text-font-size)] font-medium">{title}</div>
+        <div className="mt-1 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
+          {description}
+        </div>
+      </div>
+      {control && <div className="shrink-0">{control}</div>}
+    </div>
+  )
+}
+
 export function AppearanceSettings() {
   const { themeName, mode, availableThemes, setTheme, setMode } = useTheme()
   const toolViewMode = useStore($toolViewMode)
-  const activeTheme = availableThemes.find(t => t.name === themeName)
 
   return (
     <SettingsContent>
-      <div className="space-y-5">
-        <div>
-          <SectionHeading icon={Palette} title="Appearance" />
-          <p className="max-w-2xl text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
-            These are desktop-only display preferences. Mode controls brightness; theme controls the accent palette and
-            chat surface styling.
-          </p>
-        </div>
+      <div className="grid gap-8">
+        <p className="max-w-2xl text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
+          These are desktop-only display preferences. Mode controls brightness; theme controls the accent palette and
+          chat surface styling.
+        </p>
 
-        <section className="rounded-xl border border-(--ui-stroke-tertiary) bg-(--ui-chat-bubble-background) p-3 shadow-sm">
-          <div className="mb-3 flex items-center justify-between gap-3">
-            <div>
-              <div className="text-sm font-medium">Color Mode</div>
-              <div className="mt-1 text-xs text-muted-foreground">
-                Pick a fixed mode or let Hermes follow your system setting.
-              </div>
-            </div>
-            <Pill>{prettyName(mode)}</Pill>
-          </div>
-          <div className="grid gap-2 sm:grid-cols-3">
-            {MODE_OPTIONS.map(({ id, label, description, icon: Icon }) => {
-              const active = mode === id
-
-              return (
-                <button
-                  className={cn(
-                    'group rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) p-2.5 text-left transition hover:bg-(--chrome-action-hover)',
-                    active && 'border-(--ui-stroke-secondary) bg-(--ui-bg-tertiary)'
-                  )}
-                  key={id}
-                  onClick={() => {
-                    triggerHaptic('crisp')
-                    setMode(id)
-                  }}
-                  type="button"
-                >
-                  <div className="flex items-start justify-between gap-3">
-                    <span className="flex size-9 items-center justify-center rounded-lg bg-muted text-foreground transition group-hover:bg-background">
-                      <Icon className="size-4" />
-                    </span>
-                    {active && (
-                      <span className="grid size-5 place-items-center rounded-full bg-primary text-primary-foreground">
-                        <Check className="size-3.5" />
-                      </span>
-                    )}
-                  </div>
-                  <div className="mt-2 text-[length:var(--conversation-text-font-size)] font-medium">{label}</div>
-                  <div className="mt-1 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
-                    {description}
-                  </div>
-                </button>
-              )
-            })}
-          </div>
+        <section>
+          <SectionHead
+            control={
+              <SegmentedControl
+                onChange={id => {
+                  triggerHaptic('crisp')
+                  setMode(id)
+                }}
+                options={MODE_OPTIONS}
+                value={mode}
+              />
+            }
+            description="Pick a fixed mode or let Hermes follow your system setting."
+            title="Color Mode"
+          />
         </section>
 
-        <section className="rounded-xl border border-(--ui-stroke-tertiary) bg-(--ui-chat-bubble-background) p-3 shadow-sm">
-          <div className="mb-3 flex items-center justify-between gap-3">
-            <div>
-              <div className="text-sm font-medium">Tool Call Display</div>
-              <div className="mt-1 text-xs text-muted-foreground">
-                Product hides raw tool payloads; Technical shows full input/output.
-              </div>
-            </div>
-            <Pill>{toolViewMode === 'technical' ? 'Technical' : 'Product'}</Pill>
-          </div>
-          <div className="grid gap-2 sm:grid-cols-2">
-            {(
-              [
-                {
-                  id: 'product',
-                  label: 'Product',
-                  description: 'Human-friendly tool activity with concise summaries.'
-                },
-                {
-                  id: 'technical',
-                  label: 'Technical',
-                  description: 'Include raw tool args/results and low-level details.'
+        <section>
+          <SectionHead
+            control={
+              <SegmentedControl
+                onChange={id => {
+                  triggerHaptic('selection')
+                  setToolViewMode(id)
+                }}
+                options={
+                  [
+                    { id: 'product', label: 'Product' },
+                    { id: 'technical', label: 'Technical' }
+                  ] as const
                 }
-              ] as const
-            ).map(option => {
-              const active = toolViewMode === option.id
-
-              return (
-                <button
-                  className={cn(
-                    'group rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) p-2.5 text-left transition hover:bg-(--chrome-action-hover)',
-                    active && 'border-(--ui-stroke-secondary) bg-(--ui-bg-tertiary)'
-                  )}
-                  key={option.id}
-                  onClick={() => {
-                    triggerHaptic('selection')
-                    setToolViewMode(option.id)
-                  }}
-                  type="button"
-                >
-                  <div className="flex items-start justify-between gap-3">
-                    <div className="text-[length:var(--conversation-text-font-size)] font-medium">{option.label}</div>
-                    {active && (
-                      <span className="grid size-5 place-items-center rounded-full bg-primary text-primary-foreground">
-                        <Check className="size-3.5" />
-                      </span>
-                    )}
-                  </div>
-                  <div className="mt-1 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
-                    {option.description}
-                  </div>
-                </button>
-              )
-            })}
-          </div>
+                value={toolViewMode}
+              />
+            }
+            description="Product hides raw tool payloads; Technical shows full input/output."
+            title="Tool Call Display"
+          />
         </section>
 
-        <section className="rounded-xl border border-(--ui-stroke-tertiary) bg-(--ui-chat-bubble-background) p-3 shadow-sm">
-          <div className="mb-3 flex items-center justify-between gap-3">
-            <div>
-              <div className="text-sm font-medium">Theme</div>
-              <div className="mt-1 text-xs text-muted-foreground">
-                Desktop palettes only. The selected mode is applied on top.
-              </div>
-            </div>
-            {activeTheme && <Pill>{activeTheme.label}</Pill>}
-          </div>
-          <div className="grid gap-3 sm:grid-cols-2 xl:grid-cols-3">
+        <section className="grid gap-3">
+          <SectionHead description="Desktop palettes only. The selected mode is applied on top." title="Theme" />
+          <div className="grid gap-x-4 gap-y-5 sm:grid-cols-2 xl:grid-cols-3">
             {availableThemes.map(theme => {
               const active = themeName === theme.name
 
               return (
                 <button
-                  className={cn(
-                    'rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) p-2 text-left transition hover:bg-(--chrome-action-hover)',
-                    active && 'border-(--ui-stroke-secondary) bg-(--ui-bg-tertiary)'
-                  )}
+                  className="group text-left"
                   key={theme.name}
                   onClick={() => {
                     triggerHaptic('crisp')
@@ -198,8 +133,17 @@ export function AppearanceSettings() {
                   }}
                   type="button"
                 >
-                  <ThemePreview name={theme.name} />
-                  <div className="mt-3 flex items-start justify-between gap-3 px-1">
+                  <div
+                    className={cn(
+                      'rounded-xl transition',
+                      active
+                        ? 'ring-2 ring-primary ring-offset-2 ring-offset-background'
+                        : 'opacity-90 group-hover:opacity-100'
+                    )}
+                  >
+                    <ThemePreview name={theme.name} />
+                  </div>
+                  <div className="mt-2.5 flex items-start justify-between gap-2 px-0.5">
                     <div className="min-w-0">
                       <div className="truncate text-[length:var(--conversation-text-font-size)] font-medium">
                         {theme.label}
@@ -208,11 +152,7 @@ export function AppearanceSettings() {
                         {theme.description}
                       </div>
                     </div>
-                    {active && (
-                      <span className="mt-0.5 grid size-5 shrink-0 place-items-center rounded-full bg-primary text-primary-foreground">
-                        <Check className="size-3.5" />
-                      </span>
-                    )}
+                    {active && <Check className="mt-0.5 size-4 shrink-0 text-primary" />}
                   </div>
                 </button>
               )

apps/desktop/src/app/settings/config-settings.tsx

@@ -1,5 +1,6 @@
 import type { ChangeEvent, ReactNode } from 'react'
 import { useEffect, useMemo, useRef, useState } from 'react'
+import { useSearchParams } from 'react-router-dom'
 
 import { Input } from '@/components/ui/input'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
@@ -17,10 +18,9 @@ import { notify, notifyError } from '@/store/notifications'
 import type { ConfigFieldSchema, HermesConfigRecord } from '@/types/hermes'
 
 import { CONTROL_TEXT, EMPTY_SELECT_VALUE, FIELD_DESCRIPTIONS, FIELD_LABELS, SECTIONS } from './constants'
-import { enumOptionsFor, getNested, includesQuery, prettyName, setNested } from './helpers'
+import { enumOptionsFor, getNested, prettyName, setNested } from './helpers'
 import { ModelSettings } from './model-settings'
 import { EmptyState, ListRow, LoadingState, SettingsContent } from './primitives'
-import type { SearchProps } from './types'
 
 function ConfigField({
   schemaKey,
@@ -53,8 +53,7 @@ function ConfigField({
 
   if (schema.type === 'boolean') {
     return row(
-      <div className="flex items-center justify-end gap-3">
-        <span className="text-xs text-muted-foreground">{value ? 'On' : 'Off'}</span>
+      <div className="flex items-center justify-end">
         <Switch checked={Boolean(value)} onCheckedChange={onChange} />
       </div>
     )
@@ -89,7 +88,7 @@ function ConfigField({
   if (schema.type === 'number') {
     return row(
       <Input
-        className={cn('h-8', CONTROL_TEXT)}
+        className={CONTROL_TEXT}
         onChange={e => {
           const raw = e.target.value
           const n = raw === '' ? 0 : Number(raw)
@@ -108,7 +107,7 @@ function ConfigField({
   if (schema.type === 'list') {
     return row(
       <Input
-        className={cn('h-8', CONTROL_TEXT)}
+        className={CONTROL_TEXT}
         onChange={e =>
           onChange(
             e.target.value
@@ -154,7 +153,7 @@ function ConfigField({
       />
     ) : (
       <Input
-        className={cn('h-8', CONTROL_TEXT)}
+        className={CONTROL_TEXT}
         onChange={e => onChange(e.target.value)}
         placeholder="Not set"
         value={String(value ?? '')}
@@ -165,12 +164,11 @@ function ConfigField({
 }
 
 export function ConfigSettings({
-  query,
   activeSectionId,
   onConfigSaved,
   onMainModelChanged,
   importInputRef
-}: SearchProps & {
+}: {
   activeSectionId: string
   onConfigSaved?: () => void
   onMainModelChanged?: (provider: string, model: string) => void
@@ -265,37 +263,41 @@ export function ConfigSettings({
     )
   }, [schema])
 
-  const matched = useMemo(() => {
-    const q = query.trim().toLowerCase()
+  const fields = sectionFields.get(activeSectionId) ?? []
 
-    if (!schema || !q) {
-      return []
+  // Deep-link target from the command palette (?field=<key>): scroll the row
+  // into view and flash it, then drop the param so it doesn't re-fire.
+  const [searchParams, setSearchParams] = useSearchParams()
+  const targetField = searchParams.get('field')
+
+  useEffect(() => {
+    if (!targetField || !config || !schema) {
+      return
     }
 
-    const seen = new Set<string>()
+    const element = document.getElementById(`setting-field-${targetField}`)
 
-    return SECTIONS.flatMap(s =>
-      s.keys.flatMap(k => {
-        if (seen.has(k) || !schema[k]) {
-          return []
-        }
+    if (!element) {
+      return
+    }
 
-        seen.add(k)
-        const label = prettyName(k.split('.').pop() ?? k)
-        const item = schema[k]
+    element.scrollIntoView({ behavior: 'smooth', block: 'center' })
+    element.classList.add('setting-field-highlight')
 
-        const hit =
-          k.toLowerCase().includes(q) ||
-          label.toLowerCase().includes(q) ||
-          includesQuery(item.category, q) ||
-          includesQuery(item.description, q)
+    const timeout = window.setTimeout(() => element.classList.remove('setting-field-highlight'), 1600)
 
-        return hit ? [[k, item] as [string, ConfigFieldSchema]] : []
-      })
+    setSearchParams(
+      previous => {
+        const next = new URLSearchParams(previous)
+        next.delete('field')
+
+        return next
+      },
+      { replace: true }
     )
-  }, [schema, query])
 
-  const fields = query.trim() ? matched : (sectionFields.get(activeSectionId) ?? [])
+    return () => window.clearTimeout(timeout)
+  }, [config, schema, setSearchParams, targetField])
 
   function handleImport(e: ChangeEvent<HTMLInputElement>) {
     const file = e.target.files?.[0]
@@ -325,34 +327,30 @@ export function ConfigSettings({
 
   return (
     <SettingsContent>
-      {activeSectionId === 'model' && !query.trim() && (
+      {activeSectionId === 'model' && (
         <div className="mb-6">
           <ModelSettings onMainModelChanged={onMainModelChanged} />
         </div>
       )}
-      {query.trim() && (
-        <div className="mb-4 text-xs text-muted-foreground">
-          {fields.length} result{fields.length === 1 ? '' : 's'}
-        </div>
-      )}
       {fields.length === 0 ? (
-        <EmptyState description="Try a different search term or choose another section." title="No matching settings" />
+        <EmptyState description="This section has no adjustable settings." title="Nothing to configure" />
       ) : (
-        <div className="divide-y divide-border/40">
+        <div className="grid gap-1">
           {fields.map(([key, field]) => (
-            <ConfigField
-              enumOptions={
-                key === 'tts.elevenlabs.voice_id'
-                  ? enumOptionsFor(key, getNested(config, key), config, elevenLabsVoiceOptions ?? undefined)
-                  : enumOptionsFor(key, getNested(config, key), config)
-              }
-              key={key}
-              onChange={value => updateConfig(setNested(config, key, value))}
-              optionLabels={key === 'tts.elevenlabs.voice_id' ? elevenLabsVoiceLabels : undefined}
-              schema={field}
-              schemaKey={key}
-              value={getNested(config, key)}
-            />
+            <div className="scroll-mt-6 rounded-lg" id={`setting-field-${key}`} key={key}>
+              <ConfigField
+                enumOptions={
+                  key === 'tts.elevenlabs.voice_id'
+                    ? enumOptionsFor(key, getNested(config, key), config, elevenLabsVoiceOptions ?? undefined)
+                    : enumOptionsFor(key, getNested(config, key), config)
+                }
+                onChange={value => updateConfig(setNested(config, key, value))}
+                optionLabels={key === 'tts.elevenlabs.voice_id' ? elevenLabsVoiceLabels : undefined}
+                schema={field}
+                schemaKey={key}
+                value={getNested(config, key)}
+              />
+            </div>
           ))}
         </div>
       )}

apps/desktop/src/app/settings/constants.ts

@@ -15,34 +15,202 @@ import type { ThemeMode } from '@/themes/context'
 
 import type { DesktopConfigSection } from './types'
 
+// Provider group definitions used to fold raw env-var names like
+// ``XAI_API_KEY`` into a single "xAI" card with a friendly label, short
+// description, and signup URL. Membership is determined by longest
+// prefix match (see ``providerGroup`` in helpers.ts) so more specific
+// prefixes (``MINIMAX_CN_``) correctly beat their general parents
+// (``MINIMAX_``). New providers should be added here so they get their
+// own card in Settings → Keys instead of being lumped into "Other".
 interface ProviderPrefix {
   prefix: string
   name: string
+  /** Optional one-line tagline shown beneath the group name. */
+  description?: string
+  /** Optional canonical signup/console URL surfaced from the card header. */
+  docsUrl?: string
+  /** Lower numbers float to the top of the providers list. */
   priority: number
 }
 
 export const EMPTY_SELECT_VALUE = '__hermes_empty__'
-export const CONTROL_TEXT = 'text-[0.8125rem]'
+export const CONTROL_TEXT = 'text-xs'
 
 export const PROVIDER_GROUPS: ProviderPrefix[] = [
-  { prefix: 'NOUS_', name: 'Nous Portal', priority: 0 },
-  { prefix: 'ANTHROPIC_', name: 'Anthropic', priority: 1 },
-  { prefix: 'DASHSCOPE_', name: 'DashScope (Qwen)', priority: 2 },
-  { prefix: 'HERMES_QWEN_', name: 'DashScope (Qwen)', priority: 2 },
-  { prefix: 'DEEPSEEK_', name: 'DeepSeek', priority: 3 },
-  { prefix: 'GOOGLE_', name: 'Gemini', priority: 4 },
+  {
+    prefix: 'NOUS_',
+    name: 'Nous Portal',
+    description: 'Hosted Hermes & Nous-trained models',
+    docsUrl: 'https://portal.nousresearch.com',
+    priority: 0
+  },
+  {
+    prefix: 'OPENROUTER_',
+    name: 'OpenRouter',
+    description: 'Aggregator for hundreds of frontier models',
+    docsUrl: 'https://openrouter.ai/keys',
+    priority: 1
+  },
+  {
+    prefix: 'ANTHROPIC_',
+    name: 'Anthropic',
+    description: 'Claude API access (Sonnet, Opus, Haiku)',
+    docsUrl: 'https://console.anthropic.com/settings/keys',
+    priority: 2
+  },
+  {
+    prefix: 'XAI_',
+    name: 'xAI',
+    description: 'Grok models (use OAuth for SuperGrok / Premium+)',
+    docsUrl: 'https://console.x.ai/',
+    priority: 3
+  },
+  {
+    prefix: 'GOOGLE_',
+    name: 'Gemini',
+    description: 'Google AI Studio (Gemini 1.5 / 2.0 / 2.5)',
+    docsUrl: 'https://aistudio.google.com/app/apikey',
+    priority: 4
+  },
   { prefix: 'GEMINI_', name: 'Gemini', priority: 4 },
-  { prefix: 'GLM_', name: 'GLM / Z.AI', priority: 5 },
-  { prefix: 'ZAI_', name: 'GLM / Z.AI', priority: 5 },
-  { prefix: 'Z_AI_', name: 'GLM / Z.AI', priority: 5 },
-  { prefix: 'HF_', name: 'Hugging Face', priority: 6 },
-  { prefix: 'KIMI_', name: 'Kimi / Moonshot', priority: 7 },
-  { prefix: 'MINIMAX_', name: 'MiniMax', priority: 8 },
-  { prefix: 'MINIMAX_CN_', name: 'MiniMax (China)', priority: 9 },
-  { prefix: 'OPENCODE_GO_', name: 'OpenCode Go', priority: 10 },
-  { prefix: 'OPENCODE_ZEN_', name: 'OpenCode Zen', priority: 11 },
-  { prefix: 'OPENROUTER_', name: 'OpenRouter', priority: 12 },
-  { prefix: 'XIAOMI_', name: 'Xiaomi MiMo', priority: 13 }
+  { prefix: 'HERMES_GEMINI_', name: 'Gemini', priority: 4 },
+  {
+    prefix: 'DEEPSEEK_',
+    name: 'DeepSeek',
+    description: 'Direct DeepSeek API (V3.x, R1)',
+    docsUrl: 'https://platform.deepseek.com/api_keys',
+    priority: 5
+  },
+  {
+    prefix: 'DASHSCOPE_',
+    name: 'DashScope (Qwen)',
+    description: 'Alibaba Cloud DashScope — Qwen and multi-vendor models',
+    docsUrl: 'https://modelstudio.console.alibabacloud.com/',
+    priority: 6
+  },
+  { prefix: 'HERMES_QWEN_', name: 'DashScope (Qwen)', priority: 6 },
+  {
+    prefix: 'GLM_',
+    name: 'GLM / Z.AI',
+    description: 'Zhipu GLM-4.6 and Z.AI hosted endpoints',
+    docsUrl: 'https://z.ai/',
+    priority: 7
+  },
+  { prefix: 'ZAI_', name: 'GLM / Z.AI', priority: 7 },
+  { prefix: 'Z_AI_', name: 'GLM / Z.AI', priority: 7 },
+  {
+    prefix: 'KIMI_',
+    name: 'Kimi / Moonshot',
+    description: 'Moonshot Kimi K2 / coding endpoints',
+    docsUrl: 'https://platform.moonshot.cn/',
+    priority: 8
+  },
+  {
+    prefix: 'KIMI_CN_',
+    name: 'Kimi (China)',
+    description: 'Moonshot China endpoint',
+    docsUrl: 'https://platform.moonshot.cn/',
+    priority: 9
+  },
+  {
+    prefix: 'MINIMAX_',
+    name: 'MiniMax',
+    description: 'MiniMax-M2 and Hailuo international endpoints',
+    docsUrl: 'https://www.minimax.io/',
+    priority: 10
+  },
+  {
+    prefix: 'MINIMAX_CN_',
+    name: 'MiniMax (China)',
+    description: 'MiniMax mainland China endpoint',
+    docsUrl: 'https://www.minimaxi.com/',
+    priority: 11
+  },
+  {
+    prefix: 'HF_',
+    name: 'Hugging Face',
+    description: 'Inference Providers — 20+ open models via router.huggingface.co',
+    docsUrl: 'https://huggingface.co/settings/tokens',
+    priority: 12
+  },
+  {
+    prefix: 'OPENCODE_ZEN_',
+    name: 'OpenCode Zen',
+    description: 'Pay-as-you-go access to curated coding models',
+    docsUrl: 'https://opencode.ai/auth',
+    priority: 13
+  },
+  {
+    prefix: 'OPENCODE_GO_',
+    name: 'OpenCode Go',
+    description: '$10/month subscription for open coding models',
+    docsUrl: 'https://opencode.ai/auth',
+    priority: 14
+  },
+  {
+    prefix: 'NVIDIA_',
+    name: 'NVIDIA NIM',
+    description: 'build.nvidia.com or your own local NIM endpoint',
+    docsUrl: 'https://build.nvidia.com/',
+    priority: 15
+  },
+  {
+    prefix: 'OLLAMA_',
+    name: 'Ollama Cloud',
+    description: 'Cloud-hosted open models from ollama.com',
+    docsUrl: 'https://ollama.com/settings',
+    priority: 16
+  },
+  {
+    prefix: 'LM_',
+    name: 'LM Studio',
+    description: 'Local LM Studio server (OpenAI-compatible)',
+    docsUrl: 'https://lmstudio.ai/docs/local-server',
+    priority: 17
+  },
+  {
+    prefix: 'STEPFUN_',
+    name: 'StepFun',
+    description: 'StepFun Step Plan coding models',
+    docsUrl: 'https://platform.stepfun.com/',
+    priority: 18
+  },
+  {
+    prefix: 'XIAOMI_',
+    name: 'Xiaomi MiMo',
+    description: 'MiMo-V2.5 and Xiaomi proprietary models',
+    docsUrl: 'https://platform.xiaomimimo.com',
+    priority: 19
+  },
+  {
+    prefix: 'ARCEEAI_',
+    name: 'Arcee AI',
+    description: 'Arcee-hosted small + medium models',
+    docsUrl: 'https://chat.arcee.ai/',
+    priority: 20
+  },
+  { prefix: 'ARCEE_', name: 'Arcee AI', priority: 20 },
+  {
+    prefix: 'GMI_',
+    name: 'GMI Cloud',
+    description: 'GMI Cloud GPU + model serving',
+    docsUrl: 'https://www.gmicloud.ai/',
+    priority: 21
+  },
+  {
+    prefix: 'AZURE_FOUNDRY_',
+    name: 'Azure Foundry',
+    description: 'Azure AI Foundry custom endpoints (OpenAI / Anthropic-compatible)',
+    docsUrl: 'https://ai.azure.com/',
+    priority: 22
+  },
+  {
+    prefix: 'AWS_',
+    name: 'AWS Bedrock',
+    description: 'Authenticate via AWS profile + region',
+    docsUrl: 'https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html',
+    priority: 23
+  }
 ]
 
 export const BUILTIN_PERSONALITIES = [
@@ -289,21 +457,11 @@ export const SECTIONS: DesktopConfigSection[] = [
 export interface ModeOption {
   id: ThemeMode
   label: string
-  description: string
   icon: IconComponent
 }
 
 export const MODE_OPTIONS: ModeOption[] = [
-  { id: 'light', label: 'Light', description: 'Bright desktop surfaces', icon: Sun },
-  { id: 'dark', label: 'Dark', description: 'Low-glare workspace', icon: Moon },
-  { id: 'system', label: 'System', description: 'Follow OS appearance', icon: Monitor }
+  { id: 'light', label: 'Light', icon: Sun },
+  { id: 'dark', label: 'Dark', icon: Moon },
+  { id: 'system', label: 'System', icon: Monitor }
 ]
-
-export const SEARCH_PLACEHOLDER: Record<'about' | 'config' | 'gateway' | 'keys' | 'mcp' | 'sessions', string> = {
-  about: 'About Hermes Desktop',
-  config: 'Search settings...',
-  gateway: 'Gateway connection...',
-  keys: 'Search API keys...',
-  mcp: 'Search MCP servers...',
-  sessions: 'Search archived sessions...'
-}

apps/desktop/src/app/settings/credential-key-ui.tsx

@@ -0,0 +1,363 @@
+import { type ChangeEvent, type KeyboardEvent } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { ChevronDown, ExternalLink, Loader2, Save } from '@/lib/icons'
+import { cn } from '@/lib/utils'
+import type { EnvVarInfo } from '@/types/hermes'
+
+import { CONTROL_TEXT } from './constants'
+import { prettyName, withoutKey } from './helpers'
+import { ListRow } from './primitives'
+import type { EnvRowProps } from './types'
+
+export type KeyRowProps = Omit<EnvRowProps, 'info' | 'varKey'>
+
+/** Matches Advanced / config field controls (ListRow + Input). */
+export const CREDENTIAL_CONTROL_CLASS = cn('h-8', CONTROL_TEXT)
+
+export const isKeyVar = (key: string, info: EnvVarInfo) =>
+  info.is_password || /(?:_API_KEY|_TOKEN|_KEY)$/.test(key)
+
+export const friendlyFieldLabel = (key: string, info: EnvVarInfo) =>
+  info.description?.trim() ||
+  key
+    .replace(/_/g, ' ')
+    .toLowerCase()
+    .replace(/\b\w/g, c => c.toUpperCase())
+
+export const credentialPlaceholder = (key: string, info: EnvVarInfo, label: string): string =>
+  isKeyVar(key, info) ? `Paste ${label} key` : /URL$/i.test(key) ? 'https://…' : 'Optional'
+
+// A single credential field: a set key shows as a filled read-only input
+// (redacted value) that edits in place on click. Save appears once typed; a set
+// key also offers Remove, and Esc cancels without closing the overlay.
+export function KeyField({
+  info,
+  placeholder,
+  rowProps,
+  varKey
+}: {
+  info: EnvVarInfo
+  placeholder?: string
+  rowProps: KeyRowProps
+  varKey: string
+}) {
+  const { edits, onClear, onSave, saving, setEdits } = rowProps
+  const editing = edits[varKey] !== undefined
+  const draft = edits[varKey] ?? ''
+  const dirty = draft.trim().length > 0
+  const busy = saving === varKey
+  const masked = info.redacted_value ?? '••••••••'
+  const startEdit = () => setEdits(c => ({ ...c, [varKey]: '' }))
+  const cancel = () => setEdits(c => withoutKey(c, varKey))
+  const update = (e: ChangeEvent<HTMLInputElement>) => setEdits(c => ({ ...c, [varKey]: e.target.value }))
+
+  const keydown = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Enter' && dirty) {
+      void onSave(varKey)
+    } else if (e.key === 'Escape' && editing) {
+      e.preventDefault()
+      e.stopPropagation()
+      cancel()
+    }
+  }
+
+  const editType = info.is_password ? 'password' : 'text'
+
+  if (info.is_set && !editing) {
+    return (
+      <Input
+        className={cn(CREDENTIAL_CONTROL_CLASS, 'cursor-pointer text-muted-foreground')}
+        onFocus={startEdit}
+        readOnly
+        value={masked}
+      />
+    )
+  }
+
+  return (
+    <div className="grid gap-1">
+      <div className="flex items-center gap-2">
+        <Input
+          autoFocus={editing}
+          className={cn(CREDENTIAL_CONTROL_CLASS, 'min-w-0 flex-1')}
+          onChange={update}
+          onKeyDown={keydown}
+          placeholder={placeholder ?? 'Paste key'}
+          type={editType}
+          value={draft}
+        />
+        {dirty && (
+          <Button className="h-8 shrink-0" disabled={busy} onClick={() => void onSave(varKey)} size="sm">
+            {busy ? <Loader2 className="size-4 animate-spin" /> : <Save />}
+            {busy ? 'Saving' : 'Save'}
+          </Button>
+        )}
+      </div>
+      {editing && (
+        <div className="flex items-center gap-1 text-[0.6875rem]">
+          {info.is_set && (
+            <>
+              <Button
+                className="h-auto px-0 py-0 text-[0.6875rem] text-destructive hover:text-destructive"
+                disabled={busy}
+                onClick={() => void onClear(varKey)}
+                type="button"
+                variant="text"
+              >
+                Remove
+              </Button>
+              <span className="text-muted-foreground">or</span>
+            </>
+          )}
+          <span className="text-muted-foreground">esc to cancel</span>
+        </div>
+      )}
+    </div>
+  )
+}
+
+function CredentialDocsLink({ href }: { href: string }) {
+  return (
+    <a
+      className="inline-flex w-fit items-center gap-1 text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary) underline-offset-4 transition-colors hover:text-foreground hover:underline"
+      href={href}
+      onClick={e => e.stopPropagation()}
+      rel="noreferrer"
+      target="_blank"
+    >
+      Get a key
+      <ExternalLink className="size-3" />
+    </a>
+  )
+}
+
+/** One credential row — collapsible; description and docs link expand on click. */
+export function CredentialKeyCard({
+  expanded,
+  info,
+  label,
+  onExpand,
+  onToggle,
+  placeholder,
+  rowProps,
+  varKey
+}: CredentialKeyCardProps) {
+  const docsUrl = info.url?.trim()
+  const description = info.description?.trim()
+  const expandable = Boolean(description || docsUrl)
+
+  return (
+    <div
+      className={cn(
+        'group/card rounded-[6px] px-2 py-1 transition-colors',
+        expandable && 'cursor-pointer',
+        expandable && !expanded && 'hover:bg-(--ui-row-hover-background)',
+        expanded && 'bg-(--ui-bg-quaternary) ring-1 ring-(--ui-stroke-secondary)'
+      )}
+      onClick={expandable ? onToggle : undefined}
+      onKeyDown={
+        expandable
+          ? e => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault()
+                onToggle()
+              }
+            }
+          : undefined
+      }
+      role={expandable ? 'button' : undefined}
+      tabIndex={expandable ? 0 : undefined}
+    >
+      <div className="grid gap-3 py-2 sm:grid-cols-[minmax(0,1fr)_minmax(15rem,22rem)] sm:items-center">
+        <div className="flex min-w-0 items-center gap-2">
+          <span
+            className={cn(
+              'size-2 shrink-0 rounded-full',
+              info.is_set ? 'bg-primary' : 'bg-(--ui-stroke-secondary)'
+            )}
+          />
+
+          <span className="min-w-0 truncate text-[length:var(--conversation-text-font-size)] font-medium text-foreground">
+            {label}
+          </span>
+
+          {expandable && (
+            <ChevronDown
+              className={cn(
+                'size-3.5 shrink-0 text-muted-foreground transition',
+                expanded ? 'rotate-180 opacity-100' : 'opacity-0 group-hover/card:opacity-100'
+              )}
+            />
+          )}
+        </div>
+
+        <div
+          className="min-w-0 sm:justify-self-end"
+          onClick={e => e.stopPropagation()}
+          onFocus={() => {
+            if (expandable && !expanded) {
+              onExpand()
+            }
+          }}
+        >
+          <KeyField info={info} placeholder={placeholder} rowProps={rowProps} varKey={varKey} />
+        </div>
+      </div>
+
+      {expandable && expanded && (
+        <div className="grid gap-2.5 pb-2 pl-4" onClick={e => e.stopPropagation()}>
+          {description && (
+            <p className="text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
+              {description}
+            </p>
+          )}
+
+          {docsUrl && <CredentialDocsLink href={docsUrl} />}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/** Provider API key group — collapsible card; description, docs link, and advanced fields expand on click. */
+export function ProviderKeyRows({ expanded, group, onExpand, onToggle, rowProps }: ProviderKeyRowsProps) {
+  const docsUrl = group.docsUrl?.trim()
+  const description = group.description?.trim()
+  const expandable = Boolean(description || docsUrl || group.advanced.length > 0)
+
+  return (
+    <div
+      className={cn(
+        'group/card rounded-[6px] px-2 py-1 transition-colors',
+        expandable && 'cursor-pointer',
+        expandable && !expanded && 'hover:bg-(--ui-row-hover-background)',
+        expanded && 'bg-(--ui-bg-quaternary) ring-1 ring-(--ui-stroke-secondary)'
+      )}
+      onClick={expandable ? onToggle : undefined}
+      onKeyDown={
+        expandable
+          ? e => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault()
+                onToggle()
+              }
+            }
+          : undefined
+      }
+      role={expandable ? 'button' : undefined}
+      tabIndex={expandable ? 0 : undefined}
+    >
+      <div className="grid gap-3 py-2 sm:grid-cols-[minmax(0,1fr)_minmax(15rem,22rem)] sm:items-center">
+        <div className="flex min-w-0 items-center gap-2">
+          <span
+            className={cn(
+              'size-2 shrink-0 rounded-full',
+              group.hasAnySet ? 'bg-primary' : 'bg-(--ui-stroke-secondary)'
+            )}
+          />
+
+          <span className="min-w-0 truncate text-[length:var(--conversation-text-font-size)] font-medium text-foreground">
+            {group.name}
+          </span>
+
+          {expandable && (
+            <ChevronDown
+              className={cn(
+                'size-3.5 shrink-0 text-muted-foreground transition',
+                expanded ? 'rotate-180 opacity-100' : 'opacity-0 group-hover/card:opacity-100'
+              )}
+            />
+          )}
+        </div>
+
+        <div
+          className="min-w-0 sm:justify-self-end"
+          onClick={e => e.stopPropagation()}
+          onFocus={() => {
+            if (expandable && !expanded) {
+              onExpand()
+            }
+          }}
+        >
+          <KeyField
+            info={group.primary[1]}
+            placeholder={`Paste ${group.name} key`}
+            rowProps={rowProps}
+            varKey={group.primary[0]}
+          />
+        </div>
+      </div>
+
+      {expandable && expanded && (
+        <div className="grid gap-2.5 pb-2 pl-4" onClick={e => e.stopPropagation()}>
+          {description && (
+            <p className="text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
+              {description}
+            </p>
+          )}
+
+          {group.advanced.map(([key, info]) => {
+            const fieldLabel = isKeyVar(key, info)
+              ? prettyName(key.replace(/(?:_API_KEY|_TOKEN|_KEY)$/i, ''))
+              : friendlyFieldLabel(key, info)
+
+            return (
+              <ListRow
+                action={
+                  <KeyField
+                    info={info}
+                    placeholder={credentialPlaceholder(key, info, fieldLabel)}
+                    rowProps={rowProps}
+                    varKey={key}
+                  />
+                }
+                key={key}
+                title={fieldLabel}
+              />
+            )
+          })}
+
+          {docsUrl && <CredentialDocsLink href={docsUrl} />}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export function credentialRowLabel(varKey: string, info: EnvVarInfo): string {
+  if (isKeyVar(varKey, info)) {
+    return prettyName(varKey.replace(/(?:_API_KEY|_TOKEN|_KEY)$/i, ''))
+  }
+
+  return prettyName(varKey)
+}
+
+interface CredentialKeyCardProps {
+  expanded: boolean
+  info: EnvVarInfo
+  label: string
+  onExpand: () => void
+  onToggle: () => void
+  placeholder: string
+  rowProps: KeyRowProps
+  varKey: string
+}
+
+interface ProviderKeyRowsProps {
+  expanded: boolean
+  group: ProviderKeyRowGroup
+  onExpand: () => void
+  onToggle: () => void
+  rowProps: KeyRowProps
+}
+
+export interface ProviderKeyRowGroup {
+  advanced: [string, EnvVarInfo][]
+  description?: string
+  docsUrl?: string
+  hasAnySet: boolean
+  name: string
+  primary: [string, EnvVarInfo]
+}

apps/desktop/src/app/settings/env-credentials.tsx

@@ -0,0 +1,194 @@
+import { useEffect, useState } from 'react'
+
+import { deleteEnvVar, getEnvVars, revealEnvVar, setEnvVar } from '@/hermes'
+import { type IconComponent } from '@/lib/icons'
+import { notify, notifyError } from '@/store/notifications'
+import type { EnvVarInfo } from '@/types/hermes'
+
+import { asText, includesQuery, redactedValue, withoutKey } from './helpers'
+import { Pill } from './primitives'
+import type { EnvRowProps } from './types'
+
+// Shared filter used by every credential surface (Providers + Keys pages):
+// category gate first, then a free-text match across key name + description.
+export function filterEnv(info: EnvVarInfo, key: string, q: string, cat: string, extra?: string): boolean {
+  if (asText(info.category) !== cat) {
+    return false
+  }
+
+  if (!q) {
+    return true
+  }
+
+  return (
+    key.toLowerCase().includes(q) ||
+    includesQuery(info.description, q) ||
+    Boolean(extra && extra.toLowerCase().includes(q))
+  )
+}
+
+export function SettingsCategoryHeading({ count, icon: Icon, title }: CategoryHeadingProps) {
+  return (
+    <div className="mb-3 flex items-center gap-2 text-[length:var(--conversation-text-font-size)] font-medium">
+      <Icon className="size-4 text-muted-foreground" />
+      <span>{title}</span>
+      {count && <Pill>{count}</Pill>}
+    </div>
+  )
+}
+
+// Owns the env-var fetch + the edit/reveal/save/delete lifecycle so multiple
+// credential pages (Providers, Keys) share one source of truth and one set of
+// mutation handlers instead of duplicating the plumbing.
+export function useEnvCredentials(): UseEnvCredentials {
+  const [vars, setVars] = useState<Record<string, EnvVarInfo> | null>(null)
+  const [edits, setEdits] = useState<Record<string, string>>({})
+  const [revealed, setRevealed] = useState<Record<string, string>>({})
+  const [saving, setSaving] = useState<string | null>(null)
+
+  // Best-effort cleanup of a retired localStorage flag (global "Show
+  // advanced" toggle) — everything in these views is configuration-level.
+  useEffect(() => {
+    try {
+      window.localStorage.removeItem('desktop.settings.keys.show_advanced')
+    } catch {
+      // Ignore — old key cleanup is best-effort.
+    }
+  }, [])
+
+  useEffect(() => {
+    let cancelled = false
+
+    void (async () => {
+      try {
+        const next = await getEnvVars()
+
+        if (!cancelled) {
+          setVars(next)
+        }
+      } catch (err) {
+        notifyError(err, 'API keys failed to load')
+      }
+    })()
+
+    return () => void (cancelled = true)
+  }, [])
+
+  function patchVar(key: string, patch: Partial<Pick<EnvVarInfo, 'is_set' | 'redacted_value'>>) {
+    setVars(c => (c ? { ...c, [key]: { ...c[key], ...patch } } : c))
+  }
+
+  function clearLocalState(key: string) {
+    setEdits(c => withoutKey(c, key))
+    setRevealed(c => withoutKey(c, key))
+  }
+
+  async function handleSave(key: string) {
+    const value = edits[key]
+
+    if (!value) {
+      return
+    }
+
+    setSaving(key)
+
+    try {
+      await setEnvVar(key, value)
+      patchVar(key, { is_set: true, redacted_value: redactedValue(value) })
+      clearLocalState(key)
+      notify({ kind: 'success', title: 'Credential saved', message: `${key} updated.` })
+    } catch (err) {
+      notifyError(err, `Failed to save ${key}`)
+    } finally {
+      setSaving(null)
+    }
+  }
+
+  // Direct save for a known value (no edit-state round-trip) — used by the
+  // onboarding-style key form, which owns its own input. Returns a result so
+  // the form can surface inline errors instead of only toasting.
+  async function saveValue(key: string, value: string): Promise<{ message?: string; ok: boolean }> {
+    const trimmed = value.trim()
+
+    if (!trimmed) {
+      return { message: 'Enter a value first.', ok: false }
+    }
+
+    setSaving(key)
+
+    try {
+      await setEnvVar(key, trimmed)
+      patchVar(key, { is_set: true, redacted_value: redactedValue(trimmed) })
+      clearLocalState(key)
+      notify({ kind: 'success', message: `${key} updated.`, title: 'Credential saved' })
+
+      return { ok: true }
+    } catch (err) {
+      notifyError(err, `Failed to save ${key}`)
+
+      return { message: err instanceof Error ? err.message : 'Could not save credential.', ok: false }
+    } finally {
+      setSaving(null)
+    }
+  }
+
+  async function handleClear(key: string) {
+    if (!window.confirm(`Remove ${key} from .env?`)) {
+      return
+    }
+
+    setSaving(key)
+
+    try {
+      await deleteEnvVar(key)
+      patchVar(key, { is_set: false, redacted_value: null })
+      clearLocalState(key)
+      notify({ kind: 'success', title: 'Credential removed', message: `${key} removed.` })
+    } catch (err) {
+      notifyError(err, `Failed to remove ${key}`)
+    } finally {
+      setSaving(null)
+    }
+  }
+
+  async function handleReveal(key: string) {
+    if (revealed[key]) {
+      setRevealed(c => withoutKey(c, key))
+
+      return
+    }
+
+    try {
+      const result = await revealEnvVar(key)
+      setRevealed(c => ({ ...c, [key]: result.value }))
+    } catch (err) {
+      notifyError(err, `Failed to reveal ${key}`)
+    }
+  }
+
+  return {
+    saveValue,
+    vars,
+    rowProps: {
+      edits,
+      revealed,
+      saving,
+      setEdits,
+      onSave: handleSave,
+      onClear: handleClear,
+      onReveal: handleReveal
+    }
+  }
+}
+
+interface CategoryHeadingProps {
+  count?: string
+  icon: IconComponent
+  title: string
+}
+
+interface UseEnvCredentials {
+  rowProps: Omit<EnvRowProps, 'varKey' | 'info'>
+  saveValue: (key: string, value: string) => Promise<{ message?: string; ok: boolean }>
+  vars: Record<string, EnvVarInfo> | null
+}

apps/desktop/src/app/settings/env-var-actions-menu.tsx

@@ -0,0 +1,130 @@
+import type * as React from 'react'
+
+import { Button } from '@/components/ui/button'
+import { Codicon } from '@/components/ui/codicon'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger
+} from '@/components/ui/dropdown-menu'
+import { Eye, EyeOff, ExternalLink, Trash2 } from '@/lib/icons'
+import { triggerHaptic } from '@/lib/haptics'
+import { cn } from '@/lib/utils'
+
+interface EnvVarActionsMenuProps
+  extends Pick<React.ComponentProps<typeof DropdownMenuContent>, 'align' | 'sideOffset'> {
+  children: React.ReactNode
+  clearDisabled?: boolean
+  docsUrl?: string | null
+  isRevealed?: boolean
+  isSet: boolean
+  label: string
+  onClear?: () => void
+  onEdit: () => void
+  onReveal?: () => void
+  showReveal?: boolean
+}
+
+export function EnvVarActionsMenu({
+  align = 'end',
+  children,
+  clearDisabled = false,
+  docsUrl,
+  isRevealed = false,
+  isSet,
+  label,
+  onClear,
+  onEdit,
+  onReveal,
+  showReveal = true,
+  sideOffset = 6
+}: EnvVarActionsMenuProps) {
+  const hasClear = isSet && onClear
+  const hasReveal = isSet && showReveal && onReveal
+  const hasDocs = Boolean(docsUrl?.trim())
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>{children}</DropdownMenuTrigger>
+      <DropdownMenuContent
+        align={align}
+        aria-label={`Actions for ${label}`}
+        className="w-44"
+        sideOffset={sideOffset}
+      >
+        {hasDocs && (
+          <DropdownMenuItem
+            onSelect={event => {
+              event.preventDefault()
+              triggerHaptic('selection')
+              window.open(docsUrl!, '_blank', 'noopener,noreferrer')
+            }}
+          >
+            <ExternalLink className="size-3.5" />
+            <span>Docs</span>
+          </DropdownMenuItem>
+        )}
+
+        {hasReveal && (
+          <DropdownMenuItem
+            onSelect={() => {
+              triggerHaptic('selection')
+              onReveal()
+            }}
+          >
+            {isRevealed ? <EyeOff className="size-3.5" /> : <Eye className="size-3.5" />}
+            <span>{isRevealed ? 'Hide value' : 'Reveal value'}</span>
+          </DropdownMenuItem>
+        )}
+
+        <DropdownMenuItem
+          onSelect={() => {
+            triggerHaptic('selection')
+            onEdit()
+          }}
+        >
+          <Codicon name="edit" size="0.875rem" />
+          <span>{isSet ? 'Replace' : 'Set'}</span>
+        </DropdownMenuItem>
+
+        {hasClear && (
+          <>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem
+              disabled={clearDisabled}
+              onSelect={() => {
+                triggerHaptic('warning')
+                onClear()
+              }}
+              variant="destructive"
+            >
+              <Trash2 className="size-3.5" />
+              <span>Clear</span>
+            </DropdownMenuItem>
+          </>
+        )}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+interface EnvVarActionsTriggerProps extends Omit<React.ComponentProps<typeof Button>, 'size' | 'variant'> {
+  label: string
+}
+
+export function EnvVarActionsTrigger({ className, label, ...props }: EnvVarActionsTriggerProps) {
+  return (
+    <Button
+      aria-label={`Actions for ${label}`}
+      className={cn('text-muted-foreground hover:text-foreground', className)}
+      size="icon-sm"
+      title="Credential actions"
+      variant="ghost"
+      {...props}
+    >
+      <Codicon name="ellipsis" size="0.875rem" />
+    </Button>
+  )
+}

apps/desktop/src/app/settings/gateway-settings.tsx

@@ -1,8 +1,9 @@
-import { useEffect, useMemo, useState } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
 
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
-import { AlertCircle, Check, FileText, Globe, Loader2, Monitor } from '@/lib/icons'
+import type { DesktopAuthProvider, DesktopConnectionProbeResult } from '@/global'
+import { AlertCircle, Check, FileText, Globe, Loader2, LogIn, Monitor } from '@/lib/icons'
 import { cn } from '@/lib/utils'
 import { notify, notifyError } from '@/store/notifications'
 
@@ -10,10 +11,14 @@ import { CONTROL_TEXT } from './constants'
 import { EmptyState, ListRow, LoadingState, Pill, SettingsContent } from './primitives'
 
 type Mode = 'local' | 'remote'
+type AuthMode = 'oauth' | 'token'
+type ProbeStatus = 'idle' | 'probing' | 'done' | 'error'
 
 interface GatewaySettingsState {
   envOverride: boolean
   mode: Mode
+  remoteAuthMode: AuthMode
+  remoteOauthConnected: boolean
   remoteTokenPreview: string | null
   remoteTokenSet: boolean
   remoteUrl: string
@@ -22,6 +27,8 @@ interface GatewaySettingsState {
 const EMPTY_STATE: GatewaySettingsState = {
   envOverride: false,
   mode: 'local',
+  remoteAuthMode: 'token',
+  remoteOauthConnected: false,
   remoteTokenPreview: null,
   remoteTokenSet: false,
   remoteUrl: ''
@@ -71,10 +78,18 @@ export function GatewaySettings() {
   const [loading, setLoading] = useState(true)
   const [saving, setSaving] = useState(false)
   const [testing, setTesting] = useState(false)
+  const [signingIn, setSigningIn] = useState(false)
   const [state, setState] = useState<GatewaySettingsState>(EMPTY_STATE)
   const [remoteToken, setRemoteToken] = useState('')
   const [lastTest, setLastTest] = useState<null | string>(null)
 
+  // Auth-mode probe: as the user types a remote URL we ask the gateway (via
+  // its public /api/status) whether it gates with OAuth or a static session
+  // token, so we can show the right control (login button vs token box).
+  const [probeStatus, setProbeStatus] = useState<ProbeStatus>('idle')
+  const [probe, setProbe] = useState<DesktopConnectionProbeResult | null>(null)
+  const probeSeq = useRef(0)
+
   useEffect(() => {
     let cancelled = false
     const desktop = window.hermesDesktop
@@ -104,15 +119,129 @@ export function GatewaySettings() {
     return () => void (cancelled = true)
   }, [])
 
-  const canUseRemote = useMemo(
-    () => Boolean(state.remoteUrl.trim()) && (Boolean(remoteToken.trim()) || state.remoteTokenSet),
-    [remoteToken, state.remoteTokenSet, state.remoteUrl]
-  )
+  // Debounced probe of the entered remote URL. Only runs in remote mode with a
+  // syntactically plausible URL. The probe result drives whether we render the
+  // OAuth login button or the session-token entry box. The effective auth mode
+  // prefers a fresh probe result over the saved value.
+  const trimmedUrl = state.remoteUrl.trim()
+  useEffect(() => {
+    if (state.mode !== 'remote' || !trimmedUrl || !/^https?:\/\//i.test(trimmedUrl)) {
+      setProbeStatus('idle')
+      setProbe(null)
+
+      return
+    }
+
+    const desktop = window.hermesDesktop
+
+    if (!desktop?.probeConnectionConfig) {
+      return
+    }
+
+    const seq = ++probeSeq.current
+    setProbeStatus('probing')
+
+    const timer = setTimeout(() => {
+      desktop
+        .probeConnectionConfig(trimmedUrl)
+        .then(result => {
+          if (seq !== probeSeq.current) {
+            return
+          }
+
+          setProbe(result)
+          setProbeStatus(result.reachable ? 'done' : 'error')
+        })
+        .catch(() => {
+          if (seq !== probeSeq.current) {
+            return
+          }
+
+          setProbe(null)
+          setProbeStatus('error')
+        })
+    }, 500)
+
+    return () => clearTimeout(timer)
+  }, [state.mode, trimmedUrl])
+
+  // Effective auth mode: a reachable probe wins; otherwise fall back to the
+  // saved config's mode so a re-open of settings doesn't flicker.
+  const authMode: AuthMode = useMemo(() => {
+    if (probeStatus === 'done' && probe && probe.authMode !== 'unknown') {
+      return probe.authMode
+    }
+
+    return state.remoteAuthMode
+  }, [probe, probeStatus, state.remoteAuthMode])
+
+  // Whether we actually KNOW how this gateway authenticates yet. Until we do,
+  // neither the OAuth button nor the session-token box should render —
+  // `authMode` defaults to 'token', so without this gate the token box flashes
+  // for every gateway (including OAuth ones) during the idle/probing window
+  // before the first probe lands. The scheme is known when either:
+  //   * the live probe finished (probeStatus 'done'), or
+  //   * we're idle but showing a previously-saved remote config (re-opening
+  //     settings for a gateway already signed-in or with a saved token), so
+  //     its control appears immediately with no flicker.
+  // While probing (or after a probe error), the scheme is unknown and we show
+  // the probe status row instead of a control.
+  const hasSavedRemote = state.remoteTokenSet || state.remoteOauthConnected
+
+  const authResolved = useMemo(() => {
+    if (probeStatus === 'done') {
+      return true
+    }
+
+    return probeStatus === 'idle' && hasSavedRemote
+  }, [probeStatus, hasSavedRemote])
+
+  const providerLabel = useMemo(() => {
+    const providers: DesktopAuthProvider[] = probe?.providers ?? []
+
+    if (providers.length === 1) {
+      return providers[0].displayName || providers[0].name
+    }
+
+    if (providers.length > 1) {
+      return providers.map(p => p.displayName || p.name).join(' / ')
+    }
+
+    return 'your identity provider'
+  }, [probe])
+
+  // A username/password gateway authenticates through a credential form on the
+  // gateway's /login page (POST /auth/password-login) rather than an OAuth
+  // redirect. Everything downstream — the session cookie, the ws-ticket mint,
+  // the persistent partition — is identical, so the desktop drives it through
+  // the same sign-in window; only the button copy changes. We treat the
+  // gateway as password-style only when EVERY advertised provider supports
+  // password, so a mixed deployment keeps the generic OAuth copy.
+  const isPasswordProvider = useMemo(() => {
+    const providers: DesktopAuthProvider[] = probe?.providers ?? []
+
+    return providers.length > 0 && providers.every(p => p.supportsPassword)
+  }, [probe])
+
+  const oauthConnected = state.remoteOauthConnected
+
+  const canUseRemote = useMemo(() => {
+    if (!trimmedUrl) {
+      return false
+    }
+
+    if (authMode === 'oauth') {
+      return oauthConnected
+    }
+
+    return Boolean(remoteToken.trim()) || state.remoteTokenSet
+  }, [authMode, oauthConnected, remoteToken, state.remoteTokenSet, trimmedUrl])
 
   const payload = () => ({
     mode: state.mode,
-    remoteToken: remoteToken.trim() || undefined,
-    remoteUrl: state.remoteUrl.trim()
+    remoteAuthMode: authMode,
+    remoteToken: authMode === 'token' ? remoteToken.trim() || undefined : undefined,
+    remoteUrl: trimmedUrl
   })
 
   const save = async (apply: boolean) => {
@@ -120,7 +249,10 @@ export function GatewaySettings() {
       notify({
         kind: 'warning',
         title: 'Remote gateway incomplete',
-        message: 'Enter a remote URL and session token before switching to remote.'
+        message:
+          authMode === 'oauth'
+            ? 'Enter a remote URL and sign in before switching to remote.'
+            : 'Enter a remote URL and session token before switching to remote.'
       })
 
       return
@@ -147,12 +279,73 @@ export function GatewaySettings() {
     }
   }
 
+  // OAuth sign-in: persist the URL + oauth mode first (so the saved config has
+  // the URL the login window needs), then open the gateway login window and
+  // refresh the connection status from the saved config once it completes.
+  const signIn = async () => {
+    if (!trimmedUrl) {
+      notify({ kind: 'warning', title: 'Remote gateway incomplete', message: 'Enter a remote URL first.' })
+
+      return
+    }
+
+    setSigningIn(true)
+
+    try {
+      // Save (don't apply/restart) so the login window has a URL to use and the
+      // oauth mode is persisted, without yet flipping the live connection.
+      const saved = await window.hermesDesktop.saveConnectionConfig({
+        mode: state.mode,
+        remoteAuthMode: 'oauth',
+        remoteUrl: trimmedUrl
+      })
+
+      setState(saved)
+
+      const result = await window.hermesDesktop.oauthLoginConnectionConfig(trimmedUrl)
+
+      if (result.connected) {
+        const refreshed = await window.hermesDesktop.getConnectionConfig()
+        setState(refreshed)
+        notify({ kind: 'success', title: 'Signed in', message: `Connected to ${providerLabel}.` })
+      } else {
+        notify({
+          kind: 'warning',
+          title: 'Sign-in incomplete',
+          message: 'The login window closed before authentication finished.'
+        })
+      }
+    } catch (err) {
+      notifyError(err, 'Sign-in failed')
+    } finally {
+      setSigningIn(false)
+    }
+  }
+
+  const signOut = async () => {
+    setSigningIn(true)
+
+    try {
+      await window.hermesDesktop.oauthLogoutConnectionConfig(trimmedUrl || undefined)
+      const refreshed = await window.hermesDesktop.getConnectionConfig()
+      setState(refreshed)
+      notify({ kind: 'success', title: 'Signed out', message: 'Cleared the remote gateway session.' })
+    } catch (err) {
+      notifyError(err, 'Sign-out failed')
+    } finally {
+      setSigningIn(false)
+    }
+  }
+
   const testRemote = async () => {
     if (!canUseRemote) {
       notify({
         kind: 'warning',
         title: 'Remote gateway incomplete',
-        message: 'Enter a remote URL and session token before testing.'
+        message:
+          authMode === 'oauth'
+            ? 'Enter a remote URL and sign in before testing.'
+            : 'Enter a remote URL and session token before testing.'
       })
 
       return
@@ -164,8 +357,9 @@ export function GatewaySettings() {
     try {
       const result = await window.hermesDesktop.testConnectionConfig({
         mode: 'remote',
-        remoteToken: remoteToken.trim() || undefined,
-        remoteUrl: state.remoteUrl.trim()
+        remoteAuthMode: authMode,
+        remoteToken: authMode === 'token' ? remoteToken.trim() || undefined : undefined,
+        remoteUrl: trimmedUrl
       })
 
       const message = `Connected to ${result.baseUrl}${result.version ? ` · Hermes ${result.version}` : ''}`
@@ -229,7 +423,7 @@ export function GatewaySettings() {
         />
         <ModeCard
           active={state.mode === 'remote'}
-          description="Connect this desktop shell to a remote Hermes backend using its session token."
+          description="Connect this desktop shell to a remote Hermes backend. Hosted gateways use OAuth or a username and password; self-hosted ones may use a session token."
           disabled={state.envOverride}
           icon={Globe}
           onSelect={() => setState(current => ({ ...current, mode: 'remote' }))}
@@ -237,7 +431,7 @@ export function GatewaySettings() {
         />
       </div>
 
-      <div className="mt-5 divide-y divide-border/40">
+      <div className="mt-5 grid gap-1">
         <ListRow
           action={
             <Input
@@ -251,49 +445,103 @@ export function GatewaySettings() {
           description="Base URL for the remote dashboard backend. Path prefixes are supported, for example /hermes."
           title="Remote URL"
         />
-        <ListRow
-          action={
-            <Input
-              autoComplete="off"
-              className={cn('h-8 font-mono', CONTROL_TEXT)}
-              disabled={state.envOverride}
-              onChange={event => setRemoteToken(event.target.value)}
-              placeholder={
-                state.remoteTokenSet ? `Existing token ${state.remoteTokenPreview ?? 'saved'}` : 'Paste session token'
-              }
-              type="password"
-              value={remoteToken}
-            />
-          }
-          description="The dashboard session token used for REST and WebSocket access. Leave blank to keep the saved token."
-          title="Session token"
-        />
+
+        {state.mode === 'remote' && probeStatus === 'probing' ? (
+          <div className="flex items-center gap-2 py-3 text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
+            <Loader2 className="size-4 animate-spin" />
+            Checking how this gateway authenticates…
+          </div>
+        ) : null}
+
+        {state.mode === 'remote' && probeStatus === 'error' ? (
+          <div className="flex items-start gap-2 py-3 text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
+            <AlertCircle className="mt-0.5 size-4 shrink-0" />
+            Could not reach this gateway yet. Check the URL — the auth method will appear once it responds.
+          </div>
+        ) : null}
+
+        {/* OAuth / password gateways: present a sign-in button + connection status. */}
+        {state.mode === 'remote' && authResolved && authMode === 'oauth' ? (
+          <ListRow
+            action={
+              oauthConnected ? (
+                <div className="flex items-center gap-2">
+                  <Pill tone="primary">
+                    <Check className="size-3" /> Signed in
+                  </Pill>
+                  <Button disabled={signingIn || state.envOverride} onClick={() => void signOut()} variant="outline">
+                    {signingIn ? <Loader2 className="size-4 animate-spin" /> : null}
+                    Sign out
+                  </Button>
+                </div>
+              ) : (
+                <Button disabled={signingIn || state.envOverride || !trimmedUrl} onClick={() => void signIn()}>
+                  {signingIn ? <Loader2 className="size-4 animate-spin" /> : <LogIn className="size-4" />}
+                  {isPasswordProvider ? 'Sign in' : `Sign in with ${providerLabel}`}
+                </Button>
+              )
+            }
+            description={
+              oauthConnected
+                ? isPasswordProvider
+                  ? 'This gateway uses a username and password. You are signed in; the session refreshes automatically.'
+                  : 'This gateway uses OAuth. You are signed in; the session refreshes automatically.'
+                : isPasswordProvider
+                  ? 'This gateway uses a username and password. Sign in to authorize this desktop app.'
+                  : `This gateway uses OAuth. Sign in with ${providerLabel} to authorize this desktop app.`
+            }
+            title="Authentication"
+          />
+        ) : null}
+
+        {/* Session-token gateways: keep the existing token entry box. */}
+        {state.mode === 'remote' && authResolved && authMode === 'token' ? (
+          <ListRow
+            action={
+              <Input
+                autoComplete="off"
+                className={cn('h-8 font-mono', CONTROL_TEXT)}
+                disabled={state.envOverride}
+                onChange={event => setRemoteToken(event.target.value)}
+                placeholder={
+                  state.remoteTokenSet ? `Existing token ${state.remoteTokenPreview ?? 'saved'}` : 'Paste session token'
+                }
+                type="password"
+                value={remoteToken}
+              />
+            }
+            description="The dashboard session token used for REST and WebSocket access. Leave blank to keep the saved token."
+            title="Session token"
+          />
+        ) : null}
       </div>
 
       {lastTest ? <div className="mt-4 text-xs text-primary">{lastTest}</div> : null}
 
-      <div className="mt-6 flex flex-wrap justify-end gap-3">
+      <div className="mt-6 flex flex-wrap items-center justify-end gap-4">
         <Button
+          className="mr-auto"
           disabled={state.envOverride || testing || !canUseRemote}
           onClick={() => void testRemote()}
-          variant="outline"
+          size="sm"
+          variant="text"
         >
           {testing ? <Loader2 className="size-4 animate-spin" /> : null}
           Test remote
         </Button>
-        <Button disabled={state.envOverride || saving} onClick={() => void save(false)} variant="outline">
+        <Button disabled={state.envOverride || saving} onClick={() => void save(false)} size="sm" variant="textStrong">
           Save for next restart
         </Button>
-        <Button disabled={state.envOverride || saving} onClick={() => void save(true)}>
+        <Button disabled={state.envOverride || saving} onClick={() => void save(true)} size="sm">
           {saving ? <Loader2 className="size-4 animate-spin" /> : null}
           Save and reconnect
         </Button>
       </div>
 
-      <div className="mt-6 divide-y divide-border/40">
+      <div className="mt-6 grid gap-1">
         <ListRow
           action={
-            <Button onClick={() => void window.hermesDesktop?.revealLogs()} variant="outline">
+            <Button onClick={() => void window.hermesDesktop?.revealLogs()} size="sm" variant="textStrong">
               <FileText className="size-4" />
               Open logs
             </Button>

apps/desktop/src/app/settings/helpers.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 
 import type { HermesConfigRecord } from '@/types/hermes'
 
-import { getNested, setNested } from './helpers'
+import { getNested, providerGroup, setNested, stripToolsetLabel, toolsetDisplayLabel } from './helpers'
 
 describe('settings helpers', () => {
   it('reads and writes nested config paths', () => {
@@ -20,4 +20,48 @@ describe('settings helpers', () => {
     expect(() => setNested(config, 'constructor.prototype.polluted', true)).toThrow('Unsafe config path')
     expect(({} as Record<string, unknown>).polluted).toBeUndefined()
   })
+
+  describe('stripToolsetLabel', () => {
+    it('removes leading emoji prefixes from registry labels', () => {
+      expect(stripToolsetLabel('⏰ Cron Jobs')).toBe('Cron Jobs')
+      expect(stripToolsetLabel('⚡ Code Execution')).toBe('Code Execution')
+      expect(stripToolsetLabel('❓ Clarifying Questions')).toBe('Clarifying Questions')
+      expect(stripToolsetLabel('🌐 Browser Automation')).toBe('Browser Automation')
+      expect(stripToolsetLabel('🎨 Image Generation')).toBe('Image Generation')
+    })
+
+    it('leaves plain titles unchanged', () => {
+      expect(stripToolsetLabel('Terminal & Processes')).toBe('Terminal & Processes')
+    })
+  })
+
+  describe('toolsetDisplayLabel', () => {
+    it('strips emoji from toolset rows', () => {
+      expect(toolsetDisplayLabel({ name: 'cronjob', label: '⏰ Cron Jobs' })).toBe('Cron Jobs')
+    })
+  })
+
+  describe('providerGroup', () => {
+    it('maps a provider env var to its labeled group', () => {
+      expect(providerGroup('XAI_API_KEY')).toBe('xAI')
+      expect(providerGroup('NOUS_API_KEY')).toBe('Nous Portal')
+      expect(providerGroup('OPENROUTER_API_KEY')).toBe('OpenRouter')
+    })
+
+    it('prefers the longest matching prefix so CN/regional buckets win', () => {
+      // MINIMAX_CN_ must beat the generic MINIMAX_ prefix.
+      expect(providerGroup('MINIMAX_CN_API_KEY')).toBe('MiniMax (China)')
+      expect(providerGroup('MINIMAX_API_KEY')).toBe('MiniMax')
+      // KIMI_CN_ likewise must beat KIMI_.
+      expect(providerGroup('KIMI_CN_API_KEY')).toBe('Kimi (China)')
+      expect(providerGroup('KIMI_API_KEY')).toBe('Kimi / Moonshot')
+      // HERMES_QWEN_ and HERMES_GEMINI_ both share the HERMES_ stem.
+      expect(providerGroup('HERMES_QWEN_BASE_URL')).toBe('DashScope (Qwen)')
+      expect(providerGroup('HERMES_GEMINI_CLIENT_ID')).toBe('Gemini')
+    })
+
+    it('falls back to "Other" for un-grouped env vars', () => {
+      expect(providerGroup('SOMETHING_RANDOM')).toBe('Other')
+    })
+  })
 })

apps/desktop/src/app/settings/helpers.ts

@@ -8,6 +8,13 @@ export const includesQuery = (v: unknown, q: string) => asText(v).toLowerCase().
 
 export const prettyName = (v: string) => v.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase())
 
+/** Strip leading emoji from toolset titles (CLI registry prefixes labels with icons). */
+export const stripToolsetLabel = (label: string): string =>
+  label.replace(/^[\p{Emoji}\p{Extended_Pictographic}\s]+/u, '').trim() || label
+
+export const toolsetDisplayLabel = (toolset: Pick<ToolsetInfo, 'label' | 'name'>): string =>
+  stripToolsetLabel(asText(toolset.label || toolset.name))
+
 export const toolNames = (t: ToolsetInfo) => (Array.isArray(t.tools) ? t.tools.map(asText).filter(Boolean) : [])
 
 export const withoutKey = <T>(record: Record<string, T>, key: string) => {
@@ -19,9 +26,30 @@ export const withoutKey = <T>(record: Record<string, T>, key: string) => {
 
 export const redactedValue = (v: string) => (v.length <= 8 ? '••••' : `${v.slice(0, 4)}...${v.slice(-4)}`)
 
-export const providerGroup = (key: string) => PROVIDER_GROUPS.find(g => key.startsWith(g.prefix))?.name ?? 'Other'
+// Longest-prefix match so a more specific group like ``MINIMAX_CN_`` is
+// chosen over its shorter parent ``MINIMAX_``. Falls back to the bucket
+// "Other" used by the Keys settings view for un-grouped env vars.
+export const providerGroup = (key: string) => {
+  let best: (typeof PROVIDER_GROUPS)[number] | undefined
 
-export const providerPriority = (name: string) => PROVIDER_GROUPS.find(g => g.name === name)?.priority ?? 99
+  for (const candidate of PROVIDER_GROUPS) {
+    if (!key.startsWith(candidate.prefix)) {
+      continue
+    }
+
+    if (!best || candidate.prefix.length > best.prefix.length) {
+      best = candidate
+    }
+  }
+
+  return best?.name ?? 'Other'
+}
+
+export const providerMeta = (name: string) =>
+  PROVIDER_GROUPS.find(g => g.name === name && (g.description || g.docsUrl)) ??
+  PROVIDER_GROUPS.find(g => g.name === name)
+
+export const providerPriority = (name: string) => providerMeta(name)?.priority ?? 99
 
 const POLLUTING_PATH_PARTS = new Set(['__proto__', 'constructor', 'prototype'])
 

apps/desktop/src/app/settings/index.tsx

@@ -1,29 +1,30 @@
 import { IconDownload, IconRefresh, IconUpload } from '@tabler/icons-react'
-import { useEffect, useRef, useState } from 'react'
+import { useRef } from 'react'
 
 import { getHermesConfigDefaults, getHermesConfigRecord, saveHermesConfig } from '@/hermes'
 import { triggerHaptic } from '@/lib/haptics'
-import { Archive, Globe, Info, KeyRound, Wrench } from '@/lib/icons'
+import { Archive, Globe, Info, KeyRound, Settings2, Sparkles, Wrench, Zap } from '@/lib/icons'
 import { notifyError } from '@/store/notifications'
 
 import { useRouteEnumParam } from '../hooks/use-route-enum-param'
 import { OverlayIconButton } from '../overlays/overlay-chrome'
-import { OverlaySearchInput } from '../overlays/overlay-search-input'
 import { OverlayMain, OverlayNavItem, OverlaySidebar, OverlaySplitLayout } from '../overlays/overlay-split-layout'
 import { OverlayView } from '../overlays/overlay-view'
 
 import { AboutSettings } from './about-settings'
 import { AppearanceSettings } from './appearance-settings'
 import { ConfigSettings } from './config-settings'
-import { SEARCH_PLACEHOLDER, SECTIONS } from './constants'
+import { SECTIONS } from './constants'
 import { GatewaySettings } from './gateway-settings'
-import { KeysSettings } from './keys-settings'
+import { KEYS_VIEWS, KeysSettings, type KeysView } from './keys-settings'
 import { McpSettings } from './mcp-settings'
+import { PROVIDER_VIEWS, ProvidersSettings, type ProviderView } from './providers-settings'
 import { SessionsSettings } from './sessions-settings'
-import type { SettingsPageProps, SettingsQueryKey, SettingsView as SettingsViewId } from './types'
+import type { SettingsPageProps, SettingsView as SettingsViewId } from './types'
 
 const SETTINGS_VIEWS: readonly SettingsViewId[] = [
   ...SECTIONS.map(s => `config:${s.id}` as SettingsViewId),
+  'providers',
   'gateway',
   'keys',
   'mcp',
@@ -33,23 +34,23 @@ const SETTINGS_VIEWS: readonly SettingsViewId[] = [
 
 export function SettingsView({ gateway, onClose, onConfigSaved, onMainModelChanged }: SettingsPageProps) {
   const [activeView, setActiveView] = useRouteEnumParam('tab', SETTINGS_VIEWS, 'config:model' as SettingsViewId)
+  // Providers subnav (Accounts vs API keys) lives in its own param so each
+  // sub-view is deep-linkable and survives a refresh.
+  const [providerView, setProviderView] = useRouteEnumParam<ProviderView>('pview', PROVIDER_VIEWS, 'accounts')
+  const [keysView, setKeysView] = useRouteEnumParam<KeysView>('kview', KEYS_VIEWS, 'tools')
 
-  const [queries, setQueries] = useState<Record<SettingsQueryKey, string>>({
-    about: '',
-    config: '',
-    gateway: '',
-    keys: '',
-    mcp: '',
-    sessions: ''
-  })
+  const openProviderView = (view: ProviderView) => {
+    setActiveView('providers')
+    setProviderView(view)
+  }
+
+  const openKeysView = (view: KeysView) => {
+    setActiveView('keys')
+    setKeysView(view)
+  }
 
-  const searchInputRef = useRef<HTMLInputElement>(null)
   const importInputRef = useRef<HTMLInputElement | null>(null)
 
-  const queryKey: SettingsQueryKey = activeView.startsWith('config:') ? 'config' : (activeView as SettingsQueryKey)
-  const query = queries[queryKey]
-  const setQuery = (next: string) => setQueries(c => ({ ...c, [queryKey]: next }))
-
   const exportConfig = async () => {
     try {
       const cfg = await getHermesConfigRecord()
@@ -80,35 +81,8 @@ export function SettingsView({ gateway, onClose, onConfigSaved, onMainModelChang
     }
   }
 
-  // OverlayView handles Esc; this just adds Cmd/Ctrl+P → focus search.
-  useEffect(() => {
-    const onKeyDown = (e: KeyboardEvent) => {
-      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'p') {
-        e.preventDefault()
-        searchInputRef.current?.focus()
-        searchInputRef.current?.select()
-      }
-    }
-
-    window.addEventListener('keydown', onKeyDown)
-
-    return () => window.removeEventListener('keydown', onKeyDown)
-  }, [])
-
   return (
-    <OverlayView
-      closeLabel="Close settings"
-      headerContent={
-        <OverlaySearchInput
-          containerClassName="w-[min(36rem,calc(100vw-32rem))] min-w-80"
-          inputRef={searchInputRef}
-          onChange={setQuery}
-          placeholder={SEARCH_PLACEHOLDER[queryKey]}
-          value={query}
-        />
-      }
-      onClose={onClose}
-    >
+    <OverlayView closeLabel="Close settings" onClose={onClose}>
       <OverlaySplitLayout>
         <OverlaySidebar>
           {SECTIONS.map(s => {
@@ -116,7 +90,7 @@ export function SettingsView({ gateway, onClose, onConfigSaved, onMainModelChang
 
             return (
               <OverlayNavItem
-                active={activeView === view && !queries.config.trim()}
+                active={activeView === view}
                 icon={s.icon}
                 key={s.id}
                 label={s.label}
@@ -125,6 +99,30 @@ export function SettingsView({ gateway, onClose, onConfigSaved, onMainModelChang
             )
           })}
           <div className="my-2 h-px bg-border/30" />
+          <OverlayNavItem
+            active={activeView === 'providers'}
+            icon={Zap}
+            label="Providers"
+            onClick={() => setActiveView('providers')}
+          />
+          {activeView === 'providers' && (
+            <div className="ml-3.5 flex flex-col gap-0.5 pl-1.5">
+              <OverlayNavItem
+                active={providerView === 'accounts'}
+                icon={Sparkles}
+                label="Accounts"
+                nested
+                onClick={() => openProviderView('accounts')}
+              />
+              <OverlayNavItem
+                active={providerView === 'keys'}
+                icon={KeyRound}
+                label="API keys"
+                nested
+                onClick={() => openProviderView('keys')}
+              />
+            </div>
+          )}
           <OverlayNavItem
             active={activeView === 'gateway'}
             icon={Globe}
@@ -134,9 +132,27 @@ export function SettingsView({ gateway, onClose, onConfigSaved, onMainModelChang
           <OverlayNavItem
             active={activeView === 'keys'}
             icon={KeyRound}
-            label="API Keys"
+            label="Tools & Keys"
             onClick={() => setActiveView('keys')}
           />
+          {activeView === 'keys' && (
+            <div className="ml-3.5 flex flex-col gap-0.5 pl-1.5">
+              <OverlayNavItem
+                active={keysView === 'tools'}
+                icon={Wrench}
+                label="Tools"
+                nested
+                onClick={() => openKeysView('tools')}
+              />
+              <OverlayNavItem
+                active={keysView === 'settings'}
+                icon={Settings2}
+                label="Settings"
+                nested
+                onClick={() => openKeysView('settings')}
+              />
+            </div>
+          )}
           <OverlayNavItem
             active={activeView === 'mcp'}
             icon={Wrench}
@@ -182,7 +198,7 @@ export function SettingsView({ gateway, onClose, onConfigSaved, onMainModelChang
           </div>
         </OverlaySidebar>
 
-        <OverlayMain className="p-0">
+        <OverlayMain className="px-0 pb-0 pt-[calc(var(--titlebar-height)+1rem)]">
           {activeView === 'config:appearance' ? (
             <AppearanceSettings />
           ) : activeView === 'about' ? (
@@ -195,14 +211,15 @@ export function SettingsView({ gateway, onClose, onConfigSaved, onMainModelChang
               importInputRef={importInputRef}
               onConfigSaved={onConfigSaved}
               onMainModelChanged={onMainModelChanged}
-              query={queries.config}
             />
+          ) : activeView === 'providers' ? (
+            <ProvidersSettings onViewChange={setProviderView} view={providerView} />
           ) : activeView === 'keys' ? (
-            <KeysSettings query={queries.keys} />
+            <KeysSettings view={keysView} />
           ) : activeView === 'mcp' ? (
-            <McpSettings gateway={gateway} onConfigSaved={onConfigSaved} query={queries.mcp} />
+            <McpSettings gateway={gateway} onConfigSaved={onConfigSaved} />
           ) : (
-            <SessionsSettings query={queries.sessions} />
+            <SessionsSettings />
           )}
         </OverlayMain>
       </OverlaySplitLayout>

apps/desktop/src/app/settings/keys-settings.tsx

@@ -1,431 +1,94 @@
-import { useCallback, useEffect, useMemo, useState } from 'react'
+import { useEffect, useMemo, useState } from 'react'
 
-import { Button } from '@/components/ui/button'
-import { Codicon } from '@/components/ui/codicon'
-import { Input } from '@/components/ui/input'
-import { deleteEnvVar, getEnvVars, revealEnvVar, setEnvVar } from '@/hermes'
-import { Check, Eye, EyeOff, Save, Settings2, Trash2, Zap } from '@/lib/icons'
-import { cn } from '@/lib/utils'
-import { notify, notifyError } from '@/store/notifications'
 import type { EnvVarInfo } from '@/types/hermes'
 
-import { CONTROL_TEXT } from './constants'
-import {
-  asText,
-  includesQuery,
-  prettyName,
-  providerGroup,
-  providerPriority,
-  redactedValue,
-  withoutKey
-} from './helpers'
-import { LoadingState, Pill, SectionHeading, SettingsContent } from './primitives'
-import type { EnvPatch, EnvRowProps, ProviderGroup, SearchProps } from './types'
+import { CredentialKeyCard, credentialPlaceholder, credentialRowLabel } from './credential-key-ui'
+import { useEnvCredentials } from './env-credentials'
+import { asText } from './helpers'
+import { LoadingState, SettingsContent } from './primitives'
 
-interface EnvActionsProps {
-  varKey: string
-  info: EnvVarInfo
-  saving: string | null
-  onEdit: () => void
-  onClear: (key: string) => void
-  onReveal: (key: string) => void
-  isRevealed: boolean
-  showReveal?: boolean
+// Sub-views surfaced as sidebar subnav under Tools & Keys (see settings/index.tsx).
+export const KEYS_VIEWS = ['tools', 'settings'] as const
+
+export type KeysView = (typeof KEYS_VIEWS)[number]
+
+// Providers live on their own page; messaging-platform credentials live on the
+// dedicated Messaging page (and are hidden here via `channel_managed`). This
+// view covers tool API keys plus server/setting env vars (API server, webhook,
+// gateway), which fold into the Settings subnav.
+
+// Backend categories that surface under each subnav. Platform credentials use the
+// `messaging` category but are flagged ``channel_managed`` and configured on
+// the Messaging page; only gateway-wide ``messaging`` rows (e.g. GATEWAY_PROXY)
+// appear here alongside ``setting``.
+const VIEW_CATEGORIES: Record<KeysView, readonly string[]> = {
+  settings: ['setting', 'messaging'],
+  tools: ['tool']
 }
 
-function EnvActions({
-  varKey,
-  info,
-  saving,
-  onEdit,
-  onClear,
-  onReveal,
-  isRevealed,
-  showReveal = true
-}: EnvActionsProps) {
-  return (
-    <div className="flex shrink-0 items-center gap-1.5">
-      {info.url && (
-        <Button asChild size="xs" title="Open provider docs" variant="ghost">
-          <a href={info.url} rel="noreferrer" target="_blank">
-            Docs
-          </a>
-        </Button>
-      )}
-      {info.is_set && showReveal && (
-        <Button
-          onClick={() => onReveal(varKey)}
-          size="icon-xs"
-          title={isRevealed ? 'Hide value' : 'Reveal value'}
-          variant="ghost"
-        >
-          {isRevealed ? <EyeOff /> : <Eye />}
-        </Button>
-      )}
-      <Button onClick={onEdit} size="xs" variant="outline">
-        {info.is_set ? 'Replace' : 'Set'}
-      </Button>
-      {info.is_set && (
-        <Button
-          disabled={saving === varKey}
-          onClick={() => onClear(varKey)}
-          size="icon-xs"
-          title="Clear value"
-          variant="ghost"
-        >
-          <Trash2 />
-        </Button>
-      )}
-    </div>
-  )
-}
-
-function EnvVarRow({
-  varKey,
-  info,
-  edits,
-  revealed,
-  saving,
-  setEdits,
-  onSave,
-  onClear,
-  onReveal,
-  compact = false
-}: EnvRowProps) {
-  const isEditing = edits[varKey] !== undefined
-  const isRevealed = revealed[varKey] !== undefined
-  const value = isRevealed ? revealed[varKey] : info.redacted_value
-  const startEdit = () => setEdits(c => ({ ...c, [varKey]: '' }))
-
-  if (compact && !isEditing) {
-    return (
-      <div className="flex items-center justify-between gap-3 py-1.5">
-        <div className="min-w-0">
-          <div className="truncate font-mono text-[0.72rem] text-muted-foreground">{varKey}</div>
-          <div className="truncate text-[0.68rem] text-muted-foreground/70">{info.description}</div>
-        </div>
-        <EnvActions
-          info={info}
-          isRevealed={isRevealed}
-          onClear={onClear}
-          onEdit={startEdit}
-          onReveal={onReveal}
-          saving={saving}
-          showReveal={false}
-          varKey={varKey}
-        />
-      </div>
-    )
-  }
-
-  return (
-    <div className="grid gap-2 rounded-xl bg-background/55 p-3">
-      <div className="flex flex-wrap items-start justify-between gap-3">
-        <div className="min-w-0">
-          <div className="flex flex-wrap items-center gap-2">
-            <span className="font-mono text-xs font-medium">{varKey}</span>
-            <Pill tone={info.is_set ? 'primary' : 'muted'}>
-              {info.is_set && <Check className="size-3" />}
-              {info.is_set ? 'Set' : 'Not set'}
-            </Pill>
-          </div>
-          <p className="mt-1 text-xs leading-5 text-muted-foreground">{info.description}</p>
-        </div>
-        <EnvActions
-          info={info}
-          isRevealed={isRevealed}
-          onClear={onClear}
-          onEdit={startEdit}
-          onReveal={onReveal}
-          saving={saving}
-          varKey={varKey}
-        />
-      </div>
-
-      {!isEditing && info.is_set && (
-        <div
-          className={cn(
-            'rounded-md px-3 py-2 font-mono text-xs',
-            isRevealed ? 'bg-background text-foreground' : 'bg-muted/30 text-muted-foreground'
-          )}
-        >
-          {value || '---'}
-        </div>
-      )}
-
-      {isEditing && (
-        <div className="flex flex-wrap items-center gap-2">
-          <Input
-            autoFocus
-            className={cn('min-w-56 flex-1 font-mono', CONTROL_TEXT)}
-            onChange={e => setEdits(c => ({ ...c, [varKey]: e.target.value }))}
-            placeholder={info.is_set ? 'Replace current value' : 'Enter value'}
-            type={info.is_password ? 'password' : 'text'}
-            value={edits[varKey]}
-          />
-          <Button disabled={saving === varKey || !edits[varKey]} onClick={() => onSave(varKey)} size="sm">
-            <Save />
-            {saving === varKey ? 'Saving' : 'Save'}
-          </Button>
-          <Button onClick={() => setEdits(c => withoutKey(c, varKey))} size="sm" variant="outline">
-            <Codicon name="close" />
-            Cancel
-          </Button>
-        </div>
-      )}
-    </div>
-  )
-}
-
-function EnvProviderGroup({
-  group,
-  rowProps
-}: {
-  group: ProviderGroup
-  rowProps: Omit<EnvRowProps, 'varKey' | 'info'>
-}) {
-  const setCount = group.entries.filter(([, info]) => info.is_set).length
-  // Default-expand providers that already have at least one key set; the
-  // user is much more likely to be coming back to edit those than to start
-  // configuring a fresh provider from scratch.
-  const [expanded, setExpanded] = useState(setCount > 0)
-
-  return (
-    <div className="overflow-hidden rounded-xl bg-background/60">
-      <button
-        className="flex w-full items-center justify-between gap-3 bg-transparent px-3 py-2.5 text-left hover:bg-accent/50"
-        onClick={() => setExpanded(e => !e)}
-        type="button"
-      >
-        <span className="flex min-w-0 items-center gap-2">
-          <Zap className="size-4 shrink-0 text-muted-foreground" />
-          <span className="truncate text-sm font-medium">
-            {group.name === 'Other' ? 'Other providers' : group.name}
-          </span>
-          {setCount > 0 && <Pill tone="primary">{setCount} set</Pill>}
-        </span>
-        <span className="text-xs text-muted-foreground">{group.entries.length} keys</span>
-      </button>
-      {expanded && (
-        <div className="grid gap-2 bg-muted/20 p-3">
-          {group.entries.map(([key, info]) => (
-            <EnvVarRow compact={!info.is_set} info={info} key={key} varKey={key} {...rowProps} />
-          ))}
-        </div>
-      )}
-    </div>
-  )
-}
-
-export function KeysSettings({ query }: SearchProps) {
-  const [vars, setVars] = useState<Record<string, EnvVarInfo> | null>(null)
-  const [edits, setEdits] = useState<Record<string, string>>({})
-  const [revealed, setRevealed] = useState<Record<string, string>>({})
-  const [saving, setSaving] = useState<string | null>(null)
-
-  // We used to hide ~80% of rows behind a global "Show advanced" toggle, but
-  // everything in this view is configuration-level — "advanced" was a poor
-  // distinction. The full list is rendered now and provider groups
-  // default-collapsed-unless-set keep the surface manageable.
-  useEffect(() => {
-    try {
-      window.localStorage.removeItem('desktop.settings.keys.show_advanced')
-    } catch {
-      // Ignore — old key cleanup is best-effort.
-    }
-  }, [])
+export function KeysSettings({ view }: KeysSettingsProps) {
+  const { rowProps, vars } = useEnvCredentials()
+  const [openKey, setOpenKey] = useState<null | string>(null)
 
   useEffect(() => {
-    let cancelled = false
+    setOpenKey(null)
+  }, [view])
 
-    void (async () => {
-      try {
-        const next = await getEnvVars()
-
-        if (!cancelled) {
-          setVars(next)
-        }
-      } catch (err) {
-        notifyError(err, 'API keys failed to load')
-      }
-    })()
-
-    return () => void (cancelled = true)
-  }, [])
-
-  const filterEnv = useCallback((info: EnvVarInfo, key: string, q: string, cat: string, extra?: string) => {
-    if (asText(info.category) !== cat) {
-      return false
-    }
-
-    if (!q) {
-      return true
-    }
-
-    return (
-      key.toLowerCase().includes(q) ||
-      includesQuery(info.description, q) ||
-      Boolean(extra && extra.toLowerCase().includes(q))
-    )
-  }, [])
-
-  const providerGroups = useMemo<ProviderGroup[]>(() => {
+  const groups = useMemo(() => {
     if (!vars) {
       return []
     }
 
-    const q = query.trim().toLowerCase()
+    return KEYS_VIEWS.flatMap(v => {
+      const cats = VIEW_CATEGORIES[v]
 
-    const entries = Object.entries(vars).filter(([key, info]) =>
-      filterEnv(info, key, q, 'provider', providerGroup(key))
-    )
-
-    const groups = new Map<string, [string, EnvVarInfo][]>()
-
-    for (const entry of entries) {
-      const name = providerGroup(entry[0])
-      groups.set(name, [...(groups.get(name) ?? []), entry])
-    }
-
-    return Array.from(groups, ([name, entries]) => ({
-      name,
-      priority: providerPriority(name),
-      entries: entries.sort(([a], [b]) => a.localeCompare(b)),
-      hasAnySet: entries.some(([, info]) => info.is_set)
-    })).sort((a, b) => a.priority - b.priority || a.name.localeCompare(b.name))
-  }, [filterEnv, query, vars])
-
-  const otherGroups = useMemo(() => {
-    if (!vars) {
-      return []
-    }
-
-    const q = query.trim().toLowerCase()
-
-    const labels: Record<string, string> = {
-      tool: 'Tools',
-      messaging: 'Messaging',
-      setting: 'Settings'
-    }
-
-    return ['tool', 'messaging', 'setting'].flatMap(cat => {
       const entries = Object.entries(vars)
-        .filter(([key, info]) => filterEnv(info, key, q, cat))
+        .filter(([, info]) => !info.channel_managed && cats.includes(asText(info.category)))
         .sort(([a], [b]) => a.localeCompare(b))
 
-      return entries.length === 0 ? [] : [{ category: cat, label: labels[cat] ?? prettyName(cat), entries }]
+      return entries.length === 0 ? [] : [{ category: v, entries }]
     })
-  }, [filterEnv, query, vars])
-
-  function patchVar(key: string, patch: EnvPatch) {
-    setVars(c => (c ? { ...c, [key]: { ...c[key], ...patch } } : c))
-  }
-
-  function clearLocalState(key: string) {
-    setEdits(c => withoutKey(c, key))
-    setRevealed(c => withoutKey(c, key))
-  }
-
-  async function handleSave(key: string) {
-    const value = edits[key]
-
-    if (!value) {
-      return
-    }
-
-    setSaving(key)
-
-    try {
-      await setEnvVar(key, value)
-      patchVar(key, { is_set: true, redacted_value: redactedValue(value) })
-      clearLocalState(key)
-      notify({ kind: 'success', title: 'Credential saved', message: `${key} updated.` })
-    } catch (err) {
-      notifyError(err, `Failed to save ${key}`)
-    } finally {
-      setSaving(null)
-    }
-  }
-
-  async function handleClear(key: string) {
-    if (!window.confirm(`Remove ${key} from .env?`)) {
-      return
-    }
-
-    setSaving(key)
-
-    try {
-      await deleteEnvVar(key)
-      patchVar(key, { is_set: false, redacted_value: null })
-      clearLocalState(key)
-      notify({ kind: 'success', title: 'Credential removed', message: `${key} removed.` })
-    } catch (err) {
-      notifyError(err, `Failed to remove ${key}`)
-    } finally {
-      setSaving(null)
-    }
-  }
-
-  async function handleReveal(key: string) {
-    if (revealed[key]) {
-      setRevealed(c => withoutKey(c, key))
-
-      return
-    }
-
-    try {
-      const result = await revealEnvVar(key)
-      setRevealed(c => ({ ...c, [key]: result.value }))
-    } catch (err) {
-      notifyError(err, `Failed to reveal ${key}`)
-    }
-  }
+  }, [vars])
 
   if (!vars) {
     return <LoadingState label="Loading API keys and credentials..." />
   }
 
-  const rowProps = {
-    edits,
-    revealed,
-    saving,
-    setEdits,
-    onSave: handleSave,
-    onClear: handleClear,
-    onReveal: handleReveal
-  }
-
-  const configuredCount = providerGroups.filter(g => g.hasAnySet).length
+  const visible = groups.filter(g => g.category === view)
 
   return (
     <SettingsContent>
-      <div className="mb-6">
-        <SectionHeading
-          icon={Zap}
-          meta={`${configuredCount} of ${providerGroups.length} configured`}
-          title="LLM providers"
-        />
-        <div className="grid gap-2">
-          {providerGroups.map(group => (
-            <EnvProviderGroup group={group} key={group.name} rowProps={rowProps} />
-          ))}
-        </div>
-      </div>
+      {visible.map(group => (
+        <div className="grid gap-2" key={group.category}>
+          {group.entries.map(([key, info]: [string, EnvVarInfo]) => {
+            const label = credentialRowLabel(key, info)
 
-      {otherGroups.map(group => (
-        <div className="mb-6" key={group.category}>
-          <SectionHeading
-            icon={Settings2}
-            meta={`${group.entries.filter(([, i]) => i.is_set).length} of ${group.entries.length} set`}
-            title={group.label}
-          />
-          <div className="grid gap-2">
-            {group.entries.map(([key, info]) => (
-              <EnvVarRow info={info} key={key} varKey={key} {...rowProps} />
-            ))}
-          </div>
+            return (
+              <CredentialKeyCard
+                expanded={openKey === key}
+                info={info}
+                key={key}
+                label={label}
+                onExpand={() => setOpenKey(key)}
+                onToggle={() => setOpenKey(prev => (prev === key ? null : key))}
+                placeholder={credentialPlaceholder(key, info, label)}
+                rowProps={rowProps}
+                varKey={key}
+              />
+            )
+          })}
         </div>
       ))}
+
+      {visible.length === 0 && (
+        <div className="rounded-lg border border-dashed border-(--ui-stroke-tertiary) px-4 py-8 text-center text-[length:var(--conversation-caption-font-size)] text-muted-foreground">
+          Nothing configured in this category yet.
+        </div>
+      )}
     </SettingsContent>
   )
 }
+
+interface KeysSettingsProps {
+  view: KeysView
+}

apps/desktop/src/app/settings/mcp-settings.tsx

@@ -1,20 +1,20 @@
 import { useStore } from '@nanostores/react'
 import { useEffect, useMemo, useState } from 'react'
 
-import { OverlayActionButton, OverlayCard } from '@/app/overlays/overlay-chrome'
+import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Textarea } from '@/components/ui/textarea'
 import { getHermesConfigRecord, type HermesGateway, saveHermesConfig } from '@/hermes'
-import { Package, Wrench } from '@/lib/icons'
+import { Wrench } from '@/lib/icons'
+import { cn } from '@/lib/utils'
 import { notify, notifyError } from '@/store/notifications'
 import { $activeSessionId } from '@/store/session'
 import type { HermesConfigRecord } from '@/types/hermes'
 
-import { includesQuery } from './helpers'
-import { EmptyState, LoadingState, Pill, SectionHeading, SettingsContent } from './primitives'
-import type { SearchProps } from './types'
+import { EmptyState, LoadingState, Pill, SettingsContent } from './primitives'
+import { useDeepLinkHighlight } from './use-deep-link-highlight'
 
-interface McpSettingsProps extends SearchProps {
+interface McpSettingsProps {
   gateway?: HermesGateway | null
   onConfigSaved?: () => void
 }
@@ -42,15 +42,7 @@ const transportLabel = (server: Record<string, unknown>) =>
         ? 'stdio'
         : 'custom'
 
-function serverMatches(name: string, server: Record<string, unknown>, query: string) {
-  if (!query) {
-    return true
-  }
-
-  return includesQuery(name, query) || includesQuery(JSON.stringify(server), query)
-}
-
-export function McpSettings({ gateway, onConfigSaved, query }: McpSettingsProps) {
+export function McpSettings({ gateway, onConfigSaved }: McpSettingsProps) {
   const activeSessionId = useStore($activeSessionId)
   const [config, setConfig] = useState<HermesConfigRecord | null>(null)
   const [selected, setSelected] = useState<string | null>(null)
@@ -80,10 +72,13 @@ export function McpSettings({ gateway, onConfigSaved, query }: McpSettingsProps)
   const servers = useMemo(() => getServers(config), [config])
   const names = useMemo(() => Object.keys(servers).sort(), [servers])
 
-  const filtered = useMemo(
-    () => names.filter(serverName => serverMatches(serverName, servers[serverName], query.trim().toLowerCase())),
-    [names, query, servers]
-  )
+  useDeepLinkHighlight({
+    block: 'nearest',
+    elementId: serverName => `mcp-server-${serverName}`,
+    onResolve: setSelected,
+    param: 'server',
+    ready: serverName => Boolean(config) && serverName in servers
+  })
 
   useEffect(() => {
     const server = selected ? servers[selected] : null
@@ -188,31 +183,32 @@ export function McpSettings({ gateway, onConfigSaved, query }: McpSettingsProps)
 
   return (
     <SettingsContent>
-      <div className="mb-4 flex items-center justify-between gap-3">
-        <SectionHeading icon={Package} meta={`${names.length} configured`} title="MCP servers" />
-        <div className="flex items-center gap-2">
-          <OverlayActionButton onClick={() => setSelected(null)}>New server</OverlayActionButton>
-          <OverlayActionButton disabled={reloading} onClick={() => void reloadMcp()}>
-            {reloading ? 'Reloading...' : 'Reload MCP'}
-          </OverlayActionButton>
-        </div>
+      <div className="mb-4 flex items-center justify-end gap-4">
+        <Button onClick={() => setSelected(null)} size="xs" variant="text">
+          New server
+        </Button>
+        <Button disabled={reloading} onClick={() => void reloadMcp()} size="xs" variant="text">
+          {reloading ? 'Reloading...' : 'Reload MCP'}
+        </Button>
       </div>
 
-      <div className="grid min-h-0 gap-4 lg:grid-cols-[17rem_minmax(0,1fr)]">
-        <OverlayCard className="min-h-64 overflow-hidden p-2">
-          {filtered.length === 0 ? (
+      <div className="grid min-h-0 gap-6 lg:grid-cols-[16rem_minmax(0,1fr)]">
+        <div className="min-h-64">
+          {names.length === 0 ? (
             <EmptyState description="Add a stdio or HTTP server to expose MCP tools." title="No MCP servers" />
           ) : (
-            <div className="grid gap-1">
-              {filtered.map(serverName => {
+            <div className="grid gap-0.5">
+              {names.map(serverName => {
                 const server = servers[serverName]
                 const active = selected === serverName
 
                 return (
                   <button
-                    className={`rounded-md px-2 py-2 text-left transition-colors hover:bg-(--chrome-action-hover) ${
-                      active ? 'bg-accent/45 text-foreground' : 'text-muted-foreground'
-                    }`}
+                    className={cn(
+                      'scroll-mt-2 rounded-md px-2 py-2 text-left transition-colors hover:bg-(--chrome-action-hover)',
+                      active ? 'bg-(--ui-bg-tertiary) text-foreground' : 'text-muted-foreground'
+                    )}
+                    id={`mcp-server-${serverName}`}
                     key={serverName}
                     onClick={() => setSelected(serverName)}
                     type="button"
@@ -227,9 +223,9 @@ export function McpSettings({ gateway, onConfigSaved, query }: McpSettingsProps)
               })}
             </div>
           )}
-        </OverlayCard>
+        </div>
 
-        <OverlayCard className="grid gap-3 p-4">
+        <div className="grid content-start gap-3">
           <div className="flex items-center gap-2 text-sm font-medium">
             <Wrench className="size-4 text-muted-foreground" />
             {selected ? 'Edit server' : 'New server'}
@@ -249,17 +245,23 @@ export function McpSettings({ gateway, onConfigSaved, query }: McpSettingsProps)
           </label>
           <div className="flex items-center justify-between">
             {selected ? (
-              <OverlayActionButton disabled={saving} onClick={() => void removeServer(selected)} tone="danger">
+              <Button
+                className="text-destructive hover:text-destructive"
+                disabled={saving}
+                onClick={() => void removeServer(selected)}
+                size="xs"
+                variant="text"
+              >
                 Remove
-              </OverlayActionButton>
+              </Button>
             ) : (
               <span />
             )}
-            <OverlayActionButton disabled={saving} onClick={() => void saveServer()}>
+            <Button disabled={saving} onClick={() => void saveServer()} size="sm">
               {saving ? 'Saving...' : 'Save server'}
-            </OverlayActionButton>
+            </Button>
           </div>
-        </OverlayCard>
+        </div>
       </div>
     </SettingsContent>
   )