chore(desktop): drop find-git-repositories native dep

The pure-fs git-repo scan replaces the native crawler, so anyone pulling main
gets discovery with no electron-rebuild.

.gitignore

@@ -5,6 +5,7 @@
 *.pyc*
 __pycache__/
 .venv/
+.venv
 .vscode/
 .env
 .env.local

Dockerfile

@@ -9,8 +9,11 @@ FROM ghcr.io/astral-sh/uv:0.11.6-python3.13-trixie@sha256:b3c543b6c4f23a5f2df228
 FROM node:22-bookworm-slim@sha256:7af03b14a13c8cdd38e45058fd957bf00a72bbe17feac43b1c15a689c029c732 AS node_source
 FROM debian:13.4
 
-# Disable Python stdout buffering to ensure logs are printed immediately
+# Disable Python stdout buffering to ensure logs are printed immediately.
+# Do not write .pyc files at runtime: /opt/hermes is immutable in the
+# published container and writable state belongs under /opt/data.
 ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
 
 # Store Playwright browsers outside the volume mount so the build-time
 # install survives the /opt/data volume overlay at runtime.
@@ -186,36 +189,38 @@ RUN cd web && npm run build && \
 
 # ---------- Source code ----------
 # .dockerignore excludes node_modules, so the installs above survive.
-COPY --chown=hermes:hermes . .
+COPY . .
 
 # ---------- Permissions ----------
-# Make install dir world-readable so any HERMES_UID can read it at runtime.
-# The venv needs to be traversable too.
-# node_modules trees additionally need to be writable by the hermes user
-# so the runtime `npm install` triggered by _tui_need_npm_install() in
-# hermes_cli/main.py succeeds (see #18800). /opt/hermes/web is build-time
-# only (HERMES_WEB_DIST points at hermes_cli/web_dist) and is intentionally
-# not chowned here.
-# /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.
+# Link hermes-agent itself (editable). Deps are already installed in the
+# cached layer above; `--no-deps` makes this a fast egg-link creation with no
+# resolution or downloads.
+RUN uv pip install --no-cache-dir --no-deps -e "."
+
+# Keep /opt/hermes immutable for the runtime hermes user. Hosted/container
+# instances must not be able to self-edit the installed source or venv; user
+# data, skills, plugins, config, logs, and dashboard uploads live under
+# /opt/data instead. Root can still repair the image during build/boot, but
+# supervised Hermes processes drop to the non-root hermes user.
 USER root
-RUN chmod -R a+rX /opt/hermes && \
-    chown -R hermes:hermes /opt/hermes/.venv /opt/hermes/ui-tui /opt/hermes/gateway /opt/hermes/node_modules
+RUN mkdir -p /opt/hermes/bin && \
+    cp /opt/hermes/docker/hermes-exec-shim.sh /opt/hermes/bin/hermes && \
+    chmod 0755 /opt/hermes/bin/hermes && \
+    printf 'docker\n' > /opt/hermes/.install_method && \
+    chown -R root:root /opt/hermes && \
+    chmod -R a+rX /opt/hermes && \
+    chmod -R a-w /opt/hermes
+# The ``.install_method`` stamp is baked next to the running code (the install
+# tree), NOT into $HERMES_HOME. $HERMES_HOME (/opt/data) is a shared data
+# volume that is commonly bind-mounted from the host and even shared with a
+# host-side Desktop/CLI install; stamping it at boot used to clobber that
+# host install's marker and wrongly block its ``hermes update``. A code-scoped
+# stamp is read first by detect_install_method() and is immune to the share.
 # 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
 # run as the default hermes user (UID 10000).
 
-# ---------- Link hermes-agent itself (editable) ----------
-# Deps are already installed in the cached layer above; `--no-deps` makes
-# this a fast (~1s) egg-link creation with no resolution or downloads.
-RUN uv pip install --no-cache-dir --no-deps -e "."
-
 # ---------- Bake build-time git revision ----------
 # .dockerignore excludes .git, so `git rev-parse HEAD` from inside the
 # container always returns nothing — meaning `hermes dump` reports
@@ -235,8 +240,9 @@ RUN uv pip install --no-cache-dir --no-deps -e "."
 # every published image has it.
 ARG HERMES_GIT_SHA=
 RUN if [ -n "${HERMES_GIT_SHA}" ]; then \
+        chmod u+w /opt/hermes && \
         printf '%s\n' "${HERMES_GIT_SHA}" > /opt/hermes/.hermes_build_sha && \
-        chown hermes:hermes /opt/hermes/.hermes_build_sha; \
+        chmod a-w /opt/hermes /opt/hermes/.hermes_build_sha; \
     fi
 
 # ---------- s6-overlay service wiring ----------
@@ -282,6 +288,8 @@ ENV HERMES_WEB_DIST=/opt/hermes/hermes_cli/web_dist
 # check. (A separate launcher hardening is tracked independently.)
 ENV HERMES_TUI_DIR=/opt/hermes/ui-tui
 ENV HERMES_HOME=/opt/data
+ENV HERMES_WRITE_SAFE_ROOT=/opt/data
+ENV HERMES_DISABLE_LAZY_INSTALLS=1
 
 # `docker exec` privilege-drop shim. When operators run
 # `docker exec <c> hermes ...` they default to root, and any file the
@@ -294,7 +302,6 @@ ENV HERMES_HOME=/opt/data
 # Recursion is impossible because the shim exec's the venv binary by
 # absolute path (/opt/hermes/.venv/bin/hermes). See the shim source for
 # the opt-out env var (HERMES_DOCKER_EXEC_AS_ROOT=1).
-COPY --chmod=0755 docker/hermes-exec-shim.sh /opt/hermes/bin/hermes
 
 # Pre-s6 entrypoint.sh did `source .venv/bin/activate` which exported
 # the venv bin onto PATH; Architecture B's main-wrapper.sh does the

agent/agent_init.py

@@ -27,7 +27,7 @@ import threading
 import time
 import uuid
 from datetime import datetime
-from typing import Any, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional
 from urllib.parse import urlparse, parse_qs, urlunparse
 
 from agent.context_compressor import ContextCompressor
@@ -195,6 +195,7 @@ def init_agent(
     status_callback: callable = None,
     notice_callback: callable = None,
     notice_clear_callback: callable = None,
+    event_callback: Optional[Callable[[str, dict], None]] = None,
     max_tokens: int = None,
     reasoning_config: Dict[str, Any] = None,
     service_tier: str = None,
@@ -426,6 +427,7 @@ def init_agent(
     agent.status_callback = status_callback
     agent.notice_callback = notice_callback
     agent.notice_clear_callback = notice_clear_callback
+    agent.event_callback = event_callback
     agent.tool_gen_callback = tool_gen_callback
 
     
@@ -597,6 +599,7 @@ def init_agent(
     # (e.g. CLI voice mode adds a temporary prefix for the live call only).
     agent._persist_user_message_idx = None
     agent._persist_user_message_override = None
+    agent._persist_user_message_timestamp = None
 
     # Cache anthropic image-to-text fallbacks per image payload/URL so a
     # single tool loop does not repeatedly re-run auxiliary vision on the
@@ -1153,6 +1156,9 @@ def init_agent(
                         "hermes_home": str(get_hermes_home()),
                         "agent_context": "primary",
                     }
+                    if _init_kwargs["platform"] == "cli":
+                        _init_kwargs["warning_callback"] = agent._emit_warning
+                        _init_kwargs["status_callback"] = agent._emit_status
                     # Thread session title for memory provider scoping
                     # (e.g. honcho uses this to derive chat-scoped session keys)
                     if agent._session_db:
@@ -1221,12 +1227,35 @@ def init_agent(
     # targets.
     agent._task_completion_guidance = bool(_agent_section.get("task_completion_guidance", True))
 
+    # Universal parallel-tool-call guidance toggle.  Default True.  Separate
+    # flag from task_completion_guidance because a user may want one but not
+    # the other.  Steers the model to batch independent tool calls into a
+    # single turn; the runtime already executes such batches concurrently.
+    agent._parallel_tool_call_guidance = bool(_agent_section.get("parallel_tool_call_guidance", True))
+
     # Local Python toolchain probe toggle.  Default True.  When False,
     # the probe is skipped entirely (no subprocess calls, no system-prompt
     # line).  Useful for users on exotic setups where the probe heuristics
     # are noisy.
     agent._environment_probe = bool(_agent_section.get("environment_probe", True))
 
+    # Per-platform prompt-hint overrides (config.yaml → platform_hints).
+    # Lets an enterprise admin append to or replace Hermes' built-in
+    # platform hint for a single messaging platform (e.g. WhatsApp) without
+    # affecting other platforms. Shape:
+    #   platform_hints:
+    #     whatsapp:
+    #       append: "When tabular output would help, invoke the ... skill."
+    #     slack:
+    #       replace: "Custom Slack hint that fully replaces the default."
+    # Stored verbatim; resolution happens in agent/system_prompt.py against
+    # the active platform. Invalid shapes are ignored defensively so a bad
+    # config entry can never break prompt assembly.
+    _platform_hints_cfg = _agent_cfg.get("platform_hints", {})
+    if not isinstance(_platform_hints_cfg, dict):
+        _platform_hints_cfg = {}
+    agent._platform_hint_overrides = _platform_hints_cfg
+
     # App-level API retry count (wraps each model API call).  Default 3,
     # overridable via agent.api_max_retries in config.yaml.  See #11616.
     try:

agent/agent_runtime_helpers.py

@@ -1839,28 +1839,42 @@ def invoke_tool(agent, function_name: str, function_args: dict, effective_task_i
     elif function_name == "memory":
         def _execute(next_args: dict) -> Any:
             target = next_args.get("target", "memory")
+            operations = next_args.get("operations")
             from tools.memory_tool import memory_tool as _memory_tool
             result = _memory_tool(
                 action=next_args.get("action"),
                 target=target,
                 content=next_args.get("content"),
                 old_text=next_args.get("old_text"),
+                operations=operations,
                 store=agent._memory_store,
             )
-            # Bridge: notify external memory provider of built-in memory writes
-            if agent._memory_manager and next_args.get("action") in {"add", "replace"}:
-                try:
-                    agent._memory_manager.on_memory_write(
-                        next_args.get("action", ""),
-                        target,
-                        next_args.get("content", ""),
-                        metadata=agent._build_memory_write_metadata(
-                            task_id=effective_task_id,
-                            tool_call_id=tool_call_id,
-                        ),
+            # Bridge: notify external memory provider of built-in memory writes.
+            # Covers both the single-op shape and each add/replace inside a batch.
+            if agent._memory_manager:
+                if operations:
+                    _mem_ops = [
+                        op for op in operations
+                        if isinstance(op, dict) and op.get("action") in {"add", "replace"}
+                    ]
+                else:
+                    _mem_ops = (
+                        [{"action": next_args.get("action"), "content": next_args.get("content")}]
+                        if next_args.get("action") in {"add", "replace"} else []
                     )
-                except Exception:
-                    pass
+                for _op in _mem_ops:
+                    try:
+                        agent._memory_manager.on_memory_write(
+                            _op.get("action", ""),
+                            target,
+                            _op.get("content", "") or "",
+                            metadata=agent._build_memory_write_metadata(
+                                task_id=effective_task_id,
+                                tool_call_id=tool_call_id,
+                            ),
+                        )
+                    except Exception:
+                        pass
             return _finish_agent_tool(result, next_args)
     elif agent._memory_manager and agent._memory_manager.has_tool(function_name):
         def _execute(next_args: dict) -> Any:

agent/anthropic_adapter.py

@@ -372,7 +372,7 @@ def _detect_claude_code_version() -> str:
 
 
 _CLAUDE_CODE_SYSTEM_PREFIX = "You are Claude Code, Anthropic's official CLI for Claude."
-_MCP_TOOL_PREFIX = "mcp_"
+_MCP_TOOL_PREFIX = "mcp__"
 
 
 def _get_claude_code_version() -> str:
@@ -2349,25 +2349,46 @@ def build_anthropic_kwargs(
                 text = text.replace("Nous Research", "Anthropic")
                 block["text"] = text
 
-        # 3. Prefix tool names with mcp_ (Claude Code convention)
-        #    Skip names that already begin with the marker — native MCP server
-        #    tools (from mcp_servers: in config.yaml) are registered under their
-        #    full mcp_<server>_<tool> name and would double-prefix otherwise,
-        #    breaking round-trip registry lookup in normalize_response. GH-25255.
+        # 3. Normalize tool names so NOTHING goes on the OAuth wire with a
+        #    single-underscore ``mcp_`` prefix.  Anthropic's subscription/OAuth
+        #    billing classifier treats a single-underscore ``mcp_`` tool name as
+        #    a third-party-app fingerprint and rejects the request with HTTP 400
+        #    "Third-party apps now draw from extra usage, not plan limits"
+        #    (verified empirically: a single ``mcp_foo`` tool flips a request
+        #    from plan-billing to the extra-usage lane; ``mcp__foo`` is accepted).
+        #
+        #    Two cases, both must land on the double-underscore ``mcp__`` form:
+        #      a) bare Hermes-native tools (``read_file``)  -> ``mcp__read_file``
+        #      b) native MCP server tools registered under their full
+        #         single-underscore ``mcp_<server>_<tool>`` name
+        #         (``mcp_linear_get_issue``) -> ``mcp__linear_get_issue``
+        #    Case (b) is the gap that the bare ``mcp_``->``mcp__`` constant swap
+        #    left open: those tools were *skipped* and stayed single-underscore,
+        #    so any session with an MCP server configured still tripped the
+        #    classifier. normalize_response reverses both forms via registry
+        #    lookup so the dispatcher still sees the original name. GH-25255.
+        def _to_oauth_wire_name(name: str) -> str:
+            if name.startswith("mcp__"):
+                return name  # already correct, don't double-prefix
+            if name.startswith("mcp_"):
+                # single-underscore native MCP tool -> promote to double
+                return "mcp__" + name[len("mcp_"):]
+            return _MCP_TOOL_PREFIX + name  # bare name -> mcp__<name>
+
         if anthropic_tools:
             for tool in anthropic_tools:
-                if "name" in tool and not tool["name"].startswith(_MCP_TOOL_PREFIX):
-                    tool["name"] = _MCP_TOOL_PREFIX + tool["name"]
+                if "name" in tool:
+                    tool["name"] = _to_oauth_wire_name(tool["name"])
 
-        # 4. Prefix tool names in message history (tool_use and tool_result blocks)
+        # 4. Apply the same normalization to tool names in message history
+        #    (tool_use blocks) so replayed turns match the wire names above.
         for msg in anthropic_messages:
             content = msg.get("content")
             if isinstance(content, list):
                 for block in content:
                     if isinstance(block, dict):
                         if block.get("type") == "tool_use" and "name" in block:
-                            if not block["name"].startswith(_MCP_TOOL_PREFIX):
-                                block["name"] = _MCP_TOOL_PREFIX + block["name"]
+                            block["name"] = _to_oauth_wire_name(block["name"])
                         elif block.get("type") == "tool_result" and "tool_use_id" in block:
                             pass  # tool_result uses ID, not name
 

agent/background_review.py

@@ -300,6 +300,7 @@ def summarize_background_review_actions(
                     "target": args.get("target", "memory"),
                     "content": args.get("content", ""),
                     "old_text": args.get("old_text", ""),
+                    "operations": args.get("operations") or [],
                     "name": args.get("name", ""),
                     "old_string": args.get("old_string", ""),
                     "new_string": args.get("new_string", ""),
@@ -353,6 +354,7 @@ def summarize_background_review_actions(
             content = detail.get("content", "")
             old_text = detail.get("old_text", "")
             skill_name = detail.get("name", "")
+            operations = detail.get("operations") or []
             max_preview = 120
             if is_skill:
                 change = data.get("_change", {})
@@ -376,6 +378,21 @@ def summarize_background_review_actions(
                     actions.append(f"📝 Skill '{skill_name}' rewritten: {description}")
                 else:
                     actions.append(f"📝 {message}" if message else f"Skill {action}")
+            elif operations:
+                for op in operations:
+                    op = op or {}
+                    op_act = op.get("action", "")
+                    op_content = (op.get("content") or "")
+                    op_old = (op.get("old_text") or "")
+                    if op_act == "add" and op_content:
+                        preview = op_content[:max_preview] + ("…" if len(op_content) > max_preview else "")
+                        actions.append(f"{label} ➕ {preview}")
+                    elif op_act == "replace" and op_content:
+                        preview = op_content[:max_preview] + ("…" if len(op_content) > max_preview else "")
+                        actions.append(f"{label} ✏️ {preview}")
+                    elif op_act == "remove" and op_old:
+                        preview = op_old[:60] + ("…" if len(op_old) > 60 else "")
+                        actions.append(f"{label} ➖ {preview}")
             elif action == "add" and content:
                 preview = content[:max_preview] + ("…" if len(content) > max_preview else "")
                 actions.append(f"{label} ➕ {preview}")
@@ -391,6 +408,7 @@ def summarize_background_review_actions(
             "added" in message_lower
             or "replaced" in message_lower
             or "removed" in message_lower
+            or "applied" in message_lower
             or (target and "add" in message.lower())
             or "Entry added" in message
         ):

agent/billing_view.py

@@ -0,0 +1,295 @@
+"""Surface-agnostic core for the Phase 2b terminal-billing screens.
+
+One fetch/parse per concern, consumed identically by the CLI handler
+(``cli.py::_show_billing``), the TUI JSON-RPC methods
+(``tui_gateway/server.py``), and any other surface. Mirrors the proven
+``agent/account_usage.py::build_credits_view`` pattern: parse the server payload
+into a frozen dataclass; **fail open** — when not logged in or the portal is
+unreachable, return a struct with ``logged_in=False`` and let the surface degrade
+gracefully (never crash).
+
+Money discipline: the server emits decimal STRINGS (``"142.5"``, not fixed 2dp).
+We keep them as :class:`decimal.Decimal` end-to-end and only format for display.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from dataclasses import dataclass, field
+from decimal import Decimal, InvalidOperation
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Decimal money helpers
+# =============================================================================
+
+
+def parse_money(value: Any) -> Optional[Decimal]:
+    """Parse a server money value (decimal string) into :class:`Decimal`.
+
+    Returns None for missing/invalid input. Never raises. Accepts str/int (and,
+    defensively, float — though the server always sends strings).
+    """
+    if value is None:
+        return None
+    try:
+        # Decimal(str(...)) avoids binary-float artifacts if a float ever sneaks in.
+        return Decimal(str(value).strip())
+    except (InvalidOperation, ValueError, TypeError):
+        return None
+
+
+def format_money(value: Optional[Decimal]) -> str:
+    """Format a Decimal as ``$X`` / ``$X.YY`` for display.
+
+    Whole dollars show no decimals; any fractional amount shows exactly 2dp:
+    ``Decimal("142.5")`` → ``"$142.50"``, ``Decimal("100")`` → ``"$100"``,
+    ``Decimal("0.01")`` → ``"$0.01"``.
+    """
+    if value is None:
+        return "—"
+    if value == value.to_integral_value():
+        # Whole dollars — no decimal point. format(..., "f") avoids 1E+3 for 1000.
+        return f"${format(value.to_integral_value(), 'f')}"
+    # Fractional — always show 2dp.
+    return f"${format(value.quantize(Decimal('0.01')), 'f')}"
+
+
+# =============================================================================
+# Parsed sub-structures
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class CardInfo:
+    brand: str
+    last4: str
+
+    @property
+    def masked(self) -> str:
+        return f"{self.brand} ····{self.last4}"
+
+
+@dataclass(frozen=True)
+class MonthlyCap:
+    limit_usd: Optional[Decimal] = None
+    spent_this_month_usd: Optional[Decimal] = None
+    is_default_ceiling: bool = False
+
+
+@dataclass(frozen=True)
+class AutoReload:
+    enabled: bool = False
+    threshold_usd: Optional[Decimal] = None
+    reload_to_usd: Optional[Decimal] = None
+
+
+@dataclass(frozen=True)
+class BillingState:
+    """Parsed ``GET /api/billing/state`` — the overview screen's data.
+
+    Fail-open: ``logged_in=False`` (and empty fields) when not logged in or the
+    portal is unreachable.
+    """
+
+    logged_in: bool
+    org_id: Optional[str] = None
+    org_slug: Optional[str] = None
+    org_name: Optional[str] = None
+    role: Optional[str] = None  # "OWNER" | "ADMIN" | "MEMBER"
+    balance_usd: Optional[Decimal] = None
+    cli_billing_enabled: bool = False
+    charge_presets: tuple[Decimal, ...] = ()
+    min_usd: Optional[Decimal] = None
+    max_usd: Optional[Decimal] = None
+    card: Optional[CardInfo] = None
+    monthly_cap: Optional[MonthlyCap] = None
+    auto_reload: Optional[AutoReload] = None
+    portal_url: Optional[str] = None
+    # When the fetch failed (vs cleanly not-logged-in), the message for the surface.
+    error: Optional[str] = None
+
+    @property
+    def is_admin(self) -> bool:
+        """True for OWNER/ADMIN — the roles that can manage billing."""
+        return (self.role or "").upper() in ("OWNER", "ADMIN")
+
+    @property
+    def can_charge(self) -> bool:
+        """True when the UI should offer charge/auto-reload actions.
+
+        Admin role AND the per-org kill-switch on. (The server still enforces;
+        this is just for graying out actions the user can't take.)
+        """
+        return self.is_admin and self.cli_billing_enabled
+
+
+def _parse_card(raw: Any) -> Optional[CardInfo]:
+    if not isinstance(raw, dict):
+        return None
+    brand = raw.get("brand")
+    last4 = raw.get("last4")
+    if isinstance(brand, str) and isinstance(last4, str):
+        return CardInfo(brand=brand, last4=last4)
+    return None
+
+
+def _parse_monthly_cap(raw: Any) -> Optional[MonthlyCap]:
+    if not isinstance(raw, dict):
+        return None
+    return MonthlyCap(
+        limit_usd=parse_money(raw.get("limitUsd")),
+        spent_this_month_usd=parse_money(raw.get("spentThisMonthUsd")),
+        is_default_ceiling=bool(raw.get("isDefaultCeiling")),
+    )
+
+
+def _parse_auto_reload(raw: Any) -> Optional[AutoReload]:
+    if not isinstance(raw, dict):
+        return None
+    return AutoReload(
+        enabled=bool(raw.get("enabled")),
+        threshold_usd=parse_money(raw.get("thresholdUsd")),
+        reload_to_usd=parse_money(raw.get("reloadToUsd")),
+    )
+
+
+def billing_state_from_payload(
+    payload: dict[str, Any], *, portal_url: Optional[str] = None
+) -> BillingState:
+    """Map a raw ``/api/billing/state`` JSON dict into :class:`BillingState`."""
+    raw_org = payload.get("org")
+    org: dict[str, Any] = raw_org if isinstance(raw_org, dict) else {}
+    raw_bounds = payload.get("bounds")
+    bounds: dict[str, Any] = raw_bounds if isinstance(raw_bounds, dict) else {}
+
+    presets: list[Decimal] = []
+    for item in payload.get("chargePresets") or ():
+        parsed = parse_money(item)
+        if parsed is not None:
+            presets.append(parsed)
+
+    return BillingState(
+        logged_in=True,
+        org_id=org.get("id"),
+        org_slug=org.get("slug"),
+        org_name=org.get("name"),
+        role=org.get("role"),
+        balance_usd=parse_money(payload.get("balanceUsd")),
+        cli_billing_enabled=bool(payload.get("cliBillingEnabled")),
+        charge_presets=tuple(presets),
+        min_usd=parse_money(bounds.get("minUsd")),
+        max_usd=parse_money(bounds.get("maxUsd")),
+        card=_parse_card(payload.get("card")),
+        monthly_cap=_parse_monthly_cap(payload.get("monthlyCap")),
+        auto_reload=_parse_auto_reload(payload.get("autoReload")),
+        portal_url=portal_url,
+    )
+
+
+# =============================================================================
+# Fail-open builders (the surface front doors)
+# =============================================================================
+
+
+def build_billing_state(*, timeout: float = 15.0) -> BillingState:
+    """Fetch + parse ``/api/billing/state``. Fail-open.
+
+    Returns ``BillingState(logged_in=False)`` when not logged in. On a portal/HTTP
+    failure, returns ``logged_in=False`` with ``error`` set so the surface can show
+    a clear message rather than crashing.
+    """
+    try:
+        from hermes_cli.nous_billing import (
+            BillingAuthError,
+            BillingError,
+            _absolutize_portal_url,
+            get_billing_state,
+            resolve_portal_base_url,
+        )
+    except Exception:
+        return BillingState(logged_in=False, error="billing client unavailable")
+
+    try:
+        payload = get_billing_state(timeout=timeout)
+    except BillingAuthError:
+        return BillingState(logged_in=False)
+    except BillingError as exc:
+        logger.debug("billing ▸ /state fetch failed (fail-open)", exc_info=True)
+        return BillingState(logged_in=False, error=str(exc))
+    except Exception:
+        logger.debug("billing ▸ /state unexpected error (fail-open)", exc_info=True)
+        return BillingState(logged_in=False, error="could not load billing state")
+
+    # Prefer a server-supplied portalUrl if present (resolved to absolute in case
+    # it's relative); else build the standard one.
+    raw_portal = payload.get("portalUrl") if isinstance(payload, dict) else None
+    portal_url = _absolutize_portal_url(raw_portal) if raw_portal else None
+    if not portal_url:
+        try:
+            portal_url = _fallback_portal_url(resolve_portal_base_url())
+        except Exception:
+            portal_url = None
+
+    return billing_state_from_payload(payload, portal_url=portal_url)
+
+
+def _fallback_portal_url(base: str) -> str:
+    """Standard billing deep-link when the server omits ``portalUrl``."""
+    return f"{base.rstrip('/')}/billing?topup=open"
+
+
+# =============================================================================
+# Idempotency
+# =============================================================================
+
+
+def new_idempotency_key() -> str:
+    """Fresh UUID for a user-confirmed purchase (reuse on retry of the SAME buy).
+
+    The ``Idempotency-Key`` header is mandatory on ``POST /charge``; generate one
+    per confirmed purchase and reuse it across retries so a double-submit collapses
+    to a single charge. Never reuse a key across different amounts (the server
+    returns 409 idempotency_conflict).
+    """
+    return str(uuid.uuid4())
+
+
+# =============================================================================
+# Amount validation (Screen 3 custom input)
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class AmountValidation:
+    ok: bool
+    amount: Optional[Decimal] = None
+    error: Optional[str] = None
+
+
+def validate_charge_amount(
+    raw: str, *, min_usd: Optional[Decimal], max_usd: Optional[Decimal]
+) -> AmountValidation:
+    """Validate a custom charge amount against bounds + 2dp (multipleOf 0.01).
+
+    Mirrors the server's accept/reject so the UI can give instant feedback rather
+    than round-tripping a sure-to-fail charge. The server is still authoritative.
+    """
+    cleaned = (raw or "").strip().lstrip("$").strip()
+    amount = parse_money(cleaned)
+    if amount is None:
+        return AmountValidation(ok=False, error="Enter a dollar amount, e.g. 100")
+    if amount <= 0:
+        return AmountValidation(ok=False, error="Amount must be greater than $0")
+    # multipleOf 0.01 — reject sub-cent precision.
+    if amount != amount.quantize(Decimal("0.01")):
+        return AmountValidation(ok=False, error="Amount can't be smaller than a cent")
+    if min_usd is not None and amount < min_usd:
+        return AmountValidation(ok=False, error=f"Minimum is {format_money(min_usd)}")
+    if max_usd is not None and amount > max_usd:
+        return AmountValidation(ok=False, error=f"Maximum is {format_money(max_usd)}")
+    return AmountValidation(ok=True, amount=amount)

agent/codex_responses_adapter.py

@@ -262,6 +262,26 @@ def _responses_tools(tools: Optional[List[Dict[str, Any]]] = None) -> Optional[L
     return converted or None
 
 
+# Provider-executed built-in tool *declaration* types accepted on the
+# Responses ``tools`` array.  These are declared by ``type`` alone (no
+# client-side name/parameters schema) and run server-side — the provider
+# owns the implementation and reports progress via the matching ``*_call``
+# output items.  Hermes injects xAI's native ``web_search`` for the xAI
+# transport (see agent/transports/codex.py); the rest are listed so the
+# preflight validator passes them through rather than rejecting them as
+# "unsupported type".  Mirrors the ``*_call`` item-type set used in
+# _normalize_codex_response.
+_RESPONSES_BUILTIN_TOOL_TYPES = {
+    "web_search",
+    "web_search_preview",
+    "file_search",
+    "code_interpreter",
+    "image_generation",
+    "computer_use_preview",
+    "local_shell",
+}
+
+
 # ---------------------------------------------------------------------------
 # Message format conversion
 # ---------------------------------------------------------------------------
@@ -802,7 +822,22 @@ def _preflight_codex_api_kwargs(
         for idx, tool in enumerate(tools):
             if not isinstance(tool, dict):
                 raise ValueError(f"Codex Responses tools[{idx}] must be an object.")
-            if tool.get("type") != "function":
+
+            tool_type = tool.get("type")
+
+            # Provider-executed built-in tools (xAI native web_search, code
+            # interpreter, etc.) are declared by ``type`` alone and carry no
+            # ``name``/``parameters`` schema — the provider owns the
+            # implementation.  Pass them through verbatim instead of forcing
+            # them through the function-tool validation below (which would
+            # otherwise reject them with "unsupported type").  See
+            # agent/transports/codex.py for where xAI's native web_search is
+            # injected.
+            if tool_type in _RESPONSES_BUILTIN_TOOL_TYPES:
+                normalized_tools.append(dict(tool))
+                continue
+
+            if tool_type != "function":
                 raise ValueError(f"Codex Responses tools[{idx}] has unsupported type {tool.get('type')!r}.")
 
             name = tool.get("name")
@@ -1086,6 +1121,33 @@ def _normalize_codex_response(
     saw_final_answer_phase = False
     saw_reasoning_item = False
 
+    # Server-side built-in tool calls (xAI's native web_search, code
+    # interpreter, etc.) are executed by the provider and reported as
+    # discrete ``*_call`` output items.  xAI's /v1/responses surface
+    # (e.g. grok-composer-2.5-fast on SuperGrok OAuth) routinely leaves
+    # these items at ``status="in_progress"`` even when the overall
+    # ``response.status == "completed"`` — the search ran to completion
+    # server-side, the per-item status simply isn't reconciled.  These
+    # are NOT a signal that the model's turn is unfinished, so they must
+    # not flip ``has_incomplete_items``.  Only the response-level status
+    # and genuine model output items (message/reasoning/function_call)
+    # govern the incomplete verdict.  Without this guard, any turn where
+    # grok-composer invokes server-side search is misclassified as
+    # ``finish_reason="incomplete"`` and burns 3 fruitless continuation
+    # retries before failing with "Codex response remained incomplete
+    # after 3 continuation attempts".  client-side function/custom tool
+    # calls keep their own in_progress handling below (they are skipped,
+    # not awaited).
+    _SERVER_SIDE_TOOL_CALL_TYPES = {
+        "web_search_call",
+        "file_search_call",
+        "code_interpreter_call",
+        "image_generation_call",
+        "computer_call",
+        "local_shell_call",
+        "mcp_call",
+    }
+
     for item in output:
         item_type = getattr(item, "type", None)
         item_status = getattr(item, "status", None)
@@ -1094,7 +1156,10 @@ def _normalize_codex_response(
         else:
             item_status = None
 
-        if item_status in {"queued", "in_progress", "incomplete"}:
+        if (
+            item_status in {"queued", "in_progress", "incomplete"}
+            and item_type not in _SERVER_SIDE_TOOL_CALL_TYPES
+        ):
             has_incomplete_items = True
             saw_streaming_or_item_incomplete = True
 

agent/conversation_compression.py

@@ -512,6 +512,16 @@ def compress_context(
             old_title = agent._session_db.get_session_title(agent.session_id)
             # Trigger memory extraction on the old session before it rotates.
             agent.commit_memory_session(messages)
+            # Flush any un-persisted messages from the current turn to the
+            # old session *before* rotating.  compress_context() can be
+            # called mid-turn (auto-compress when context exceeds threshold)
+            # at a point when _flush_messages_to_session_db() has not yet
+            # run.  Without this, messages generated during the current turn
+            # are silently lost on session rotation (#47202).
+            try:
+                agent._flush_messages_to_session_db(messages)
+            except Exception:
+                pass  # best-effort — don't block compression on a flush error
             agent._session_db.end_session(agent.session_id, "compression")
             old_session_id = agent.session_id
             agent.session_id = f"{datetime.now().strftime('%Y%m%d_%H%M%S')}_{uuid.uuid4().hex[:6]}"
@@ -603,6 +613,20 @@ def compress_context(
             force=True,
         )
 
+    # Emit session:compress event so hooks (e.g. MemPalace sync) can ingest
+    # the completed old session before its details are lost.
+    _old_sid_for_event = locals().get("old_session_id")
+    if getattr(agent, "event_callback", None):
+        try:
+            agent.event_callback("session:compress", {
+                "platform": agent.platform or "",
+                "session_id": agent.session_id,
+                "old_session_id": _old_sid_for_event or "",
+                "compression_count": agent.context_compressor.compression_count,
+            })
+        except Exception as e:
+            logger.debug("event_callback error on session:compress: %s", e)
+
     # Keep the post-compression rough estimate for diagnostics, but do not
     # treat it as provider-reported prompt usage. Schema-heavy rough estimates
     # can remain above threshold even after the next real API request fits.

agent/conversation_loop.py

@@ -300,11 +300,20 @@ def _restore_or_build_system_prompt(agent, system_message, conversation_history)
                 agent.session_id, exc,
             )
 
-    if stored_prompt:
+    if stored_prompt and _stored_prompt_matches_runtime(agent, stored_prompt):
         # Continuing session — reuse the exact system prompt from the
         # previous turn so the Anthropic cache prefix matches.
         agent._cached_system_prompt = stored_prompt
         return
+    if stored_prompt:
+        stored_state = "stale_runtime"
+        logger.info(
+            "Stored system prompt for session %s has stale runtime identity; "
+            "rebuilding for model=%s provider=%s.",
+            agent.session_id,
+            getattr(agent, "model", "") or "",
+            getattr(agent, "provider", "") or "",
+        )
 
     if conversation_history and stored_state in ("null", "empty"):
         # Continuing session whose stored prompt is unusable.  The
@@ -366,6 +375,30 @@ def _restore_or_build_system_prompt(agent, system_message, conversation_history)
             )
 
 
+def _stored_prompt_matches_runtime(agent, prompt: str) -> bool:
+    """Return False when the persisted Model/Provider lines are stale."""
+
+    def line_value(label: str) -> str:
+        prefix = f"{label}:"
+        value = ""
+        for line in prompt.splitlines():
+            if line.startswith(prefix):
+                value = line[len(prefix):].strip()
+        return value
+
+    stored_model = line_value("Model")
+    current_model = str(getattr(agent, "model", "") or "").strip()
+    if stored_model and current_model and stored_model != current_model:
+        return False
+
+    stored_provider = line_value("Provider")
+    current_provider = str(getattr(agent, "provider", "") or "").strip()
+    if stored_provider and current_provider and stored_provider != current_provider:
+        return False
+
+    return True
+
+
 def _get_continuation_prompt(is_partial_stub: bool, dropped_tools: Optional[List[str]] = None) -> str:
     if is_partial_stub and dropped_tools:
         tool_list = ", ".join(dropped_tools[:3])
@@ -441,6 +474,7 @@ def run_conversation(
     task_id: str = None,
     stream_callback: Optional[callable] = None,
     persist_user_message: Optional[str] = None,
+    persist_user_timestamp: Optional[float] = None,
 ) -> Dict[str, Any]:
     """
     Run a complete conversation with tool calling until completion.
@@ -456,6 +490,8 @@ def run_conversation(
         persist_user_message: Optional clean user message to store in
             transcripts/history when user_message contains API-only
             synthetic prefixes.
+        persist_user_timestamp: Optional platform event timestamp to store
+            as metadata on that persisted user message.
                 or queuing follow-up prefetch work.
 
     Returns:
@@ -477,6 +513,7 @@ def run_conversation(
         task_id,
         stream_callback,
         persist_user_message,
+        persist_user_timestamp,
         restore_or_build_system_prompt=_restore_or_build_system_prompt,
         install_safe_stdio=_install_safe_stdio,
         sanitize_surrogates=_sanitize_surrogates,
@@ -3719,8 +3756,30 @@ def run_conversation(
                     assistant_msg = agent._build_assistant_message(assistant_message, finish_reason)
                     messages.append(assistant_msg)
                     for tc in assistant_message.tool_calls:
-                        if tc.function.name not in agent.valid_tool_names:
-                            content = f"Tool '{tc.function.name}' does not exist. Available tools: {available}"
+                        _tc_name = tc.function.name
+                        if _tc_name not in agent.valid_tool_names:
+                            # A blank/whitespace-only name is not a typo the
+                            # model can fuzzy-correct toward a real tool — it is
+                            # almost always a weak open model echoing tool-call
+                            # XML/JSON it saw in file or tool output (#47967:
+                            # <tool_call>/<invoke name=...> payloads in a file
+                            # prime mimo/nemotron-class models to emit empty
+                            # structured calls). Dumping the full tool catalog
+                            # in that case feeds the priming loop more names to
+                            # mimic and inflates context 3-4x across retries, so
+                            # send a terse error that tells the model in-context
+                            # tool-call syntax is DATA, not a call to make.
+                            if not (_tc_name or "").strip():
+                                content = (
+                                    "Tool call rejected: the tool name was empty. "
+                                    "If tool-call XML or JSON appeared in file "
+                                    "contents or tool output, that is data — do "
+                                    "not re-emit it as a tool call. To call a "
+                                    "tool, use a valid name from your tool list; "
+                                    "otherwise reply in plain text."
+                                )
+                            else:
+                                content = f"Tool '{_tc_name}' does not exist. Available tools: {available}"
                         else:
                             content = "Skipped: another tool call in this turn used an invalid name. Please retry this tool call."
                         messages.append({

agent/curator.py

@@ -57,6 +57,11 @@ DEFAULT_INTERVAL_HOURS = 24 * 7  # 7 days
 DEFAULT_MIN_IDLE_HOURS = 2
 DEFAULT_STALE_AFTER_DAYS = 30
 DEFAULT_ARCHIVE_AFTER_DAYS = 90
+# Consolidation (the LLM umbrella-building fork) is OFF by default. The
+# deterministic inactivity prune (apply_automatic_transitions) still runs
+# whenever the curator is enabled; only the opinionated, aux-model-cost
+# consolidation pass is opt-in.
+DEFAULT_CONSOLIDATE = False
 
 
 # ---------------------------------------------------------------------------
@@ -182,6 +187,22 @@ def get_prune_builtins() -> bool:
     return bool(cfg.get("prune_builtins", True))
 
 
+def get_consolidate() -> bool:
+    """Whether the curator runs its LLM consolidation (umbrella-building) pass.
+
+    OFF by default. When off, a curator run does ONLY the deterministic
+    inactivity prune (mark stale / archive long-unused skills) and skips the
+    forked aux-model review entirely — no consolidation, no umbrella-building,
+    no aux-model cost. Set ``curator.consolidate: true`` to opt back into the
+    LLM pass that merges overlapping skills into class-level umbrellas.
+
+    The explicit ``hermes curator run --consolidate`` flag overrides this for
+    a single invocation regardless of the config value.
+    """
+    cfg = _load_config()
+    return bool(cfg.get("consolidate", DEFAULT_CONSOLIDATE))
+
+
 # ---------------------------------------------------------------------------
 # Idle / interval check
 # ---------------------------------------------------------------------------
@@ -1408,25 +1429,38 @@ def run_curator_review(
     on_summary: Optional[Callable[[str], None]] = None,
     synchronous: bool = False,
     dry_run: bool = False,
+    consolidate: Optional[bool] = None,
 ) -> Dict[str, Any]:
     """Execute a single curator review pass.
 
     Steps:
       1. Apply automatic state transitions (pure, no LLM).
-      2. If there are agent-created skills, spawn a forked AIAgent that runs
-         the LLM review prompt against the current candidate list.
+      2. If consolidation is enabled AND there are agent-created skills, spawn
+         a forked AIAgent that runs the LLM review prompt against the current
+         candidate list.
       3. Update .curator_state with last_run_at and a one-line summary.
       4. Invoke *on_summary* with a user-visible description.
 
     If *synchronous* is True, the LLM review runs in the calling thread; the
     default is to spawn a daemon thread so the caller returns immediately.
 
+    *consolidate* gates the LLM umbrella-building pass. ``None`` (the default)
+    reads ``curator.consolidate`` from config (OFF by default). Passing
+    ``True``/``False`` overrides the config for this invocation — used by the
+    ``hermes curator run --consolidate`` flag. When consolidation is off, only
+    the deterministic inactivity prune runs and the forked aux-model review is
+    skipped entirely (no aux-model cost).
+
     If *dry_run* is True, the automatic stale/archive transitions are SKIPPED
     and the LLM review pass is instructed to produce a report only — no
     skill_manage mutations, no terminal archive moves. The REPORT.md still
     gets written and ``state.last_report_path`` still records it so users
-    can read what the curator WOULD have done.
+    can read what the curator WOULD have done. A dry-run also honors
+    *consolidate*: when consolidation is off, the preview only reports the
+    deterministic prune candidates.
     """
+    if consolidate is None:
+        consolidate = get_consolidate()
     start = datetime.now(timezone.utc)
     if dry_run:
         # Count candidates without mutating state.
@@ -1489,6 +1523,53 @@ def run_curator_review(
             before_report = []
         before_names = {r.get("name") for r in before_report if isinstance(r, dict)}
 
+        # Consolidation gate. When off (the default), the curator does ONLY the
+        # deterministic inactivity prune above — no forked aux-model review, no
+        # umbrella-building, no aux-model cost. Record the run, write a report
+        # reflecting the prune-only outcome, and return without spawning a fork.
+        if not consolidate:
+            final_summary = (
+                f"{prefix}{auto_summary}; llm: skipped (consolidation off)"
+            )
+            llm_meta = {
+                "final": "",
+                "summary": "skipped (consolidation off)",
+                "model": "",
+                "provider": "",
+                "tool_calls": [],
+                "error": None,
+            }
+            elapsed = (datetime.now(timezone.utc) - start).total_seconds()
+            state2 = load_state()
+            state2["last_run_duration_seconds"] = elapsed
+            state2["last_run_summary"] = final_summary
+            try:
+                after_report = skill_usage.agent_created_report()
+            except Exception:
+                after_report = []
+            try:
+                report_path = _write_run_report(
+                    started_at=start,
+                    elapsed_seconds=elapsed,
+                    auto_counts=counts,
+                    auto_summary=auto_summary,
+                    before_report=before_report,
+                    before_names=before_names,
+                    after_report=after_report,
+                    llm_meta=llm_meta,
+                )
+                if report_path is not None:
+                    state2["last_report_path"] = str(report_path)
+            except Exception as e:
+                logger.debug("Curator report write failed: %s", e, exc_info=True)
+            save_state(state2)
+            if on_summary:
+                try:
+                    on_summary(f"curator: {final_summary}")
+                except Exception:
+                    pass
+            return
+
         llm_meta: Dict[str, Any] = {}
         try:
             candidate_list = _render_candidate_list()

agent/curator_backup.py

@@ -46,7 +46,7 @@ import shutil
 import tarfile
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Set, Tuple
 
 from hermes_constants import get_hermes_home
 from agent.skill_utils import is_excluded_skill_path
@@ -208,13 +208,17 @@ def _write_manifest(dest: Path, reason: str, archive_path: Path,
     )
 
 
-def snapshot_skills(reason: str = "manual") -> Optional[Path]:
+def snapshot_skills(reason: str = "manual", *, protect_ids: Optional[Set[str]] = None) -> Optional[Path]:
     """Create a tar.gz snapshot of ``~/.hermes/skills/`` and prune old ones.
 
     Returns the snapshot directory path, or ``None`` if the snapshot was
     skipped (backup disabled, skills dir missing, or an IO error occurred —
     in which case we log at debug and return None so the curator never
     aborts a pass because of a backup failure).
+
+    ``protect_ids`` is forwarded to the prune step so callers can guarantee
+    specific snapshot ids survive even when they fall outside the keep
+    window (rollback passes the id it is about to restore from).
     """
     if not is_enabled():
         logger.debug("Curator backup disabled by config; skipping snapshot")
@@ -276,15 +280,19 @@ def snapshot_skills(reason: str = "manual") -> Optional[Path]:
             pass
         return None
 
-    _prune_old(keep=get_keep())
+    _prune_old(keep=get_keep(), protect=protect_ids)
     logger.info("Curator snapshot created: %s (%s)", snap_id, reason)
     return dest
 
 
-def _prune_old(keep: int) -> List[str]:
+def _prune_old(keep: int, protect: Optional[Set[str]] = None) -> List[str]:
     """Delete regular snapshots beyond the newest *keep*. Returns deleted
-    ids. Staging dirs (``.rollback-staging-*``) are implementation detail
-    and pruned independently on every call."""
+    ids. Snapshot ids in *protect* are never deleted even when they fall
+    outside the keep window — rollback() uses this so the mandatory
+    pre-rollback safety snapshot can never evict the very snapshot being
+    restored. Staging dirs (``.rollback-staging-*``) are implementation
+    detail and pruned independently on every call."""
+    protect = protect or set()
     backups = _backups_dir()
     if not backups.exists():
         return []
@@ -305,6 +313,8 @@ def _prune_old(keep: int) -> List[str]:
     entries.sort(key=lambda t: t[0], reverse=True)
     deleted: List[str] = []
     for _, path in entries[keep:]:
+        if path.name in protect:
+            continue
         try:
             shutil.rmtree(path)
             deleted.append(path.name)
@@ -564,7 +574,13 @@ def rollback(backup_id: Optional[str] = None) -> Tuple[bool, str, Optional[Path]
     # out before touching anything — otherwise a failed extract could leave
     # the user with no skills.
     try:
-        snapshot_skills(reason=f"pre-rollback to {target.name}")
+        # Protect the target from this snapshot's prune step: at the steady
+        # keep limit, pruning the oldest snapshot would otherwise delete the
+        # very snapshot we are about to extract from.
+        snapshot_skills(
+            reason=f"pre-rollback to {target.name}",
+            protect_ids={target.name},
+        )
     except Exception as e:
         return (False, f"pre-rollback safety snapshot failed: {e}", None)
 

agent/memory_manager.py

@@ -33,6 +33,7 @@ from concurrent.futures import ThreadPoolExecutor
 from typing import Any, Dict, List, Optional
 
 from agent.memory_provider import MemoryProvider
+from agent.skill_commands import extract_user_instruction_from_skill_message
 from tools.registry import tool_error
 
 logger = logging.getLogger(__name__)
@@ -430,16 +431,37 @@ class MemoryManager:
 
     # -- Prefetch / recall ---------------------------------------------------
 
+    @staticmethod
+    def _strip_skill_scaffolding(text: str) -> Optional[str]:
+        """Return memory-worthy user text, or None to skip the turn.
+
+        When a user invokes a /skill or /bundle, Hermes expands the turn into
+        a model-facing message that embeds the entire skill body. Feeding that
+        verbatim to memory providers pollutes their stores/embeddings with
+        prompt scaffolding instead of what the user actually asked. We recover
+        just the user's instruction here, once, for every provider — so this
+        is fixed for the whole provider fan-out, not per backend.
+
+        - Non-skill messages pass through unchanged.
+        - Skill turns with a user instruction return that instruction.
+        - Bare skill invocations (no instruction) return None → callers skip
+          the turn, since there is no user content worth remembering.
+        """
+        return extract_user_instruction_from_skill_message(text)
+
     def prefetch_all(self, query: str, *, session_id: str = "") -> str:
         """Collect prefetch context from all providers.
 
         Returns merged context text labeled by provider. Empty providers
         are skipped. Failures in one provider don't block others.
         """
+        clean_query = self._strip_skill_scaffolding(query)
+        if not clean_query:
+            return ""
         parts = []
         for provider in self._providers:
             try:
-                result = provider.prefetch(query, session_id=session_id)
+                result = provider.prefetch(clean_query, session_id=session_id)
                 if result and result.strip():
                     parts.append(result)
             except Exception as e:
@@ -460,10 +482,14 @@ class MemoryManager:
         if not providers:
             return
 
+        clean_query = self._strip_skill_scaffolding(query)
+        if not clean_query:
+            return
+
         def _run() -> None:
             for provider in providers:
                 try:
-                    provider.queue_prefetch(query, session_id=session_id)
+                    provider.queue_prefetch(clean_query, session_id=session_id)
                 except Exception as e:
                     logger.debug(
                         "Memory provider '%s' queue_prefetch failed (non-fatal): %s",
@@ -515,6 +541,11 @@ class MemoryManager:
         if not providers:
             return
 
+        clean_user_content = self._strip_skill_scaffolding(user_content)
+        if not clean_user_content:
+            return
+        user_content = clean_user_content
+
         def _run() -> None:
             for provider in providers:
                 try:

agent/model_metadata.py

@@ -275,6 +275,11 @@ DEFAULT_CONTEXT_LENGTHS = {
     # via a custom provider. Values sourced from models.dev (2026-04).
     # Keys use substring matching (longest-first), so e.g. "grok-4.20"
     # matches "grok-4.20-0309-reasoning" / "-non-reasoning" / "-multi-agent-0309".
+    # OAuth-only slug; absent from GET /v1/models. xAI publishes a 200k
+    # usable context window for Composer 2.5 on Grok Build (SuperGrok /
+    # Premium+); /v1/responses additionally enforces a ~262144 input+output
+    # budget, but the usable context (what we track here) is 200k.
+    "grok-composer": 200000,    # grok-composer-2.5-fast (Grok Build CLI)
     "grok-build": 256000,       # grok-build-0.1
     "grok-code-fast": 256000,   # grok-code-fast-1
     "grok-2-vision": 8192,      # grok-2-vision, -1212, -latest

agent/prompt_builder.py

@@ -8,6 +8,7 @@ import json
 import logging
 import os
 import threading
+import contextvars
 from collections import OrderedDict
 from pathlib import Path
 
@@ -304,6 +305,47 @@ TASK_COMPLETION_GUIDANCE = (
     "is always better than inventing a result."
 )
 
+# Universal parallel-tool-call guidance — applied to ALL models.
+#
+# Why this matters for cost: every assistant turn resends the entire
+# accumulated conversation (and, on cache-friendly providers, re-reads the
+# cached prefix and pays for the newly-appended turn). A model that issues
+# one tool call per turn multiplies the number of round-trips — and therefore
+# the resent context — for any task that needs several independent reads,
+# searches, or safe lookups. Batching independent calls into a single
+# assistant response collapses N turns into one, cutting both latency and the
+# resent-context cost that compounds over a long conversation.
+#
+# The hermes-agent runtime already executes a batch of tool calls
+# concurrently when they are independent (read-only tools always; path-scoped
+# file ops when their targets don't overlap — see
+# run_agent._execute_tool_calls / tool_dispatch_helpers). The missing piece
+# was telling the *model* to emit those calls together in the first place.
+# Until now the only batching steer in the prompt lived in
+# GOOGLE_MODEL_OPERATIONAL_GUIDANCE — Gemini/Gemma got it, every other model
+# got nothing. This block makes the steer universal; the now-redundant
+# Google-only bullet has been dropped so no model receives it twice.
+#
+# Short on purpose — shipped in the cached system prompt to every user, every
+# session. Token cost is paid once at install and amortised across all
+# sessions via prefix caching. Keep it tight.
+#
+# Ported from cline/cline#11514 ("encourage parallel tool calls"), adapted
+# from Cline's TypeScript tool-surface guidance to hermes-agent's Python
+# prompt-assembly architecture.
+PARALLEL_TOOL_CALL_GUIDANCE = (
+    "# Parallel tool calls\n"
+    "When you need several pieces of information that don't depend on each "
+    "other, request them together in a single response instead of one tool "
+    "call per turn. Independent reads, searches, web fetches, and read-only "
+    "commands should be batched into the same assistant turn — the runtime "
+    "executes independent calls concurrently, and batching avoids resending "
+    "the whole conversation on every extra round-trip.\n"
+    "Only serialize calls when a later call genuinely depends on an earlier "
+    "call's result (e.g. you must read a file before you can patch it). When "
+    "in doubt and the calls are independent, batch them."
+)
+
 # OpenAI GPT/Codex-specific execution guidance.  Addresses known failure modes
 # where GPT models abandon work on partial results, skip prerequisite lookups,
 # hallucinate instead of using tools, and declare "done" without verification.
@@ -385,9 +427,10 @@ GOOGLE_MODEL_OPERATIONAL_GUIDANCE = (
     "package.json, requirements.txt, Cargo.toml, etc. before importing.\n"
     "- **Conciseness:** Keep explanatory text brief — a few sentences, not "
     "paragraphs. Focus on actions and results over narration.\n"
-    "- **Parallel tool calls:** When you need to perform multiple independent "
-    "operations (e.g. reading several files), make all the tool calls in a "
-    "single response rather than sequentially.\n"
+    # Parallel-tool-call steering now lives in the universal
+    # PARALLEL_TOOL_CALL_GUIDANCE block (injected for all models), so it is no
+    # longer duplicated here — keeping it would send Gemini/Gemma the same
+    # instruction twice.
     "- **Non-interactive commands:** Use flags like -y, --yes, --non-interactive "
     "to prevent CLI tools from hanging on prompts.\n"
     "- **Keep going:** Work autonomously until the task is fully resolved. "
@@ -957,6 +1000,80 @@ CONTEXT_FILE_MAX_CHARS = 20_000
 CONTEXT_TRUNCATE_HEAD_RATIO = 0.7
 CONTEXT_TRUNCATE_TAIL_RATIO = 0.2
 
+# Dynamic-cap parameters (used when no explicit context_file_max_chars is set).
+# The cap scales with the model's context window so large-context models rarely
+# truncate a project doc, while small-context models stay at the historical
+# 20K floor. ~4 chars/token is the usual English heuristic; we spend a small
+# slice of the window on context files since they share the cached prefix with
+# the system prompt, tools, memory, and the whole conversation.
+_CONTEXT_FILE_CHARS_PER_TOKEN = 4
+_CONTEXT_FILE_WINDOW_FRACTION = 0.06
+_CONTEXT_FILE_DYNAMIC_CEILING = 500_000
+
+
+def _dynamic_context_file_max_chars(context_length: Optional[int]) -> int:
+    """Derive a char cap from the model's context window.
+
+    Returns at least ``CONTEXT_FILE_MAX_CHARS`` (the historical 20K floor) and
+    at most ``_CONTEXT_FILE_DYNAMIC_CEILING``. When ``context_length`` is
+    unknown/invalid, returns the flat default so behavior is unchanged.
+    """
+    if not isinstance(context_length, int) or context_length <= 0:
+        return CONTEXT_FILE_MAX_CHARS
+    budget = int(
+        context_length * _CONTEXT_FILE_CHARS_PER_TOKEN * _CONTEXT_FILE_WINDOW_FRACTION
+    )
+    return max(CONTEXT_FILE_MAX_CHARS, min(budget, _CONTEXT_FILE_DYNAMIC_CEILING))
+
+
+def _get_context_file_max_chars(context_length: Optional[int] = None) -> int:
+    """Return the context-file truncation limit.
+
+    Resolution order:
+      1. Explicit ``context_file_max_chars`` in config.yaml — user knows best,
+         always wins (including over the dynamic cap).
+      2. Dynamic cap derived from the model's ``context_length`` when provided
+         (scales the budget to the window; floor 20K, ceiling 500K).
+      3. ``CONTEXT_FILE_MAX_CHARS`` (20K) as the upstream-compatible fallback.
+    """
+    try:
+        from hermes_cli.config import load_config
+
+        val = load_config().get("context_file_max_chars")
+        if isinstance(val, (int, float)) and val > 0:
+            return int(val)
+    except Exception as e:
+        logger.debug("Could not read context_file_max_chars from config: %s", e)
+    return _dynamic_context_file_max_chars(context_length)
+
+# Collect truncation warnings so the caller (run_agent) can surface them.
+# A ContextVar (not a module-global list) isolates accumulation per thread /
+# per async task, so concurrent gateway-session prompt builds can't drain or
+# clear each other's pending warnings (cross-session leak). Each build runs in
+# its own context, collects its own warnings, and drains them synchronously.
+_truncation_warnings: "contextvars.ContextVar[Optional[list]]" = contextvars.ContextVar(
+    "context_file_truncation_warnings", default=None
+)
+
+
+def _record_truncation_warning(msg: str) -> None:
+    """Append a truncation warning to the current context's accumulator."""
+    warnings = _truncation_warnings.get()
+    if warnings is None:
+        warnings = []
+        _truncation_warnings.set(warnings)
+    warnings.append(msg)
+
+
+def drain_truncation_warnings() -> list:
+    """Return and clear any truncation warnings accumulated in this context."""
+    warnings = _truncation_warnings.get()
+    if not warnings:
+        return []
+    drained = list(warnings)
+    warnings.clear()
+    return drained
+
 
 # =========================================================================
 # Skills prompt cache
@@ -1463,19 +1580,47 @@ def build_nous_subscription_prompt(valid_tool_names: "set[str] | None" = None) -
 # Context files (SOUL.md, AGENTS.md, .cursorrules)
 # =========================================================================
 
-def _truncate_content(content: str, filename: str, max_chars: int = CONTEXT_FILE_MAX_CHARS) -> str:
-    """Head/tail truncation with a marker in the middle."""
+def _truncate_content(
+    content: str,
+    filename: str,
+    max_chars: Optional[int] = None,
+    context_length: Optional[int] = None,
+    read_path: Optional[str] = None,
+) -> str:
+    """Head/tail truncation with a marker in the middle.
+
+    ``filename`` is the human label used in warnings. ``read_path`` is the
+    concrete path the agent should ``read_file`` to recover the full content
+    (defaults to ``filename`` when not supplied). ``context_length`` lets the
+    cap scale to the model's window when no explicit config override is set.
+    """
+    if max_chars is None:
+        max_chars = _get_context_file_max_chars(context_length)
     if len(content) <= max_chars:
         return content
+    target = read_path or filename
+    msg = (
+        f"⚠️  Context file {filename} TRUNCATED: "
+        f"{len(content)} chars exceeds limit of {max_chars} — "
+        f"trim the file, pin a larger context_file_max_chars, or use a "
+        f"larger-context model!"
+    )
+    logger.warning(msg)
+    _record_truncation_warning(msg)
     head_chars = int(max_chars * CONTEXT_TRUNCATE_HEAD_RATIO)
     tail_chars = int(max_chars * CONTEXT_TRUNCATE_TAIL_RATIO)
     head = content[:head_chars]
     tail = content[-tail_chars:]
-    marker = f"\n\n[...truncated {filename}: kept {head_chars}+{tail_chars} of {len(content)} chars. Use file tools to read the full file.]\n\n"
+    marker = (
+        f"\n\n[...truncated {filename}: kept {head_chars}+{tail_chars} of "
+        f"{len(content)} chars. The middle is omitted — if you need the full "
+        f"instructions, read the complete file with the read_file tool: "
+        f"{target}]\n\n"
+    )
     return head + marker + tail
 
 
-def load_soul_md() -> Optional[str]:
+def load_soul_md(context_length: Optional[int] = None) -> Optional[str]:
     """Load SOUL.md from HERMES_HOME and return its content, or None.
 
     Used as the agent identity (slot #1 in the system prompt).  When this
@@ -1496,14 +1641,17 @@ def load_soul_md() -> Optional[str]:
         if not content:
             return None
         content = _scan_context_content(content, "SOUL.md")
-        content = _truncate_content(content, "SOUL.md")
+        content = _truncate_content(
+            content, "SOUL.md", context_length=context_length,
+            read_path=str(soul_path),
+        )
         return content
     except Exception as e:
         logger.debug("Could not read SOUL.md from %s: %s", soul_path, e)
         return None
 
 
-def _load_hermes_md(cwd_path: Path) -> str:
+def _load_hermes_md(cwd_path: Path, context_length: Optional[int] = None) -> str:
     """.hermes.md / HERMES.md — walk to git root."""
     hermes_md_path = _find_hermes_md(cwd_path)
     if not hermes_md_path:
@@ -1520,13 +1668,16 @@ def _load_hermes_md(cwd_path: Path) -> str:
             pass
         content = _scan_context_content(content, rel)
         result = f"## {rel}\n\n{content}"
-        return _truncate_content(result, ".hermes.md")
+        return _truncate_content(
+            result, ".hermes.md", context_length=context_length,
+            read_path=str(hermes_md_path),
+        )
     except Exception as e:
         logger.debug("Could not read %s: %s", hermes_md_path, e)
         return ""
 
 
-def _load_agents_md(cwd_path: Path) -> str:
+def _load_agents_md(cwd_path: Path, context_length: Optional[int] = None) -> str:
     """AGENTS.md — top-level only (no recursive walk)."""
     for name in ["AGENTS.md", "agents.md"]:
         candidate = cwd_path / name
@@ -1536,13 +1687,16 @@ def _load_agents_md(cwd_path: Path) -> str:
                 if content:
                     content = _scan_context_content(content, name)
                     result = f"## {name}\n\n{content}"
-                    return _truncate_content(result, "AGENTS.md")
+                    return _truncate_content(
+                        result, "AGENTS.md", context_length=context_length,
+                        read_path=str(candidate),
+                    )
             except Exception as e:
                 logger.debug("Could not read %s: %s", candidate, e)
     return ""
 
 
-def _load_claude_md(cwd_path: Path) -> str:
+def _load_claude_md(cwd_path: Path, context_length: Optional[int] = None) -> str:
     """CLAUDE.md / claude.md — cwd only."""
     for name in ["CLAUDE.md", "claude.md"]:
         candidate = cwd_path / name
@@ -1552,13 +1706,16 @@ def _load_claude_md(cwd_path: Path) -> str:
                 if content:
                     content = _scan_context_content(content, name)
                     result = f"## {name}\n\n{content}"
-                    return _truncate_content(result, "CLAUDE.md")
+                    return _truncate_content(
+                        result, "CLAUDE.md", context_length=context_length,
+                        read_path=str(candidate),
+                    )
             except Exception as e:
                 logger.debug("Could not read %s: %s", candidate, e)
     return ""
 
 
-def _load_cursorrules(cwd_path: Path) -> str:
+def _load_cursorrules(cwd_path: Path, context_length: Optional[int] = None) -> str:
     """.cursorrules + .cursor/rules/*.mdc — cwd only."""
     cursorrules_content = ""
     cursorrules_file = cwd_path / ".cursorrules"
@@ -1585,10 +1742,17 @@ def _load_cursorrules(cwd_path: Path) -> str:
 
     if not cursorrules_content:
         return ""
-    return _truncate_content(cursorrules_content, ".cursorrules")
+    return _truncate_content(
+        cursorrules_content, ".cursorrules", context_length=context_length,
+        read_path=str(cwd_path / ".cursorrules"),
+    )
 
 
-def build_context_files_prompt(cwd: Optional[str] = None, skip_soul: bool = False) -> str:
+def build_context_files_prompt(
+    cwd: Optional[str] = None,
+    skip_soul: bool = False,
+    context_length: Optional[int] = None,
+) -> str:
     """Discover and load context files for the system prompt.
 
     Priority (first found wins — only ONE project context type is loaded):
@@ -1598,7 +1762,11 @@ def build_context_files_prompt(cwd: Optional[str] = None, skip_soul: bool = Fals
       4. .cursorrules / .cursor/rules/*.mdc  (cwd only)
 
     SOUL.md from HERMES_HOME is independent and always included when present.
-    Each context source is capped at 20,000 chars.
+
+    Each context source is capped before injection. The cap defaults to the
+    model's context window (scaled — see ``_dynamic_context_file_max_chars``)
+    when *context_length* is provided, falling back to 20,000 chars otherwise.
+    An explicit ``context_file_max_chars`` in config.yaml always wins.
 
     When *skip_soul* is True, SOUL.md is not included here (it was already
     loaded via ``load_soul_md()`` for the identity slot).
@@ -1611,17 +1779,17 @@ def build_context_files_prompt(cwd: Optional[str] = None, skip_soul: bool = Fals
 
     # Priority-based project context: first match wins
     project_context = (
-        _load_hermes_md(cwd_path)
-        or _load_agents_md(cwd_path)
-        or _load_claude_md(cwd_path)
-        or _load_cursorrules(cwd_path)
+        _load_hermes_md(cwd_path, context_length)
+        or _load_agents_md(cwd_path, context_length)
+        or _load_claude_md(cwd_path, context_length)
+        or _load_cursorrules(cwd_path, context_length)
     )
     if project_context:
         sections.append(project_context)
 
     # SOUL.md from HERMES_HOME only — skip when already loaded as identity
     if not skip_soul:
-        soul_content = load_soul_md()
+        soul_content = load_soul_md(context_length)
         if soul_content:
             sections.append(soul_content)
 

agent/skill_commands.py

@@ -26,6 +26,91 @@ _skill_commands_platform: Optional[str] = None
 _SKILL_INVALID_CHARS = re.compile(r"[^a-z0-9-]")
 _SKILL_MULTI_HYPHEN = re.compile(r"-{2,}")
 
+# ---------------------------------------------------------------------------
+# Skill-scaffolding markers and the canonical extractor.
+#
+# When a user invokes a /skill (or /bundle), Hermes expands the turn into a
+# model-facing message that embeds the full skill body plus scaffolding. That
+# expanded text is what flows into the agent loop — and into memory providers
+# via MemoryManager. Providers that store or embed the raw user turn (mem0,
+# openviking, hindsight, retaindb, byterover, honcho, supermemory) would
+# otherwise capture the entire skill body instead of what the user actually
+# asked. ``extract_user_instruction_from_skill_message`` recovers just the
+# user's instruction so memory stays clean.
+#
+# These markers MUST stay byte-identical to the builders below
+# (``_build_skill_message`` here, ``build_bundle_invocation_message`` in
+# agent/skill_bundles.py). They are co-located with the single-skill builder
+# on purpose, and the bundle markers are asserted against the bundle builder in
+# tests/openviking_plugin/test_openviking.py::test_skill_markers_match_hermes_scaffolding.
+# ---------------------------------------------------------------------------
+_SKILL_INVOCATION_PREFIX = "[IMPORTANT: The user has invoked the "
+_SINGLE_SKILL_MARKER = "The full skill content is loaded below.]"
+_SINGLE_SKILL_INSTRUCTION = (
+    "The user has provided the following instruction alongside the skill invocation: "
+)
+_RUNTIME_NOTE = "\n\n[Runtime note:"
+_BUNDLE_MARKER = " skill bundle,"
+_BUNDLE_USER_INSTRUCTION = "\nUser instruction: "
+_BUNDLE_FIRST_SKILL_BLOCK = "\n\n[Loaded as part of the "
+
+
+def extract_user_instruction_from_skill_message(content: Any) -> Optional[str]:
+    """Recover the user's instruction from a slash-skill-expanded turn.
+
+    Returns:
+        - The original string unchanged when it is NOT skill scaffolding
+          (a normal user message passes straight through).
+        - The extracted user instruction when the scaffolding carried one.
+        - ``None`` when the content is skill scaffolding with no user
+          instruction (i.e. a bare ``/skill`` invocation). Callers that feed
+          memory providers should skip the turn in that case — there is no
+          user content worth storing.
+    """
+    if not isinstance(content, str):
+        return None
+
+    if not content.startswith(_SKILL_INVOCATION_PREFIX):
+        return content
+
+    if _BUNDLE_MARKER in content:
+        return _extract_bundle_user_instruction(content)
+
+    if _SINGLE_SKILL_MARKER in content:
+        return _extract_single_skill_user_instruction(content)
+
+    return None
+
+
+def _extract_single_skill_user_instruction(message: str) -> Optional[str]:
+    # Single-skill format appends the user instruction after the skill body, so
+    # the last occurrence is the user-provided one; the body may quote this text.
+    marker_idx = message.rfind(_SINGLE_SKILL_INSTRUCTION)
+    if marker_idx < 0:
+        return None
+
+    instruction = message[marker_idx + len(_SINGLE_SKILL_INSTRUCTION):]
+    runtime_idx = instruction.find(_RUNTIME_NOTE)
+    if runtime_idx >= 0:
+        instruction = instruction[:runtime_idx]
+    instruction = instruction.strip()
+    return instruction or None
+
+
+def _extract_bundle_user_instruction(message: str) -> Optional[str]:
+    # Bundle format puts the user instruction before the loaded skills, so the
+    # first occurrence is the user-provided one.
+    marker_idx = message.find(_BUNDLE_USER_INSTRUCTION)
+    if marker_idx < 0:
+        return None
+
+    instruction = message[marker_idx + len(_BUNDLE_USER_INSTRUCTION):]
+    first_skill_idx = instruction.find(_BUNDLE_FIRST_SKILL_BLOCK)
+    if first_skill_idx >= 0:
+        instruction = instruction[:first_skill_idx]
+    instruction = instruction.strip()
+    return instruction or None
+
 
 def _resolve_skill_commands_platform() -> Optional[str]:
     """Return the current platform scope used for disabled-skill filtering.

agent/skill_utils.py

@@ -43,14 +43,20 @@ EXCLUDED_SKILL_DIRS = frozenset(
     )
 )
 
+# Supporting files live inside a skill package and are loaded explicitly via
+# skill_view(skill, file_path=...). They are not standalone skills and must not
+# be scanned for active SKILL.md/DESCRIPTION.md entries, even if a Curator or
+# archive workflow preserves a complete old skill package under references/.
+SKILL_SUPPORT_DIRS = frozenset(("references", "templates", "assets", "scripts"))
+
 
 def is_excluded_skill_path(path) -> bool:
-    """True if any component of *path* is in EXCLUDED_SKILL_DIRS.
+    """True if *path* should be skipped by active skill scanners.
 
-    Use this on every SKILL.md path produced by ``rglob`` to prune
-    dependency, virtualenv, VCS, and cache directories. Centralising the
-    check here keeps every skill-scanning site in sync with the shared
-    exclusion set.
+    Use this on every ``SKILL.md`` path produced by direct ``rglob`` scans to
+    prune dependency, virtualenv, VCS, cache, and progressive-disclosure
+    support-package paths. Centralising the check here keeps every
+    skill-scanning site in sync with the shared exclusion set.
 
     Accepts a Path or string.
     """
@@ -59,7 +65,36 @@ def is_excluded_skill_path(path) -> bool:
     except AttributeError:
         from pathlib import PurePath
         parts = PurePath(str(path)).parts
-    return any(part in EXCLUDED_SKILL_DIRS for part in parts)
+    return any(part in EXCLUDED_SKILL_DIRS for part in parts) or is_skill_support_path(
+        path
+    )
+
+
+def is_skill_support_path(path) -> bool:
+    """True if *path* is under a support dir of an actual skill root.
+
+    ``references/``, ``templates/``, ``assets/``, and ``scripts/`` are
+    progressive-disclosure support areas when they sit directly inside a skill
+    directory containing ``SKILL.md``. They are not active discovery roots for
+    standalone skills. A preserved package such as
+    ``some-skill/references/old-skill-package/SKILL.md`` is documentation data
+    unless the caller explicitly loads it via ``file_path``.
+
+    Legitimate categories or skill names such as ``skills/scripts/foo`` remain
+    discoverable because their ``scripts`` component is not directly under a
+    directory that contains ``SKILL.md``.
+    """
+    path_obj = path if isinstance(path, Path) else Path(str(path))
+    parts = path_obj.parts
+    # Last component may be a file or candidate skill directory name. Only
+    # components before the leaf can be containing support directories.
+    for idx, part in enumerate(parts[:-1]):
+        if part not in SKILL_SUPPORT_DIRS or idx == 0:
+            continue
+        skill_root = Path(*parts[:idx])
+        if (skill_root / "SKILL.md").exists():
+            return True
+    return False
 
 
 # ── Lazy YAML loader ─────────────────────────────────────────────────────
@@ -661,12 +696,21 @@ def extract_skill_description(frontmatter: Dict[str, Any]) -> str:
 def iter_skill_index_files(skills_dir: Path, filename: str):
     """Walk skills_dir yielding sorted paths matching *filename*.
 
-    Excludes Hermes metadata, VCS, virtualenv/dependency, and cache
-    directories so dependencies cannot register nested skills.
+    Excludes Hermes metadata, VCS, virtualenv/dependency, cache, and skill
+    support directories. Support directories (references/templates/assets/
+    scripts) can contain arbitrary markdown and even archived package
+    ``SKILL.md`` files, but they are progressive-disclosure data loaded through
+    ``skill_view(..., file_path=...)`` rather than active skill roots.
     """
     matches = []
     for root, dirs, files in os.walk(skills_dir, followlinks=True):
-        dirs[:] = [d for d in dirs if d not in EXCLUDED_SKILL_DIRS]
+        has_skill_md = "SKILL.md" in files
+        dirs[:] = [
+            d
+            for d in dirs
+            if d not in EXCLUDED_SKILL_DIRS
+            and not (has_skill_md and d in SKILL_SUPPORT_DIRS)
+        ]
         if filename in files:
             matches.append(Path(root) / filename)
     for path in sorted(matches, key=lambda p: str(p.relative_to(skills_dir))):

agent/system_prompt.py

@@ -33,6 +33,7 @@ from agent.prompt_builder import (
     KANBAN_GUIDANCE,
     MEMORY_GUIDANCE,
     OPENAI_MODEL_EXECUTION_GUIDANCE,
+    PARALLEL_TOOL_CALL_GUIDANCE,
     PLATFORM_HINTS,
     SESSION_SEARCH_GUIDANCE,
     SKILLS_GUIDANCE,
@@ -40,6 +41,7 @@ from agent.prompt_builder import (
     TASK_COMPLETION_GUIDANCE,
     TOOL_USE_ENFORCEMENT_GUIDANCE,
     TOOL_USE_ENFORCEMENT_MODELS,
+    drain_truncation_warnings,
 )
 from agent.runtime_cwd import resolve_context_cwd
 
@@ -59,6 +61,55 @@ def _ra():
     return run_agent
 
 
+def _resolve_platform_hint(agent: Any, platform_key: str, default_hint: str) -> str:
+    """Apply a per-platform prompt-hint override to the default hint.
+
+    Reads ``agent._platform_hint_overrides`` (populated from
+    ``config.yaml`` ``platform_hints`` by ``agent_init``) and resolves the
+    effective hint for *platform_key*:
+
+      * ``replace`` — substitute the default hint entirely.
+      * ``append``  — keep the default and append the extra text.
+      * a bare string value — treated as ``append`` (convenience shorthand).
+
+    Precedence: ``replace`` wins over ``append`` if both are present.
+    Override text is added on top of (not instead of) the SOUL/context/
+    memory tiers — it only affects the platform-hint segment, so other
+    platforms are unaffected and general system instructions still apply.
+
+    Defensive: any malformed entry falls back to the unmodified default so
+    a bad config value can never break prompt assembly or leak across
+    platforms.
+    """
+    if not platform_key:
+        return default_hint
+    overrides = getattr(agent, "_platform_hint_overrides", None)
+    if not isinstance(overrides, dict) or not overrides:
+        return default_hint
+    spec = overrides.get(platform_key)
+    if spec is None:
+        return default_hint
+
+    # Shorthand: a bare string is treated as append text.
+    if isinstance(spec, str):
+        extra = spec.strip()
+        return f"{default_hint}\n\n{extra}".strip() if extra else default_hint
+
+    if not isinstance(spec, dict):
+        return default_hint
+
+    replace_text = spec.get("replace")
+    if isinstance(replace_text, str) and replace_text.strip():
+        base = replace_text.strip()
+    else:
+        base = default_hint
+
+    append_text = spec.get("append")
+    if isinstance(append_text, str) and append_text.strip():
+        return f"{base}\n\n{append_text.strip()}".strip()
+    return base
+
+
 def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None) -> Dict[str, str]:
     """Assemble the system prompt as three ordered parts.
 
@@ -82,6 +133,17 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None)
     # we resolve through ``_ra()`` to honor those patches.
     _r = _ra()
 
+    # Resolve the model's context window once so context-file caps can scale
+    # to it (dynamic cap — see prompt_builder._dynamic_context_file_max_chars).
+    # None falls back to the historical flat default. This value is stable for
+    # the life of the conversation, so it does not threaten prompt caching.
+    _ctx_len: Optional[int] = None
+    _cc = getattr(agent, "context_compressor", None)
+    if _cc is not None:
+        _cc_len = getattr(_cc, "context_length", None)
+        if isinstance(_cc_len, int) and _cc_len > 0:
+            _ctx_len = _cc_len
+
     # ── Stable tier ────────────────────────────────────────────────
     stable_parts: List[str] = []
 
@@ -90,7 +152,7 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None)
     # cwd project instructions disabled.
     _soul_loaded = False
     if agent.load_soul_identity or not agent.skip_context_files:
-        _soul_content = _r.load_soul_md()
+        _soul_content = _r.load_soul_md(_ctx_len)
         if _soul_content:
             stable_parts.append(_soul_content)
             _soul_loaded = True
@@ -111,6 +173,17 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None)
     if getattr(agent, "_task_completion_guidance", True) and agent.valid_tool_names:
         stable_parts.append(TASK_COMPLETION_GUIDANCE)
 
+    # Universal parallel-tool-call guidance.  Tells the model to batch
+    # independent tool calls into one assistant turn rather than emitting one
+    # call per turn — the runtime already runs independent calls concurrently
+    # (read-only tools always; non-overlapping path-scoped file ops), so the
+    # only thing missing was steering the model to produce the batch.  Cuts
+    # round-trips and the resent-context cost that compounds over a long
+    # conversation.  Gated by config.yaml ``agent.parallel_tool_call_guidance``
+    # (default True) and only injected when tools are actually loaded.
+    if getattr(agent, "_parallel_tool_call_guidance", True) and agent.valid_tool_names:
+        stable_parts.append(PARALLEL_TOOL_CALL_GUIDANCE)
+
     # Tool-aware behavioral guidance: only inject when the tools are loaded
     tool_guidance = []
     if "memory" in agent.valid_tool_names:
@@ -307,18 +380,25 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None)
         )
 
     platform_key = (agent.platform or "").lower().strip()
+    # Resolve the built-in/plugin default hint for this platform, then apply
+    # any per-platform override from config (platform_hints.<platform>).
+    _default_hint = ""
     if platform_key in PLATFORM_HINTS:
-        stable_parts.append(PLATFORM_HINTS[platform_key])
+        _default_hint = PLATFORM_HINTS[platform_key]
     elif platform_key:
         # Check plugin registry for platform-specific LLM guidance
         try:
             from gateway.platform_registry import platform_registry
             _entry = platform_registry.get(platform_key)
             if _entry and _entry.platform_hint:
-                stable_parts.append(_entry.platform_hint)
+                _default_hint = _entry.platform_hint
         except Exception:
             pass
 
+    _effective_hint = _resolve_platform_hint(agent, platform_key, _default_hint)
+    if _effective_hint:
+        stable_parts.append(_effective_hint)
+
     # ── Context tier (cwd-dependent, may change between sessions) ─
     context_parts: List[str] = []
 
@@ -333,7 +413,8 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None)
         # dir — the user's real cwd there, but the install dir for the gateway
         # daemon, which is why the gateway sets TERMINAL_CWD.
         context_files_prompt = _r.build_context_files_prompt(
-            cwd=resolve_context_cwd(), skip_soul=_soul_loaded)
+            cwd=resolve_context_cwd(), skip_soul=_soul_loaded,
+            context_length=_ctx_len)
         if context_files_prompt:
             context_parts.append(context_files_prompt)
 
@@ -400,7 +481,14 @@ def build_system_prompt(agent: Any, system_message: Optional[str] = None) -> str
     warm across turns.
     """
     parts = build_system_prompt_parts(agent, system_message=system_message)
-    return "\n\n".join(p for p in (parts["stable"], parts["context"], parts["volatile"]) if p)
+    joined = "\n\n".join(p for p in (parts["stable"], parts["context"], parts["volatile"]) if p)
+
+    # Surface context-file truncation warnings through the normal agent status
+    # channel so gateway/CLI users see them in chat instead of only in logs.
+    for warning in drain_truncation_warnings():
+        agent._emit_status(warning)
+
+    return joined
 
 
 def invalidate_system_prompt(agent: Any) -> None:

agent/tool_executor.py

@@ -1012,28 +1012,42 @@ def execute_tool_calls_sequential(agent, assistant_message, messages: list, effe
         elif function_name == "memory":
             def _execute(next_args: dict) -> Any:
                 target = next_args.get("target", "memory")
+                operations = next_args.get("operations")
                 from tools.memory_tool import memory_tool as _memory_tool
                 result = _memory_tool(
                     action=next_args.get("action"),
                     target=target,
                     content=next_args.get("content"),
                     old_text=next_args.get("old_text"),
+                    operations=operations,
                     store=agent._memory_store,
                 )
-                # Bridge: notify external memory provider of built-in memory writes
-                if agent._memory_manager and next_args.get("action") in {"add", "replace"}:
-                    try:
-                        agent._memory_manager.on_memory_write(
-                            next_args.get("action", ""),
-                            target,
-                            next_args.get("content", ""),
-                            metadata=agent._build_memory_write_metadata(
-                                task_id=effective_task_id,
-                                tool_call_id=getattr(tool_call, "id", None),
-                            ),
+                # Bridge: notify external memory provider of built-in memory writes.
+                # Covers both the single-op shape and each add/replace inside a batch.
+                if agent._memory_manager:
+                    if operations:
+                        _mem_ops = [
+                            op for op in operations
+                            if isinstance(op, dict) and op.get("action") in {"add", "replace"}
+                        ]
+                    else:
+                        _mem_ops = (
+                            [{"action": next_args.get("action"), "content": next_args.get("content")}]
+                            if next_args.get("action") in {"add", "replace"} else []
                         )
-                    except Exception:
-                        pass
+                    for _op in _mem_ops:
+                        try:
+                            agent._memory_manager.on_memory_write(
+                                _op.get("action", ""),
+                                target,
+                                _op.get("content", "") or "",
+                                metadata=agent._build_memory_write_metadata(
+                                    task_id=effective_task_id,
+                                    tool_call_id=getattr(tool_call, "id", None),
+                                ),
+                            )
+                        except Exception:
+                            pass
                 return result
             function_result, function_args = _run_agent_tool_execution_middleware(
                 agent,

agent/transports/anthropic.py

@@ -88,7 +88,7 @@ class AnthropicTransport(ProviderTransport):
         from agent.transports.types import ToolCall
 
         strip_tool_prefix = kwargs.get("strip_tool_prefix", False)
-        _MCP_PREFIX = "mcp_"
+        _MCP_PREFIX = "mcp__"
 
         text_parts = []
         reasoning_parts = []
@@ -132,17 +132,25 @@ class AnthropicTransport(ProviderTransport):
             elif block.type == "tool_use":
                 name = block.name
                 if strip_tool_prefix and name.startswith(_MCP_PREFIX):
-                    stripped = name[len(_MCP_PREFIX):]
-                    # Only strip the mcp_ prefix for OAuth-injected tools
-                    # (where Hermes adds the prefix when sending to Anthropic
-                    # and must remove it on the way back).  Native MCP server
-                    # tools (from mcp_servers: in config.yaml) are registered
-                    # in the tool registry under their FULL mcp_<server>_<tool>
-                    # name and must NOT be stripped.  GH-25255.
+                    # On the OAuth wire every tool carries a double-underscore
+                    # ``mcp__`` prefix (added in build_anthropic_kwargs to avoid
+                    # Anthropic's single-underscore third-party classifier).
+                    # Reverse it back to the name the registry/dispatcher knows.
+                    # Two original forms map onto the same ``mcp__`` wire name:
+                    #   ``mcp__read_file``       <- bare native tool ``read_file``
+                    #   ``mcp__linear_get_issue`` <- MCP server tool
+                    #                                ``mcp_linear_get_issue``
+                    # Resolve by registry lookup, preferring whichever original
+                    # is actually registered; never rewrite a name the LLM used
+                    # that already resolves natively. GH-25255.
                     from tools.registry import registry as _tool_registry
-                    if (_tool_registry.get_entry(stripped)
-                            and not _tool_registry.get_entry(name)):
-                        name = stripped
+                    if not _tool_registry.get_entry(name):
+                        bare = name[len(_MCP_PREFIX):]            # read_file
+                        single = "mcp_" + bare                    # mcp_read_file / mcp_linear_get_issue
+                        if _tool_registry.get_entry(single):
+                            name = single
+                        elif _tool_registry.get_entry(bare):
+                            name = bare
                 tool_calls.append(
                     ToolCall(
                         id=block.id,

agent/transports/codex.py

@@ -128,6 +128,65 @@ class ResponsesApiTransport(ProviderTransport):
         reasoning_effort = _effort_clamp.get(reasoning_effort, reasoning_effort)
 
         response_tools = _responses_tools(tools)
+
+        # xAI server-side web search.
+        #
+        # grok models on xAI's /v1/responses surface (notably
+        # grok-composer-2.5-fast on SuperGrok OAuth) have a *native*,
+        # server-executed web search.  When the model is handed a
+        # client-side function literally named ``web_search``, it routes
+        # the intent to that native engine — but because the tool is
+        # declared as a plain ``function`` rather than xAI's first-class
+        # ``{"type": "web_search"}`` built-in, the server-side search is
+        # dispatched but never reconciled: the response streams reasoning
+        # + ``web_search_call`` progress items, the searches never reach
+        # ``status="completed"`` in the assembled output, no final
+        # message is emitted, and ``_normalize_codex_response`` correctly
+        # sees reasoning-with-no-answer and reports ``incomplete``.  The
+        # turn then burns 3 continuation retries and fails with "Codex
+        # response remained incomplete after 3 continuation attempts".
+        # Verified live against grok-composer-2.5-fast (2026-06).
+        #
+        # Fix: when the agent HAS a client-side ``web_search`` function (i.e.
+        # the user enabled the web toolset), declare xAI's native
+        # ``web_search`` built-in instead so the search actually runs to
+        # completion server-side and the model streams a real answer.  The
+        # Responses API rejects two tools sharing the name ``web_search``
+        # (HTTP 400 "Duplicate tool names"), so we drop the client-side
+        # ``web_search`` function for the xAI path and let the native tool
+        # satisfy it.  All other client-side tools (read_file, terminal,
+        # web_extract, MCP tools, …) are untouched and continue to dispatch
+        # through Hermes's agent loop.
+        #
+        # Scope: we ONLY swap in the native built-in when the client
+        # ``web_search`` was actually present.  We do NOT force-enable Grok
+        # server-side search on turns where the user never had web enabled —
+        # that would silently route around Hermes's web-provider config and
+        # tool-trace/citation plumbing for every xai-oauth turn.  The swap is
+        # a 1:1 replacement of an already-requested capability, not an
+        # additive grant.
+        #
+        # NOTE: for the swapped case this routes ``web_search`` to Grok's
+        # native search engine for xAI sessions instead of Hermes's
+        # configured web provider (Tavily/etc.), and those results bypass
+        # Hermes's tool-trace / citation plumbing (they arrive baked into the
+        # model's answer rather than as a tool result the loop observes).
+        # Scoped to ``is_xai_responses`` deliberately; narrow to specific
+        # models if a future grok variant should keep the client-side
+        # function.
+        if is_xai_responses and response_tools:
+            has_client_web_search = any(
+                isinstance(t, dict) and t.get("name") == "web_search"
+                for t in response_tools
+            )
+            if has_client_web_search:
+                filtered = [
+                    t for t in response_tools
+                    if not (isinstance(t, dict) and t.get("name") == "web_search")
+                ]
+                filtered.append({"type": "web_search"})
+                response_tools = filtered
+
         # ``tools`` MUST be omitted entirely when there are no functions to
         # expose: the openai SDK's ``responses.stream()`` / ``responses.parse()``
         # eagerly call ``_make_tools(tools)`` which does ``for tool in tools``
@@ -218,10 +277,28 @@ class ResponsesApiTransport(ProviderTransport):
             kwargs.pop("timeout", None)
 
         if is_codex_backend:
-            # chatgpt.com/backend-api/codex rejects body-level
-            # ``extra_headers`` with HTTP 400. Correlation/cache routing for
-            # this backend must not be sent through the Responses payload.
-            kwargs.pop("extra_headers", None)
+            # The Codex backend rejects body-level ``extra_headers`` with
+            # HTTP 400, but the OpenAI SDK's ``extra_headers`` kwarg maps
+            # to actual HTTP request headers (not body fields).  We need
+            # these headers for cache-scope routing so prompt cache hits
+            # remain high.  Send session_id / x-client-request-id as HTTP
+            # headers while keeping ``prompt_cache_key`` in the body for
+            # standard OpenAI routing as a belt-and-braces fallback.
+            cache_scope_id = str(session_id or "").strip()
+            if cache_scope_id:
+                existing_extra_headers = kwargs.get("extra_headers")
+                merged_extra_headers: Dict[str, str] = {}
+                if isinstance(existing_extra_headers, dict):
+                    merged_extra_headers.update(
+                        {
+                            str(key): str(value)
+                            for key, value in existing_extra_headers.items()
+                            if key and value is not None
+                        }
+                    )
+                merged_extra_headers["session_id"] = cache_scope_id
+                merged_extra_headers["x-client-request-id"] = cache_scope_id
+                kwargs["extra_headers"] = merged_extra_headers
 
         max_tokens = params.get("max_tokens")
         if max_tokens is not None and not is_codex_backend:

agent/turn_context.py

@@ -69,6 +69,7 @@ def build_turn_context(
     task_id: Optional[str],
     stream_callback,
     persist_user_message: Optional[str],
+    persist_user_timestamp: Optional[float] = None,
     *,
     restore_or_build_system_prompt,
     install_safe_stdio,
@@ -121,6 +122,7 @@ def build_turn_context(
     agent._stream_callback = stream_callback
     agent._persist_user_message_idx = None
     agent._persist_user_message_override = persist_user_message
+    agent._persist_user_message_timestamp = persist_user_timestamp
     # Generate unique task_id if not provided to isolate VMs between tasks.
     effective_task_id = task_id or str(uuid.uuid4())
     agent._current_task_id = effective_task_id

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

@@ -286,7 +286,7 @@ async fn run_update(app: AppHandle) -> Result<()> {
     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(
+    let mut rebuild = run_streamed(
         &app,
         &hermes,
         &rebuild_args,
@@ -295,6 +295,33 @@ async fn run_update(app: AppHandle) -> Result<()> {
         Some("rebuild"),
     )
     .await?;
+
+    // Retry-once: the first `--build-only` can return nonzero on a still-settling
+    // post-update tree or a network-blocked Electron fetch that our self-heal
+    // repaired mid-run. A second attempt then builds clean off the healed dist
+    // (the content-hash stamp makes it a near-no-op when the first actually
+    // succeeded). Without this the updater bails here and never reaches the
+    // relaunch below — the app updates but doesn't restart. Matches the
+    // retry-once `hermes update` already does above, and `hermes update`'s own
+    // desktop rebuild in cmd_update.
+    if rebuild_needs_retry(rebuild.exit_code) {
+        emit_log(
+            &app,
+            Some("rebuild"),
+            LogStream::Stdout,
+            "[rebuild] first desktop rebuild failed; retrying once (a self-healed \
+             Electron download builds clean on the second run)…",
+        );
+        rebuild = run_streamed(
+            &app,
+            &hermes,
+            &rebuild_args,
+            &install_root,
+            &child_env,
+            Some("rebuild"),
+        )
+        .await?;
+    }
     let rebuild_ms = started.elapsed().as_millis() as u64;
 
     if rebuild.exit_code != Some(0) {
@@ -533,6 +560,14 @@ fn is_locked(path: &Path) -> bool {
     }
 }
 
+/// Whether the `desktop --build-only` rebuild should be retried once. Any
+/// non-success exit qualifies: the common cause is a transient first-attempt
+/// failure (still-settling tree / self-healed Electron download) that a clean
+/// second run resolves.
+fn rebuild_needs_retry(exit_code: Option<i32>) -> bool {
+    exit_code != Some(0)
+}
+
 /// Spawn `hermes <args>` from `cwd`, stream stdout/stderr as Log events on the
 /// bootstrap channel, and return the exit code. Mirrors powershell::run_script
 /// but for an arbitrary command (no install.ps1 -File wrapping).
@@ -970,6 +1005,16 @@ mod tests {
         assert_eq!(update_branch_from_args(["--update"]), None);
     }
 
+    #[test]
+    fn rebuild_retries_only_on_failure() {
+        assert!(!rebuild_needs_retry(Some(0)), "a clean rebuild must not retry");
+        assert!(rebuild_needs_retry(Some(1)), "a failed rebuild retries once");
+        assert!(
+            rebuild_needs_retry(None),
+            "a killed/signalled rebuild (no exit code) retries once"
+        );
+    }
+
     #[test]
     fn parses_only_app_targets() {
         assert_eq!(

apps/desktop/electron/git-repo-scan.cjs

@@ -0,0 +1,98 @@
+'use strict'
+
+// Repo-first discovery: walk bounded roots for git repos using only Node's `fs`
+// — no native addon, so it just works for anyone who pulls main (no
+// electron-rebuild). Mirrors how GitHub Desktop scans: stop at the first `.git`
+// (don't descend into a repo), cap depth, and skip heavy non-repo trees so the
+// first scan stays fast. Results are cached by the backend after the first run.
+
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const fsp = fs.promises
+
+// Shallow on purpose: real projects live a few levels under home
+// (`~/www/repo`, `~/code/org/repo`); deeper `.git` dirs are almost always
+// fixtures/vendored/eval checkouts (e.g. `~/www/ha-evals/tasks/*/repo`). Repos
+// you actually use but keep deeper still surface via session-derived discovery,
+// so this only prunes noise, never repos with history.
+const DEFAULT_MAX_DEPTH = 3
+const MAX_CONCURRENCY = 32
+
+// Big trees that are never themselves repos and would waste the walk. Anything
+// hidden (dotdirs like .cache/.Trash/.npm) is skipped wholesale below, so this
+// only needs the non-hidden heavyweights.
+const JUNK_DIRS = new Set(['Applications', 'Library', 'node_modules', 'site-packages', 'vendor', 'venv'])
+
+async function mapLimit(items, limit, fn) {
+  let cursor = 0
+
+  async function worker() {
+    while (cursor < items.length) {
+      const index = cursor
+      cursor += 1
+      await fn(items[index])
+    }
+  }
+
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker))
+}
+
+/**
+ * Scan `roots` (default: the home dir) for git repositories. Returns deduped
+ * `{ root, label }` entries. `options.maxDepth` caps recursion (default 3).
+ */
+async function scanGitRepos(roots, options = {}) {
+  const maxDepth = Number(options.maxDepth) || DEFAULT_MAX_DEPTH
+  const searchRoots = Array.isArray(roots) && roots.length > 0 ? roots : [os.homedir()]
+  const found = new Map()
+
+  async function walk(dir, depth) {
+    if (depth > maxDepth) {
+      return
+    }
+
+    let entries
+    try {
+      entries = await fsp.readdir(dir, { withFileTypes: true })
+    } catch {
+      return // unreadable / permission denied
+    }
+
+    // A `.git` DIRECTORY marks a real repo root (a main checkout). A `.git`
+    // FILE is a linked worktree or submodule — those belong to their parent
+    // repo as lanes, not as separate projects, so we don't list them (and we
+    // keep descending in case a real repo sits deeper). This is what kills the
+    // worktree/eval-repo duplicate explosion.
+    if (entries.some(entry => entry.name === '.git' && entry.isDirectory())) {
+      const root = dir.replace(/[/\\]+$/, '')
+      found.set(root, path.basename(root) || root)
+
+      return
+    }
+
+    const subdirs = []
+    for (const entry of entries) {
+      // Real directories only (skip symlinks to avoid loops), no hidden dirs, no
+      // known heavy trees.
+      if (!entry.isDirectory() || entry.name.startsWith('.') || JUNK_DIRS.has(entry.name)) {
+        continue
+      }
+
+      subdirs.push(path.join(dir, entry.name))
+    }
+
+    await mapLimit(subdirs, MAX_CONCURRENCY, sub => walk(sub, depth + 1))
+  }
+
+  await mapLimit(
+    searchRoots.map(root => String(root || '').trim()).filter(Boolean),
+    MAX_CONCURRENCY,
+    root => walk(root, 0)
+  )
+
+  return [...found.entries()].map(([root, label]) => ({ label, root }))
+}
+
+module.exports = { scanGitRepos }

apps/desktop/electron/git-worktree-ops.cjs

@@ -0,0 +1,227 @@
+'use strict'
+
+// Git-driven worktree operations for the desktop "Start work" flow: spin up a
+// fresh worktree the lightest way (`git worktree add -b`), list real worktrees,
+// and remove them. Git is the source of truth; the renderer just drives these.
+
+const path = require('node:path')
+const fs = require('node:fs')
+const { execFile } = require('node:child_process')
+
+const { resolveRequestedPathForIpc } = require('./hardening.cjs')
+
+function runGit(gitBin, args, cwd) {
+  return new Promise((resolve, reject) => {
+    execFile(
+      gitBin,
+      args,
+      { cwd, windowsHide: true, timeout: 30_000, maxBuffer: 8 * 1024 * 1024 },
+      (err, stdout, stderr) => {
+        if (err) {
+          err.stderr = String(stderr || '')
+          reject(err)
+
+          return
+        }
+
+        resolve(String(stdout || ''))
+      }
+    )
+  })
+}
+
+// Parse `git worktree list --porcelain`. The first record is the main worktree.
+function parseWorktrees(out) {
+  const trees = []
+  let cur = null
+
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (cur) {
+        trees.push(cur)
+      }
+
+      cur = { path: line.slice(9).trim(), branch: null, detached: false, bare: false, locked: false }
+    } else if (!cur) {
+      continue
+    } else if (line.startsWith('branch ')) {
+      cur.branch = line.slice(7).trim().replace(/^refs\/heads\//, '')
+    } else if (line === 'detached') {
+      cur.detached = true
+    } else if (line === 'bare') {
+      cur.bare = true
+    } else if (line.startsWith('locked')) {
+      cur.locked = true
+    }
+  }
+
+  if (cur) {
+    trees.push(cur)
+  }
+
+  return trees
+}
+
+async function listWorktrees(repoPath, gitBin) {
+  let resolved
+
+  try {
+    resolved = resolveRequestedPathForIpc(repoPath, { purpose: 'Worktree list' })
+  } catch {
+    return []
+  }
+
+  try {
+    const out = await runGit(gitBin, ['worktree', 'list', '--porcelain'], resolved)
+
+    return parseWorktrees(out).map((tree, index) => ({
+      path: tree.path,
+      branch: tree.branch,
+      isMain: index === 0,
+      detached: tree.detached,
+      locked: tree.locked
+    }))
+  } catch {
+    return []
+  }
+}
+
+// A git-ref-safe branch name (spaces → "-", drop forbidden chars, trim edges),
+// or "" when nothing usable remains. Mirrors the renderer's `gitRef`, so a bad
+// value can't reach `git` no matter the caller (the GUI also enforces live).
+function sanitizeBranch(name) {
+  return String(name || '')
+    .replace(/\s+/g, '-')
+    .replace(/[^\w./-]/g, '')
+    .replace(/-{2,}/g, '-')
+    .replace(/\/{2,}/g, '/')
+    .replace(/\.{2,}/g, '.')
+    .replace(/^[-./]+|[-./]+$/g, '')
+}
+
+function slugify(name) {
+  const slug = String(name || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40)
+    .replace(/-+$/g, '')
+
+  return slug || 'work'
+}
+
+// A brand-new project folder isn't a git repo — and a freshly-init'd one has no
+// commit to branch from — so `git worktree add` would fail. Make the dir a repo
+// with a root commit on the user's behalf so worktrees "just work". No-op for a
+// repo that already has commits; never touches the user's files (the seed commit
+// is `--allow-empty`), and never inits a dir that already lives inside a repo.
+async function ensureGitRepo(gitBin, dir) {
+  let needsRoot = false
+
+  try {
+    const inside = (await runGit(gitBin, ['rev-parse', '--is-inside-work-tree'], dir)).trim()
+
+    if (inside !== 'true') {
+      await runGit(gitBin, ['init'], dir)
+      needsRoot = true
+    } else {
+      // Repo exists; a worktree still needs a HEAD to branch from.
+      try {
+        await runGit(gitBin, ['rev-parse', '--verify', 'HEAD'], dir)
+      } catch {
+        needsRoot = true
+      }
+    }
+  } catch {
+    await runGit(gitBin, ['init'], dir)
+    needsRoot = true
+  }
+
+  if (needsRoot) {
+    // Inline identity so the seed commit lands even with no global git config.
+    await runGit(
+      gitBin,
+      ['-c', 'user.email=hermes@localhost', '-c', 'user.name=Hermes', 'commit', '--allow-empty', '-m', 'Initial commit'],
+      dir
+    )
+  }
+}
+
+// Resolve the repo's MAIN worktree root, so `.worktrees/` always nests under the
+// primary checkout even when called from a linked worktree.
+async function mainRoot(gitBin, cwd) {
+  const list = await listWorktrees(cwd, gitBin)
+  const main = list.find(tree => tree.isMain)
+
+  return main ? main.path : cwd
+}
+
+function uniqueDir(base) {
+  let dir = base
+  let n = 1
+
+  while (fs.existsSync(dir)) {
+    n += 1
+    dir = `${base}-${n}`
+  }
+
+  return dir
+}
+
+async function addWorktree(repoPath, options, gitBin) {
+  const resolved = resolveRequestedPathForIpc(repoPath, { purpose: 'Worktree add' })
+  // A new project's folder may not be a git repo yet — init it (with a root
+  // commit) so the worktree has something to branch from.
+  await ensureGitRepo(gitBin, resolved)
+  const root = await mainRoot(gitBin, resolved)
+  const opts = options || {}
+  const slug = slugify(opts.name || `work-${Date.now().toString(36)}`)
+  const branch = sanitizeBranch(opts.branch) || `hermes/${slug}`
+  const dir = uniqueDir(path.join(root, '.worktrees', slug))
+
+  const args = ['worktree', 'add', '-b', branch, dir]
+
+  if (opts.base) {
+    args.push(String(opts.base))
+  }
+
+  try {
+    await runGit(gitBin, args, root)
+  } catch (err) {
+    // Branch name may already exist — retry checking out the existing branch
+    // into a fresh worktree dir instead of failing the whole flow.
+    if (/already exists/i.test(err.stderr || '')) {
+      await runGit(gitBin, ['worktree', 'add', dir, branch], root)
+    } else {
+      throw err
+    }
+  }
+
+  return { path: dir, branch, repoRoot: root }
+}
+
+async function removeWorktree(repoPath, worktreePath, options, gitBin) {
+  const resolvedRepo = resolveRequestedPathForIpc(repoPath, { purpose: 'Worktree remove (repo)' })
+  const resolvedTree = resolveRequestedPathForIpc(worktreePath, { purpose: 'Worktree remove (tree)' })
+  const root = await mainRoot(gitBin, resolvedRepo)
+  const args = ['worktree', 'remove']
+
+  if (options && options.force) {
+    args.push('--force')
+  }
+
+  args.push(resolvedTree)
+  await runGit(gitBin, args, root)
+
+  return { removed: resolvedTree }
+}
+
+module.exports = {
+  addWorktree,
+  ensureGitRepo,
+  listWorktrees,
+  parseWorktrees,
+  removeWorktree,
+  sanitizeBranch
+}

apps/desktop/electron/git-worktree-ops.test.cjs

@@ -0,0 +1,72 @@
+'use strict'
+
+const assert = require('node:assert/strict')
+const { execFileSync } = require('node:child_process')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const test = require('node:test')
+
+const { ensureGitRepo, parseWorktrees, sanitizeBranch } = require('./git-worktree-ops.cjs')
+
+test('sanitizeBranch: spaces → hyphens, forbidden chars dropped, edges trimmed', () => {
+  assert.equal(sanitizeBranch('beach vibes'), 'beach-vibes')
+  assert.equal(sanitizeBranch('feat/cool thing'), 'feat/cool-thing')
+  assert.equal(sanitizeBranch('  wip~^:? '), 'wip')
+  assert.equal(sanitizeBranch('///'), '')
+})
+
+test('parseWorktrees: main checkout + linked worktree', () => {
+  const out = [
+    'worktree /repo',
+    'HEAD abc123',
+    'branch refs/heads/main',
+    '',
+    'worktree /repo/.worktrees/feat',
+    'HEAD def456',
+    'branch refs/heads/hermes/feat',
+    ''
+  ].join('\n')
+
+  const trees = parseWorktrees(out)
+
+  assert.equal(trees.length, 2)
+  assert.equal(trees[0].path, '/repo')
+  assert.equal(trees[0].branch, 'main')
+  assert.equal(trees[1].path, '/repo/.worktrees/feat')
+  assert.equal(trees[1].branch, 'hermes/feat')
+})
+
+test('parseWorktrees: detached + locked flags', () => {
+  const out = ['worktree /repo/wt', 'HEAD abc', 'detached', 'locked reason', ''].join('\n')
+  const trees = parseWorktrees(out)
+
+  assert.equal(trees.length, 1)
+  assert.equal(trees[0].detached, true)
+  assert.equal(trees[0].locked, true)
+  assert.equal(trees[0].branch, null)
+})
+
+test('parseWorktrees: empty input', () => {
+  assert.deepEqual(parseWorktrees(''), [])
+})
+
+test('ensureGitRepo: inits a plain dir with a root commit so worktrees branch', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-wt-'))
+  const git = (...args) => execFileSync('git', args, { cwd: dir }).toString().trim()
+
+  try {
+    await ensureGitRepo('git', dir)
+    assert.match(git('rev-parse', '--verify', 'HEAD'), /^[0-9a-f]{7,}$/)
+
+    // The whole point: a worktree can now branch off the seeded root commit.
+    execFileSync('git', ['worktree', 'add', '-b', 'wt', path.join(dir, '.worktrees', 'wt')], { cwd: dir })
+    assert.ok(fs.existsSync(path.join(dir, '.worktrees', 'wt')))
+
+    // Idempotent: an already-committed repo gets no extra commit.
+    await ensureGitRepo('git', dir)
+    assert.equal(git('rev-list', '--count', 'HEAD'), '1')
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})

apps/desktop/electron/git-worktrees.cjs

@@ -1,174 +0,0 @@
-'use strict'
-
-// Resolve git-worktree relationships for a set of session cwds, reading git's
-// on-disk metadata directly (no `git` spawn per path):
-//
-//   - A normal checkout has a `.git` DIRECTORY at its root → it's the main
-//     worktree; its repo root IS that directory's parent.
-//   - A linked worktree has a `.git` FILE: `gitdir: <repo>/.git/worktrees/<name>`.
-//     That admin dir's `commondir` points back at the shared `<repo>/.git`, whose
-//     parent is the main repo root.
-//
-// Grouping by repoRoot therefore clusters a repo's main checkout with all of its
-// linked worktrees, regardless of how the worktree directories are named. The
-// branch (read from the worktree's own HEAD) gives each worktree a meaningful
-// label.
-
-const fs = require('node:fs')
-const path = require('node:path')
-const { resolveRequestedPathForIpc } = require('./hardening.cjs')
-
-// Walk up from `start` to the nearest ancestor that carries a `.git` entry
-// (file for a linked worktree, dir for the main checkout). Capped so a stray
-// path can't loop forever.
-function findGitHost(start, fsImpl) {
-  let dir = start
-
-  for (let i = 0; i < 64; i += 1) {
-    const dotgit = path.join(dir, '.git')
-
-    try {
-      if (fsImpl.existsSync(dotgit)) {
-        return dir
-      }
-    } catch {
-      return null
-    }
-
-    const parent = path.dirname(dir)
-
-    if (parent === dir) {
-      return null
-    }
-
-    dir = parent
-  }
-
-  return null
-}
-
-function readBranch(gitDir, fsImpl) {
-  try {
-    const head = fsImpl.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim()
-    const ref = head.match(/^ref:\s*refs\/heads\/(.+)$/)
-
-    if (ref) {
-      return ref[1]
-    }
-
-    // Detached HEAD: surface a short sha so the worktree still gets a label.
-    return /^[0-9a-f]{7,40}$/i.test(head) ? head.slice(0, 8) : null
-  } catch {
-    return null
-  }
-}
-
-// Given the directory that owns the `.git` entry, resolve its worktree identity.
-function resolveFromHost(host, fsImpl) {
-  const dotgit = path.join(host, '.git')
-  let stat
-
-  try {
-    stat = fsImpl.statSync(dotgit)
-  } catch {
-    return null
-  }
-
-  if (stat.isDirectory()) {
-    return {
-      repoRoot: host,
-      worktreeRoot: host,
-      isMainWorktree: true,
-      branch: readBranch(dotgit, fsImpl)
-    }
-  }
-
-  // Linked worktree: `.git` is a file pointing at the admin dir.
-  let contents
-
-  try {
-    contents = fsImpl.readFileSync(dotgit, 'utf8').trim()
-  } catch {
-    return null
-  }
-
-  const match = contents.match(/^gitdir:\s*(.+)$/m)
-
-  if (!match) {
-    return null
-  }
-
-  const adminDir = path.resolve(host, match[1].trim())
-
-  // `commondir` resolves to the shared `<repo>/.git`; fall back to walking two
-  // levels up from `<repo>/.git/worktrees/<name>` if it's missing.
-  let commonDir
-
-  try {
-    const rel = fsImpl.readFileSync(path.join(adminDir, 'commondir'), 'utf8').trim()
-    commonDir = path.resolve(adminDir, rel)
-  } catch {
-    commonDir = path.dirname(path.dirname(adminDir))
-  }
-
-  return {
-    repoRoot: path.dirname(commonDir),
-    worktreeRoot: host,
-    isMainWorktree: false,
-    branch: readBranch(adminDir, fsImpl)
-  }
-}
-
-function resolveWorktree(startPath, fsImpl = fs) {
-  let resolved
-
-  try {
-    resolved = resolveRequestedPathForIpc(startPath, { purpose: 'Worktree lookup' })
-  } catch {
-    return null
-  }
-
-  let start = resolved
-
-  try {
-    const stat = fsImpl.statSync(resolved)
-
-    if (!stat.isDirectory()) {
-      start = path.dirname(resolved)
-    }
-  } catch {
-    return null
-  }
-
-  const host = findGitHost(start, fsImpl)
-
-  if (!host) {
-    return null
-  }
-
-  return resolveFromHost(host, fsImpl)
-}
-
-// Batch entry point for the renderer: maps each requested cwd to its worktree
-// info (or null when it isn't inside a git checkout / can't be read). Dedupes so
-// many sessions sharing a cwd cost one lookup.
-async function worktreesForIpc(cwds, options = {}) {
-  const fsImpl = options.fs || fs
-  const list = Array.isArray(cwds) ? cwds : []
-  const out = {}
-
-  for (const cwd of list) {
-    if (typeof cwd !== 'string' || !cwd.trim() || cwd in out) {
-      continue
-    }
-
-    out[cwd] = resolveWorktree(cwd, fsImpl)
-  }
-
-  return out
-}
-
-module.exports = {
-  resolveWorktree,
-  worktreesForIpc
-}

apps/desktop/electron/main.cjs

@@ -28,6 +28,7 @@ const { detectRemoteDisplay, isWindowsBinaryPathInWsl, isWslEnvironment } = requ
 const { runBootstrap } = require('./bootstrap-runner.cjs')
 const {
   buildSessionWindowUrl,
+  chatWindowWebPreferences,
   createSessionWindowRegistry,
   SESSION_WINDOW_MIN_HEIGHT,
   SESSION_WINDOW_MIN_WIDTH
@@ -42,8 +43,10 @@ const { buildDesktopBackendEnv, normalizeHermesHomeRoot } = require('./backend-e
 const { readWindowsUserEnvVar } = require('./windows-user-env.cjs')
 const { readDirForIpc } = require('./fs-read-dir.cjs')
 const { gitRootForIpc } = require('./git-root.cjs')
-const { worktreesForIpc } = require('./git-worktrees.cjs')
+const { addWorktree, listWorktrees, removeWorktree } = require('./git-worktree-ops.cjs')
+const { scanGitRepos } = require('./git-repo-scan.cjs')
 const { OFFICIAL_REPO_HTTPS_URL, isOfficialSshRemote } = require('./update-remote.cjs')
+const { runRebuildWithRetry } = require('./update-rebuild.cjs')
 const {
   buildPosixCleanupScript,
   buildWindowsCleanupScript,
@@ -2008,10 +2011,14 @@ async function applyUpdatesPosixInApp() {
   }
 
   emitUpdateProgress({ stage: 'rebuild', message: 'Rebuilding the desktop app…', percent: 60 })
-  const rebuilt = await runStreamedUpdate(hermes, ['desktop', '--build-only'], {
-    cwd: updateRoot,
-    env,
-    stage: 'rebuild'
+  // Retry-once: a first rebuild can fail on a still-settling tree or a
+  // self-healed (network-blocked) Electron download; a second run builds clean
+  // off the healed dist so we reach the swap+relaunch below instead of bailing.
+  const rebuilt = await runRebuildWithRetry(attempt => {
+    if (attempt > 0) {
+      emitUpdateProgress({ stage: 'rebuild', message: 'Retrying the desktop rebuild…', percent: 60 })
+    }
+    return runStreamedUpdate(hermes, ['desktop', '--build-only'], { cwd: updateRoot, env, stage: 'rebuild' })
   })
   if (rebuilt.code !== 0) {
     emitUpdateProgress({
@@ -5106,14 +5113,7 @@ function spawnSecondaryWindow({ sessionId, watch, newSession } = {}) {
     // themes/context.tsx, so the window appears already themed.
     show: false,
     backgroundColor: getWindowBackgroundColor(),
-    webPreferences: {
-      preload: path.join(__dirname, 'preload.cjs'),
-      contextIsolation: true,
-      webviewTag: true,
-      sandbox: true,
-      nodeIntegration: false,
-      devTools: true
-    }
+    webPreferences: chatWindowWebPreferences(path.join(__dirname, 'preload.cjs'))
   })
 
   if (IS_MAC) {
@@ -5180,23 +5180,11 @@ function createWindow() {
     // material before the renderer paints the app theme. See createSessionWindow.
     show: false,
     backgroundColor: getWindowBackgroundColor(),
-    webPreferences: {
-      preload: path.join(__dirname, 'preload.cjs'),
-      contextIsolation: true,
-      webviewTag: true,
-      sandbox: true,
-      nodeIntegration: false,
-      devTools: true,
-      // Keep timers + requestAnimationFrame running at full speed when the
-      // window is blurred/occluded. The chat transcript streams to the screen
-      // through a requestAnimationFrame-gated flush (useSessionStateCache),
-      // so with Chromium's default background throttling the live answer
-      // stalls whenever this window isn't focused (e.g. you switch to your
-      // editor mid-turn, or open detached devtools) and only appears once you
-      // refocus or refresh. A streaming chat app must render in the
-      // background, so opt out — matching the secondary windows above.
-      backgroundThrottling: false
-    }
+    // Shared with the secondary session windows (chatWindowWebPreferences) so
+    // both keep `backgroundThrottling: false` — the chat transcript streams via
+    // a requestAnimationFrame-gated flush that Chromium pauses for blurred
+    // windows, stalling the live answer until refocus. See session-windows.cjs.
+    webPreferences: chatWindowWebPreferences(path.join(__dirname, 'preload.cjs'))
   })
 
   if (IS_MAC) {
@@ -6052,7 +6040,46 @@ ipcMain.handle('hermes:fs:readDir', async (_event, dirPath) => readDirForIpc(dir
 
 ipcMain.handle('hermes:fs:gitRoot', async (_event, startPath) => gitRootForIpc(startPath))
 
-ipcMain.handle('hermes:fs:worktrees', async (_event, cwds) => worktreesForIpc(cwds))
+// Reveal a path in the OS file manager (Finder / Explorer / Files).
+ipcMain.handle('hermes:fs:reveal', async (_event, targetPath) => {
+  const target = String(targetPath || '').trim()
+
+  if (!target) {
+    return false
+  }
+
+  try {
+    shell.showItemInFolder(target)
+
+    return true
+  } catch {
+    return false
+  }
+})
+
+// Git-driven worktree management ("Start work" flow). Errors surface to the
+// renderer as rejected promises so it can toast a friendly message.
+ipcMain.handle('hermes:git:worktreeList', async (_event, repoPath) =>
+  listWorktrees(repoPath, resolveGitBinary())
+)
+
+ipcMain.handle('hermes:git:worktreeAdd', async (_event, repoPath, options) =>
+  addWorktree(repoPath, options || {}, resolveGitBinary())
+)
+
+ipcMain.handle('hermes:git:worktreeRemove', async (_event, repoPath, worktreePath, options) =>
+  removeWorktree(repoPath, worktreePath, options || {}, resolveGitBinary())
+)
+
+// Repo-first project discovery: scan bounded roots for git repos (pure fs walk,
+// no native addon). Never throws to the renderer — failures yield an empty list.
+ipcMain.handle('hermes:git:scanRepos', async (_event, roots, options) => {
+  try {
+    return await scanGitRepos(roots || [], options || {})
+  } catch {
+    return []
+  }
+})
 
 ipcMain.handle('hermes:terminal:start', async (event, payload = {}) => {
   if (!nodePty) {
@@ -6564,6 +6591,12 @@ app.on('before-quit', () => {
   flushDesktopLogBufferSync()
   closePreviewWatchers()
 
+  // Kill open PTYs before environment teardown to avoid the node-pty#904
+  // ThreadSafeFunction SIGABRT race.
+  for (const id of [...terminalSessions.keys()]) {
+    disposeTerminalSession(id)
+  }
+
   if (hermesProcess && !hermesProcess.killed) {
     hermesProcess.kill('SIGTERM')
   }

apps/desktop/electron/preload.cjs

@@ -55,7 +55,14 @@ contextBridge.exposeInMainWorld('hermesDesktop', {
   getRecentLogs: () => ipcRenderer.invoke('hermes:logs:recent'),
   readDir: dirPath => ipcRenderer.invoke('hermes:fs:readDir', dirPath),
   gitRoot: startPath => ipcRenderer.invoke('hermes:fs:gitRoot', startPath),
-  worktrees: cwds => ipcRenderer.invoke('hermes:fs:worktrees', cwds),
+  revealPath: targetPath => ipcRenderer.invoke('hermes:fs:reveal', targetPath),
+  git: {
+    worktreeList: repoPath => ipcRenderer.invoke('hermes:git:worktreeList', repoPath),
+    worktreeAdd: (repoPath, options) => ipcRenderer.invoke('hermes:git:worktreeAdd', repoPath, options),
+    worktreeRemove: (repoPath, worktreePath, options) =>
+      ipcRenderer.invoke('hermes:git:worktreeRemove', repoPath, worktreePath, options),
+    scanRepos: (roots, options) => ipcRenderer.invoke('hermes:git:scanRepos', roots, options)
+  },
   terminal: {
     dispose: id => ipcRenderer.invoke('hermes:terminal:dispose', id),
     resize: (id, size) => ipcRenderer.invoke('hermes:terminal:resize', id, size),

apps/desktop/electron/session-windows.cjs

@@ -10,6 +10,29 @@ const { pathToFileURL } = require('node:url')
 const SESSION_WINDOW_MIN_WIDTH = 420
 const SESSION_WINDOW_MIN_HEIGHT = 620
 
+// Shared webPreferences for every window that renders the chat transcript — the
+// primary window AND the secondary session windows. Keeping it in one place is
+// the whole point: the two BrowserWindow definitions in main.cjs used to be
+// hand-copied, and the secondary windows silently lost `backgroundThrottling:
+// false`, so a streamed answer stalled until the window regained focus.
+//
+// `backgroundThrottling: false` is load-bearing: the transcript streams to the
+// screen through a requestAnimationFrame-gated flush, which Chromium pauses for
+// blurred/occluded windows. A streaming chat app must keep painting in the
+// background, so every chat window opts out. The preload path is injected
+// because it depends on the Electron entry's __dirname.
+function chatWindowWebPreferences(preloadPath) {
+  return {
+    preload: preloadPath,
+    contextIsolation: true,
+    webviewTag: true,
+    sandbox: true,
+    nodeIntegration: false,
+    devTools: true,
+    backgroundThrottling: false
+  }
+}
+
 // Build the renderer URL for a secondary window. The renderer uses a
 // HashRouter, so the session route lives after the '#'. The `?win=secondary`
 // flag MUST sit in the query string BEFORE the '#': anything after the '#' is
@@ -94,6 +117,7 @@ function createSessionWindowRegistry() {
 
 module.exports = {
   buildSessionWindowUrl,
+  chatWindowWebPreferences,
   createSessionWindowRegistry,
   SESSION_WINDOW_MIN_HEIGHT,
   SESSION_WINDOW_MIN_WIDTH

apps/desktop/electron/session-windows.test.cjs

@@ -1,7 +1,11 @@
 const assert = require('node:assert/strict')
 const test = require('node:test')
 
-const { buildSessionWindowUrl, createSessionWindowRegistry } = require('./session-windows.cjs')
+const {
+  buildSessionWindowUrl,
+  chatWindowWebPreferences,
+  createSessionWindowRegistry
+} = require('./session-windows.cjs')
 
 // A minimal fake BrowserWindow: tracks listeners + destroyed state and lets a
 // test fire the 'closed' event, mirroring the slice of the Electron API the
@@ -175,3 +179,21 @@ test('registry trims the session id before keying', () => {
 
   assert.equal(registry.has('s1'), true)
 })
+
+test('chatWindowWebPreferences disables background throttling so streaming paints while blurred', () => {
+  // Regression: secondary session windows used to omit this flag, so a streamed
+  // answer stalled until the window regained focus (Chromium pauses the
+  // requestAnimationFrame-gated transcript flush for backgrounded windows).
+  const prefs = chatWindowWebPreferences('/tmp/preload.cjs')
+
+  assert.equal(prefs.backgroundThrottling, false)
+})
+
+test('chatWindowWebPreferences passes the preload path through and keeps the hardened defaults', () => {
+  const prefs = chatWindowWebPreferences('/some/preload.cjs')
+
+  assert.equal(prefs.preload, '/some/preload.cjs')
+  assert.equal(prefs.contextIsolation, true)
+  assert.equal(prefs.sandbox, true)
+  assert.equal(prefs.nodeIntegration, false)
+})

apps/desktop/electron/update-rebuild.cjs

@@ -0,0 +1,29 @@
+'use strict'
+
+/**
+ * Retry-once policy for the desktop `--build-only` rebuild during self-update.
+ *
+ * The first rebuild can return nonzero on a still-settling post-update tree or a
+ * network-blocked Electron fetch that the installer's self-heal repaired mid-run.
+ * A second attempt then builds clean off the healed dist (the content-hash stamp
+ * makes it a near-no-op when the first actually succeeded). Without the retry the
+ * updater bails before the relaunch step — the app updates but doesn't restart.
+ */
+
+function shouldRetryRebuild(code) {
+  return code !== 0
+}
+
+/**
+ * Run `rebuild()` (async, resolves `{ code, ... }`), retrying once on failure.
+ * Returns the final result.
+ */
+async function runRebuildWithRetry(rebuild) {
+  let result = await rebuild(0)
+  if (shouldRetryRebuild(result.code)) {
+    result = await rebuild(1)
+  }
+  return result
+}
+
+module.exports = { shouldRetryRebuild, runRebuildWithRetry }

apps/desktop/electron/update-rebuild.test.cjs

@@ -0,0 +1,55 @@
+/**
+ * Tests for electron/update-rebuild.cjs — the retry-once policy for the desktop
+ * `--build-only` rebuild during self-update.
+ *
+ * Run with: node --test electron/update-rebuild.test.cjs
+ * (Wired into npm test:desktop:platforms in package.json.)
+ *
+ * Why this matters: a first rebuild can return nonzero on a still-settling tree
+ * or a self-healed (network-blocked) Electron download. Without a second attempt
+ * the updater bails before the relaunch step — the app updates but never restarts
+ * (the field report behind this fix). The retry must fire on failure, not on
+ * success, and must run at most twice.
+ */
+
+const test = require('node:test')
+const assert = require('node:assert/strict')
+
+const { shouldRetryRebuild, runRebuildWithRetry } = require('./update-rebuild.cjs')
+
+test('shouldRetryRebuild retries only on a non-success exit', () => {
+  assert.equal(shouldRetryRebuild(0), false)
+  assert.equal(shouldRetryRebuild(1), true)
+  assert.equal(shouldRetryRebuild(null), true)
+})
+
+test('a clean first rebuild runs once and does not retry', async () => {
+  const codes = []
+  const result = await runRebuildWithRetry(attempt => {
+    codes.push(attempt)
+    return Promise.resolve({ code: 0 })
+  })
+  assert.deepEqual(codes, [0])
+  assert.equal(result.code, 0)
+})
+
+test('a failed first rebuild retries once and succeeds', async () => {
+  const codes = []
+  const result = await runRebuildWithRetry(attempt => {
+    codes.push(attempt)
+    return Promise.resolve({ code: attempt === 0 ? 1 : 0 })
+  })
+  assert.deepEqual(codes, [0, 1])
+  assert.equal(result.code, 0)
+})
+
+test('a rebuild that keeps failing runs at most twice and reports the failure', async () => {
+  const codes = []
+  const result = await runRebuildWithRetry(attempt => {
+    codes.push(attempt)
+    return Promise.resolve({ code: 1, error: 'rebuild-failed' })
+  })
+  assert.deepEqual(codes, [0, 1])
+  assert.equal(result.code, 1)
+  assert.equal(result.error, 'rebuild-failed')
+})

apps/desktop/package.json

@@ -21,7 +21,7 @@
     "build": "node scripts/assert-root-install.cjs && node scripts/write-build-stamp.cjs && node scripts/stage-native-deps.cjs && tsc -b && vite build && npm run postbuild",
     "postbuild": "node scripts/assert-dist-built.cjs",
     "prebuilder": "node scripts/patch-electron-builder-mac-binary.cjs",
-    "builder": "cross-env NODE_OPTIONS=--max-old-space-size=16384 electron-builder",
+    "builder": "cross-env NODE_OPTIONS=--max-old-space-size=16384 node scripts/run-electron-builder.cjs",
     "pack": "npm run build && npm run builder -- --dir",
     "dist": "npm run build && npm run builder",
     "dist:mac": "npm run build && npm run builder -- --mac",
@@ -37,7 +37,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-env.test.cjs electron/backend-probes.test.cjs electron/bootstrap-runner.test.cjs electron/connection-config.test.cjs electron/dashboard-token.test.cjs electron/gateway-ws-probe.test.cjs electron/oauth-net-request.test.cjs electron/desktop-uninstall.test.cjs electron/session-windows.test.cjs electron/workspace-cwd.test.cjs electron/fs-read-dir.test.cjs electron/git-root.test.cjs electron/windows-child-process.test.cjs electron/update-remote.test.cjs electron/windows-user-env.test.cjs",
+    "test:desktop:platforms": "node --test electron/bootstrap-platform.test.cjs electron/hardening.test.cjs electron/backend-env.test.cjs electron/backend-probes.test.cjs electron/bootstrap-runner.test.cjs electron/connection-config.test.cjs electron/dashboard-token.test.cjs electron/gateway-ws-probe.test.cjs electron/oauth-net-request.test.cjs electron/desktop-uninstall.test.cjs electron/session-windows.test.cjs electron/workspace-cwd.test.cjs electron/fs-read-dir.test.cjs electron/git-root.test.cjs electron/windows-child-process.test.cjs electron/update-remote.test.cjs electron/update-rebuild.test.cjs electron/windows-user-env.test.cjs",
     "typecheck": "tsc -p . --noEmit",
     "lint": "eslint src/ electron/",
     "lint:fix": "eslint src/ electron/ --fix",
@@ -55,7 +55,7 @@
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@hermes/shared": "file:../shared",
-    "@icons-pack/react-simple-icons": "^13.13.0",
+    "@icons-pack/react-simple-icons": "=13.11.1",
     "@nanostores/react": "^1.1.0",
     "@nous-research/ui": "^0.13.0",
     "@radix-ui/react-slot": "^1.2.4",
@@ -117,7 +117,7 @@
     "@vitejs/plugin-react": "^6.0.1",
     "concurrently": "^10.0.3",
     "cross-env": "^10.1.0",
-    "electron": "^40.9.3",
+    "electron": "40.10.2",
     "electron-builder": "^26.8.1",
     "eslint": "^9.39.4",
     "eslint-plugin-perfectionist": "^5.9.0",
@@ -134,8 +134,7 @@
     "wait-on": "^9.0.5"
   },
   "build": {
-    "electronVersion": "40.9.3",
-    "electronDist": "../../node_modules/electron/dist",
+    "electronVersion": "40.10.2",
     "appId": "com.nousresearch.hermes",
     "productName": "Hermes",
     "executableName": "Hermes",

apps/desktop/scripts/patch-electron-builder-mac-binary.cjs

@@ -24,6 +24,11 @@ const replacement = `    // ${marker}: electron-builder 26.8.x can sometimes cop
     if (!fs.existsSync(bundledElectronBinary)) {
         const candidates = [
             path.join(packager.info.framework.distMacOsAppName, "Contents", "MacOS", electronBranding.productName),
+            // npm may nest the workspace-only electron devDep under
+            // apps/desktop/node_modules (process.cwd() during pack), or hoist
+            // it to the repo root. Try the workspace-local install first, then
+            // the root hoist, so the fallback works under either layout.
+            path.join(process.cwd(), "node_modules", "electron", "dist", "Electron.app", "Contents", "MacOS", electronBranding.productName),
             path.join(process.cwd(), "..", "..", "node_modules", "electron", "dist", "Electron.app", "Contents", "MacOS", electronBranding.productName),
         ];
         const sourceBinary = candidates.find(candidate => fs.existsSync(candidate));

apps/desktop/scripts/run-electron-builder.cjs

@@ -0,0 +1,57 @@
+"use strict"
+
+// Resolve electronDist at runtime (#38673, #47917): electron-builder 26.8.x can
+// re-unpack a broken Electron.app; reusing the installed dist dodges that.
+// npm workspace hoisting is non-deterministic — require.resolve finds electron
+// wherever it landed. Dist present → -c.electronDist=<abs>/dist; absent → let
+// electron-builder fetch via @electron/get (electronVersion + ELECTRON_MIRROR).
+
+const fs = require("node:fs")
+const path = require("node:path")
+const { spawnSync } = require("node:child_process")
+
+function electronDistDir() {
+  try {
+    return path.join(path.dirname(require.resolve("electron/package.json")), "dist")
+  } catch {
+    return null
+  }
+}
+
+function distBinary(dist) {
+  if (process.platform === "darwin") {
+    return path.join(dist, "Electron.app", "Contents", "MacOS", "Electron")
+  }
+  if (process.platform === "win32") {
+    return path.join(dist, "electron.exe")
+  }
+  return path.join(dist, "electron")
+}
+
+function electronBuilderCli() {
+  const pkgJson = require.resolve("electron-builder/package.json")
+  const bin = require(pkgJson).bin
+  const rel = typeof bin === "string" ? bin : bin["electron-builder"]
+  return path.join(path.dirname(pkgJson), rel)
+}
+
+const dist = electronDistDir()
+const args = []
+if (dist && fs.existsSync(distBinary(dist))) {
+  args.push(`-c.electronDist=${dist}`)
+} else {
+  console.warn(
+    "[run-electron-builder] no local electron dist; electron-builder will fetch " +
+      "via @electron/get (electronVersion + ELECTRON_MIRROR)."
+  )
+}
+args.push(...process.argv.slice(2))
+
+const result = spawnSync(process.execPath, [electronBuilderCli(), ...args], {
+  stdio: "inherit",
+})
+if (result.error) {
+  console.error(`[run-electron-builder] spawn failed: ${result.error.message}`)
+  process.exit(1)
+}
+process.exit(result.status == null ? 1 : result.status)

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

@@ -9,6 +9,7 @@ import { formatCombo } from '@/lib/keybinds/combo'
 import { cn } from '@/lib/utils'
 
 import type { ConversationStatus } from './hooks/use-voice-conversation'
+import { ModelPill } from './model-pill'
 import type { ChatBarState, VoiceStatus } from './types'
 
 export const ICON_BTN = 'size-(--composer-control-size) shrink-0 rounded-md'
@@ -66,6 +67,7 @@ export function ComposerControls({
   const c = t.composer
   const steerCombo = formatCombo('mod+enter')
   const steerLabel = `${c.steer} (${steerCombo})`
+
   const steerTip = (
     <span className="inline-flex items-center gap-1.5">
       {c.steer}
@@ -81,8 +83,10 @@ export function ComposerControls({
 
   return (
     <div className="ml-auto flex shrink-0 items-center gap-(--composer-control-gap)">
-      <DictationButton disabled={disabled} onToggle={onDictate} state={state.voice} status={voiceStatus} />
-      {canSteer && (
+      <ModelPill disabled={disabled} model={state.model} />
+      {/* While the agent runs and the user is typing, steer takes over the mic's
+          slot rather than crowding the row with an extra button. */}
+      {canSteer ? (
         <Tip label={steerTip}>
           <Button
             aria-label={steerLabel}
@@ -96,6 +100,8 @@ export function ComposerControls({
             <SteeringWheel size={16} />
           </Button>
         </Tip>
+      ) : (
+        <DictationButton disabled={disabled} onToggle={onDictate} state={state.voice} status={voiceStatus} />
       )}
       {showVoicePrimary ? (
         <Tip label={c.startVoice}>

apps/desktop/src/app/chat/composer/model-pill.tsx

@@ -0,0 +1,86 @@
+import { useStore } from '@nanostores/react'
+import { useState } from 'react'
+
+import { ModelMenuCloseContext } from '@/app/shell/model-menu-panel'
+import { Button } from '@/components/ui/button'
+import { DropdownMenu, DropdownMenuContent, DropdownMenuTrigger } from '@/components/ui/dropdown-menu'
+import { GlyphSpinner } from '@/components/ui/glyph-spinner'
+import { useI18n } from '@/i18n'
+import { ChevronDown } from '@/lib/icons'
+import { formatModelStatusLabel } from '@/lib/model-status-label'
+import { cn } from '@/lib/utils'
+import {
+  $currentFastMode,
+  $currentModel,
+  $currentProvider,
+  $currentReasoningEffort,
+  setModelPickerOpen
+} from '@/store/session'
+
+import type { ChatBarState } from './types'
+
+const PILL = cn(
+  'h-(--composer-control-size) max-w-40 shrink-0 gap-1 rounded-md px-2 text-xs font-normal',
+  'text-(--ui-text-tertiary) hover:bg-(--chrome-action-hover) hover:text-foreground'
+)
+
+/**
+ * Composer model selector — the relocated status-bar pill. Reuses the live
+ * `model.options` dropdown (`modelMenuContent`) verbatim; falls back to the
+ * full picker when the gateway is closed and no live menu exists.
+ */
+export function ModelPill({ disabled, model }: { disabled: boolean; model: ChatBarState['model'] }) {
+  const copy = useI18n().t.shell.statusbar
+  const currentModel = useStore($currentModel)
+  const currentProvider = useStore($currentProvider)
+  const fastMode = useStore($currentFastMode)
+  const reasoningEffort = useStore($currentReasoningEffort)
+  const [open, setOpen] = useState(false)
+
+  // The model resolves a beat after the gateway/session comes up. Rather than
+  // flash a literal "No model", show a quiet loader (inherits the pill text
+  // color at half opacity) until a model lands.
+  const label = (
+    <>
+      {currentModel.trim() ? (
+        <span className="truncate">{formatModelStatusLabel(currentModel, { fastMode, reasoningEffort })}</span>
+      ) : (
+        <GlyphSpinner className="opacity-50" spinner="braille" />
+      )}
+      <ChevronDown className="size-2.5 shrink-0 opacity-50" />
+    </>
+  )
+
+  const title = currentProvider ? copy.modelTitle(currentProvider, currentModel || copy.modelNone) : copy.switchModel
+
+  if (!model.modelMenuContent) {
+    return (
+      <Button
+        aria-label={copy.openModelPicker}
+        className={PILL}
+        disabled={disabled}
+        onClick={() => setModelPickerOpen(true)}
+        title={copy.openModelPicker}
+        type="button"
+        variant="ghost"
+      >
+        {label}
+      </Button>
+    )
+  }
+
+  return (
+    <DropdownMenu onOpenChange={setOpen} open={open}>
+      <DropdownMenuTrigger asChild>
+        <Button aria-label={title} className={PILL} disabled={disabled} title={title} type="button" variant="ghost">
+          {label}
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-64 p-0" side="top" sideOffset={8}>
+        <ModelMenuCloseContext.Provider value={() => setOpen(false)}>
+          {model.modelMenuContent}
+        </ModelMenuCloseContext.Provider>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}

apps/desktop/src/app/chat/composer/types.ts

@@ -1,3 +1,5 @@
+import type { ReactNode } from 'react'
+
 import type { HermesGateway } from '@/hermes'
 import type { ComposerAttachment } from '@/store/composer'
 
@@ -22,6 +24,8 @@ export interface ChatBarState {
     canSwitch: boolean
     loading?: boolean
     quickModels?: QuickModelOption[]
+    /** Reused status-bar dropdown (built with gateway + selectModel upstream). */
+    modelMenuContent?: ReactNode
   }
   tools: { enabled: boolean; label: string; suggestions?: ContextSuggestion[] }
   voice: { enabled: boolean; active: boolean }

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

@@ -15,7 +15,9 @@ import { Backdrop } from '@/components/Backdrop'
 import { PromptOverlays } from '@/components/prompt-overlays'
 import { Button } from '@/components/ui/button'
 import { Codicon } from '@/components/ui/codicon'
+import { ErrorState } from '@/components/ui/error-state'
 import { getGlobalModelOptions, type HermesGateway } from '@/hermes'
+import { useI18n } from '@/i18n'
 import type { ChatMessage } from '@/lib/chat-messages'
 import { quickModelOptions, sessionTitle, toRuntimeMessage } from '@/lib/chat-runtime'
 import { useIncrementalExternalStoreRuntime } from '@/lib/incremental-external-store-runtime'
@@ -38,11 +40,12 @@ import {
   $lastVisibleMessageIsUser,
   $messages,
   $messagesEmpty,
+  $resumeExhaustedSessionId,
   $selectedStoredSessionId,
   $sessions,
   sessionPinId
 } from '@/store/session'
-import { isNewSessionWindow, isSecondaryWindow } from '@/store/windows'
+import { isSecondaryWindow } from '@/store/windows'
 import type { ModelOptionsResponse } from '@/types/hermes'
 
 import { routeSessionId } from '../routes'
@@ -62,6 +65,7 @@ import { threadLoadingState } from './thread-loading'
 
 interface ChatViewProps extends Omit<React.ComponentProps<'div'>, 'onSubmit'> {
   gateway: HermesGateway | null
+  modelMenuContent?: React.ReactNode
   onToggleSelectedPin: () => void
   onDeleteSelectedSession: () => void
   onCancel: () => Promise<void> | void
@@ -85,7 +89,9 @@ interface ChatViewProps extends Omit<React.ComponentProps<'div'>, 'onSubmit'> {
   onEdit: (message: AppendMessage) => Promise<void>
   onReload: (parentId: string | null) => Promise<void>
   onRestoreToMessage?: (messageId: string) => Promise<void>
+  onRetryResume: (sessionId: string) => void
   onTranscribeAudio?: (audio: Blob) => Promise<string>
+  onDismissError?: (messageId: string) => void
 }
 
 interface ChatHeaderProps {
@@ -120,10 +126,10 @@ function ChatHeader({
       ? 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 (isNewSessionWindow() || (!selectedSessionId && !activeSessionId && !isRoutedSessionView)) {
+  // Secondary windows (new-session scratch, subagent watch, cmd-click pop-out)
+  // are compact side panels — they drop the session-actions header + border
+  // entirely. A brand-new draft has nothing to pin/delete/rename either.
+  if (isSecondaryWindow() || (!selectedSessionId && !activeSessionId && !isRoutedSessionView)) {
     return null
   }
 
@@ -250,6 +256,7 @@ function ChatRuntimeBoundary({
 export function ChatView({
   className,
   gateway,
+  modelMenuContent,
   onToggleSelectedPin,
   onDeleteSelectedSession,
   onCancel,
@@ -270,9 +277,12 @@ export function ChatView({
   onEdit,
   onReload,
   onRestoreToMessage,
-  onTranscribeAudio
+  onRetryResume,
+  onTranscribeAudio,
+  onDismissError
 }: ChatViewProps) {
   const location = useLocation()
+  const { t } = useI18n()
   const activeSessionId = useStore($activeSessionId)
   const awaitingResponse = useStore($awaitingResponse)
   const busy = useStore($busy)
@@ -294,6 +304,7 @@ export function ChatView({
   const messagesEmpty = useStore($messagesEmpty)
   const lastVisibleIsUser = useStore($lastVisibleMessageIsUser)
   const selectedSessionId = useStore($selectedStoredSessionId)
+  const resumeExhaustedSessionId = useStore($resumeExhaustedSessionId)
   const routedSessionId = routeSessionId(location.pathname)
   const isRoutedSessionView = Boolean(routedSessionId)
 
@@ -313,9 +324,21 @@ export function ChatView({
   // session exists — even if it has zero messages (a brand-new routed
   // session). The flicker where `busy` flips true briefly during hydrate
   // is handled by `threadLoadingState`'s last-visible-user gate.
-  const loadingSession = isRoutedSessionView && (routeSessionMismatch || (messagesEmpty && !activeSessionId))
+  //
+  // resumeExhausted: the bounded auto-retry in use-route-resume gave up on this
+  // routed session (gateway RPC + REST fallback failed through every attempt).
+  // Suppress the loader and show an explicit error + manual Retry instead of
+  // spinning forever. Gated on the route matching so a stale latch from another
+  // session can't blank the current one.
+  const resumeExhausted = isRoutedSessionView && resumeExhaustedSessionId === routedSessionId
+
+  const loadingSession =
+    !resumeExhausted && isRoutedSessionView && (routeSessionMismatch || (messagesEmpty && !activeSessionId))
+
   const threadLoading = threadLoadingState(loadingSession, busy, awaitingResponse, lastVisibleIsUser)
-  const showChatBar = !loadingSession
+  // Hide the composer in the exhausted error state too: there's no live runtime
+  // to send to until a retry rebinds one.
+  const showChatBar = !loadingSession && !resumeExhausted
   const threadKey = selectedSessionId || activeSessionId || (isRoutedSessionView ? location.pathname : 'new')
 
   const modelOptionsQuery = useQuery<ModelOptionsResponse>({
@@ -346,6 +369,7 @@ export function ChatView({
         provider: currentProvider,
         canSwitch: gatewayOpen,
         loading: !gatewayOpen || (!currentModel && !currentProvider),
+        modelMenuContent,
         quickModels
       },
       tools: {
@@ -358,7 +382,7 @@ export function ChatView({
         active: false
       }
     }),
-    [contextSuggestions, currentModel, currentProvider, gatewayOpen, quickModels]
+    [contextSuggestions, currentModel, currentProvider, gatewayOpen, modelMenuContent, quickModels]
   )
 
   // Drop files anywhere in the conversation area, not just on the composer
@@ -429,6 +453,7 @@ export function ChatView({
             loading={threadLoading}
             onBranchInNewChat={onBranchInNewChat}
             onCancel={onCancel}
+            onDismissError={onDismissError}
             onRestoreToMessage={onRestoreToMessage}
             sessionId={activeSessionId}
             sessionKey={threadKey}
@@ -462,6 +487,21 @@ export function ChatView({
             </Suspense>
           )}
         </ChatRuntimeBoundary>
+        {resumeExhausted && routedSessionId && (
+          <div className="absolute inset-0 z-10 grid place-items-center bg-(--ui-chat-surface-background) px-8 py-10">
+            <ErrorState
+              className="max-w-sm"
+              description={t.desktop.resumeStrandedBody}
+              title={t.desktop.resumeStrandedTitle}
+            >
+              <div className="grid justify-items-center">
+                <Button onClick={() => onRetryResume(routedSessionId)} size="sm" variant="outline">
+                  {t.desktop.resumeRetry}
+                </Button>
+              </div>
+            </ErrorState>
+          </div>
+        )}
         {showChatBar && <ScrollToBottomButton />}
         <ChatDropOverlay kind={dragKind} />
         <ChatSwapOverlay profile={gatewaySwapTarget} />

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

@@ -7,6 +7,7 @@ import { Tip } from '@/components/ui/tooltip'
 import { translateNow, useI18n } from '@/i18n'
 import { cn } from '@/lib/utils'
 import {
+  $panesFlipped,
   $rightRailActiveTabId,
   RIGHT_RAIL_PREVIEW_TAB_ID,
   type RightRailTabId,
@@ -56,6 +57,7 @@ export function ChatPreviewRail({ onRestartServer, setTitlebarToolGroup }: ChatP
   const { t } = useI18n()
   const previewReloadRequest = useStore($previewReloadRequest)
   const activeTabId = useStore($rightRailActiveTabId)
+  const panesFlipped = useStore($panesFlipped)
   const filePreviewTabs = useStore($filePreviewTabs)
   const previewTarget = useStore($previewTarget)
 
@@ -82,7 +84,12 @@ export function ChatPreviewRail({ onRestartServer, setTitlebarToolGroup }: ChatP
   const isPreview = activeTab.id === RIGHT_RAIL_PREVIEW_TAB_ID
 
   return (
-    <aside className="relative flex h-full w-full min-w-0 flex-col overflow-hidden border-l border-(--ui-stroke-tertiary) bg-(--ui-editor-surface-background) text-(--ui-text-tertiary)">
+    <aside
+      className={cn(
+        'relative flex h-full w-full min-w-0 flex-col overflow-hidden border-(--ui-stroke-tertiary) bg-(--ui-editor-surface-background) text-(--ui-text-tertiary)',
+        panesFlipped ? 'border-r' : 'border-l'
+      )}
+    >
       <div className="group/rail-tabs flex h-(--titlebar-height) shrink-0 border-b border-(--ui-stroke-tertiary) bg-(--ui-sidebar-surface-background)">
         <div
           className="flex min-w-0 flex-1 overflow-x-auto overflow-y-hidden overscroll-x-contain [-ms-overflow-style:none] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"

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

@@ -0,0 +1,158 @@
+import type * as React from 'react'
+
+import { Codicon } from '@/components/ui/codicon'
+import { cn } from '@/lib/utils'
+
+// Shared, content-agnostic sidebar chrome — used by both the flat session
+// sections and the project/workspace tree, so it lives outside either to keep
+// imports one-directional (no index <-> projects cycle).
+
+/** `loaded/total` when there's more on the server, else just the loaded count. */
+export const countLabel = (loaded: number, total: number): string =>
+  total > loaded ? `${loaded}/${total}` : String(loaded)
+
+/** The muted count chip next to a section/workspace label. */
+export function SidebarCount({ children }: { children: React.ReactNode }) {
+  return <span className="text-[0.6875rem] font-medium text-(--ui-text-quaternary)">{children}</span>
+}
+
+// ── Row geometry (session row is canonical — everything composes these) ─────
+//
+// Height lives ONLY on SidebarRowShell (min-h-[1.625rem]). Inset children
+// stretch to fill the cell and center content internally — never items-center
+// on the shell grid, or short clusters (projects) float 1–2px off sessions.
+
+const rowMinH = 'min-h-[1.625rem]'
+const rowPadX = 'pl-2 pr-1'
+const rowGap = 'gap-1.5'
+const rowLead = 'grid size-3.5 shrink-0 place-items-center'
+const rowInset = cn(rowPadX, rowGap, 'flex h-full min-w-0 items-center self-stretch py-0.5')
+const rowLabel = 'min-w-0 truncate text-[0.8125rem] leading-none text-(--ui-text-secondary)'
+
+/** Codicon size in sidebar row leads — matches the file tree (`tree.tsx`). */
+export const SIDEBAR_LEAD_ICON_SIZE = '0.875rem' as const
+
+/** Vertical stack of rows (gap-px, single column). */
+export function SidebarRowStack({ className, ...props }: React.ComponentProps<'div'>) {
+  return <div className={cn('grid grid-cols-[minmax(0,1fr)] gap-px', className)} {...props} />
+}
+
+/** Nested rows (session previews, worktree bodies). */
+export function SidebarRowNest({ className, ...props }: React.ComponentProps<'div'>) {
+  return <SidebarRowStack className={cn('pb-1 pl-4', className)} {...props} />
+}
+
+/** Outer grid — sole owner of row height. */
+export function SidebarRowShell({
+  actions,
+  children,
+  className,
+  ...props
+}: React.ComponentProps<'div'> & { actions?: React.ReactNode }) {
+  return (
+    <div className={cn(rowMinH, 'grid grid-cols-[minmax(0,1fr)_auto] items-stretch rounded-md', className)} {...props}>
+      {children}
+      {actions ? <div className="flex shrink-0 items-center self-center">{actions}</div> : null}
+    </div>
+  )
+}
+
+/** Multi-control left cluster (project rows). */
+export function SidebarRowCluster({ className, ...props }: React.ComponentProps<'div'>) {
+  return <div className={cn(rowInset, className)} {...props} />
+}
+
+/** Session row main tap target. */
+export function SidebarRowBody({ className, ...props }: React.ComponentProps<'button'>) {
+  return <button className={cn(rowInset, 'bg-transparent text-left', className)} type="button" {...props} />
+}
+
+/** Tappable label — underline/truncate live on the inner span, not the button. */
+export function SidebarRowLink({
+  className,
+  labelClassName,
+  children,
+  ...props
+}: React.ComponentProps<'button'> & { labelClassName?: string }) {
+  return (
+    <button className={cn('min-w-0 shrink bg-transparent p-0 text-left', className)} type="button" {...props}>
+      <span className={cn(rowLabel, labelClassName)}>{children}</span>
+    </button>
+  )
+}
+
+/** Fixed leading column (dot, icon, drag handle). */
+export function SidebarRowLead({ className, ...props }: React.ComponentProps<'span'>) {
+  return <span className={cn(rowLead, className)} {...props} />
+}
+
+/** Standard row label typography. */
+export function SidebarRowLabel({ className, ...props }: React.ComponentProps<'span'>) {
+  return <span className={cn(rowLabel, className)} {...props} />
+}
+
+/** Dot ↔ grabber swap for dnd-kit reorder rows. */
+export function SidebarRowGrab({
+  ariaLabel,
+  children,
+  className,
+  dragging = false,
+  dragHandleProps,
+  leadClassName
+}: {
+  ariaLabel: string
+  children: React.ReactNode
+  className?: string
+  dragging?: boolean
+  dragHandleProps?: React.HTMLAttributes<HTMLElement>
+  leadClassName?: string
+}) {
+  return (
+    <SidebarRowLead
+      {...dragHandleProps}
+      aria-label={ariaLabel}
+      className={cn(
+        'group/handle relative cursor-grab touch-none overflow-hidden active:cursor-grabbing',
+        leadClassName,
+        className
+      )}
+      data-reorder-handle
+      onClick={event => event.stopPropagation()}
+    >
+      <span className="grid size-full place-items-center transition-opacity group-hover/handle:opacity-0 group-focus-within/handle:opacity-0">
+        {children}
+      </span>
+      <Codicon
+        className={cn(
+          '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"
+        size="0.75rem"
+      />
+    </SidebarRowLead>
+  )
+}
+
+/** Icon/dot slot inside SidebarRowLead — caps visual size so rows align. */
+export function SidebarRowLeadGlyph({
+  children,
+  className,
+  style
+}: {
+  children: React.ReactNode
+  className?: string
+  style?: React.CSSProperties
+}) {
+  return (
+    <span
+      className={cn(
+        'grid size-full place-items-center text-(--ui-text-tertiary) [&_.codicon]:leading-none',
+        className
+      )}
+      style={style}
+    >
+      {children}
+    </span>
+  )
+}

apps/desktop/src/app/chat/sidebar/cron-jobs-section.tsx

@@ -3,6 +3,7 @@ import { useEffect, useMemo, useState } from 'react'
 
 import { Codicon } from '@/components/ui/codicon'
 import { DisclosureCaret } from '@/components/ui/disclosure-caret'
+import { GlyphSpinner } from '@/components/ui/glyph-spinner'
 import { SidebarGroup, SidebarGroupContent } from '@/components/ui/sidebar'
 import { Tip } from '@/components/ui/tooltip'
 import { getCronJobRuns, type SessionInfo } from '@/hermes'
@@ -328,7 +329,7 @@ function CronJobSidebarRuns({ jobId, onOpenRun }: { jobId: string; onOpenRun: (s
     <div className="mb-1 ml-[1.375rem] flex flex-col gap-px">
       {runs === null ? (
         <div className="flex items-center gap-1.5 py-1 pl-1 text-[0.6875rem] text-(--ui-text-tertiary)">
-          <Codicon name="loading" size="0.75rem" spinning />
+          <GlyphSpinner ariaLabel={c.loading} className="text-[0.75rem]" />
         </div>
       ) : runs.length === 0 ? (
         <div className="py-1 pl-1 text-[0.6875rem] text-(--ui-text-tertiary)">{c.noRuns}</div>

apps/desktop/src/app/chat/sidebar/load-more-row.tsx

@@ -1,4 +1,5 @@
 import { Codicon } from '@/components/ui/codicon'
+import { GlyphSpinner } from '@/components/ui/glyph-spinner'
 import { useI18n } from '@/i18n'
 
 interface SidebarLoadMoreRowProps {
@@ -7,24 +8,22 @@ interface SidebarLoadMoreRowProps {
   loading?: boolean
 }
 
-// "Load N more" affordance shared by the recents, messaging, and cron sections.
-// The chevron sits in the same w-3.5 column the rows use for their dot, so it
-// lines up with the list above.
+// Compact "load more" affordance shared by recents, messaging, and cron. Kept
+// intentionally identical to workspace "show more" controls (ellipsis button)
+// so pagination reads as one interaction everywhere.
 export function SidebarLoadMoreRow({ step, onClick, loading = false }: SidebarLoadMoreRowProps) {
   const { t } = useI18n()
   const label = loading ? t.sidebar.loading : step > 0 ? t.sidebar.loadCount(step) : t.sidebar.loadMore
 
   return (
     <button
-      className="flex min-h-5 items-center gap-1.5 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)"
+      aria-label={label}
+      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 disabled:cursor-default disabled:opacity-60 disabled:hover:bg-transparent disabled:hover:text-(--ui-text-tertiary)"
       disabled={loading}
       onClick={onClick}
       type="button"
     >
-      <span className="grid w-3.5 shrink-0 place-items-center">
-        <Codicon className="opacity-70" name={loading ? 'loading' : 'chevron-down'} size="0.75rem" spinning={loading} />
-      </span>
-      <span>{label}</span>
+      {loading ? <GlyphSpinner ariaLabel={label} className="text-[0.75rem]" /> : <Codicon name="ellipsis" size="0.75rem" />}
     </button>
   )
 }

apps/desktop/src/app/chat/sidebar/order.ts

@@ -1,3 +1,12 @@
+/** New ids first, then ids still present in the persisted order. */
+export function reconcileFreshFirst(currentIds: string[], orderIds: string[]): string[] {
+  const current = new Set(currentIds)
+  const retained = orderIds.filter(id => current.has(id))
+  const retainedSet = new Set(retained)
+
+  return [...currentIds.filter(id => !retainedSet.has(id)), ...retained]
+}
+
 export function resolveManualSessionOrderIds(currentIds: string[], orderIds: string[], manual: boolean): string[] {
   if (!manual || !currentIds.length || !orderIds.length) {
     return []
@@ -10,8 +19,5 @@ export function resolveManualSessionOrderIds(currentIds: string[], orderIds: str
     return []
   }
 
-  const retainedSet = new Set(retained)
-  const fresh = currentIds.filter(id => !retainedSet.has(id))
-
-  return [...fresh, ...retained]
+  return reconcileFreshFirst(currentIds, orderIds)
 }

apps/desktop/src/app/chat/sidebar/profile-switcher.tsx

@@ -24,6 +24,7 @@ import { useNavigate } from 'react-router-dom'
 
 import { Button } from '@/components/ui/button'
 import { Codicon } from '@/components/ui/codicon'
+import { ColorSwatches } from '@/components/ui/color-swatches'
 import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuTrigger } from '@/components/ui/context-menu'
 import { Popover, PopoverAnchor, PopoverContent } from '@/components/ui/popover'
 import { Tip, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'
@@ -494,30 +495,14 @@ function ProfileSquare({ active, color, label, onDelete, onRecolor, onRename, on
         collisionPadding={{ bottom: 44, left: 8, right: 8, top: 8 }}
         side="top"
       >
-        <div className="grid grid-cols-6 gap-1.5">
-          {PROFILE_SWATCHES.map(swatch => (
-            <button
-              aria-label={p.setColor(swatch)}
-              className="size-5 rounded-full transition-transform hover:scale-110"
-              key={swatch}
-              onClick={() => pickColor(swatch)}
-              style={{
-                backgroundColor: swatch,
-                boxShadow: swatch === color ? '0 0 0 2px var(--ui-bg-elevated), 0 0 0 3.5px currentColor' : undefined,
-                color: swatch
-              }}
-              type="button"
-            />
-          ))}
-        </div>
-        <button
-          className="mt-2 flex w-full items-center justify-center gap-1.5 rounded-md py-1 text-xs text-(--ui-text-tertiary) transition hover:bg-(--ui-control-hover-background) hover:text-foreground"
-          onClick={() => pickColor(null)}
-          type="button"
-        >
-          <Codicon name="sync" size="0.75rem" />
-          {p.autoColor}
-        </button>
+        <ColorSwatches
+          clearIcon="sync"
+          clearLabel={p.autoColor}
+          onChange={pickColor}
+          swatches={PROFILE_SWATCHES}
+          swatchLabel={p.setColor}
+          value={color}
+        />
       </PopoverContent>
     </Popover>
   )

apps/desktop/src/app/chat/sidebar/project-dialog.tsx

@@ -0,0 +1,213 @@
+import { useStore } from '@nanostores/react'
+import { useEffect, useRef, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { Codicon } from '@/components/ui/codicon'
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from '@/components/ui/dialog'
+import { Input } from '@/components/ui/input'
+import { useI18n } from '@/i18n'
+import { cn } from '@/lib/utils'
+import { notifyError } from '@/store/notifications'
+import {
+  $projectDialog,
+  addProjectFolder,
+  closeProjectDialog,
+  createProject,
+  pickProjectFolder,
+  renameProject
+} from '@/store/projects'
+
+// Single dialog mounted once in the sidebar; it renders create / rename /
+// add-folder flows driven by the $projectDialog atom. Folders are chosen via
+// the native directory picker (reused from the default-project-dir setting).
+export function ProjectDialog() {
+  const { t } = useI18n()
+  const p = t.sidebar.projects
+  const state = useStore($projectDialog)
+  const open = state !== null
+  const mode = state?.mode ?? 'create'
+
+  const [name, setName] = useState('')
+  const [folders, setFolders] = useState<string[]>([])
+  const [submitting, setSubmitting] = useState(false)
+  const nameRef = useRef<HTMLInputElement>(null)
+
+  useEffect(() => {
+    if (open) {
+      setName(state?.name ?? '')
+      setFolders([])
+      setSubmitting(false)
+
+      if (mode !== 'add-folder') {
+        window.setTimeout(() => nameRef.current?.select(), 0)
+      }
+    }
+  }, [open, mode, state?.name])
+
+  const onOpenChange = (next: boolean) => {
+    if (!next) {
+      closeProjectDialog()
+    }
+  }
+
+  // One submit beat for every flow: guard re-entry, run the write, close on
+  // success, surface a toast on failure. Callers pass only the write.
+  const runSubmit = async (write: () => Promise<unknown>) => {
+    if (submitting) {
+      return
+    }
+
+    setSubmitting(true)
+
+    try {
+      await write()
+      closeProjectDialog()
+    } catch (err) {
+      notifyError(err, p.createFailed)
+    } finally {
+      setSubmitting(false)
+    }
+  }
+
+  const pickFolder = async () => {
+    const dir = await pickProjectFolder()
+
+    if (!dir) {
+      return
+    }
+
+    const projectId = state?.projectId
+
+    if (mode === 'add-folder' && projectId) {
+      await runSubmit(() => addProjectFolder(projectId, dir))
+
+      return
+    }
+
+    setFolders(prev => (prev.includes(dir) ? prev : [...prev, dir]))
+  }
+
+  const submit = async () => {
+    const trimmed = name.trim()
+    const projectId = state?.projectId
+
+    if (mode === 'rename' && projectId) {
+      if (trimmed) {
+        await runSubmit(() => renameProject(projectId, trimmed))
+      }
+
+      return
+    }
+
+    // A project owns sessions by folder (cwd-prefix), so creation requires at
+    // least one — a folder-less project couldn't hold a session anyway.
+    if (mode === 'create' && trimmed && folders.length) {
+      await runSubmit(() => createProject({ folders, name: trimmed, use: true }))
+    }
+  }
+
+  const title = mode === 'rename' ? p.renameTitle : mode === 'add-folder' ? p.addFolderTitle : p.createTitle
+
+  return (
+    <Dialog onOpenChange={onOpenChange} open={open}>
+      <DialogContent className="max-w-md">
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+          {mode === 'create' && <DialogDescription>{p.createDesc}</DialogDescription>}
+        </DialogHeader>
+
+        {mode !== 'add-folder' && (
+          <Input
+            autoFocus
+            disabled={submitting}
+            onChange={event => setName(event.target.value)}
+            onKeyDown={event => {
+              if (event.key === 'Enter') {
+                event.preventDefault()
+                void submit()
+              } else if (event.key === 'Escape') {
+                onOpenChange(false)
+              }
+            }}
+            placeholder={p.namePlaceholder}
+            ref={nameRef}
+            value={name}
+          />
+        )}
+
+        {mode === 'create' && (
+          <div className="flex flex-col gap-1.5">
+            <span className="text-[0.6875rem] font-medium text-(--ui-text-tertiary)">{p.foldersLabel}</span>
+            {folders.length === 0 ? (
+              <span className="text-[0.75rem] text-(--ui-text-quaternary)">{p.noFolders}</span>
+            ) : (
+              <ul className="flex flex-col gap-1">
+                {folders.map((folder, index) => (
+                  <li
+                    className={cn(
+                      'flex items-center gap-2 rounded-md bg-(--ui-control-hover-background) px-2 py-1 text-[0.75rem]'
+                    )}
+                    key={folder}
+                  >
+                    <Codicon className="shrink-0 text-(--ui-text-tertiary)" name="folder" size="0.75rem" />
+                    <span className="min-w-0 flex-1 truncate" title={folder}>
+                      {folder}
+                    </span>
+                    {index === 0 && (
+                      <span className="shrink-0 text-[0.625rem] uppercase text-(--ui-text-quaternary)">
+                        {p.primaryBadge}
+                      </span>
+                    )}
+                    <Button
+                      aria-label={p.removeFolder}
+                      className="size-5 shrink-0 text-(--ui-text-quaternary) hover:text-foreground"
+                      onClick={() => setFolders(prev => prev.filter(f => f !== folder))}
+                      size="icon-xs"
+                      type="button"
+                      variant="ghost"
+                    >
+                      <Codicon name="close" size="0.75rem" />
+                    </Button>
+                  </li>
+                ))}
+              </ul>
+            )}
+            <Button
+              className="self-start"
+              disabled={submitting}
+              onClick={() => void pickFolder()}
+              size="sm"
+              type="button"
+              variant="ghost"
+            >
+              <Codicon name="add" size="0.75rem" />
+              {p.addFolder}
+            </Button>
+          </div>
+        )}
+
+        {mode === 'add-folder' && (
+          <Button disabled={submitting} onClick={() => void pickFolder()} type="button">
+            <Codicon name="folder-opened" size="0.875rem" />
+            {p.addFolder}
+          </Button>
+        )}
+
+        {mode !== 'add-folder' && (
+          <DialogFooter>
+            <Button disabled={submitting} onClick={() => onOpenChange(false)} type="button" variant="ghost">
+              {t.common.cancel}
+            </Button>
+            <Button
+              disabled={submitting || !name.trim() || (mode === 'create' && folders.length === 0)}
+              onClick={() => void submit()}
+              type="button"
+            >
+              {mode === 'rename' ? t.common.save : p.create}
+            </Button>
+          </DialogFooter>
+        )}
+      </DialogContent>
+    </Dialog>
+  )
+}

apps/desktop/src/app/chat/sidebar/projects/entered-content.tsx

@@ -0,0 +1,249 @@
+import { useStore } from '@nanostores/react'
+import type * as React from 'react'
+import { useMemo, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { Codicon } from '@/components/ui/codicon'
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from '@/components/ui/dialog'
+import type { HermesGitWorktree } from '@/global'
+import type { SessionInfo } from '@/hermes'
+import { useI18n } from '@/i18n'
+import { $dismissedWorktreeIds, dismissWorktree } from '@/store/layout'
+import { notifyError } from '@/store/notifications'
+import { removeWorktreePath } from '@/store/projects'
+
+import { SidebarRowStack } from '../chrome'
+
+import { useWorkspaceNodeOpen } from './model'
+import { SidebarWorkspaceGroup } from './workspace-group'
+import {
+  mergeRepoWorktreeGroups,
+  overlayRepoLanes,
+  type SidebarProjectTree,
+  type SidebarSessionGroup,
+  type SidebarWorkspaceTree
+} from './workspace-groups'
+import { WorkspaceAddButton, WorkspaceHeader } from './workspace-header'
+
+// The entered project's body. Main-checkout sessions render directly — no
+// redundant repo/branch header (the breadcrumb already names the project). Only
+// linked worktrees nest, shown by branch. Multi-folder projects keep per-repo
+// headers so the folders stay distinguishable.
+export function EnteredProjectContent({
+  project,
+  renderRows,
+  onNewSession,
+  repoWorktrees,
+  liveSessions,
+  removedSessionIds
+}: {
+  project: SidebarProjectTree
+  renderRows: (sessions: SessionInfo[]) => React.ReactNode
+  onNewSession?: (path: null | string) => void
+  repoWorktrees?: Record<string, HermesGitWorktree[]>
+  liveSessions?: SessionInfo[]
+  removedSessionIds?: ReadonlySet<string>
+}) {
+  if (!project.repos.length) {
+    return null
+  }
+
+  const single = project.repos.length === 1
+
+  return (
+    <>
+      {project.repos.map(repo => (
+        <RepoFlatSection
+          discoveredWorktrees={repo.path ? repoWorktrees?.[repo.path] : undefined}
+          key={repo.id}
+          liveSessions={liveSessions}
+          onNewSession={onNewSession}
+          removedSessionIds={removedSessionIds}
+          renderRows={renderRows}
+          repo={repo}
+          showHeader={!single}
+        />
+      ))}
+    </>
+  )
+}
+
+function RepoFlatSection({
+  repo,
+  showHeader,
+  renderRows,
+  onNewSession,
+  discoveredWorktrees,
+  liveSessions,
+  removedSessionIds
+}: {
+  repo: SidebarWorkspaceTree
+  showHeader: boolean
+  renderRows: (sessions: SessionInfo[]) => React.ReactNode
+  onNewSession?: (path: null | string) => void
+  discoveredWorktrees?: HermesGitWorktree[]
+  liveSessions?: SessionInfo[]
+  removedSessionIds?: ReadonlySet<string>
+}) {
+  const { t } = useI18n()
+  const s = t.sidebar
+  const [open, toggleOpen] = useWorkspaceNodeOpen(repo.id)
+  const dismissedWorktrees = useStore($dismissedWorktreeIds)
+
+  // The repo's session lanes already come fully built from the backend; this
+  // only injects empty VISUAL lanes from a live `git worktree list`.
+  const mergedGroups = useMemo(() => mergeRepoWorktreeGroups(repo, discoveredWorktrees), [repo, discoveredWorktrees])
+
+  // Optimistic placement runs against the MERGED lane set (backend + visual
+  // git-worktree lanes) so out-of-tree/sibling worktrees — which exist as visual
+  // lanes before the snapshot carries their sessions — get the new row. The
+  // overlay drops lanes it empties, so re-merge to restore still-real worktrees.
+  const overlaidGroups = useMemo(() => {
+    if (!(liveSessions?.length || removedSessionIds?.size)) {
+      return mergedGroups
+    }
+
+    const { groups } = overlayRepoLanes({ ...repo, groups: mergedGroups }, liveSessions ?? [], removedSessionIds)
+
+    return mergeRepoWorktreeGroups({ id: repo.id, path: repo.path, groups }, discoveredWorktrees)
+  }, [repo, mergedGroups, discoveredWorktrees, liveSessions, removedSessionIds])
+
+  // Main lanes are always visible; linked worktrees can be user-dismissed.
+  const ordered = overlaidGroups.filter(group => group.isMain || !dismissedWorktrees.includes(group.id))
+  const repoCount = ordered.reduce((sum, group) => sum + group.sessions.length, 0)
+
+  // Removal asks how: actually `git worktree remove` it, or just hide the lane
+  // and leave the worktree on disk. A dirty worktree escalates to a force prompt
+  // instead of erroring (those changes are usually throwaway).
+  const [removeTarget, setRemoveTarget] = useState<null | SidebarSessionGroup>(null)
+  const [forceTarget, setForceTarget] = useState<null | SidebarSessionGroup>(null)
+
+  const removeViaGit = async (group: SidebarSessionGroup, force = false) => {
+    if (!repo.path || !group.path) {
+      return
+    }
+
+    try {
+      await removeWorktreePath(repo.path, group.path, { force })
+      dismissWorktree(group.id)
+    } catch (err) {
+      // git refuses a non-force remove on a dirty/locked worktree — offer force
+      // rather than dead-ending on an error toast.
+      if (!force && /force|modified|untracked|dirty|locked|contains/i.test(String((err as Error)?.message ?? ''))) {
+        setForceTarget(group)
+      } else {
+        notifyError(err, s.projects.removeWorktreeFailed)
+      }
+    }
+  }
+
+  const body = (
+    <>
+      {ordered.map(group => (
+        <SidebarWorkspaceGroup
+          group={group}
+          key={group.id}
+          // The kanban bucket is read-only: it aggregates many task worktrees, so
+          // "new session here" and "remove worktree" have no single target.
+          onNewSession={group.isKanban ? undefined : onNewSession}
+          onRemove={group.isMain || group.isKanban ? undefined : () => setRemoveTarget(group)}
+          renderRows={renderRows}
+        />
+      ))}
+    </>
+  )
+
+  // Both removal prompts share the shape (hide-from-sidebar + cancel + a
+  // destructive action); only the copy and the destructive handler differ.
+  const worktreeDialog = (
+    target: null | SidebarSessionGroup,
+    setTarget: (next: null | SidebarSessionGroup) => void,
+    description: string,
+    destructiveLabel: string,
+    onDestructive: (group: SidebarSessionGroup) => void
+  ) => (
+    <Dialog onOpenChange={isOpen => !isOpen && setTarget(null)} open={Boolean(target)}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>{`${s.projects.removeWorktree} "${target?.label ?? ''}"?`}</DialogTitle>
+          <DialogDescription>{description}</DialogDescription>
+        </DialogHeader>
+        <DialogFooter>
+          <Button onClick={() => setTarget(null)} variant="ghost">
+            {t.common.cancel}
+          </Button>
+          <Button
+            onClick={() => {
+              if (target) {
+                dismissWorktree(target.id)
+              }
+
+              setTarget(null)
+            }}
+            variant="secondary"
+          >
+            {s.projects.removeFromSidebar}
+          </Button>
+          <Button
+            onClick={() => {
+              setTarget(null)
+
+              if (target) {
+                onDestructive(target)
+              }
+            }}
+            variant="destructive"
+          >
+            {destructiveLabel}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+
+  const removeDialog = (
+    <>
+      {worktreeDialog(
+        removeTarget,
+        setRemoveTarget,
+        s.projects.removeWorktreeConfirm,
+        s.projects.removeWorktree,
+        group => void removeViaGit(group)
+      )}
+      {worktreeDialog(
+        forceTarget,
+        setForceTarget,
+        s.projects.removeWorktreeDirty,
+        s.projects.forceRemove,
+        group => void removeViaGit(group, true)
+      )}
+    </>
+  )
+
+  if (!showHeader) {
+    return (
+      <>
+        {body}
+        {removeDialog}
+      </>
+    )
+  }
+
+  return (
+    <SidebarRowStack>
+      <WorkspaceHeader
+        action={
+          onNewSession && <WorkspaceAddButton label={s.newSessionIn(repo.label)} onClick={() => onNewSession(repo.path)} />
+        }
+        count={repoCount}
+        emphasis
+        icon={<Codicon className="shrink-0 text-(--ui-text-tertiary)" name="repo" size="0.75rem" />}
+        label={repo.label}
+        onToggle={toggleOpen}
+        open={open}
+      />
+      {open && <SidebarRowStack className="pl-2.5">{body}</SidebarRowStack>}
+      {removeDialog}
+    </SidebarRowStack>
+  )
+}

apps/desktop/src/app/chat/sidebar/projects/index.ts

@@ -0,0 +1,15 @@
+// Public surface of the project/worktree sidebar, consumed by the sidebar root.
+export { EnteredProjectContent } from './entered-content'
+export { PROJECT_PREVIEW_COUNT, projectTreeCwd, sortProjectsForOverview, useRepoWorktreeMap } from './model'
+export { ProjectBackRow, ProjectOverviewRow } from './overview-row'
+export { ProjectMenu } from './project-menu'
+export { SidebarWorkspaceGroup } from './workspace-group'
+export {
+  overlayLiveLanes,
+  overlayLivePreviews,
+  sessionRecency,
+  type SidebarProjectTree,
+  type SidebarSessionGroup,
+  type SidebarWorkspaceTree
+} from './workspace-groups'
+export { StartWorkButton } from './workspace-header'

apps/desktop/src/app/chat/sidebar/projects/model.ts

@@ -0,0 +1,121 @@
+import { useStore } from '@nanostores/react'
+import { useEffect, useMemo, useState } from 'react'
+
+import type { HermesGitWorktree } from '@/global'
+import type { SessionInfo } from '@/hermes'
+import { mapPool } from '@/lib/pool'
+import { $sidebarWorkspaceCollapsedIds, toggleWorkspaceNodeCollapsed } from '@/store/layout'
+import { $worktreeRefreshToken } from '@/store/projects'
+
+import { sessionRecency, type SidebarProjectTree } from './workspace-groups'
+
+// Page size when revealing more already-loaded rows within a workspace group.
+export const SIDEBAR_GROUP_PAGE = 5
+
+// Recent sessions previewed under each project in the overview.
+export const PROJECT_PREVIEW_COUNT = 3
+
+// Max concurrent `git worktree list` probes when a project spans many repos.
+const WORKTREE_PROBE_CONCURRENCY = 4
+
+const pathListKey = (paths: string[]): string =>
+  paths.map(path => path.trim()).filter(Boolean).sort((a, b) => a.localeCompare(b)).join('\n')
+
+// Every session in a project, across its repos/worktrees (order-agnostic).
+const projectSessions = (project: SidebarProjectTree): SessionInfo[] =>
+  project.repos.flatMap(repo => repo.groups.flatMap(group => group.sessions))
+
+export const projectTreeCwd = (project: SidebarProjectTree): null | string =>
+  project.path || project.repos.find(repo => repo.path)?.path || null
+
+// Overview rows carry their activity stamp from the backend (lanes are empty in
+// overview mode), falling back to loaded session times when present.
+const projectActivityTime = (project: SidebarProjectTree): number =>
+  Math.max(
+    project.lastActive ?? 0,
+    projectSessions(project).reduce((latest, s) => Math.max(latest, sessionRecency(s)), 0)
+  )
+
+// The project's most-recent sessions, for the overview preview under each row.
+export const latestProjectSessions = (project: SidebarProjectTree, limit: number): SessionInfo[] =>
+  [...projectSessions(project)].sort((a, b) => sessionRecency(b) - sessionRecency(a)).slice(0, limit)
+
+export function sortProjectsForOverview(
+  projects: SidebarProjectTree[],
+  activeProjectId: null | string
+): SidebarProjectTree[] {
+  return [...projects].sort((a, b) => {
+    const aActive = Boolean(activeProjectId && a.id === activeProjectId && !a.isAuto)
+    const bActive = Boolean(activeProjectId && b.id === activeProjectId && !b.isAuto)
+
+    if (aActive !== bActive) {
+      return aActive ? -1 : 1
+    }
+
+    if (!a.isAuto !== !b.isAuto) {
+      return a.isAuto ? 1 : -1
+    }
+
+    const aHasSessions = a.sessionCount > 0
+    const bHasSessions = b.sessionCount > 0
+
+    if (aHasSessions !== bHasSessions) {
+      return aHasSessions ? -1 : 1
+    }
+
+    return projectActivityTime(b) - projectActivityTime(a) || a.label.localeCompare(b.label, undefined, { sensitivity: 'base' })
+  })
+}
+
+// Project drill-in lanes are git-driven: source them from `git worktree list` so
+// linked worktrees still appear even when their sessions aren't in the recents
+// payload currently loaded in memory.
+export function useRepoWorktreeMap(
+  repoPaths: string[],
+  enabled: boolean
+): [Record<string, HermesGitWorktree[]>, boolean] {
+  const [map, setMap] = useState<Record<string, HermesGitWorktree[]>>({})
+  const [loading, setLoading] = useState(false)
+  const key = useMemo(() => pathListKey(repoPaths), [repoPaths])
+  // Refetch when a worktree is added/removed so a new lane shows immediately.
+  const refreshToken = useStore($worktreeRefreshToken)
+
+  useEffect(() => {
+    const git = window.hermesDesktop?.git
+
+    if (!enabled || !repoPaths.length || !git?.worktreeList) {
+      setMap({})
+      setLoading(false)
+
+      return
+    }
+
+    let cancelled = false
+
+    setLoading(true)
+    // Bounded so a many-repo project doesn't spawn a `git` process per repo at once.
+    void mapPool(repoPaths, WORKTREE_PROBE_CONCURRENCY, async repoPath => {
+      try {
+        return [repoPath, await git.worktreeList(repoPath)] as const
+      } catch {
+        return [repoPath, []] as const
+      }
+    })
+      .then(entries => void (cancelled || setMap(Object.fromEntries(entries))))
+      .finally(() => void (cancelled || setLoading(false)))
+
+    return () => {
+      cancelled = true
+    }
+  }, [enabled, key, repoPaths, refreshToken])
+
+  return [map, loading]
+}
+
+// Persisted open/collapse for a repo/worktree node (absent = open). Lets a
+// project's folder layout auto-restore when you enter it, and survive reloads.
+export function useWorkspaceNodeOpen(id: string): [boolean, () => void] {
+  const collapsed = useStore($sidebarWorkspaceCollapsedIds)
+
+  return [!collapsed.includes(id), () => toggleWorkspaceNodeCollapsed(id)]
+}

apps/desktop/src/app/chat/sidebar/projects/overview-row.tsx

@@ -0,0 +1,155 @@
+import type * as React from 'react'
+import { useRef } from 'react'
+
+import { Codicon } from '@/components/ui/codicon'
+import { DisclosureCaret } from '@/components/ui/disclosure-caret'
+import type { SessionInfo } from '@/hermes'
+import { useI18n } from '@/i18n'
+import { cn } from '@/lib/utils'
+
+import {
+  SIDEBAR_LEAD_ICON_SIZE,
+  SidebarRowBody,
+  SidebarRowCluster,
+  SidebarRowGrab,
+  SidebarRowLabel,
+  SidebarRowLead,
+  SidebarRowLeadGlyph,
+  SidebarRowLink,
+  SidebarRowNest,
+  SidebarRowShell
+} from '../chrome'
+
+import { latestProjectSessions, PROJECT_PREVIEW_COUNT, useWorkspaceNodeOpen } from './model'
+import { ProjectMenu } from './project-menu'
+import type { SidebarProjectTree } from './workspace-groups'
+import { WorkspaceAddButton } from './workspace-header'
+
+// A bare color dot (no icon) or an icon glyph — tinted by `color` when set, else
+// the lead's default tertiary. The glyph wrapper centers + caps size either way.
+export function projectIcon({ color, icon }: SidebarProjectTree) {
+  if (color && !icon) {
+    return (
+      <SidebarRowLeadGlyph>
+        <span aria-hidden="true" className="size-1 rounded-full" style={{ backgroundColor: color }} />
+      </SidebarRowLeadGlyph>
+    )
+  }
+
+  return (
+    <SidebarRowLeadGlyph style={color ? { color } : undefined}>
+      <Codicon name={icon || 'folder-library'} size={SIDEBAR_LEAD_ICON_SIZE} />
+    </SidebarRowLeadGlyph>
+  )
+}
+
+export function ProjectBackRow({ label, onClick }: { label: string; onClick: () => void }) {
+  return (
+    <SidebarRowShell>
+      <SidebarRowBody
+        className="group/back w-full text-(--ui-text-tertiary) opacity-40 hover:text-foreground"
+        onClick={onClick}
+      >
+        <SidebarRowLead>
+          <SidebarRowLeadGlyph>
+            <Codicon name="arrow-left" size={SIDEBAR_LEAD_ICON_SIZE} />
+          </SidebarRowLeadGlyph>
+        </SidebarRowLead>
+        <SidebarRowLabel className="text-xs underline-offset-4 group-hover/back:underline">{label}</SidebarRowLabel>
+      </SidebarRowBody>
+    </SidebarRowShell>
+  )
+}
+
+interface ProjectOverviewRowProps {
+  project: SidebarProjectTree
+  onEnter?: (id: string) => void
+  onNewSession?: (path: null | string) => void
+  renderRows?: (sessions: SessionInfo[]) => React.ReactNode
+  activeProjectId?: null | string
+  previewSessions?: SessionInfo[]
+  reorderable?: boolean
+  dragging?: boolean
+  dragHandleProps?: React.HTMLAttributes<HTMLElement>
+  ref?: React.Ref<HTMLDivElement>
+  style?: React.CSSProperties
+}
+
+export function ProjectOverviewRow({
+  project,
+  onEnter,
+  onNewSession,
+  renderRows,
+  activeProjectId,
+  previewSessions,
+  reorderable = false,
+  dragging = false,
+  dragHandleProps,
+  ref,
+  style
+}: ProjectOverviewRowProps) {
+  const { t } = useI18n()
+  const s = t.sidebar
+  const isActive = project.id === activeProjectId
+  const [open, toggleOpen] = useWorkspaceNodeOpen(project.id)
+  // The appearance popover anchors here (the full row) so it opens flush with
+  // the sidebar's content edge regardless of which side the sidebar is on.
+  const rowRef = useRef<HTMLDivElement>(null)
+  const fetched = (previewSessions ?? []).slice(0, PROJECT_PREVIEW_COUNT)
+  const preview = renderRows ? (fetched.length ? fetched : latestProjectSessions(project, PROJECT_PREVIEW_COUNT)) : []
+
+  const lead = reorderable ? (
+    <SidebarRowGrab
+      ariaLabel={s.projects.reorder(project.label)}
+      dragging={dragging}
+      dragHandleProps={dragHandleProps}
+      leadClassName="overflow-visible"
+    >
+      {projectIcon(project)}
+    </SidebarRowGrab>
+  ) : (
+    <SidebarRowLead>{projectIcon(project)}</SidebarRowLead>
+  )
+
+  return (
+    <div className={cn(dragging && 'relative z-10')} ref={ref} style={style}>
+      <SidebarRowShell
+        actions={
+          <>
+            {onNewSession && <WorkspaceAddButton label={s.newSessionIn(project.label)} onClick={() => onNewSession(project.path)} />}
+            <ProjectMenu anchorRef={rowRef} isActive={isActive} project={project} />
+          </>
+        }
+        className={cn('group/workspace', dragging && 'cursor-grabbing bg-(--ui-sidebar-surface-background)')}
+        ref={rowRef}
+      >
+        <SidebarRowCluster className="min-w-0 flex-1">
+          {lead}
+          <SidebarRowLink
+            aria-label={s.projects.enter(project.label)}
+            labelClassName={cn('hover:text-foreground hover:underline', isActive && 'text-foreground')}
+            onClick={() => onEnter?.(project.id)}
+          >
+            {project.label}
+          </SidebarRowLink>
+          {preview.length > 0 ? (
+            <button
+              aria-label={s.projects.toggle(project.label)}
+              className="flex flex-1 items-center self-stretch bg-transparent p-0"
+              onClick={toggleOpen}
+              type="button"
+            >
+              <DisclosureCaret
+                className="shrink-0 text-(--ui-text-tertiary) opacity-0 transition group-hover/workspace:opacity-100"
+                open={open}
+              />
+            </button>
+          ) : (
+            <span className="flex-1" />
+          )}
+        </SidebarRowCluster>
+      </SidebarRowShell>
+      {open && preview.length > 0 && <SidebarRowNest>{renderRows?.(preview)}</SidebarRowNest>}
+    </div>
+  )
+}

apps/desktop/src/app/chat/sidebar/projects/project-menu.tsx

@@ -0,0 +1,206 @@
+import { useStore } from '@nanostores/react'
+import type * as React from 'react'
+import { useState } from 'react'
+
+import { Codicon } from '@/components/ui/codicon'
+import { ColorSwatches } from '@/components/ui/color-swatches'
+import { ConfirmDialog } from '@/components/ui/confirm-dialog'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger
+} from '@/components/ui/dropdown-menu'
+import { Popover, PopoverAnchor, PopoverContent } from '@/components/ui/popover'
+import { useI18n } from '@/i18n'
+import { PROFILE_SWATCHES } from '@/lib/profile-color'
+import { cn } from '@/lib/utils'
+import { $panesFlipped, dismissAutoProject } from '@/store/layout'
+import {
+  copyPath,
+  deleteProject,
+  openProjectAddFolder,
+  openProjectRename,
+  revealPath,
+  setActiveProject,
+  updateProject
+} from '@/store/projects'
+
+import type { SidebarProjectTree } from './workspace-groups'
+
+// Curated codicons for the project glyph (tinted by the chosen color).
+const ICONS = [
+  'folder-library', 'repo', 'rocket', 'beaker', 'flame', 'star-full', 'heart',
+  'zap', 'target', 'lightbulb', 'tools', 'device-desktop', 'device-mobile', 'terminal',
+  'dashboard', 'globe', 'broadcast', 'cloud', 'database', 'package', 'book',
+  'organization', 'bug', 'shield', 'key', 'gift', 'telescope', 'home'
+]
+
+// Per-project actions, modeled on git GUIs (GitHub Desktop / GitKraken): reveal
+// in the file manager, copy path, and "Remove from sidebar" (never deletes files
+// — auto projects are dismissed, explicit ones drop their entry). Explicit
+// projects additionally get rename / add folder / set active. Hidden until the
+// row is hovered (group/workspace), matching the + affordance.
+export function ProjectMenu({
+  project,
+  isActive,
+  scoped = false,
+  onExitScope,
+  anchorRef
+}: {
+  project: SidebarProjectTree
+  isActive: boolean
+  // True when rendered in the entered-project header, so removal can leave the
+  // now-defunct scope.
+  scoped?: boolean
+  onExitScope?: () => void
+  // Anchor the appearance popover to the whole row instead of the kebab, so it
+  // opens flush against the sidebar's content-facing edge — otherwise a
+  // right-side sidebar drags the picker across the entire panel (the kebab
+  // lives at the row's outer edge). Falls back to the kebab when absent.
+  anchorRef?: React.RefObject<HTMLElement | null>
+}) {
+  const { t } = useI18n()
+  const p = t.sidebar.projects
+  const target = { id: project.id, name: project.label }
+  const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false)
+  const [appearanceOpen, setAppearanceOpen] = useState(false)
+  // Open toward the content area: right when the sidebar is on the left, left
+  // when the panes are flipped (sidebar on the right).
+  const panesFlipped = useStore($panesFlipped)
+
+  const removeAuto = () => {
+    dismissAutoProject(project.id)
+
+    if (scoped) {
+      onExitScope?.()
+    }
+  }
+
+  const confirmDelete = async () => {
+    await deleteProject(project.id)
+
+    if (scoped) {
+      onExitScope?.()
+    }
+  }
+
+  const trigger = (
+    <DropdownMenuTrigger asChild>
+      <button
+        aria-label={p.menu}
+        className={cn(
+          '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 data-[state=open]:opacity-100',
+          // In the project header reveal on the whole header hover; in overview
+          // rows reveal on the row hover.
+          scoped ? 'group-hover/section:opacity-100' : 'group-hover/workspace:opacity-100'
+        )}
+        onClick={event => event.stopPropagation()}
+        type="button"
+      >
+        <Codicon name="kebab-vertical" size="0.75rem" />
+      </button>
+    </DropdownMenuTrigger>
+  )
+
+  return (
+    <Popover onOpenChange={setAppearanceOpen} open={appearanceOpen}>
+      {/* Position the appearance popover against the row (when a ref is wired);
+          the kebab is only the dropdown trigger then. */}
+      {anchorRef ? <PopoverAnchor virtualRef={anchorRef as React.RefObject<HTMLElement>} /> : null}
+      <DropdownMenu>
+        {anchorRef ? trigger : <PopoverAnchor asChild>{trigger}</PopoverAnchor>}
+        {/* Closing the menu refocuses the trigger (also the popover anchor),
+            which the appearance popover would read as focus-outside and die on.
+            Suppress that refocus so it survives. */}
+        <DropdownMenuContent align="end" className="w-48" onCloseAutoFocus={event => event.preventDefault()} sideOffset={6}>
+          {!project.isAuto && (
+            <>
+              <DropdownMenuItem onSelect={() => openProjectRename(target)}>
+                <Codicon name="edit" size="0.875rem" />
+                <span>{p.menuRename}</span>
+              </DropdownMenuItem>
+              <DropdownMenuItem onSelect={() => setAppearanceOpen(true)}>
+                <Codicon name="symbol-color" size="0.875rem" />
+                <span>{p.menuAppearance}</span>
+              </DropdownMenuItem>
+              <DropdownMenuItem onSelect={() => openProjectAddFolder(target)}>
+                <Codicon name="new-folder" size="0.875rem" />
+                <span>{p.menuAddFolder}</span>
+              </DropdownMenuItem>
+              <DropdownMenuItem disabled={isActive} onSelect={() => void setActiveProject(project.id)}>
+                <Codicon name="target" size="0.875rem" />
+                <span>{p.menuSetActive}</span>
+              </DropdownMenuItem>
+              <DropdownMenuSeparator />
+            </>
+          )}
+          <DropdownMenuItem disabled={!project.path} onSelect={() => void revealPath(project.path)}>
+            <Codicon name="folder-opened" size="0.875rem" />
+            <span>{p.reveal}</span>
+          </DropdownMenuItem>
+          <DropdownMenuItem disabled={!project.path} onSelect={() => void copyPath(project.path)}>
+            <Codicon name="copy" size="0.875rem" />
+            <span>{p.copyPath}</span>
+          </DropdownMenuItem>
+          <DropdownMenuSeparator />
+          {project.isAuto ? (
+            <DropdownMenuItem onSelect={removeAuto} variant="destructive">
+              <Codicon name="trash" size="0.875rem" />
+              <span>{p.removeFromSidebar}</span>
+            </DropdownMenuItem>
+          ) : (
+            <DropdownMenuItem onSelect={() => setConfirmDeleteOpen(true)} variant="destructive">
+              <Codicon name="trash" size="0.875rem" />
+              <span>{`${p.menuDelete}…`}</span>
+            </DropdownMenuItem>
+          )}
+        </DropdownMenuContent>
+      </DropdownMenu>
+      <PopoverContent
+        align="start"
+        className="w-auto p-2"
+        onClick={event => event.stopPropagation()}
+        side={panesFlipped ? 'left' : 'right'}
+        sideOffset={6}
+      >
+        <ColorSwatches
+          clearIcon="circle-slash"
+          clearLabel={p.noColor}
+          onChange={color => void updateProject(project.id, { color })}
+          swatches={PROFILE_SWATCHES}
+          value={project.color ?? null}
+        />
+        {/* Same 6 columns + gap as the swatch grid so the popover keeps the
+            profile picker's width (icons flex to fill, not fixed-width). */}
+        <div className="mt-2 grid grid-cols-6 gap-1.5">
+          {ICONS.map(name => (
+            <button
+              aria-label={name}
+              className={cn(
+                'grid aspect-square place-items-center rounded-md text-(--ui-text-tertiary) transition hover:bg-(--ui-control-hover-background)',
+                project.icon === name && 'bg-(--ui-control-active-background) text-foreground'
+              )}
+              key={name}
+              onClick={() => void updateProject(project.id, { icon: project.icon === name ? null : name })}
+              style={project.icon === name && project.color ? { color: project.color } : undefined}
+              type="button"
+            >
+              <Codicon name={name} size="0.8125rem" />
+            </button>
+          ))}
+        </div>
+      </PopoverContent>
+      <ConfirmDialog
+        confirmLabel={p.menuDelete}
+        description={p.deleteConfirm}
+        destructive
+        onClose={() => setConfirmDeleteOpen(false)}
+        onConfirm={confirmDelete}
+        open={confirmDeleteOpen}
+        title={`${p.menuDelete} "${project.label}"?`}
+      />
+    </Popover>
+  )
+}

apps/desktop/src/app/chat/sidebar/projects/workspace-group.tsx

@@ -0,0 +1,105 @@
+import type * as React from 'react'
+import { useState } from 'react'
+
+import { Codicon } from '@/components/ui/codicon'
+import type { SessionInfo } from '@/hermes'
+import { useI18n } from '@/i18n'
+import { newSessionInProfile } from '@/store/profile'
+
+import { countLabel, SidebarRowStack } from '../chrome'
+import { SidebarLoadMoreRow } from '../load-more-row'
+
+import { SIDEBAR_GROUP_PAGE, useWorkspaceNodeOpen } from './model'
+import type { SidebarSessionGroup } from './workspace-groups'
+import { WorkspaceAddButton, WorkspaceHeader, WorkspaceMenu, WorkspaceShowMoreButton } from './workspace-header'
+
+interface SidebarWorkspaceGroupProps {
+  group: SidebarSessionGroup
+  renderRows: (sessions: SessionInfo[]) => React.ReactNode
+  onNewSession?: (path: null | string) => void
+  // When set (linked worktree rows), shows a remove affordance that runs a real
+  // `git worktree remove`.
+  onRemove?: () => void
+}
+
+export function SidebarWorkspaceGroup({ group, renderRows, onNewSession, onRemove }: SidebarWorkspaceGroupProps) {
+  const { t } = useI18n()
+  const s = t.sidebar
+  const isProfileGroup = group.mode === 'profile'
+  const [open, toggleOpen] = useWorkspaceNodeOpen(group.id)
+  const [visibleCount, setVisibleCount] = useState(SIDEBAR_GROUP_PAGE)
+
+  const loadedCount = group.sessions.length
+  // Profile groups know their on-disk total (children excluded); workspace
+  // groups only ever page within what's already loaded.
+  const totalCount = isProfileGroup ? Math.max(group.totalCount ?? loadedCount, loadedCount) : loadedCount
+  const visibleSessions = group.sessions.slice(0, visibleCount)
+  const hiddenCount = Math.max(0, totalCount - visibleSessions.length)
+  const nextCount = Math.min(SIDEBAR_GROUP_PAGE, hiddenCount)
+
+  // Leading glyph: profile color dot, or a branch/kanban mark for a worktree.
+  const leadingIcon = group.color ? (
+    <span aria-hidden="true" className="size-2 shrink-0 rounded-full" style={{ backgroundColor: group.color }} />
+  ) : (
+    <Codicon className="shrink-0 text-(--ui-text-tertiary)" name={group.isKanban ? 'checklist' : 'git-branch'} size="0.75rem" />
+  )
+
+  // Reveal already-loaded rows first; only hit the backend when the next page
+  // crosses what's been fetched for this profile.
+  const handleProfileLoadMore = () => {
+    const target = visibleCount + SIDEBAR_GROUP_PAGE
+
+    setVisibleCount(target)
+
+    if (target > loadedCount && loadedCount < totalCount) {
+      group.onLoadMore?.()
+    }
+  }
+
+  return (
+    <SidebarRowStack>
+      <WorkspaceHeader
+        action={
+          (onNewSession || isProfileGroup || onRemove) && (
+            <div className="flex items-center">
+              {(onNewSession || isProfileGroup) && (
+                <WorkspaceAddButton
+                  label={s.newSessionIn(group.label)}
+                  // Profile groups start a fresh session in that profile but keep
+                  // the all-profiles browse view (newSessionInProfile leaves the
+                  // scope alone); workspace groups seed the new session's cwd.
+                  onClick={() => (isProfileGroup ? newSessionInProfile(group.id) : onNewSession?.(group.path))}
+                />
+              )}
+              {onRemove && <WorkspaceMenu onRemove={onRemove} path={group.path} />}
+            </div>
+          )
+        }
+        count={isProfileGroup ? countLabel(visibleSessions.length, totalCount) : group.sessions.length}
+        icon={leadingIcon}
+        label={group.label}
+        onToggle={toggleOpen}
+        open={open}
+      />
+      {open && (
+        <>
+          {visibleSessions.length === 0 ? (
+            <div className="min-h-7 pl-2 text-[0.75rem] leading-7 text-(--ui-text-quaternary)">{s.noSessions}</div>
+          ) : (
+            renderRows(visibleSessions)
+          )}
+          {hiddenCount > 0 &&
+            (isProfileGroup ? (
+              <SidebarLoadMoreRow loading={Boolean(group.loadingMore)} onClick={handleProfileLoadMore} step={nextCount} />
+            ) : (
+              <WorkspaceShowMoreButton
+                count={nextCount}
+                label={group.label}
+                onClick={() => setVisibleCount(count => count + SIDEBAR_GROUP_PAGE)}
+              />
+            ))}
+        </>
+      )}
+    </SidebarRowStack>
+  )
+}

apps/desktop/src/app/chat/sidebar/projects/workspace-groups.test.ts

@@ -0,0 +1,422 @@
+import { describe, expect, it } from 'vitest'
+
+import type { HermesGitWorktree } from '@/global'
+import type { ProjectInfo, SessionInfo } from '@/types/hermes'
+
+import {
+  baseName,
+  kanbanWorktreeDir,
+  liveSessionProjectId,
+  mergeRepoWorktreeGroups,
+  overlayLiveLanes,
+  overlayLivePreviews,
+  type SidebarProjectTree,
+  type SidebarSessionGroup,
+  sortWorktreeGroups
+} from './workspace-groups'
+
+// The grouping itself now lives on the backend (tui_gateway/project_tree.py,
+// covered by tests/tui_gateway/test_project_tree.py). This file only covers the
+// thin render helpers the desktop still owns + the VISUAL worktree enhancer.
+
+let nextId = 0
+
+function makeSession(cwd: null | string, overrides: Partial<SessionInfo> = {}): SessionInfo {
+  return {
+    archived: false,
+    cwd,
+    ended_at: null,
+    id: `s${nextId++}`,
+    input_tokens: 0,
+    is_active: false,
+    last_active: 1_000,
+    message_count: 1,
+    model: 'claude',
+    output_tokens: 0,
+    preview: null,
+    source: 'cli',
+    started_at: 1_000,
+    title: null,
+    tool_call_count: 0,
+    ...overrides
+  }
+}
+
+const lane = (over: Partial<SidebarSessionGroup> & Pick<SidebarSessionGroup, 'id' | 'label'>): SidebarSessionGroup => ({
+  path: null,
+  sessions: [],
+  ...over
+})
+
+describe('baseName', () => {
+  it('returns the final path segment, ignoring trailing slashes and separators', () => {
+    expect(baseName('/www/hermes-agent/')).toBe('hermes-agent')
+    expect(baseName('C:\\repos\\app')).toBe('app')
+    expect(baseName('')).toBeUndefined()
+  })
+})
+
+describe('kanbanWorktreeDir', () => {
+  it('matches a kanban task worktree (t_<hex>) and returns its .worktrees dir', () => {
+    expect(kanbanWorktreeDir('/repo/.worktrees/t_aaaaaaaa')).toBe('/repo/.worktrees')
+  })
+
+  it('does NOT match a user-named "New worktree" under .worktrees/ (its own lane)', () => {
+    expect(kanbanWorktreeDir('/repo/.worktrees/test-gui-stuff')).toBeNull()
+  })
+
+  it('returns null for non-kanban paths', () => {
+    expect(kanbanWorktreeDir('/repo/src')).toBeNull()
+    expect(kanbanWorktreeDir('/repo')).toBeNull()
+  })
+})
+
+describe('sortWorktreeGroups', () => {
+  it('pins trunk to the top, sinks kanban to the bottom, and orders the rest by recency', () => {
+    const at = (t: number) => [makeSession('/x', { last_active: t })]
+
+    const groups = [
+      lane({ id: 'k', label: 'kanban', isKanban: true, sessions: at(999) }),
+      lane({ id: 'stale', label: 'stale-branch', isMain: true, sessions: at(10) }),
+      lane({ id: 'wt', label: 'busy-worktree', isMain: false, sessions: at(500) }),
+      lane({ id: 'main', label: 'main', isMain: true, sessions: at(1) })
+    ]
+
+    // main (trunk) first despite being least recent; kanban last despite being
+    // most recent; busy-worktree ahead of stale-branch by activity.
+    expect(sortWorktreeGroups(groups).map(g => g.label)).toEqual(['main', 'busy-worktree', 'stale-branch', 'kanban'])
+  })
+
+  it('falls back to label order for equally-idle lanes', () => {
+    const groups = [
+      lane({ id: 'b', label: 'beta', isMain: false }),
+      lane({ id: 'a', label: 'alpha', isMain: false })
+    ]
+
+    expect(sortWorktreeGroups(groups).map(g => g.label)).toEqual(['alpha', 'beta'])
+  })
+})
+
+describe('mergeRepoWorktreeGroups (visual enhancer)', () => {
+  it('injects a linked worktree lane discovered by git that has no sessions yet', () => {
+    const repo = { id: '/repo', path: '/repo', groups: [lane({ id: '/repo::branch::main', label: 'main', isMain: true, path: '/repo' })] }
+
+    const discovered: HermesGitWorktree[] = [
+      { branch: 'feature', detached: false, isMain: false, locked: false, path: '/repo-wt-feature' }
+    ]
+
+    const merged = mergeRepoWorktreeGroups(repo, discovered)
+
+    expect(merged.map(g => g.label)).toEqual(['main', 'feature'])
+    // The injected lane is empty (visual only — never carries sessions).
+    expect(merged.find(g => g.label === 'feature')?.sessions).toEqual([])
+  })
+
+  it('never spawns a lane per kanban task worktree', () => {
+    const repo = { id: '/repo', path: '/repo', groups: [lane({ id: '/repo::branch::main', label: 'main', isMain: true, path: '/repo' })] }
+
+    const discovered: HermesGitWorktree[] = [
+      { branch: 'wt/t_aaaaaaaa', detached: false, isMain: false, locked: false, path: '/repo/.worktrees/t_aaaaaaaa' },
+      { branch: 'wt/t_bbbbbbbb', detached: false, isMain: false, locked: false, path: '/repo/.worktrees/t_bbbbbbbb' }
+    ]
+
+    expect(mergeRepoWorktreeGroups(repo, discovered).map(g => g.label)).toEqual(['main'])
+  })
+
+  it('does not duplicate a lane already present from the backend (by id/path)', () => {
+    const repo = {
+      id: '/repo',
+      path: '/repo',
+      groups: [
+        lane({ id: '/repo::branch::main', label: 'main', isMain: true, path: '/repo', sessions: [makeSession('/repo')] })
+      ]
+    }
+
+    const discovered: HermesGitWorktree[] = [
+      { branch: 'main', detached: false, isMain: true, locked: false, path: '/repo' }
+    ]
+
+    const merged = mergeRepoWorktreeGroups(repo, discovered)
+
+    expect(merged).toHaveLength(1)
+    // The backend lane keeps its session rows; the enhancer left it untouched.
+    expect(merged[0].sessions).toHaveLength(1)
+  })
+
+  it('is a no-op when git worktree list is unavailable (remote backend)', () => {
+    const groups = [lane({ id: '/repo::branch::main', label: 'main', isMain: true, path: '/repo' })]
+
+    expect(mergeRepoWorktreeGroups({ id: '/repo', path: '/repo', groups }, undefined).map(g => g.label)).toEqual(['main'])
+  })
+
+  it('does not add a second "main" for a linked worktree checked out on main', () => {
+    const groups = [lane({ id: '/repo::branch::main', label: 'main', isMain: true, path: '/repo', sessions: [makeSession('/repo')] })]
+
+    const discovered: HermesGitWorktree[] = [
+      { branch: 'main', detached: false, isMain: false, locked: false, path: '/repo/.worktrees/main-mirror' }
+    ]
+
+    expect(mergeRepoWorktreeGroups({ id: '/repo', path: '/repo', groups }, discovered).filter(g => g.label === 'main')).toHaveLength(1)
+  })
+
+  it('surfaces a user-named "New worktree" under .worktrees/ as its own lane', () => {
+    const discovered: HermesGitWorktree[] = [
+      { branch: 'hermes/test-gui-stuff', detached: false, isMain: false, locked: false, path: '/repo/.worktrees/test-gui-stuff' }
+    ]
+
+    const merged = mergeRepoWorktreeGroups({ id: '/repo', path: '/repo', groups: [] }, discovered)
+
+    expect(merged.map(g => g.label)).toContain('hermes/test-gui-stuff')
+  })
+})
+
+const makeProject = (id: string, folders: string[]): ProjectInfo => ({
+  archived: false,
+  board_slug: null,
+  color: null,
+  created_at: 0,
+  description: null,
+  folders: folders.map((path, i) => ({ added_at: 0, is_primary: i === 0, label: null, path })),
+  icon: null,
+  id,
+  name: id,
+  primary_path: folders[0] ?? null,
+  slug: id
+})
+
+const projectNode = (over: Partial<SidebarProjectTree> & Pick<SidebarProjectTree, 'id'>): SidebarProjectTree => ({
+  label: over.id,
+  path: over.id,
+  repos: [],
+  sessionCount: 0,
+  ...over
+})
+
+describe('liveSessionProjectId', () => {
+  it('maps a brand-new (unpersisted) session to its auto project (the repo root)', () => {
+    expect(liveSessionProjectId(makeSession('/www/app'), [])).toBe('/www/app')
+  })
+
+  it('routes a session under an explicit project folder to that project', () => {
+    const id = liveSessionProjectId(makeSession('/www/app/src', { git_repo_root: '/www/app', git_branch: 'feat' }), [
+      makeProject('p_app', ['/www/app'])
+    ])
+
+    expect(id).toBe('p_app')
+  })
+
+  it('skips cwd-less, kanban, and linked-worktree sessions (backend folds those)', () => {
+    expect(liveSessionProjectId(makeSession(null), [])).toBeNull()
+    expect(liveSessionProjectId(makeSession('/repo/.worktrees/t_aaaaaaaa'), [])).toBeNull()
+    expect(liveSessionProjectId(makeSession('/elsewhere/wt', { git_repo_root: '/repo' }), [])).toBeNull()
+  })
+})
+
+describe('overlayLiveLanes', () => {
+  it('injects a live session into the matching main lane instantly', () => {
+    const project = projectNode({
+      id: '/www/app',
+      isAuto: true,
+      repos: [{ id: '/www/app', label: 'app', path: '/www/app', sessionCount: 0, groups: [] }]
+    })
+
+    const live = [makeSession('/www/app', { id: 'fresh', git_branch: 'main' })]
+
+    const overlaid = overlayLiveLanes(project, live)
+    const lane = overlaid.repos[0].groups.find(g => g.label === 'main')
+
+    expect(lane?.sessions.map(session => session.id)).toContain('fresh')
+    expect(overlaid.sessionCount).toBe(1)
+  })
+
+  it('injects a session created in a fresh worktree into that worktree lane (no git_repo_root yet)', () => {
+    // The brand-new session row has only a cwd — no git_repo_root. The entered
+    // project knows its repo root, so the worktree session still lands in its
+    // own lane (not kanban, not skipped) optimistically.
+    const project = projectNode({
+      id: '/www/app',
+      isAuto: true,
+      repos: [{ id: '/www/app', label: 'app', path: '/www/app', sessionCount: 0, groups: [] }]
+    })
+
+    const live = [makeSession('/www/app/.worktrees/baby', { id: 'fresh' })]
+
+    const overlaid = overlayLiveLanes(project, live)
+    const lane = overlaid.repos[0].groups.find(g => g.id === '/www/app/.worktrees/baby')
+
+    expect(lane?.label).toBe('baby')
+    expect(lane?.sessions.map(s => s.id)).toEqual(['fresh'])
+  })
+
+  it('folds a kanban-task worktree session into the kanban lane', () => {
+    const project = projectNode({
+      id: '/www/app',
+      isAuto: true,
+      repos: [{ id: '/www/app', label: 'app', path: '/www/app', sessionCount: 0, groups: [] }]
+    })
+
+    const live = [makeSession('/www/app/.worktrees/t_abc12345', { id: 'k' })]
+
+    const overlaid = overlayLiveLanes(project, live)
+    const lane = overlaid.repos[0].groups.find(g => g.isKanban)
+
+    expect(lane?.id).toBe('/www/app::kanban')
+    expect(lane?.sessions.map(s => s.id)).toEqual(['k'])
+  })
+
+  it('does not duplicate a session already present in a backend lane', () => {
+    const existing = makeSession('/www/app', { id: 'dup', git_branch: 'main' })
+
+    const project = projectNode({
+      id: '/www/app',
+      repos: [
+        {
+          id: '/www/app',
+          label: 'app',
+          path: '/www/app',
+          sessionCount: 1,
+          groups: [lane({ id: '/www/app::branch::main', label: 'main', isMain: true, path: '/www/app', sessions: [existing] })]
+        }
+      ]
+    })
+
+    const overlaid = overlayLiveLanes(project, [existing])
+
+    expect(overlaid.repos[0].groups.flatMap(g => g.sessions.map(s => s.id))).toEqual(['dup'])
+  })
+
+  it('adds a new session to an existing worktree lane keyed by a divergent id (matches by path)', () => {
+    // Backend keyed the worktree lane off a branch-style id (no live git probe),
+    // but the lane PATH is the worktree dir. A new session under that worktree
+    // must join the existing lane, not spawn a twin.
+    const existing = makeSession('/www/app/.worktrees/baby', { id: 'old' })
+
+    const project = projectNode({
+      id: '/www/app',
+      repos: [
+        {
+          id: '/www/app',
+          label: 'app',
+          path: '/www/app',
+          sessionCount: 1,
+          groups: [
+            lane({ id: '/www/app::branch::baby', label: 'baby', path: '/www/app/.worktrees/baby', sessions: [existing] })
+          ]
+        }
+      ]
+    })
+
+    const fresh = makeSession('/www/app/.worktrees/baby', { id: 'fresh' })
+
+    const overlaid = overlayLiveLanes(project, [existing, fresh])
+    const lanes = overlaid.repos[0].groups.filter(g => g.path === '/www/app/.worktrees/baby')
+
+    expect(lanes).toHaveLength(1)
+    expect(lanes[0].sessions.map(s => s.id).sort()).toEqual(['fresh', 'old'])
+  })
+
+  it('places a session into an out-of-tree (sibling) worktree lane by its path', () => {
+    // `hermes-agent-ci` is a linked worktree living BESIDE the repo, not under
+    // it — repo-root nesting fails, but the existing lane carries its real path.
+    const existing = makeSession('/www/app-ci', { id: 'old' })
+
+    const project = projectNode({
+      id: '/www/app',
+      repos: [
+        {
+          id: '/www/app',
+          label: 'app',
+          path: '/www/app',
+          sessionCount: 1,
+          groups: [
+            lane({ id: '/www/app::branch::main', label: 'main', isMain: true, path: '/www/app', sessions: [] }),
+            lane({ id: '/www/app-ci', label: 'app-ci', path: '/www/app-ci', sessions: [existing] })
+          ]
+        }
+      ]
+    })
+
+    const fresh = makeSession('/www/app-ci', { id: 'fresh' })
+
+    const overlaid = overlayLiveLanes(project, [existing, fresh])
+    const ci = overlaid.repos[0].groups.find(g => g.path === '/www/app-ci')
+    const main = overlaid.repos[0].groups.find(g => g.label === 'main')
+
+    expect(ci?.sessions.map(s => s.id).sort()).toEqual(['fresh', 'old'])
+    expect(main?.sessions ?? []).toHaveLength(0)
+  })
+
+  it('places into a visual-only discovered worktree lane after merge', () => {
+    const discovered = [{ path: '/www/app-retry', branch: 'bb/ci-install-retry', isMain: false, detached: false, locked: false }]
+    const groups = mergeRepoWorktreeGroups({ id: '/www/app', path: '/www/app', groups: [] }, discovered)
+
+    const project = projectNode({
+      id: '/www/app',
+      repos: [{ id: '/www/app', label: 'app', path: '/www/app', sessionCount: 0, groups }]
+    })
+
+    const fresh = makeSession('/www/app-retry', { id: 'fresh' })
+
+    const overlaid = overlayLiveLanes(project, [fresh])
+    const lane = overlaid.repos[0].groups.find(g => g.path === '/www/app-retry')
+
+    expect(lane?.sessions.map(s => s.id)).toEqual(['fresh'])
+  })
+
+  it('evicts a deleted/archived snapshot row (and drops the lane once empty)', () => {
+    const a = makeSession('/www/app', { id: 'keep', git_branch: 'main' })
+    const b = makeSession('/www/app/.worktrees/baby', { id: 'gone' })
+
+    const project = projectNode({
+      id: '/www/app',
+      repos: [
+        {
+          id: '/www/app',
+          label: 'app',
+          path: '/www/app',
+          sessionCount: 2,
+          groups: [
+            lane({ id: '/www/app::branch::main', label: 'main', isMain: true, path: '/www/app', sessions: [a] }),
+            lane({ id: '/www/app/.worktrees/baby', label: 'baby', path: '/www/app/.worktrees/baby', sessions: [b] })
+          ]
+        }
+      ]
+    })
+
+    // No live rows (both deleted from $sessions); only 'gone' is tombstoned.
+    const overlaid = overlayLiveLanes(project, [a], new Set(['gone']))
+
+    expect(overlaid.repos[0].groups.map(g => g.id)).toEqual(['/www/app::branch::main'])
+    expect(overlaid.repos[0].groups[0].sessions.map(s => s.id)).toEqual(['keep'])
+    expect(overlaid.sessionCount).toBe(1)
+  })
+})
+
+describe('overlayLivePreviews', () => {
+  it('merges live sessions into a project preview, live first, capped to the limit', () => {
+    const project = projectNode({
+      id: '/www/app',
+      previewSessions: [makeSession('/www/app', { id: 'old', started_at: 1, last_active: 1 })]
+    })
+
+    const live = [makeSession('/www/app', { id: 'fresh', started_at: 99, last_active: 99 })]
+
+    const previews = overlayLivePreviews([project], live, [], 3)
+
+    expect(previews['/www/app'].map(s => s.id)).toEqual(['fresh', 'old'])
+  })
+
+  it('evicts a deleted session from a project preview (snapshot + live)', () => {
+    const project = projectNode({
+      id: '/www/app',
+      previewSessions: [
+        makeSession('/www/app', { id: 'gone', started_at: 5, last_active: 5 }),
+        makeSession('/www/app', { id: 'old', started_at: 1, last_active: 1 })
+      ]
+    })
+
+    const previews = overlayLivePreviews([project], [], [], 3, new Set(['gone']))
+
+    expect(previews['/www/app'].map(s => s.id)).toEqual(['old'])
+  })
+})

apps/desktop/src/app/chat/sidebar/projects/workspace-groups.ts

@@ -0,0 +1,447 @@
+import type { HermesGitWorktree } from '@/global'
+import type { ProjectInfo, SessionInfo } from '@/hermes'
+
+// Session grouping is now computed authoritatively on the backend
+// (`tui_gateway/project_tree.py`, exposed via `projects.tree` /
+// `projects.project_sessions`). The desktop is a thin renderer: this module
+// only holds the render contract (the three tree interfaces) plus a couple of
+// pure helpers and the VISUAL-ONLY worktree enhancer that injects empty lanes
+// from `git worktree list`. It never decides session membership.
+
+export interface SidebarSessionGroup {
+  id: string
+  label: string
+  path: null | string
+  sessions: SessionInfo[]
+  // Profile color for the ALL-profiles view; absent for workspace groups.
+  color?: null | string
+  // True when this group is a repo's main checkout (vs a linked worktree).
+  isMain?: boolean
+  // True for the synthetic lane that collapses all of a repo's kanban task
+  // worktrees (`<repo>/.worktrees/t_*`) into one row, so a heavy board doesn't
+  // spray hundreds of throwaway branch lanes across the sidebar.
+  isKanban?: boolean
+  loadingMore?: boolean
+  mode?: 'profile' | 'source' | 'workspace'
+  onLoadMore?: () => void
+  sourceId?: string
+  totalCount?: number
+}
+
+/** A repo node: holds its branch/worktree lanes (`repo -> lane -> sessions`). */
+export interface SidebarWorkspaceTree {
+  id: string
+  label: string
+  path: null | string
+  groups: SidebarSessionGroup[]
+  sessionCount: number
+}
+
+/** A project node: human-named (or repo-derived), holds its repo subtree. */
+export interface SidebarProjectTree {
+  id: string
+  label: string
+  path: null | string
+  color?: null | string
+  icon?: null | string
+  archived?: boolean
+  // A git repo root promoted automatically (not a user-created projects.db row).
+  // Deletable = dismissable.
+  isAuto?: boolean
+  // The synthetic "No project" bucket for cwd-less sessions.
+  isNoProject?: boolean
+  repos: SidebarWorkspaceTree[]
+  sessionCount: number
+  // Max activity timestamp across the project's sessions (overview sort key).
+  lastActive?: number
+  // Up to N most-recent sessions for the overview preview (set by `projects.tree`).
+  previewSessions?: SessionInfo[]
+}
+
+/** Path split into segments, ignoring trailing slashes and mixed separators. */
+const segments = (path: string): string[] => path.replace(/[/\\]+$/, '').split(/[/\\]/).filter(Boolean)
+
+/** A path with trailing separators stripped, for stable equality checks. */
+const normalizePath = (path: null | string | undefined): string => (path ?? '').replace(/[/\\]+$/, '')
+
+/** Last path segment. */
+export const baseName = (path: string): string | undefined => segments(path).pop()
+
+// The `.worktrees` dir for a KANBAN-TASK worktree path, else null. Only matches
+// task worktrees (`<repo>/.worktrees/t_<hex>`, the `t_…` id kanban_db mints) so
+// the many ephemeral task worktrees collapse into one lane — while user-named
+// "New worktree" dirs (`<repo>/.worktrees/<slug>`) stay as their own lanes.
+const KANBAN_DIR_RE = /^(.*[/\\]\.worktrees)[/\\]t_[0-9a-f]+[/\\]?$/
+
+export function kanbanWorktreeDir(path: string): null | string {
+  return path.match(KANBAN_DIR_RE)?.[1] ?? null
+}
+
+/** Label for a main-checkout lane whose session recorded no branch. */
+export const DEFAULT_BRANCH_LABEL = 'main'
+
+/** The one definition of a main-checkout lane id (must match the backend tree). */
+export const branchLaneId = (repoRoot: string, branch?: string): string => `${repoRoot}::branch::${(branch ?? '').trim()}`
+
+/** A session's recency stamp (last activity, falling back to creation). */
+export const sessionRecency = (session: SessionInfo): number => session.last_active || session.started_at || 0
+
+/** Default-branch names that pin to the top and read as the repo's trunk. */
+const TRUNK_BRANCHES = new Set(['main', 'master', 'trunk', 'develop'])
+
+const isTrunkLane = (group: SidebarSessionGroup): boolean =>
+  Boolean(group.isMain) && TRUNK_BRANCHES.has(group.label.toLowerCase())
+
+/** A lane's recency = its most-recently-active session (empty lanes sink). */
+const laneActivity = (group: SidebarSessionGroup): number =>
+  group.sessions.reduce((max, session) => Math.max(max, sessionRecency(session)), 0)
+
+/**
+ * Trunk (main/master/...) sticks to the top; the kanban aggregate sinks to the
+ * bottom; everything between — branches and linked worktrees alike — sorts by
+ * most-recent activity (empty lanes fall last), label as the tiebreak.
+ */
+function compareWorktreeGroups(a: SidebarSessionGroup, b: SidebarSessionGroup): number {
+  if (isTrunkLane(a) !== isTrunkLane(b)) {
+    return isTrunkLane(a) ? -1 : 1
+  }
+
+  if (Boolean(a.isKanban) !== Boolean(b.isKanban)) {
+    return a.isKanban ? 1 : -1
+  }
+
+  const byActivity = laneActivity(b) - laneActivity(a)
+
+  return byActivity || a.label.localeCompare(b.label, undefined, { sensitivity: 'base' })
+}
+
+export function sortWorktreeGroups(groups: SidebarSessionGroup[]): SidebarSessionGroup[] {
+  return [...groups].sort(compareWorktreeGroups)
+}
+
+/**
+ * VISUAL enhancer only: inject empty lanes from a live `git worktree list` so a
+ * repo shows its branches/worktrees even when they have no Hermes sessions yet.
+ * The repo's real session lanes already come fully built from the backend
+ * (`projects.project_sessions`); this never adds or moves session rows, and it
+ * degrades to a no-op on remote backends (where the Electron probe returns
+ * nothing). Lanes already present (by id/path) are left untouched.
+ */
+export function mergeRepoWorktreeGroups(
+  repo: Pick<SidebarWorkspaceTree, 'groups' | 'id' | 'path'>,
+  discoveredWorktrees?: HermesGitWorktree[]
+): SidebarSessionGroup[] {
+  const merged = [...repo.groups]
+  const seenIds = new Set(merged.map(group => group.id))
+  const seenPaths = new Set(merged.map(group => group.path).filter((path): path is string => Boolean(path)))
+  // Dedupe by branch label too: a branch shows once even if it's checked out in
+  // a linked worktree AND already has a session lane (e.g. a worktree sitting on
+  // `main` must not spawn a second, empty "main" next to the trunk lane).
+  const seenLabels = new Set(merged.map(group => group.label.toLowerCase()))
+
+  for (const worktree of discoveredWorktrees ?? []) {
+    const wtPath = worktree.path?.trim()
+
+    if (!wtPath) {
+      continue
+    }
+
+    // Kanban task worktrees never get their own lane — they fold into the
+    // session-derived `::kanban` bucket. Listing every `git worktree list` entry
+    // here is exactly what blew the sidebar up to hundreds of empty rows.
+    if (!worktree.isMain && kanbanWorktreeDir(wtPath)) {
+      continue
+    }
+
+    const label = (worktree.isMain ? worktree.branch?.trim() || DEFAULT_BRANCH_LABEL : worktree.branch?.trim()) || baseName(wtPath) || wtPath
+    const id = worktree.isMain ? branchLaneId(repo.id, label) : wtPath
+
+    if (seenIds.has(id) || seenPaths.has(wtPath) || seenLabels.has(label.toLowerCase())) {
+      continue
+    }
+
+    merged.push({ id, isMain: worktree.isMain, label, path: wtPath, sessions: [] })
+    seenIds.add(id)
+    seenPaths.add(wtPath)
+    seenLabels.add(label.toLowerCase())
+  }
+
+  return sortWorktreeGroups(merged)
+}
+
+// ── Live session overlay ─────────────────────────────────────────────────────
+// The backend tree is a snapshot (sessions with >=1 message, refreshed on a
+// turn boundary). For parity with the flat Recents list — instant insertion of
+// a freshly-created session and the live "working" arc — we overlay the live
+// `$sessions` store onto the tree at render time. This is ADDITIVE only: the
+// backend still owns membership, structure, counts, and history. The overlay
+// just places rows already present in `$sessions` into the project/lane the
+// backend would put them in, using the same id scheme. Worktree/kanban folding
+// needs the backend common-root probe, so those rows are left for the next
+// tree refresh; the common case (a new main-checkout session) overlays here.
+
+/** True when `target` equals `folder` or is nested under it (segment-wise). */
+function isPathUnder(folder: string, target: string): boolean {
+  const f = segments(folder)
+  const t = segments(target)
+
+  if (!f.length || f.length > t.length) {
+    return false
+  }
+
+  return f.every((seg, i) => seg === t[i])
+}
+
+/**
+ * The project a plain main-checkout live session belongs to (overview
+ * membership) — explicit project by longest-prefix folder, else the repo root
+ * (the auto-project id). Returns null for sessions we can't place without the
+ * backend (cwd-less, kanban, or a linked worktree); those wait for the refresh.
+ */
+export function liveSessionProjectId(session: SessionInfo, explicitProjects: ProjectInfo[]): null | string {
+  const cwd = (session.cwd || '').trim()
+
+  if (!cwd || kanbanWorktreeDir(cwd)) {
+    return null
+  }
+
+  // No persisted repo root yet (brand-new session) → the cwd is the root.
+  const repoRoot = (session.git_repo_root || '').trim() || cwd
+  const underRepo = cwd === repoRoot || cwd.startsWith(`${repoRoot}/`) || cwd.startsWith(`${repoRoot}\\`)
+
+  if (!underRepo || cwd.startsWith(`${repoRoot}/.worktrees/`) || cwd.startsWith(`${repoRoot}\\.worktrees\\`)) {
+    return null
+  }
+
+  let projectId = ''
+  let bestLen = -1
+
+  for (const project of explicitProjects) {
+    if (project.archived) {
+      continue
+    }
+
+    for (const folder of project.folders) {
+      if (isPathUnder(folder.path, cwd) || isPathUnder(folder.path, repoRoot)) {
+        const len = segments(folder.path).length
+
+        if (len > bestLen) {
+          bestLen = len
+          projectId = project.id
+        }
+      }
+    }
+  }
+
+  return projectId || repoRoot
+}
+
+const upsertSession = (rows: SessionInfo[], session: SessionInfo): SessionInfo[] =>
+  [session, ...rows.filter(row => row.id !== session.id)].sort((a, b) => b.started_at - a.started_at)
+
+/**
+ * The lane a live session belongs to WITHIN a known repo root, by path — the
+ * entered project already knows its repo roots, so we don't need the session's
+ * (often-unset, on a fresh row) git_repo_root. Mirrors the backend's lane ids:
+ * main checkout -> branch lane, `.worktrees/t_<hex>` -> kanban, any other
+ * `.worktrees/<slug>` -> that worktree's own lane.
+ */
+function liveLaneForRepo(repoRoot: string, session: SessionInfo): null | SidebarSessionGroup {
+  const cwd = (session.cwd || '').trim()
+
+  if (!cwd || !isPathUnder(repoRoot, cwd)) {
+    return null
+  }
+
+  const wt = cwd.match(/^(.*[/\\]\.worktrees)[/\\]([^/\\]+)/)
+
+  if (wt) {
+    const [worktreeRoot, worktreesDir, slug] = [wt[0], wt[1], wt[2]]
+
+    return /^t_[0-9a-f]+$/.test(slug)
+      ? { id: `${repoRoot}::kanban`, isKanban: true, isMain: false, label: 'kanban', path: worktreesDir, sessions: [] }
+      : { id: worktreeRoot, isMain: false, label: slug, path: worktreeRoot, sessions: [] }
+  }
+
+  const branch = (session.git_branch || '').trim() || DEFAULT_BRANCH_LABEL
+
+  return { id: branchLaneId(repoRoot, branch), isMain: true, label: branch, path: repoRoot, sessions: [] }
+}
+
+const NO_REMOVED: ReadonlySet<string> = new Set()
+
+/**
+ * Reconcile ONE repo's lanes against the live `$sessions` cache: evict
+ * deleted/archived rows (`removed`) and inject freshly-created ones, so a lane
+ * mutates exactly like the flat Recents list. The backend snapshot stays the
+ * datasource for structure and off-page history; this is the optimistic layer
+ * on top (Apollo-style), reconciled away on the next snapshot refresh. Returns
+ * the same repo ref when nothing changes (memo-stable).
+ */
+export function overlayRepoLanes(
+  repo: SidebarWorkspaceTree,
+  live: SessionInfo[],
+  removed: ReadonlySet<string> = NO_REMOVED
+): SidebarWorkspaceTree {
+  const repoRoot = normalizePath(repo.path)
+  let changed = false
+
+  // Snapshot lanes minus anything the user just deleted/archived.
+  const lanes = repo.groups.map(g => {
+    if (!removed.size) {
+      return { ...g, sessions: [...g.sessions] }
+    }
+
+    const kept = g.sessions.filter(s => !removed.has(s.id))
+
+    changed ||= kept.length !== g.sessions.length
+
+    return { ...g, sessions: kept }
+  })
+
+  for (const session of live) {
+    const cwd = (session.cwd || '').trim()
+
+    if (removed.has(session.id) || !cwd) {
+      continue
+    }
+
+    // (1) Join an EXISTING worktree lane by its own path. A linked worktree can
+    // live anywhere on disk (often a repo sibling, e.g. `repo-ci`), so nesting
+    // under the repo root isn't reliable — but the lane carries its real dir.
+    // Longest match wins; skip the root lane so an in-tree `.worktrees/<slug>`
+    // session isn't swallowed by main.
+    let lane: SidebarSessionGroup | undefined
+    let bestLen = -1
+
+    for (const g of lanes) {
+      const lanePath = normalizePath(g.path)
+
+      if (!lanePath || lanePath === repoRoot || !isPathUnder(lanePath, cwd)) {
+        continue
+      }
+
+      const len = segments(lanePath).length
+
+      if (len > bestLen) {
+        bestLen = len
+        lane = g
+      }
+    }
+
+    // (2) Else place under the repo root via a computed lane (main / branch /
+    // in-tree `.worktrees` / kanban). Match by id, then path (the backend may
+    // key a worktree lane off the git-probed root OR a branch-style id), then
+    // the main-lane label; create it when the snapshot lacked it.
+    if (!lane) {
+      const placed = repo.path ? liveLaneForRepo(repo.path, session) : null
+
+      if (!placed) {
+        continue
+      }
+
+      const placedPath = normalizePath(placed.path)
+
+      lane =
+        lanes.find(g => g.id === placed.id) ??
+        (placedPath ? lanes.find(g => normalizePath(g.path) === placedPath) : undefined) ??
+        (placed.isMain ? lanes.find(g => g.isMain && g.label.toLowerCase() === placed.label.toLowerCase()) : undefined)
+
+      if (!lane) {
+        lane = { ...placed, sessions: [] }
+        lanes.push(lane)
+      }
+    }
+
+    lane.sessions = upsertSession(lane.sessions, session)
+    changed = true
+  }
+
+  if (!changed) {
+    return repo
+  }
+
+  // Drop lanes emptied by eviction (the server only emits non-empty lanes; the
+  // git-worktree enhancer re-adds any still-real worktree as an empty lane).
+  const groups = sortWorktreeGroups(lanes.filter(g => g.sessions.length > 0))
+
+  return { ...repo, groups, sessionCount: groups.reduce((n, g) => n + g.sessions.length, 0) }
+}
+
+/** Project-level overlay: {@link overlayRepoLanes} across every repo subtree. */
+export function overlayLiveLanes(
+  project: SidebarProjectTree,
+  live: SessionInfo[],
+  removed: ReadonlySet<string> = NO_REMOVED
+): SidebarProjectTree {
+  let changed = false
+
+  const repos = project.repos.map(repo => {
+    const next = overlayRepoLanes(repo, live, removed)
+
+    changed ||= next !== repo
+
+    return next
+  })
+
+  if (!changed) {
+    return project
+  }
+
+  return { ...project, repos, sessionCount: repos.reduce((n, repo) => n + repo.sessionCount, 0) }
+}
+
+/** Merge live sessions into per-project overview previews, keyed by project path. */
+export function overlayLivePreviews(
+  projects: SidebarProjectTree[],
+  live: SessionInfo[],
+  explicitProjects: ProjectInfo[],
+  limit: number,
+  removed: ReadonlySet<string> = new Set()
+): Record<string, SessionInfo[]> {
+  const byProject = new Map<string, SessionInfo[]>()
+
+  for (const session of live) {
+    if (removed.has(session.id)) {
+      continue
+    }
+
+    const projectId = liveSessionProjectId(session, explicitProjects)
+
+    if (!projectId) {
+      continue
+    }
+
+    const arr = byProject.get(projectId) ?? []
+    arr.push(session)
+    byProject.set(projectId, arr)
+  }
+
+  const out: Record<string, SessionInfo[]> = {}
+
+  for (const node of projects) {
+    if (!node.path) {
+      continue
+    }
+
+    const liveRows = byProject.get(node.id) ?? []
+    const base = (node.previewSessions ?? []).filter(session => !removed.has(session.id))
+
+    if (!liveRows.length && !base.length) {
+      continue
+    }
+
+    // Live rows take precedence (fresher title/activity/working state).
+    const map = new Map<string, SessionInfo>()
+
+    for (const session of [...liveRows, ...base]) {
+      if (!map.has(session.id)) {
+        map.set(session.id, session)
+      }
+    }
+
+    out[node.path] = [...map.values()].sort((a, b) => sessionRecency(b) - sessionRecency(a)).slice(0, limit)
+  }
+
+  return out
+}

apps/desktop/src/app/chat/sidebar/projects/workspace-header.tsx

@@ -0,0 +1,222 @@
+import type * as React from 'react'
+import { useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { Codicon } from '@/components/ui/codicon'
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from '@/components/ui/dialog'
+import { DisclosureCaret } from '@/components/ui/disclosure-caret'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger
+} from '@/components/ui/dropdown-menu'
+import { SanitizedInput } from '@/components/ui/sanitized-input'
+import { useI18n } from '@/i18n'
+import { gitRef } from '@/lib/sanitize'
+import { cn } from '@/lib/utils'
+import { notifyError } from '@/store/notifications'
+import { copyPath, revealPath, startWorkInRepo } from '@/store/projects'
+
+import { SidebarCount, SidebarRowLead } from '../chrome'
+
+// "+" affordance shared by repo and worktree headers — reveals on header hover.
+export function WorkspaceAddButton({ label, onClick }: { label: string; onClick: () => void }) {
+  return (
+    <button
+      aria-label={label}
+      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={onClick}
+      type="button"
+    >
+      <Codicon name="add" size="0.75rem" />
+    </button>
+  )
+}
+
+// Reveals the next page of already-loaded rows within a workspace/worktree.
+export function WorkspaceShowMoreButton({ count, label, onClick }: { count: number; label: string; onClick: () => void }) {
+  const { t } = useI18n()
+  const text = t.sidebar.showMoreIn(count, label)
+
+  return (
+    <button
+      aria-label={text}
+      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={onClick}
+      type="button"
+    >
+      <Codicon name="ellipsis" size="0.75rem" />
+    </button>
+  )
+}
+
+// Per-worktree actions (linked worktree lanes only), mirroring the session row
+// and ProjectMenu kebab: reveal in the file manager, copy path, and remove the
+// worktree (runs a real `git worktree remove` via the caller's confirm dialog).
+export function WorkspaceMenu({ path, onRemove }: { path: null | string; onRemove: () => void }) {
+  const { t } = useI18n()
+  const p = t.sidebar.projects
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <button
+          aria-label={p.menu}
+          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 data-[state=open]:opacity-100"
+          onClick={event => event.stopPropagation()}
+          type="button"
+        >
+          <Codicon name="kebab-vertical" size="0.75rem" />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-48" sideOffset={6}>
+        <DropdownMenuItem disabled={!path} onSelect={() => void revealPath(path)}>
+          <Codicon name="folder-opened" size="0.875rem" />
+          <span>{p.reveal}</span>
+        </DropdownMenuItem>
+        <DropdownMenuItem disabled={!path} onSelect={() => void copyPath(path)}>
+          <Codicon name="copy" size="0.875rem" />
+          <span>{p.copyPath}</span>
+        </DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem onSelect={onRemove} variant="destructive">
+          <Codicon name="trash" size="0.875rem" />
+          <span>{`${p.removeWorktree}…`}</span>
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+// "New worktree": prompt for a branch name, then git spins up a fresh worktree
+// for that branch under the repo (the lightest way) and we open a new session
+// inside it. Naming is explicit — no auto-generated `hermes/work-<ts>` trees.
+export function StartWorkButton({ repoPath, onStarted }: { repoPath: string; onStarted: (path: string) => void }) {
+  const { t } = useI18n()
+  const s = t.sidebar
+  const [open, setOpen] = useState(false)
+  const [name, setName] = useState('')
+  const [pending, setPending] = useState(false)
+
+  const submit = async () => {
+    const branch = name.trim()
+
+    if (pending || !repoPath || !branch) {
+      return
+    }
+
+    setPending(true)
+
+    try {
+      // Pass the typed value as both the dir slug source and the branch, so the
+      // branch is exactly what the user named (the dir is slugified git-side).
+      const result = await startWorkInRepo(repoPath, { branch, name: branch })
+
+      if (result) {
+        onStarted(result.path)
+        setOpen(false)
+        setName('')
+      }
+    } catch (err) {
+      notifyError(err, s.projects.startWorkFailed)
+    } finally {
+      setPending(false)
+    }
+  }
+
+  return (
+    <>
+      <button
+        aria-label={s.projects.startWork}
+        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/section:opacity-100 focus-visible:opacity-100"
+        onClick={() => setOpen(true)}
+        type="button"
+      >
+        <Codicon name="git-branch" size="0.75rem" />
+      </button>
+      <Dialog onOpenChange={setOpen} open={open}>
+        <DialogContent className="max-w-md">
+          <DialogHeader>
+            <DialogTitle>{s.projects.newWorktreeTitle}</DialogTitle>
+            <DialogDescription>{s.projects.newWorktreeDesc}</DialogDescription>
+          </DialogHeader>
+          <SanitizedInput
+            autoFocus
+            disabled={pending}
+            onKeyDown={event => {
+              if (event.key === 'Enter') {
+                event.preventDefault()
+                void submit()
+              } else if (event.key === 'Escape') {
+                setOpen(false)
+              }
+            }}
+            onValueChange={setName}
+            placeholder={s.projects.branchPlaceholder}
+            sanitize={gitRef}
+            value={name}
+          />
+          <DialogFooter>
+            <Button disabled={pending} onClick={() => setOpen(false)} type="button" variant="ghost">
+              {t.common.cancel}
+            </Button>
+            <Button disabled={pending || !name.trim()} onClick={() => void submit()} type="button">
+              {s.projects.startWork}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  )
+}
+
+// Collapsible header shared by the repo (emphasis) and worktree levels: a toggle
+// button with a leading glyph, plus an optional trailing action (the +).
+export function WorkspaceHeader({
+  action,
+  count,
+  emphasis = false,
+  icon,
+  label,
+  onToggle,
+  open
+}: {
+  action?: React.ReactNode
+  count: React.ReactNode
+  emphasis?: boolean
+  icon: React.ReactNode
+  label: string
+  onToggle: () => void
+  open: boolean
+}) {
+  return (
+    <div
+      className={cn(
+        'group/workspace flex min-h-6 items-center gap-1 px-2 pt-1 text-[0.6875rem]',
+        emphasis ? 'font-semibold text-(--ui-text-secondary)' : 'font-medium text-(--ui-text-tertiary)'
+      )}
+    >
+      <button
+        className={cn(
+          'flex min-w-0 flex-1 items-center gap-1.5 bg-transparent text-left',
+          emphasis ? 'hover:text-foreground' : 'hover:text-(--ui-text-secondary)'
+        )}
+        onClick={onToggle}
+        type="button"
+      >
+        <SidebarRowLead>{icon}</SidebarRowLead>
+        <span className="min-w-0 truncate">{label}</span>
+        <span className="shrink-0">
+          <SidebarCount>{count}</SidebarCount>
+        </span>
+        <DisclosureCaret
+          className="shrink-0 text-(--ui-text-tertiary) opacity-0 transition group-hover/workspace:opacity-100"
+          open={open}
+        />
+      </button>
+      {action}
+    </div>
+  )
+}

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

@@ -15,6 +15,7 @@ import { cn } from '@/lib/utils'
 import { $attentionSessionIds } from '@/store/session'
 import { canOpenSessionWindow, openSessionInNewWindow } from '@/store/windows'
 
+import { SidebarRowBody, SidebarRowGrab, SidebarRowLabel, SidebarRowLead, SidebarRowShell } from './chrome'
 import { SessionActionsMenu, SessionContextMenu } from './session-actions-menu'
 
 interface SidebarSessionRowProps extends React.ComponentProps<'div'> {
@@ -91,9 +92,37 @@ export function SidebarSessionRow({
       sessionId={session.id}
       title={title}
     >
-      <div
+      <SidebarRowShell
+        actions={
+          <div className="relative z-2 grid w-[1.375rem] place-items-center">
+            {!isWorking && (
+              <span className="pointer-events-none absolute right-6 top-1/2 min-w-6 -translate-y-1/2 text-right text-[0.625rem] leading-none text-(--ui-text-tertiary) opacity-0 transition-opacity group-hover:opacity-100">
+                {age}
+              </span>
+            )}
+            <SessionActionsMenu
+              onArchive={onArchive}
+              onDelete={onDelete}
+              onPin={onPin}
+              pinned={isPinned}
+              profile={session.profile}
+              sessionId={session.id}
+              title={title}
+            >
+              <Button
+                aria-label={r.actionsFor(title)}
+                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={r.sessionActions}
+                variant="ghost"
+              >
+                <Codicon name="kebab-vertical" size="0.875rem" />
+              </Button>
+            </SessionActionsMenu>
+          </div>
+        }
         className={cn(
-          'group relative grid min-h-[1.625rem] cursor-pointer grid-cols-[minmax(0,1fr)_1.375rem] items-center rounded-md transition-colors duration-100 ease-out hover:bg-(--ui-row-hover-background) hover:transition-none',
+          'group relative cursor-pointer transition-colors duration-100 ease-out hover:bg-(--ui-row-hover-background) hover:transition-none',
           isSelected && 'bg-(--ui-row-active-background)',
           isWorking && 'text-foreground',
           // Opaque surface while lifted so the dragged row erases what's under
@@ -123,9 +152,7 @@ export function SidebarSessionRow({
         {...rest}
       >
         {isWorking && !needsInput && <span aria-hidden="true" className="arc-border" />}
-        <button
-          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 => {
+        <SidebarRowBody className="z-0 group-hover:pr-12" onClick={event => {
             if (event.shiftKey) {
               event.preventDefault()
               event.stopPropagation()
@@ -150,49 +177,24 @@ export function SidebarSessionRow({
 
             onResume()
           }}
-          type="button"
         >
           {reorderable ? (
-            <span
-              {...dragHandleProps}
-              aria-label={handleLabel}
-              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. Width MUST match the non-reorderable dot
-                // column (w-3.5) so rows don't shift horizontally when reorder is
-                // toggled (e.g. scoped → ALL-profiles view).
-                'group/handle relative -my-0.5 grid w-3.5 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'
-              )}
-              data-reorder-handle
-              onClick={event => event.stopPropagation()}
+            <SidebarRowGrab
+              ariaLabel={handleLabel}
+              dragging={dragging}
+              dragHandleProps={dragHandleProps}
+              leadClassName={needsInput ? 'overflow-visible' : undefined}
             >
               <SidebarRowDot
                 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/handle:opacity-80 group-focus-within/handle:opacity-80 hover:text-(--ui-text-secondary)',
-                  dragging && 'text-(--ui-text-secondary) opacity-100'
-                )}
-                name="grabber"
-                size="0.75rem"
-              />
-            </span>
+            </SidebarRowGrab>
           ) : (
-            <span
-              className={cn(
-                'grid w-3.5 shrink-0 place-items-center',
-                needsInput ? 'overflow-visible' : 'overflow-hidden'
-              )}
-            >
+            <SidebarRowLead className={needsInput ? 'overflow-visible' : 'overflow-hidden'}>
               <SidebarRowDot isWorking={isWorking} needsInput={needsInput} />
-            </span>
+            </SidebarRowLead>
           )}
           {handoffSource && handoffLabel ? (
             <Tip label={r.handoffOrigin(handoffLabel)}>
@@ -203,37 +205,11 @@ export function SidebarSessionRow({
               />
             </Tip>
           ) : null}
-          <span className="min-w-0 flex-1 truncate text-[0.8125rem] font-normal text-(--ui-text-secondary) group-hover:text-foreground group-data-[working=true]:text-foreground/90">
+          <SidebarRowLabel className="flex-1 font-normal group-hover:text-foreground group-data-[working=true]:text-foreground/90">
             {title}
-          </span>
-        </button>
-        <div className="relative z-2 grid w-[1.375rem] place-items-center">
-          {!isWorking && (
-            <span className="pointer-events-none absolute right-6 top-1/2 min-w-6 -translate-y-1/2 text-right text-[0.625rem] leading-none text-(--ui-text-tertiary) opacity-0 transition-opacity group-hover:opacity-100">
-              {age}
-            </span>
-          )}
-          <SessionActionsMenu
-            onArchive={onArchive}
-            onDelete={onDelete}
-            onPin={onPin}
-            pinned={isPinned}
-            profile={session.profile}
-            sessionId={session.id}
-            title={title}
-          >
-            <Button
-              aria-label={r.actionsFor(title)}
-              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={r.sessionActions}
-              variant="ghost"
-            >
-              <Codicon name="ellipsis" size="0.875rem" />
-            </Button>
-          </SessionActionsMenu>
-        </div>
-      </div>
+          </SidebarRowLabel>
+        </SidebarRowBody>
+      </SidebarRowShell>
     </SessionContextMenu>
   )
 }

apps/desktop/src/app/chat/sidebar/workspace-groups.test.ts

@@ -1,149 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import type { HermesWorktreeInfo } from '@/global'
-import type { SessionInfo } from '@/types/hermes'
-
-import { uniqueCwds, workspaceGroupsFor, workspaceTreeFor, type WorktreeResolver } from './workspace-groups'
-
-let nextId = 0
-
-function makeSession(cwd: null | string, overrides: Partial<SessionInfo> = {}): SessionInfo {
-  return {
-    archived: false,
-    cwd,
-    ended_at: null,
-    id: `s${nextId++}`,
-    input_tokens: 0,
-    is_active: false,
-    last_active: 1_000,
-    message_count: 1,
-    model: 'claude',
-    output_tokens: 0,
-    preview: null,
-    source: 'cli',
-    started_at: 1_000,
-    title: null,
-    tool_call_count: 0,
-    ...overrides
-  }
-}
-
-const labels = (sessions: SessionInfo[]) => workspaceGroupsFor(sessions, 'No workspace').map(g => g.label)
-
-describe('workspaceGroupsFor', () => {
-  it('groups by full cwd, not by basename — same-named folders are separate groups', () => {
-    const groups = workspaceGroupsFor(
-      [makeSession('/a/hermes-agent/apps/desktop'), makeSession('/a/hermes-agent-wt-rtl/apps/desktop')],
-      'No workspace'
-    )
-
-    expect(groups).toHaveLength(2)
-  })
-
-  it('disambiguates colliding basenames by walking up the path', () => {
-    expect(
-      labels([makeSession('/a/hermes-agent/apps/desktop'), makeSession('/a/hermes-agent-wt-rtl/apps/desktop')])
-    ).toEqual(['hermes-agent/apps/desktop', 'hermes-agent-wt-rtl/apps/desktop'])
-  })
-
-  it('leaves a unique basename as its short label', () => {
-    expect(labels([makeSession('/a/hermes-agent/apps/desktop'), makeSession('/b/heval-py')])).toEqual([
-      'desktop',
-      'heval-py'
-    ])
-  })
-
-  it('grows the prefix past one segment when the parent also collides', () => {
-    expect(labels([makeSession('/x/proj/apps/desktop'), makeSession('/y/proj/apps/desktop')])).toEqual([
-      'x/proj/apps/desktop',
-      'y/proj/apps/desktop'
-    ])
-  })
-
-  it('keeps the synthetic no-workspace group untouched even if a real group shares its label', () => {
-    const groups = workspaceGroupsFor([makeSession(null), makeSession('/a/No workspace')], 'No workspace')
-    const noWorkspace = groups.find(g => g.path === null)
-
-    expect(noWorkspace?.label).toBe('No workspace')
-  })
-})
-
-const info = (over: Partial<HermesWorktreeInfo> & Pick<HermesWorktreeInfo, 'repoRoot' | 'worktreeRoot'>): HermesWorktreeInfo => ({
-  branch: null,
-  isMainWorktree: false,
-  ...over
-})
-
-describe('workspaceTreeFor', () => {
-  it('heuristic nests `<repo>-wt-<branch>` under its sibling repo', () => {
-    const tree = workspaceTreeFor(
-      [makeSession('/www/hermes-agent'), makeSession('/www/hermes-agent-wt-rtl')],
-      'No workspace'
-    )
-
-    expect(tree).toHaveLength(1)
-    expect(tree[0].label).toBe('hermes-agent')
-    expect(tree[0].groups.map(g => g.label).sort()).toEqual(['hermes-agent', 'rtl'])
-  })
-
-  it('git metadata is authoritative — worktrees group by repoRoot regardless of directory naming', () => {
-    const resolver: WorktreeResolver = cwd => {
-      if (cwd === '/www/hermes-agent') {
-        return info({ repoRoot: '/www/hermes-agent', worktreeRoot: '/www/hermes-agent', isMainWorktree: true, branch: 'main' })
-      }
-
-      if (cwd === '/elsewhere/ha-rtl') {
-        return info({ repoRoot: '/www/hermes-agent', worktreeRoot: '/elsewhere/ha-rtl', branch: 'rtl' })
-      }
-
-      return null
-    }
-
-    const tree = workspaceTreeFor(
-      [makeSession('/www/hermes-agent'), makeSession('/elsewhere/ha-rtl')],
-      'No workspace',
-      resolver
-    )
-
-    expect(tree).toHaveLength(1)
-    expect(tree[0].label).toBe('hermes-agent')
-    // The main checkout labels by directory (its branch is transient — using it
-    // would misattribute old sessions to the currently checked-out branch);
-    // linked worktrees label by branch.
-    expect(tree[0].groups.map(g => g.label)).toEqual(['hermes-agent', 'rtl'])
-  })
-
-  it('a standalone directory is its own parent (always parent → worktree → sessions)', () => {
-    const tree = workspaceTreeFor([makeSession('/www/heval-node')], 'No workspace')
-
-    expect(tree).toHaveLength(1)
-    expect(tree[0].label).toBe('heval-node')
-    expect(tree[0].groups).toHaveLength(1)
-    expect(tree[0].groups[0].label).toBe('heval-node')
-  })
-
-  it('aggregates session counts across a repo’s worktrees', () => {
-    const tree = workspaceTreeFor(
-      [makeSession('/www/ha'), makeSession('/www/ha-wt-x'), makeSession('/www/ha-wt-x')],
-      'No workspace'
-    )
-
-    const parent = tree.find(p => p.label === 'ha')
-
-    expect(parent?.sessionCount).toBe(3)
-  })
-
-  it('no-workspace sessions form their own parent', () => {
-    const tree = workspaceTreeFor([makeSession(null)], 'No workspace')
-
-    expect(tree).toHaveLength(1)
-    expect(tree[0].label).toBe('No workspace')
-    expect(tree[0].path).toBeNull()
-  })
-})
-
-describe('uniqueCwds', () => {
-  it('dedupes and drops empty/whitespace cwds', () => {
-    expect(uniqueCwds([makeSession('/a'), makeSession('/a'), makeSession(null), makeSession('   ')])).toEqual(['/a'])
-  })
-})

apps/desktop/src/app/chat/sidebar/workspace-groups.ts

@@ -1,326 +0,0 @@
-import type { HermesWorktreeInfo } from '@/global'
-import type { SessionInfo } from '@/hermes'
-
-export interface SidebarSessionGroup {
-  id: string
-  label: string
-  path: null | string
-  sessions: SessionInfo[]
-  // Profile color for the ALL-profiles view; absent for workspace groups.
-  color?: null | string
-  loadingMore?: boolean
-  mode?: 'profile' | 'source' | 'workspace'
-  onLoadMore?: () => void
-  sourceId?: string
-  totalCount?: number
-}
-
-const NO_WORKSPACE_ID = '__no_workspace__'
-
-/** Path split into segments, ignoring trailing slashes and mixed separators. */
-const segments = (path: string): string[] => path.replace(/[/\\]+$/, '').split(/[/\\]/).filter(Boolean)
-
-/** Last path segment. */
-export const baseName = (path: string): string | undefined => segments(path).pop()
-
-/** The segments above the basename. */
-const parentSegments = (path: string): string[] => segments(path).slice(0, -1)
-
-interface Labelable {
-  id: string
-  label: string
-  path: null | string
-}
-
-/**
- * Disambiguate groups whose basename collides (worktrees all end in the same
- * `apps/desktop`, sibling repos share a folder name, etc.) by walking up the
- * path and prepending parent segments until each colliding label is unique —
- * e.g. `hermes-agent/desktop` vs `hermes-agent-wt-rtl/desktop`. Groups with a
- * unique basename keep their short label untouched.
- */
-function disambiguateLabels(groups: Labelable[]): void {
-  const byLabel = new Map<string, Labelable[]>()
-
-  for (const group of groups) {
-    const bucket = byLabel.get(group.label)
-
-    if (bucket) {
-      bucket.push(group)
-    } else {
-      byLabel.set(group.label, [group])
-    }
-  }
-
-  for (const bucket of byLabel.values()) {
-    if (bucket.length < 2) {
-      continue
-    }
-
-    // Only groups backed by a real path can grow a prefix; the synthetic
-    // "No workspace" group has no path and stays as-is.
-    const pathed = bucket.filter(group => group.path)
-
-    if (pathed.length < 2) {
-      continue
-    }
-
-    const parents = new Map(pathed.map(group => [group.id, parentSegments(group.path!)]))
-    let depth = 1
-
-    // Grow the prefix one parent segment at a time until every label in the
-    // bucket is distinct, or we run out of parent segments to add.
-    while (depth <= Math.max(...pathed.map(g => parents.get(g.id)!.length))) {
-      const labels = new Map<string, number>()
-
-      for (const group of pathed) {
-        const segs = parents.get(group.id)!
-        const prefix = segs.slice(-depth).join('/')
-        const base = baseName(group.path!) ?? group.path!
-        group.label = prefix ? `${prefix}/${base}` : base
-        labels.set(group.label, (labels.get(group.label) ?? 0) + 1)
-      }
-
-      if ([...labels.values()].every(count => count === 1)) {
-        break
-      }
-
-      depth += 1
-    }
-  }
-}
-
-export function workspaceGroupsFor(
-  sessions: SessionInfo[],
-  noWorkspaceLabel: string,
-  options: { preserveSessionOrder?: boolean } = {}
-): SidebarSessionGroup[] {
-  const groups = new Map<string, SidebarSessionGroup>()
-
-  for (const session of sessions) {
-    const path = session.cwd?.trim() || ''
-    const id = path || NO_WORKSPACE_ID
-    const label = baseName(path) || path || noWorkspaceLabel
-
-    const group = groups.get(id) ?? { id, label, path: path || null, sessions: [] }
-    group.sessions.push(session)
-    groups.set(id, group)
-  }
-
-  if (!options.preserveSessionOrder) {
-    // Groups keep recency order (Map insertion = first-seen in the recency-sorted
-    // input, so an active project floats up), but rows *within* a group sort by
-    // creation time so they don't reshuffle every time a message lands — keeps
-    // muscle memory intact.
-    for (const group of groups.values()) {
-      group.sessions.sort((a, b) => b.started_at - a.started_at)
-    }
-  }
-
-  const result = [...groups.values()]
-  disambiguateLabels(result)
-
-  return result
-}
-
-/**
- * A worktree's main repo and all its linked worktrees collapse into ONE parent
- * (keyed by the repo root); each worktree is a child group; sessions hang off
- * the worktree they ran in. `parent → worktree → sessions`.
- */
-export interface SidebarWorkspaceTree {
-  id: string
-  label: string
-  path: null | string
-  groups: SidebarSessionGroup[]
-  sessionCount: number
-}
-
-/** Resolves a session cwd to git-worktree identity (from the local fs probe). */
-export type WorktreeResolver = (cwd: string) => HermesWorktreeInfo | null | undefined
-
-interface WorkspacePlacement {
-  parentKey: string
-  parentLabel: string
-  parentPath: string
-  worktreeKey: string
-  worktreeLabel: string
-  worktreePath: string
-}
-
-/** Replace a path's final segment, preserving its prefix + separators. */
-const withBaseName = (path: string, name: string): string =>
-  path.replace(/[/\\]+$/, '').replace(/[^/\\]+$/, name)
-
-/**
- * Path-only fallback for when git metadata is unavailable (remote backends,
- * unreadable paths). Mirrors the git layout: a `<repo>-wt-<branch>` directory
- * nests under its sibling `<repo>`; any other directory is its own repo root.
- */
-function placeByHeuristic(path: string): WorkspacePlacement | null {
-  const base = baseName(path)
-
-  if (!base) {
-    return null
-  }
-
-  const worktreeMatch = base.match(/^(.+)-wt-(.+)$/)
-
-  if (worktreeMatch) {
-    const repo = worktreeMatch[1]
-    const repoPath = withBaseName(path, repo)
-
-    return {
-      parentKey: repoPath,
-      parentLabel: repo,
-      parentPath: repoPath,
-      worktreeKey: path,
-      worktreeLabel: worktreeMatch[2],
-      worktreePath: path
-    }
-  }
-
-  return {
-    parentKey: path,
-    parentLabel: base,
-    parentPath: path,
-    worktreeKey: path,
-    worktreeLabel: base,
-    worktreePath: path
-  }
-}
-
-function placeWorkspace(path: string, resolver?: WorktreeResolver): WorkspacePlacement | null {
-  const info = resolver?.(path)
-
-  if (info?.repoRoot && info.worktreeRoot) {
-    const dirLabel = baseName(info.worktreeRoot) || info.worktreeRoot
-
-    return {
-      parentKey: info.repoRoot,
-      parentLabel: baseName(info.repoRoot) ?? info.repoRoot,
-      parentPath: info.repoRoot,
-      worktreeKey: info.worktreeRoot,
-      // The main checkout's branch is transient — it changes as you work, so a
-      // branch label would misattribute every past session to whatever branch
-      // is checked out *now*. Label it by directory. Linked worktrees are
-      // per-branch by construction, so branch is the clearest label there.
-      worktreeLabel: info.isMainWorktree ? dirLabel : info.branch || dirLabel,
-      worktreePath: info.worktreeRoot
-    }
-  }
-
-  return placeByHeuristic(path)
-}
-
-/** Unique, non-empty session cwds — the batch to probe for worktree info. */
-export function uniqueCwds(sessions: SessionInfo[]): string[] {
-  const seen = new Set<string>()
-
-  for (const session of sessions) {
-    const path = session.cwd?.trim()
-
-    if (path) {
-      seen.add(path)
-    }
-  }
-
-  return [...seen]
-}
-
-/**
- * Build the `parent → worktree → sessions` tree. Parents keep recency order
- * (first-seen in the recency-sorted input); worktree groups within a parent do
- * too, while rows inside a worktree sort by creation time (stable muscle memory,
- * matching `workspaceGroupsFor`).
- */
-export function workspaceTreeFor(
-  sessions: SessionInfo[],
-  noWorkspaceLabel: string,
-  resolver?: WorktreeResolver,
-  options: { preserveSessionOrder?: boolean } = {}
-): SidebarWorkspaceTree[] {
-  interface WorktreeEntry {
-    group: SidebarSessionGroup
-    parentKey: string
-    parentLabel: string
-    parentPath: string
-  }
-
-  const worktrees = new Map<string, WorktreeEntry>()
-  const noWorkspace: SessionInfo[] = []
-
-  for (const session of sessions) {
-    const path = session.cwd?.trim() || ''
-
-    if (!path) {
-      noWorkspace.push(session)
-
-      continue
-    }
-
-    const placement = placeWorkspace(path, resolver)
-
-    if (!placement) {
-      noWorkspace.push(session)
-
-      continue
-    }
-
-    let entry = worktrees.get(placement.worktreeKey)
-
-    if (!entry) {
-      entry = {
-        group: { id: placement.worktreeKey, label: placement.worktreeLabel, path: placement.worktreePath, sessions: [] },
-        parentKey: placement.parentKey,
-        parentLabel: placement.parentLabel,
-        parentPath: placement.parentPath
-      }
-      worktrees.set(placement.worktreeKey, entry)
-    }
-
-    entry.group.sessions.push(session)
-  }
-
-  if (!options.preserveSessionOrder) {
-    for (const entry of worktrees.values()) {
-      entry.group.sessions.sort((a, b) => b.started_at - a.started_at)
-    }
-  }
-
-  const parents = new Map<string, SidebarWorkspaceTree>()
-
-  for (const entry of worktrees.values()) {
-    let parent = parents.get(entry.parentKey)
-
-    if (!parent) {
-      parent = { id: entry.parentKey, label: entry.parentLabel, path: entry.parentPath, groups: [], sessionCount: 0 }
-      parents.set(entry.parentKey, parent)
-    }
-
-    parent.groups.push(entry.group)
-    parent.sessionCount += entry.group.sessions.length
-  }
-
-  const result = [...parents.values()]
-
-  if (noWorkspace.length) {
-    result.push({
-      id: NO_WORKSPACE_ID,
-      label: noWorkspaceLabel,
-      path: null,
-      groups: [{ id: NO_WORKSPACE_ID, label: noWorkspaceLabel, path: null, sessions: noWorkspace }],
-      sessionCount: noWorkspace.length
-    })
-  }
-
-  // Parents that collide on basename grow a path prefix; worktree labels that
-  // collide inside a parent do the same.
-  disambiguateLabels(result)
-
-  for (const parent of result) {
-    disambiguateLabels(parent.groups)
-  }
-
-  return result
-}

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

@@ -13,7 +13,7 @@ import { useSkinCommand } from '@/themes/use-skin-command'
 
 import { formatRefValue } from '../components/assistant-ui/directive-text'
 import { getCronJobs, getSessionMessages, listAllProfileSessions, type SessionInfo, triggerCronJob } from '../hermes'
-import { preserveLocalAssistantErrors, toChatMessages } from '../lib/chat-messages'
+import { type ChatMessage, chatMessageText, preserveLocalAssistantErrors, toChatMessages } from '../lib/chat-messages'
 import {
   isMessagingSource,
   LOCAL_SESSION_SOURCE_IDS,
@@ -52,7 +52,10 @@ import {
   $currentCwd,
   $freshDraftReady,
   $gatewayState,
+  $messages,
   $messagingSessions,
+  $resumeFailedSessionId,
+  $resumeExhaustedSessionId,
   $selectedStoredSessionId,
   $sessions,
   $workingSessionIds,
@@ -199,6 +202,8 @@ export function DesktopController() {
   const activeSessionId = useStore($activeSessionId)
   const currentCwd = useStore($currentCwd)
   const freshDraftReady = useStore($freshDraftReady)
+  const resumeFailedSessionId = useStore($resumeFailedSessionId)
+  const resumeExhaustedSessionId = useStore($resumeExhaustedSessionId)
   const filePreviewTarget = useStore($filePreviewTarget)
   const previewTarget = useStore($previewTarget)
   const selectedStoredSessionId = useStore($selectedStoredSessionId)
@@ -460,9 +465,9 @@ export function DesktopController() {
     void refreshMessagingSessions()
   }, [profileScope, refreshCronSessions, refreshCronJobs, refreshMessagingSessions])
 
-  const loadMoreSessions = useCallback(() => {
+  const loadMoreSessions = useCallback(async () => {
     bumpSessionsLimit()
-    void refreshSessions()
+    await refreshSessions()
   }, [refreshSessions])
 
   // Another window mutated the shared session list (e.g. a chat started in the
@@ -711,7 +716,9 @@ export function DesktopController() {
     }
 
     lastGatewayProfileRef.current = activeGatewayProfile
-    void refreshCurrentModel()
+    // Force: the new profile has its own default, so reseed even if the composer
+    // already shows the previous profile's model.
+    void refreshCurrentModel(true)
     void refreshActiveProfile()
   }, [activeGatewayProfile, refreshCurrentModel])
 
@@ -734,6 +741,49 @@ export function DesktopController() {
     [branchCurrentSession, refreshSessions]
   )
 
+  // Clear a failed turn's red error banner from the transcript. Errors are
+  // renderer-local state (never persisted), so dismissing is purely a view +
+  // session-cache edit. A message that errored before emitting any visible
+  // text is a bare error placeholder → drop it entirely; one that streamed
+  // partial output then failed keeps its content and just sheds the error.
+  // Both the per-runtime cache AND the live $messages view must be updated:
+  // `preserveLocalAssistantErrors` re-grafts any still-errored message it
+  // finds in the view onto the next session.info flush, so clearing only the
+  // cache would let the heartbeat resurrect the banner.
+  const dismissError = useCallback(
+    (messageId: string) => {
+      const runtimeSessionId = activeSessionIdRef.current
+
+      if (!runtimeSessionId) {
+        return
+      }
+
+      const clearErrorIn = (messages: ChatMessage[]): ChatMessage[] =>
+        messages.flatMap(message => {
+          if (message.id !== messageId || !message.error) {
+            return [message]
+          }
+
+          if (!chatMessageText(message).trim() && !message.parts.some(part => part.type !== 'text')) {
+            return []
+          }
+
+          return [{ ...message, error: undefined, pending: false }]
+        })
+
+      // View first: the flush below reads $messages as the "current" baseline
+      // for error preservation, so the banner must be gone from it before the
+      // cache update triggers a re-sync.
+      setMessages(clearErrorIn($messages.get()))
+
+      updateSessionState(runtimeSessionId, state => ({
+        ...state,
+        messages: clearErrorIn(state.messages)
+      }))
+    },
+    [activeSessionIdRef, updateSessionState]
+  )
+
   const startSessionInWorkspace = useCallback(
     (path: null | string) => {
       startFreshSessionDraft()
@@ -843,6 +893,8 @@ export function DesktopController() {
     gatewayState,
     locationPathname: location.pathname,
     resumeSession,
+    resumeFailedSessionId,
+    resumeExhaustedSessionId,
     routedSessionId,
     runtimeIdByStoredSessionIdRef,
     selectedStoredSessionId,
@@ -859,7 +911,6 @@ export function DesktopController() {
     gatewayLogLines,
     gatewayState,
     inferenceStatus,
-    modelMenuContent,
     openAgents,
     freshDraftReady,
     openCommandCenterSection,
@@ -981,6 +1032,7 @@ export function DesktopController() {
     <ChatView
       gateway={gatewayRef.current}
       maxVoiceRecordingSeconds={voiceMaxRecordingSeconds}
+      modelMenuContent={modelMenuContent}
       onAddContextRef={composer.addContextRefAttachment}
       onAddUrl={url => composer.addContextRefAttachment(`@url:${formatRefValue(url)}`, url)}
       onAttachDroppedItems={composer.attachDroppedItems}
@@ -992,6 +1044,7 @@ export function DesktopController() {
           void removeSession(selectedStoredSessionId)
         }
       }}
+      onDismissError={dismissError}
       onEdit={editMessage}
       onPasteClipboardImage={() => void composer.pasteClipboardImage()}
       onPickFiles={() => void composer.pickContextPaths('file')}
@@ -1000,6 +1053,7 @@ export function DesktopController() {
       onReload={reloadFromMessage}
       onRemoveAttachment={id => void composer.removeAttachment(id)}
       onRestoreToMessage={restoreToMessage}
+      onRetryResume={sessionId => void resumeSession(sessionId, true)}
       onSteer={steerPrompt}
       onSubmit={submitText}
       onThreadMessagesChange={handleThreadMessagesChange}

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

@@ -11,7 +11,7 @@ import {
   DialogHeader,
   DialogTitle
 } from '@/components/ui/dialog'
-import { Input } from '@/components/ui/input'
+import { SanitizedInput } from '@/components/ui/sanitized-input'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
 import { Textarea } from '@/components/ui/textarea'
 import {
@@ -26,6 +26,7 @@ import {
 } from '@/hermes'
 import { useI18n } from '@/i18n'
 import { AlertTriangle, Pencil, Save, Terminal, Trash2, Users } from '@/lib/icons'
+import { slug } from '@/lib/sanitize'
 import { cn } from '@/lib/utils'
 import { notify, notifyError } from '@/store/notifications'
 
@@ -519,12 +520,13 @@ function CreateProfileDialog({
             <label className="text-xs font-medium" htmlFor="new-profile-name">
               {p.nameLabel}
             </label>
-            <Input
+            <SanitizedInput
               aria-invalid={invalid}
               autoFocus
               id="new-profile-name"
-              onChange={event => setName(event.target.value)}
+              onValueChange={setName}
               placeholder="my-profile"
+              sanitize={slug}
               value={name}
             />
             <p className={cn('text-[0.66rem] leading-4', invalid ? 'text-destructive' : 'text-muted-foreground')}>
@@ -648,11 +650,12 @@ function RenameProfileDialog({
             <label className="text-xs font-medium" htmlFor="rename-profile-name">
               {p.newNameLabel}
             </label>
-            <Input
+            <SanitizedInput
               aria-invalid={invalid}
               autoFocus
               id="rename-profile-name"
-              onChange={event => setName(event.target.value)}
+              onValueChange={setName}
+              sanitize={slug}
               value={name}
             />
             <p className={cn('text-[0.66rem] leading-4', invalid ? 'text-destructive' : 'text-muted-foreground')}>

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

@@ -12,8 +12,20 @@ import type { TreeNode } from './use-project-tree'
 
 const ROW_HEIGHT = 22
 const INDENT = 10
-/** Base inset for every row; react-arborist owns paddingLeft for depth indent. */
-const TREE_ROW_INSET = 12
+/** Fixed base inset (`px-6.5`) layered on top of arborist's depth indent. */
+const TREE_ROW_INSET = '17px'
+
+function withTreeInset(paddingLeft: number | string | undefined): string {
+  if (typeof paddingLeft === 'number') {
+    return `calc(${paddingLeft}px + ${TREE_ROW_INSET})`
+  }
+
+  if (!paddingLeft) {
+    return TREE_ROW_INSET
+  }
+
+  return `calc(${paddingLeft} + ${TREE_ROW_INSET})`
+}
 
 interface ProjectTreeProps {
   collapseNonce: number
@@ -204,10 +216,7 @@ function ProjectTreeRow({
       ref={dragHandle}
       style={{
         ...style,
-        paddingLeft:
-          (typeof style.paddingLeft === 'number'
-            ? style.paddingLeft
-            : Number.parseFloat(String(style.paddingLeft ?? 0)) || 0) + TREE_ROW_INSET
+        paddingLeft: withTreeInset(style.paddingLeft)
       }}
     >
       {/* No chevron column — the folder icon (open/closed) already carries the

apps/desktop/src/app/right-sidebar/store.ts

@@ -9,3 +9,22 @@ export const $terminalTakeover = atom(storedBoolean(TAKEOVER_KEY, false))
 $terminalTakeover.subscribe(active => persistBoolean(TAKEOVER_KEY, active))
 
 export const setTerminalTakeover = (active: boolean) => $terminalTakeover.set(active)
+
+/** A command queued to run in the embedded terminal. The terminal pane flushes
+ *  (and clears) it once its session is live, so a value set before the pane
+ *  mounts still runs. Cleared after flush so a later remount can't replay it. */
+export const $terminalInjection = atom<null | string>(null)
+
+/** Open the terminal pane and run a command in it. Used to disconnect external
+ *  (CLI-managed) providers, which Hermes can't clear via the API — the user
+ *  sees exactly what runs instead of Hermes silently deleting their creds. */
+export const runInTerminal = (command: string) => {
+  const trimmed = command.trim()
+
+  if (!trimmed) {
+    return
+  }
+
+  setTerminalTakeover(true)
+  $terminalInjection.set(trimmed)
+}

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

@@ -10,6 +10,8 @@ import { triggerHaptic } from '@/lib/haptics'
 import { $filePreviewTarget, $previewTarget } from '@/store/preview'
 import { useTheme } from '@/themes/context'
 
+import { $terminalInjection } from '../store'
+
 import { makeTerminalReader, setActiveTerminalReader } from './buffer'
 import {
   isAddSelectionShortcut,
@@ -675,6 +677,28 @@ export function useTerminalSession({ cwd, onAddSelectionToChat }: UseTerminalSes
     return () => cancelAnimationFrame(raf)
   }, [activeTheme, themeName])
 
+  // Flush a queued command (e.g. a provider-disconnect) into the live session.
+  // Only active while open; the subscribe fires immediately, so a command set
+  // before this pane mounted runs as soon as the session is ready. Clearing the
+  // atom after writing stops a later remount from replaying a stale command.
+  useEffect(() => {
+    if (status !== 'open') {
+      return
+    }
+
+    return $terminalInjection.subscribe(command => {
+      const id = sessionIdRef.current
+
+      if (!command || !id) {
+        return
+      }
+
+      void window.hermesDesktop?.terminal?.write(id, `${command}\r`)
+      $terminalInjection.set(null)
+      termRef.current?.focus()
+    })
+  }, [status])
+
   return {
     addSelectionToChat,
     hostRef,

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

@@ -13,6 +13,7 @@ import {
   type GatewayEventPayload,
   reasoningPart,
   renderMediaTags,
+  textPart,
   upsertToolPart
 } from '@/lib/chat-messages'
 import { coerceGatewayText, coerceThinkingText, normalizePersonalityValue } from '@/lib/chat-runtime'
@@ -1080,6 +1081,32 @@ export function useMessageStream({
           // completions / watch matches here — re-sync the status stack.
           void refreshBackgroundProcesses(sessionId)
         }
+      } else if (event.type === 'review.summary') {
+        // Self-improvement background review saved something to memory/skills
+        // and emitted a persistent summary (Python formats it as
+        // "💾 Self-improvement review: …"). The CLI prints this via
+        // prompt_toolkit and the Ink TUI renders it as a system line; the
+        // desktop has neither, so without this handler the skill/memory
+        // change happens silently. Surface it as a persistent system message
+        // in the transcript so the user is always informed — it must not be a
+        // transient toast that can be missed.
+        const text = coerceGatewayText(payload?.text).trim()
+
+        if (text && sessionId) {
+          flushQueuedDeltas(sessionId)
+          updateSessionState(sessionId, state => ({
+            ...state,
+            messages: [
+              ...state.messages,
+              {
+                id: `review-summary-${Date.now()}`,
+                role: 'system',
+                parts: [textPart(text)],
+                timestamp: Math.floor(Date.now() / 1000)
+              }
+            ]
+          }))
+        }
       } else if (event.type === 'error') {
         const errorMessage = payload?.message || 'Hermes reported an error'
         const looksLikeProviderSetup = isProviderSetupErrorMessage(errorMessage)
@@ -1102,8 +1129,13 @@ export function useMessageStream({
 
         if (looksLikeProviderSetup) {
           requestDesktopOnboarding(errorMessage)
-        } else if (isActiveEvent) {
+        } else {
+          // Toast globally, not just when the failing thread is focused: a
+          // turn-ending error (e.g. out of funds) blocks every thread, so the
+          // inline error alone is too easy to miss. The stable id collapses the
+          // same error from multiple blocked threads into one toast.
           notify({
+            id: `gateway-error:${errorMessage}`,
             kind: 'error',
             title: 'Hermes error',
             message: errorMessage

apps/desktop/src/app/session/hooks/use-model-controls.test.tsx

@@ -130,7 +130,6 @@ describe('useModelControls', () => {
     await expect(
       controls.selectModel({
         model: 'claude-sonnet-4.6',
-        persistGlobal: false,
         provider: 'anthropic'
       })
     ).resolves.toBe(true)
@@ -143,26 +142,57 @@ describe('useModelControls', () => {
     expect(requestGateway).not.toHaveBeenCalledWith('slash.exec', expect.anything())
   })
 
-  it('keeps the global path on setGlobalModel when there is no active session', async () => {
-    setGlobalModel.mockResolvedValue(undefined)
+  it('stores a no-session pick as UI state with no gateway or global write', async () => {
+    const requestGateway = vi.fn()
     let controls!: Controls
 
     render(
       <Harness
         activeSessionId={null}
         onReady={value => (controls = value)}
-        requestGateway={vi.fn()}
+        requestGateway={requestGateway}
       />
     )
 
     await expect(
       controls.selectModel({
         model: 'claude-sonnet-4.6',
-        persistGlobal: false,
         provider: 'anthropic'
       })
     ).resolves.toBe(true)
 
-    expect(setGlobalModel).toHaveBeenCalledWith('anthropic', 'claude-sonnet-4.6')
+    // The pick is plain UI state; session.create ships it later. Nothing touches
+    // the gateway or the profile default here.
+    expect($currentModel.get()).toBe('claude-sonnet-4.6')
+    expect($currentProvider.get()).toBe('anthropic')
+    expect(requestGateway).not.toHaveBeenCalled()
+    expect(setGlobalModel).not.toHaveBeenCalled()
+  })
+
+  it('seeds an empty composer model from global but never clobbers a pick', async () => {
+    vi.mocked(getGlobalModelInfo).mockResolvedValue({ model: 'openai/gpt-5.5', provider: 'openai-codex' })
+
+    const { result } = renderHook(() =>
+      useModelControls({
+        activeSessionId: null,
+        queryClient: new QueryClient(),
+        requestGateway: vi.fn()
+      })
+    )
+
+    // Empty → seeds the default.
+    await result.current.refreshCurrentModel()
+    expect($currentModel.get()).toBe('openai/gpt-5.5')
+
+    // A user pick must survive the lifecycle refreshes that fire on boot / fresh
+    // draft / session events.
+    setCurrentModel('anthropic/claude-sonnet-4.6')
+    setCurrentProvider('anthropic')
+    await result.current.refreshCurrentModel()
+    expect($currentModel.get()).toBe('anthropic/claude-sonnet-4.6')
+
+    // A profile swap forces a reseed to the new profile's default.
+    await result.current.refreshCurrentModel(true)
+    expect($currentModel.get()).toBe('openai/gpt-5.5')
   })
 })

apps/desktop/src/app/session/hooks/use-model-controls.ts

@@ -1,7 +1,7 @@
 import { type QueryClient } from '@tanstack/react-query'
 import { useCallback } from 'react'
 
-import { getGlobalModelInfo, setGlobalModel } from '@/hermes'
+import { getGlobalModelInfo } from '@/hermes'
 import { useI18n } from '@/i18n'
 import { notifyError } from '@/store/notifications'
 import {
@@ -15,7 +15,6 @@ import type { ModelOptionsResponse } from '@/types/hermes'
 
 interface ModelSelection {
   model: string
-  persistGlobal: boolean
   provider: string
 }
 
@@ -28,6 +27,7 @@ interface ModelControlsOptions {
 export function useModelControls({ activeSessionId, queryClient, requestGateway }: ModelControlsOptions) {
   const { t } = useI18n()
   const copy = t.desktop
+
   const updateModelOptionsCache = useCallback(
     (provider: string, model: string, includeGlobal: boolean) => {
       const patch = (prev: ModelOptionsResponse | undefined) => ({ ...(prev ?? {}), provider, model })
@@ -41,14 +41,24 @@ export function useModelControls({ activeSessionId, queryClient, requestGateway
     [activeSessionId, queryClient]
   )
 
-  const refreshCurrentModel = useCallback(async () => {
+  // Seed the composer's model state from the profile default. `force` reseeds
+  // for a profile swap (the new profile has its own default); otherwise this
+  // only fills an EMPTY selection so a user's pick (plain UI state in
+  // $currentModel) survives the lifecycle refreshes that fire on boot / fresh
+  // draft / session events. A live session owns the footer, so skip entirely.
+  const refreshCurrentModel = useCallback(async (force = false) => {
     try {
+      if ($activeSessionId.get()) {
+        return
+      }
+
+      if (!force && $currentModel.get()) {
+        return
+      }
+
       const result = await getGlobalModelInfo()
 
-      // A resumed/live session owns the footer model state. Global config
-      // refreshes (gateway boot, profile swap, settings save) must not clobber
-      // the active chat's runtime model/provider in the status bar.
-      if ($activeSessionId.get()) {
+      if ($activeSessionId.get() || (!force && $currentModel.get())) {
         return
       }
 
@@ -64,12 +74,14 @@ export function useModelControls({ activeSessionId, queryClient, requestGateway
     }
   }, [])
 
-  // Returns whether the switch succeeded so callers can await it before
-  // applying follow-up changes (e.g. editing a model's reasoning/fast must land
-  // on the right active model — bail rather than write to the previous one).
+  // Returns whether the switch succeeded so callers can await it before applying
+  // follow-up changes. The composer model is plain UI state: with no live
+  // session it's just stored (and shipped on the next session.create); with one
+  // it's scoped to that session via config.set. It NEVER writes the profile
+  // default — that lives in Settings → Model — so picking a model here can't
+  // silently mutate global config.
   const selectModel = useCallback(
     async (selection: ModelSelection): Promise<boolean> => {
-      const includeGlobal = selection.persistGlobal || !activeSessionId
       // Snapshot for rollback: the switch is applied optimistically, so a
       // failure must restore the prior model/provider (store + query cache)
       // rather than leave the UI showing a model the backend never selected.
@@ -78,42 +90,34 @@ export function useModelControls({ activeSessionId, queryClient, requestGateway
 
       setCurrentModel(selection.model)
       setCurrentProvider(selection.provider)
-      updateModelOptionsCache(selection.provider, selection.model, includeGlobal)
+      updateModelOptionsCache(selection.provider, selection.model, !activeSessionId)
+
+      // No live session yet: the pick is pure UI state. session.create reads
+      // $currentModel/$currentProvider and applies it as that session's override.
+      if (!activeSessionId) {
+        return true
+      }
 
       try {
-        if (activeSessionId) {
-          await requestGateway('config.set', {
-            session_id: activeSessionId,
-            key: 'model',
-            value: `${selection.model} --provider ${selection.provider}${selection.persistGlobal ? ' --global' : ''}`
-          })
+        await requestGateway('config.set', {
+          session_id: activeSessionId,
+          key: 'model',
+          value: `${selection.model} --provider ${selection.provider}`
+        })
 
-          if (selection.persistGlobal) {
-            void refreshCurrentModel()
-          }
-
-          void queryClient.invalidateQueries({
-            queryKey: selection.persistGlobal ? ['model-options'] : ['model-options', activeSessionId]
-          })
-
-          return true
-        }
-
-        await setGlobalModel(selection.provider, selection.model)
-        void refreshCurrentModel()
-        void queryClient.invalidateQueries({ queryKey: ['model-options'] })
+        void queryClient.invalidateQueries({ queryKey: ['model-options', activeSessionId] })
 
         return true
       } catch (err) {
         setCurrentModel(prevModel)
         setCurrentProvider(prevProvider)
-        updateModelOptionsCache(prevProvider, prevModel, includeGlobal)
+        updateModelOptionsCache(prevProvider, prevModel, !activeSessionId)
         notifyError(err, copy.modelSwitchFailed)
 
         return false
       }
     },
-    [activeSessionId, copy.modelSwitchFailed, queryClient, refreshCurrentModel, requestGateway, updateModelOptionsCache]
+    [activeSessionId, copy.modelSwitchFailed, queryClient, requestGateway, updateModelOptionsCache]
   )
 
   return { refreshCurrentModel, selectModel, updateModelOptionsCache }

apps/desktop/src/app/session/hooks/use-route-resume.test.tsx

@@ -2,6 +2,8 @@ import { cleanup, render } from '@testing-library/react'
 import type { MutableRefObject } from 'react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
+import { $resumeExhaustedSessionId, setResumeExhaustedSessionId } from '@/store/session'
+
 import { useRouteResume } from './use-route-resume'
 
 interface HarnessProps {
@@ -13,6 +15,8 @@ interface HarnessProps {
   gatewayState: string
   locationPathname: string
   resumeSession: (sessionId: string, focus: boolean) => Promise<unknown>
+  resumeFailedSessionId?: null | string
+  resumeExhaustedSessionId?: null | string
   routedSessionId: null | string
   runtimeIdByStoredSessionIdRef: MutableRefObject<Map<string, string>>
   selectedStoredSessionId: null | string
@@ -20,8 +24,12 @@ interface HarnessProps {
   startFreshSessionDraft: (focus: boolean) => unknown
 }
 
-function RouteResumeHarness(props: HarnessProps) {
-  useRouteResume(props)
+function RouteResumeHarness({
+  resumeFailedSessionId = null,
+  resumeExhaustedSessionId = null,
+  ...props
+}: HarnessProps) {
+  useRouteResume({ ...props, resumeExhaustedSessionId, resumeFailedSessionId })
 
   return null
 }
@@ -256,3 +264,212 @@ describe('useRouteResume', () => {
     expect(resumeSession).toHaveBeenCalledWith('session-1', true)
   })
 })
+
+describe('useRouteResume bounded auto-retry after a failed resume', () => {
+  afterEach(() => {
+    cleanup()
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+    setResumeExhaustedSessionId(null)
+  })
+
+  // Common stranded-window props: gateway open, route on the session, no runtime
+  // yet, and the ref already synced to the route (resumeSession sets it at entry
+  // before failing) — the exact state that defeats the main effect's self-heal.
+  function strandedProps(resumeSession: (sid: string, focus: boolean) => Promise<unknown>) {
+    return {
+      activeSessionId: null,
+      activeSessionIdRef: { current: null } as MutableRefObject<null | string>,
+      creatingSessionRef: { current: false },
+      currentView: 'chat',
+      freshDraftReady: false,
+      gatewayState: 'open',
+      locationPathname: '/session-1',
+      resumeSession,
+      routedSessionId: 'session-1',
+      runtimeIdByStoredSessionIdRef: { current: new Map<string, string>() },
+      selectedStoredSessionId: 'session-1',
+      // Synced to the route by the failed resume's synchronous entry-write.
+      selectedStoredSessionIdRef: { current: 'session-1' } as MutableRefObject<null | string>,
+      startFreshSessionDraft: vi.fn()
+    }
+  }
+
+  it('retries the resume on backoff when the routed session is flagged as failed', () => {
+    vi.useFakeTimers()
+    const resumeSession = vi.fn(async () => undefined)
+
+    render(<RouteResumeHarness {...strandedProps(resumeSession)} resumeFailedSessionId="session-1" />)
+
+    // The main effect fires one resume on mount (pathname-changed). Clear it so
+    // we assert purely the bounded-retry effect's scheduled retry below.
+    resumeSession.mockClear()
+
+    // No immediate fire — the retry is scheduled behind the backoff timer.
+    expect(resumeSession).not.toHaveBeenCalled()
+
+    // First backoff window (1s) elapses → one retry.
+    vi.advanceTimersByTime(1_000)
+    expect(resumeSession).toHaveBeenCalledTimes(1)
+    expect(resumeSession).toHaveBeenCalledWith('session-1', true)
+  })
+
+  it('does NOT retry a failed session that is not the routed one', () => {
+    vi.useFakeTimers()
+    const resumeSession = vi.fn(async () => undefined)
+
+    // The failure flag points at a different session than the route.
+    render(<RouteResumeHarness {...strandedProps(resumeSession)} resumeFailedSessionId="other-session" />)
+    resumeSession.mockClear() // drop the mount resume
+
+    vi.advanceTimersByTime(10_000)
+    expect(resumeSession).not.toHaveBeenCalled()
+  })
+
+  it('skips the scheduled retry if the session already recovered when the timer fires', () => {
+    vi.useFakeTimers()
+    const resumeSession = vi.fn(async () => undefined)
+    const props = strandedProps(resumeSession)
+
+    render(<RouteResumeHarness {...props} resumeFailedSessionId="session-1" />)
+    resumeSession.mockClear() // drop the mount resume
+
+    // A resume landed while we waited: runtime is now bound.
+    props.activeSessionIdRef.current = 'runtime-1'
+
+    vi.advanceTimersByTime(8_000)
+    expect(resumeSession).not.toHaveBeenCalled()
+  })
+
+  it('stops retrying after MAX_RESUME_RETRIES consecutive failures', () => {
+    vi.useFakeTimers()
+    const resumeSession = vi.fn(async () => undefined)
+    const props = strandedProps(resumeSession)
+
+    // Model the real re-arm loop: resumeSession clears $resumeFailedSessionId at
+    // entry (null) and a repeat failure re-sets it ('session-1'). That null->id
+    // toggle is what re-runs the effect and advances the bounded counter. The
+    // routed session never changes, so the counter is NOT reset between cycles.
+    const { rerender } = render(<RouteResumeHarness {...props} resumeFailedSessionId="session-1" />)
+    resumeSession.mockClear() // drop the mount resume; count only the retries
+
+    for (let i = 0; i < 8; i += 1) {
+      vi.advanceTimersByTime(8_000) // fire the scheduled retry (if any)
+      rerender(<RouteResumeHarness {...props} resumeFailedSessionId={null} />) // cleared at entry
+      rerender(<RouteResumeHarness {...props} resumeFailedSessionId="session-1" />) // re-armed on failure
+    }
+
+    // Capped at MAX_RESUME_RETRIES (4): a persistently dead backend can't
+    // hot-loop the resume forever.
+    expect(resumeSession.mock.calls.length).toBe(4)
+
+    // Once auto-retry gives up, the exhausted latch is armed for the routed
+    // session so the chat view can swap the perpetual loader for an explicit
+    // error + manual Retry instead of spinning forever.
+    expect($resumeExhaustedSessionId.get()).toBe('session-1')
+  })
+
+  it('does not arm the exhausted latch while retries remain', () => {
+    vi.useFakeTimers()
+    const resumeSession = vi.fn(async () => undefined)
+    const props = strandedProps(resumeSession)
+
+    const { rerender } = render(<RouteResumeHarness {...props} resumeFailedSessionId="session-1" />)
+    resumeSession.mockClear()
+
+    // Two failure cycles — still under the 4-retry cap, so the latch must stay
+    // clear and the loader keeps spinning (auto-recovery hasn't given up yet).
+    for (let i = 0; i < 2; i += 1) {
+      vi.advanceTimersByTime(8_000)
+      rerender(<RouteResumeHarness {...props} resumeFailedSessionId={null} />)
+      rerender(<RouteResumeHarness {...props} resumeFailedSessionId="session-1" />)
+    }
+
+    expect($resumeExhaustedSessionId.get()).toBeNull()
+  })
+
+  it('clears a stale exhausted latch when the route moves off the stranded session', () => {
+    vi.useFakeTimers()
+    const resumeSession = vi.fn(async () => undefined)
+    const props = strandedProps(resumeSession)
+
+    // Pre-arm the latch as if this session had exhausted its retries.
+    setResumeExhaustedSessionId('session-1')
+
+    // Route is now on a different, healthy session that is not flagged as
+    // failed — the retry effect's "route moved off" branch clears the latch.
+    render(
+      <RouteResumeHarness
+        {...props}
+        activeSessionId="runtime-2"
+        activeSessionIdRef={{ current: 'runtime-2' }}
+        locationPathname="/session-2"
+        resumeFailedSessionId={null}
+        routedSessionId="session-2"
+        selectedStoredSessionId="session-2"
+        selectedStoredSessionIdRef={{ current: 'session-2' }}
+      />
+    )
+
+    expect($resumeExhaustedSessionId.get()).toBeNull()
+  })
+
+  it('resets the retry counter for a fresh backoff cycle when the exhausted latch clears (manual retry, same session)', () => {
+    vi.useFakeTimers()
+    const resumeSession = vi.fn(async () => undefined)
+    const props = strandedProps(resumeSession)
+
+    // Phase A — exhaust the bounded auto-retry (counter → MAX) like a dead
+    // backend. The resumeExhaustedSessionId prop stays null here: the hook sets
+    // the store, which doesn't feed back into the prop in this harness.
+    const { rerender } = render(<RouteResumeHarness {...props} resumeFailedSessionId="session-1" />)
+    resumeSession.mockClear()
+    for (let i = 0; i < 8; i += 1) {
+      vi.advanceTimersByTime(8_000)
+      rerender(<RouteResumeHarness {...props} resumeFailedSessionId={null} />)
+      rerender(<RouteResumeHarness {...props} resumeFailedSessionId="session-1" />)
+    }
+    expect(resumeSession.mock.calls.length).toBe(4) // capped
+    expect($resumeExhaustedSessionId.get()).toBe('session-1')
+
+    // Phase B — user clicks Retry on the SAME stranded session. resumeSession
+    // clears both latches at entry; the exhausted latch's armed->cleared edge
+    // must reset the attempt counter so a fresh bounded cycle runs, not a single
+    // one-shot attempt that immediately re-arms the error. Model the prop
+    // transitions: reflect the armed latch, then clear it (retry), then re-arm
+    // the failure latch on the fresh failure.
+    resumeSession.mockClear()
+    rerender(<RouteResumeHarness {...props} resumeExhaustedSessionId="session-1" resumeFailedSessionId="session-1" />)
+    rerender(<RouteResumeHarness {...props} resumeExhaustedSessionId={null} resumeFailedSessionId={null} />)
+    rerender(<RouteResumeHarness {...props} resumeExhaustedSessionId={null} resumeFailedSessionId="session-1" />)
+
+    // A real retry fires again instead of staying pinned at MAX (which would
+    // dispatch nothing). Without the reset the counter stays >= MAX and this
+    // advance dispatches zero resumes.
+    vi.advanceTimersByTime(8_000)
+    expect(resumeSession.mock.calls.length).toBeGreaterThan(0)
+  })
+
+  it('does not burn retry attempts on unrelated re-renders during the backoff window', () => {
+    vi.useFakeTimers()
+    const props = strandedProps(vi.fn())
+
+    // Mount schedules the first backoff timer. Then re-render repeatedly with a
+    // fresh resumeSession identity (referential instability — a real dep change
+    // for the retry effect) WITHOUT ever letting the timer fire. The old code
+    // incremented the attempt counter at schedule time, so >= MAX re-renders
+    // armed the exhausted error with zero resumes actually dispatched. The fix
+    // only advances the counter when a timer truly fires, so the latch stays
+    // clear no matter how many spurious re-renders happen mid-backoff.
+    const { rerender } = render(
+      <RouteResumeHarness {...props} resumeFailedSessionId="session-1" resumeSession={vi.fn(async () => undefined)} />
+    )
+    for (let j = 0; j < 8; j += 1) {
+      rerender(
+        <RouteResumeHarness {...props} resumeFailedSessionId="session-1" resumeSession={vi.fn(async () => undefined)} />
+      )
+    }
+
+    expect($resumeExhaustedSessionId.get()).toBeNull()
+  })
+})

apps/desktop/src/app/session/hooks/use-route-resume.ts

@@ -1,6 +1,7 @@
 import { type MutableRefObject, useEffect, useRef } from 'react'
 
 import { isNewChatRoute } from '@/app/routes'
+import { setResumeExhaustedSessionId } from '@/store/session'
 
 interface RouteResumeOptions {
   activeSessionId: string | null
@@ -11,6 +12,17 @@ interface RouteResumeOptions {
   gatewayState: string | undefined
   locationPathname: string
   resumeSession: (sessionId: string, focus: boolean) => Promise<unknown>
+  // Stored-session id whose most recent resume failed terminally (set by
+  // useSessionActions, mirrored from $resumeFailedSessionId). While this equals
+  // routedSessionId the window would otherwise latch on the loader forever, so
+  // the bounded-retry effect below re-attempts the resume.
+  resumeFailedSessionId: string | null
+  // Stored-session id whose bounded auto-retry has EXHAUSTED (mirrored from
+  // $resumeExhaustedSessionId). Only resumeSession clears this latch (manual
+  // Retry / reconnect / reselect) — the auto-retry loop never does — so its
+  // armed->cleared edge is an unambiguous "give me a fresh backoff cycle"
+  // signal the effect below uses to reset the attempt counter.
+  resumeExhaustedSessionId: string | null
   routedSessionId: string | null
   runtimeIdByStoredSessionIdRef: MutableRefObject<Map<string, string>>
   selectedStoredSessionId: string | null
@@ -18,6 +30,19 @@ interface RouteResumeOptions {
   startFreshSessionDraft: (focus: boolean) => unknown
 }
 
+// Bounded auto-retry for a stranded session window. A resume can fail terminally
+// (gateway RPC reject + REST fallback failure) on a transiently wedged backend —
+// dead provider key, a runaway turn hogging the dispatcher, flaky DNS. Without a
+// retry the loader latches forever. We retry with backoff, capped, so a
+// genuinely dead backend doesn't hot-loop the resume.
+const MAX_RESUME_RETRIES = 4
+const RESUME_RETRY_BASE_MS = 1_000
+const RESUME_RETRY_MAX_MS = 8_000
+
+function resumeRetryDelayMs(attempt: number): number {
+  return Math.min(RESUME_RETRY_MAX_MS, RESUME_RETRY_BASE_MS * 2 ** attempt)
+}
+
 // HashRouter boot edge case: pathname briefly reads `/` before the hash is
 // parsed. If the hash references a real session, defer; resume picks it up
 // next tick. Without this, ctrl+R on `#/:sessionId` flashes 5 loading states.
@@ -49,6 +74,8 @@ export function useRouteResume({
   gatewayState,
   locationPathname,
   resumeSession,
+  resumeFailedSessionId,
+  resumeExhaustedSessionId,
   routedSessionId,
   runtimeIdByStoredSessionIdRef,
   selectedStoredSessionId,
@@ -58,6 +85,16 @@ export function useRouteResume({
   const lastPathnameRef = useRef<string | null>(null)
   const seenGatewayStateRef = useRef(false)
   const wasGatewayOpenRef = useRef(false)
+  // Per-session retry bookkeeping for the bounded auto-retry effect below. Keyed
+  // by the session id we're retrying so switching chats resets the counter.
+  const retrySessionIdRef = useRef<string | null>(null)
+  const retryAttemptRef = useRef(0)
+  // Tracks the previous exhausted-latch value so we can detect its armed->cleared
+  // edge. resumeSession clears $resumeExhaustedSessionId on a manual Retry /
+  // reconnect / reselect; that transition is our cue to reset the attempt counter
+  // for a fresh backoff cycle on the SAME session (the auto-retry loop itself
+  // never touches this latch, so it can't spuriously trigger the reset).
+  const prevResumeExhaustedRef = useRef<string | null>(null)
 
   useEffect(() => {
     const gatewayOpen = gatewayState === 'open'
@@ -139,4 +176,111 @@ export function useRouteResume({
     selectedStoredSessionIdRef,
     startFreshSessionDraft
   ])
+
+  // Bounded auto-retry: when the routed session's resume failed terminally
+  // (resumeFailedSessionId matches the route), schedule a backoff retry so the
+  // window recovers on its own instead of latching the loader forever. This is
+  // the safety net the main effect above can't provide: after a failed resume,
+  // selectedStoredSessionIdRef.current already equals the route (resumeSession
+  // sets it synchronously at entry) and the pathname/gateway are unchanged, so
+  // none of stuckOnRoutedSession / pathnameChanged / gatewayBecameOpen fire
+  // again. resumeSession clears resumeFailedSessionId on its next attempt; a
+  // success keeps it clear (the effect's guard then no-ops), a repeat failure
+  // re-arms it and we back off further, capped at MAX_RESUME_RETRIES.
+  useEffect(() => {
+    // Detect the exhausted-latch armed->cleared edge for the current route. Only
+    // resumeSession clears $resumeExhaustedSessionId (manual Retry / reconnect /
+    // reselect) — the auto-retry loop never touches it — so this transition
+    // uniquely means "the user asked for another go." Reset the attempt counter
+    // for a fresh bounded backoff cycle on the SAME session. Without this,
+    // retryAttemptRef stays pinned at MAX after exhaustion (the !stranded reset
+    // below only fires on a route CHANGE to a different session), so a manual
+    // retry on the same stranded session would get exactly ONE attempt and then
+    // immediately re-arm the exhausted error — never the renewed backoff cycle
+    // the store/session.ts + use-session-actions.ts comments promise. (Point 2)
+    const wasExhausted = prevResumeExhaustedRef.current
+    prevResumeExhaustedRef.current = resumeExhaustedSessionId
+    if (wasExhausted && wasExhausted === routedSessionId && resumeExhaustedSessionId !== wasExhausted) {
+      retrySessionIdRef.current = routedSessionId
+      retryAttemptRef.current = 0
+    }
+
+    if (currentView !== 'chat' || gatewayState !== 'open') {
+      return
+    }
+
+    const stranded =
+      Boolean(routedSessionId) &&
+      resumeFailedSessionId === routedSessionId &&
+      !creatingSessionRef.current
+
+    if (!stranded) {
+      // Route moved off the stranded session (or it recovered) — reset the
+      // counter so a future failure on another session starts fresh, and clear
+      // any exhausted-latch armed for a session we're no longer viewing (never
+      // the current route: that's the error state we want to keep showing).
+      // resumeSession also clears it on a fresh attempt; this covers a plain
+      // route-change away from the stranded window.
+      if (retrySessionIdRef.current !== routedSessionId) {
+        retrySessionIdRef.current = null
+        retryAttemptRef.current = 0
+        setResumeExhaustedSessionId(current => (current && current !== routedSessionId ? null : current))
+      }
+
+      return
+    }
+
+    // New stranded session id → reset the attempt counter.
+    if (retrySessionIdRef.current !== routedSessionId) {
+      retrySessionIdRef.current = routedSessionId
+      retryAttemptRef.current = 0
+    }
+
+    if (retryAttemptRef.current >= MAX_RESUME_RETRIES) {
+      // Give up auto-retrying a persistently dead backend; the user can still
+      // reconnect / reselect (which resets the counter via the branch above).
+      // Surface an explicit error + manual Retry in the chat view instead of
+      // spinning the loader forever — resumeSession (manual Retry / reconnect /
+      // reselect) clears this latch and resets the counter for a fresh cycle.
+      setResumeExhaustedSessionId(routedSessionId)
+
+      return
+    }
+
+    const attempt = retryAttemptRef.current
+    const sessionId = routedSessionId as string
+
+    const timer = setTimeout(() => {
+      // Re-check liveness at fire time: a resume may have landed while we waited.
+      if (
+        creatingSessionRef.current ||
+        selectedStoredSessionIdRef.current !== sessionId ||
+        activeSessionIdRef.current !== null
+      ) {
+        return
+      }
+
+      // Consume an attempt ONLY now that a resume is actually dispatching.
+      // Incrementing at schedule time (the old behavior) let unrelated dep
+      // changes during the 1s–8s backoff window — a transient gatewayState
+      // flip, a non-referentially-stable resumeSession — clear the pending
+      // timer and re-run the effect, burning an attempt without any resume
+      // having fired. A flapping backend could then hit MAX in a couple of
+      // re-renders with far fewer than MAX real attempts. (Point 3)
+      retryAttemptRef.current += 1
+      void resumeSession(sessionId, true)
+    }, resumeRetryDelayMs(attempt))
+
+    return () => clearTimeout(timer)
+  }, [
+    activeSessionIdRef,
+    creatingSessionRef,
+    currentView,
+    gatewayState,
+    resumeSession,
+    resumeFailedSessionId,
+    resumeExhaustedSessionId,
+    routedSessionId,
+    selectedStoredSessionIdRef
+  ])
 }

apps/desktop/src/app/session/hooks/use-session-actions.test.tsx

@@ -3,8 +3,9 @@ import type { MutableRefObject } from 'react'
 import { useEffect } from 'react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
+import { getSessionMessages } from '@/hermes'
 import { $activeGatewayProfile, $newChatProfile } from '@/store/profile'
-import { $currentCwd } from '@/store/session'
+import { $currentCwd, $messages, $resumeFailedSessionId, setMessages, setResumeFailedSessionId } from '@/store/session'
 
 import type { ClientSessionState } from '../../types'
 
@@ -117,3 +118,142 @@ describe('createBackendSessionForSend profile routing', () => {
     expect(params).toMatchObject({ profile: 'default' })
   })
 })
+
+// ── Resume failure recovery (the "stuck loading session window" bug) ──────────
+// When session.resume rejects AND the REST transcript fallback ALSO fails, the
+// hook must (a) not throw out of the fallback (which stranded the loader), and
+// (b) arm $resumeFailedSessionId so use-route-resume can retry. A resume that
+// succeeds must NOT leave the flag armed.
+function ResumeHarness({
+  onReady,
+  requestGateway
+}: {
+  onReady: (resume: (storedSessionId: string, replaceRoute?: boolean) => Promise<unknown>) => void
+  requestGateway: <T>(method: string, params?: Record<string, unknown>) => Promise<T>
+}) {
+  const ref = <T,>(value: T): MutableRefObject<T> => ({ current: value })
+
+  const actions = useSessionActions({
+    activeSessionId: null,
+    activeSessionIdRef: ref<string | null>(null),
+    busyRef: ref(false),
+    creatingSessionRef: ref(false),
+    ensureSessionState: () => ({}) as ClientSessionState,
+    getRouteToken: () => 'token',
+    navigate: vi.fn() as never,
+    requestGateway,
+    runtimeIdByStoredSessionIdRef: ref(new Map<string, string>()),
+    selectedStoredSessionId: null,
+    selectedStoredSessionIdRef: ref<string | null>(null),
+    sessionStateByRuntimeIdRef: ref(new Map<string, ClientSessionState>()),
+    syncSessionStateToView: vi.fn(),
+    updateSessionState: (_sessionId, updater) => updater({} as ClientSessionState)
+  })
+
+  useEffect(() => {
+    onReady(actions.resumeSession)
+  }, [actions.resumeSession, onReady])
+
+  return null
+}
+
+describe('resumeSession failure recovery', () => {
+  afterEach(() => {
+    cleanup()
+    setResumeFailedSessionId(null)
+    setMessages([])
+    vi.restoreAllMocks()
+  })
+
+  async function runResume(
+    requestGateway: <T>(method: string, params?: Record<string, unknown>) => Promise<T>
+  ): Promise<void> {
+    let resume: ((storedSessionId: string, replaceRoute?: boolean) => Promise<unknown>) | null = null
+    render(<ResumeHarness onReady={r => (resume = r)} requestGateway={requestGateway} />)
+    await waitFor(() => expect(resume).not.toBeNull())
+    await resume!('stored-1', true)
+  }
+
+  it('arms $resumeFailedSessionId when resume RPC and REST fallback both fail', async () => {
+    // session.resume rejects (e.g. timeout against a wedged backend)...
+    const requestGateway = vi.fn(async (method: string) => {
+      if (method === 'session.resume') {
+        throw new Error('request timed out: session.resume')
+      }
+
+      return {} as never
+    })
+
+    // ...and the REST transcript fallback also rejects (backend unreachable).
+    vi.mocked(getSessionMessages).mockRejectedValue(new Error('network down'))
+
+    await runResume(requestGateway)
+
+    // The window is no longer silently stranded: the failure latch is armed for
+    // the stored session, which use-route-resume consumes to retry.
+    expect($resumeFailedSessionId.get()).toBe('stored-1')
+  })
+
+  it('does NOT arm the failure latch when the resume RPC fails but the REST fallback paints history', async () => {
+    // session.resume rejects, but the REST transcript fallback succeeds and
+    // hydrates a readable transcript — the window is NOT stranded.
+    const requestGateway = vi.fn(async (method: string) => {
+      if (method === 'session.resume') {
+        throw new Error('request timed out: session.resume')
+      }
+
+      return {} as never
+    })
+
+    vi.mocked(getSessionMessages).mockResolvedValue({
+      messages: [
+        { content: 'hello', role: 'user', timestamp: 1 },
+        { content: 'hi there', role: 'assistant', timestamp: 2 }
+      ],
+      session_id: 'stored-1'
+    } as never)
+
+    await runResume(requestGateway)
+
+    // Arming here would auto-retry a window that already shows history and,
+    // on exhaustion, blank that transcript behind the error overlay — a
+    // regression vs. plain fallback-success. The latch must stay clear.
+    expect($resumeFailedSessionId.get()).toBeNull()
+    // The fallback transcript is visible.
+    expect($messages.get().length).toBeGreaterThan(0)
+  })
+
+  it('does NOT throw out of the fallback when REST also fails (no unhandled rejection)', async () => {
+    const requestGateway = vi.fn(async (method: string) => {
+      if (method === 'session.resume') {
+        throw new Error('request timed out: session.resume')
+      }
+
+      return {} as never
+    })
+
+    vi.mocked(getSessionMessages).mockRejectedValue(new Error('network down'))
+
+    // resumeSession must resolve (swallow the fallback failure), not reject.
+    await expect(runResume(requestGateway)).resolves.toBeUndefined()
+  })
+
+  it('leaves the failure latch clear when resume succeeds', async () => {
+    // Pre-arm to prove a successful resume clears it (entry-clear path).
+    setResumeFailedSessionId('stored-1')
+
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      if (method === 'session.resume') {
+        return { session_id: 'runtime-1', resumed: params?.session_id, messages: [], info: {} } as never
+      }
+
+      return {} as never
+    })
+
+    vi.mocked(getSessionMessages).mockResolvedValue({ messages: [] } as never)
+
+    await runResume(requestGateway)
+
+    expect($resumeFailedSessionId.get()).toBeNull()
+  })
+})

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

@@ -13,8 +13,13 @@ import { $pinnedSessionIds } from '@/store/layout'
 import { clearNotifications, notify, notifyError } from '@/store/notifications'
 import { requestDesktopOnboarding } from '@/store/onboarding'
 import { $activeGatewayProfile, $newChatProfile, $profiles, ensureGatewayProfile, normalizeProfileKey } from '@/store/profile'
+import { tombstoneSessions, untombstoneSessions } from '@/store/projects'
 import {
   $currentCwd,
+  $currentFastMode,
+  $currentModel,
+  $currentProvider,
+  $currentReasoningEffort,
   $messages,
   $sessions,
   $yoloActive,
@@ -34,6 +39,8 @@ import {
   setFreshDraftReady,
   setIntroSeed,
   setMessages,
+  setResumeExhaustedSessionId,
+  setResumeFailedSessionId,
   setSelectedStoredSessionId,
   setSessions,
   setSessionStartedAt,
@@ -182,7 +189,10 @@ function upsertOptimisticSession(
   const profileKey = normalizeProfileKey($activeGatewayProfile.get())
 
   const session: SessionInfo = {
-    cwd: created.info?.cwd ?? null,
+    // Seed cwd so the grouped sidebar can place the new row in its repo/worktree
+    // lane immediately (the overlay groups by path); fall back to the workspace
+    // the session was just started in when the create response omits it.
+    cwd: created.info?.cwd ?? ($currentCwd.get().trim() || null),
     ended_at: null,
     id,
     input_tokens: 0,
@@ -407,13 +417,13 @@ export function useSessionActions({
       })
       setSessionStartedAt(null)
       setTurnStartedAt(null)
-      // New chats start in the configured default project dir when set,
-      // otherwise the sticky last-used workspace (PR #37586).
-      setCurrentModel('')
-      setCurrentProvider('')
-      setCurrentReasoningEffort('')
+      // The composer's model/effort/fast is sticky UI state (persisted in
+      // localStorage) — a new chat FOLLOWS your last pick instead of snapping
+      // back to the profile default, so we deliberately don't reset it here. The
+      // profile default still owns first-run seeding and profile switches (see
+      // refreshCurrentModel). Only $currentServiceTier (a live-session mirror)
+      // is cleared.
       setCurrentServiceTier('')
-      setCurrentFastMode(false)
       setYoloActive(false)
       setCurrentCwd(workspaceCwdForNewSession())
       setCurrentBranch('')
@@ -443,11 +453,23 @@ export function useSessionActions({
         const newChatProfile = $newChatProfile.get() ?? normalizeProfileKey($activeGatewayProfile.get())
         await ensureGatewayProfile(newChatProfile)
         const cwd = $currentCwd.get().trim() || workspaceCwdForNewSession()
+        // The composer's model/effort/fast is sticky UI state ($currentModel,
+        // $currentProvider, $currentReasoningEffort, $currentFastMode). Ship it
+        // with every session.create so the new chat opens on whatever the picker
+        // shows — applied as per-session overrides, never written to the profile
+        // default (that lives in Settings → Model).
+        const uiModel = $currentModel.get().trim()
+        const uiProvider = $currentProvider.get().trim()
+        const uiEffort = $currentReasoningEffort.get().trim()
+        const uiFast = $currentFastMode.get()
 
         const created = await requestGateway<SessionCreateResponse>('session.create', {
           cols: 96,
           ...(cwd && { cwd }),
-          ...(newChatProfile ? { profile: newChatProfile } : {})
+          ...(newChatProfile ? { profile: newChatProfile } : {}),
+          ...(uiModel ? { model: uiModel, ...(uiProvider ? { provider: uiProvider } : {}) } : {}),
+          ...(uiEffort ? { reasoning_effort: uiEffort } : {}),
+          ...(uiFast ? { fast: true } : {})
         })
 
         const stored = created.stored_session_id ?? null
@@ -563,6 +585,15 @@ export function useSessionActions({
       clearNotifications()
       setSelectedStoredSessionId(storedSessionId)
       selectedStoredSessionIdRef.current = storedSessionId
+      // Optimistically clear any prior resume-failure latch for this session:
+      // we're attempting a fresh resume, so the self-heal in use-route-resume
+      // must not keep treating it as stranded. It's re-armed below only if THIS
+      // attempt fails terminally (RPC reject + REST fallback failure).
+      setResumeFailedSessionId(current => (current === storedSessionId ? null : current))
+      // Also clear the exhausted-latch: a fresh attempt (manual Retry, reconnect,
+      // reselect) gives the bounded auto-retry counter a clean cycle, so the
+      // chat view drops the error state and shows the loader again.
+      setResumeExhaustedSessionId(current => (current === storedSessionId ? null : current))
 
       const warmRuntimeId = runtimeIdByStoredSessionIdRef.current.get(storedSessionId)
 
@@ -753,13 +784,41 @@ export function useSessionActions({
           return
         }
 
-        const fallback = await getSessionMessages(storedSessionId, sessionProfile)
+        // The gateway resume RPC failed. Try the REST transcript as a fallback
+        // so the window at least shows history. CRITICAL: this fallback must be
+        // wrapped in its own try — if it ALSO throws (wedged/unreachable backend,
+        // the common case when resume failed in the first place), an unguarded
+        // throw here skips setMessages AND leaves activeSessionId null with an
+        // empty transcript. That is the exact state the thread loader latches on
+        // forever (messagesEmpty && !activeSessionId) with no recovery path —
+        // the "open in new window stays stuck loading, even after a nap" bug.
+        try {
+          const fallback = await getSessionMessages(storedSessionId, sessionProfile)
 
-        if (!isCurrentResume()) {
-          return
+          if (!isCurrentResume()) {
+            return
+          }
+
+          setMessages(preserveLocalAssistantErrors(toChatMessages(fallback.messages), $messages.get()))
+        } catch {
+          // Fallback also failed: nothing to paint. Leave whatever messages are
+          // already shown and fall through to arm the resume-failure latch so
+          // use-route-resume re-attempts the resume on the next render / window
+          // focus / gateway reconnect instead of stranding the loader.
+        }
+
+        if (isCurrentResume() && $messages.get().length === 0) {
+          // Arm the self-heal ONLY when the window is still empty: the gateway
+          // resume rejected AND the REST fallback failed to paint a transcript.
+          // That is the exact stranded state the loader latches on
+          // (messagesEmpty && !activeSessionId), and matches $resumeFailedSessionId's
+          // documented contract. If the REST fallback DID paint history, the
+          // window is readable — arming here would needlessly auto-retry and,
+          // once retries exhaust, blank that visible transcript behind the
+          // exhausted-state error overlay (a regression vs. plain fallback success).
+          setResumeFailedSessionId(storedSessionId)
         }
 
-        setMessages(preserveLocalAssistantErrors(toChatMessages(fallback.messages), $messages.get()))
         notifyError(err, copy.resumeFailed)
       } finally {
         if (isCurrentResume()) {
@@ -916,6 +975,10 @@ export function useSessionActions({
       const removedPinId = removed ? sessionPinId(removed) : storedSessionId
 
       setSessions(prev => prev.filter(session => !sessionMatchesStoredId(session, storedSessionId)))
+      // Evict from the project tree's optimistic layer too (the backend snapshot
+      // still lists it until its next refresh), so grouped + flat views drop the
+      // row in lockstep.
+      tombstoneSessions([storedSessionId, removed?.id, removed?._lineage_root_id])
       // 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))
@@ -944,6 +1007,7 @@ export function useSessionActions({
           setSessionsTotal(prev => prev + 1)
         }
 
+        untombstoneSessions([storedSessionId, removed?.id, removed?._lineage_root_id])
         $pinnedSessionIds.set(previousPinned)
 
         if (wasSelected) {
@@ -998,6 +1062,7 @@ export function useSessionActions({
 
       // Soft-hide: drop from the sidebar immediately, keep the data.
       setSessions(prev => prev.filter(session => !sessionMatchesStoredId(session, storedSessionId)))
+      tombstoneSessions([storedSessionId, archived?.id, archived?._lineage_root_id])
       // Archived sessions are hidden by the listSessions(min_messages=1) query
       // on the next refresh, so they count as "removed" for the load-more
       // footer math.
@@ -1023,6 +1088,7 @@ export function useSessionActions({
           setSessionsTotal(prev => prev + 1)
         }
 
+        untombstoneSessions([storedSessionId, archived?.id, archived?._lineage_root_id])
         $pinnedSessionIds.set(previousPinned)
         notifyError(err, copy.archiveFailed)
       }

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

@@ -2,12 +2,14 @@ import { act, cleanup, render } from '@testing-library/react'
 import type { MutableRefObject } from 'react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
+import type { ChatMessage } from '@/lib/chat-messages'
 import {
   $currentFastMode,
   $currentModel,
   $currentProvider,
   $currentReasoningEffort,
   $currentServiceTier,
+  $messages,
   $turnStartedAt,
   setCurrentFastMode,
   setCurrentModel,
@@ -213,3 +215,113 @@ describe('useSessionStateCache — per-session turn timer', () => {
     expect($currentFastMode.get()).toBe(false)
   })
 })
+
+function userMessage(id: string, text: string): ChatMessage {
+  return { id, role: 'user', parts: [{ type: 'text', text }] }
+}
+
+function assistantText(id: string, text: string): ChatMessage {
+  return { id, role: 'assistant', parts: [{ type: 'text', text }] }
+}
+
+function assistantError(id: string, error: string): ChatMessage {
+  return { id, role: 'assistant', parts: [], error, pending: false }
+}
+
+interface ViewHarnessProps {
+  activeSessionId: string | null
+  onReady: (cache: Cache) => void
+}
+
+function ViewHarness({ activeSessionId, onReady }: ViewHarnessProps) {
+  const busyRef: MutableRefObject<boolean> = { current: false }
+  const cache = useSessionStateCache({
+    activeSessionId,
+    busyRef,
+    selectedStoredSessionId: null,
+    setAwaitingResponse: () => undefined,
+    setBusy: () => undefined,
+    // Wire the published view back into the real $messages atom the flush
+    // reads from, so the round-trip matches production.
+    setMessages: messages => $messages.set(messages)
+  })
+
+  onReady(cache)
+
+  return null
+}
+
+describe('useSessionStateCache — cross-thread error isolation', () => {
+  afterEach(() => {
+    cleanup()
+    $messages.set([])
+  })
+
+  it('does not leak a failed turn into another thread on switch', () => {
+    $messages.set([])
+    let cache!: Cache
+    const { rerender } = render(<ViewHarness activeSessionId="thread-A" onReady={c => (cache = c)} />)
+
+    // Thread A ends its turn with an out-of-funds error and is on screen.
+    act(() => {
+      cache.updateSessionState(
+        'thread-A',
+        state => ({
+          ...state,
+          busy: false,
+          messages: [userMessage('user-a', 'do the thing'), assistantError('assistant-a-error', 'Out of funds')]
+        }),
+        'stored-A'
+      )
+    })
+
+    expect($messages.get().some(message => message.error === 'Out of funds')).toBe(true)
+
+    // Switch to thread B (which completed cleanly). Its cached state syncs to
+    // the view while $messages still holds thread A's transcript.
+    rerender(<ViewHarness activeSessionId="thread-B" onReady={c => (cache = c)} />)
+    act(() => {
+      cache.updateSessionState(
+        'thread-B',
+        state => ({
+          ...state,
+          busy: false,
+          messages: [userMessage('user-b', 'hello'), assistantText('assistant-b', 'hi there')]
+        }),
+        'stored-B'
+      )
+    })
+
+    expect($messages.get().map(message => message.id)).toEqual(['user-b', 'assistant-b'])
+    expect($messages.get().some(message => message.error === 'Out of funds')).toBe(false)
+  })
+
+  it('still preserves a same-session local error a heartbeat dropped', () => {
+    $messages.set([])
+    let cache!: Cache
+    render(<ViewHarness activeSessionId="thread-A" onReady={c => (cache = c)} />)
+
+    // First paint establishes thread A as the on-screen session.
+    act(() => {
+      cache.updateSessionState(
+        'thread-A',
+        state => ({ ...state, busy: false, messages: [userMessage('user-a', 'do the thing')] }),
+        'stored-A'
+      )
+    })
+
+    // A local error lands in the view (e.g. failAssistantMessage wrote it).
+    $messages.set([userMessage('user-a', 'do the thing'), assistantError('assistant-a-error', 'OpenRouter 403')])
+
+    // A later same-session heartbeat carries cached state that lost the error.
+    act(() => {
+      cache.updateSessionState('thread-A', state => ({
+        ...state,
+        busy: false,
+        messages: [userMessage('user-a', 'do the thing')]
+      }))
+    })
+
+    expect($messages.get().some(message => message.error === 'OpenRouter 403')).toBe(true)
+  })
+})

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

@@ -79,6 +79,9 @@ export function useSessionStateCache({
   const runtimeIdByStoredSessionIdRef = useRef(new Map<string, string>())
   const pendingViewStateRef = useRef<{ sessionId: string; state: ClientSessionState } | null>(null)
   const viewSyncRafRef = useRef<number | null>(null)
+  // Runtime id whose transcript currently occupies `$messages` — lets the
+  // flush below tell a same-session refresh from a thread switch.
+  const viewSessionIdRef = useRef<string | null>(null)
 
   useEffect(() => {
     activeSessionIdRef.current = activeSessionId
@@ -142,12 +145,22 @@ export function useSessionStateCache({
     // jerks the scroll position while the user is reading. Skip the publish when
     // the merged result is content-identical to what's already on screen.
     const currentMessages = $messages.get()
-    const nextMessages = preserveLocalAssistantErrors(pending.state.messages, currentMessages)
+    // On a thread switch `$messages` still holds the *previous* thread, so
+    // preserving its local errors would graft that thread's failed turn (e.g.
+    // an out-of-funds error) onto this one — then cascade it everywhere as the
+    // polluted view becomes the next switch's baseline. Only carry errors
+    // across a same-session refresh; our cached state already keeps its own.
+    const nextMessages =
+      viewSessionIdRef.current === pending.sessionId
+        ? preserveLocalAssistantErrors(pending.state.messages, currentMessages)
+        : pending.state.messages
 
     if (!sameMessageList(nextMessages, currentMessages)) {
       setMessages(nextMessages)
     }
 
+    viewSessionIdRef.current = pending.sessionId
+
     syncRuntimeMetadataToView(pending.state)
     setBusy(pending.state.busy)
     setMutableRef(busyRef, pending.state.busy)

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

@@ -23,6 +23,7 @@ import { fieldCopyForSchemaKey } from './field-copy'
 import { enumOptionsFor, getNested, prettyName, setNested } from './helpers'
 import { ModelSettings } from './model-settings'
 import { EmptyState, ListRow, LoadingState, SettingsContent } from './primitives'
+import { ProviderConfigPanel } from './provider-config-panel'
 
 function ConfigField({
   schemaKey,
@@ -368,6 +369,9 @@ export function ConfigSettings({
                 schemaKey={key}
                 value={getNested(config, key)}
               />
+              {key === 'memory.provider' && typeof getNested(config, key) === 'string' && getNested(config, key) ? (
+                <ProviderConfigPanel provider={String(getNested(config, key))} />
+              ) : null}
             </div>
           ))}
         </div>

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

@@ -239,7 +239,7 @@ export const ENUM_OPTIONS: Record<string, string[]> = {
   'code_execution.mode': ['project', 'strict'],
   'context.engine': ['compressor', 'default', 'custom'],
   'delegation.reasoning_effort': ['', 'minimal', 'low', 'medium', 'high', 'xhigh'],
-  'memory.provider': ['', 'builtin', 'honcho'],
+  'memory.provider': ['', 'builtin', 'hindsight', 'honcho'],
   // Terminal execution backends — kept in sync with the dispatch ladder in
   // tools/terminal_tool.py::_create_environment (local/docker/singularity/
   // modal/daytona/ssh). Remote backends need extra env (image, tokens, host).

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

@@ -6,6 +6,12 @@ import { defineFieldCopy, fieldCopyForSchemaKey, schemaKeyToFieldCopyKey } from
 import { enumOptionsFor, getNested, providerGroup, setNested, stripToolsetLabel, toolsetDisplayLabel } from './helpers'
 
 describe('settings helpers', () => {
+  it('lists Hindsight as a built-in desktop memory provider option', () => {
+    const options = enumOptionsFor('memory.provider', '', {})
+
+    expect(options).toContain('hindsight')
+  })
+
   describe('defineFieldCopy', () => {
     it('flattens nested field copy paths', () => {
       const copy = defineFieldCopy({

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

@@ -228,7 +228,7 @@ export function SettingsView({ gateway, onClose, onConfigSaved, onMainModelChang
               onMainModelChanged={onMainModelChanged}
             />
           ) : activeView === 'providers' ? (
-            <ProvidersSettings onViewChange={setProviderView} view={providerView} />
+            <ProvidersSettings onClose={onClose} onViewChange={setProviderView} view={providerView} />
           ) : activeView === 'keys' ? (
             <KeysSettings view={keysView} />
           ) : activeView === 'mcp' ? (

apps/desktop/src/app/settings/model-settings.test.tsx

@@ -16,6 +16,8 @@ const getAuxiliaryModels = vi.fn()
 const setModelAssignment = vi.fn()
 const getRecommendedDefaultModel = vi.fn()
 const setEnvVar = vi.fn()
+const getHermesConfigRecord = vi.fn()
+const saveHermesConfig = vi.fn()
 const startManualProviderOAuth = vi.fn()
 
 vi.mock('@/hermes', () => ({
@@ -24,7 +26,9 @@ vi.mock('@/hermes', () => ({
   getAuxiliaryModels: () => getAuxiliaryModels(),
   setModelAssignment: (body: unknown) => setModelAssignment(body),
   getRecommendedDefaultModel: (slug: string) => getRecommendedDefaultModel(slug),
-  setEnvVar: (key: string, value: string) => setEnvVar(key, value)
+  setEnvVar: (key: string, value: string) => setEnvVar(key, value),
+  getHermesConfigRecord: () => getHermesConfigRecord(),
+  saveHermesConfig: (config: unknown) => saveHermesConfig(config)
 }))
 
 vi.mock('@/store/onboarding', () => ({
@@ -35,7 +39,13 @@ beforeEach(() => {
   getGlobalModelInfo.mockResolvedValue({ provider: 'nous', model: 'hermes-4' })
   getGlobalModelOptions.mockResolvedValue({
     providers: [
-      { name: 'Nous', slug: 'nous', models: ['hermes-4', 'hermes-4-mini'], authenticated: true },
+      {
+        name: 'Nous',
+        slug: 'nous',
+        models: ['hermes-4', 'hermes-4-mini'],
+        authenticated: true,
+        capabilities: { 'hermes-4': { reasoning: true, fast: true } }
+      },
       // An unconfigured api_key provider — surfaced by the full-universe payload.
       { name: 'DeepSeek', slug: 'deepseek', models: [], authenticated: false, auth_type: 'api_key', key_env: 'DEEPSEEK_API_KEY' }
     ]
@@ -47,6 +57,8 @@ beforeEach(() => {
   setModelAssignment.mockResolvedValue({ provider: 'nous', model: 'hermes-4', gateway_tools: [] })
   getRecommendedDefaultModel.mockResolvedValue({ provider: 'deepseek', model: 'deepseek-chat', free_tier: null })
   setEnvVar.mockResolvedValue({ ok: true })
+  getHermesConfigRecord.mockResolvedValue({ agent: { reasoning_effort: 'medium', service_tier: 'normal' } })
+  saveHermesConfig.mockResolvedValue({ ok: true })
 })
 
 afterEach(() => {
@@ -100,6 +112,31 @@ describe('ModelSettings', () => {
     await waitFor(() => expect(setEnvVar).toHaveBeenCalledWith('DEEPSEEK_API_KEY', 'sk-test-123'))
   })
 
+  it('writes the profile default speed (service_tier) when the fast switch is toggled', async () => {
+    await renderModelSettings()
+    await waitFor(() => expect(getHermesConfigRecord).toHaveBeenCalled())
+
+    const fastSwitch = await screen.findByRole('switch')
+    fireEvent.click(fastSwitch)
+
+    await waitFor(() =>
+      expect(saveHermesConfig).toHaveBeenCalledWith(
+        expect.objectContaining({ agent: expect.objectContaining({ service_tier: 'fast' }) })
+      )
+    )
+  })
+
+  it('hides the reasoning/speed defaults when the main model reports no capabilities', async () => {
+    getGlobalModelOptions.mockResolvedValueOnce({
+      providers: [{ name: 'Nous', slug: 'nous', models: ['hermes-4'], authenticated: true, capabilities: { 'hermes-4': { reasoning: false, fast: false } } }]
+    })
+
+    await renderModelSettings()
+    await waitFor(() => expect(getHermesConfigRecord).toHaveBeenCalled())
+
+    expect(screen.queryByRole('switch')).toBeNull()
+  })
+
   it('renders the auxiliary task rows', async () => {
     await renderModelSettings()
 

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

@@ -3,11 +3,14 @@ import { useCallback, useEffect, useMemo, useState } from 'react'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import { Switch } from '@/components/ui/switch'
 import {
   getAuxiliaryModels,
   getGlobalModelInfo,
   getGlobalModelOptions,
+  getHermesConfigRecord,
   getRecommendedDefaultModel,
+  saveHermesConfig,
   setEnvVar,
   setModelAssignment
 } from '@/hermes'
@@ -15,11 +18,26 @@ import type { AuxiliaryModelsResponse, ModelOptionProvider, StaleAuxAssignment }
 import { useI18n } from '@/i18n'
 import { AlertTriangle, Cpu, Loader2 } from '@/lib/icons'
 import { cn } from '@/lib/utils'
+import { notifyError } from '@/store/notifications'
 import { startManualLocalEndpoint, startManualProviderOAuth } from '@/store/onboarding'
+import type { HermesConfigRecord } from '@/types/hermes'
 
 import { CONTROL_TEXT } from './constants'
+import { getNested, setNested } from './helpers'
 import { ListRow, LoadingState, Pill, SectionHeading } from './primitives'
 
+// Hermes' reasoning levels (VALID_REASONING_EFFORTS); `none` = thinking off.
+// Empty config = Hermes default (medium), shown as Medium.
+const EFFORT_VALUES = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh'] as const
+
+// agent.service_tier stores "fast"/"priority"/"on" for fast; anything else is
+// normal (mirrors tui_gateway _load_service_tier).
+const isFastTier = (tier: unknown): boolean =>
+  ['fast', 'priority', 'on'].includes(String(tier ?? '').trim().toLowerCase())
+
+// Reuse the composer's effort labels (`xhigh` shows as "Max", else 1:1).
+const effortLabelKey = (v: string) => (v === 'xhigh' ? 'max' : v) as 'high' | 'low' | 'max' | 'medium' | 'minimal'
+
 // A provider row is "ready" to pick a model from when it reports models. The
 // backend now surfaces the full `hermes model` universe (every canonical
 // provider), so unconfigured providers come back with `authenticated:false`
@@ -97,6 +115,9 @@ export function ModelSettings({ onMainModelChanged }: ModelSettingsProps) {
   const [selectedProvider, setSelectedProvider] = useState('')
   const [selectedModel, setSelectedModel] = useState('')
   const [auxiliary, setAuxiliary] = useState<AuxiliaryModelsResponse | null>(null)
+  // Full profile config, kept so the reasoning/speed defaults round-trip
+  // (read agent.* → write back the whole record) like the generic config page.
+  const [config, setConfig] = useState<HermesConfigRecord | null>(null)
   const [applying, setApplying] = useState(false)
   const [editingAuxTask, setEditingAuxTask] = useState<null | string>(null)
   const [auxDraft, setAuxDraft] = useState<{ model: string; provider: string }>({ model: '', provider: '' })
@@ -113,10 +134,11 @@ export function ModelSettings({ onMainModelChanged }: ModelSettingsProps) {
     setError('')
 
     try {
-      const [modelInfo, modelOptions, auxiliaryModels] = await Promise.all([
+      const [modelInfo, modelOptions, auxiliaryModels, cfg] = await Promise.all([
         getGlobalModelInfo(),
         getGlobalModelOptions(),
-        getAuxiliaryModels()
+        getAuxiliaryModels(),
+        getHermesConfigRecord()
       ])
 
       setMainModel({ model: modelInfo.model, provider: modelInfo.provider })
@@ -124,6 +146,7 @@ export function ModelSettings({ onMainModelChanged }: ModelSettingsProps) {
       setSelectedProvider(prev => prev || modelInfo.provider)
       setSelectedModel(prev => prev || modelInfo.model)
       setAuxiliary(auxiliaryModels)
+      setConfig(cfg)
     } catch (err) {
       setError(err instanceof Error ? err.message : String(err))
     } finally {
@@ -181,6 +204,42 @@ export function ModelSettings({ onMainModelChanged }: ModelSettingsProps) {
       .map(entry => ({ task: entry.task, provider: entry.provider, model: entry.model }))
   }, [auxiliary, mainModel])
 
+  // Capabilities of the APPLIED main model — gates the profile-default
+  // reasoning/speed controls the same way the composer picker gates per-model
+  // edits (reasoning defaults on, fast defaults off when unreported).
+  const mainCaps = useMemo(() => {
+    const row = providers.find(provider => provider.slug === mainModel?.provider)
+
+    return mainModel ? row?.capabilities?.[mainModel.model] : undefined
+  }, [providers, mainModel])
+
+  const reasoningSupported = mainCaps?.reasoning ?? true
+  const fastSupported = mainCaps?.fast ?? false
+  const effortValue = String(getNested(config ?? {}, 'agent.reasoning_effort') ?? '').trim().toLowerCase() || 'medium'
+  const fastOn = isFastTier(getNested(config ?? {}, 'agent.service_tier'))
+
+  // Persist a single agent.* default by round-tripping the whole config record
+  // (PUT /api/config replaces it) — optimistic, with rollback on failure.
+  const writeAgentDefault = useCallback(
+    async (key: string, value: string) => {
+      if (!config) {
+        return
+      }
+
+      const prev = config
+      const next = setNested(config, key, value)
+      setConfig(next)
+
+      try {
+        await saveHermesConfig(next)
+      } catch (err) {
+        setConfig(prev)
+        notifyError(err, m.defaultsFailed)
+      }
+    },
+    [config, m.defaultsFailed]
+  )
+
   // Paste an API key for the selected `api_key` provider, persist it, then
   // refresh so the now-authenticated provider's models populate. Auto-selects
   // the recommended default model so the user can Apply in one more click.
@@ -433,6 +492,38 @@ export function ModelSettings({ onMainModelChanged }: ModelSettingsProps) {
               : `${selectedProviderRow?.name} signs in through your browser — Hermes runs the flow for you.`}
           </p>
         )}
+        {config && mainModel && (reasoningSupported || fastSupported) && (
+          <div className="mt-3 flex flex-wrap items-center gap-x-6 gap-y-3">
+            <span className="text-xs text-muted-foreground">{m.defaultsLabel}</span>
+            {reasoningSupported && (
+              <div className="flex items-center gap-2 text-xs">
+                {m.reasoning}
+                <Select onValueChange={value => void writeAgentDefault('agent.reasoning_effort', value)} value={effortValue}>
+                  <SelectTrigger className={cn('min-w-28', CONTROL_TEXT)}>
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {EFFORT_VALUES.map(value => (
+                      <SelectItem key={value} value={value}>
+                        {value === 'none' ? m.reasoningOff : t.shell.modelOptions[effortLabelKey(value)]}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </div>
+            )}
+            {fastSupported && (
+              <label className="flex items-center gap-2 text-xs">
+                {t.shell.modelOptions.fast}
+                <Switch
+                  checked={fastOn}
+                  onCheckedChange={checked => void writeAgentDefault('agent.service_tier', checked ? 'fast' : 'normal')}
+                  size="xs"
+                />
+              </label>
+            )}
+          </div>
+        )}
         {error && <div className="mt-2 text-xs text-destructive">{error}</div>}
         {switchStaleAux.length > 0 && (
           <div className="mt-2">

apps/desktop/src/app/settings/provider-config-panel.test.tsx

@@ -0,0 +1,142 @@
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { MemoryProviderConfig } from '@/types/hermes'
+
+const getMemoryProviderConfig = vi.fn()
+const saveMemoryProviderConfig = vi.fn()
+
+vi.mock('@/hermes', () => ({
+  getMemoryProviderConfig: (provider: string) => getMemoryProviderConfig(provider),
+  saveMemoryProviderConfig: (provider: string, values: unknown) => saveMemoryProviderConfig(provider, values)
+}))
+
+vi.mock('@/store/notifications', () => ({
+  notify: vi.fn(),
+  notifyError: vi.fn()
+}))
+
+function hindsightSchema(overrides: Partial<MemoryProviderConfig['fields'][number]>[] = []): MemoryProviderConfig {
+  const fields: MemoryProviderConfig['fields'] = [
+    {
+      key: 'mode',
+      label: 'Mode',
+      kind: 'select',
+      value: 'cloud',
+      description: 'How Hermes connects to Hindsight.',
+      placeholder: '',
+      is_set: true,
+      options: [
+        { value: 'cloud', label: 'Cloud', description: 'Hindsight Cloud API (lightweight, just needs an API key)' },
+        { value: 'local_external', label: 'Local External', description: 'Connect to an existing Hindsight instance' }
+      ]
+    },
+    {
+      key: 'api_key',
+      label: 'API key',
+      kind: 'secret',
+      value: '',
+      description: 'Used to authenticate with the Hindsight API.',
+      placeholder: 'Enter Hindsight API key',
+      is_set: false,
+      options: []
+    },
+    {
+      key: 'api_url',
+      label: 'API URL',
+      kind: 'text',
+      value: 'https://api.hindsight.vectorize.io',
+      description: '',
+      placeholder: '',
+      is_set: true,
+      options: []
+    },
+    { key: 'bank_id', label: 'Bank ID', kind: 'text', value: 'hermes', description: '', placeholder: '', is_set: true, options: [] },
+    {
+      key: 'recall_budget',
+      label: 'Recall budget',
+      kind: 'select',
+      value: 'mid',
+      description: '',
+      placeholder: '',
+      is_set: true,
+      options: [
+        { value: 'low', label: 'low', description: '' },
+        { value: 'mid', label: 'mid', description: '' },
+        { value: 'high', label: 'high', description: '' }
+      ]
+    }
+  ]
+
+  return {
+    name: 'hindsight',
+    label: 'Hindsight',
+    fields: fields.map((field, index) => ({ ...field, ...overrides[index] }))
+  }
+}
+
+beforeEach(() => {
+  getMemoryProviderConfig.mockResolvedValue(hindsightSchema())
+  saveMemoryProviderConfig.mockResolvedValue({ ok: true })
+})
+
+afterEach(() => {
+  cleanup()
+  vi.clearAllMocks()
+})
+
+async function renderPanel(provider = 'hindsight') {
+  const { ProviderConfigPanel } = await import('./provider-config-panel')
+
+  return render(<ProviderConfigPanel provider={provider} />)
+}
+
+describe('ProviderConfigPanel', () => {
+  it('renders the declared provider fields generically', async () => {
+    await renderPanel()
+
+    expect(await screen.findByDisplayValue('https://api.hindsight.vectorize.io')).toBeTruthy()
+    expect(screen.getByDisplayValue('hermes')).toBeTruthy()
+    expect(screen.getByText('Cloud')).toBeTruthy()
+    expect(screen.getAllByText('Hindsight Cloud API (lightweight, just needs an API key)').length).toBeGreaterThan(0)
+    expect(screen.getByText('mid')).toBeTruthy()
+  })
+
+  it('collapses and expands the fields', async () => {
+    await renderPanel()
+
+    expect(await screen.findByLabelText('API URL')).toBeTruthy()
+    fireEvent.click(screen.getByRole('button', { name: /Hindsight settings/ }))
+    expect(screen.queryByLabelText('API URL')).toBeNull()
+    fireEvent.click(screen.getByRole('button', { name: /Hindsight settings/ }))
+    expect(await screen.findByLabelText('API URL')).toBeTruthy()
+  })
+
+  it('saves edited values without requiring a secret replacement', async () => {
+    await renderPanel()
+
+    const apiUrl = await screen.findByLabelText('API URL')
+    fireEvent.change(apiUrl, { target: { value: 'http://localhost:8888' } })
+    fireEvent.change(screen.getByLabelText('Bank ID'), { target: { value: 'ben-bank' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Save' }))
+
+    await waitFor(() =>
+      expect(saveMemoryProviderConfig).toHaveBeenCalledWith('hindsight', {
+        mode: 'cloud',
+        api_key: '',
+        api_url: 'http://localhost:8888',
+        bank_id: 'ben-bank',
+        recall_budget: 'mid'
+      })
+    )
+  })
+
+  it('renders nothing for a provider with no declared config surface', async () => {
+    getMemoryProviderConfig.mockResolvedValue({ name: 'builtin', label: 'builtin', fields: [] })
+
+    const { container } = await renderPanel('builtin')
+
+    await waitFor(() => expect(getMemoryProviderConfig).toHaveBeenCalledWith('builtin'))
+    expect(container.querySelector('section')).toBeNull()
+  })
+})

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

@@ -0,0 +1,182 @@
+import { useCallback, useEffect, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { DisclosureCaret } from '@/components/ui/disclosure-caret'
+import { Input } from '@/components/ui/input'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import { getMemoryProviderConfig, saveMemoryProviderConfig } from '@/hermes'
+import { Check, Loader2, Save } from '@/lib/icons'
+import { notify, notifyError } from '@/store/notifications'
+import type { MemoryProviderConfig, MemoryProviderField } from '@/types/hermes'
+
+import { CONTROL_TEXT } from './constants'
+import { LoadingState, Pill } from './primitives'
+
+/** Seed editable values from the schema: non-secret fields keep their current
+ *  value, secret fields start blank (their value is never returned). */
+function seedValues(config: MemoryProviderConfig): Record<string, string> {
+  return Object.fromEntries(
+    config.fields.map(field => [field.key, field.kind === 'secret' ? '' : field.value])
+  )
+}
+
+function FieldControl({
+  field,
+  value,
+  onChange
+}: {
+  field: MemoryProviderField
+  value: string
+  onChange: (value: string) => void
+}) {
+  if (field.kind === 'select') {
+    const selected = field.options.find(option => option.value === value)
+
+    return (
+      <>
+        <Select onValueChange={onChange} value={value}>
+          <SelectTrigger className={CONTROL_TEXT}>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {field.options.map(option => (
+              <SelectItem key={option.value} value={option.value}>
+                {option.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+        {(selected?.description || field.description) && (
+          <span className="text-xs text-muted-foreground">{selected?.description || field.description}</span>
+        )}
+      </>
+    )
+  }
+
+  if (field.kind === 'secret') {
+    return (
+      <div className="flex flex-wrap items-center gap-2">
+        <Input
+          className="min-w-64 flex-1 font-mono"
+          onChange={event => onChange(event.target.value)}
+          placeholder={field.is_set ? 'Leave blank to keep current value' : field.placeholder}
+          type="password"
+          value={value}
+        />
+        {field.is_set && (
+          <Pill tone="primary">
+            <Check className="size-3" />
+            Set
+          </Pill>
+        )}
+      </div>
+    )
+  }
+
+  return (
+    <Input
+      className="font-mono"
+      onChange={event => onChange(event.target.value)}
+      placeholder={field.placeholder}
+      value={value}
+    />
+  )
+}
+
+export function ProviderConfigPanel({ provider }: { provider: string }) {
+  const [config, setConfig] = useState<MemoryProviderConfig | null>(null)
+  const [values, setValues] = useState<Record<string, string>>({})
+  const [expanded, setExpanded] = useState(true)
+  const [saving, setSaving] = useState(false)
+
+  const refresh = useCallback(async () => {
+    try {
+      const next = await getMemoryProviderConfig(provider)
+      setConfig(next)
+      setValues(seedValues(next))
+    } catch (err) {
+      notifyError(err, 'Memory provider settings failed to load')
+      setConfig(null)
+    }
+  }, [provider])
+
+  useEffect(() => {
+    setConfig(null)
+    void refresh()
+  }, [refresh])
+
+  const save = useCallback(async () => {
+    if (!config) {
+      return
+    }
+
+    setSaving(true)
+
+    try {
+      await saveMemoryProviderConfig(provider, values)
+      notify({ kind: 'success', title: `${config.label} saved`, message: 'Memory provider configuration updated.' })
+      await refresh()
+    } catch (err) {
+      notifyError(err, `Failed to save ${config.label} settings`)
+    } finally {
+      setSaving(false)
+    }
+  }, [config, provider, refresh, values])
+
+  // Providers without a declared config surface (e.g. builtin) render nothing.
+  if (config && config.fields.length === 0) {
+    return null
+  }
+
+  if (!config) {
+    return <LoadingState label="Loading memory provider settings..." />
+  }
+
+  const secretFields = config.fields.filter(field => field.kind === 'secret')
+
+  return (
+    <section className="py-3">
+      <button
+        aria-expanded={expanded}
+        className="flex w-full items-center justify-between gap-3 rounded-lg bg-background/60 px-3 py-2 text-left hover:bg-accent/50"
+        onClick={() => setExpanded(open => !open)}
+        type="button"
+      >
+        <span className="flex min-w-0 items-center gap-2">
+          <DisclosureCaret open={expanded} />
+          <span className="text-[length:var(--conversation-text-font-size)] font-medium text-foreground">
+            {config.label} settings
+          </span>
+          {secretFields.map(field => (
+            <Pill key={field.key}>{field.is_set ? `${field.label} set` : `${field.label} not set`}</Pill>
+          ))}
+        </span>
+      </button>
+
+      {expanded && (
+        <div className="mt-3 grid gap-4 rounded-xl bg-background/60 p-4">
+          {config.fields.map(field => (
+            <label className="grid gap-1.5" key={field.key}>
+              <span className="text-xs font-medium text-muted-foreground">{field.label}</span>
+              <FieldControl
+                field={field}
+                onChange={value => setValues(current => ({ ...current, [field.key]: value }))}
+                value={values[field.key] ?? ''}
+              />
+              {field.kind !== 'select' && field.description && (
+                <span className="text-xs text-muted-foreground">{field.description}</span>
+              )}
+            </label>
+          ))}
+
+          <div className="flex justify-end">
+            <Button disabled={saving} onClick={() => void save()} size="sm">
+              {saving ? <Loader2 className="size-3.5 animate-spin" /> : <Save />}
+              Save
+            </Button>
+          </div>
+        </div>
+      )}
+    </section>
+  )
+}

apps/desktop/src/app/settings/providers-settings.test.tsx

@@ -55,7 +55,7 @@ afterEach(() => {
 async function renderProvidersSettings() {
   const { ProvidersSettings } = await import('./providers-settings')
 
-  return render(<ProvidersSettings onViewChange={vi.fn()} view="accounts" />)
+  return render(<ProvidersSettings onClose={vi.fn()} onViewChange={vi.fn()} view="accounts" />)
 }
 
 describe('ProvidersSettings', () => {
@@ -95,6 +95,6 @@ describe('ProvidersSettings', () => {
 
     expect(await screen.findByText('Qwen Code')).toBeTruthy()
     expect(screen.queryByRole('button', { name: 'Remove Qwen Code' })).toBeNull()
-    expect(screen.getByText(/managed outside Hermes/)).toBeTruthy()
+    expect(screen.getByText(/managed by its own CLI/)).toBeTruthy()
   })
 })

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

@@ -1,6 +1,8 @@
 import { useStore } from '@nanostores/react'
+import type { ReactNode } from 'react'
 import { useCallback, useEffect, useMemo, useState } from 'react'
 
+import { runInTerminal } from '@/app/right-sidebar/store'
 import {
   FEATURED_ID,
   FeaturedProviderRow,
@@ -23,6 +25,20 @@ import { SettingsCategoryHeading, useEnvCredentials } from './env-credentials'
 import { providerGroup, providerMeta, providerPriority } from './helpers'
 import { LoadingState, SettingsContent } from './primitives'
 
+// The embedded terminal (and thus the "run disconnect command" path) only
+// exists in the Electron desktop shell, not the web dashboard.
+const canRunInTerminal = () => typeof window !== 'undefined' && Boolean(window.hermesDesktop?.terminal)
+
+// Parallel group headers ("Connected", "Other providers") so the expanded list
+// reads as its own section instead of bleeding into the connected group.
+function GroupLabel({ children }: { children: ReactNode }) {
+  return (
+    <p className="mt-3 px-0.5 text-[length:var(--conversation-caption-font-size)] font-medium text-(--ui-text-tertiary)">
+      {children}
+    </p>
+  )
+}
+
 // Sub-views surfaced as a sidebar subnav: account sign-in vs raw API keys.
 export const PROVIDER_VIEWS = ['accounts', 'keys'] as const
 
@@ -90,11 +106,13 @@ function buildProviderKeyGroups(vars: Record<string, EnvVarInfo>): ProviderKeyGr
 function OAuthPicker({
   disconnecting,
   onDisconnect,
+  onTerminalDisconnect,
   onWantApiKey,
   providers
 }: {
   disconnecting: null | string
   onDisconnect: (provider: OAuthProvider) => void
+  onTerminalDisconnect: (provider: OAuthProvider) => void
   onWantApiKey: () => void
   providers: OAuthProvider[]
 }) {
@@ -138,15 +156,14 @@ function OAuthPicker({
       {featured && <FeaturedProviderRow onSelect={select} provider={featured} />}
       {connected.length > 0 && (
         <>
-          <p className="mt-1 px-0.5 text-[length:var(--conversation-caption-font-size)] font-medium text-(--ui-text-tertiary)">
-            {p.connected}
-          </p>
+          <GroupLabel>{p.connected}</GroupLabel>
           {connected.map(p => (
             <ConnectedProviderRow
               disconnecting={disconnecting === p.id}
               key={p.id}
               onDisconnect={onDisconnect}
               onSelect={select}
+              onTerminalDisconnect={onTerminalDisconnect}
               provider={p}
             />
           ))}
@@ -154,6 +171,7 @@ function OAuthPicker({
       )}
       {showOthers && (
         <>
+          {connected.length > 0 && <GroupLabel>{p.otherProviders}</GroupLabel>}
           {others.map(p => (
             <ProviderRow key={p.id} onSelect={select} provider={p} />
           ))}
@@ -180,21 +198,26 @@ function ConnectedProviderRow({
   disconnecting,
   onDisconnect,
   onSelect,
+  onTerminalDisconnect,
   provider
 }: {
   disconnecting: boolean
   onDisconnect: (provider: OAuthProvider) => void
   onSelect: (provider: OAuthProvider) => void
+  onTerminalDisconnect: (provider: OAuthProvider) => void
   provider: OAuthProvider
 }) {
   const { t } = useI18n()
+  const copy = t.settings.providers
   const title = providerTitle(provider)
   const Trail = provider.flow === 'external' ? Terminal : ChevronRight
+  // Hermes can clear this provider's creds via the API.
   const canDisconnect = provider.disconnectable ?? provider.flow !== 'external'
-
-  const disconnectHint = provider.flow === 'external'
-    ? t.settings.providers.removeExternal(title, provider.cli_command)
-    : t.settings.providers.removeKeyManaged(title)
+  // External (CLI-managed) provider Hermes can't clear via the API, but ships a
+  // command we can run in the embedded terminal (Electron shell only).
+  const terminalDisconnect = !canDisconnect && Boolean(provider.disconnect_command) && canRunInTerminal()
+  // Only fall back to a static "remove it elsewhere" hint when we offer no button.
+  const showHint = !canDisconnect && !terminalDisconnect
 
   return (
     <div className="group grid grid-cols-[minmax(0,1fr)_auto] items-center gap-1 rounded-[6px] transition-colors hover:bg-(--ui-control-hover-background)">
@@ -203,13 +226,13 @@ function ConnectedProviderRow({
           <span className="truncate text-[length:var(--conversation-text-font-size)] font-semibold">{title}</span>
           <span className="inline-flex shrink-0 items-center gap-1 bg-primary/10 px-2 py-0.5 text-xs font-medium text-primary">
             <Check className="size-3" />
-            {t.settings.providers.connected}
+            {copy.connected}
           </span>
         </div>
         <p className="mt-1 text-xs leading-5 text-muted-foreground">{t.onboarding.flowSubtitles[provider.flow]}</p>
-        {!canDisconnect && (
+        {showHint && (
           <p className="mt-0.5 truncate text-[0.68rem] leading-5 text-muted-foreground/70">
-            {disconnectHint}
+            {provider.flow === 'external' ? copy.removeExternalGeneric(title) : copy.removeKeyManaged(title)}
           </p>
         )}
       </button>
@@ -228,6 +251,18 @@ function ConnectedProviderRow({
             {disconnecting ? <Loader2 className="size-3 animate-spin" /> : <Trash2 className="size-3" />}
           </Button>
         )}
+        {terminalDisconnect && (
+          <Button
+            aria-label={`${copy.disconnect} ${title}`}
+            onClick={() => onTerminalDisconnect(provider)}
+            size="icon-xs"
+            title={copy.disconnectInTerminal}
+            type="button"
+            variant="ghost"
+          >
+            <Trash2 className="size-3" />
+          </Button>
+        )}
       </div>
     </div>
   )
@@ -243,7 +278,7 @@ function NoProviderKeys() {
   )
 }
 
-export function ProvidersSettings({ onViewChange, view }: ProvidersSettingsProps) {
+export function ProvidersSettings({ onClose, onViewChange, view }: ProvidersSettingsProps) {
   const { t } = useI18n()
   const { rowProps, vars } = useEnvCredentials()
   const [oauthProviders, setOauthProviders] = useState<OAuthProvider[]>([])
@@ -282,6 +317,29 @@ export function ProvidersSettings({ onViewChange, view }: ProvidersSettingsProps
     return () => void (cancelled = true)
   }, [onboardingActive])
 
+  // External (CLI-managed) providers can't be cleared via the API by design —
+  // Hermes never deletes creds another tool owns behind a silent API call.
+  // Instead we run the documented removal command in the embedded terminal so
+  // the user sees exactly what executes, then return them to chat to watch it.
+  function handleTerminalDisconnect(provider: OAuthProvider) {
+    const command = provider.disconnect_command
+
+    if (!command) {
+      return
+    }
+
+    const name = providerTitle(provider)
+
+    if (!window.confirm(t.settings.providers.removeTerminalConfirm(name, command))) {
+      return
+    }
+
+    // Leave the settings overlay so the terminal pane (chat-only) is visible.
+    onClose()
+    runInTerminal(command)
+    notify({ kind: 'info', title: t.settings.providers.removedTitle, message: t.settings.providers.removeTerminalRunning(name) })
+  }
+
   async function handleDisconnect(provider: OAuthProvider) {
     const name = providerTitle(provider)
 
@@ -341,6 +399,7 @@ export function ProvidersSettings({ onViewChange, view }: ProvidersSettingsProps
       <OAuthPicker
         disconnecting={disconnecting}
         onDisconnect={provider => void handleDisconnect(provider)}
+        onTerminalDisconnect={handleTerminalDisconnect}
         onWantApiKey={() => onViewChange('keys')}
         providers={oauthProviders}
       />
@@ -359,6 +418,7 @@ interface ProviderKeyGroup {
 }
 
 interface ProvidersSettingsProps {
+  onClose: () => void
   onViewChange: (view: ProviderView) => void
   view: ProviderView
 }

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

@@ -8,6 +8,7 @@ import { sessionTitle } from '@/lib/chat-runtime'
 import { triggerHaptic } from '@/lib/haptics'
 import { Archive, ArchiveOff, FolderOpen, Loader2, Trash2 } from '@/lib/icons'
 import { notify, notifyError } from '@/store/notifications'
+import { untombstoneSessions } from '@/store/projects'
 import { applyConfiguredDefaultProjectDir, ensureDefaultWorkspaceCwd, setSessions } from '@/store/session'
 import type { SessionInfo } from '@/types/hermes'
 
@@ -62,7 +63,9 @@ export function SessionsSettings() {
     try {
       await setSessionArchived(session.id, false, session.profile)
       setLocalSessions(prev => prev.filter(s => s.id !== session.id))
-      // Surface it again in the sidebar without waiting for a full refresh.
+      // Surface it again in the sidebar without waiting for a full refresh, and
+      // lift any optimistic eviction so the grouped tree shows it again too.
+      untombstoneSessions([session.id, session._lineage_root_id])
       setSessions(prev => [{ ...session, archived: false }, ...prev.filter(s => s.id !== session.id)])
       triggerHaptic('selection')
       notify({ durationMs: 2_000, kind: 'success', message: s.restored })

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

@@ -16,7 +16,7 @@ import {
 } from '@/store/layout'
 import { $paneWidthOverride } from '@/store/panes'
 import { $connection } from '@/store/session'
-import { isNewSessionWindow, isSecondaryWindow } from '@/store/windows'
+import { isSecondaryWindow } from '@/store/windows'
 
 import { SIDEBAR_COLLAPSE_MEDIA_QUERY } from '../layout-constants'
 
@@ -80,7 +80,10 @@ export function AppShell({
   const connection = useStore($connection)
   const viewportFullscreen = useSyncExternalStore(subscribeWindowSize, viewportIsFullscreen, () => false)
   const isFullscreen = Boolean(connection?.isFullscreen) || viewportFullscreen
-  const hideTitlebarControls = isNewSessionWindow()
+  // Every secondary window (new-session scratch, subagent watch, cmd-click
+  // pop-out) is a compact side panel — none of them carry the full titlebar
+  // tool cluster. Gate on isSecondaryWindow, never the narrower new-session flag.
+  const hideTitlebarControls = isSecondaryWindow()
   const titlebarControls = titlebarControlsPosition(connection?.windowButtonPosition, isFullscreen)
   // Width Windows/Linux reserve for the OS-painted min/max/close overlay (zero
   // on macOS, where window controls sit on the left and are reported via

apps/desktop/src/app/shell/hooks/use-statusbar-items.tsx

@@ -1,5 +1,4 @@
 import { useStore } from '@nanostores/react'
-import type { ReactNode } from 'react'
 import { useCallback, useMemo } from 'react'
 
 import type { CommandCenterSection } from '@/app/command-center'
@@ -9,7 +8,6 @@ import { useI18n } from '@/i18n'
 import {
   Activity,
   AlertCircle,
-  ChevronDown,
   Clock,
   Command,
   Hash,
@@ -19,7 +17,6 @@ import {
   Zap,
   ZapFilled
 } from '@/lib/icons'
-import { formatModelStatusLabel } from '@/lib/model-status-label'
 import type { RuntimeReadinessResult } from '@/lib/runtime-readiness'
 import { contextBarLabel, LiveDuration, usageContextLabel } from '@/lib/statusbar'
 import { cn } from '@/lib/utils'
@@ -30,16 +27,11 @@ import {
   $activeSessionId,
   $busy,
   $connection,
-  $currentFastMode,
-  $currentModel,
-  $currentProvider,
-  $currentReasoningEffort,
   $currentUsage,
   $sessionStartedAt,
   $turnStartedAt,
   $workingSessionIds,
   $yoloActive,
-  setModelPickerOpen,
   setYoloActive
 } from '@/store/session'
 import { $subagentsBySession, activeSubagentCount } from '@/store/subagents'
@@ -65,7 +57,6 @@ interface StatusbarItemsOptions {
   gatewayLogLines: readonly string[]
   gatewayState: string
   inferenceStatus: RuntimeReadinessResult | null
-  modelMenuContent?: ReactNode
   openAgents: () => void
   openCommandCenterSection: (section: CommandCenterSection) => void
   freshDraftReady: boolean
@@ -83,7 +74,6 @@ export function useStatusbarItems({
   gatewayLogLines,
   gatewayState,
   inferenceStatus,
-  modelMenuContent,
   openAgents,
   openCommandCenterSection,
   freshDraftReady,
@@ -97,10 +87,6 @@ export function useStatusbarItems({
   const terminalTakeover = useStore($terminalTakeover)
   const yoloActive = useStore($yoloActive)
   const busy = useStore($busy)
-  const currentFastMode = useStore($currentFastMode)
-  const currentModel = useStore($currentModel)
-  const currentProvider = useStore($currentProvider)
-  const currentReasoningEffort = useStore($currentReasoningEffort)
   const currentUsage = useStore($currentUsage)
   const desktopActionTasks = useStore($desktopActionTasks)
   const previewServerRestartStatus = useStore($previewServerRestartStatus)
@@ -416,37 +402,6 @@ export function useStatusbarItems({
         title: yoloActive ? copy.yoloOn : copy.yoloOff,
         variant: 'action'
       },
-      {
-        id: 'model-summary',
-        label: (
-          <span className="inline-flex min-w-0 items-center gap-0.5">
-            <span className="truncate">
-              {formatModelStatusLabel(currentModel, {
-                fastMode: currentFastMode,
-                reasoningEffort: currentReasoningEffort
-              })}
-            </span>
-            <ChevronDown className="size-2.5 shrink-0 opacity-50" />
-          </span>
-        ),
-        ...(modelMenuContent
-          ? {
-              menuAlign: 'end' as const,
-              menuClassName: 'w-64',
-              menuContent: modelMenuContent,
-              title: currentProvider
-                ? copy.modelTitle(currentProvider, currentModel || copy.modelNone)
-                : copy.switchModel,
-              variant: 'menu' as const
-            }
-          : {
-              onSelect: () => setModelPickerOpen(true),
-              title: currentProvider
-                ? copy.providerModelTitle(currentProvider, currentModel || copy.noModel)
-                : copy.openModelPicker,
-              variant: 'action' as const
-            })
-      },
       {
         className: `w-7 justify-center px-0${terminalTakeover ? ' bg-accent/55 text-foreground' : ''}`,
         hidden: !chatOpen,
@@ -465,11 +420,6 @@ export function useStatusbarItems({
       contextBar,
       contextUsage,
       copy,
-      currentFastMode,
-      currentModel,
-      currentProvider,
-      currentReasoningEffort,
-      modelMenuContent,
       sessionStartedAt,
       showYoloToggle,
       terminalTakeover,

apps/desktop/src/app/shell/model-edit-submenu.test.tsx

@@ -0,0 +1,84 @@
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { DropdownMenu, DropdownMenuContent, DropdownMenuSub, DropdownMenuSubTrigger } from '@/components/ui/dropdown-menu'
+import { $modelPresets, getModelPreset } from '@/store/model-presets'
+import { $activeSessionId } from '@/store/session'
+
+import { type FastControl, ModelEditSubmenu } from './model-edit-submenu'
+
+// Radix calls these on open; jsdom doesn't implement them.
+beforeAll(() => {
+  Element.prototype.scrollIntoView = vi.fn()
+  Element.prototype.hasPointerCapture = vi.fn(() => false)
+  Element.prototype.releasePointerCapture = vi.fn()
+})
+
+beforeEach(() => {
+  $modelPresets.set({})
+  $activeSessionId.set(null)
+})
+
+afterEach(() => {
+  cleanup()
+  vi.clearAllMocks()
+})
+
+// Render the submenu inside an open menu/sub so its content (switches) mounts.
+function renderSubmenu(opts: { fastControl: FastControl; reasoning: boolean; requestGateway: () => Promise<unknown> }) {
+  return render(
+    <DropdownMenu open>
+      <DropdownMenuContent>
+        <DropdownMenuSub open>
+          <DropdownMenuSubTrigger>edit</DropdownMenuSubTrigger>
+          <ModelEditSubmenu
+            effort="medium"
+            fastControl={opts.fastControl}
+            isActive
+            model="m1"
+            onSelectModel={vi.fn()}
+            provider="p1"
+            reasoning={opts.reasoning}
+            requestGateway={opts.requestGateway as never}
+          />
+        </DropdownMenuSub>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+// Regression: editing the active row before a live session exists must stay
+// preset-only — the gateway's config.set falls back to global config when no
+// session matches, so it must not be called. (Caught in the second review.)
+describe('ModelEditSubmenu no-session guard', () => {
+  it('param fast: records the preset but skips the gateway without a session', () => {
+    const requestGateway = vi.fn().mockResolvedValue({})
+    renderSubmenu({ fastControl: { kind: 'param', on: false }, reasoning: false, requestGateway })
+
+    fireEvent.click(screen.getByRole('switch'))
+
+    expect(getModelPreset('p1', 'm1').fast).toBe(true)
+    expect(requestGateway).not.toHaveBeenCalled()
+  })
+
+  it('reasoning: records the preset but skips the gateway without a session', () => {
+    const requestGateway = vi.fn().mockResolvedValue({})
+    renderSubmenu({ fastControl: { kind: 'none' }, reasoning: true, requestGateway })
+
+    // Thinking starts on (medium); toggling it off routes through patchReasoning.
+    fireEvent.click(screen.getByRole('switch'))
+
+    expect(getModelPreset('p1', 'm1').effort).toBe('none')
+    expect(requestGateway).not.toHaveBeenCalled()
+  })
+
+  it('param fast: pushes to the gateway once a session is active', async () => {
+    const requestGateway = vi.fn().mockResolvedValue({})
+    $activeSessionId.set('sess1')
+    renderSubmenu({ fastControl: { kind: 'param', on: false }, reasoning: false, requestGateway })
+
+    fireEvent.click(screen.getByRole('switch'))
+
+    expect(requestGateway).toHaveBeenCalledWith('config.set', { key: 'fast', session_id: 'sess1', value: 'fast' })
+  })
+})

apps/desktop/src/app/shell/model-edit-submenu.tsx

@@ -12,13 +12,9 @@ import {
 } from '@/components/ui/dropdown-menu'
 import { Switch } from '@/components/ui/switch'
 import { useI18n } from '@/i18n'
+import { setModelPreset } from '@/store/model-presets'
 import { notifyError } from '@/store/notifications'
-import {
-  $activeSessionId,
-  $currentReasoningEffort,
-  setCurrentFastMode,
-  setCurrentReasoningEffort
-} from '@/store/session'
+import { $activeSessionId, setCurrentFastMode, setCurrentReasoningEffort } from '@/store/session'
 
 // Hermes' real reasoning levels (see VALID_REASONING_EFFORTS); `none` is owned
 // by the Thinking toggle, not the radio.
@@ -76,96 +72,104 @@ export function resolveFastControl(
 }
 
 interface ModelEditSubmenuProps {
+  /** This row's effective reasoning effort (live for the active model, else its
+   *  preset) — the submenu shows and edits from this, never the raw session. */
+  effort: string
   /** How fast mode is offered for this model (param toggle vs. variant swap). */
   fastControl: FastControl
   /** Whether this row's model is the active one. */
   isActive: boolean
-  /** Switch to this model (resolves false on failure). Awaited before applying
-   *  edits when not active so a failed switch doesn't write to the old model. */
-  onActivate: () => Promise<boolean> | void
+  /** This row's model id — edits persist as its global preset. */
+  model: string
   /** Switch to a specific model id (used to swap base ⇄ -fast variant). */
   onSelectModel: (model: string) => Promise<boolean> | void
+  /** This row's provider slug — edits persist as its global preset. */
+  provider: string
   /** Whether this model supports reasoning effort. */
   reasoning: boolean
   requestGateway: <T>(method: string, params?: Record<string, unknown>) => Promise<T>
 }
 
 export function ModelEditSubmenu({
+  effort,
   fastControl,
   isActive,
-  onActivate,
+  model,
   onSelectModel,
+  provider,
   reasoning,
   requestGateway
 }: ModelEditSubmenuProps) {
   const { t } = useI18n()
   const copy = t.shell.modelOptions
-  // Reactive session state comes straight from the stores rather than being
-  // drilled through the panel, so editing it re-renders only this submenu.
   const activeSessionId = useStore($activeSessionId)
-  const currentReasoningEffort = useStore($currentReasoningEffort)
 
-  const effort = normalizeEffort(currentReasoningEffort)
-  const thinkingOn = isThinkingEnabled(currentReasoningEffort)
+  const effortValue = normalizeEffort(effort)
+  const thinkingOn = isThinkingEnabled(effort)
 
-  // Reasoning/fast are session-scoped (they apply to the active model), so
-  // editing a non-active model first switches to it. Returns false if the
-  // switch failed, so callers skip applying to the wrong (previous) model.
-  const ensureActive = async (): Promise<boolean> => {
-    if (isActive) {
-      return true
+  // Editing always records the model's global preset; the active model also gets
+  // it pushed onto the live session. Non-active edits stay preset-only — they do
+  // not switch you to that model.
+  const patchReasoning = async (next: string) => {
+    setModelPreset(provider, model, { effort: next })
+
+    if (!isActive) {
+      return
     }
 
-    return (await onActivate()) !== false
-  }
-
-  const patchReasoning = async (next: string, rollback: string) => {
     setCurrentReasoningEffort(next)
 
+    // Preset-only without a session: `isActive` holds for the global/default
+    // row pre-session, and the gateway's `config.set` falls back to global
+    // config when none matches — so don't reach it (preset + optimistic store
+    // are the whole effect). Same guard in applyModelPreset / toggleFast.
+    if (!activeSessionId) {
+      return
+    }
+
     try {
-      if (!(await ensureActive())) {
-        setCurrentReasoningEffort(rollback)
-
-        return
-      }
-
-      await requestGateway('config.set', {
-        key: 'reasoning',
-        session_id: activeSessionId ?? '',
-        value: next
-      })
+      await requestGateway('config.set', { key: 'reasoning', session_id: activeSessionId, value: next })
     } catch (err) {
-      setCurrentReasoningEffort(rollback)
+      setCurrentReasoningEffort(effort)
+      setModelPreset(provider, model, { effort })
       notifyError(err, copy.updateFailed)
     }
   }
 
   const toggleFast = (enabled: boolean) => {
     if (fastControl.kind === 'variant') {
-      // Fast is a separate model id — swap to it (or back to the base).
-      void onSelectModel(enabled ? fastControl.fastId : fastControl.baseId)
+      // Fast is a separate model id. Record the choice on the base model's
+      // preset (selectFamily picks the `-fast` sibling later when set), and
+      // only swap models now if this is the active row — inactive edits must
+      // stay preset-only, same as the param path below.
+      setModelPreset(provider, fastControl.baseId, { fast: enabled })
+
+      if (isActive) {
+        void onSelectModel(enabled ? fastControl.fastId : fastControl.baseId)
+      }
 
       return
     }
 
     if (fastControl.kind === 'param') {
+      setModelPreset(provider, model, { fast: enabled })
+
+      if (!isActive) {
+        return
+      }
+
       setCurrentFastMode(enabled)
 
+      // Preset-only without a session (see patchReasoning).
+      if (!activeSessionId) {
+        return
+      }
       void (async () => {
         try {
-          if (!(await ensureActive())) {
-            setCurrentFastMode(!enabled)
-
-            return
-          }
-
-          await requestGateway('config.set', {
-            key: 'fast',
-            session_id: activeSessionId ?? '',
-            value: enabled ? 'fast' : 'normal'
-          })
+          await requestGateway('config.set', { key: 'fast', session_id: activeSessionId, value: enabled ? 'fast' : 'normal' })
         } catch (err) {
           setCurrentFastMode(!enabled)
+          setModelPreset(provider, model, { fast: !enabled })
           notifyError(err, copy.fastFailed)
         }
       })()
@@ -188,9 +192,7 @@ export function ModelEditSubmenu({
               <Switch
                 checked={thinkingOn}
                 className="ml-auto"
-                onCheckedChange={checked =>
-                  void patchReasoning(checked ? effort || 'medium' : 'none', currentReasoningEffort)
-                }
+                onCheckedChange={checked => void patchReasoning(checked ? effortValue || 'medium' : 'none')}
                 size="xs"
               />
             </DropdownMenuItem>
@@ -205,10 +207,7 @@ export function ModelEditSubmenu({
             <>
               <DropdownMenuSeparator className="mx-0" />
               <DropdownMenuLabel className={dropdownMenuSectionLabel}>{copy.effort}</DropdownMenuLabel>
-              <DropdownMenuRadioGroup
-                onValueChange={value => void patchReasoning(value, currentReasoningEffort)}
-                value={effort}
-              >
+              <DropdownMenuRadioGroup onValueChange={value => void patchReasoning(value)} value={effortValue}>
                 {EFFORT_OPTIONS.map(option => (
                   <DropdownMenuRadioItem
                     className={dropdownMenuRow}

apps/desktop/src/app/shell/model-menu-panel.tsx

@@ -1,6 +1,6 @@
 import { useStore } from '@nanostores/react'
 import { useQuery } from '@tanstack/react-query'
-import { useMemo, useState } from 'react'
+import { createContext, useContext, useMemo, useState } from 'react'
 
 import { Codicon } from '@/components/ui/codicon'
 import {
@@ -18,8 +18,9 @@ import { Skeleton } from '@/components/ui/skeleton'
 import type { HermesGateway } from '@/hermes'
 import { getGlobalModelOptions } from '@/hermes'
 import { useI18n } from '@/i18n'
-import { displayModelName, modelDisplayParts, reasoningEffortLabel } from '@/lib/model-status-label'
+import { currentPickerSelection, displayModelName, modelDisplayParts, reasoningEffortLabel } from '@/lib/model-status-label'
 import { cn } from '@/lib/utils'
+import { $modelPresets, applyModelPreset, modelPresetKey } from '@/store/model-presets'
 import {
   $visibleModels,
   collapseModelFamilies,
@@ -40,9 +41,14 @@ import type { ModelOptionProvider, ModelOptionsResponse } from '@/types/hermes'
 
 import { ModelEditSubmenu, resolveFastControl } from './model-edit-submenu'
 
+// Lets the host dropdown (model-pill) hand the panel a way to dismiss itself so
+// clicking a model row commits + closes, while the hover-revealed edit submenu
+// (reasoning/fast) stays open to play with (its items preventDefault on select).
+export const ModelMenuCloseContext = createContext<() => void>(() => {})
+
 interface ModelMenuPanelProps {
   gateway?: HermesGateway
-  onSelectModel: (selection: { model: string; persistGlobal: boolean; provider: string }) => Promise<boolean> | void
+  onSelectModel: (selection: { model: string; provider: string }) => Promise<boolean> | void
   requestGateway: <T>(method: string, params?: Record<string, unknown>) => Promise<T>
 }
 
@@ -54,6 +60,7 @@ interface ProviderGroup {
 export function ModelMenuPanel({ gateway, onSelectModel, requestGateway }: ModelMenuPanelProps) {
   const { t } = useI18n()
   const copy = t.shell.modelMenu
+  const closeMenu = useContext(ModelMenuCloseContext)
   const [search, setSearch] = useState('')
   // Reactive session state is read from the stores here (not drilled in), so
   // toggling effort/fast/model re-renders this panel in place without forcing
@@ -63,6 +70,7 @@ export function ModelMenuPanel({ gateway, onSelectModel, requestGateway }: Model
   const currentModel = useStore($currentModel)
   const currentProvider = useStore($currentProvider)
   const currentReasoningEffort = useStore($currentReasoningEffort)
+  const modelPresets = useStore($modelPresets)
   const visibleModels = useStore($visibleModels)
 
   const modelOptions = useQuery({
@@ -76,8 +84,12 @@ export function ModelMenuPanel({ gateway, onSelectModel, requestGateway }: Model
     }
   })
 
-  const optionsModel = String(modelOptions.data?.model ?? currentModel ?? '')
-  const optionsProvider = String(modelOptions.data?.provider ?? currentProvider ?? '')
+  const { model: optionsModel, provider: optionsProvider } = currentPickerSelection(
+    !!activeSessionId,
+    { model: currentModel, provider: currentProvider },
+    modelOptions.data
+  )
+
   const loading = modelOptions.isPending && !modelOptions.data
 
   const error = modelOptions.error
@@ -87,13 +99,41 @@ export function ModelMenuPanel({ gateway, onSelectModel, requestGateway }: Model
     : null
 
   const providers = modelOptions.data?.providers
+
   const effectiveVisibleModels = useMemo(
     () => effectiveVisibleKeys(visibleModels, providers ?? []),
     [visibleModels, providers]
   )
 
-  const switchTo = (model: string, provider: string) =>
-    onSelectModel({ model, persistGlobal: !activeSessionId, provider })
+  // The composer picker never persists the profile default. With a session it
+  // scopes the switch to that session; with none it's UI state shipped on the
+  // next session.create (see selectModel). The default lives in Settings → Model.
+  const switchTo = (model: string, provider: string) => onSelectModel({ model, provider })
+
+  // Selecting a model row restores that model's remembered preset onto the
+  // session (effort/fast), gated by capability. Unset → Hermes defaults.
+  const selectFamily = async (family: ModelFamily, provider: ModelOptionProvider) => {
+    const caps = provider.capabilities?.[family.id]
+    const preset = modelPresets[modelPresetKey(provider.slug, family.id)] ?? {}
+
+    // Variant-fast models (no speed param) express "fast" as a separate `-fast`
+    // id, so honor the saved preset by selecting that sibling. Param-fast is
+    // applied via applyModelPreset below instead.
+    const variantFast = !(caps?.fast ?? false) && !!family.fastId
+    const targetId = variantFast && preset.fast === true ? family.fastId! : family.id
+
+    if ((await switchTo(targetId, provider.slug)) === false) {
+      return
+    }
+
+    await applyModelPreset(
+      {
+        effort: (caps?.reasoning ?? true) ? (preset.effort ?? 'medium') : undefined,
+        fast: (caps?.fast ?? false) ? (preset.fast ?? false) : undefined
+      },
+      { failMessage: t.shell.modelOptions.updateFailed, request: requestGateway, sessionId: activeSessionId }
+    )
+  }
 
   const groups = useMemo(
     () => groupModels(providers ?? [], search, { model: optionsModel, provider: optionsProvider }, effectiveVisibleModels),
@@ -152,37 +192,42 @@ export function ModelMenuPanel({ gateway, onSelectModel, requestGateway }: Model
                 // -fast variant carries the same param support as its base.
                 const caps = group.provider.capabilities?.[family.id]
 
-                // Single source of truth for the active row's fast state — keeps
-                // the row label in lock-step with the submenu's Fast toggle and
-                // handles the standalone `-fast` id case.
+                // Effective settings for this row: live session state when it's
+                // the active model, otherwise its remembered preset (Hermes
+                // defaults when unset). Row label AND submenu read from these so
+                // they never disagree.
+                const preset = modelPresets[modelPresetKey(group.provider.slug, family.id)] ?? {}
+                const effEffort = isCurrent ? currentReasoningEffort : preset.effort ?? ''
+                const effFast = isCurrent ? currentFastMode : preset.fast ?? false
+
                 const fastControl = resolveFastControl(
                   activeId ?? family.id,
                   group.provider.models ?? [],
                   caps?.fast ?? false,
-                  currentFastMode
+                  effFast
                 )
 
-                // Grayed text is live session state only. Do not label inactive
-                // rows as "Fast" just because they have a fast-capable sibling:
-                // that makes an off Fast toggle look like it is already on.
-                const meta = isCurrent
-                  ? [
-                      fastControl.kind !== 'none' && fastControl.on ? copy.fast : null,
-                      reasoningEffortLabel(currentReasoningEffort) || copy.medium
-                    ]
-                      .filter(Boolean)
-                      .join(' ')
-                  : ''
+                const meta = [
+                  fastControl.kind !== 'none' && fastControl.on ? copy.fast : null,
+                  (caps?.reasoning ?? true) ? reasoningEffortLabel(effEffort) || copy.medium : null
+                ]
+                  .filter(Boolean)
+                  .join(' ')
 
                 // Every row is a hover-Edit submenu trigger. Activating it
-                // (pointer or keyboard) switches to the family's base model;
-                // the Fast toggle inside swaps to the -fast sibling (or flips
-                // the speed param). The sub-trigger has no `onSelect`, so wire
-                // both click and Enter/Space for keyboard parity.
+                // (pointer or keyboard) switches to the family's base model and
+                // restores its preset; the Fast toggle inside swaps to the -fast
+                // sibling (or flips the speed param). The sub-trigger has no
+                // `onSelect`, so wire both click and Enter/Space for keyboard parity.
+                // Clicking the row commits the model and closes the picker; the
+                // edit submenu (reasoning/fast) is reached by HOVER, so you can
+                // still tweak those without the click dismissing everything.
                 const activate = () => {
                   if (!isCurrent) {
-                    void switchTo(family.id, group.provider.slug)
+                    void selectFamily(family, group.provider)
                   }
+
+                  closeMenu()
                 }
 
                 return (
@@ -204,10 +249,12 @@ export function ModelMenuPanel({ gateway, onSelectModel, requestGateway }: Model
                       {isCurrent ? <Codicon className="ml-auto text-foreground" name="check" size="0.75rem" /> : null}
                     </DropdownMenuSubTrigger>
                     <ModelEditSubmenu
+                      effort={effEffort}
                       fastControl={fastControl}
                       isActive={isCurrent}
-                      onActivate={() => switchTo(family.id, group.provider.slug)}
+                      model={family.id}
                       onSelectModel={nextModel => switchTo(nextModel, group.provider.slug)}
+                      provider={group.provider.slug}
                       reasoning={caps?.reasoning ?? true}
                       requestGateway={requestGateway}
                     />

apps/desktop/src/components/assistant-ui/block-direction.test.tsx

@@ -0,0 +1,129 @@
+// Lists and blockquotes have chrome beside the text (markers, the quote
+// border) whose side is driven by the box's CSS direction, which the
+// unicode-bidi:plaintext rules never touch. These tests pin the split of
+// responsibilities: ul/ol/blockquote carry dir="auto" so the browser
+// resolves their box direction from content, inline code carries dir="ltr"
+// so it neither votes in that resolution nor reorders, and plain prose
+// blocks stay attribute-free (the plaintext CSS owns them). jsdom does not
+// resolve dir="auto", so the contract is asserted at the attribute level.
+import { AssistantRuntimeProvider, type ThreadMessage, useExternalStoreRuntime } from '@assistant-ui/react'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+
+import { Thread } from './thread'
+
+const createdAt = new Date('2026-06-01T00:00:00.000Z')
+
+class TestResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+vi.stubGlobal('ResizeObserver', TestResizeObserver)
+vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
+  window.setTimeout(() => callback(performance.now()), 0)
+)
+vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
+
+Element.prototype.scrollTo = function scrollTo() {}
+
+function stubOffsetDimension(
+  prop: 'offsetHeight' | 'offsetWidth',
+  clientProp: 'clientHeight' | 'clientWidth',
+  fallback: number
+) {
+  const previous = Object.getOwnPropertyDescriptor(HTMLElement.prototype, prop)
+
+  Object.defineProperty(HTMLElement.prototype, prop, {
+    configurable: true,
+    get() {
+      return previous?.get?.call(this) || (this as HTMLElement)[clientProp] || fallback
+    }
+  })
+}
+
+stubOffsetDimension('offsetWidth', 'clientWidth', 800)
+stubOffsetDimension('offsetHeight', 'clientHeight', 600)
+
+function userMessage(): ThreadMessage {
+  return {
+    id: 'user-1',
+    role: 'user',
+    content: [{ type: 'text', text: 'hi' }],
+    attachments: [],
+    createdAt,
+    metadata: { custom: {} }
+  } as ThreadMessage
+}
+
+function assistantMessage(text: string): ThreadMessage {
+  return {
+    id: 'assistant-1',
+    role: 'assistant',
+    content: [{ type: 'text', text }],
+    status: { type: 'complete', reason: 'stop' },
+    createdAt,
+    metadata: {
+      unstable_state: null,
+      unstable_annotations: [],
+      unstable_data: [],
+      steps: [],
+      custom: {}
+    }
+  } as ThreadMessage
+}
+
+function Harness({ text }: { text: string }) {
+  const runtime = useExternalStoreRuntime<ThreadMessage>({
+    messages: [userMessage(), assistantMessage(text)],
+    isRunning: false,
+    onNew: async () => {}
+  })
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  )
+}
+
+describe('block-level direction chrome', () => {
+  it('lists carry dir="auto" so markers follow the resolved direction', async () => {
+    render(<Harness text={'מקומות:\n\n1. חוף גורדון\n2. שוק הכרמל\n\n- פריט\n- item'} />)
+
+    const item = await screen.findByText(/חוף גורדון/)
+
+    expect(item.closest('ol')?.getAttribute('dir')).toBe('auto')
+
+    const bullet = await screen.findByText(/פריט/)
+
+    expect(bullet.closest('ul')?.getAttribute('dir')).toBe('auto')
+  })
+
+  it('blockquotes carry dir="auto" so the border follows the resolved direction', async () => {
+    render(<Harness text={'> ציטוט קצר בעברית'} />)
+
+    const quote = await screen.findByText(/ציטוט קצר/)
+
+    expect(quote.closest('blockquote')?.getAttribute('dir')).toBe('auto')
+  })
+
+  it('inline code carries dir="ltr" so it does not vote in dir="auto" resolution', async () => {
+    render(<Harness text={'1. `npm install` מתקין תלויות'} />)
+
+    const code = await screen.findByText('npm install')
+
+    expect(code.tagName).toBe('CODE')
+    expect(code.getAttribute('dir')).toBe('ltr')
+    expect(code.closest('ol')?.getAttribute('dir')).toBe('auto')
+  })
+
+  it('plain prose blocks stay attribute-free (plaintext CSS owns them)', async () => {
+    render(<Harness text={'שלום לכולם'} />)
+
+    const paragraph = await screen.findByText(/שלום לכולם/)
+
+    expect(paragraph.closest('p')?.hasAttribute('dir')).toBe(false)
+  })
+})

apps/desktop/src/components/assistant-ui/directive-text.tsx

@@ -322,13 +322,29 @@ function shortLabel(type: HermesRefType, id: string): string {
   return tail || id
 }
 
+function safeEmbeddedImages(text: string) {
+  try {
+    return extractEmbeddedImages(text)
+  } catch {
+    return { cleanedText: text, images: [] as string[] }
+  }
+}
+
+function safeDirectiveSegments(text: string): Unstable_DirectiveSegment[] {
+  try {
+    return [...hermesDirectiveFormatter.parse(text)]
+  } catch {
+    return [{ kind: 'text', text }]
+  }
+}
+
 /**
  * Renders text containing Hermes directives (`@file:...`, `@image:...`) as
  * inline chips. Embedded MEDIA images render below as a thumbnail row.
  */
 export function DirectiveContent({ text }: { text: string }) {
-  const { cleanedText, images } = useMemo(() => extractEmbeddedImages(text ?? ''), [text])
-  const segments = useMemo(() => hermesDirectiveFormatter.parse(cleanedText), [cleanedText])
+  const { cleanedText, images } = useMemo(() => safeEmbeddedImages(text ?? ''), [text])
+  const segments = useMemo(() => safeDirectiveSegments(cleanedText), [cleanedText])
 
   return (
     <span className="whitespace-pre-line" data-slot="aui_directive-text">

apps/desktop/src/components/assistant-ui/markdown-text.test.ts

@@ -201,4 +201,13 @@ describe('preprocessMarkdown', () => {
 
     expect(output).toContain('<https://example.com/a_b/c~d/page>')
   })
+
+  it('handles a fenced block larger than V8 spread-argument limit', () => {
+    // A single huge code block (e.g. a logged minified bundle) used to throw
+    // `RangeError: Maximum call stack size exceeded` via `out.push(...lines)`.
+    const body = Array.from({ length: 200_000 }, (_, i) => `line ${i}`).join('\n')
+    const input = `\`\`\`js\n${body}\n\`\`\``
+
+    expect(() => preprocessMarkdown(input)).not.toThrow()
+  })
 })

apps/desktop/src/components/assistant-ui/markdown-text.tsx

@@ -19,8 +19,9 @@ import {
   useState
 } from 'react'
 
+import { ExpandableBlock } from '@/components/chat/expandable-block'
 import { PreviewAttachment } from '@/components/chat/preview-attachment'
-import { SyntaxHighlighter } from '@/components/chat/shiki-highlighter'
+import { chunkByLines, SyntaxHighlighter } from '@/components/chat/shiki-highlighter'
 import { ZoomableImage } from '@/components/chat/zoomable-image'
 import { normalizeExternalUrl, openExternalLink, PrettyLink } from '@/lib/external-link'
 import { createMemoizedMathPlugin } from '@/lib/katex-memo'
@@ -57,7 +58,11 @@ const mathPlugin = createMemoizedMathPlugin({ singleDollarTextMath: true })
 // flush) with a tail-bounded repair — see lib/remend-tail.ts. Must stay
 // module-scope so the prop identity is stable across renders.
 function preprocessWithTailRepair(text: string): string {
-  return tailBoundedRemend(preprocessMarkdown(text))
+  try {
+    return tailBoundedRemend(preprocessMarkdown(text))
+  } catch {
+    return text
+  }
 }
 
 // Memoized block splitter. Streamdown calls `parseMarkdownIntoBlocks` (a full
@@ -453,8 +458,35 @@ const MARKDOWN_CONTAINER_CLASS_NAME = cn(
   '[&>*:first-child]:mt-0 [&>*:last-child]:mb-0 [&>*+*]:mt-(--paragraph-gap)'
 )
 
+const MAX_MARKDOWN_CHARS = 200_000
+
+function HugeTextFallback({ containerClassName, text }: { containerClassName?: string; text: string }) {
+  const chunks = useMemo(() => chunkByLines(text, 200), [text])
+
+  return (
+    <div
+      className={cn(
+        'aui-md w-full max-w-none overflow-hidden rounded-[0.625rem] border border-border font-mono text-[0.7rem] leading-relaxed text-foreground/90',
+        containerClassName
+      )}
+    >
+      <ExpandableBlock className="p-2">
+        {chunks.map((chunk, index) => (
+          <div
+            className="[content-visibility:auto]"
+            key={index}
+            style={{ containIntrinsicSize: `auto ${chunk.lines * 16}px` }}
+          >
+            {chunk.text}
+          </div>
+        ))}
+      </ExpandableBlock>
+    </div>
+  )
+}
+
 function MarkdownTextSurface({ containerClassName, containerProps }: MarkdownTextSurfaceProps) {
-  const { status } = useMessagePartText()
+  const { status, text } = useMessagePartText()
   const isStreaming = status.type === 'running'
 
   // Keep code parsing enabled while streaming so incomplete fenced blocks still
@@ -484,19 +516,37 @@ function MarkdownTextSurface({ containerClassName, containerProps }: MarkdownTex
           <p className={cn('wrap-anywhere leading-(--dt-line-height)', className)} {...props} />
         ),
         a: MarkdownLink,
+        // Inline code must not vote when an ancestor resolves `dir="auto"`
+        // (HTML's algorithm skips descendants that carry their own dir),
+        // mirroring the CSS isolate that already keeps it out of the
+        // plaintext scan. Fenced code never reaches this override; it goes
+        // through the code plugin's CodeCard path.
+        inlineCode: ({ className, ...props }: ComponentProps<'code'>) => (
+          <code className={className} dir="ltr" {...props} />
+        ),
         // `---` as quiet spacing, not a heavy full-width rule.
         hr: (_props: ComponentProps<'hr'>) => <div aria-hidden className="my-3" />,
+        // Lists and blockquotes have chrome that sits *beside* the text
+        // (markers, the quote border), and that side is driven by the CSS
+        // `direction` of the box, which `unicode-bidi: plaintext` never
+        // touches — an RTL list otherwise renders its numbers stranded at
+        // the far left. `dir="auto"` lets the browser resolve the box
+        // direction from content; the plaintext rules in styles.css keep
+        // owning per-line text direction. Inline code carries `dir="ltr"`
+        // (see the `code` override) so it doesn't vote here either, same
+        // contract as the CSS isolate.
         blockquote: ({ className, ...props }: ComponentProps<'blockquote'>) => (
           <blockquote
-            className={cn('border-l-2 border-border pl-3 text-muted-foreground italic', className)}
+            className={cn('border-s-2 border-border ps-3 text-muted-foreground italic', className)}
+            dir="auto"
             {...props}
           />
         ),
         ul: ({ className, ...props }: ComponentProps<'ul'>) => (
-          <ul className={cn('my-1 gap-0', className)} {...props} />
+          <ul className={cn('my-1 gap-0', className)} dir="auto" {...props} />
         ),
         ol: ({ className, ...props }: ComponentProps<'ol'>) => (
-          <ol className={cn('my-1 gap-0', className)} {...props} />
+          <ol className={cn('my-1 gap-0', className)} dir="auto" {...props} />
         ),
         li: ({ className, ...props }: ComponentProps<'li'>) => (
           <li className={cn('leading-(--dt-line-height)', className)} {...props} />
@@ -533,6 +583,10 @@ function MarkdownTextSurface({ containerClassName, containerProps }: MarkdownTex
     [isStreaming]
   )
 
+  if (text.length > MAX_MARKDOWN_CHARS) {
+    return <HugeTextFallback containerClassName={containerClassName} text={text} />
+  }
+
   return (
     <StreamdownTextPrimitive
       components={components}

apps/desktop/src/components/assistant-ui/streaming.test.tsx

@@ -378,6 +378,20 @@ function IntroHarness() {
   )
 }
 
+function DismissibleErrorHarness({ onDismissError }: { onDismissError: (messageId: string) => void }) {
+  const runtime = useExternalStoreRuntime<ThreadMessage>({
+    messages: [assistantErrorMessage('OpenRouter rejected the request (403).')],
+    isRunning: false,
+    onNew: async () => {}
+  })
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread onDismissError={onDismissError} />
+    </AssistantRuntimeProvider>
+  )
+}
+
 describe('assistant-ui streaming renderer', () => {
   beforeEach(() => {
     resizeObservers.clear()
@@ -421,6 +435,23 @@ describe('assistant-ui streaming renderer', () => {
     expect(screen.getByRole('alert').textContent).toContain('OpenRouter rejected the request (403).')
   })
 
+  it('omits the dismiss control when no onDismissError handler is supplied', () => {
+    render(<MessageHarness message={assistantErrorMessage('OpenRouter rejected the request (403).')} />)
+
+    expect(screen.queryByRole('button', { name: 'Dismiss error' })).toBeNull()
+  })
+
+  it('invokes onDismissError with the errored message id when the dismiss control is clicked', () => {
+    const onDismissError = vi.fn()
+    render(<DismissibleErrorHarness onDismissError={onDismissError} />)
+
+    const dismiss = screen.getByRole('button', { name: 'Dismiss error' })
+    fireEvent.click(dismiss)
+
+    expect(onDismissError).toHaveBeenCalledTimes(1)
+    expect(onDismissError).toHaveBeenCalledWith('assistant-error-1')
+  })
+
   // Scroll behavior (follow-at-bottom, escape-on-scroll-up, re-engage) is owned
   // by the use-stick-to-bottom library and covered by its own test suite. We
   // don't re-assert its scrollTop mechanics here — doing so in jsdom (no real

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

@@ -22,7 +22,7 @@ import {
   resetThreadScroll,
   setThreadAtBottom
 } from '@/store/thread-scroll'
-import { isNewSessionWindow, isSecondaryWindow } from '@/store/windows'
+import { isSecondaryWindow } from '@/store/windows'
 
 import { MessageRenderBoundary } from './message-render-boundary'
 
@@ -134,13 +134,20 @@ const ThreadMessageListInner: FC<ThreadMessageListProps> = ({
   const hiddenCount = firstVisible
   const visibleGroups = hiddenCount > 0 ? groups.slice(hiddenCount) : groups
   const restoreFromBottomRef = useRef<number | null>(null)
-  const newSessionWindow = isNewSessionWindow()
-  const newSessionTitlebarGap = 'calc(var(--titlebar-height)+0.75rem)'
-  const threadContentTopPad = newSessionWindow
+  // Secondary windows (new-session scratch, subagent watch, cmd-click pop-out)
+  // hide the titlebar tool cluster + session header, but the OS traffic lights
+  // still sit in the top-left, so reserve the titlebar gap above the transcript.
+  const secondaryWindow = isSecondaryWindow()
+  // NB: CSS calc() requires whitespace around the +/- operator. This string is
+  // assigned verbatim to the --sticky-human-top inline style below (it does not
+  // go through Tailwind, which would auto-space it), so the spaces are load-
+  // bearing — without them the declaration is invalid, gets dropped, and the
+  // sticky user bubble falls back to its ~4px default and slides under the OS
+  // traffic lights.
+  const secondaryTitlebarGap = 'calc(var(--titlebar-height) + 0.75rem)'
+  const threadContentTopPad = secondaryWindow
     ? 'pt-[calc(var(--titlebar-height)+0.75rem)]'
-    : isSecondaryWindow()
-      ? 'pt-6'
-      : 'pt-[calc(var(--titlebar-height)+1.5rem)]'
+    : 'pt-[calc(var(--titlebar-height)-0.5rem)]'
 
   useEffect(() => setThreadAtBottom(isAtBottom), [isAtBottom])
   useEffect(() => () => resetThreadScroll(), [])
@@ -247,10 +254,21 @@ const ThreadMessageListInner: FC<ThreadMessageListProps> = ({
       style={
         {
           height: clampToComposer ? 'var(--thread-viewport-height)' : '100%',
-          ...(newSessionWindow ? { '--sticky-human-top': newSessionTitlebarGap } : {})
+          ...(secondaryWindow ? { '--sticky-human-top': secondaryTitlebarGap } : {})
         } as CSSProperties
       }
     >
+      {secondaryWindow && (
+        // Secondary windows hide the titlebar chrome, so the scroller runs to
+        // the window's top edge and streamed text slides up under the OS
+        // traffic lights. Content padding alone scrolls away with the text — a
+        // fixed opaque strip (the titlebar's drag region) masks anything behind
+        // it and keeps the window draggable, matching the main window's header.
+        <div
+          aria-hidden="true"
+          className="absolute inset-x-0 top-0 z-10 h-(--titlebar-height) bg-background [-webkit-app-region:drag]"
+        />
+      )}
       <div
         className="size-full overflow-x-hidden overflow-y-auto overscroll-contain"
         data-following={isAtBottom ? 'true' : 'false'}

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

@@ -91,7 +91,7 @@ import { attachmentDisplayText, attachmentId, pathLabel } from '@/lib/chat-runti
 import { DATA_IMAGE_URL_RE } from '@/lib/embedded-images'
 import { LinkifiedText } from '@/lib/external-link'
 import { triggerHaptic } from '@/lib/haptics'
-import { GitBranchIcon, Loader2Icon, Volume2Icon, VolumeXIcon } from '@/lib/icons'
+import { GitBranchIcon, Loader2Icon, Volume2Icon, VolumeXIcon, XIcon } from '@/lib/icons'
 import { extractPreviewTargets } from '@/lib/preview-targets'
 import { useEnterAnimation } from '@/lib/use-enter-animation'
 import { cn } from '@/lib/utils'
@@ -169,6 +169,7 @@ export const Thread: FC<{
   loading?: ThreadLoadingState
   onBranchInNewChat?: (messageId: string) => void
   onCancel?: () => Promise<void> | void
+  onDismissError?: (messageId: string) => void
   onRestoreToMessage?: (messageId: string) => Promise<void> | void
   sessionId?: string | null
   sessionKey?: string | null
@@ -180,18 +181,19 @@ export const Thread: FC<{
   loading,
   onBranchInNewChat,
   onCancel,
+  onDismissError,
   onRestoreToMessage,
   sessionId = null,
   sessionKey
 }) => {
   const messageComponents = useMemo(
     () => ({
-      AssistantMessage: () => <AssistantMessage onBranchInNewChat={onBranchInNewChat} />,
+      AssistantMessage: () => <AssistantMessage onBranchInNewChat={onBranchInNewChat} onDismissError={onDismissError} />,
       SystemMessage,
       UserEditComposer: () => <UserEditComposer cwd={cwd} gateway={gateway} sessionId={sessionId} />,
       UserMessage: () => <UserMessage onCancel={onCancel} onRestoreToMessage={onRestoreToMessage} />
     }),
-    [cwd, gateway, onBranchInNewChat, onCancel, onRestoreToMessage, sessionId]
+    [cwd, gateway, onBranchInNewChat, onCancel, onDismissError, onRestoreToMessage, sessionId]
   )
 
   const emptyPlaceholder = intro ? (
@@ -245,9 +247,13 @@ const CenteredThreadSpinner: FC = () => {
   )
 }
 
-const AssistantMessage: FC<{ onBranchInNewChat?: (messageId: string) => void }> = ({ onBranchInNewChat }) => {
+const AssistantMessage: FC<{
+  onBranchInNewChat?: (messageId: string) => void
+  onDismissError?: (messageId: string) => void
+}> = ({ onBranchInNewChat, onDismissError }) => {
   const messageId = useAuiState(s => s.message.id)
   const messageRuntime = useMessageRuntime()
+  const { t } = useI18n()
 
   // PERF: this component must NOT subscribe to the streaming text. Every
   // selector here returns a value that stays referentially stable across
@@ -306,10 +312,20 @@ const AssistantMessage: FC<{ onBranchInNewChat?: (messageId: string) => void }>
         )}
         <MessagePrimitive.Error>
           <ErrorPrimitive.Root
-            className="mt-1.5 text-[0.78rem] leading-5 text-[color-mix(in_srgb,var(--dt-destructive)_78%,var(--ui-text-secondary))]"
+            className="mt-1.5 flex items-start gap-1.5 text-[0.78rem] leading-5 text-[color-mix(in_srgb,var(--dt-destructive)_78%,var(--ui-text-secondary))]"
             role="alert"
           >
-            <ErrorPrimitive.Message />
+            <ErrorPrimitive.Message className="min-w-0 flex-1" />
+            {onDismissError && (
+              <TooltipIconButton
+                className="-my-0.5 shrink-0 text-current opacity-70 hover:opacity-100"
+                onClick={() => onDismissError(messageId)}
+                side="top"
+                tooltip={t.assistant.thread.dismissError}
+              >
+                <XIcon className="size-3.5" />
+              </TooltipIconButton>
+            )}
           </ErrorPrimitive.Root>
         </MessagePrimitive.Error>
       </div>
@@ -811,7 +827,7 @@ function StickyHumanMessageContainer({ attachments, children }: { attachments?:
 // so without the carve-out, clicking a stuck bubble drags the window instead of
 // opening the edit composer.
 const USER_BUBBLE_BASE_CLASS =
-  'composer-human-message standalone-glass relative flex w-full min-w-0 max-w-full flex-col gap-1.5 overflow-hidden rounded-xl border bg-(--dt-user-bubble) px-3 py-2 text-left [-webkit-app-region:no-drag]'
+  'composer-human-message standalone-glass relative flex w-full min-w-0 max-w-full flex-col gap-1.5 overflow-y-auto rounded-xl border bg-(--dt-user-bubble) px-3 py-2 text-left [-webkit-app-region:no-drag]'
 
 const USER_ACTION_ICON_BUTTON_CLASS =
   'grid place-items-center rounded-md bg-transparent text-(--ui-text-secondary) transition-colors hover:bg-(--ui-control-active-background) hover:text-foreground disabled:cursor-default disabled:text-(--ui-text-quaternary) disabled:opacity-70'

apps/desktop/src/components/chat/code-card.tsx

@@ -66,7 +66,7 @@ function CodeCardBody({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
       className={cn(
-        'p-1.5 font-mono text-[0.7rem] leading-relaxed text-foreground/90 [&_pre]:m-0 [&_pre]:overflow-x-auto [&_pre]:bg-transparent! [&_pre]:px-2 [&_pre]:py-1.5 [&_pre]:font-mono [&_pre]:leading-relaxed',
+        'font-mono text-[0.7rem] leading-relaxed text-foreground/90 [&_pre]:m-0 [&_pre]:overflow-x-auto [&_pre]:bg-transparent! [&_pre]:px-2 [&_pre]:py-1.5 [&_pre]:font-mono [&_pre]:leading-relaxed',
         className
       )}
       data-slot="code-card-body"