fix(dashboard): use DS Button prefix/size API instead of inline icons

@nous-research/ui@0.18.2 Button is grid-based: size=xs is an
aspect-square icon-only box, and icons belong in prefix/suffix.
The dashboard used shadcn-style size=xs + inline <Icon/> text
children, which forced text buttons into broken tall squares
(Configure, Run setup, Select, Save keys) and split icon/label
across grid columns elsewhere (Schedule it, Prune/Delete actions).

Move leading icons to prefix and size text buttons as sm/default.
For the post-setup spinner, drive the spin from a button-level
[&_svg]:animate-spin selector since the prefix slot clones the
icon and overwrites its className.

- ToolsetConfigDrawer: Select, Save keys, Run setup
- SkillsPage: New skill, Configure
- AutomationBlueprints: Schedule it
- SessionsPage: Prune old sessions, Delete empty, Delete selected

.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

@@ -599,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
@@ -1155,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:
@@ -1223,6 +1227,12 @@ 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

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/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_loop.py

@@ -474,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.
@@ -489,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:
@@ -510,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,
@@ -3752,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/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/pet/__init__.py

@@ -1,51 +0,0 @@
-"""Petdex pet engine — shared core for the CLI, TUI, and desktop surfaces.
-
-Petdex (https://github.com/crafter-station/petdex) is a public gallery of
-animated sprite "pets" for coding agents.  Each pet is a ``pet.json`` plus a
-``spritesheet.{webp,png}`` of 192×208 px cells. Current Codex/petdex sheets use
-an 8-column × 9-row atlas; older Hermes/petdex sheets used an 8-row atlas.
-Hermes infers the row taxonomy from the sheet and maps agent activity onto
-idle/run/review/failed/wave/jump.
-
-This package is the **single source of truth** for the feature so the base
-CLI (Python) and TUI (Ink, via ``tui_gateway``) never duplicate the hard
-parts:
-
-- :mod:`agent.pet.constants` — frame geometry + the :class:`PetState` enum.
-- :mod:`agent.pet.state`     — map agent activity → a :class:`PetState`.
-- :mod:`agent.pet.manifest`  — fetch the public petdex manifest.
-- :mod:`agent.pet.store`     — install / list / resolve pets on disk
-                               (profile-aware via ``get_hermes_home()``).
-- :mod:`agent.pet.render`    — decode a spritesheet and encode frames for a
-                               terminal (kitty / iTerm2 / sixel graphics
-                               protocols, with a Unicode half-block
-                               fallback).
-
-Rendering in the Electron desktop is necessarily TypeScript (canvas), but it
-reuses the same on-disk store and the same state semantics.
-
-The whole feature is a *display* concern: it adds no model tool, mutates no
-system prompt or toolset, and therefore has zero effect on prompt caching.
-"""
-
-from agent.pet.constants import (
-    DEFAULT_SCALE,
-    FRAME_H,
-    FRAME_W,
-    FRAMES_PER_STATE,
-    LOOP_MS,
-    STATE_ROWS,
-    PetState,
-)
-from agent.pet.state import derive_pet_state
-
-__all__ = [
-    "DEFAULT_SCALE",
-    "FRAME_H",
-    "FRAME_W",
-    "FRAMES_PER_STATE",
-    "LOOP_MS",
-    "STATE_ROWS",
-    "PetState",
-    "derive_pet_state",
-]

agent/pet/constants.py

@@ -1,167 +0,0 @@
-"""Pet sprite geometry + animation-state taxonomy.
-
-These values are the common petdex/Codex pet geometry. The real ``pet.json``
-usually only carries ``id``/``displayName``/``description``/``spritesheetPath``;
-row taxonomy is inferred from the atlas shape so Hermes can render both legacy
-8-row sheets and current 9-row Codex sheets.
-"""
-
-from __future__ import annotations
-
-from enum import Enum
-
-# Frame geometry (pixels). Current Codex/petdex spritesheets are 8 columns x 9
-# rows (1536x1872), while older Hermes/petdex sheets used 9 columns x 8 rows
-# (1728x1664). Renderers derive both row taxonomy and real column count from the
-# concrete sheet, so either shape works.
-FRAME_W = 192
-FRAME_H = 208
-
-# Frames consumed per animation state (the petdex web app uses CSS
-# ``steps(6)``).  A sheet may physically contain more columns; we only step
-# through the first ``FRAMES_PER_STATE``.
-FRAMES_PER_STATE = 6
-
-# Full-loop duration for one state, milliseconds (petdex default).
-LOOP_MS = 1100
-
-# Default on-screen scale relative to native frame size.  ``display.pet.scale``
-# is the single master scalar: the desktop canvas multiplies its native pixels
-# by it and every terminal surface derives its half-block/kitty column width
-# from it (see :func:`cols_for_scale`), so one number shrinks all three
-# interfaces together.  (petdex's own clients render at 0.7; we default smaller
-# so the kitty/GUI mascot stays a glanceable corner sprite.  The half-block
-# fallback can't shrink as far — see ``UNICODE_MIN_COLS`` — and clamps to its
-# legibility floor instead.)
-DEFAULT_SCALE = 0.33
-
-# User-settable scale bounds (``/pet scale``, desktop slider).  Floor keeps the
-# pet clickable/visible; ceiling stops a fat-fingered value from filling the
-# screen.  The unicode fallback additionally clamps to ``UNICODE_MIN_COLS``.
-MIN_SCALE = 0.1
-MAX_SCALE = 3.0
-
-
-def clamp_scale(scale: float) -> float:
-    """Clamp *scale* to ``[MIN_SCALE, MAX_SCALE]`` (the single validation point)."""
-    return max(MIN_SCALE, min(MAX_SCALE, scale))
-
-# Terminal cells one native frame spans at ``scale == 1.0``.  A cell is ~8px
-# wide, a frame is ``FRAME_W`` (192) px → 24 cells.  This mirrors the kitty
-# graphics placement (``scaled_px // 8``) so at full scale every renderer agrees.
-BASE_UNICODE_COLS = FRAME_W // 8
-
-# Legibility floor for the half-block fallback.  A half-block cell samples the
-# sprite at only 1 horizontal + 2 vertical taps, so below this width a 192×208
-# pet collapses into an unreadable blob *regardless* of scale.  kitty/GUI draw
-# true pixels and have no such floor — that's why the same ``scale: 0.33`` is
-# crisp there but mush in half-blocks.  ``scale`` shrinks the unicode pet down
-# TO this floor (and grows it above), instead of past it into noise.
-UNICODE_MIN_COLS = 16
-
-
-def cols_for_scale(scale: float) -> int:
-    """Half-block width implied by *scale*, clamped to the legibility floor.
-
-    Above the floor it tracks the kitty cell box (``scaled_px // 8``) so the two
-    renderers converge at larger sizes; below it the floor keeps the sprite
-    readable rather than letting it devolve into a blob.
-    """
-    return max(UNICODE_MIN_COLS, round(BASE_UNICODE_COLS * (scale or DEFAULT_SCALE)))
-
-
-def resolve_cols(scale: float, unicode_cols: int = 0) -> int:
-    """Resolve terminal width: explicit *unicode_cols* override, else from *scale*."""
-    return int(unicode_cols) if unicode_cols and int(unicode_cols) > 0 else cols_for_scale(scale)
-
-
-class PetState(str, Enum):
-    """Animation state a pet can be shown in.
-
-    These are Hermes' activity state names. They are not always identical to the
-    source atlas row names: Codex-format pets use rows like ``jumping`` /
-    ``running`` while the UI keeps the shorter ``jump`` / ``run`` names.
-    """
-
-    IDLE = "idle"
-    WAVE = "wave"
-    RUN = "run"
-    FAILED = "failed"
-    REVIEW = "review"
-    JUMP = "jump"
-    WAITING = "waiting"
-
-
-# Legacy Hermes/petdex row order (top -> bottom) used by the older 8-row,
-# 9-column atlas shape.
-LEGACY_STATE_ROWS: list[str] = [
-    PetState.IDLE.value,
-    PetState.WAVE.value,
-    PetState.RUN.value,
-    PetState.FAILED.value,
-    PetState.REVIEW.value,
-    PetState.JUMP.value,
-    "extra1",
-    "extra2",
-]
-
-# Current Petdex row order (top -> bottom) used by 1536x1872 atlases:
-# 8 columns x 9 rows of 192x208 cells.
-CODEX_STATE_ROWS: list[str] = [
-    PetState.IDLE.value,
-    "running-right",
-    "running-left",
-    "waving",
-    "jumping",
-    PetState.FAILED.value,
-    PetState.WAITING.value,
-    "running",
-    PetState.REVIEW.value,
-]
-
-# Default/fallback for callers without a sheet. Prefer the current 9-row Codex
-# format because generated pets and the public Codex pet contract use it.
-STATE_ROWS: list[str] = CODEX_STATE_ROWS
-
-# Canonical Hermes activity names -> accepted row-name aliases in descending
-# preference. This keeps our internal state names stable (`wave`/`jump`/`run`)
-# while matching Petdex's current `waving`/`jumping`/`running` taxonomy.
-STATE_ALIASES: dict[str, tuple[str, ...]] = {
-    PetState.IDLE.value: (PetState.IDLE.value,),
-    PetState.WAVE.value: (PetState.WAVE.value, "waving"),
-    PetState.JUMP.value: (PetState.JUMP.value, "jumping"),
-    PetState.RUN.value: (PetState.RUN.value, "running"),
-    PetState.FAILED.value: (PetState.FAILED.value,),
-    PetState.REVIEW.value: (PetState.REVIEW.value,),
-    PetState.WAITING.value: (PetState.WAITING.value,),
-}
-
-
-def state_aliases_for(state: "PetState | str") -> tuple[str, ...]:
-    """Return accepted row-name aliases for *state* (always non-empty)."""
-    value = state.value if isinstance(state, PetState) else str(state)
-    aliases = STATE_ALIASES.get(value)
-    return aliases if aliases else (value,)
-
-
-def state_rows_for_grid(row_count: int | None) -> list[str]:
-    """Return the row taxonomy for a spritesheet with *row_count* rows."""
-    try:
-        rows = int(row_count or 0)
-    except (TypeError, ValueError):
-        rows = 0
-
-    if rows >= len(CODEX_STATE_ROWS):
-        return CODEX_STATE_ROWS
-    return LEGACY_STATE_ROWS
-
-
-def state_row_index(state: "PetState | str", row_count: int | None = None) -> int:
-    """Return the spritesheet row index for *state* (clamped, never raises)."""
-    rows = state_rows_for_grid(row_count)
-    for name in state_aliases_for(state):
-        try:
-            return rows.index(name)
-        except ValueError:
-            continue
-    return 0  # fall back to the idle row

agent/pet/generate/__init__.py

@@ -1,29 +0,0 @@
-"""Pet generation — base-draft → hatch pipeline.
-
-Public surface used by the gateway RPCs, the CLI ``hermes pets generate``
-command, and tests:
-
-- :func:`generate_base_drafts` / :func:`hatch_pet` — the two-step flow.
-- :class:`HatchResult`, :class:`GenerationError`.
-- :mod:`atlas` — deterministic frame extraction + atlas composition/validation.
-
-Image generation is delegated to the active reference-capable
-:class:`~agent.image_gen_provider.ImageGenProvider` (OpenAI gpt-image-2 or Krea);
-atlas assembly is fully deterministic so it's testable without any API calls.
-"""
-
-from __future__ import annotations
-
-from agent.pet.generate.imagegen import GenerationError
-from agent.pet.generate.orchestrate import (
-    HatchResult,
-    generate_base_drafts,
-    hatch_pet,
-)
-
-__all__ = [
-    "GenerationError",
-    "HatchResult",
-    "generate_base_drafts",
-    "hatch_pet",
-]

agent/pet/generate/atlas.py

@@ -1,400 +0,0 @@
-"""Deterministic spritesheet assembly — generated row strips → Hermes atlas.
-
-Image-generation models are good at *drawing* a row of poses but bad at exact
-grid geometry, so the model never owns the atlas layout: it produces one loose
-horizontal strip per state, and these deterministic ops slice that strip into
-clean, centered, transparent ``192x208`` cells and pack them into the sheet our
-renderer reads.
-
-The atlas is **Hermes-native**, not the petdex/Codex format. Our renderer
-(:mod:`agent.pet.render`) keys frames as ``rows = states, cols = frames`` using
-:data:`agent.pet.constants.STATE_ROWS`, so we emit exactly the six states the
-engine drives — idle, wave, run, failed, review, jump — left-packed with
-trailing transparent cells (which the renderer trims). Sheet is
-``COLUMNS*192 x ROWS*208`` (1152x1248).
-
-The frame-segmentation, fit-to-cell, and transparency-residue logic is adapted
-from OpenAI's ``hatch-pet`` skill (openai/skills, Apache-2.0).
-"""
-
-from __future__ import annotations
-
-import io
-import logging
-import math
-from pathlib import Path
-
-from agent.pet.constants import FRAME_H, FRAME_W
-
-logger = logging.getLogger(__name__)
-
-CELL_WIDTH = FRAME_W
-CELL_HEIGHT = FRAME_H
-
-# (state, row index, frame count). Order/row indices MUST match
-# ``STATE_ROWS`` so the renderer crops the right row for each driven state.
-# Frame counts are the petdex-ish per-state lengths; the renderer trims any
-# trailing blank columns, so rows shorter than ``COLUMNS`` just leave the tail
-# transparent.
-ROW_SPECS: list[tuple[str, int, int]] = [
-    ("idle", 0, 6),
-    ("wave", 1, 4),
-    ("run", 2, 6),
-    ("failed", 3, 6),
-    ("review", 4, 6),
-    ("jump", 5, 5),
-]
-
-ROWS = len(ROW_SPECS)
-COLUMNS = max(count for _, _, count in ROW_SPECS)
-ATLAS_WIDTH = COLUMNS * CELL_WIDTH
-ATLAS_HEIGHT = ROWS * CELL_HEIGHT
-
-FRAME_COUNTS: dict[str, int] = {state: count for state, _, count in ROW_SPECS}
-
-# Alpha at/below which a pixel is "background" for component detection.
-_ALPHA_FLOOR = 16
-# Cell padding kept around a fitted sprite so poses never touch the edge.
-_CELL_PAD = 10
-
-
-# ───────────────────────── background removal ─────────────────────────
-
-
-def _color_distance(r: int, g: int, b: int, key: tuple[int, int, int]) -> float:
-    return math.sqrt((r - key[0]) ** 2 + (g - key[1]) ** 2 + (b - key[2]) ** 2)
-
-
-def _has_transparency(image) -> bool:
-    """True if the strip already carries a real alpha background."""
-    extrema = image.getchannel("A").getextrema()
-    # Min alpha 0 somewhere and a meaningful share of fully-transparent pixels.
-    if extrema[0] > _ALPHA_FLOOR:
-        return False
-    hist = image.getchannel("A").histogram()
-    transparent = sum(hist[: _ALPHA_FLOOR + 1])
-    total = image.width * image.height
-    return transparent > total * 0.05
-
-
-def _dominant_corner_color(image) -> tuple[int, int, int]:
-    """Sample the four corners and return the most common opaque color."""
-    from collections import Counter
-
-    w, h = image.width, image.height
-    px = image.load()
-    counter: Counter = Counter()
-    for x, y in ((0, 0), (w - 1, 0), (0, h - 1), (w - 1, h - 1)):
-        r, g, b, a = px[x, y]
-        if a > _ALPHA_FLOOR:
-            counter[(r, g, b)] += 1
-    if not counter:
-        return (0, 255, 0)
-    return counter.most_common(1)[0][0]
-
-
-def remove_background(image, *, chroma_key: tuple[int, int, int] | None = None, threshold: float = 110.0):
-    """Return *image* (RGBA) with its flat background keyed out to transparent.
-
-    If the strip already has a transparent background we leave it alone; else we
-    key out *chroma_key* (or the dominant corner color when not given). This
-    handles both providers that emit transparency natively and those that paint
-    a solid backdrop.
-    """
-    rgba = image.convert("RGBA")
-    if _has_transparency(rgba):
-        return rgba
-
-    key = chroma_key or _dominant_corner_color(rgba)
-    px = rgba.load()
-    for y in range(rgba.height):
-        for x in range(rgba.width):
-            r, g, b, a = px[x, y]
-            if a > _ALPHA_FLOOR and _color_distance(r, g, b, key) <= threshold:
-                px[x, y] = (0, 0, 0, 0)
-    return rgba
-
-
-# ───────────────────────── frame extraction ─────────────────────────
-
-
-def _fit_to_cell(image):
-    """Crop to content, scale to fit a padded cell, and center on transparent."""
-    from PIL import Image
-
-    target = Image.new("RGBA", (CELL_WIDTH, CELL_HEIGHT), (0, 0, 0, 0))
-    bbox = image.getbbox()
-    if bbox is None:
-        return target
-
-    sprite = image.crop(bbox)
-    max_w = CELL_WIDTH - _CELL_PAD
-    max_h = CELL_HEIGHT - _CELL_PAD
-    scale = min(max_w / sprite.width, max_h / sprite.height, 1.0)
-    if scale != 1.0:
-        sprite = sprite.resize(
-            (max(1, round(sprite.width * scale)), max(1, round(sprite.height * scale))),
-            Image.Resampling.LANCZOS,
-        )
-    left = (CELL_WIDTH - sprite.width) // 2
-    top = (CELL_HEIGHT - sprite.height) // 2
-    target.alpha_composite(sprite, (left, top))
-    return target
-
-
-def _connected_components(image) -> list[dict]:
-    """Flood-fill the alpha mask into connected blobs (4-connectivity)."""
-    alpha = image.getchannel("A")
-    w, h = image.size
-    data = alpha.tobytes()
-    visited = bytearray(w * h)
-    out: list[dict] = []
-
-    for start, a in enumerate(data):
-        if a <= _ALPHA_FLOOR or visited[start]:
-            continue
-        stack = [start]
-        visited[start] = 1
-        pixels: list[int] = []
-        min_x = w
-        min_y = h
-        max_x = 0
-        max_y = 0
-        while stack:
-            cur = stack.pop()
-            pixels.append(cur)
-            x = cur % w
-            y = cur // w
-            min_x = min(min_x, x)
-            min_y = min(min_y, y)
-            max_x = max(max_x, x)
-            max_y = max(max_y, y)
-            for nb, ok in (
-                (cur - 1, x > 0),
-                (cur + 1, x + 1 < w),
-                (cur - w, y > 0),
-                (cur + w, y + 1 < h),
-            ):
-                if ok and not visited[nb] and data[nb] > _ALPHA_FLOOR:
-                    visited[nb] = 1
-                    stack.append(nb)
-        out.append(
-            {
-                "pixels": pixels,
-                "area": len(pixels),
-                "bbox": (min_x, min_y, max_x + 1, max_y + 1),
-                "center_x": (min_x + max_x + 1) / 2,
-            }
-        )
-    return out
-
-
-def _group_image(source, components: list[dict], padding: int = 4):
-    from PIL import Image
-
-    w, h = source.size
-    min_x = max(0, min(c["bbox"][0] for c in components) - padding)
-    min_y = max(0, min(c["bbox"][1] for c in components) - padding)
-    max_x = min(w, max(c["bbox"][2] for c in components) + padding)
-    max_y = min(h, max(c["bbox"][3] for c in components) + padding)
-
-    out = Image.new("RGBA", (max_x - min_x, max_y - min_y), (0, 0, 0, 0))
-    src_px = source.load()
-    out_px = out.load()
-    for c in components:
-        for idx in c["pixels"]:
-            x = idx % w
-            y = idx // w
-            out_px[x - min_x, y - min_y] = src_px[x, y]
-    return out
-
-
-def _component_frames(strip, frame_count: int) -> list | None:
-    """Segment a strip into *frame_count* sprites by connected components.
-
-    Picks the ``frame_count`` largest blobs as seeds (left→right), attaches
-    smaller blobs to the nearest seed, and returns one fitted cell per group.
-    Returns ``None`` when it can't find enough distinct sprites (caller falls
-    back to equal slicing).
-    """
-    components = _connected_components(strip)
-    if not components:
-        return None
-
-    largest = max(c["area"] for c in components)
-    seed_threshold = max(120, largest * 0.20)
-    seeds = [c for c in components if c["area"] >= seed_threshold]
-    if len(seeds) < frame_count:
-        seeds = sorted(components, key=lambda c: c["area"], reverse=True)[:frame_count]
-    if len(seeds) < frame_count:
-        return None
-
-    seeds = sorted(
-        sorted(seeds, key=lambda c: c["area"], reverse=True)[:frame_count],
-        key=lambda c: c["center_x"],
-    )
-    seed_ids = {id(s) for s in seeds}
-    groups: list[list[dict]] = [[s] for s in seeds]
-    noise_threshold = max(12, largest * 0.002)
-    for c in components:
-        if id(c) in seed_ids or c["area"] < noise_threshold:
-            continue
-        nearest = min(range(len(seeds)), key=lambda i: abs(seeds[i]["center_x"] - c["center_x"]))
-        groups[nearest].append(c)
-
-    return [_fit_to_cell(_group_image(strip, g)) for g in groups]
-
-
-def _slot_frames(strip, frame_count: int) -> list:
-    """Fallback: slice the strip into *frame_count* equal columns."""
-    slot = strip.width / frame_count
-    frames = []
-    for i in range(frame_count):
-        left = round(i * slot)
-        right = round((i + 1) * slot)
-        frames.append(_fit_to_cell(strip.crop((left, 0, right, strip.height))))
-    return frames
-
-
-def extract_strip_frames(
-    strip,
-    frame_count: int,
-    *,
-    chroma_key: tuple[int, int, int] | None = None,
-    method: str = "auto",
-) -> list:
-    """Turn one generated row strip into *frame_count* clean 192x208 cells.
-
-    *strip* is a PIL image (or path). Background is keyed out, then frames are
-    found by connected components (``auto``) with an equal-slot fallback.
-    """
-    from PIL import Image
-
-    if isinstance(strip, (str, Path)):
-        with Image.open(strip) as opened:
-            strip = opened.convert("RGBA")
-    else:
-        strip = strip.convert("RGBA")
-
-    strip = remove_background(strip, chroma_key=chroma_key)
-
-    if method in ("auto", "components"):
-        frames = _component_frames(strip, frame_count)
-        if frames is not None:
-            return frames
-        if method == "components":
-            raise ValueError(f"could not segment {frame_count} sprites from strip")
-    return _slot_frames(strip, frame_count)
-
-
-# ───────────────────────── atlas composition ─────────────────────────
-
-
-def single_frame(image):
-    """One fitted 192x208 cell from a standalone image (e.g. the base look).
-
-    Used as an idle fallback so a pet always renders even if the idle row
-    generation failed.
-    """
-    from PIL import Image
-
-    if isinstance(image, (str, Path)):
-        with Image.open(image) as opened:
-            image = opened.convert("RGBA")
-    return _fit_to_cell(remove_background(image))
-
-
-def _clear_transparent_rgb(image):
-    """Zero the RGB of fully-transparent pixels (no colored-halo residue)."""
-    from PIL import Image
-
-    rgba = image.convert("RGBA")
-    data = bytearray(rgba.tobytes())
-    for i in range(0, len(data), 4):
-        if data[i + 3] == 0:
-            data[i] = data[i + 1] = data[i + 2] = 0
-    return Image.frombytes("RGBA", rgba.size, bytes(data))
-
-
-def compose_atlas(frames_by_state: dict[str, list]):
-    """Pack per-state frame lists into the Hermes atlas (RGBA, residue-cleared).
-
-    Missing/short states leave their trailing cells transparent; extra frames
-    beyond a state's spec are dropped.
-    """
-    from PIL import Image
-
-    atlas = Image.new("RGBA", (ATLAS_WIDTH, ATLAS_HEIGHT), (0, 0, 0, 0))
-    for state, row, count in ROW_SPECS:
-        frames = frames_by_state.get(state) or []
-        for col, frame in enumerate(frames[:count]):
-            cell = frame.convert("RGBA")
-            if cell.size != (CELL_WIDTH, CELL_HEIGHT):
-                cell = _fit_to_cell(cell)
-            atlas.alpha_composite(cell, (col * CELL_WIDTH, row * CELL_HEIGHT))
-    return _clear_transparent_rgb(atlas)
-
-
-def atlas_to_webp_bytes(atlas) -> bytes:
-    """Encode an atlas image to lossless WebP bytes (the on-disk pet format)."""
-    buf = io.BytesIO()
-    atlas.save(buf, format="WEBP", lossless=True, quality=100, method=6, exact=True)
-    return buf.getvalue()
-
-
-def validate_atlas(atlas) -> dict:
-    """Check geometry, per-cell occupancy, and transparency invariants.
-
-    Returns ``{ok, width, height, errors, warnings, filled_states}``. Errors are
-    blockers (wrong size, empty used cell, opaque/dirty transparency); warnings
-    are soft (a whole state row blank — generation likely dropped a row).
-    """
-    from PIL import Image
-
-    if isinstance(atlas, (str, Path)):
-        with Image.open(atlas) as opened:
-            atlas = opened.convert("RGBA")
-    else:
-        atlas = atlas.convert("RGBA")
-
-    errors: list[str] = []
-    warnings: list[str] = []
-
-    if atlas.size != (ATLAS_WIDTH, ATLAS_HEIGHT):
-        errors.append(f"expected {ATLAS_WIDTH}x{ATLAS_HEIGHT}, got {atlas.width}x{atlas.height}")
-        return {"ok": False, "width": atlas.width, "height": atlas.height, "errors": errors, "warnings": warnings, "filled_states": []}
-
-    filled_states: list[str] = []
-    for state, row, count in ROW_SPECS:
-        row_pixels = 0
-        for col in range(count):
-            left = col * CELL_WIDTH
-            top = row * CELL_HEIGHT
-            cell = atlas.crop((left, top, left + CELL_WIDTH, top + CELL_HEIGHT))
-            nonblank = sum(cell.getchannel("A").histogram()[1:])
-            row_pixels += nonblank
-        if row_pixels > 0:
-            filled_states.append(state)
-        else:
-            warnings.append(f"state '{state}' has no frames")
-
-    if not filled_states:
-        errors.append("atlas is empty — no state produced any frames")
-
-    # Transparent pixels must carry zero RGB (no halo residue).
-    data = atlas.tobytes()
-    residue = 0
-    for i in range(0, len(data), 4):
-        if data[i + 3] == 0 and (data[i] or data[i + 1] or data[i + 2]):
-            residue += 1
-    if residue:
-        errors.append(f"{residue} transparent pixels retain RGB residue")
-
-    return {
-        "ok": not errors,
-        "width": atlas.width,
-        "height": atlas.height,
-        "errors": errors,
-        "warnings": warnings,
-        "filled_states": filled_states,
-    }

agent/pet/generate/imagegen.py

@@ -1,168 +0,0 @@
-"""Thin image-generation layer for pet sprites.
-
-Wraps the active :class:`~agent.image_gen_provider.ImageGenProvider` with the
-two things sprite generation needs that the agent-facing ``image_generate`` tool
-doesn't expose: **N variants** (loop) and **reference-image grounding** (so each
-animation row stays the same character as the chosen base).
-
-Reference grounding only works on providers that support it — currently OpenAI
-``gpt-image-2`` (image edits) and Krea (style references). We resolve to one of
-those and surface a clear, actionable error otherwise rather than silently
-producing an ungrounded, drifting pet.
-"""
-
-from __future__ import annotations
-
-import logging
-from dataclasses import dataclass
-from pathlib import Path
-
-logger = logging.getLogger(__name__)
-
-# Providers that can ground generation on a reference image.
-_REF_CAPABLE = ("openai", "openai-codex", "krea")
-
-
-class GenerationError(RuntimeError):
-    """Raised on any image-generation failure (no provider, API error, IO)."""
-
-
-@dataclass(frozen=True)
-class SpriteProvider:
-    """Resolved provider plus whether it can take reference images."""
-
-    name: str
-    provider: object
-    supports_references: bool
-
-
-def _discover() -> None:
-    try:
-        from hermes_cli.plugins import _ensure_plugins_discovered
-
-        _ensure_plugins_discovered()
-    except Exception as exc:  # noqa: BLE001 - discovery is best-effort
-        logger.debug("image-gen plugin discovery failed: %s", exc)
-
-
-def resolve_provider(*, require_references: bool = True) -> SpriteProvider:
-    """Pick the image provider to use for sprite work.
-
-    Preference: the configured provider when it's reference-capable, else the
-    first available reference-capable provider. With *require_references* off we
-    fall back to any available provider (used for prompt-only base drafts).
-    """
-    _discover()
-    from agent.image_gen_registry import get_active_provider, get_provider
-
-    # Configured / active provider first.
-    active = None
-    try:
-        active = get_active_provider()
-    except Exception:  # noqa: BLE001
-        active = None
-    if active is not None:
-        name = getattr(active, "name", "")
-        if name in _REF_CAPABLE and active.is_available():
-            return SpriteProvider(name=name, provider=active, supports_references=True)
-
-    # Any available reference-capable provider.
-    for name in _REF_CAPABLE:
-        provider = get_provider(name)
-        if provider is not None and provider.is_available():
-            return SpriteProvider(name=name, provider=provider, supports_references=True)
-
-    if not require_references and active is not None and active.is_available():
-        return SpriteProvider(
-            name=getattr(active, "name", "unknown"), provider=active, supports_references=False
-        )
-
-    raise GenerationError(
-        "Pet generation needs a reference-capable image backend. "
-        "Run `hermes tools` → Image Generation → OpenAI (gpt-image-2) and add an "
-        "OpenAI API key (or configure Krea)."
-    )
-
-
-def _save_local(image_ref: str, *, prefix: str) -> Path:
-    """Return a local path for *image_ref*, downloading it if it's a URL."""
-    if image_ref.startswith(("http://", "https://")):
-        from agent.image_gen_provider import save_url_image
-
-        return Path(save_url_image(image_ref, prefix=prefix))
-    return Path(image_ref)
-
-
-def _rejected_background(error: str) -> bool:
-    """True when a provider error is specifically about the ``background`` param.
-
-    Transparent backgrounds are a per-model capability (e.g. some gpt-image tiers
-    reject ``background=transparent`` outright). We detect that one rejection so
-    we can retry without the flag rather than failing the whole pet — our chroma
-    key pass makes the result transparent regardless.
-    """
-    lowered = (error or "").lower()
-    return "background" in lowered and ("not supported" in lowered or "transparent" in lowered)
-
-
-def generate(
-    prompt: str,
-    *,
-    n: int = 1,
-    reference_images: list[Path] | None = None,
-    provider: SpriteProvider | None = None,
-    prefix: str = "pet_gen",
-) -> list[Path]:
-    """Generate *n* square sprite images and return their local paths.
-
-    *reference_images* grounds the output on a base image (required for rows).
-    We *ask* for a transparent background, but fall back to an opaque generation
-    (cleaned up downstream by the chroma-key pass) on models that reject the
-    flag. Raises :class:`GenerationError` if nothing usable comes back.
-    """
-    sprite = provider or resolve_provider(require_references=bool(reference_images))
-    if reference_images and not sprite.supports_references:
-        raise GenerationError(
-            f"image backend '{sprite.name}' cannot use reference images; "
-            "configure OpenAI gpt-image-2 or Krea for pet generation"
-        )
-
-    refs = [str(p) for p in (reference_images or [])]
-
-    def _run(extra: dict) -> tuple[Path | None, str]:
-        kwargs: dict = {"aspect_ratio": "square", **extra}
-        if refs:
-            kwargs["reference_images"] = refs
-        try:
-            result = sprite.provider.generate(prompt, **kwargs)
-        except Exception as exc:  # noqa: BLE001 - normalize provider crashes
-            logger.debug("provider.generate crashed: %s", exc)
-            return None, str(exc)
-        if not isinstance(result, dict) or not result.get("success"):
-            return None, (result or {}).get("error", "unknown error") if isinstance(result, dict) else "no result"
-        image_ref = result.get("image")
-        if not image_ref:
-            return None, "provider returned no image"
-        try:
-            return _save_local(str(image_ref), prefix=prefix), ""
-        except Exception as exc:  # noqa: BLE001
-            return None, f"could not save generated image: {exc}"
-
-    out: list[Path] = []
-    last_error = ""
-    allow_transparent = True
-    for _ in range(max(1, n)):
-        path, err = _run({"background": "transparent"} if allow_transparent else {})
-        # Model doesn't support the transparent flag → drop it for this and every
-        # remaining variant (no point re-probing a capability we just disproved).
-        if path is None and allow_transparent and _rejected_background(err):
-            allow_transparent = False
-            path, err = _run({})
-        if path is not None:
-            out.append(path)
-        else:
-            last_error = err
-
-    if not out:
-        raise GenerationError(last_error or "image generation produced no output")
-    return out

agent/pet/generate/orchestrate.py

@@ -1,149 +0,0 @@
-"""Pet generation orchestration — the base-draft → hatch flow.
-
-Two steps, mirroring the UX across every surface:
-
-1. :func:`generate_base_drafts` — a handful of prompt-only "what should this pet
-   look like" variants. Cheap; the user picks one (or retries for a fresh set).
-2. :func:`hatch_pet` — takes the chosen base and generates one grounded row
-   strip per Hermes state, slices each into frames, composes the atlas, validates
-   it, and writes the pet into the store.
-
-Splitting it this way bounds cost (4 cheap base calls per round; the ~6 row
-calls happen once, on the pet you actually keep) and gives each UI a natural
-preview/loading point.
-"""
-
-from __future__ import annotations
-
-import logging
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Callable
-
-from agent.pet.generate import atlas, imagegen, prompts
-from agent.pet.generate.imagegen import GenerationError, SpriteProvider
-
-logger = logging.getLogger(__name__)
-
-# (event, detail) — e.g. ("row", "idle"), ("compose", ""), ("save", "<slug>").
-ProgressFn = Callable[[str, str], None]
-
-
-@dataclass(frozen=True)
-class HatchResult:
-    """Outcome of a successful :func:`hatch_pet`."""
-
-    slug: str
-    display_name: str
-    spritesheet: Path
-    states: list[str]
-    validation: dict
-
-
-def _harden_transparency(path: Path) -> Path:
-    """Key out any solid backdrop the provider painted; save as an RGBA PNG.
-
-    ``background=transparent`` is requested on every call, but image models honor
-    it inconsistently — some still paint a flat (often near-white) backdrop. We
-    run the same chroma-key pass the row extractor uses so every base draft the
-    user picks between (and the reference the rows are grounded on) is a clean
-    cutout. Best-effort: a decode failure leaves the original untouched.
-    """
-    from PIL import Image
-
-    try:
-        with Image.open(path) as opened:
-            keyed = atlas.remove_background(opened.convert("RGBA"))
-        out = path.with_suffix(".png")
-        keyed.save(out, format="PNG")
-        return out
-    except Exception as exc:  # noqa: BLE001 - cosmetic; fall back to the raw image
-        logger.debug("base draft transparency hardening failed for %s: %s", path, exc)
-        return path
-
-
-def generate_base_drafts(
-    concept: str,
-    *,
-    n: int = 4,
-    style: str = "auto",
-    provider: SpriteProvider | None = None,
-) -> list[Path]:
-    """Generate *n* candidate base looks for *concept*; returns image paths.
-
-    Each draft is hardened to a transparent cutout (see :func:`_harden_transparency`).
-    """
-    prompt = prompts.build_base_prompt(concept, style=style)
-    sprite = provider or imagegen.resolve_provider(require_references=False)
-    raw = imagegen.generate(prompt, n=n, provider=sprite, prefix="pet_base")
-    return [_harden_transparency(p) for p in raw]
-
-
-def hatch_pet(
-    *,
-    base_image: str | Path,
-    slug: str,
-    display_name: str = "",
-    description: str = "",
-    concept: str = "",
-    style: str = "auto",
-    on_progress: ProgressFn | None = None,
-    provider: SpriteProvider | None = None,
-) -> HatchResult:
-    """Turn an approved base image into a full, installed Hermes pet.
-
-    Generates a grounded row strip per state, extracts frames, composes +
-    validates the atlas, and registers it. The idle row falls back to the base
-    look so the pet always renders. Raises :class:`GenerationError` on failure.
-    """
-    base = Path(base_image)
-    if not base.is_file():
-        raise GenerationError(f"base image not found: {base}")
-
-    sprite = provider or imagegen.resolve_provider(require_references=True)
-    progress = on_progress or (lambda *_: None)
-    label = concept or display_name or slug
-
-    frames_by_state: dict[str, list] = {}
-    for state, _row, count in atlas.ROW_SPECS:
-        progress("row", state)
-        row_prompt = prompts.build_row_prompt(state, count, label, style=style)
-        try:
-            strips = imagegen.generate(
-                row_prompt,
-                n=1,
-                reference_images=[base],
-                provider=sprite,
-                prefix=f"pet_row_{state}",
-            )
-            frames_by_state[state] = atlas.extract_strip_frames(strips[0], count, method="auto")
-        except Exception as exc:  # noqa: BLE001 - a single row may fail; keep going
-            logger.warning("pet row '%s' failed: %s", state, exc)
-
-    # Idle is the resting state the renderer falls back to — guarantee it.
-    if not frames_by_state.get("idle"):
-        progress("row", "idle-fallback")
-        frames_by_state["idle"] = [atlas.single_frame(base)]
-
-    progress("compose", "")
-    sheet = atlas.compose_atlas(frames_by_state)
-    validation = atlas.validate_atlas(sheet)
-    if not validation["ok"]:
-        raise GenerationError("; ".join(validation["errors"]) or "atlas validation failed")
-
-    from agent.pet import store
-
-    progress("save", slug)
-    pet = store.register_local_pet(
-        sheet,
-        slug=slug,
-        display_name=display_name or slug,
-        description=description,
-    )
-    return HatchResult(
-        slug=pet.slug,
-        display_name=pet.display_name,
-        spritesheet=pet.spritesheet,
-        states=validation["filled_states"],
-        validation=validation,
-    )

agent/pet/generate/prompts.py

@@ -1,74 +0,0 @@
-"""Prompt builders for pet generation.
-
-Two prompt shapes: a *base* prompt (prompt-only, produces the canonical look the
-user picks between) and per-*state* *row* prompts (grounded on the chosen base,
-produce one horizontal strip of N poses). Prompts stay concise and
-sprite-production oriented; the identity lock and "one transparent row" framing
-matter more than flowery description.
-
-Hermes drives six states (see :data:`agent.pet.generate.atlas.ROW_SPECS`); these
-mirror that set rather than the petdex/Codex nine.
-"""
-
-from __future__ import annotations
-
-# What each Hermes state should depict (kept short — these go straight into the
-# row prompt). Phrased to avoid the common sprite-gen failure modes (detached
-# effects, motion lines, shadows).
-STATE_ACTIONS: dict[str, str] = {
-    "idle": "a calm idle loop: subtle breathing, a tiny blink or gentle bob, no big gestures",
-    "wave": "a friendly greeting: raising a paw/hand/limb to wave, clear up-and-down gesture",
-    "run": "focused active work: leaning in, concentrating, busy 'thinking/processing' energy (NOT foot-running)",
-    "failed": "a sad or deflated reaction: slumped, dejected, small frown — readable but not noisy",
-    "review": "careful inspection: a focused lean, head tilt, studying something intently",
-    "jump": "a happy celebration jump: anticipation, lift off the ground, peak, and land",
-}
-
-_STYLE_HINTS: dict[str, str] = {
-    "auto": "",
-    "pixel": " Render in clean pixel-art style.",
-    "plush": " Render as a soft plush toy.",
-    "clay": " Render as a claymation / soft 3D clay figure.",
-    "sticker": " Render as a glossy die-cut sticker.",
-    "flat-vector": " Render in flat vector mascot style.",
-    "3d-toy": " Render as a glossy 3D toy.",
-    "painterly": " Render in a soft painterly style.",
-}
-
-_BACKGROUND = (
-    "Center one full-body character on a fully transparent background. "
-    "No text, no labels, no shadow, no ground line, no scenery, no frame, no border."
-)
-
-
-def style_hint(style: str | None) -> str:
-    return _STYLE_HINTS.get((style or "auto").strip().lower(), "")
-
-
-def build_base_prompt(concept: str, *, style: str | None = "auto") -> str:
-    """The base look: a single, clean, centered full-body mascot."""
-    concept = (concept or "a cute friendly mascot creature").strip()
-    return (
-        f"A cute, characterful mascot pet: {concept}. "
-        "Compact, whole-body silhouette that reads clearly at small size, "
-        "appealing face, simple consistent palette. "
-        f"{_BACKGROUND}{style_hint(style)}"
-    )
-
-
-def build_row_prompt(state: str, frame_count: int, concept: str, *, style: str | None = "auto") -> str:
-    """A row strip: *frame_count* poses of the SAME character, left→right.
-
-    The attached base image is the identity source of truth; the prompt locks
-    species, palette, face, and props to it.
-    """
-    action = STATE_ACTIONS.get(state, "a simple idle pose")
-    concept = (concept or "the mascot").strip()
-    return (
-        f"Using the attached reference image as the exact same character "
-        f"(same species, face, colors, markings, proportions, and props), "
-        f"draw a single horizontal strip of {frame_count} animation frames showing {action}. "
-        f"The {frame_count} poses must be evenly spaced left to right, each fully separated "
-        "(not overlapping), same size and baseline, forming a smooth loop. "
-        f"Keep the character identical across all frames. {_BACKGROUND}{style_hint(style)}"
-    )

agent/pet/manifest.py

@@ -1,128 +0,0 @@
-"""Fetch the public petdex manifest.
-
-``https://petdex.dev/api/manifest`` 307-redirects to a JSON document on R2:
-
-    {
-      "generatedAt": "...",
-      "total": 2926,
-      "pets": [
-        {"slug": "boba", "displayName": "Boba", "kind": "creature",
-         "submittedBy": "railly",
-         "spritesheetUrl": "https://assets.petdex.dev/.../spritesheet.webp",
-         "petJsonUrl": "https://assets.petdex.dev/.../pet.json",
-         "zipUrl": "https://assets.petdex.dev/.../boba.zip"},
-        ...
-      ]
-    }
-
-Read-only and unauthenticated; no credentials involved.
-"""
-
-from __future__ import annotations
-
-import logging
-import time
-from dataclasses import dataclass
-
-logger = logging.getLogger(__name__)
-
-MANIFEST_URL = "https://petdex.dev/api/manifest"
-
-_DEFAULT_TIMEOUT = 20.0
-
-# In-process cache for the (large, slow, identical-per-call) manifest. The list
-# is a static CDN object that barely changes, yet a single session can ask for
-# it many times — every gallery open, plus a full re-fetch per install/select
-# (``find_entry``). A short TTL collapses those into one network hit without
-# going stale for long. Cleared by :func:`clear_cache` (tests).
-_MANIFEST_TTL = 300.0
-_cache: tuple[float, list[ManifestEntry]] | None = None
-
-
-def clear_cache() -> None:
-    """Drop the cached manifest (forces the next fetch to hit the network)."""
-    global _cache
-    _cache = None
-
-
-@dataclass(frozen=True)
-class ManifestEntry:
-    """A single pet's row in the manifest."""
-
-    slug: str
-    display_name: str
-    kind: str
-    submitted_by: str
-    spritesheet_url: str
-    pet_json_url: str
-    zip_url: str
-
-    @classmethod
-    def from_dict(cls, data: dict) -> "ManifestEntry":
-        return cls(
-            slug=str(data.get("slug", "")).strip(),
-            display_name=str(data.get("displayName", "") or data.get("slug", "")),
-            kind=str(data.get("kind", "") or "pet"),
-            submitted_by=str(data.get("submittedBy", "") or ""),
-            spritesheet_url=str(data.get("spritesheetUrl", "") or ""),
-            pet_json_url=str(data.get("petJsonUrl", "") or ""),
-            zip_url=str(data.get("zipUrl", "") or ""),
-        )
-
-
-class ManifestError(RuntimeError):
-    """Raised when the manifest can't be fetched or parsed."""
-
-
-def fetch_manifest(*, timeout: float = _DEFAULT_TIMEOUT, force: bool = False) -> list[ManifestEntry]:
-    """Return every approved pet from the public manifest.
-
-    Cached in-process for ``_MANIFEST_TTL`` seconds (pass ``force=True`` to
-    bypass). Follows the 307 redirect to R2.  Raises :class:`ManifestError` on
-    any network/parse failure so callers can surface a clean message.
-    """
-    global _cache
-
-    if not force and _cache is not None and time.monotonic() - _cache[0] < _MANIFEST_TTL:
-        return _cache[1]
-
-    try:
-        import httpx
-    except ImportError as exc:  # pragma: no cover - httpx is a core dep
-        raise ManifestError("httpx is required to fetch the petdex manifest") from exc
-
-    try:
-        resp = httpx.get(
-            MANIFEST_URL,
-            timeout=timeout,
-            follow_redirects=True,
-            headers={"User-Agent": "hermes-agent-petdex"},
-        )
-        resp.raise_for_status()
-        payload = resp.json()
-    except Exception as exc:  # noqa: BLE001 - normalize to one error type
-        raise ManifestError(f"could not fetch petdex manifest: {exc}") from exc
-
-    pets = payload.get("pets") if isinstance(payload, dict) else None
-    if not isinstance(pets, list):
-        raise ManifestError("petdex manifest had no 'pets' array")
-
-    entries: list[ManifestEntry] = []
-    for raw in pets:
-        if not isinstance(raw, dict):
-            continue
-        entry = ManifestEntry.from_dict(raw)
-        if entry.slug and entry.spritesheet_url:
-            entries.append(entry)
-
-    _cache = (time.monotonic(), entries)
-    return entries
-
-
-def find_entry(slug: str, *, timeout: float = _DEFAULT_TIMEOUT) -> ManifestEntry | None:
-    """Return the manifest entry for *slug*, or ``None`` if not listed."""
-    slug = slug.strip().lower()
-    for entry in fetch_manifest(timeout=timeout):
-        if entry.slug.lower() == slug:
-            return entry
-    return None

agent/pet/render.py

@@ -1,618 +0,0 @@
-"""Decode a pet spritesheet and encode frames for a terminal.
-
-Shared by the base CLI (writes the escape bytes to its own stdout) and the
-TUI (``tui_gateway`` ships the encoded bytes to Ink, which writes them) so the
-decode + capability-detection + protocol-encoding logic exists exactly once.
-
-Supported output modes, in fidelity order:
-
-- ``kitty``   — the kitty graphics protocol (kitty, Ghostty, WezTerm).
-- ``iterm``   — iTerm2 inline images (iTerm2, WezTerm).
-- ``sixel``   — DEC sixel (xterm -ti vt340, foot, mlterm, WezTerm, …).
-- ``unicode`` — 24-bit half-block downscale; works in any truecolor terminal.
-
-Frame decoding requires Pillow (a core Hermes dependency).  If Pillow or the
-spritesheet is unavailable the renderer degrades to ``unicode`` text or an
-empty string rather than raising.
-"""
-
-from __future__ import annotations
-
-import base64
-import io
-import logging
-import os
-import sys
-from functools import lru_cache
-from pathlib import Path
-
-from agent.pet.constants import (
-    DEFAULT_SCALE,
-    FRAME_H,
-    FRAME_W,
-    FRAMES_PER_STATE,
-    PetState,
-    state_row_index,
-)
-
-logger = logging.getLogger(__name__)
-
-# Public render-mode names accepted by ``display.pet.render_mode``.
-RENDER_MODES = ("auto", "kitty", "iterm", "sixel", "unicode", "off")
-
-
-# ─────────────────────────────────────────────────────────────────────────
-# Terminal capability detection
-# ─────────────────────────────────────────────────────────────────────────
-
-def detect_terminal_graphics() -> str:
-    """Best-effort detection of the richest graphics protocol available.
-
-    Env-based (non-blocking — we never issue a DA1/terminal query that could
-    hang a pipe).  Returns one of ``kitty`` / ``iterm`` / ``sixel`` /
-    ``unicode``.  Conservative: unknown terminals get ``unicode``, which works
-    anywhere with truecolor.
-    """
-    term = os.environ.get("TERM", "").lower()
-    term_program = os.environ.get("TERM_PROGRAM", "").lower()
-
-    # The VS Code / Cursor integrated terminal sets TERM_PROGRAM=vscode
-    # authoritatively but does NOT scrub the terminal env vars it inherits when
-    # launched from another emulator (ITERM_SESSION_ID, KITTY_WINDOW_ID, …).
-    # Trusting those leaks emits an image protocol the embedded xterm.js can't
-    # display — you get a blank frame. Inline images there are opt-in
-    # (terminal.integrated.enableImages), so default to half-blocks, which
-    # always render in its truecolor grid. Users who enabled images can pin
-    # display.pet.render_mode explicitly.
-    if term_program == "vscode":
-        return "unicode"
-
-    # kitty graphics protocol
-    if os.environ.get("KITTY_WINDOW_ID") or "kitty" in term or "ghostty" in term:
-        return "kitty"
-    if term_program in {"ghostty"}:
-        return "kitty"
-
-    # WezTerm speaks both kitty and iterm; prefer kitty (richer placement).
-    if term_program == "wezterm" or os.environ.get("WEZTERM_PANE"):
-        return "kitty"
-
-    # iTerm2 inline images
-    if term_program == "iterm.app" or os.environ.get("ITERM_SESSION_ID"):
-        return "iterm"
-
-    # sixel-capable terminals (env heuristics only)
-    if term_program in {"mintty"} or "foot" in term or "mlterm" in term:
-        return "sixel"
-    if "sixel" in term:
-        return "sixel"
-
-    return "unicode"
-
-
-def resolve_mode(configured: str | None, *, stream=None) -> str:
-    """Resolve the effective render mode from config + the environment.
-
-    ``configured`` is ``display.pet.render_mode`` (``auto`` → detect).  Returns
-    ``off`` when not attached to a TTY (no point emitting graphics into a pipe
-    or logfile).
-    """
-    mode = (configured or "auto").strip().lower()
-    if mode not in RENDER_MODES:
-        mode = "auto"
-    if mode == "off":
-        return "off"
-
-    stream = stream or sys.stdout
-    try:
-        if not (hasattr(stream, "isatty") and stream.isatty()):
-            return "off"
-    except (ValueError, OSError):
-        return "off"
-
-    if mode == "auto":
-        return detect_terminal_graphics()
-    return mode
-
-
-# ─────────────────────────────────────────────────────────────────────────
-# Frame decoding
-# ─────────────────────────────────────────────────────────────────────────
-
-def _open_sheet(path: Path):
-    from PIL import Image
-
-    img = Image.open(path)
-    return img.convert("RGBA")
-
-
-# Max alpha at/below which a frame counts as blank padding.  petdex sheets are
-# left-packed: a state with fewer real frames than ``FRAMES_PER_STATE`` fills
-# the trailing columns with fully transparent cells.  Animating into one flashes
-# the pet blank, so we stop the row at the first such gap.
-_BLANK_ALPHA = 8
-
-
-def _frame_is_blank(frame) -> bool:
-    """True if *frame* has no meaningfully opaque pixel (transparent padding)."""
-    return frame.getchannel("A").getextrema()[1] <= _BLANK_ALPHA
-
-
-@lru_cache(maxsize=16)
-def _raw_frames(
-    sheet_path: str,
-    state_value: str,
-    frame_w: int,
-    frame_h: int,
-    frames_per_state: int,
-) -> tuple:
-    """Cropped, padding-trimmed RGBA frames for one state row (unscaled).
-
-    Steps across the row until the first blank column so pets with ragged
-    per-state frame counts never animate into empty padding.  Cached; returns
-    ``()`` on any decode failure.
-    """
-    try:
-        sheet = _open_sheet(Path(sheet_path))
-        cols = max(1, sheet.width // frame_w)
-        rows = max(1, sheet.height // frame_h)
-        row = state_row_index(state_value, rows)
-        top = row * frame_h
-        # Clamp the row to the sheet (some pets ship fewer rows than the 8 the
-        # taxonomy reserves).
-        if top + frame_h > sheet.height:
-            top = max(0, sheet.height - frame_h)
-
-        frames = []
-        for i in range(min(frames_per_state, cols)):
-            left = i * frame_w
-            frame = sheet.crop((left, top, left + frame_w, top + frame_h))
-            if _frame_is_blank(frame):
-                break  # trailing transparent padding — real frames end here
-            frames.append(frame)
-        return tuple(frames)
-    except Exception as exc:  # noqa: BLE001 - cosmetic feature, never fatal
-        logger.debug("pet frame decode failed (%s, %s): %s", sheet_path, state_value, exc)
-        return ()
-
-
-@lru_cache(maxsize=8)
-def _frames_for(
-    sheet_path: str,
-    state_value: str,
-    frame_w: int,
-    frame_h: int,
-    frames_per_state: int,
-    scale_w: int,
-    scale_h: int,
-):
-    """Return padding-trimmed RGBA frames for one state row, scaled.
-
-    Thin scaling layer over :func:`_raw_frames`; both are cached so repeated
-    frame requests during animation are free.
-    """
-    raw = _raw_frames(sheet_path, state_value, frame_w, frame_h, frames_per_state)
-    if not raw or (scale_w, scale_h) == (frame_w, frame_h):
-        return list(raw)
-    from PIL import Image
-
-    return [f.resize((scale_w, scale_h), Image.LANCZOS) for f in raw]
-
-
-def state_frame_counts(
-    sheet_path: str | Path,
-    *,
-    frame_w: int = FRAME_W,
-    frame_h: int = FRAME_H,
-    frames_per_state: int = FRAMES_PER_STATE,
-) -> dict[str, int]:
-    """Map each driven :class:`PetState` → its real (padding-trimmed) frame count.
-
-    The single source of truth for "how many frames does this state actually
-    have?".  The CLI/TUI consume the trimmed frame lists directly; the gateway
-    ships this map to the desktop canvas, which steps its own loop.
-    """
-    return {
-        state.value: len(
-            _raw_frames(str(sheet_path), state.value, frame_w, frame_h, frames_per_state)
-        )
-        for state in PetState
-    }
-
-
-# ─────────────────────────────────────────────────────────────────────────
-# Encoders
-# ─────────────────────────────────────────────────────────────────────────
-
-def _png_bytes(frame) -> bytes:
-    buf = io.BytesIO()
-    frame.save(buf, format="PNG")
-    return buf.getvalue()
-
-
-def _kitty_apc(ctrl: str, data: str) -> str:
-    """Emit a kitty APC escape for *data*, chunked into ≤4096-byte ``m`` pieces."""
-    chunk = 4096
-    if len(data) <= chunk:
-        return f"\x1b_G{ctrl},m=0;{data}\x1b\\"
-    out = [f"\x1b_G{ctrl},m=1;{data[:chunk]}\x1b\\"]
-    rest = data[chunk:]
-    while rest:
-        piece, rest = rest[:chunk], rest[chunk:]
-        out.append(f"\x1b_Gm={1 if rest else 0};{piece}\x1b\\")
-    return "".join(out)
-
-
-def _encode_kitty(frame, *, cell_cols: int | None = None, cell_rows: int | None = None) -> str:
-    """Encode one frame via the kitty graphics protocol (transmit + display).
-
-    ``a=T`` transmits & displays at the cursor; ``c``/``r`` request a display
-    box in terminal cells so successive frames overwrite the same area.
-    """
-    ctrl = "f=100,a=T,q=2"
-    if cell_cols:
-        ctrl += f",c={cell_cols}"
-    if cell_rows:
-        ctrl += f",r={cell_rows}"
-    return _kitty_apc(ctrl, base64.standard_b64encode(_png_bytes(frame)).decode("ascii"))
-
-
-# ─────────────────────────────────────────────────────────────────────────
-# kitty Unicode placeholders
-#
-# Ink (the TUI's React-for-terminal layer) owns the screen and measures every
-# cell's width, so it can't host raw kitty image escapes (no width to count,
-# clobbered on the next repaint). kitty's *Unicode placeholder* protocol is the
-# grid-safe path: transmit the image once (q=2, virtual placement U=1), then the
-# host app prints ordinary-width placeholder cells (U+10EEEE + diacritics) whose
-# foreground color encodes the image id. Ink counts those as width-1 text, so
-# layout stays correct and the terminal paints the image underneath.
-#   https://sw.kovidgoyal.net/kitty/graphics-protocol/#unicode-placeholders
-# ─────────────────────────────────────────────────────────────────────────
-
-_KITTY_PLACEHOLDER = "\U0010eeee"
-
-# Row/column diacritics, in order (index → diacritic). Verbatim from kitty's
-# gen/rowcolumn-diacritics.txt (Unicode 6.0.0, combining class 230). Index i is
-# the diacritic that encodes the number i; we only ever need the row index.
-_ROWCOL_DIACRITICS: tuple[int, ...] = (
-    0x0305, 0x030D, 0x030E, 0x0310, 0x0312, 0x033D, 0x033E, 0x033F, 0x0346, 0x034A,
-    0x034B, 0x034C, 0x0350, 0x0351, 0x0352, 0x0357, 0x035B, 0x0363, 0x0364, 0x0365,
-    0x0366, 0x0367, 0x0368, 0x0369, 0x036A, 0x036B, 0x036C, 0x036D, 0x036E, 0x036F,
-    0x0483, 0x0484, 0x0485, 0x0486, 0x0487, 0x0592, 0x0593, 0x0594, 0x0595, 0x0597,
-    0x0598, 0x0599, 0x059C, 0x059D, 0x059E, 0x059F, 0x05A0, 0x05A1, 0x05A8, 0x05A9,
-    0x05AB, 0x05AC, 0x05AF, 0x05C4, 0x0610, 0x0611, 0x0612, 0x0613, 0x0614, 0x0615,
-    0x0616, 0x0617, 0x0657, 0x0658, 0x0659, 0x065A, 0x065B, 0x065D, 0x065E, 0x06D6,
-    0x06D7, 0x06D8, 0x06D9, 0x06DA, 0x06DB, 0x06DC, 0x06DF, 0x06E0, 0x06E1, 0x06E2,
-    0x06E4, 0x06E7, 0x06E8, 0x06EB, 0x06EC, 0x0730, 0x0732, 0x0733, 0x0735, 0x0736,
-    0x073A, 0x073D, 0x073F, 0x0740, 0x0741, 0x0743, 0x0745, 0x0747, 0x0749, 0x074A,
-    0x07EB, 0x07EC, 0x07ED, 0x07EE, 0x07EF, 0x07F0, 0x07F1, 0x07F3, 0x0816, 0x0817,
-    0x0818, 0x0819, 0x081B, 0x081C, 0x081D, 0x081E, 0x081F, 0x0820, 0x0821, 0x0822,
-    0x0823, 0x0825, 0x0826, 0x0827, 0x0829, 0x082A, 0x082B, 0x082C, 0x082D, 0x0951,
-    0x0953, 0x0954, 0x0F82, 0x0F83, 0x0F86, 0x0F87, 0x135D, 0x135E, 0x135F, 0x17DD,
-    0x193A, 0x1A17, 0x1A75, 0x1A76, 0x1A77, 0x1A78, 0x1A79, 0x1A7A, 0x1A7B, 0x1A7C,
-    0x1B6B, 0x1B6D, 0x1B6E, 0x1B6F, 0x1B70, 0x1B71, 0x1B72, 0x1B73, 0x1CD0, 0x1CD1,
-    0x1CD2, 0x1CDA, 0x1CDB, 0x1CE0, 0x1DC0, 0x1DC1, 0x1DC3, 0x1DC4, 0x1DC5, 0x1DC6,
-    0x1DC7, 0x1DC8, 0x1DC9, 0x1DCB, 0x1DCC, 0x1DD1, 0x1DD2, 0x1DD3, 0x1DD4, 0x1DD5,
-    0x1DD6, 0x1DD7, 0x1DD8, 0x1DD9, 0x1DDA, 0x1DDB, 0x1DDC, 0x1DDD, 0x1DDE, 0x1DDF,
-    0x1DE0, 0x1DE1, 0x1DE2, 0x1DE3, 0x1DE4, 0x1DE5, 0x1DE6, 0x1DFE, 0x20D0, 0x20D1,
-    0x20D4, 0x20D5, 0x20D6, 0x20D7, 0x20DB, 0x20DC, 0x20E1, 0x20E7, 0x20E9, 0x20F0,
-    0x2CEF, 0x2CF0, 0x2CF1, 0x2DE0, 0x2DE1, 0x2DE2, 0x2DE3, 0x2DE4, 0x2DE5, 0x2DE6,
-    0x2DE7, 0x2DE8, 0x2DE9, 0x2DEA, 0x2DEB, 0x2DEC, 0x2DED, 0x2DEE, 0x2DEF, 0x2DF0,
-    0x2DF1, 0x2DF2, 0x2DF3, 0x2DF4, 0x2DF5, 0x2DF6, 0x2DF7, 0x2DF8, 0x2DF9, 0x2DFA,
-    0x2DFB, 0x2DFC, 0x2DFD, 0x2DFE, 0x2DFF, 0xA66F, 0xA67C, 0xA67D, 0xA6F0, 0xA6F1,
-    0xA8E0, 0xA8E1, 0xA8E2, 0xA8E3, 0xA8E4, 0xA8E5, 0xA8E6, 0xA8E7, 0xA8E8, 0xA8E9,
-    0xA8EA, 0xA8EB, 0xA8EC, 0xA8ED, 0xA8EE, 0xA8EF, 0xA8F0, 0xA8F1, 0xAAB0, 0xAAB2,
-    0xAAB3, 0xAAB7, 0xAAB8, 0xAABE, 0xAABF, 0xAAC1, 0xFE20, 0xFE21, 0xFE22, 0xFE23,
-    0xFE24, 0xFE25, 0xFE26, 0x10A0F, 0x10A38, 0x1D185, 0x1D186, 0x1D187, 0x1D188,
-    0x1D189, 0x1D1AA, 0x1D1AB, 0x1D1AC, 0x1D1AD, 0x1D242, 0x1D243, 0x1D244,
-)
-
-
-def kitty_image_id(slug: str) -> int:
-    """Stable per-pet image id in ``[1, 0x7FFF]``.
-
-    The id is encoded in the placeholder's 24-bit foreground color, so it must
-    be non-zero and fit comfortably under ``0xFFFFFF``. A small CRC keeps it
-    deterministic per slug (so re-renders reuse the same terminal-side image)
-    while making collisions between two different pets unlikely.
-    """
-    import zlib
-
-    return (zlib.crc32(slug.encode("utf-8")) % 0x7FFE) + 1
-
-
-def kitty_color_hex(image_id: int) -> str:
-    """Hex foreground color (``#rrggbb``) that encodes *image_id* for kitty."""
-    return "#%06x" % (image_id & 0xFFFFFF)
-
-
-def kitty_placeholder_rows(cols: int, rows: int) -> list[str]:
-    """Build the placeholder text grid for an *rows*×*cols* image.
-
-    Each line is one row of the grid: the first cell carries the row diacritic
-    (column defaults to 0), and the remaining ``cols-1`` bare placeholders let
-    the terminal auto-increment the column. The foreground color (the image id)
-    is applied by the caller / Ink, not embedded here.
-    """
-    cols = max(1, cols)
-    out: list[str] = []
-    for r in range(max(1, rows)):
-        idx = min(r, len(_ROWCOL_DIACRITICS) - 1)
-        first = _KITTY_PLACEHOLDER + chr(_ROWCOL_DIACRITICS[idx])
-        out.append(first + _KITTY_PLACEHOLDER * (cols - 1))
-    return out
-
-
-def _encode_kitty_virtual(frame, *, image_id: int, cols: int, rows: int) -> str:
-    """Transmit a frame as a kitty *virtual* placement for Unicode placeholders.
-
-    ``a=T`` transmits and creates the placement in one shot; ``U=1`` marks it
-    virtual (no on-screen output, cursor untouched); ``q=2`` suppresses the
-    terminal's OK/error replies that would otherwise corrupt the host app's
-    output. Re-sending with the same ``i`` replaces the image, so the static
-    placeholder cells animate underneath.
-    """
-    ctrl = f"a=T,U=1,i={image_id},c={cols},r={rows},f=100,q=2"
-    return _kitty_apc(ctrl, base64.standard_b64encode(_png_bytes(frame)).decode("ascii"))
-
-
-def _encode_iterm(frame, *, cell_cols: int | None = None, cell_rows: int | None = None) -> str:
-    """Encode one frame as an iTerm2 inline image (OSC 1337 File)."""
-    payload = base64.standard_b64encode(_png_bytes(frame)).decode("ascii")
-    size = len(payload)
-    args = [f"inline=1", f"size={size}", "preserveAspectRatio=1"]
-    if cell_cols:
-        args.append(f"width={cell_cols}")
-    if cell_rows:
-        args.append(f"height={cell_rows}")
-    return f"\x1b]1337;File={';'.join(args)}:{payload}\x07"
-
-
-def _encode_sixel(frame) -> str:
-    """Encode one frame as DEC sixel.
-
-    Quantizes to an adaptive palette (≤255 colors) and emits the sixel band
-    stream.  Pillow has no sixel writer, so this is a compact hand-rolled
-    encoder.  Transparent pixels render as background (color register skipped).
-    """
-    from PIL import Image
-
-    rgba = frame
-    # Composite onto transparent-as-skip: track alpha to decide background.
-    pal = rgba.convert("RGB").quantize(colors=255, method=Image.MEDIANCUT)
-    palette = pal.getpalette() or []
-    px = pal.load()
-    alpha = rgba.getchannel("A").load()
-    w, h = pal.size
-
-    out = ["\x1bP0;1;0q", '"1;1;%d;%d' % (w, h)]
-    # Color register definitions (sixel uses 0..100 scale).
-    used = sorted({px[x, y] for y in range(h) for x in range(w)})
-    for idx in used:
-        r = palette[idx * 3] if idx * 3 < len(palette) else 0
-        g = palette[idx * 3 + 1] if idx * 3 + 1 < len(palette) else 0
-        b = palette[idx * 3 + 2] if idx * 3 + 2 < len(palette) else 0
-        out.append("#%d;2;%d;%d;%d" % (idx, r * 100 // 255, g * 100 // 255, b * 100 // 255))
-
-    # Emit in 6-row bands.
-    for band in range(0, h, 6):
-        for color_idx in used:
-            line = ["#%d" % color_idx]
-            run_char = None
-            run_len = 0
-
-            def flush():
-                nonlocal run_char, run_len
-                if run_char is None:
-                    return
-                if run_len > 3:
-                    line.append("!%d%s" % (run_len, run_char))
-                else:
-                    line.append(run_char * run_len)
-                run_char, run_len = None, 0
-
-            for x in range(w):
-                bits = 0
-                for bit in range(6):
-                    y = band + bit
-                    if y < h and alpha[x, y] > 32 and px[x, y] == color_idx:
-                        bits |= 1 << bit
-                ch = chr(63 + bits)
-                if ch == run_char:
-                    run_len += 1
-                else:
-                    flush()
-                    run_char, run_len = ch, 1
-            flush()
-            out.append("".join(line) + "$")  # carriage return within band
-        out.append("-")  # next band
-    out.append("\x1b\\")
-    return "".join(out)
-
-
-_HALF_BLOCK = "▀"
-
-# A single half-block cell: top pixel + bottom pixel as (r, g, b, a) tuples.
-Cell = tuple[tuple[int, int, int, int], tuple[int, int, int, int]]
-
-
-def _downscale_cells(frame, *, target_cols: int) -> list[list[Cell]]:
-    """Downscale a frame to a grid of half-block cells.
-
-    Each cell pairs a top and bottom pixel so one terminal row encodes two
-    pixel rows.  Returns rows of ``((tr,tg,tb,ta),(br,bg,bb,ba))`` — the
-    framework-neutral representation shared by the ANSI encoder (CLI) and the
-    structured ``cells`` API (Ink).
-    """
-    from PIL import Image
-
-    target_cols = max(4, target_cols)
-    aspect = frame.height / max(1, frame.width)
-    target_rows = max(2, int(round(target_cols * aspect * 0.5)) * 2)
-    small = frame.resize((target_cols, target_rows), Image.LANCZOS).convert("RGBA")
-    px = small.load()
-
-    grid: list[list[Cell]] = []
-    for y in range(0, target_rows, 2):
-        row: list[Cell] = []
-        for x in range(target_cols):
-            top = px[x, y]
-            bottom = px[x, y + 1] if y + 1 < target_rows else (0, 0, 0, 0)
-            row.append((top, bottom))
-        grid.append(row)
-    return grid
-
-
-def _encode_unicode(frame, *, target_cols: int) -> str:
-    """Downscale to truecolor ANSI half-blocks (one char = 2 vertical pixels)."""
-    lines: list[str] = []
-    for row in _downscale_cells(frame, target_cols=target_cols):
-        cells: list[str] = []
-        for (tr, tg, tb, ta), (br, bg, bb, ba) in row:
-            if ta < 32 and ba < 32:
-                cells.append("\x1b[0m ")  # fully transparent → blank
-                continue
-            cells.append(f"\x1b[38;2;{tr};{tg};{tb}m\x1b[48;2;{br};{bg};{bb}m{_HALF_BLOCK}")
-        lines.append("".join(cells) + "\x1b[0m")
-    return "\n".join(lines)
-
-
-# ─────────────────────────────────────────────────────────────────────────
-# Public renderer
-# ─────────────────────────────────────────────────────────────────────────
-
-class PetRenderer:
-    """Holds a pet's spritesheet and yields encoded frames per (state, index).
-
-    Construct once per pet, then call :meth:`frame` on an animation timer.
-    Cheap to call repeatedly — decoded frames are cached.
-    """
-
-    def __init__(
-        self,
-        spritesheet: str | Path,
-        *,
-        mode: str = "unicode",
-        scale: float = DEFAULT_SCALE,
-        unicode_cols: int = 20,
-        frame_w: int = FRAME_W,
-        frame_h: int = FRAME_H,
-        frames_per_state: int = FRAMES_PER_STATE,
-    ) -> None:
-        self.spritesheet = str(spritesheet)
-        self.mode = mode if mode in RENDER_MODES else "unicode"
-        self.scale = scale
-        self.unicode_cols = unicode_cols
-        self.frame_w = frame_w
-        self.frame_h = frame_h
-        self.frames_per_state = frames_per_state
-
-    @property
-    def available(self) -> bool:
-        return self.mode != "off" and Path(self.spritesheet).is_file()
-
-    def frame_count(self, state: PetState | str) -> int:
-        return len(self._frames(state))
-
-    def _frames(self, state: PetState | str):
-        value = state.value if isinstance(state, PetState) else str(state)
-        scale_w = max(1, int(self.frame_w * self.scale))
-        scale_h = max(1, int(self.frame_h * self.scale))
-        return _frames_for(
-            self.spritesheet,
-            value,
-            self.frame_w,
-            self.frame_h,
-            self.frames_per_state,
-            scale_w,
-            scale_h,
-        )
-
-    def cells(self, state: PetState | str, index: int, *, cols: int | None = None) -> list[list[Cell]]:
-        """Return one frame as a half-block cell grid (framework-neutral).
-
-        Used by the TUI, which renders the grid with native Ink color props
-        instead of raw ANSI.  Returns ``[]`` when no frame is available.
-        """
-        frames = self._frames(state)
-        if not frames:
-            return []
-        frame = frames[index % len(frames)]
-        return _downscale_cells(frame, target_cols=cols or self.unicode_cols)
-
-    def _cell_box(self, frame) -> tuple[int, int]:
-        """Terminal cell box for a scaled frame (~8×16 px per cell).
-
-        Must match :meth:`frame` graphics sizing — kitty stretches the image to
-        fill ``c``×``r`` cells, so these must reflect the scaled pixel
-        dimensions, not a native-aspect column count (that upscales small pets).
-        """
-        return max(1, frame.width // 8), max(1, frame.height // 16)
-
-    def kitty_payload(self, state: PetState | str, *, image_id: int) -> dict | None:
-        """Build the kitty Unicode-placeholder payload for one state.
-
-        Returns ``{cols, rows, placeholder, frames}`` where ``frames`` is a
-        list of transmit escapes (one per animation frame, all reusing
-        ``image_id``) and ``placeholder`` is the static text grid Ink paints.
-        Placement geometry is derived from the scaled frame pixels (via
-        :meth:`_cell_box`), not ``unicode_cols`` — kitty upscales to fill
-        ``c``×``r`` cells. ``None`` when no frame is available.
-        """
-        frames = self._frames(state)
-        if not frames:
-            return None
-        cols, rows = self._cell_box(frames[0])
-        return {
-            "cols": cols,
-            "rows": rows,
-            "placeholder": kitty_placeholder_rows(cols, rows),
-            "frames": [
-                _encode_kitty_virtual(f, image_id=image_id, cols=cols, rows=rows) for f in frames
-            ],
-        }
-
-    def frame(self, state: PetState | str, index: int) -> str:
-        """Return the encoded escape string for one frame, or ``""``.
-
-        ``index`` is taken modulo the available frame count so callers can pass
-        a free-running counter.
-        """
-        if self.mode == "off":
-            return ""
-        frames = self._frames(state)
-        if not frames:
-            return ""
-        frame = frames[index % len(frames)]
-        cell_cols, cell_rows = self._cell_box(frame)
-
-        try:
-            if self.mode == "kitty":
-                return _encode_kitty(frame, cell_cols=cell_cols, cell_rows=cell_rows)
-            if self.mode == "iterm":
-                return _encode_iterm(frame, cell_cols=cell_cols, cell_rows=cell_rows)
-            if self.mode == "sixel":
-                return _encode_sixel(frame)
-            return _encode_unicode(frame, target_cols=self.unicode_cols)
-        except Exception as exc:  # noqa: BLE001 - degrade silently
-            logger.debug("pet frame encode failed (mode=%s): %s", self.mode, exc)
-            return ""
-
-
-def build_renderer(
-    spritesheet: str | Path,
-    *,
-    configured_mode: str | None = None,
-    scale: float = DEFAULT_SCALE,
-    unicode_cols: int = 20,
-    stream=None,
-) -> PetRenderer:
-    """Convenience factory: resolve the mode from config+env, then construct."""
-    mode = resolve_mode(configured_mode, stream=stream)
-    return PetRenderer(
-        spritesheet,
-        mode=mode,
-        scale=scale,
-        unicode_cols=unicode_cols,
-    )

agent/pet/state.py

@@ -1,81 +0,0 @@
-"""Map agent activity → a :class:`PetState`.
-
-This is the one place the "what is the agent doing right now?" → "which
-animation row?" decision lives.  Each surface feeds it the signals it already
-tracks:
-
-- CLI    — ``KawaiiSpinner`` waiting/thinking state + tool outcomes.
-- TUI    — gateway ``tool.start/complete`` + ``message.delta/complete`` events.
-- Desktop — the ``$busy``/``$awaitingResponse``/tool-event nanostores
-            (re-implemented in TS, but mirroring this priority order).
-
-Keeping the priority order here (and documenting it) lets the TypeScript
-mirror stay faithful without a second design.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Iterable
-from typing import Any
-
-from agent.pet.constants import PetState
-
-
-def todos_all_done(todos: Iterable[Any] | None) -> bool:
-    """True iff there's ≥1 todo and every one is completed/cancelled.
-
-    The "celebrate" beat (``JUMP``) fires when a plan finishes; this mirrors
-    the TUI's ``isTodoDone`` so the trigger is defined once across surfaces.
-    Accepts dicts (``{"status": ...}``) or objects with a ``status`` attr.
-    """
-    items = list(todos or [])
-    if not items:
-        return False
-
-    def _status(t: Any) -> Any:
-        return t.get("status") if isinstance(t, dict) else getattr(t, "status", None)
-
-    return all(_status(t) in ("completed", "cancelled") for t in items)
-
-
-def derive_pet_state(
-    *,
-    busy: bool = False,
-    awaiting_input: bool = False,
-    error: bool = False,
-    celebrate: bool = False,
-    just_completed: bool = False,
-    tool_running: bool = False,
-    reasoning: bool = False,
-) -> PetState:
-    """Resolve the animation state from coarse activity signals.
-
-    Priority (highest first) — only one row can show at a time, so the most
-    salient signal wins:
-
-    1. ``error``          → ``FAILED``  (a tool/turn just failed)
-    2. ``celebrate``      → ``JUMP``    (explicit success beat, e.g. todos done)
-    3. ``just_completed`` → ``WAVE``    (turn finished cleanly / greeting)
-    4. ``awaiting_input`` → ``WAITING`` (blocked on the user — a clarify/approval
-       prompt is open; this outranks the in-flight signals below because the turn
-       is paused on *you*, even though a tool is technically mid-call)
-    5. ``tool_running``   → ``RUN``     (a tool is executing)
-    6. ``reasoning``      → ``REVIEW``  (model is thinking / reading)
-    7. ``busy``           → ``RUN``     (turn in flight, unspecified work)
-    8. otherwise          → ``IDLE``
-    """
-    if error:
-        return PetState.FAILED
-    if celebrate:
-        return PetState.JUMP
-    if just_completed:
-        return PetState.WAVE
-    if awaiting_input:
-        return PetState.WAITING
-    if tool_running:
-        return PetState.RUN
-    if reasoning:
-        return PetState.REVIEW
-    if busy:
-        return PetState.RUN
-    return PetState.IDLE

agent/pet/store.py

@@ -1,388 +0,0 @@
-"""On-disk pet store — install / list / resolve pets.
-
-Pets live under ``get_hermes_home()/pets/<slug>/`` so every profile gets its
-own set (we deliberately do **not** reuse petdex's ``~/.codex/pets`` default —
-that's owned by the petdex npm CLI and isn't profile-aware).  Each installed
-pet directory holds:
-
-    pets/<slug>/
-        pet.json            # {id, displayName, description, spritesheetPath}
-        spritesheet.webp    # (or .png)
-
-The active pet is resolved from the caller-supplied ``display.pet.slug`` config
-value (falling back to the first installed pet), so this module stays free of
-the config loader.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import re
-from dataclasses import dataclass
-from pathlib import Path
-
-from hermes_constants import get_hermes_home
-
-logger = logging.getLogger(__name__)
-
-_DOWNLOAD_TIMEOUT = 60.0
-
-
-class PetStoreError(RuntimeError):
-    """Raised on install/IO failures."""
-
-
-@dataclass(frozen=True)
-class InstalledPet:
-    """A pet present on disk."""
-
-    slug: str
-    display_name: str
-    description: str
-    directory: Path
-    spritesheet: Path
-
-    @property
-    def exists(self) -> bool:
-        return self.spritesheet.is_file()
-
-
-def pets_dir() -> Path:
-    """Return the profile-scoped pets directory (created on demand)."""
-    path = get_hermes_home() / "pets"
-    path.mkdir(parents=True, exist_ok=True)
-    return path
-
-
-def _read_pet_json(directory: Path) -> dict:
-    pet_json = directory / "pet.json"
-    if not pet_json.is_file():
-        return {}
-    try:
-        return json.loads(pet_json.read_text(encoding="utf-8"))
-    except (OSError, ValueError) as exc:
-        logger.debug("unreadable pet.json in %s: %s", directory, exc)
-        return {}
-
-
-def _resolve_spritesheet(directory: Path, meta: dict) -> Path:
-    """Find the spritesheet for a pet dir.
-
-    Honors ``spritesheetPath`` from pet.json, else probes the conventional
-    filenames (``spritesheet.{webp,png}`` and petdex R2's ``sprite.webp``).
-    """
-    declared = str(meta.get("spritesheetPath", "") or "").strip()
-    if declared:
-        candidate = directory / declared
-        if candidate.is_file():
-            return candidate
-    for name in ("spritesheet.webp", "spritesheet.png", "sprite.webp", "sprite.png"):
-        candidate = directory / name
-        if candidate.is_file():
-            return candidate
-    # Default expectation even if missing, so callers get a stable path.
-    return directory / "spritesheet.webp"
-
-
-def load_pet(slug: str) -> InstalledPet | None:
-    """Return the :class:`InstalledPet` for *slug*, or ``None`` if absent."""
-    slug = slug.strip()
-    directory = pets_dir() / slug
-    if not directory.is_dir():
-        return None
-    meta = _read_pet_json(directory)
-    return InstalledPet(
-        slug=slug,
-        display_name=str(meta.get("displayName", "") or slug),
-        description=str(meta.get("description", "") or ""),
-        directory=directory,
-        spritesheet=_resolve_spritesheet(directory, meta),
-    )
-
-
-def installed_pets() -> list[InstalledPet]:
-    """Return every installed pet (dirs containing a usable spritesheet)."""
-    out: list[InstalledPet] = []
-    for child in sorted(pets_dir().iterdir()):
-        if not child.is_dir():
-            continue
-        pet = load_pet(child.name)
-        if pet and pet.exists:
-            out.append(pet)
-    return out
-
-
-def resolve_active_pet(configured_slug: str | None = None) -> InstalledPet | None:
-    """Resolve which pet to display.
-
-    Precedence: the configured slug (``display.pet.slug``) if it's installed,
-    otherwise the first installed pet alphabetically, otherwise ``None``.
-    """
-    if configured_slug:
-        pet = load_pet(configured_slug.strip())
-        if pet and pet.exists:
-            return pet
-    pets = installed_pets()
-    return pets[0] if pets else None
-
-
-def install_pet(slug: str, *, force: bool = False, timeout: float = _DOWNLOAD_TIMEOUT) -> InstalledPet:
-    """Download *slug* from the manifest into the pets directory.
-
-    Idempotent: a fully-installed pet is returned as-is unless *force*.  Raises
-    :class:`PetStoreError` / :class:`~agent.pet.manifest.ManifestError` on
-    failure.
-    """
-    from agent.pet.manifest import find_entry
-
-    slug = slug.strip()
-    existing = load_pet(slug)
-    if existing and existing.exists and not force:
-        return existing
-
-    entry = find_entry(slug, timeout=timeout)
-    if entry is None:
-        raise PetStoreError(f"pet '{slug}' is not in the petdex manifest")
-
-    directory = pets_dir() / slug
-    directory.mkdir(parents=True, exist_ok=True)
-
-    sprite_ext = ".png" if entry.spritesheet_url.lower().split("?")[0].endswith(".png") else ".webp"
-    sprite_path = directory / f"spritesheet{sprite_ext}"
-
-    _download(entry.spritesheet_url, sprite_path, timeout=timeout)
-
-    # Fetch the upstream pet.json if present; otherwise synthesize a minimal
-    # one so the local layout is self-describing.
-    meta: dict = {}
-    if entry.pet_json_url:
-        try:
-            meta = _download_json(entry.pet_json_url, timeout=timeout)
-        except Exception as exc:  # noqa: BLE001 - non-fatal, fall back below
-            logger.debug("pet.json fetch failed for %s: %s", slug, exc)
-    if not isinstance(meta, dict) or not meta:
-        meta = {"id": slug, "displayName": entry.display_name, "description": ""}
-    meta["spritesheetPath"] = sprite_path.name
-    meta.setdefault("id", slug)
-    meta.setdefault("displayName", entry.display_name)
-    (directory / "pet.json").write_text(json.dumps(meta, indent=2), encoding="utf-8")
-
-    pet = load_pet(slug)
-    if pet is None or not pet.exists:
-        raise PetStoreError(f"install of '{slug}' did not produce a spritesheet")
-    return pet
-
-
-def slugify(name: str) -> str:
-    """Lowercase, hyphenate, and strip a display name into a filesystem slug."""
-    slug = re.sub(r"[^a-z0-9]+", "-", (name or "").strip().lower()).strip("-")
-    return slug or "pet"
-
-
-def unique_slug(name: str) -> str:
-    """A :func:`slugify` result that doesn't collide with an existing pet dir."""
-    base = slugify(name)
-    slug = base
-    counter = 2
-    while (pets_dir() / slug).exists():
-        slug = f"{base}-{counter}"
-        counter += 1
-    return slug
-
-
-def _write_spritesheet(source, dest: Path) -> None:
-    """Write *source* (PIL image, bytes, or path) as a lossless WebP at *dest*."""
-    if isinstance(source, (bytes, bytearray)):
-        dest.write_bytes(bytes(source))
-        return
-
-    from PIL import Image
-
-    if isinstance(source, (str, Path)):
-        with Image.open(source) as opened:
-            image = opened.convert("RGBA")
-    else:
-        image = source.convert("RGBA")
-    image.save(dest, format="WEBP", lossless=True, quality=100, method=6, exact=True)
-
-
-def register_local_pet(
-    spritesheet,
-    *,
-    slug: str,
-    display_name: str = "",
-    description: str = "",
-) -> InstalledPet:
-    """Write a locally-generated pet into the store and return it.
-
-    *spritesheet* may be a PIL image, raw WebP/PNG bytes, or a path. The pet
-    appears in :func:`installed_pets` immediately, and because :func:`install_pet`
-    returns an already-on-disk pet before consulting the manifest, it can be
-    adopted (``pet.select`` / ``/pet <slug>``) without a manifest entry.
-    """
-    slug = slugify(slug)
-    directory = pets_dir() / slug
-    directory.mkdir(parents=True, exist_ok=True)
-    sprite_path = directory / "spritesheet.webp"
-    try:
-        _write_spritesheet(spritesheet, sprite_path)
-    except Exception as exc:  # noqa: BLE001 - normalize to one error type
-        raise PetStoreError(f"could not write spritesheet for '{slug}': {exc}") from exc
-
-    meta = {
-        "id": slug,
-        "displayName": display_name or slug,
-        "description": description or "",
-        "spritesheetPath": sprite_path.name,
-        "createdBy": "generator",
-    }
-    (directory / "pet.json").write_text(json.dumps(meta, indent=2), encoding="utf-8")
-
-    pet = load_pet(slug)
-    if pet is None or not pet.exists:
-        raise PetStoreError(f"register of generated pet '{slug}' did not produce a spritesheet")
-    return pet
-
-
-_THUMB_FRAME_W = 192
-_THUMB_FRAME_H = 208
-_THUMB_W = 96  # rendered ~40px; 2x+ keeps it crisp on HiDPI
-
-
-def _thumbs_dir() -> Path:
-    path = pets_dir() / ".thumbs"
-    path.mkdir(parents=True, exist_ok=True)
-    return path
-
-
-def _is_petdex_host(url: str) -> bool:
-    """True only for petdex.dev hosts — bounds server-side fetch (anti-SSRF)."""
-    from urllib.parse import urlparse
-
-    try:
-        host = (urlparse(url).hostname or "").lower()
-    except ValueError:
-        return False
-    return host == "petdex.dev" or host.endswith(".petdex.dev")
-
-
-def thumbnail_png(slug: str, *, source_url: str = "", timeout: float = 30.0) -> bytes | None:
-    """Return a small idle-frame PNG for *slug*, cached on disk.
-
-    Crops the top-left (idle, frame 0) cell of the spritesheet and downsamples
-    it to a thumbnail. Source preference: an installed spritesheet on disk, else
-    *source_url* — but only when it points at petdex (so the gateway never
-    fetches an arbitrary client-supplied URL). Returns ``None`` when there's no
-    usable source or Pillow/network fails; callers render a placeholder.
-
-    Doing this server-side sidesteps the renderer's CSP / R2 hotlink limits that
-    break a direct ``<img src=cdn>`` and lets the result ride the authenticated
-    gateway as a same-origin data URL.
-    """
-    slug = slug.strip()
-    if not slug:
-        return None
-
-    cache = _thumbs_dir() / f"{slug}.png"
-    if cache.is_file():
-        try:
-            return cache.read_bytes()
-        except OSError:
-            pass
-
-    sheet_bytes: bytes | None = None
-    pet = load_pet(slug)
-    if pet and pet.exists:
-        try:
-            sheet_bytes = pet.spritesheet.read_bytes()
-        except OSError:
-            sheet_bytes = None
-
-    if sheet_bytes is None and source_url and _is_petdex_host(source_url):
-        try:
-            import httpx
-
-            resp = httpx.get(
-                source_url,
-                timeout=timeout,
-                follow_redirects=True,
-                headers={"User-Agent": "hermes-agent-petdex"},
-            )
-            resp.raise_for_status()
-            sheet_bytes = resp.content
-        except Exception as exc:  # noqa: BLE001 - cosmetic, degrade to placeholder
-            logger.debug("thumb fetch failed for %s: %s", slug, exc)
-
-    if not sheet_bytes:
-        return None
-
-    try:
-        import io
-
-        from PIL import Image
-
-        with Image.open(io.BytesIO(sheet_bytes)) as im:
-            frame = im.convert("RGBA").crop(
-                (0, 0, min(_THUMB_FRAME_W, im.width), min(_THUMB_FRAME_H, im.height))
-            )
-            height = round(_THUMB_W * _THUMB_FRAME_H / _THUMB_FRAME_W)
-            frame = frame.resize((_THUMB_W, height), Image.NEAREST)
-            buf = io.BytesIO()
-            frame.save(buf, format="PNG")
-            data = buf.getvalue()
-    except Exception as exc:  # noqa: BLE001
-        logger.debug("thumb crop failed for %s: %s", slug, exc)
-        return None
-
-    try:
-        cache.write_bytes(data)
-    except OSError:
-        pass
-    return data
-
-
-def remove_pet(slug: str) -> bool:
-    """Delete an installed pet directory.  Returns True if anything was removed."""
-    import shutil
-
-    directory = pets_dir() / slug.strip()
-    if not directory.is_dir():
-        return False
-    shutil.rmtree(directory, ignore_errors=True)
-    return not directory.exists()
-
-
-def _download(url: str, dest: Path, *, timeout: float) -> None:
-    import httpx
-
-    try:
-        with httpx.stream(
-            "GET",
-            url,
-            timeout=timeout,
-            follow_redirects=True,
-            headers={"User-Agent": "hermes-agent-petdex"},
-        ) as resp:
-            resp.raise_for_status()
-            tmp = dest.with_suffix(dest.suffix + ".part")
-            with tmp.open("wb") as fh:
-                for chunk in resp.iter_bytes():
-                    fh.write(chunk)
-            tmp.replace(dest)
-    except Exception as exc:  # noqa: BLE001
-        raise PetStoreError(f"download failed for {url}: {exc}") from exc
-
-
-def _download_json(url: str, *, timeout: float) -> dict:
-    import httpx
-
-    resp = httpx.get(
-        url,
-        timeout=timeout,
-        follow_redirects=True,
-        headers={"User-Agent": "hermes-agent-petdex"},
-    )
-    resp.raise_for_status()
-    data = resp.json()
-    return data if isinstance(data, dict) else {}

agent/prompt_builder.py

@@ -305,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.
@@ -386,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. "
@@ -958,13 +1000,41 @@ 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 _get_context_file_max_chars() -> int:
-    """Return the configured context-file truncation limit.
 
-    ``CONTEXT_FILE_MAX_CHARS`` remains the upstream-compatible default and
-    fallback. Users with larger context windows can raise
-    ``context_file_max_chars`` in config.yaml without patching Hermes.
+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
@@ -974,7 +1044,7 @@ def _get_context_file_max_chars() -> int:
             return int(val)
     except Exception as e:
         logger.debug("Could not read context_file_max_chars from config: %s", e)
-    return CONTEXT_FILE_MAX_CHARS
+    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 /
@@ -1510,16 +1580,30 @@ 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: Optional[int] = None) -> 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()
+        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"increase context_file_max_chars or trim the file!"
+        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)
@@ -1527,11 +1611,16 @@ def _truncate_content(content: str, filename: str, max_chars: Optional[int] = No
     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
@@ -1552,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:
@@ -1576,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
@@ -1592,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
@@ -1608,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"
@@ -1641,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):
@@ -1654,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).
@@ -1667,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/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,
@@ -83,6 +84,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] = []
 
@@ -91,7 +103,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
@@ -112,6 +124,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:
@@ -334,7 +357,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)
 

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/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
@@ -44,6 +45,7 @@ const { readDirForIpc } = require('./fs-read-dir.cjs')
 const { gitRootForIpc } = require('./git-root.cjs')
 const { worktreesForIpc } = require('./git-worktrees.cjs')
 const { OFFICIAL_REPO_HTTPS_URL, isOfficialSshRemote } = require('./update-remote.cjs')
+const { runRebuildWithRetry } = require('./update-rebuild.cjs')
 const {
   buildPosixCleanupScript,
   buildWindowsCleanupScript,
@@ -2008,10 +2010,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 +5112,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) {
@@ -5155,142 +5154,6 @@ function createNewSessionWindow() {
   return spawnSecondaryWindow({ newSession: true })
 }
 
-// The pet overlay: a single transparent, frameless, always-on-top window that
-// hosts ONLY the floating mascot. Shift-clicking the in-window pet "pops it out"
-// here so it can leave the app's bounds and stay visible while Hermes is
-// minimized (Codex-style task-completion glance). It carries no gateway
-// connection of its own — the main renderer is the single source of truth and
-// pushes pet state over IPC (hermes:pet-overlay:state); the overlay just renders
-// it. Control flows back (pop-in, composer submit) via hermes:pet-overlay:control.
-let petOverlayWindow = null
-
-function petOverlayUrl() {
-  if (DEV_SERVER) {
-    return `${DEV_SERVER.endsWith('/') ? DEV_SERVER.slice(0, -1) : DEV_SERVER}/?win=overlay#/`
-  }
-
-  return `${pathToFileURL(resolveRendererIndex()).toString()}?win=overlay#/`
-}
-
-function spawnPetOverlayWindow(bounds) {
-  const win = new BrowserWindow({
-    width: Math.max(80, Math.round(bounds?.width || 220)),
-    height: Math.max(80, Math.round(bounds?.height || 220)),
-    x: Number.isFinite(bounds?.x) ? Math.round(bounds.x) : undefined,
-    y: Number.isFinite(bounds?.y) ? Math.round(bounds.y) : undefined,
-    frame: false,
-    transparent: true,
-    resizable: false,
-    movable: true,
-    minimizable: false,
-    maximizable: false,
-    fullscreenable: false,
-    // Windows/Linux need this so the helper window does not get its own
-    // taskbar/alt-tab entry. On macOS, cmd-tab is app-level and this can make
-    // the whole app look like it vanished when the only newly-created visible
-    // window is a frameless overlay. Use NSPanel + Mission Control hiding below
-    // instead, leaving the main Hermes app as the Dock/cmd-tab anchor.
-    skipTaskbar: !IS_MAC,
-    hasShadow: false,
-    alwaysOnTop: true,
-    // macOS panels are non-activating helper windows and can float over full
-    // screen spaces without becoming the app's main switcher window.
-    type: IS_MAC ? 'panel' : undefined,
-    hiddenInMissionControl: IS_MAC,
-    // Non-activating: the overlay must never become the app's key/main window,
-    // or it (a frameless, taskbar-skipping panel) becomes the app's switcher
-    // anchor and the Hermes icon drops out of cmd/alt-tab — especially when the
-    // main window is minimized. We flip this on only while the composer needs
-    // the keyboard (see hermes:pet-overlay:set-focusable).
-    focusable: false,
-    show: false,
-    // Fully transparent — the renderer paints only the sprite + bubble.
-    backgroundColor: '#00000000',
-    webPreferences: {
-      preload: path.join(__dirname, 'preload.cjs'),
-      contextIsolation: true,
-      sandbox: true,
-      nodeIntegration: false,
-      devTools: true,
-      // Keep the sprite animating + bubble updating while the main window is
-      // minimized/blurred — the whole point of the overlay.
-      backgroundThrottling: false
-    }
-  })
-
-  // Float above other apps and follow the user across desktops so the pet is
-  // always reachable. `floating` + `type: panel` is the macOS NSPanel path; the
-  // more aggressive `screen-saver` level can interfere with normal app/window
-  // switching semantics.
-  win.setAlwaysOnTop(true, IS_MAC ? 'floating' : 'screen-saver')
-  win.setHiddenInMissionControl?.(true)
-  try {
-    // Electron docs: macOS may transform process type on each
-    // setVisibleOnAllWorkspaces() call unless skipTransformProcessType=true,
-    // which briefly hides the Dock/cmd-tab presence. Keep Hermes in the normal
-    // ForegroundApplication class so shift-clicking the pet never drops the app
-    // out of app switchers.
-    win.setVisibleOnAllWorkspaces(
-      true,
-      IS_MAC ? { visibleOnFullScreen: true, skipTransformProcessType: true } : undefined
-    )
-  } catch {
-    // Not supported everywhere — best effort.
-  }
-
-  wireCommonWindowHandlers(win)
-
-  win.once('ready-to-show', () => {
-    if (!win.isDestroyed()) win.showInactive()
-  })
-
-  win.on('closed', () => {
-    if (petOverlayWindow === win) {
-      petOverlayWindow = null
-    }
-
-    // If the overlay went away on its own (e.g. ⌘W), tell the main renderer to
-    // pop the pet back in so it doesn't stay hidden. Harmless echo when we're
-    // the ones who closed it (popInPet already cleared the active flag).
-    if (mainWindow && !mainWindow.isDestroyed()) {
-      mainWindow.webContents.send('hermes:pet-overlay:control', { type: 'pop-in' })
-    }
-  })
-
-  win.loadURL(petOverlayUrl())
-
-  return win
-}
-
-function openPetOverlay(bounds) {
-  if (petOverlayWindow && !petOverlayWindow.isDestroyed()) {
-    if (bounds) {
-      petOverlayWindow.setBounds({
-        x: Math.round(bounds.x),
-        y: Math.round(bounds.y),
-        width: Math.max(80, Math.round(bounds.width)),
-        height: Math.max(80, Math.round(bounds.height))
-      })
-    }
-
-    petOverlayWindow.showInactive()
-
-    return petOverlayWindow
-  }
-
-  petOverlayWindow = spawnPetOverlayWindow(bounds)
-
-  return petOverlayWindow
-}
-
-function closePetOverlay() {
-  if (petOverlayWindow && !petOverlayWindow.isDestroyed()) {
-    petOverlayWindow.close()
-  }
-
-  petOverlayWindow = null
-}
-
 function createWindow() {
   const icon = getAppIconPath()
   mainWindow = new BrowserWindow({
@@ -5316,23 +5179,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) {
@@ -5360,11 +5211,6 @@ function createWindow() {
   mainWindow.on('will-leave-full-screen', () => sendWindowStateChanged(false))
   mainWindow.on('leave-full-screen', () => sendWindowStateChanged(false))
 
-  // The overlay rides the main window — closing the app's primary window must
-  // tear it down too (otherwise it strands as an orphan that blocks
-  // window-all-closed from quitting on Windows/Linux).
-  mainWindow.on('closed', () => closePetOverlay())
-
   wireCommonWindowHandlers(mainWindow)
 
   mainWindow.webContents.on('render-process-gone', (_event, details) => {
@@ -5485,116 +5331,6 @@ ipcMain.handle('hermes:window:openNewSession', async () => {
 
   return { ok: true }
 })
-
-// --- Pet overlay (pop-out mascot) -----------------------------------------
-// `request` is `{ bounds, screen }`. A fresh pop-out passes viewport-space
-// bounds (screen=false): convert to screen space by adding the main window's
-// content origin so the pet lands where it sat in-window. A remembered/dragged
-// spot passes screen-space bounds (screen=true) and is used as-is. We return the
-// resolved screen bounds so the renderer can persist exactly where it opened.
-ipcMain.handle('hermes:pet-overlay:open', async (_event, request) => {
-  const bounds = request && request.bounds ? request.bounds : request
-  const isScreen = Boolean(request && request.screen)
-  let screenBounds = bounds
-
-  try {
-    if (bounds && !isScreen && mainWindow && !mainWindow.isDestroyed()) {
-      const content = mainWindow.getContentBounds()
-      screenBounds = {
-        x: content.x + (bounds.x || 0),
-        y: content.y + (bounds.y || 0),
-        width: bounds.width,
-        height: bounds.height
-      }
-    }
-  } catch {
-    // Fall back to raw bounds if the window geometry is unavailable.
-  }
-
-  openPetOverlay(screenBounds)
-
-  return { ok: true, bounds: screenBounds }
-})
-ipcMain.handle('hermes:pet-overlay:close', async () => {
-  closePetOverlay()
-
-  return { ok: true }
-})
-// Drag: the overlay reports a new absolute screen position (it already knows the
-// pointer's screen coords), we just move the window.
-ipcMain.on('hermes:pet-overlay:set-bounds', (_event, bounds) => {
-  if (!petOverlayWindow || petOverlayWindow.isDestroyed() || !bounds) {
-    return
-  }
-
-  petOverlayWindow.setBounds({
-    x: Math.round(bounds.x),
-    y: Math.round(bounds.y),
-    width: Math.max(80, Math.round(bounds.width)),
-    height: Math.max(80, Math.round(bounds.height))
-  })
-})
-// Click-through: the overlay window is a full rectangle but only the pet pixels
-// should be interactive. The renderer toggles this as the cursor enters/leaves
-// the sprite so transparent margins pass clicks to whatever is behind.
-ipcMain.on('hermes:pet-overlay:ignore-mouse', (_event, ignore) => {
-  if (petOverlayWindow && !petOverlayWindow.isDestroyed()) {
-    petOverlayWindow.setIgnoreMouseEvents(Boolean(ignore), { forward: true })
-  }
-})
-// The overlay is a non-activating panel (focusable:false) so it never steals
-// the app's cmd/alt-tab anchor from the main window. But the pop-up composer
-// needs the keyboard, so the renderer asks us to flip it focusable + focus it
-// while the composer is open, then back to non-activating when it closes.
-ipcMain.on('hermes:pet-overlay:set-focusable', (_event, focusable) => {
-  if (!petOverlayWindow || petOverlayWindow.isDestroyed()) {
-    return
-  }
-
-  petOverlayWindow.setFocusable(Boolean(focusable))
-  if (focusable) {
-    petOverlayWindow.focus()
-  }
-})
-// Main renderer → overlay: forward the latest pet state for the overlay to render.
-ipcMain.on('hermes:pet-overlay:state', (_event, payload) => {
-  if (petOverlayWindow && !petOverlayWindow.isDestroyed()) {
-    petOverlayWindow.webContents.send('hermes:pet-overlay:state', payload)
-  }
-})
-// Overlay → main renderer: control messages (pop back in, composer submit).
-ipcMain.on('hermes:pet-overlay:control', (_event, payload) => {
-  if (!mainWindow || mainWindow.isDestroyed()) {
-    return
-  }
-
-  // Double-click toggles the app window: hide it away if it's up front, bring it
-  // back if it's minimized/buried. Pure window control — nothing for the
-  // renderer to do, so don't forward it.
-  if (payload && payload.type === 'toggle-app') {
-    if (mainWindow.isMinimized() || !mainWindow.isVisible()) {
-      mainWindow.show()
-      mainWindow.focus()
-    } else {
-      mainWindow.minimize()
-    }
-
-    return
-  }
-
-  // The mail icon means "take me to the app": raise the main window (it may be
-  // minimized or buried) before the renderer navigates to the latest thread.
-  if (payload && payload.type === 'open-app') {
-    if (mainWindow.isMinimized()) {
-      mainWindow.restore()
-    }
-
-    mainWindow.show()
-    mainWindow.focus()
-  }
-
-  mainWindow.webContents.send('hermes:pet-overlay:control', payload)
-})
 ipcMain.handle('hermes:bootstrap:reset', async () => {
   // Renderer's "Reload and retry" path. Clear the latched failure and
   // reset connection state so the next startHermes() call restarts the
@@ -6799,10 +6535,6 @@ function configureSpellChecker() {
 }
 
 app.on('before-quit', () => {
-  // The always-on-top overlay isn't a "real" app window; close it so a stray
-  // pet can't keep the process alive or float over a quit app.
-  closePetOverlay()
-
   // Quitting mid-install should stop the installer, not orphan it.
   if (bootstrapAbortController) {
     try {
@@ -6819,6 +6551,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

@@ -7,32 +7,6 @@ contextBridge.exposeInMainWorld('hermesDesktop', {
   getGatewayWsUrl: profile => ipcRenderer.invoke('hermes:gateway:ws-url', profile),
   openSessionWindow: (sessionId, opts) => ipcRenderer.invoke('hermes:window:openSession', sessionId, opts),
   openNewSessionWindow: () => ipcRenderer.invoke('hermes:window:openNewSession'),
-  petOverlay: {
-    // Main renderer → main process: window lifecycle + drag. `request` is
-    // `{ bounds, screen }`; resolves with the screen bounds it actually used.
-    open: request => ipcRenderer.invoke('hermes:pet-overlay:open', request),
-    close: () => ipcRenderer.invoke('hermes:pet-overlay:close'),
-    setBounds: bounds => ipcRenderer.send('hermes:pet-overlay:set-bounds', bounds),
-    setIgnoreMouse: ignore => ipcRenderer.send('hermes:pet-overlay:ignore-mouse', ignore),
-    // Flip the overlay focusable (and focus it) while the composer needs keys.
-    setFocusable: focusable => ipcRenderer.send('hermes:pet-overlay:set-focusable', focusable),
-    // Main renderer → overlay (forwarded by main): push the latest pet state.
-    pushState: payload => ipcRenderer.send('hermes:pet-overlay:state', payload),
-    // Overlay → main renderer (forwarded by main): pop back in / composer submit.
-    control: payload => ipcRenderer.send('hermes:pet-overlay:control', payload),
-    // Overlay subscribes to state pushes.
-    onState: callback => {
-      const listener = (_event, payload) => callback(payload)
-      ipcRenderer.on('hermes:pet-overlay:state', listener)
-      return () => ipcRenderer.removeListener('hermes:pet-overlay:state', listener)
-    },
-    // Main renderer subscribes to overlay control messages.
-    onControl: callback => {
-      const listener = (_event, payload) => callback(payload)
-      ipcRenderer.on('hermes:pet-overlay:control', listener)
-      return () => ipcRenderer.removeListener('hermes:pet-overlay:control', listener)
-    }
-  },
   getBootProgress: () => ipcRenderer.invoke('hermes:boot-progress:get'),
   getConnectionConfig: profile => ipcRenderer.invoke('hermes:connection-config:get', profile),
   saveConnectionConfig: payload => ipcRenderer.invoke('hermes:connection-config:save', payload),

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",
@@ -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/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,6 +40,7 @@ import {
   $lastVisibleMessageIsUser,
   $messages,
   $messagesEmpty,
+  $resumeExhaustedSessionId,
   $selectedStoredSessionId,
   $sessions,
   sessionPinId
@@ -86,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 {
@@ -272,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)
@@ -296,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)
 
@@ -315,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>({
@@ -432,6 +453,7 @@ export function ChatView({
             loading={threadLoading}
             onBranchInNewChat={onBranchInNewChat}
             onCancel={onCancel}
+            onDismissError={onDismissError}
             onRestoreToMessage={onRestoreToMessage}
             sessionId={activeSessionId}
             sessionKey={threadKey}
@@ -465,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/command-palette/index.tsx

@@ -5,7 +5,6 @@ import { useCallback, useEffect, useMemo, useState } from 'react'
 import { useNavigate } from 'react-router-dom'
 
 import { HUD_HEADING, HUD_ITEM, HUD_POSITION, HUD_SURFACE, HUD_TEXT } from '@/app/floating-hud'
-import { useGatewayRequest } from '@/app/gateway/hooks/use-gateway-request'
 import { setTerminalTakeover } from '@/app/right-sidebar/store'
 import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList } from '@/components/ui/command'
 import { KbdCombo } from '@/components/ui/kbd'
@@ -21,7 +20,6 @@ import {
   Clock,
   Cpu,
   Download,
-  Egg,
   Globe,
   type IconComponent,
   Info,
@@ -31,7 +29,6 @@ import {
   Moon,
   Package,
   Palette,
-  PawPrint,
   Plus,
   Settings,
   Settings2,
@@ -42,9 +39,8 @@ import {
   Zap
 } from '@/lib/icons'
 import { cn } from '@/lib/utils'
-import { $commandPaletteOpen, $commandPalettePage, closeCommandPalette, setCommandPaletteOpen } from '@/store/command-palette'
+import { $commandPaletteOpen, closeCommandPalette, setCommandPaletteOpen } from '@/store/command-palette'
 import { $bindings } from '@/store/keybinds'
-import { $petGenStatus, cleanupPetGen, generateDrafts } from '@/store/pet-generate'
 import { luminance } from '@/themes/color'
 import { type ThemeMode, useTheme } from '@/themes/context'
 import { isUserTheme, resolveTheme } from '@/themes/user-themes'
@@ -66,8 +62,6 @@ import { fieldCopyForSchemaKey } from '../settings/field-copy'
 import { prettyName } from '../settings/helpers'
 
 import { MarketplaceThemePage } from './marketplace-theme-page'
-import { PetGeneratePage } from './pet-generate-page'
-import { PetInlineToggle, PetPalettePage } from './pet-palette-page'
 
 interface PaletteItem {
   /** Keybind action id — its live combo renders as a hotkey hint. */
@@ -93,7 +87,7 @@ interface PaletteGroup {
 
 // Nested page → its parent, so Back / Esc step up one level instead of closing
 // the palette. Pages absent here go straight back to the root list.
-const PAGE_PARENTS: Record<string, string> = { 'generate-pet': 'pets', 'install-theme': 'theme' }
+const PAGE_PARENTS: Record<string, string> = { 'install-theme': 'theme' }
 
 /** A nested page reachable from a root item via `to`. */
 interface PalettePage {
@@ -211,10 +205,8 @@ function themeSupportsMode(name: string, target: 'light' | 'dark'): boolean {
 export function CommandPalette() {
   const { t } = useI18n()
   const open = useStore($commandPaletteOpen)
-  const pendingPage = useStore($commandPalettePage)
   const bindings = useStore($bindings)
   const navigate = useNavigate()
-  const { requestGateway } = useGatewayRequest()
   const { availableThemes, resolvedMode, setMode, setTheme, themeName } = useTheme()
   const [search, setSearch] = useState('')
   const [page, setPage] = useState<string | null>(null)
@@ -250,23 +242,13 @@ export function CommandPalette() {
   const sessions = useMemo(() => (sessionsQuery.data?.sessions ?? []).map(toSessionEntry), [sessionsQuery.data])
   const archivedSessions = useMemo(() => (archivedQuery.data?.sessions ?? []).map(toSessionEntry), [archivedQuery.data])
 
-  // Reset the query/sub-page on close so it reopens clean. Cleanup also deletes
-  // a hatched-but-unadopted preview pet so it doesn't linger in the gallery.
+  // Reset the query/sub-page on close so it reopens clean.
   useEffect(() => {
     if (!open) {
       setSearch('')
       setPage(null)
-      cleanupPetGen(requestGateway)
     }
-  }, [open, requestGateway])
-
-  // Deep-link into a nested page (e.g. `/pet list` → pets picker).
-  useEffect(() => {
-    if (open && pendingPage) {
-      setPage(pendingPage)
-      $commandPalettePage.set(null)
-    }
-  }, [open, pendingPage])
+  }, [open])
 
   const go = useCallback((path: string) => () => navigate(path), [navigate])
 
@@ -400,20 +382,6 @@ export function CommandPalette() {
             keywords: ['appearance', 'color mode', 'brightness', 'dark', 'light', 'system'],
             label: cc.changeColorMode,
             to: 'color-mode'
-          },
-          {
-            icon: PawPrint,
-            id: 'appearance-pets',
-            keywords: ['pet', 'petdex', 'mascot', 'pets', '/pet', 'paw'],
-            label: cc.pets.title,
-            to: 'pets'
-          },
-          {
-            icon: Egg,
-            id: 'appearance-generate-pet',
-            keywords: ['pet', 'generate', 'create', 'make', 'new pet', 'mascot', 'hatch', 'ai'],
-            label: cc.generatePet.title,
-            to: 'generate-pet'
           }
         ]
       },
@@ -582,18 +550,6 @@ export function CommandPalette() {
           }
         ]
       },
-      // Server-driven page: browse petdex gallery, adopt/switch, toggle off.
-      pets: {
-        title: t.commandCenter.pets.title,
-        placeholder: t.commandCenter.pets.placeholder,
-        groups: []
-      },
-      // Server-driven page: describe → draft variants → hatch a custom pet.
-      'generate-pet': {
-        title: t.commandCenter.generatePet.title,
-        placeholder: t.commandCenter.generatePet.placeholder,
-        groups: []
-      },
       // Server-driven page: items come from the Marketplace, rendered by
       // <MarketplaceThemePage> (loader + live search + per-row install).
       'install-theme': {
@@ -664,77 +620,49 @@ export function CommandPalette() {
                   event.preventDefault()
                   event.stopPropagation()
                   goBack()
-
-                  return
-                }
-
-                // On the generate page, Enter (re)generates from the typed
-                // concept — cmdk has no item to select there, so each Enter,
-                // including a retype after drafts already exist, starts a fresh
-                // round. The page's own Retry/Hatch buttons cover the rest.
-                if (page === 'generate-pet' && event.key === 'Enter' && search.trim()) {
-                  const genStatus = $petGenStatus.get()
-
-                  if (
-                    genStatus !== 'generating' &&
-                    genStatus !== 'hatching' &&
-                    genStatus !== 'preview' &&
-                    genStatus !== 'adopting'
-                  ) {
-                    event.preventDefault()
-                    void generateDrafts(requestGateway, { prompt: search })
-                  }
                 }
               }}
               onValueChange={setSearch}
               placeholder={placeholder}
-              right={page === 'pets' ? <PetInlineToggle /> : undefined}
               value={search}
             />
             <CommandList className="dt-portal-scrollbar max-h-[min(20rem,56vh)]">
-              {/* Server-driven pages render their own list; the rest show groups. */}
-              {page === 'generate-pet' ? (
-                <PetGeneratePage search={search} />
-              ) : page === 'pets' ? (
-                <PetPalettePage onGenerate={() => { setSearch(''); setPage('generate-pet') }} search={search} />
-              ) : page === 'install-theme' ? (
+              {page === 'install-theme' ? (
                 <MarketplaceThemePage onPickTheme={setTheme} search={search} />
               ) : (
-                <>
-                  <CommandEmpty>{t.commandCenter.noResults}</CommandEmpty>
-                  {visibleGroups.map((group, index) => (
-                    <CommandGroup
-                      className={HUD_HEADING}
-                      heading={group.heading}
-                      key={group.heading ?? `palette-group-${index}`}
-                    >
-                      {group.items.map(item => {
-                        const Icon = item.icon
-                        const combo = item.action ? bindings[item.action]?.[0] : undefined
-
-                        return (
-                          <CommandItem
-                            className={cn(HUD_ITEM, HUD_TEXT)}
-                            key={item.id}
-                            keywords={item.keywords}
-                            onSelect={() => handleSelect(item)}
-                            value={`${item.label} ${item.keywords?.join(' ') ?? ''} ${item.id}`}
-                          >
-                            <Icon className="size-3.5 shrink-0 text-muted-foreground" />
-                            <span className="truncate">{item.label}</span>
-                            {combo && <KbdCombo className="ml-auto opacity-55" combo={combo} size="sm" />}
-                            {item.to && (
-                              <ChevronRight
-                                className={cn('size-3.5 shrink-0 text-muted-foreground/70', !combo && 'ml-auto')}
-                              />
-                            )}
-                          </CommandItem>
-                        )
-                      })}
-                    </CommandGroup>
-                  ))}
-                </>
+                <CommandEmpty>{t.commandCenter.noResults}</CommandEmpty>
               )}
+              {visibleGroups.map((group, index) => (
+                <CommandGroup
+                  className={HUD_HEADING}
+                  heading={group.heading}
+                  key={group.heading ?? `palette-group-${index}`}
+                >
+                  {group.items.map(item => {
+                    const Icon = item.icon
+                    const combo = item.action ? bindings[item.action]?.[0] : undefined
+
+                    return (
+                      <CommandItem
+                        className={cn(HUD_ITEM, HUD_TEXT)}
+                        key={item.id}
+                        keywords={item.keywords}
+                        onSelect={() => handleSelect(item)}
+                        value={`${item.label} ${item.keywords?.join(' ') ?? ''} ${item.id}`}
+                      >
+                        <Icon className="size-3.5 shrink-0 text-muted-foreground" />
+                        <span className="truncate">{item.label}</span>
+                        {combo && <KbdCombo className="ml-auto opacity-55" combo={combo} size="sm" />}
+                        {item.to && (
+                          <ChevronRight
+                            className={cn('size-3.5 shrink-0 text-muted-foreground/70', !combo && 'ml-auto')}
+                          />
+                        )}
+                      </CommandItem>
+                    )
+                  })}
+                </CommandGroup>
+              ))}
             </CommandList>
           </Command>
         </DialogPrimitive.Content>

apps/desktop/src/app/command-palette/pet-generate-page.tsx

@@ -1,303 +0,0 @@
-/**
- * Cmd-K → Pets → "Generate" page — describe a pet, pick a draft, hatch it.
- *
- * A thin view over the `pet-generate` store. The palette search box doubles as
- * the concept prompt; this page renders the variant grid, the selection, the
- * retry/hatch actions, and the loading states. The store owns the two-step
- * `pet.generate` → `pet.hatch` flow.
- */
-
-import { useStore } from '@nanostores/react'
-import { useEffect, useState } from 'react'
-
-import { useGatewayRequest } from '@/app/gateway/hooks/use-gateway-request'
-import { PetSprite } from '@/components/pet/pet-sprite'
-import { useI18n } from '@/i18n'
-import { triggerHaptic } from '@/lib/haptics'
-import { Check, Egg, Loader2, PawPrint, RefreshCw } from '@/lib/icons'
-import { cn } from '@/lib/utils'
-import { closeCommandPalette } from '@/store/command-palette'
-import { type PetInfo } from '@/store/pet'
-import {
-  $petGenDrafts,
-  $petGenError,
-  $petGenPreview,
-  $petGenSelected,
-  $petGenStatus,
-  adoptHatched,
-  discardHatched,
-  generateDrafts,
-  hatchSelected
-} from '@/store/pet-generate'
-
-const VARIANT_COUNT = 4
-
-// Fixed render scale for the preview so it's a predictable size regardless of
-// the user's configured `display.pet.scale`.
-const PREVIEW_SCALE = 0.7
-
-// Fallback row order if a backend doesn't return `stateRows`.
-const PREVIEW_ROWS = ['idle', 'waving', 'running-right', 'running-left', 'running', 'review', 'jumping', 'failed']
-const PREVIEW_STATE_MS = 1500
-
-const ROW_TO_FRAME_KEY: Record<string, string> = {
-  idle: 'idle',
-  wave: 'wave',
-  waving: 'wave',
-  jump: 'jump',
-  jumping: 'jump',
-  run: 'run',
-  running: 'run',
-  'running-right': 'run',
-  'running-left': 'run',
-  failed: 'failed',
-  review: 'review',
-  waiting: 'waiting'
-}
-
-function frameCountForRow(pet: PetInfo, row: string): number {
-  const byState = pet.framesByState
-  const mapped = ROW_TO_FRAME_KEY[row]
-  return byState?.[row] ?? (mapped ? byState?.[mapped] : undefined) ?? pet.framesPerState ?? 0
-}
-
-interface PetGeneratePageProps {
-  search: string
-}
-
-export function PetGeneratePage({ search }: PetGeneratePageProps) {
-  const { t } = useI18n()
-  const copy = t.commandCenter.generatePet
-  const { requestGateway } = useGatewayRequest()
-
-  const status = useStore($petGenStatus)
-  const error = useStore($petGenError)
-  const drafts = useStore($petGenDrafts)
-  const selected = useStore($petGenSelected)
-  const preview = useStore($petGenPreview)
-  const [name, setName] = useState('')
-
-  const prompt = search.trim()
-  const busy = status === 'generating' || status === 'hatching'
-
-  const generate = () => {
-    if (prompt) {
-      void generateDrafts(requestGateway, { prompt })
-    }
-  }
-
-  const hatch = () => {
-    void hatchSelected(requestGateway, { name: name.trim() || prompt, prompt })
-  }
-
-  const adopt = () => {
-    void adoptHatched(requestGateway).then(out => {
-      if (out.ok) {
-        triggerHaptic('crisp')
-        closeCommandPalette()
-      }
-    })
-  }
-
-  if (status === 'stale') {
-    return <Status text={copy.staleBackend} tone="error" />
-  }
-
-  // Hatching is slow (several grounded image generations) — own the whole pane.
-  if (status === 'hatching') {
-    return <Status icon={<Loader2 className="size-4 animate-spin" />} text={copy.hatching} />
-  }
-
-  // Preview: play every animation row before the user commits.
-  if ((status === 'preview' || status === 'adopting') && preview) {
-    return (
-      <HatchPreview
-        adopting={status === 'adopting'}
-        error={error}
-        onAdopt={adopt}
-        onDiscard={() => void discardHatched(requestGateway)}
-        pet={preview}
-      />
-    )
-  }
-
-  const hasDrafts = drafts.length > 0
-  const generating = status === 'generating'
-  const cells = generating ? Array.from({ length: VARIANT_COUNT }, (_, i) => ({ index: i, dataUri: '' })) : drafts
-
-  return (
-    <div className="flex flex-col gap-2 p-2">
-      {error && <p className="px-1 text-[0.6875rem] text-(--ui-red)">{error}</p>}
-
-      {!hasDrafts && !generating && (
-        <p className="px-1 py-1 text-xs text-muted-foreground">{prompt ? copy.readyHint : copy.promptHint}</p>
-      )}
-
-      {(hasDrafts || generating) && (
-        <div className="grid grid-cols-2 gap-2">
-          {cells.map((draft, i) => {
-            const isSelected = !generating && selected === draft.index
-
-            return (
-              <button
-                className={cn(
-                  'relative flex aspect-square items-center justify-center overflow-hidden rounded-lg border bg-(--ui-bg-quinary) transition-colors',
-                  isSelected
-                    ? 'border-(--ui-accent) ring-2 ring-(--ui-accent)/40'
-                    : 'border-(--ui-stroke-tertiary) hover:border-foreground/40'
-                )}
-                disabled={generating || busy}
-                key={generating ? i : draft.index}
-                onClick={() => $petGenSelected.set(draft.index)}
-                onMouseDown={event => event.preventDefault()}
-                type="button"
-              >
-                {generating ? (
-                  <Loader2 className="size-5 animate-spin text-muted-foreground" />
-                ) : (
-                  <img alt="" className="size-full object-contain" draggable={false} src={draft.dataUri} />
-                )}
-                {isSelected && (
-                  <span className="absolute right-1 top-1 rounded-full bg-(--ui-accent) p-0.5 text-(--ui-base)">
-                    <Check className="size-3" />
-                  </span>
-                )}
-              </button>
-            )
-          })}
-        </div>
-      )}
-
-      {hasDrafts ? (
-        <div className="flex flex-col gap-2">
-          <input
-            className="w-full rounded-md border border-(--ui-stroke-tertiary) bg-transparent px-2 py-1.5 text-xs outline-none placeholder:text-muted-foreground focus:border-foreground/40"
-            onChange={event => setName(event.target.value)}
-            onKeyDown={event => {
-              if (event.key === 'Enter') {
-                event.preventDefault()
-                hatch()
-              }
-            }}
-            placeholder={copy.namePlaceholder}
-            value={name}
-          />
-          <div className="flex gap-2">
-            <button
-              className="flex flex-1 items-center justify-center gap-1.5 rounded-md border border-border px-2 py-1.5 text-xs font-medium transition-colors hover:bg-(--chrome-action-hover) disabled:opacity-50"
-              disabled={busy || !prompt}
-              onClick={generate}
-              onMouseDown={event => event.preventDefault()}
-              type="button"
-            >
-              <RefreshCw className="size-3.5" />
-              {copy.retry}
-            </button>
-            <button
-              className="flex flex-1 items-center justify-center gap-1.5 rounded-md bg-primary px-2 py-1.5 text-xs font-medium text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
-              disabled={busy || selected === null}
-              onClick={hatch}
-              onMouseDown={event => event.preventDefault()}
-              type="button"
-            >
-              <PawPrint className="size-3.5" />
-              {copy.hatch}
-            </button>
-          </div>
-        </div>
-      ) : (
-        <button
-          className="flex items-center justify-center gap-1.5 rounded-md bg-primary px-2 py-2 text-xs font-medium text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
-          disabled={busy || !prompt}
-          onClick={generate}
-          onMouseDown={event => event.preventDefault()}
-          type="button"
-        >
-          {generating ? <Loader2 className="size-3.5 animate-spin" /> : <Egg className="size-3.5" />}
-          {generating ? copy.generating : copy.generate}
-        </button>
-      )}
-    </div>
-  )
-}
-
-interface HatchPreviewProps {
-  pet: PetInfo
-  adopting: boolean
-  error: string | null
-  onAdopt: () => void
-  onDiscard: () => void
-}
-
-function HatchPreview({ pet, adopting, error, onAdopt, onDiscard }: HatchPreviewProps) {
-  const { t } = useI18n()
-  const copy = t.commandCenter.generatePet
-  const [stateIndex, setStateIndex] = useState(0)
-  const previewRows = (pet.stateRows?.length ? pet.stateRows : PREVIEW_ROWS).filter(row => frameCountForRow(pet, row) > 0)
-  const rows = previewRows.length > 0 ? previewRows : ['idle']
-  const activeRow = rows[stateIndex % rows.length] ?? 'idle'
-
-  // Cycle through the animation rows so the preview showcases all frames.
-  useEffect(() => {
-    const id = setInterval(() => {
-      setStateIndex(i => (i + 1) % rows.length)
-    }, PREVIEW_STATE_MS)
-
-    return () => clearInterval(id)
-  }, [rows.length])
-
-  useEffect(() => {
-    setStateIndex(0)
-  }, [pet.slug])
-
-  const previewInfo: PetInfo = { ...pet, scale: PREVIEW_SCALE }
-
-  return (
-    <div className="flex flex-col items-center gap-2 p-2">
-      <div className="flex min-h-[9rem] w-full items-center justify-center rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) py-2">
-        <PetSprite info={previewInfo} rowOverride={activeRow} />
-      </div>
-
-      {pet.displayName && <p className="text-xs font-medium text-foreground">{pet.displayName}</p>}
-
-      {error && <p className="px-1 text-[0.6875rem] text-(--ui-red)">{error}</p>}
-
-      <div className="flex w-full gap-2">
-        <button
-          className="flex flex-1 items-center justify-center gap-1.5 rounded-md border border-border px-2 py-1.5 text-xs font-medium transition-colors hover:bg-(--chrome-action-hover) disabled:opacity-50"
-          disabled={adopting}
-          onClick={onDiscard}
-          onMouseDown={event => event.preventDefault()}
-          type="button"
-        >
-          <RefreshCw className="size-3.5" />
-          {copy.startOver}
-        </button>
-        <button
-          className="flex flex-1 items-center justify-center gap-1.5 rounded-md bg-primary px-2 py-1.5 text-xs font-medium text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
-          disabled={adopting}
-          onClick={onAdopt}
-          onMouseDown={event => event.preventDefault()}
-          type="button"
-        >
-          {adopting ? <Loader2 className="size-3.5 animate-spin" /> : <PawPrint className="size-3.5" />}
-          {copy.adopt}
-        </button>
-      </div>
-    </div>
-  )
-}
-
-function Status({ icon, text, tone }: { icon?: React.ReactNode; text: string; tone?: 'error' }) {
-  return (
-    <div
-      className={cn(
-        'flex items-center justify-center gap-2 px-2 py-6 text-xs',
-        tone === 'error' ? 'text-(--ui-red)' : 'text-muted-foreground'
-      )}
-    >
-      {icon}
-      {text}
-    </div>
-  )
-}

apps/desktop/src/app/command-palette/pet-palette-page.tsx

@@ -1,205 +0,0 @@
-/**
- * Cmd-K "Pets…" page — browse the petdex gallery, adopt/switch, toggle off.
- *
- * A thin view over the `pet-gallery` store: it subscribes to the shared atoms
- * and calls the store's actions. The store owns fetching, caching, the thumb
- * cache, and optimistic mutations, so reopening this page is instant and a
- * toggle never re-pulls the network gallery.
- */
-
-import { useStore } from '@nanostores/react'
-import { useEffect, useMemo } from 'react'
-
-import { HUD_ITEM, HUD_TEXT } from '@/app/floating-hud'
-import { useGatewayRequest } from '@/app/gateway/hooks/use-gateway-request'
-import { PetThumb } from '@/components/pet/pet-thumb'
-import { useI18n } from '@/i18n'
-import { triggerHaptic } from '@/lib/haptics'
-import { Check, Egg, Loader2, PawPrint } from '@/lib/icons'
-import { cn } from '@/lib/utils'
-import {
-  $petBusy,
-  $petGallery,
-  $petGalleryError,
-  $petGalleryStatus,
-  adoptPet,
-  loadPetGallery,
-  loadPetThumb,
-  rankedGalleryPets,
-  setPetEnabled
-} from '@/store/pet-gallery'
-
-interface PetPalettePageProps {
-  search: string
-  /** Navigate to the "generate a pet" page (rendered as a header action). */
-  onGenerate?: () => void
-}
-
-export function PetPalettePage({ search, onGenerate }: PetPalettePageProps) {
-  const { t } = useI18n()
-  const copy = t.commandCenter.pets
-  const { requestGateway } = useGatewayRequest()
-
-  const gallery = useStore($petGallery)
-  const status = useStore($petGalleryStatus)
-  const error = useStore($petGalleryError)
-  const busy = useStore($petBusy)
-
-  useEffect(() => {
-    void loadPetGallery(requestGateway)
-  }, [requestGateway])
-
-  const enabled = gallery?.enabled ?? false
-  const active = gallery?.active ?? ''
-
-  const shown = useMemo(() => rankedGalleryPets(gallery, search).slice(0, 50), [gallery, search])
-
-  const adopt = (slug: string) => {
-    void adoptPet(requestGateway, slug, copy.adoptFailed).then(ok => ok && triggerHaptic('crisp'))
-  }
-
-  if (status === 'loading' && !gallery) {
-    return <Status icon={<Loader2 className="size-3.5 animate-spin" />} text={copy.loading} />
-  }
-
-  if (status === 'stale') {
-    return <Status text={copy.staleBackend} tone="error" />
-  }
-
-  if (!gallery?.pets.length && error) {
-    return <Status text={error} tone="error" />
-  }
-
-  const mutating = Boolean(busy)
-
-  return (
-    <div role="listbox">
-      {onGenerate && (
-        <button
-          className={cn(
-            'flex w-full items-center gap-2 rounded-md text-left text-foreground transition-colors hover:bg-(--chrome-action-hover)',
-            HUD_ITEM,
-            HUD_TEXT
-          )}
-          onClick={onGenerate}
-          onMouseDown={event => event.preventDefault()}
-          type="button"
-        >
-          <span className="flex size-8 shrink-0 items-center justify-center rounded-md bg-(--chrome-action-hover)">
-            <Egg className="size-4" />
-          </span>
-          <span className="font-medium">{t.commandCenter.generatePet.title}</span>
-        </button>
-      )}
-
-      {error && <p className="px-2 pb-1 pt-1.5 text-[0.6875rem] text-(--ui-red)">{error}</p>}
-
-      {shown.length === 0 ? (
-        <Status text={copy.empty} />
-      ) : (
-        shown.map(pet => {
-          const isActive = enabled && pet.slug === active
-          const isBusy = busy === pet.slug
-
-          return (
-            <button
-              className={cn(
-                'flex w-full items-center gap-2 rounded-md text-left transition-colors hover:bg-(--chrome-action-hover) disabled:opacity-60',
-                HUD_ITEM,
-                HUD_TEXT,
-                isActive && 'bg-(--chrome-action-hover)/70'
-              )}
-              disabled={mutating && !isBusy}
-              key={pet.slug}
-              onClick={() => adopt(pet.slug)}
-              onMouseDown={event => event.preventDefault()}
-              role="option"
-              type="button"
-            >
-              <PetThumb
-                alt={pet.displayName}
-                load={(slug, url) => loadPetThumb(requestGateway, slug, url)}
-                size={32}
-                slug={pet.slug}
-                url={pet.spritesheetUrl}
-              />
-              <span className="flex min-w-0 flex-col">
-                <span className="truncate font-medium">{pet.displayName}</span>
-                <span className="truncate text-[0.6875rem] text-muted-foreground/80">
-                  {pet.slug}
-                  {pet.installed ? ` · ${copy.installed}` : ''}
-                </span>
-              </span>
-              <span className="ml-auto flex shrink-0 items-center text-[0.6875rem] text-muted-foreground">
-                {isBusy ? (
-                  <Loader2 className="size-3 animate-spin" />
-                ) : isActive ? (
-                  <Check className="size-3.5 text-foreground" />
-                ) : null}
-              </span>
-            </button>
-          )
-        })
-      )}
-    </div>
-  )
-}
-
-/**
- * Single on/off toggle, rendered inline on the palette's search row (see
- * `CommandInput`'s `right` slot). The paw lights up when pets are on. Reads the
- * same shared gallery atoms, so it stays in sync with the list below.
- */
-export function PetInlineToggle() {
-  const { t } = useI18n()
-  const copy = t.commandCenter.pets
-  const { requestGateway } = useGatewayRequest()
-  const gallery = useStore($petGallery)
-  const busy = useStore($petBusy)
-
-  if (!gallery) {
-    return null
-  }
-
-  const enabled = gallery.enabled
-
-  const toggle = () => {
-    void setPetEnabled(requestGateway, !enabled, {
-      noneAvailable: copy.noneAvailable,
-      fallback: copy.toggleFailed
-    }).then(ok => ok && triggerHaptic('crisp'))
-  }
-
-  return (
-    <button
-      aria-label={enabled ? copy.turnOff : copy.turnOn}
-      aria-pressed={enabled}
-      className={cn(
-        'flex shrink-0 items-center justify-center rounded-md p-1.5 transition-colors disabled:opacity-50',
-        enabled ? 'bg-(--chrome-action-hover) text-foreground' : 'text-muted-foreground hover:bg-(--chrome-action-hover)/60'
-      )}
-      disabled={Boolean(busy)}
-      onClick={toggle}
-      // Don't steal focus from the search input on click.
-      onMouseDown={event => event.preventDefault()}
-      title={enabled ? copy.turnOff : copy.turnOn}
-      type="button"
-    >
-      {busy ? <Loader2 className="size-4 animate-spin" /> : <PawPrint className="size-4" />}
-    </button>
-  )
-}
-
-function Status({ icon, text, tone }: { icon?: React.ReactNode; text: string; tone?: 'error' }) {
-  return (
-    <div
-      className={cn(
-        'flex items-center justify-center gap-2 px-2 py-6 text-xs',
-        tone === 'error' ? 'text-(--ui-red)' : 'text-muted-foreground'
-      )}
-    >
-      {icon}
-      {text}
-    </div>
-  )
-}

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,
@@ -38,8 +38,6 @@ import {
   unpinSession
 } from '../store/layout'
 import { respondToApprovalAction } from '../store/native-notifications'
-import { setPetActivity } from '../store/pet'
-import { setPetOverlayOpenAppHandler, setPetOverlaySubmitHandler } from '../store/pet-overlay'
 import { $filePreviewTarget, $previewTarget, closeActiveRightRailTab } from '../store/preview'
 import {
   $activeGatewayProfile,
@@ -51,11 +49,13 @@ import {
 } from '../store/profile'
 import {
   $activeSessionId,
-  $attentionSessionIds,
   $currentCwd,
   $freshDraftReady,
   $gatewayState,
+  $messages,
   $messagingSessions,
+  $resumeFailedSessionId,
+  $resumeExhaustedSessionId,
   $selectedStoredSessionId,
   $sessions,
   $workingSessionIds,
@@ -202,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)
@@ -739,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()
@@ -789,53 +834,6 @@ export function DesktopController() {
     updateSessionState
   })
 
-  // The popped-out pet drives two actions back into the app: send a prompt, and
-  // open the most recent thread. Both are registered ONCE through refs that track
-  // the latest callbacks — re-registering on every `submitText`/`resumeSession`
-  // identity change left a brief window where the handler was nulled (cleanup
-  // before re-register), which could drop a submit fired from the overlay (e.g.
-  // creating a session from the new-session screen). The ref form keeps a stable,
-  // always-current handler. Primary window only — it owns the overlay.
-  const submitTextRef = useRef(submitText)
-  submitTextRef.current = submitText
-  const resumeSessionRef = useRef(resumeSession)
-  resumeSessionRef.current = resumeSession
-
-  useEffect(() => {
-    if (isSecondaryWindow()) {
-      return
-    }
-
-    setPetOverlaySubmitHandler(text => void submitTextRef.current(text))
-    // Mail icon: $sessions is ordered most-recent-first; the pet is global (not
-    // per session) so "most recent" is the right target. main.cjs already raised
-    // the window before forwarding this.
-    setPetOverlayOpenAppHandler(() => {
-      const recent = $sessions.get()[0]
-
-      if (recent?.id) {
-        void resumeSessionRef.current(recent.id)
-      }
-    })
-
-    return () => {
-      setPetOverlaySubmitHandler(null)
-      setPetOverlayOpenAppHandler(null)
-    }
-  }, [])
-
-  // Mirror "a session is blocked on the user" (clarify/approval) into the pet's
-  // awaitingInput flag so it shows the `waiting` pose. Lives on $petActivity so
-  // it rides the same atom the pop-out overlay mirrors — no session list needed
-  // there. Every window keeps its own in-window pet in sync.
-  useEffect(() => {
-    const sync = () => setPetActivity({ awaitingInput: $attentionSessionIds.get().length > 0 })
-
-    sync()
-
-    return $attentionSessionIds.listen(sync)
-  }, [])
-
   useGatewayBoot({
     handleGatewayEvent: handleDesktopGatewayEvent,
     onConnectionReady: c => {
@@ -895,6 +893,8 @@ export function DesktopController() {
     gatewayState,
     locationPathname: location.pathname,
     resumeSession,
+    resumeFailedSessionId,
+    resumeExhaustedSessionId,
     routedSessionId,
     runtimeIdByStoredSessionIdRef,
     selectedStoredSessionId,
@@ -1044,6 +1044,7 @@ export function DesktopController() {
           void removeSession(selectedStoredSessionId)
         }
       }}
+      onDismissError={dismissError}
       onEdit={editMessage}
       onPasteClipboardImage={() => void composer.pasteClipboardImage()}
       onPickFiles={() => void composer.pickContextPaths('file')}
@@ -1052,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/pet-overlay/overlay-root.tsx

@@ -1,38 +0,0 @@
-import { StrictMode } from 'react'
-import { createRoot } from 'react-dom/client'
-
-import { ErrorBoundary } from '@/components/error-boundary'
-import { ThemeProvider } from '@/themes/context'
-
-import { PetOverlayApp } from './pet-overlay-app'
-
-/**
- * Boot the pet-overlay window. Loaded by the same bundle as the main app but
- * via `?win=overlay`, so it shares CSS/atoms while mounting a minimal, transparent
- * surface (no app shell, no gateway, no I18n — the bubble strings are inline).
- *
- * The index.html boot script paints an OPAQUE themed background to avoid a flash
- * in normal windows; the overlay must be see-through, so we force every host
- * layer transparent with a late, high-specificity style tag.
- */
-export function mountPetOverlay(): void {
-  const style = document.createElement('style')
-  style.textContent = 'html,body,#root{background:transparent !important;}'
-  document.head.appendChild(style)
-
-  const root = document.getElementById('root')
-
-  if (!root) {
-    return
-  }
-
-  createRoot(root).render(
-    <StrictMode>
-      <ErrorBoundary label="pet-overlay">
-        <ThemeProvider>
-          <PetOverlayApp />
-        </ThemeProvider>
-      </ErrorBoundary>
-    </StrictMode>
-  )
-}

apps/desktop/src/app/pet-overlay/pet-overlay-app.tsx

@@ -1,345 +0,0 @@
-import { useStore } from '@nanostores/react'
-import { useEffect, useRef, useState } from 'react'
-
-import { PetBubble } from '@/components/pet/pet-bubble'
-import { PetSprite } from '@/components/pet/pet-sprite'
-import { Mail } from '@/lib/icons'
-import { $petActivity, $petInfo, setPetInfo } from '@/store/pet'
-import { setAwaitingResponse, setBusy } from '@/store/session'
-
-/**
- * The pop-out overlay's only view: a transparent, draggable mascot with a mini
- * composer.
- *
- * This runs in a separate, gateway-less BrowserWindow (`?win=overlay`). It is a
- * pure puppet — the main renderer pushes the live pet state over IPC and we
- * mirror it into the same atoms the in-window pet reads, so `PetSprite` /
- * `PetBubble` render identically with zero extra logic.
- *
- * The window is a full rectangle but mostly transparent; we toggle OS-level
- * mouse click-through so only the sprite (or the open composer) is interactive
- * and the empty margins pass clicks through to whatever is behind.
- *
- * Gestures on the pet: drag to move it anywhere on screen (even outside the
- * app), shift-click to pop it back into the window, single-click to open a small
- * composer, double-click to toggle the app window (minimize ↔ restore). A mail
- * icon (shown only when a turn finished while you were away) raises the app on
- * the most recent thread.
- */
-
-// Below this much pointer travel, a press counts as a click, not a drag.
-const CLICK_SLOP_PX = 3
-// A second click within this window is a double-click (raise app) and cancels
-// the deferred single-click (open composer), so a double never flashes it open.
-const DOUBLE_CLICK_MS = 250
-
-interface DragState {
-  startX: number
-  startY: number
-  offX: number
-  offY: number
-  width: number
-  height: number
-  moved: boolean
-}
-
-export function PetOverlayApp() {
-  const info = useStore($petInfo)
-  const [composerOpen, setComposerOpen] = useState(false)
-  const [draft, setDraft] = useState('')
-  // Mirrored from the main renderer: a finish landed while you were away.
-  const [unread, setUnread] = useState(false)
-
-  const dragRef = useRef<DragState | null>(null)
-  const petRef = useRef<HTMLDivElement | null>(null)
-  const inputRef = useRef<HTMLInputElement | null>(null)
-  const ignoreRef = useRef(true)
-  const composerOpenRef = useRef(false)
-  const clickTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
-
-  const setIgnore = (ignore: boolean) => {
-    if (ignoreRef.current !== ignore) {
-      ignoreRef.current = ignore
-      window.hermesDesktop?.petOverlay?.setIgnoreMouse(ignore)
-    }
-  }
-
-  // Mirror pushed state into the shared atoms so PetSprite/PetBubble just work.
-  useEffect(() => {
-    const off = window.hermesDesktop?.petOverlay?.onState(payload => {
-      setPetInfo(payload.info)
-      $petActivity.set(payload.activity ?? {})
-      setBusy(Boolean(payload.busy))
-      setAwaitingResponse(Boolean(payload.awaiting))
-      setUnread(Boolean(payload.unread))
-    })
-
-    // Tell the main renderer we're mounted so it pushes the current frame (the
-    // subscribe-time pushes during open() can land before this view exists).
-    window.hermesDesktop?.petOverlay?.control({ type: 'ready' })
-
-    return off
-  }, [])
-
-  // Click-through: make only the sprite (or an open composer) interactive. With
-  // ignore+forward, the renderer still receives mousemove so we can re-enable
-  // hit-testing the moment the cursor returns to the pet.
-  useEffect(() => {
-    setIgnore(true)
-
-    const onMove = (ev: MouseEvent) => {
-      if (dragRef.current || composerOpenRef.current) {
-        setIgnore(false)
-
-        return
-      }
-
-      const el = petRef.current
-
-      if (!el) {
-        return
-      }
-
-      const r = el.getBoundingClientRect()
-      const over = ev.clientX >= r.left && ev.clientX <= r.right && ev.clientY >= r.top && ev.clientY <= r.bottom
-      setIgnore(!over)
-    }
-
-    window.addEventListener('mousemove', onMove)
-
-    return () => {
-      window.removeEventListener('mousemove', onMove)
-      clearTimeout(clickTimerRef.current)
-    }
-  }, [])
-
-  // The whole window must stay interactive while the composer is open (so the
-  // input keeps focus); focus it on open. The overlay is a non-activating panel
-  // (so it never steals the app's cmd/alt-tab anchor) — flip it focusable while
-  // the composer needs the keyboard, then back to non-activating when it closes.
-  useEffect(() => {
-    composerOpenRef.current = composerOpen
-
-    window.hermesDesktop?.petOverlay?.setFocusable(composerOpen)
-
-    if (composerOpen) {
-      setIgnore(false)
-      // The OS window has to become key first (setFocusable + focus happen in
-      // the main process), so focus the input on the next frame.
-      requestAnimationFrame(() => inputRef.current?.focus())
-    }
-  }, [composerOpen])
-
-  const onPetPointerDown = (e: React.PointerEvent) => {
-    if (e.button !== 0) {
-      return
-    }
-
-    ;(e.target as Element).setPointerCapture?.(e.pointerId)
-    dragRef.current = {
-      height: window.outerHeight,
-      moved: false,
-      offX: e.screenX - window.screenX,
-      offY: e.screenY - window.screenY,
-      startX: e.screenX,
-      startY: e.screenY,
-      width: window.outerWidth
-    }
-  }
-
-  const onPetPointerMove = (e: React.PointerEvent) => {
-    const drag = dragRef.current
-
-    if (!drag) {
-      return
-    }
-
-    if (Math.hypot(e.screenX - drag.startX, e.screenY - drag.startY) > CLICK_SLOP_PX) {
-      drag.moved = true
-    }
-
-    window.hermesDesktop?.petOverlay?.setBounds({
-      height: drag.height,
-      width: drag.width,
-      x: e.screenX - drag.offX,
-      y: e.screenY - drag.offY
-    })
-  }
-
-  const onPetPointerUp = (e: React.PointerEvent) => {
-    const drag = dragRef.current
-    dragRef.current = null
-    ;(e.target as Element).releasePointerCapture?.(e.pointerId)
-
-    if (!drag) {
-      return
-    }
-
-    if (drag.moved) {
-      // A drag cancels any deferred single-click so the composer can't pop open
-      // after you reposition the pet.
-      clearTimeout(clickTimerRef.current)
-      clickTimerRef.current = undefined
-
-      // Remember the spot on the desktop (screen coords) so the pet reopens here
-      // next time / after a restart.
-      window.hermesDesktop?.petOverlay?.control({
-        bounds: { height: drag.height, width: drag.width, x: e.screenX - drag.offX, y: e.screenY - drag.offY },
-        type: 'bounds'
-      })
-
-      return
-    }
-
-    // Shift-click always pops the pet back in (no double-click ambiguity).
-    if (e.shiftKey) {
-      window.hermesDesktop?.petOverlay?.control({ type: 'pop-in' })
-
-      return
-    }
-
-    // Double-click toggles the app window (minimize ↔ restore); defer the
-    // single-click composer toggle so a double never flashes the composer open.
-    if (clickTimerRef.current) {
-      clearTimeout(clickTimerRef.current)
-      clickTimerRef.current = undefined
-      window.hermesDesktop?.petOverlay?.control({ type: 'toggle-app' })
-
-      return
-    }
-
-    clickTimerRef.current = setTimeout(() => {
-      clickTimerRef.current = undefined
-      setComposerOpen(open => !open)
-    }, DOUBLE_CLICK_MS)
-  }
-
-  const send = () => {
-    const text = draft.trim()
-
-    if (text) {
-      window.hermesDesktop?.petOverlay?.control({ text, type: 'submit' })
-    }
-
-    setDraft('')
-    setComposerOpen(false)
-  }
-
-  const openApp = () => {
-    // Hide the icon immediately; the main renderer also clears the source flag.
-    setUnread(false)
-    window.hermesDesktop?.petOverlay?.control({ type: 'open-app' })
-  }
-
-  if (!info.enabled || !info.spritesheetBase64) {
-    return null
-  }
-
-  return (
-    <div
-      onPointerDown={e => {
-        // Click on the transparent backdrop (not the pet/composer) dismisses
-        // the composer.
-        if (composerOpen && e.target === e.currentTarget) {
-          setComposerOpen(false)
-        }
-      }}
-      style={{
-        alignItems: 'center',
-        background: 'transparent',
-        display: 'flex',
-        flexDirection: 'column',
-        height: '100vh',
-        justifyContent: 'flex-end',
-        paddingBottom: 24,
-        userSelect: 'none',
-        width: '100vw'
-      }}
-    >
-      {composerOpen && (
-        <input
-          onChange={e => setDraft(e.target.value)}
-          onKeyDown={e => {
-            if (e.key === 'Enter' && !e.shiftKey) {
-              e.preventDefault()
-              send()
-            } else if (e.key === 'Escape') {
-              setComposerOpen(false)
-            }
-          }}
-          placeholder="Message…"
-          ref={inputRef}
-          style={{
-            background: 'var(--ui-bg-elevated)',
-            border: '1px solid var(--ui-stroke-secondary)',
-            borderRadius: 2,
-            boxShadow: '0 6px 18px rgba(0,0,0,0.28)',
-            color: 'var(--foreground)',
-            fontSize: 12,
-            marginBottom: 8,
-            outline: 'none',
-            padding: '4px 8px',
-            width: 184
-          }}
-          value={draft}
-        />
-      )}
-
-      <div
-        onPointerDown={onPetPointerDown}
-        onPointerMove={onPetPointerMove}
-        onPointerUp={onPetPointerUp}
-        ref={petRef}
-        style={{
-          alignItems: 'center',
-          cursor: 'grab',
-          display: 'flex',
-          flexDirection: 'column',
-          position: 'relative',
-          touchAction: 'none'
-        }}
-      >
-        <div style={{ marginBottom: 4 }}>
-          <PetBubble />
-        </div>
-        <div style={{ lineHeight: 0, position: 'relative' }}>
-          <PetSprite info={info} />
-
-          {/* Mail icon: only when a finish landed while you were away. Jumps to
-              the app's most recent thread. Anchored to the sprite (kept inside
-              its box so the overlay's click-through hit-test still catches it);
-              stopPropagation keeps a click from starting a window drag. */}
-          {unread && (
-            <button
-              aria-label="Open in Hermes"
-              onClick={openApp}
-              onPointerDown={e => e.stopPropagation()}
-              onPointerUp={e => e.stopPropagation()}
-              style={{
-                alignItems: 'center',
-                background: 'var(--ui-bg-elevated)',
-                border: '1px solid var(--ui-stroke-secondary)',
-                borderRadius: 999,
-                boxShadow: '0 4px 14px rgba(0,0,0,0.22)',
-                color: 'var(--foreground)',
-                cursor: 'pointer',
-                display: 'inline-flex',
-                height: 24,
-                justifyContent: 'center',
-                padding: 0,
-                position: 'absolute',
-                right: 0,
-                top: 0,
-                width: 24
-              }}
-              title="Open in Hermes"
-              type="button"
-            >
-              <Mail style={{ height: 13, width: 13 }} />
-            </button>
-          )}
-        </div>
-      </div>
-    </div>
-  )
-}

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'
@@ -33,7 +34,6 @@ import { $gateway } from '@/store/gateway'
 import { dispatchNativeNotification } from '@/store/native-notifications'
 import { notify } from '@/store/notifications'
 import { requestDesktopOnboarding } from '@/store/onboarding'
-import { flashPetActivity, markPetUnread, setPetActivity } from '@/store/pet'
 import { clearAllPrompts, setApprovalRequest, setSecretRequest, setSudoRequest } from '@/store/prompts'
 import {
   setCurrentBranch,
@@ -870,18 +870,10 @@ export function useMessageStream({
         if (sessionId) {
           appendReasoningDelta(sessionId, coerceThinkingText(payload?.text))
         }
-
-        if (isActiveEvent) {
-          setPetActivity({ reasoning: true })
-        }
       } else if (event.type === 'reasoning.available') {
         if (sessionId) {
           appendReasoningDelta(sessionId, coerceThinkingText(payload?.text), true)
         }
-
-        if (isActiveEvent) {
-          setPetActivity({ reasoning: true })
-        }
       } else if (event.type === 'message.complete') {
         if (!sessionId) {
           return
@@ -903,20 +895,6 @@ export function useMessageStream({
 
         if (isActiveEvent) {
           setTurnStartedAt(null)
-
-          // Pet beat: a finished turn always celebrates — go straight to the
-          // jump, never linger on the run/reason pose. One atom update (clears
-          // toolRunning/reasoning AND sets celebrate together) so no stray "run"
-          // frame leaks to the sprite — including the popped-out overlay, which
-          // mirrors each activity change. The jump runs ~2 loops, then settles.
-          flashPetActivity({ celebrate: true, reasoning: false, toolRunning: false }, 2200)
-
-          // Light up the pet's mail icon if the user wasn't looking when the turn
-          // finished — a glanceable "new message" hint on the popped-out overlay.
-          // Cleared when they open the app via the mail icon or refocus the window.
-          if (typeof document !== 'undefined' && !document.hasFocus()) {
-            markPetUnread()
-          }
         }
 
         if (payload?.usage) {
@@ -929,19 +907,10 @@ export function useMessageStream({
 
         flushQueuedDeltas(sessionId)
         upsertToolCall(sessionId, toTodoPayload(payload) ?? payload, 'running', event.type)
-
-        if (isActiveEvent) {
-          setPetActivity({ reasoning: false, toolRunning: true })
-        }
       } else if (event.type === 'tool.complete') {
         if (sessionId) {
           flushQueuedDeltas(sessionId)
           upsertToolCall(sessionId, toTodoPayload(payload) ?? payload, 'complete', event.type)
-
-          if (isActiveEvent) {
-            setPetActivity({ toolRunning: false })
-          }
-
           // A pending clarify blocks the turn, so the first tool.complete after
           // one is the clarify resolving — drop the "needs input" flag here so
           // the sidebar indicator clears as soon as it's answered, not only at
@@ -1112,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)
@@ -1125,11 +1120,6 @@ export function useMessageStream({
           compactedTurnRef.current.delete(sessionId)
         }
 
-        if (isActiveEvent) {
-          setPetActivity({ reasoning: false, toolRunning: false })
-          flashPetActivity({ error: true })
-        }
-
         dispatchNativeNotification({
           body: errorMessage,
           kind: 'turnError',
@@ -1139,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-prompt-actions.ts

@@ -27,7 +27,6 @@ import { triggerHaptic } from '@/lib/haptics'
 import { setMutableRef } from '@/lib/mutable-ref'
 import { isProviderSetupErrorMessage } from '@/lib/provider-setup-errors'
 import { setSessionYolo } from '@/lib/yolo-session'
-import { openCommandPalettePage } from '@/store/command-palette'
 import {
   $composerAttachments,
   clearComposerAttachments,
@@ -39,7 +38,6 @@ import {
 import { resetSessionBackground } from '@/store/composer-status'
 import { clearNotifications, notify, notifyError } from '@/store/notifications'
 import { requestDesktopOnboarding } from '@/store/onboarding'
-import { setPetScale } from '@/store/pet-gallery'
 import { $activeGatewayProfile, $newChatProfile, ensureGatewayProfile, normalizeProfileKey } from '@/store/profile'
 import {
   $busy,
@@ -59,8 +57,8 @@ import { clearSessionSubagents } from '@/store/subagents'
 import { clearSessionTodos } from '@/store/todos'
 
 import type {
-  BrowserManageResponse,
   ClientSessionState,
+  BrowserManageResponse,
   FileAttachResponse,
   HandoffFailResponse,
   HandoffRequestResponse,
@@ -1145,35 +1143,6 @@ export function usePromptActions({
             renderSlashOutput(`error: ${err instanceof Error ? err.message : String(err)}`)
           }
         },
-        pet: async ctx => {
-          const [sub = '', rawValue = ''] = ctx.arg.trim().split(/\s+/)
-          const lower = sub.toLowerCase()
-
-          if (lower === 'list' || lower === 'gallery' || lower === 'browse' || lower === 'all') {
-            openCommandPalettePage('pets')
-
-            return
-          }
-
-          // `/pet scale <n>` resizes the floating pet locally (instant) and
-          // persists via the store — no round-trip to the slash worker.
-          if (lower === 'scale') {
-            const value = Number(rawValue)
-
-            if (!rawValue || Number.isNaN(value)) {
-              const resolved = await withSlashOutput(ctx)
-              resolved?.render('usage: /pet scale <factor>  (e.g. /pet scale 0.5)')
-
-              return
-            }
-
-            setPetScale(requestGateway, value)
-
-            return
-          }
-
-          await runExec(ctx)
-        },
         // /browser connect|disconnect|status manages the live CDP connection on
         // the gateway host, mirroring the TUI's browser.manage RPC. It mutates
         // BROWSER_CDP_URL (and may launch Chrome) in the gateway process — only
@@ -1390,7 +1359,6 @@ export function usePromptActions({
 
   const cancelRun = useCallback(async () => {
     const sessionId = activeSessionId || activeSessionIdRef.current
-
     const releaseBusy = () => {
       setMutableRef(busyRef, false)
       setBusy(false)

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

@@ -38,6 +38,8 @@ import {
   setFreshDraftReady,
   setIntroSeed,
   setMessages,
+  setResumeExhaustedSessionId,
+  setResumeFailedSessionId,
   setSelectedStoredSessionId,
   setSessions,
   setSessionStartedAt,
@@ -579,6 +581,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)
 
@@ -769,13 +780,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()) {

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/appearance-settings.tsx

@@ -1,31 +1,30 @@
 import { useStore } from '@nanostores/react'
-import { useQuery } from '@tanstack/react-query'
-import { useEffect, useState } from 'react'
+import { useState } from 'react'
 
 import { LanguageSwitcher } from '@/components/language-switcher'
 import { SegmentedControl } from '@/components/ui/segmented-control'
-import type { DesktopMarketplaceSearchItem } from '@/global'
 import { useI18n } from '@/i18n'
 import { triggerHaptic } from '@/lib/haptics'
 import { Check, Download, Loader2, Palette, Trash2 } from '@/lib/icons'
-import { selectableCardClass } from '@/lib/selectable-card'
 import { cn } from '@/lib/utils'
 import { $activeGatewayProfile, $profiles, normalizeProfileKey } from '@/store/profile'
 import { $toolViewMode, setToolViewMode } from '@/store/tool-view'
 import { $translucency, setTranslucency } from '@/store/translucency'
-import { getBaseColors, useTheme } from '@/themes/context'
+import { useTheme } from '@/themes/context'
 import { installVscodeThemeFromMarketplace } from '@/themes/install'
-import { isUserTheme, removeUserTheme } from '@/themes/user-themes'
+import { isUserTheme, removeUserTheme, resolveTheme } from '@/themes/user-themes'
 
 import { MODE_OPTIONS } from './constants'
-import { PetSettings } from './pet-settings'
 import { ListRow, SectionHeading, SettingsContent } from './primitives'
 
-function ThemePreview({ name, mode }: { name: string; mode: 'light' | 'dark' }) {
-  // Preview in the *current* mode: the dark palette in Dark, and the light
-  // palette in Light — synthesizing one for dark-only themes — so every card
-  // tracks the Light/Dark toggle, exactly like the app itself does.
-  const c = getBaseColors(name, mode)
+function ThemePreview({ name }: { name: string }) {
+  const t = resolveTheme(name)
+
+  if (!t) {
+    return null
+  }
+
+  const c = t.colors
 
   return (
     <div
@@ -58,200 +57,90 @@ function ThemePreview({ name, mode }: { name: string; mode: 'light' | 'dark' })
   )
 }
 
-function useDebounced<T>(value: T, delayMs: number): T {
-  const [debounced, setDebounced] = useState(value)
-
-  useEffect(() => {
-    const handle = setTimeout(() => setDebounced(value), delayMs)
-
-    return () => clearTimeout(handle)
-  }, [value, delayMs])
-
-  return debounced
-}
-
-const compactNumber = new Intl.NumberFormat(undefined, { notation: 'compact', maximumFractionDigits: 1 })
-
-/**
- * Live VS Code Marketplace theme search (the same backend as the Cmd-K "Install
- * theme…" page). Renders below the local grid when there's a query: each row
- * downloads + converts + installs via `installVscodeThemeFromMarketplace` and
- * activates it. Extensions already imported locally are marked installed.
- */
-function MarketplaceThemeResults({
-  query,
-  installedExtIds,
-  onInstalled
-}: {
-  query: string
-  installedExtIds: Set<string>
-  onInstalled: (name: string) => void
-}) {
+function VscodeThemeInstaller() {
   const { t } = useI18n()
-  const copy = t.commandCenter.installTheme
-  const debounced = useDebounced(query.trim(), 300)
-  const [installingId, setInstallingId] = useState<string | null>(null)
-  const [installedHere, setInstalledHere] = useState<Record<string, true>>({})
-  const [error, setError] = useState<string | null>(null)
+  const { setTheme } = useTheme()
+  const a = t.settings.appearance
+  const [id, setId] = useState('')
+  const [busy, setBusy] = useState(false)
+  const [status, setStatus] = useState<{ kind: 'error' | 'success'; text: string } | null>(null)
 
-  const search = useQuery({
-    enabled: debounced.length > 0,
-    queryFn: () => window.hermesDesktop?.themes?.searchMarketplace(debounced) ?? Promise.resolve([]),
-    queryKey: ['marketplace-themes-settings', debounced],
-    staleTime: 5 * 60 * 1000
-  })
+  const install = async () => {
+    const trimmed = id.trim()
 
-  const install = async (item: DesktopMarketplaceSearchItem) => {
-    if (installingId) {
+    if (!trimmed || busy) {
       return
     }
 
-    setInstallingId(item.extensionId)
-    setError(null)
+    setBusy(true)
+    setStatus(null)
 
     try {
-      const theme = await installVscodeThemeFromMarketplace(item.extensionId)
+      const theme = await installVscodeThemeFromMarketplace(trimmed)
 
       triggerHaptic('crisp')
-      setInstalledHere(prev => ({ ...prev, [item.extensionId]: true }))
-      onInstalled(theme.name)
-    } catch (e) {
-      setError(e instanceof Error ? e.message : copy.error)
+      setTheme(theme.name)
+      setStatus({ kind: 'success', text: a.installed(theme.label) })
+      setId('')
+    } catch (error) {
+      setStatus({ kind: 'error', text: error instanceof Error ? error.message : a.installError })
     } finally {
-      setInstallingId(null)
+      setBusy(false)
     }
   }
 
-  if (!debounced) {
-    return null
-  }
-
-  const header = (
-    <p className="mb-2 mt-4 text-[length:var(--conversation-caption-font-size)] font-medium text-(--ui-text-tertiary)">
-      From the VS Code Marketplace
-    </p>
-  )
-
-  if (search.isLoading) {
-    return (
-      <>
-        {header}
-        <p className="flex items-center gap-2 text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
-          <Loader2 className="size-3.5 animate-spin" />
-          {copy.loading}
-        </p>
-      </>
-    )
-  }
-
-  if (search.isError) {
-    return (
-      <>
-        {header}
-        <p className="text-[length:var(--conversation-caption-font-size)] text-(--ui-red)">{copy.error}</p>
-      </>
-    )
-  }
-
-  const results = search.data ?? []
-
-  if (results.length === 0) {
-    return (
-      <>
-        {header}
-        <p className="text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">{copy.empty}</p>
-      </>
-    )
-  }
-
   return (
-    <>
-      {header}
-      {error && <p className="mb-2 text-[length:var(--conversation-caption-font-size)] text-(--ui-red)">{error}</p>}
-      <div className="grid gap-2 sm:grid-cols-2">
-        {results.map(item => {
-          const busy = installingId === item.extensionId
-          const done = installedHere[item.extensionId] || installedExtIds.has(item.extensionId)
-
-          return (
-            <button
-              className={cn(
-                'flex items-center gap-2.5 px-2.5 py-2 text-left disabled:opacity-60',
-                selectableCardClass({ prominent: done })
-              )}
-              disabled={Boolean(installingId) && !busy}
-              key={item.extensionId}
-              onClick={() => void install(item)}
-              type="button"
-            >
-              <Palette className="size-4 shrink-0 text-(--ui-text-tertiary)" />
-              <span className="min-w-0 flex-1">
-                <span className="block truncate text-[length:var(--conversation-text-font-size)] font-medium">
-                  {item.displayName}
-                </span>
-                <span className="block truncate text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
-                  {item.publisher}
-                  {item.installs > 0 ? ` · ${copy.installs(compactNumber.format(item.installs))}` : ''}
-                </span>
-              </span>
-              <span className="shrink-0 text-(--ui-text-tertiary)">
-                {busy ? (
-                  <Loader2 className="size-4 animate-spin" />
-                ) : done ? (
-                  <Check className="size-4 text-(--ui-green)" />
-                ) : (
-                  <Download className="size-4" />
-                )}
-              </span>
-            </button>
-          )
-        })}
+    <div className="mt-3">
+      <div className="flex flex-wrap items-center gap-2">
+        <input
+          className="min-w-0 flex-1 rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) px-3 py-1.5 font-mono text-[length:var(--conversation-caption-font-size)] outline-none placeholder:text-(--ui-text-tertiary) focus:border-(--ui-stroke-secondary)"
+          disabled={busy}
+          onChange={event => {
+            setId(event.target.value)
+            setStatus(null)
+          }}
+          onKeyDown={event => {
+            if (event.key === 'Enter') {
+              void install()
+            }
+          }}
+          placeholder={a.installPlaceholder}
+          spellCheck={false}
+          value={id}
+        />
+        <button
+          className="inline-flex items-center gap-1.5 rounded-lg border border-(--ui-stroke-secondary) bg-(--ui-bg-tertiary) px-3 py-1.5 text-[length:var(--conversation-caption-font-size)] font-medium transition hover:bg-(--chrome-action-hover) disabled:opacity-50"
+          disabled={busy || !id.trim()}
+          onClick={() => void install()}
+          type="button"
+        >
+          {busy ? <Loader2 className="size-3.5 animate-spin" /> : <Download className="size-3.5" />}
+          {busy ? a.installing : a.installButton}
+        </button>
       </div>
-    </>
+      {status && (
+        <p
+          className={cn(
+            'mt-2 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height)',
+            status.kind === 'error' ? 'text-(--ui-red)' : 'text-(--ui-text-tertiary)'
+          )}
+        >
+          {status.text}
+        </p>
+      )}
+    </div>
   )
 }
 
 export function AppearanceSettings() {
   const { t, isSavingLocale } = useI18n()
-  const { themeName, mode, resolvedMode, availableThemes, setTheme, setMode } = useTheme()
+  const { themeName, mode, availableThemes, setTheme, setMode } = useTheme()
   const toolViewMode = useStore($toolViewMode)
   const translucency = useStore($translucency)
   const profiles = useStore($profiles)
   const activeProfileKey = normalizeProfileKey(useStore($activeGatewayProfile))
   const a = t.settings.appearance
 
-  const [query, setQuery] = useState('')
-
-  // One box does double duty: filter installed themes live (below), and run a
-  // name search against the VS Code Marketplace (the Cmd-K "Install theme…"
-  // backend) for anything not already installed.
-  const needle = query.trim().toLowerCase()
-
-  const filteredThemes = availableThemes
-    .filter(
-      theme =>
-        !needle ||
-        theme.label.toLowerCase().includes(needle) ||
-        theme.name.toLowerCase().includes(needle) ||
-        theme.description.toLowerCase().includes(needle)
-    )
-    // Active theme first; stable sort keeps the rest in their original order.
-    .sort((a, b) => Number(b.name === themeName) - Number(a.name === themeName))
-
-  // Marketplace imports describe themselves as "VS Code · <publisher.extension>";
-  // pull those ids back out so search results already imported show as installed.
-  const MARKETPLACE_DESC_PREFIX = 'VS Code · '
-
-  const installedExtIds = new Set(
-    availableThemes
-      .map(theme =>
-        theme.description.startsWith(MARKETPLACE_DESC_PREFIX)
-          ? theme.description.slice(MARKETPLACE_DESC_PREFIX.length)
-          : ''
-      )
-      .filter(Boolean)
-  )
-
   // Themes save per profile. Surface that only when the user actually has more
   // than one profile (single-profile installs never see the distinction).
   const showProfileNote = profiles.length > 1
@@ -274,7 +163,7 @@ export function AppearanceSettings() {
           {a.intro}
         </p>
 
-        <div className="mt-2">
+        <div className="mt-2 divide-y divide-(--ui-stroke-tertiary)">
           <ListRow
             action={<LanguageSwitcher />}
             description={isSavingLocale ? t.language.saving : t.language.description}
@@ -282,107 +171,18 @@ export function AppearanceSettings() {
           />
 
           <ListRow
-            below={
-              <>
-                {/* One search box: filters your installed themes (the grid)
-                    and live-searches the VS Code Marketplace below. */}
-                <div className="mt-3">
-                  <input
-                    className="w-full rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) px-3 py-1.5 text-[length:var(--conversation-caption-font-size)] outline-none placeholder:text-(--ui-text-tertiary) focus:border-(--ui-stroke-secondary)"
-                    onChange={event => setQuery(event.target.value)}
-                    placeholder="Search your themes or the VS Code Marketplace…"
-                    spellCheck={false}
-                    value={query}
-                  />
-                </div>
-
-                {/* Fixed-height scroll area so the (growing) theme list never
-                    runs the page long; the grid scrolls inside it. */}
-                <div className="mt-3 max-h-96 overflow-y-auto pr-1">
-                  {filteredThemes.length === 0 ? (
-                    needle ? (
-                      <p className="text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
-                        No installed themes match "{query.trim()}".
-                      </p>
-                    ) : null
-                  ) : (
-                    <div className="grid gap-3 sm:grid-cols-2 xl:grid-cols-3">
-                      {filteredThemes.map(theme => {
-                        const active = themeName === theme.name
-                        const removable = isUserTheme(theme.name)
-
-                        return (
-                          <div className="group relative" key={theme.name}>
-                            <button
-                              className={cn('w-full p-2 text-left', selectableCardClass({ active, prominent: true }))}
-                              onClick={() => {
-                                triggerHaptic('crisp')
-                                setTheme(theme.name)
-                              }}
-                              type="button"
-                            >
-                              <ThemePreview mode={resolvedMode} name={theme.name} />
-                              <div className="mt-3 px-1">
-                                <div className="truncate text-[length:var(--conversation-text-font-size)] font-medium">
-                                  {theme.label}
-                                </div>
-                                <div className="mt-0.5 line-clamp-2 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
-                                  {theme.description}
-                                </div>
-                              </div>
-                            </button>
-                            {removable && (
-                              <button
-                                aria-label={a.removeTheme}
-                                className="absolute right-1.5 top-1.5 grid size-6 place-items-center rounded-md bg-(--ui-bg-elevated)/80 text-(--ui-text-tertiary) opacity-0 backdrop-blur-sm transition hover:text-(--ui-red) focus-visible:opacity-100 group-hover:opacity-100"
-                                onClick={() => {
-                                  triggerHaptic('crisp')
-                                  removeUserTheme(theme.name)
-
-                                  // Re-normalize off the now-missing skin → default.
-                                  if (active) {
-                                    setTheme(theme.name)
-                                  }
-                                }}
-                                title={a.removeTheme}
-                                type="button"
-                              >
-                                <Trash2 className="size-3.5" />
-                              </button>
-                            )}
-                          </div>
-                        )
-                      })}
-                    </div>
-                  )}
-                  <MarketplaceThemeResults
-                    installedExtIds={installedExtIds}
-                    onInstalled={name => setTheme(name)}
-                    query={query}
-                  />
-                </div>
-                {showProfileNote && (
-                  <p className="mt-3 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
-                    {a.themeProfileNote(activeProfileName)}
-                  </p>
-                )}
-              </>
+            action={
+              <SegmentedControl
+                onChange={id => {
+                  triggerHaptic('crisp')
+                  setMode(id)
+                }}
+                options={modeOptions}
+                value={mode}
+              />
             }
-            description={a.themeDesc}
-            title={
-              <div className="flex items-center justify-between gap-3">
-                <span>{a.themeTitle}</span>
-                <SegmentedControl
-                  onChange={id => {
-                    triggerHaptic('crisp')
-                    setMode(id)
-                  }}
-                  options={modeOptions}
-                  value={mode}
-                />
-              </div>
-            }
-            wide
+            description={a.colorModeDesc}
+            title={a.colorMode}
           />
 
           <ListRow
@@ -411,6 +211,80 @@ export function AppearanceSettings() {
             title={a.translucencyTitle}
           />
 
+          <ListRow
+            below={
+              <>
+                <div className="mt-3 grid gap-3 sm:grid-cols-2 xl:grid-cols-3">
+                  {availableThemes.map(theme => {
+                    const active = themeName === theme.name
+                    const removable = isUserTheme(theme.name)
+
+                    return (
+                      <div className="group relative" key={theme.name}>
+                        <button
+                          className={cn(
+                            'w-full rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) p-2 text-left transition hover:bg-(--chrome-action-hover)',
+                            active && 'border-(--ui-stroke-secondary) bg-(--ui-bg-tertiary)'
+                          )}
+                          onClick={() => {
+                            triggerHaptic('crisp')
+                            setTheme(theme.name)
+                          }}
+                          type="button"
+                        >
+                          <ThemePreview name={theme.name} />
+                          <div className="mt-3 flex items-start justify-between gap-3 px-1">
+                            <div className="min-w-0">
+                              <div className="truncate text-[length:var(--conversation-text-font-size)] font-medium">
+                                {theme.label}
+                              </div>
+                              <div className="mt-0.5 line-clamp-2 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
+                                {theme.description}
+                              </div>
+                            </div>
+                            {active && (
+                              <span className="mt-0.5 grid size-5 shrink-0 place-items-center rounded-full bg-primary text-primary-foreground">
+                                <Check className="size-3.5" />
+                              </span>
+                            )}
+                          </div>
+                        </button>
+                        {removable && (
+                          <button
+                            aria-label={a.removeTheme}
+                            className="absolute right-1.5 top-1.5 grid size-6 place-items-center rounded-md bg-(--ui-bg-elevated)/80 text-(--ui-text-tertiary) opacity-0 backdrop-blur-sm transition hover:text-(--ui-red) focus-visible:opacity-100 group-hover:opacity-100"
+                            onClick={() => {
+                              triggerHaptic('crisp')
+                              removeUserTheme(theme.name)
+
+                              // Re-normalize off the now-missing skin → default.
+                              if (active) {
+                                setTheme(theme.name)
+                              }
+                            }}
+                            title={a.removeTheme}
+                            type="button"
+                          >
+                            <Trash2 className="size-3.5" />
+                          </button>
+                        )}
+                      </div>
+                    )
+                  })}
+                </div>
+                <VscodeThemeInstaller />
+                {showProfileNote && (
+                  <p className="mt-3 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
+                    {a.themeProfileNote(activeProfileName)}
+                  </p>
+                )}
+              </>
+            }
+            description={a.themeDesc}
+            title={a.themeTitle}
+            wide
+          />
+
           <ListRow
             action={
               <SegmentedControl
@@ -427,10 +301,6 @@ export function AppearanceSettings() {
           />
         </div>
       </div>
-
-      <div className="mt-6">
-        <PetSettings />
-      </div>
     </SettingsContent>
   )
 }

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/pet-settings.tsx

@@ -1,231 +0,0 @@
-import { useStore } from '@nanostores/react'
-import { useEffect, useState } from 'react'
-
-import { useGatewayRequest } from '@/app/gateway/hooks/use-gateway-request'
-import { PetThumb } from '@/components/pet/pet-thumb'
-import { SegmentedControl } from '@/components/ui/segmented-control'
-import { useI18n } from '@/i18n'
-import { triggerHaptic } from '@/lib/haptics'
-import { Loader2, PawPrint, Trash2 } from '@/lib/icons'
-import { selectableCardClass } from '@/lib/selectable-card'
-import { cn } from '@/lib/utils'
-import { $petInfo } from '@/store/pet'
-import {
-  $petBusy,
-  $petGallery,
-  $petGalleryError,
-  $petGalleryStatus,
-  adoptPet,
-  loadPetGallery,
-  loadPetThumb,
-  PET_SCALE_DEFAULT,
-  PET_SCALE_MAX,
-  PET_SCALE_MIN,
-  rankedGalleryPets,
-  removePet as removePetAction,
-  setPetEnabled,
-  setPetScale
-} from '@/store/pet-gallery'
-import { $gatewayState } from '@/store/session'
-
-import { ListRow, SectionHeading } from './primitives'
-
-/**
- * Appearance opt-in for the floating petdex mascot. A thin view over the shared
- * `pet-gallery` store — it subscribes to the atoms and calls the store actions,
- * so the gallery is fetched once + cached and adopt/toggle/remove patch local
- * state instead of re-pulling the network gallery. The floating mascot polls
- * `pet.info`, so picking a pet here lights it up within a couple seconds.
- */
-export function PetSettings() {
-  const { t } = useI18n()
-  const copy = t.settings.appearance.pet
-  const { requestGateway } = useGatewayRequest()
-  const gatewayState = useStore($gatewayState)
-  const gallery = useStore($petGallery)
-  const status = useStore($petGalleryStatus)
-  const error = useStore($petGalleryError)
-  const busySlug = useStore($petBusy)
-  const petInfo = useStore($petInfo)
-  const [query, setQuery] = useState('')
-  const scale = petInfo.scale ?? PET_SCALE_DEFAULT
-
-  useEffect(() => {
-    if (gatewayState !== 'open') {
-      return
-    }
-
-    void loadPetGallery(requestGateway)
-  }, [gatewayState, requestGateway])
-
-  const enabled = gallery?.enabled ?? false
-  const active = gallery?.active ?? ''
-  const pets = gallery?.pets ?? []
-  const staleBackend = status === 'stale'
-
-  const selectPet = (slug: string) => {
-    void adoptPet(requestGateway, slug, copy.adoptFailed(slug)).then(ok => ok && triggerHaptic('crisp'))
-  }
-
-  const removePet = (slug: string) => {
-    void removePetAction(requestGateway, slug, copy.uninstallFailed(slug)).then(ok => ok && triggerHaptic('crisp'))
-  }
-
-  const toggle = (on: boolean) => {
-    void setPetEnabled(requestGateway, on, {
-      noneAvailable: copy.noneAvailable,
-      fallback: on ? copy.turnOnFailed : copy.turnOffFailed
-    }).then(ok => ok && triggerHaptic('crisp'))
-  }
-
-  // The petdex catalog is thousands of entries, so rank + cap how many render.
-  const RENDER_CAP = 60
-  const sorted = rankedGalleryPets(gallery, query)
-  const shown = sorted.slice(0, RENDER_CAP)
-
-  return (
-    <div>
-      <SectionHeading icon={PawPrint} title={copy.title} />
-      <p className="max-w-2xl text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
-        {copy.intro}
-      </p>
-
-      {staleBackend && (
-        <p className="mt-2 rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) px-3 py-2 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
-          {copy.restartHint}
-        </p>
-      )}
-
-      <div className="mt-2">
-        <ListRow
-          below={
-            <>
-              <input
-                className="mt-3 w-full rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) px-3 py-1.5 text-[length:var(--conversation-caption-font-size)] outline-none placeholder:text-(--ui-text-tertiary) focus:border-(--ui-stroke-secondary)"
-                onChange={event => setQuery(event.target.value)}
-                placeholder={copy.searchPlaceholder}
-                spellCheck={false}
-                value={query}
-              />
-              {/* Fixed-height scroll area so filtering never grows/shrinks the
-                  page (no layout thrash); the grid scrolls inside it. */}
-              <div className="mt-3 h-72 overflow-y-auto pr-1">
-                {pets.length === 0 ? (
-                  <p className="text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
-                    {copy.unreachable}
-                  </p>
-                ) : shown.length === 0 ? (
-                  <p className="text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
-                    {copy.noMatch(query)}
-                  </p>
-                ) : (
-                  <div className="grid gap-2 sm:grid-cols-2 xl:grid-cols-3">
-                    {shown.map(pet => {
-                      const isActive = enabled && active === pet.slug
-                      const isBusy = busySlug === pet.slug
-
-                      return (
-                        <div className="group relative" key={pet.slug}>
-                          <button
-                            className={cn(
-                              'flex w-full items-center gap-2.5 px-2.5 py-2 text-left disabled:opacity-50',
-                              selectableCardClass({ active: isActive, prominent: pet.installed })
-                            )}
-                            disabled={isBusy}
-                            onClick={() => void selectPet(pet.slug)}
-                            type="button"
-                          >
-                            <PetThumb
-                              alt={pet.displayName}
-                              load={(slug, url) => loadPetThumb(requestGateway, slug, url)}
-                              slug={pet.slug}
-                              url={pet.spritesheetUrl}
-                            />
-                            <span className="min-w-0 flex-1">
-                              <span className="block truncate text-[length:var(--conversation-text-font-size)] font-medium">
-                                {pet.displayName}
-                              </span>
-                              <span className="block truncate text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
-                                {pet.slug}
-                                {pet.installed ? ` · ${copy.installedTag}` : ''}
-                              </span>
-                            </span>
-                            {isBusy && <Loader2 className="size-4 shrink-0 animate-spin text-(--ui-text-tertiary)" />}
-                          </button>
-                          {pet.installed && !isBusy && (
-                            <button
-                              aria-label={copy.uninstall(pet.displayName)}
-                              className="absolute right-1.5 top-1.5 grid size-6 place-items-center rounded-md bg-(--ui-bg-elevated)/80 text-(--ui-text-tertiary) opacity-0 backdrop-blur-sm transition hover:text-(--ui-red) focus-visible:opacity-100 group-hover:opacity-100"
-                              onClick={() => void removePet(pet.slug)}
-                              title={copy.uninstall(pet.displayName)}
-                              type="button"
-                            >
-                              <Trash2 className="size-3.5" />
-                            </button>
-                          )}
-                        </div>
-                      )
-                    })}
-                  </div>
-                )}
-              </div>
-              {/* Always-present status line so its appearance never shifts layout. */}
-              <p className="mt-2 min-h-4 text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
-                {error ? (
-                  <span className="text-(--ui-red)">{error}</span>
-                ) : sorted.length > RENDER_CAP ? (
-                  copy.countCapped(RENDER_CAP, sorted.length)
-                ) : (
-                  copy.count(sorted.length)
-                )}
-              </p>
-            </>
-          }
-          description={copy.chooseDesc}
-          title={
-            <div className="flex items-center justify-between gap-3">
-              <span>{copy.chooseTitle}</span>
-              <SegmentedControl
-                onChange={id => void toggle(id === 'on')}
-                options={[
-                  { id: 'off', label: copy.off },
-                  { id: 'on', label: copy.on }
-                ]}
-                value={enabled ? 'on' : 'off'}
-              />
-            </div>
-          }
-          wide
-        />
-
-        {enabled && (
-          <ListRow
-            action={
-              <div className="flex items-center gap-3">
-                <input
-                  aria-label={copy.scaleTitle}
-                  className="h-1 w-40 cursor-pointer appearance-none rounded-full bg-(--ui-stroke-tertiary)"
-                  max={PET_SCALE_MAX}
-                  min={PET_SCALE_MIN}
-                  onChange={event => {
-                    triggerHaptic('selection')
-                    setPetScale(requestGateway, Number(event.target.value))
-                  }}
-                  step={0.05}
-                  style={{ accentColor: 'var(--dt-primary)' }}
-                  type="range"
-                  value={scale}
-                />
-                <span className="w-9 text-right text-[length:var(--conversation-caption-font-size)] tabular-nums text-(--ui-text-tertiary)">
-                  {`${Math.round(scale * 100)}%`}
-                </span>
-              </div>
-            }
-            description={copy.scaleDesc}
-            title={copy.scaleTitle}
-          />
-        )}
-      </div>
-    </div>
-  )
-}

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

@@ -4,7 +4,6 @@ import { useSyncExternalStore } from 'react'
 
 import { NotificationStack } from '@/components/notifications'
 import { PaneShell } from '@/components/pane-shell'
-import { FloatingPet } from '@/components/pet/floating-pet'
 import { SidebarProvider } from '@/components/ui/sidebar'
 import { useMediaQuery } from '@/hooks/use-media-query'
 import {
@@ -203,10 +202,6 @@ export function AppShell({
       {/* Mounted at the shell root (after overlays) so success/error toasts
           surface above every route and overlay — not just the chat view. */}
       <NotificationStack />
-
-      {/* Petdex floating mascot — in-window, always-on-top, reactive to agent
-          activity. Renders nothing unless a pet is installed + enabled. */}
-      <FloatingPet />
     </SidebarProvider>
   )
 }

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

@@ -18,7 +18,7 @@ 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 {
@@ -84,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

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.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>

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"

apps/desktop/src/components/chat/expandable-block.tsx

@@ -0,0 +1,52 @@
+'use client'
+
+import { type ReactNode, useLayoutEffect, useRef, useState } from 'react'
+
+import { ChevronDown } from '@/lib/icons'
+import { cn } from '@/lib/utils'
+
+interface ExpandableBlockProps {
+  children: ReactNode
+  className?: string
+}
+
+export function ExpandableBlock({ children, className }: ExpandableBlockProps) {
+  const innerRef = useRef<HTMLDivElement>(null)
+  const [expanded, setExpanded] = useState(false)
+  const [overflowing, setOverflowing] = useState(false)
+
+  useLayoutEffect(() => {
+    const el = innerRef.current
+
+    if (!el) {return}
+
+    const measure = () => setOverflowing(el.scrollHeight > 121)
+    measure()
+    const observer = new ResizeObserver(measure)
+    observer.observe(el)
+
+    return () => observer.disconnect()
+  }, [])
+
+  return (
+    <div className="relative">
+      <div
+        className={cn('overflow-y-auto', expanded ? 'max-h-[40dvh]' : 'max-h-[7.5rem]', className)}
+        ref={innerRef}
+      >
+        {children}
+      </div>
+      {overflowing && (
+        <button
+          aria-expanded={expanded}
+          aria-label={expanded ? 'Collapse' : 'Expand'}
+          className="absolute inset-x-0 bottom-0 flex h-7 cursor-pointer items-end justify-center bg-linear-to-t from-(--ui-chat-surface-background) to-transparent pb-1 text-muted-foreground/70 transition-colors hover:text-foreground"
+          onClick={() => setExpanded(v => !v)}
+          type="button"
+        >
+          <ChevronDown className={cn('size-3.5 transition-transform', expanded && 'rotate-180')} />
+        </button>
+      )}
+    </div>
+  )
+}

apps/desktop/src/components/chat/shiki-highlighter.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest'
+
+import { chunkByLines, exceedsHighlightBudget } from '@/components/chat/shiki-highlighter'
+
+describe('exceedsHighlightBudget', () => {
+  it('highlights normal-sized blocks', () => {
+    expect(exceedsHighlightBudget('const x = 1\n'.repeat(100))).toBe(false)
+  })
+
+  it('skips highlighting past the line budget', () => {
+    expect(exceedsHighlightBudget('x\n'.repeat(5_000))).toBe(true)
+  })
+
+  it('skips highlighting past the char budget on few lines', () => {
+    expect(exceedsHighlightBudget('a'.repeat(200_000))).toBe(true)
+  })
+
+  it('short-circuits on char budget before line loop', () => {
+    expect(exceedsHighlightBudget('y\n'.repeat(250_000))).toBe(true)
+  })
+})
+
+describe('chunkByLines', () => {
+  it('keeps a small block as a single chunk', () => {
+    const code = 'a\nb\nc'
+    expect(chunkByLines(code, 200)).toEqual([{ text: code, lines: 3 }])
+  })
+
+  it('splits a large block and reconstructs it losslessly', () => {
+    const code = Array.from({ length: 1000 }, (_, i) => `line ${i}`).join('\n')
+    const chunks = chunkByLines(code, 200)
+
+    expect(chunks).toHaveLength(5)
+    expect(chunks.map(chunk => chunk.text).join('\n')).toBe(code)
+    expect(chunks.reduce((sum, chunk) => sum + chunk.lines, 0)).toBe(1000)
+  })
+})

apps/desktop/src/components/chat/shiki-highlighter.tsx

@@ -1,7 +1,7 @@
 'use client'
 
 import type { SyntaxHighlighterProps } from '@assistant-ui/react-streamdown'
-import type { FC } from 'react'
+import { type FC, useMemo } from 'react'
 import ShikiHighlighter from 'react-shiki'
 
 import {
@@ -12,6 +12,7 @@ import {
   CodeCardSubtitle,
   CodeCardTitle
 } from '@/components/chat/code-card'
+import { ExpandableBlock } from '@/components/chat/expandable-block'
 import { CopyButton } from '@/components/ui/copy-button'
 import { useI18n } from '@/i18n'
 import { codiconForLanguage, isLikelyProseCodeBlock, sanitizeLanguageTag } from '@/lib/markdown-code'
@@ -43,6 +44,74 @@ const SHIKI_COLOR_REPLACEMENTS: Record<string, Record<string, string>> = {
   'github-light-default': { '#6e7781': '#57606a' }
 }
 
+const MAX_HIGHLIGHT_CHARS = 150_000
+const MAX_HIGHLIGHT_LINES = 3_000
+const CHUNK_LINES = 200
+const EST_LINE_PX = 16
+
+export function exceedsHighlightBudget(code: string): boolean {
+  if (code.length > MAX_HIGHLIGHT_CHARS) {
+    return true
+  }
+
+  let lines = 1
+  let idx = code.indexOf('\n')
+
+  while (idx !== -1) {
+    if ((lines += 1) > MAX_HIGHLIGHT_LINES) {
+      return true
+    }
+
+    idx = code.indexOf('\n', idx + 1)
+  }
+
+  return false
+}
+
+interface CodeChunk {
+  text: string
+  lines: number
+}
+
+export function chunkByLines(code: string, perChunk: number): CodeChunk[] {
+  const lines = code.split('\n')
+
+  if (lines.length <= perChunk) {
+    return [{ text: code, lines: lines.length }]
+  }
+
+  const chunks: CodeChunk[] = []
+
+  for (let i = 0; i < lines.length; i += perChunk) {
+    const slice = lines.slice(i, i + perChunk)
+    chunks.push({ text: slice.join('\n'), lines: slice.length })
+  }
+
+  return chunks
+}
+
+const PlainCode: FC<{ code: string }> = ({ code }) => {
+  const chunks = useMemo(() => chunkByLines(code, CHUNK_LINES), [code])
+
+  if (chunks.length === 1) {
+    return <code className="block whitespace-pre">{code}</code>
+  }
+
+  return (
+    <>
+      {chunks.map((chunk, index) => (
+        <code
+          className="block whitespace-pre [content-visibility:auto]"
+          key={index}
+          style={{ containIntrinsicSize: `auto ${chunk.lines * EST_LINE_PX}px` }}
+        >
+          {chunk.text}
+        </code>
+      ))}
+    </>
+  )
+}
+
 export const SyntaxHighlighter: FC<HermesSyntaxHighlighterProps> = ({
   components: { Pre },
   language,
@@ -64,6 +133,7 @@ export const SyntaxHighlighter: FC<HermesSyntaxHighlighterProps> = ({
 
   const cleanLanguage = sanitizeLanguageTag(language || '')
   const label = cleanLanguage && cleanLanguage !== 'unknown' ? cleanLanguage : ''
+  const plain = defer || exceedsHighlightBudget(trimmed)
 
   return (
     <CodeCard data-streaming={defer ? 'true' : undefined}>
@@ -83,24 +153,26 @@ export const SyntaxHighlighter: FC<HermesSyntaxHighlighterProps> = ({
         />
       </CodeCardHeader>
       <CodeCardBody>
-        <Pre className="aui-shiki m-0 overflow-hidden bg-transparent p-0">
-          {defer ? (
-            <code className="block whitespace-pre">{trimmed}</code>
-          ) : (
-            <ShikiHighlighter
-              addDefaultStyles={false}
-              as="div"
-              colorReplacements={SHIKI_COLOR_REPLACEMENTS}
-              defaultColor="light-dark()"
-              delay={120}
-              language={language || 'text'}
-              showLanguage={false}
-              theme={SHIKI_THEME}
-            >
-              {trimmed}
-            </ShikiHighlighter>
-          )}
-        </Pre>
+        <ExpandableBlock>
+          <Pre className="aui-shiki m-0 overflow-hidden bg-transparent p-0">
+            {plain ? (
+              <PlainCode code={trimmed} />
+            ) : (
+              <ShikiHighlighter
+                addDefaultStyles={false}
+                as="div"
+                colorReplacements={SHIKI_COLOR_REPLACEMENTS}
+                defaultColor="light-dark()"
+                delay={120}
+                language={language || 'text'}
+                showLanguage={false}
+                theme={SHIKI_THEME}
+              >
+                {trimmed}
+              </ShikiHighlighter>
+            )}
+          </Pre>
+        </ExpandableBlock>
       </CodeCardBody>
     </CodeCard>
   )

apps/desktop/src/components/model-picker.tsx

@@ -2,6 +2,7 @@ import { useQuery } from '@tanstack/react-query'
 import { useState } from 'react'
 
 import { useI18n } from '@/i18n'
+import { currentPickerSelection } from '@/lib/model-status-label'
 import type { ModelOptionProvider, ModelOptionsResponse, ModelPricing } from '@/types/hermes'
 
 import type { HermesGateway } from '../hermes'
@@ -66,8 +67,13 @@ export function ModelPickerDialog({
   })
 
   const providers = modelOptions.data?.providers ?? []
-  const optionsModel = String(modelOptions.data?.model ?? currentModel ?? '')
-  const optionsProvider = String(modelOptions.data?.provider ?? currentProvider ?? '')
+
+  const { model: optionsModel, provider: optionsProvider } = currentPickerSelection(
+    !!sessionId,
+    { model: currentModel, provider: currentProvider },
+    modelOptions.data
+  )
+
   const loading = modelOptions.isPending && !modelOptions.data
 
   const error = modelOptions.error

apps/desktop/src/components/pet/floating-pet.tsx

@@ -1,291 +0,0 @@
-import { useStore } from '@nanostores/react'
-import { useCallback, useEffect, useRef, useState } from 'react'
-
-import { useGatewayRequest } from '@/app/gateway/hooks/use-gateway-request'
-import { persistString, storedString } from '@/lib/storage'
-import { $petInfo, clearPetUnread, type PetInfo, setPetInfo } from '@/store/pet'
-import { $petOverlayActive, initPetOverlayBridge, popOutPet, restorePetOverlay } from '@/store/pet-overlay'
-import { $gatewayState } from '@/store/session'
-import { isSecondaryWindow } from '@/store/windows'
-import { useTheme } from '@/themes/context'
-
-import { PetSprite } from './pet-sprite'
-
-// v2: positions are now top/left anchored (v1 stored bottom-anchored values,
-// which dragged inverted). Bumping the key discards stale v1 coordinates.
-const POSITION_KEY = 'hermes.desktop.pet-position.v2'
-
-interface Point {
-  x: number
-  y: number
-}
-
-function clampToViewport({ x, y }: Point): Point {
-  const maxX = Math.max(0, (window.innerWidth || 800) - 80)
-  const maxY = Math.max(0, (window.innerHeight || 600) - 80)
-
-  return { x: Math.min(Math.max(0, x), maxX), y: Math.min(Math.max(0, y), maxY) }
-}
-
-// The sprite art faces left by default, so mirror it when the pet's center sits
-// on the left half of the window — it always faces inward, toward the content.
-function facing(leftX: number, petW: number): string {
-  return leftX + petW / 2 < (window.innerWidth || 800) / 2 ? 'scaleX(-1)' : 'none'
-}
-
-function loadPosition(): Point {
-  try {
-    const raw = storedString(POSITION_KEY)
-
-    if (raw) {
-      const parsed = JSON.parse(raw) as Point
-
-      if (typeof parsed.x === 'number' && typeof parsed.y === 'number') {
-        return clampToViewport(parsed)
-      }
-    }
-  } catch {
-    // fall through to default
-  }
-
-  // Default: lower-left corner (top/left anchored).
-  return clampToViewport({ x: 24, y: (window.innerHeight || 600) - 220 })
-}
-
-/**
- * In-window floating petdex mascot. Always-on-top within the app, draggable,
- * and reactive to agent activity via `$petState`. Fetches the active pet via
- * the shared `pet.info` RPC; renders nothing until a pet is installed +
- * enabled.
- *
- * Adopting a pet is fully in-app: type `/pet boba` in the composer. That
- * writes `display.pet.*` from the slash worker, so we keep polling `pet.info`
- * while no pet is active and the mascot pops in within a few seconds — no
- * reload, no CLI. Once a pet is live we stop polling.
- *
- * Promotion to a separate frameless OS-level window is a follow-up — the
- * sprite + state logic here is reused as-is, only the host changes.
- */
-const PET_POLL_MS = 3000
-
-export function FloatingPet() {
-  const { requestGateway } = useGatewayRequest()
-  const { resolvedMode } = useTheme()
-  const gatewayState = useStore($gatewayState)
-  const info = useStore($petInfo)
-  const overlayActive = useStore($petOverlayActive)
-
-  const [position, setPosition] = useState<Point>(loadPosition)
-  const containerRef = useRef<HTMLDivElement | null>(null)
-  // The facing mirror lives on the sprite wrapper, not the container, so the
-  // speech bubble (a container child) never renders flipped/backwards.
-  const spriteWrapRef = useRef<HTMLDivElement | null>(null)
-  const petW = (info.frameW ?? 192) * (info.scale ?? 0.33)
-  // Soft contact shadow, sized off the pet so every scale/species grounds the
-  // same way (cf. lairp's per-actor feet ellipse). Lighter on light backgrounds.
-  const shadowW = Math.round(petW * 0.55)
-  const shadowH = Math.max(3, Math.round(shadowW * 0.28))
-  const shadowAlpha = resolvedMode === 'light' ? 0.2 : 0.55
-  // Live drag offset (pointer → element top-left). Drag updates the DOM
-  // directly to avoid a React re-render (and canvas reflow) per pointermove —
-  // state is only committed on release.
-  const dragRef = useRef<{ dx: number; dy: number; x: number; y: number } | null>(null)
-
-  // Fetch pet.info on connect, then keep polling while no pet is active so an
-  // in-app `/pet <slug>` shows up live. Stops polling once a pet is enabled.
-  const active = info.enabled && Boolean(info.spritesheetBase64)
-  useEffect(() => {
-    if (gatewayState !== 'open' || active) {
-      return
-    }
-
-    let cancelled = false
-
-    const pull = async () => {
-      try {
-        const next = await requestGateway<PetInfo>('pet.info')
-
-        if (!cancelled && next) {
-          setPetInfo(next)
-        }
-      } catch {
-        // cosmetic feature — never surface gateway errors
-      }
-    }
-
-    void pull()
-    const timer = window.setInterval(() => void pull(), PET_POLL_MS)
-
-    return () => {
-      cancelled = true
-      window.clearInterval(timer)
-    }
-  }, [gatewayState, active, requestGateway])
-
-  // Wire the overlay control channel once, only in the primary window — the
-  // pop-out overlay belongs to it (main.cjs positions it against the main
-  // window and routes control messages back to it).
-  useEffect(() => {
-    if (isSecondaryWindow()) {
-      return
-    }
-
-    return initPetOverlayBridge()
-  }, [])
-
-  // Returning to the app (by any route, not just the mail icon) clears the pet's
-  // "new message" hint — you've seen it now.
-  useEffect(() => {
-    if (isSecondaryWindow()) {
-      return
-    }
-
-    const onFocus = () => clearPetUnread()
-    window.addEventListener('focus', onFocus)
-
-    return () => window.removeEventListener('focus', onFocus)
-  }, [])
-
-  // Restore a popped-out pet on boot, once the pet has loaded (so we never spawn
-  // an empty overlay window). Primary window only; runs at most once.
-  const restoredRef = useRef(false)
-  useEffect(() => {
-    if (isSecondaryWindow() || restoredRef.current || !active) {
-      return
-    }
-
-    restoredRef.current = true
-    restorePetOverlay()
-  }, [active])
-
-  // A window resize must never strand the pet off-screen — re-clamp the
-  // committed position (and persist it) whenever the viewport shrinks.
-  useEffect(() => {
-    const onResize = () =>
-      setPosition(prev => {
-        const next = clampToViewport(prev)
-
-        if (next.x === prev.x && next.y === prev.y) {
-          return prev
-        }
-
-        persistString(POSITION_KEY, JSON.stringify(next))
-
-        return next
-      })
-
-    window.addEventListener('resize', onResize)
-
-    return () => window.removeEventListener('resize', onResize)
-  }, [])
-
-  const onPointerDown = useCallback((e: React.PointerEvent) => {
-    const el = containerRef.current
-
-    if (!el) {
-      return
-    }
-
-    const rect = el.getBoundingClientRect()
-
-    // Shift-click pops the pet out into a free-floating desktop overlay (it can
-    // leave the window and stays visible while Hermes is minimized) instead of
-    // starting an in-window drag. Primary window only — the overlay is anchored
-    // to it.
-    if (e.shiftKey && !isSecondaryWindow()) {
-      popOutPet({ height: rect.height, width: rect.width, x: rect.left, y: rect.top })
-
-      return
-    }
-
-    dragRef.current = { dx: e.clientX - rect.left, dy: e.clientY - rect.top, x: rect.left, y: rect.top }
-    el.setPointerCapture(e.pointerId)
-    el.style.cursor = 'grabbing'
-  }, [])
-
-  const onPointerMove = useCallback(
-    (e: React.PointerEvent) => {
-      const drag = dragRef.current
-      const el = containerRef.current
-
-      if (!drag || !el) {
-        return
-      }
-
-      const next = clampToViewport({ x: e.clientX - drag.dx, y: e.clientY - drag.dy })
-      drag.x = next.x
-      drag.y = next.y
-      // Mutate the DOM directly — no setState, so no re-render while dragging. The
-      // mirror follows the pointer across the midline for the same reason; it
-      // rides the sprite wrapper so the bubble stays upright.
-      el.style.left = `${next.x}px`
-      el.style.top = `${next.y}px`
-
-      if (spriteWrapRef.current) {
-        spriteWrapRef.current.style.transform = facing(next.x, petW)
-      }
-    },
-    [petW]
-  )
-
-  const onPointerUp = useCallback((e: React.PointerEvent) => {
-    const drag = dragRef.current
-
-    if (drag) {
-      dragRef.current = null
-      const committed = { x: drag.x, y: drag.y }
-      setPosition(committed)
-      persistString(POSITION_KEY, JSON.stringify(committed))
-    }
-
-    const el = containerRef.current
-
-    if (el) {
-      el.style.cursor = 'grab'
-      el.releasePointerCapture?.(e.pointerId)
-    }
-  }, [])
-
-  // While popped out, the desktop overlay window owns the mascot — hide the
-  // in-window one so there aren't two.
-  if (!info.enabled || !info.spritesheetBase64 || overlayActive) {
-    return null
-  }
-
-  return (
-    <div
-      onPointerDown={onPointerDown}
-      onPointerMove={onPointerMove}
-      onPointerUp={onPointerUp}
-      ref={containerRef}
-      style={{
-        cursor: 'grab',
-        left: position.x,
-        pointerEvents: 'auto',
-        position: 'fixed',
-        top: position.y,
-        touchAction: 'none',
-        userSelect: 'none',
-        zIndex: 60
-      }}
-    >
-      <div
-        aria-hidden
-        style={{
-          background: `radial-gradient(ellipse at center, rgba(0,0,0,${shadowAlpha}) 0%, rgba(0,0,0,0) 70%)`,
-          bottom: -shadowH * 0.4,
-          height: shadowH,
-          left: '50%',
-          pointerEvents: 'none',
-          position: 'absolute',
-          transform: 'translateX(-50%)',
-          width: shadowW,
-          zIndex: 0
-        }}
-      />
-      <div ref={spriteWrapRef} style={{ lineHeight: 0, position: 'relative', transform: facing(position.x, petW), zIndex: 1 }}>
-        <PetSprite info={info} />
-      </div>
-    </div>
-  )
-}

apps/desktop/src/components/pet/pet-bubble.tsx

@@ -1,142 +0,0 @@
-import { useStore } from '@nanostores/react'
-import { useEffect, useState } from 'react'
-
-import { AlertCircle, Clock, type IconComponent } from '@/lib/icons'
-import { $petActivity, $petState, type PetState } from '@/store/pet'
-
-/**
- * Speech bubble + status glyph for the popped-out pet overlay — the
- * "notification" half of the mascot. It externalizes what the agent is doing
- * (Codex-style) so a glance at the desktop pet replaces switching back to the
- * window. The in-window pet doesn't show it (the app itself is the surface);
- * only the overlay renders it.
- *
- * Text is derived purely from the same `$petState` / `$petActivity` the sprite
- * already reacts to, so it never drifts from the animation. The bubble is shown
- * only when there's something worth saying (working / reviewing / a transient
- * done/error beat / waiting on the user) and is hidden at plain idle.
- */
-
-type Tone = 'error' | 'wait'
-
-interface Spec {
-  lines: string[]
-  glyph?: IconComponent
-  tone?: Tone
-}
-
-// Phrasings per mood, picked at random (no immediate repeat) for a bit of life.
-// Keep them short — the bubble is tiny and never wraps.
-const SPECS: Partial<Record<PetState, Spec>> = {
-  run: {
-    lines: ['working…', 'on it…', 'crunching…', 'tinkering…', 'cooking…', 'in the weeds…', 'wiring it up…', 'making moves…', 'heads down…', 'hammering away…']
-  },
-  review: {
-    lines: ['thinking…', 'reading…', 'reviewing…', 'pondering…', 'connecting dots…', 'sizing it up…', 'tracing it…', 'mulling…', 'scheming…', 'hmm…']
-  },
-  failed: {
-    glyph: AlertCircle,
-    lines: ['hit a snag', 'welp', 'that broke', 'oof', 'snagged'],
-    tone: 'error'
-  },
-  waiting: {
-    glyph: Clock,
-    lines: ['your turn', 'all yours', 'over to you', 'ball’s in your court', 'awaiting orders'],
-    tone: 'wait'
-  }
-}
-
-const TONE_COLOR: Record<Tone, string> = {
-  error: 'var(--ui-red)',
-  wait: 'var(--ui-yellow)'
-}
-
-// Random pick that avoids repeating the line we're already showing.
-function pick(lines: string[], prev: string): string {
-  if (lines.length <= 1) {
-    return lines[0] ?? ''
-  }
-
-  let next = prev
-
-  while (next === prev) {
-    next = lines[Math.floor(Math.random() * lines.length)]
-  }
-
-  return next
-}
-
-export function PetBubble() {
-  const state = useStore($petState)
-  const activity = useStore($petActivity)
-  const [line, setLine] = useState('')
-
-  // Finish beats are carried by the sprite/mail icon; idle only speaks up when
-  // it's actually the user's turn. Everything else maps to a mood spec.
-  const specKey: null | PetState =
-    state in SPECS ? state : state === 'idle' && activity.awaitingInput ? 'waiting' : null
-  const rotating = specKey === 'run' || specKey === 'review'
-
-  // Pick a fresh line on every mood change, then keep rotating (random, no
-  // repeat) only while the agent is actively working/thinking.
-  useEffect(() => {
-    const spec = specKey ? SPECS[specKey] : null
-
-    if (!spec) {
-      setLine('')
-
-      return
-    }
-
-    setLine(prev => pick(spec.lines, prev))
-
-    if (!rotating || spec.lines.length <= 1) {
-      return
-    }
-
-    const id = window.setInterval(() => setLine(prev => pick(spec.lines, prev)), 2600)
-
-    return () => window.clearInterval(id)
-  }, [specKey, rotating])
-
-  const spec = specKey ? SPECS[specKey] : null
-
-  if (!spec) {
-    return null
-  }
-
-  const Glyph = spec.glyph
-  const text = line || spec.lines[0]
-  const hasText = Boolean(text)
-
-  return (
-    <div
-      style={{
-        alignItems: 'center',
-        // Solid, theme-driven surface (the prior --ui-bg-card mixes in
-        // `transparent`, so the bubble was see-through).
-        background: 'var(--ui-bg-elevated)',
-        border: '1px solid var(--ui-stroke-secondary)',
-        borderRadius: hasText ? 10 : 999,
-        boxShadow: '0 4px 14px rgba(0,0,0,0.22)',
-        color: 'var(--foreground)',
-        display: 'inline-flex',
-        fontSize: 11,
-        fontWeight: 500,
-        gap: hasText ? 5 : 0,
-        lineHeight: 1,
-        // Glyph-only bubbles collapse to a tight, symmetric badge.
-        padding: hasText ? '5px 8px' : 5,
-        pointerEvents: 'none',
-        whiteSpace: 'nowrap'
-      }}
-    >
-      {Glyph && (
-        <span style={{ display: 'inline-flex' }}>
-          <Glyph style={{ color: spec.tone ? TONE_COLOR[spec.tone] : 'currentColor', height: 13, width: 13 }} />
-        </span>
-      )}
-      {text}
-    </div>
-  )
-}

apps/desktop/src/components/pet/pet-sprite.tsx

@@ -1,221 +0,0 @@
-import { memo, useEffect, useMemo, useRef } from 'react'
-
-import { $petState, type PetInfo, type PetState } from '@/store/pet'
-
-const DEFAULT_FRAME_W = 192
-const DEFAULT_FRAME_H = 208
-const DEFAULT_FRAMES = 6
-const DEFAULT_LOOP_MS = 1100
-// Mirrors agent.pet.constants.DEFAULT_SCALE — fallback only; the gateway sends
-// the configured scale.
-const DEFAULT_SCALE = 0.33
-// Mirrors agent.pet.constants.CODEX_STATE_ROWS (Petdex current taxonomy).
-const DEFAULT_STATE_ROWS = [
-  'idle',
-  'running-right',
-  'running-left',
-  'waving',
-  'jumping',
-  'failed',
-  'waiting',
-  'running',
-  'review'
-]
-
-const STATE_ALIASES: Record<PetState, string[]> = {
-  idle: ['idle'],
-  wave: ['wave', 'waving'],
-  jump: ['jump', 'jumping'],
-  run: ['run', 'running'],
-  failed: ['failed'],
-  review: ['review'],
-  waiting: ['waiting']
-}
-
-const ROW_TO_STATE: Record<string, PetState> = {
-  idle: 'idle',
-  wave: 'wave',
-  waving: 'wave',
-  jump: 'jump',
-  jumping: 'jump',
-  run: 'run',
-  running: 'run',
-  'running-right': 'run',
-  'running-left': 'run',
-  failed: 'failed',
-  review: 'review',
-  waiting: 'waiting'
-}
-
-interface PetSpriteProps {
-  info: PetInfo
-  /** On-screen scale multiplier applied on top of the pet's native scale. */
-  zoom?: number
-  /**
-   * Force a specific animation state instead of reading the live `$petState`.
-   * Used by the generate-flow preview to showcase every row without driving (or
-   * being driven by) the real agent activity that moves the floating mascot.
-   */
-  stateOverride?: PetState
-  /** Force a concrete row name from `info.stateRows` (e.g. `running-right`). */
-  rowOverride?: string
-}
-
-/**
- * Canvas renderer for a petdex spritesheet — the one piece that must be
- * TypeScript (the engine's decode/encode is Python). Draws the row matching the
- * live `$petState`, stepping `framesPerState` frames across a `loopMs` loop.
- *
- * State is read from `$petState` via a ref + subscription rather than a prop,
- * so the frequent activity-driven state changes during an agent turn update the
- * canvas (inside its RAF loop) WITHOUT triggering a React re-render. Combined
- * with `memo`, this component effectively never re-renders after mount until
- * the pet itself changes.
- */
-function PetSpriteImpl({ info, zoom = 1, stateOverride, rowOverride }: PetSpriteProps) {
-  const canvasRef = useRef<HTMLCanvasElement | null>(null)
-  const stateRef = useRef<PetState>($petState.get())
-  const overrideRef = useRef<PetState | undefined>(stateOverride)
-  const rowOverrideRef = useRef<string | undefined>(rowOverride)
-
-  // Keep the override current without re-running the RAF setup effect.
-  useEffect(() => {
-    overrideRef.current = stateOverride
-  }, [stateOverride])
-
-  useEffect(() => {
-    rowOverrideRef.current = rowOverride
-  }, [rowOverride])
-
-  const frameW = info.frameW ?? DEFAULT_FRAME_W
-  const frameH = info.frameH ?? DEFAULT_FRAME_H
-  const frames = info.framesPerState ?? DEFAULT_FRAMES
-  const framesByState = info.framesByState
-  const loopMs = info.loopMs ?? DEFAULT_LOOP_MS
-  const scale = (info.scale ?? DEFAULT_SCALE) * zoom
-  const rows = info.stateRows ?? DEFAULT_STATE_ROWS
-
-  const drawW = Math.round(frameW * scale)
-  const drawH = Math.round(frameH * scale)
-
-  const image = useMemo(() => {
-    if (!info.spritesheetBase64) {
-      return null
-    }
-
-    const img = new Image()
-    img.src = `data:${info.mime ?? 'image/webp'};base64,${info.spritesheetBase64}`
-
-    return img
-  }, [info.spritesheetBase64, info.mime])
-
-  useEffect(() => {
-    const canvas = canvasRef.current
-
-    if (!canvas || !image) {
-      return
-    }
-
-    const ctx = canvas.getContext('2d')
-
-    if (!ctx) {
-      return
-    }
-
-    // Track state via subscription, not a prop — no re-render on activity ticks.
-    stateRef.current = $petState.get()
-
-    const unsubState = $petState.listen(next => {
-      stateRef.current = next
-    })
-
-    let raf = 0
-    let frame = 0
-    let lastStep = performance.now()
-    let drawnFrame = -1
-    let drawnRow = -1
-
-    const rowIndexForState = (s: PetState): number => {
-      for (const key of STATE_ALIASES[s] ?? [s]) {
-        const idx = rows.indexOf(key)
-        if (idx >= 0) {
-          return idx
-        }
-      }
-      return 0
-    }
-
-    // Resolve a state to the row it draws and its real frame count. A state
-    // with no real frames (ragged sheet, empty row) falls back to idle rather
-    // than flashing blank padding.
-    const resolve = (s: PetState): { row: number; count: number } => {
-      const real = framesByState?.[s] ?? frames
-
-      if (real > 0) {
-        return { row: rowIndexForState(s), count: real }
-      }
-
-      return { row: rowIndexForState('idle'), count: Math.max(1, framesByState?.idle ?? frames) }
-    }
-
-    const resolveRow = (rowName: string): { row: number; count: number } => {
-      const row = rows.indexOf(rowName)
-      const state = ROW_TO_STATE[rowName]
-      const count = Math.max(1, framesByState?.[rowName] ?? (state ? framesByState?.[state] : 0) ?? frames)
-      return { row: row >= 0 ? row : rowIndexForState(state ?? 'idle'), count }
-    }
-
-    const render = (now: number) => {
-      const forcedRow = rowOverrideRef.current
-      const { row, count } = forcedRow ? resolveRow(forcedRow) : resolve(overrideRef.current ?? stateRef.current)
-      // Per-state step keeps every state's loop ~loopMs even when frame counts
-      // differ; counts vary per row so derive the cadence here, not once.
-      const stepMs = loopMs / count
-
-      if (now - lastStep >= stepMs) {
-        frame += 1
-        lastStep = now
-      }
-
-      frame %= count
-
-      // Only touch the canvas when the visible cell actually changes. The RAF
-      // ticks at ~60Hz but the sprite only steps ~5Hz, so this skips ~90% of
-      // the clear+draw work and keeps the main thread free.
-      if ((frame !== drawnFrame || row !== drawnRow) && image.complete && image.naturalWidth > 0) {
-        const sx = frame * frameW
-        const sy = row * frameH
-        ctx.clearRect(0, 0, canvas.width, canvas.height)
-        ctx.imageSmoothingEnabled = false
-        ctx.drawImage(image, sx, sy, frameW, frameH, 0, 0, drawW, drawH)
-        drawnFrame = frame
-        drawnRow = row
-      }
-
-      raf = requestAnimationFrame(render)
-    }
-
-    raf = requestAnimationFrame(render)
-
-    return () => {
-      cancelAnimationFrame(raf)
-      unsubState()
-    }
-  }, [image, frameW, frameH, frames, framesByState, loopMs, drawW, drawH, rows])
-
-  return (
-    <canvas
-      aria-label={info.displayName ? `${info.displayName} pet` : 'pet'}
-      height={drawH}
-      ref={canvasRef}
-      style={{ height: drawH, width: drawW }}
-      width={drawW}
-    />
-  )
-}
-
-/**
- * Memoized so a parent re-render (e.g. a position commit on drag-end) doesn't
- * re-run the canvas setup. Props change only when the pet itself changes.
- */
-export const PetSprite = memo(PetSpriteImpl)

apps/desktop/src/components/pet/pet-thumb.tsx

@@ -1,79 +0,0 @@
-import { useEffect, useRef, useState } from 'react'
-
-import { PawPrint } from '@/lib/icons'
-
-// petdex frames are a fixed 192×208 grid; the box matches that aspect.
-const THUMB_W = 40
-const THUMB_H = Math.round((THUMB_W * 208) / 192)
-
-export type PetThumbLoader = (slug: string, url?: string) => Promise<string | null>
-
-/**
- * Idle-frame preview for one pet. The backend crops + caches the frame and
- * returns it as a same-origin data URI (`pet.thumb`), which dodges the renderer
- * CSP / R2 hotlink rules that break a direct `<img src=cdn>`.
- */
-export function PetThumb({
-  slug,
-  url,
-  alt,
-  load,
-  size = THUMB_W
-}: {
-  slug: string
-  url?: string
-  alt: string
-  load: PetThumbLoader
-  /** Width in px; height follows the petdex frame aspect. */
-  size?: number
-}) {
-  const [src, setSrc] = useState<string | null>(null)
-  const boxRef = useRef<HTMLSpanElement | null>(null)
-  const height = Math.round((size * 208) / 192)
-
-  useEffect(() => {
-    const el = boxRef.current
-
-    if (!el || src) {
-      return
-    }
-
-    const observer = new IntersectionObserver(
-      entries => {
-        if (entries.some(entry => entry.isIntersecting)) {
-          observer.disconnect()
-          void load(slug, url).then(uri => {
-            if (uri) {
-              setSrc(uri)
-            }
-          })
-        }
-      },
-      { rootMargin: '120px' }
-    )
-
-    observer.observe(el)
-
-    return () => observer.disconnect()
-  }, [slug, url, src, load])
-
-  return (
-    <span
-      className="grid shrink-0 place-items-center overflow-hidden rounded-md bg-(--ui-bg-tertiary) text-(--ui-text-tertiary)"
-      ref={boxRef}
-      style={{ height, width: size }}
-    >
-      {src ? (
-        <img
-          alt={alt}
-          aria-hidden
-          className="pointer-events-none size-full object-contain"
-          src={src}
-          style={{ imageRendering: 'pixelated' }}
-        />
-      ) : (
-        <PawPrint className="size-4" />
-      )}
-    </span>
-  )
-}

apps/desktop/src/components/ui/command.tsx

@@ -17,12 +17,7 @@ function Command({ className, ...props }: React.ComponentProps<typeof CommandPri
   )
 }
 
-interface CommandInputProps extends React.ComponentProps<typeof CommandPrimitive.Input> {
-  /** Inline trailing slot, rendered on the right of the search row. */
-  right?: React.ReactNode
-}
-
-function CommandInput({ className, right, ...props }: CommandInputProps) {
+function CommandInput({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Input>) {
   return (
     <div className="flex h-11 items-center gap-2 border-b border-border px-3" data-slot="command-input-wrapper">
       <SearchIcon className="size-4 shrink-0 text-muted-foreground" />
@@ -34,7 +29,6 @@ function CommandInput({ className, right, ...props }: CommandInputProps) {
         data-slot="command-input"
         {...props}
       />
-      {right}
     </div>
   )
 }

apps/desktop/src/global.d.ts

@@ -1,10 +1,3 @@
-import type {
-  PetOverlayBounds,
-  PetOverlayControl,
-  PetOverlayOpenRequest,
-  PetOverlayStatePayload
-} from './store/pet-overlay'
-
 export {}
 
 declare global {
@@ -33,20 +26,6 @@ declare global {
       openSessionWindow: (sessionId: string, opts?: { watch?: boolean }) => Promise<{ ok: boolean; error?: string }>
       // Open (or focus) a compact secondary window on the new-session draft.
       openNewSessionWindow: () => Promise<{ ok: boolean; error?: string }>
-      // The pop-out pet overlay: a transparent always-on-top window hosting only
-      // the mascot. The main renderer drives it (open/close/drag + state push);
-      // the overlay sends control messages back (pop-in, composer submit).
-      petOverlay: {
-        open: (request: PetOverlayOpenRequest) => Promise<{ ok: boolean; bounds?: PetOverlayBounds }>
-        close: () => Promise<{ ok: boolean }>
-        setBounds: (bounds: PetOverlayBounds) => void
-        setIgnoreMouse: (ignore: boolean) => void
-        setFocusable: (focusable: boolean) => void
-        pushState: (payload: PetOverlayStatePayload) => void
-        control: (payload: PetOverlayControl) => void
-        onState: (callback: (payload: PetOverlayStatePayload) => void) => () => void
-        onControl: (callback: (payload: PetOverlayControl) => void) => () => void
-      }
       getBootProgress: () => Promise<DesktopBootProgress>
       getConnectionConfig: (profile?: null | string) => Promise<DesktopConnectionConfig>
       saveConnectionConfig: (payload: DesktopConnectionConfigInput) => Promise<DesktopConnectionConfig>

apps/desktop/src/i18n/en.ts

@@ -366,32 +366,7 @@ export const en: Translations = {
       installError: 'Could not install that theme.',
       installed: name => `Installed “${name}”.`,
       removeTheme: 'Remove theme',
-      importedBadge: 'Imported',
-      pet: {
-        title: 'Pet',
-        intro:
-          'Adopt an animated petdex mascot that floats over the app and reacts to what Hermes is doing — running while tools execute, celebrating on success, sulking on errors.',
-        restartHint:
-          'Pets need a quick restart — the running app started before this feature was added. Quit and reopen Hermes, then come back here.',
-        on: 'On',
-        off: 'Off',
-        scaleTitle: 'Size',
-        scaleDesc: 'Resize the floating mascot. Applies everywhere instantly.',
-        chooseTitle: 'Choose a pet',
-        chooseDesc: 'Picking one installs it (if needed) and makes it active.',
-        searchPlaceholder: 'Search pets…',
-        unreachable: "Couldn't reach the petdex gallery. Check your connection and reopen this page.",
-        noMatch: query => `No pets match "${query}".`,
-        installedTag: 'installed',
-        countCapped: (cap, total) => `Showing ${cap} of ${total} — type to narrow it down.`,
-        count: n => `${n} pet${n === 1 ? '' : 's'}.`,
-        uninstall: name => `Uninstall ${name}`,
-        adoptFailed: slug => `Could not adopt ${slug}`,
-        uninstallFailed: slug => `Could not uninstall ${slug}`,
-        noneAvailable: 'No pets available to turn on right now.',
-        turnOnFailed: 'Could not turn the pet on.',
-        turnOffFailed: 'Could not turn the pet off.'
-      }
+      importedBadge: 'Imported'
     },
     fieldLabels: FIELD_LABELS,
     fieldDescriptions: FIELD_DESCRIPTIONS,
@@ -563,6 +538,10 @@ export const en: Translations = {
       provider: 'Provider',
       model: 'Model',
       applying: 'Applying...',
+      defaultsLabel: 'Defaults',
+      reasoning: 'Reasoning',
+      reasoningOff: 'Off',
+      defaultsFailed: 'Failed to save model defaults',
       auxiliaryTitle: 'Auxiliary models',
       resetAllToMain: 'Reset all to main',
       auxiliaryDesc: 'Helper tasks run on the main model by default. Assign a dedicated model to any task to override.',
@@ -735,37 +714,8 @@ export const en: Translations = {
     commandCenter: 'Command Center',
     appearance: 'Appearance',
     settings: 'Settings',
-    changeTheme: 'Change theme',
+    changeTheme: 'Change theme...',
     changeColorMode: 'Change color mode...',
-    pets: {
-      title: 'Pets',
-      placeholder: 'Search pets…',
-      loading: 'Loading petdex gallery…',
-      error: 'Could not reach the petdex gallery.',
-      staleBackend: 'Restart Hermes to use pets — the backend predates this feature.',
-      empty: 'No matching pets.',
-      turnOff: 'Turn off',
-      turnOn: 'Turn on',
-      installed: 'Installed',
-      adoptFailed: 'Could not adopt that pet.',
-      toggleFailed: 'Could not toggle the pet.',
-      noneAvailable: 'No pets available — pick one below to install.'
-    },
-    generatePet: {
-      title: 'Generate a pet',
-      placeholder: 'Describe a pet to generate…',
-      promptHint: 'Type a description, then press Enter to draft four looks.',
-      readyHint: 'Press Enter to draft four looks from your description.',
-      generate: 'Generate',
-      generating: 'Generating…',
-      retry: 'Retry',
-      hatch: 'Hatch',
-      hatching: 'Hatching your pet…',
-      namePlaceholder: 'Name your pet',
-      staleBackend: 'Update Hermes to generate pets.',
-      adopt: 'Adopt',
-      startOver: 'Start over'
-    },
     installTheme: {
       title: 'Install theme...',
       placeholder: 'Search the VS Code Marketplace...',
@@ -1783,6 +1733,7 @@ export const en: Translations = {
       refresh: 'Refresh',
       moreActions: 'More actions',
       branchNewChat: 'Branch in new chat',
+      dismissError: 'Dismiss error',
       readAloudFailed: 'Read aloud failed',
       preparingAudio: 'Preparing audio...',
       stopReading: 'Stop reading',
@@ -1892,6 +1843,9 @@ export const en: Translations = {
     regenerateFailed: 'Regenerate failed',
     editFailed: 'Edit failed',
     resumeFailed: 'Resume failed',
+    resumeStrandedTitle: "Couldn't load this session",
+    resumeStrandedBody: 'The connection to this session failed and automatic retries gave up. Check that the gateway is running, then try again.',
+    resumeRetry: 'Retry',
     nothingToBranch: 'Nothing to branch',
     branchNeedsChat: 'Start or resume a chat before branching.',
     sessionBusy: 'Session busy',

apps/desktop/src/i18n/ja.ts

@@ -281,32 +281,7 @@ export const ja = defineLocale({
       installError: 'そのテーマをインストールできませんでした。',
       installed: name => `「${name}」をインストールしました。`,
       removeTheme: 'テーマを削除',
-      importedBadge: 'インポート済み',
-      pet: {
-        title: 'ペット',
-        intro:
-          'アプリ上に浮かぶ petdex のアニメーションマスコットを採用しましょう。ツール実行中は走り、成功すると喜び、エラーでしょんぼりと、Hermes の状態に反応します。',
-        restartHint:
-          'ペット機能には再起動が必要です。この機能が追加される前に起動したアプリが動作中です。Hermes を終了して再度開き、このページに戻ってください。',
-        scaleTitle: 'サイズ',
-        scaleDesc: '浮遊マスコットの大きさを変更します。すべての画面に即時反映されます。',
-        on: 'オン',
-        off: 'オフ',
-        chooseTitle: 'ペットを選ぶ',
-        chooseDesc: '選ぶと（必要に応じて）インストールされ、アクティブになります。',
-        searchPlaceholder: 'ペットを検索…',
-        unreachable: 'petdex ギャラリーに接続できませんでした。接続を確認してこのページを開き直してください。',
-        noMatch: query => `「${query}」に一致するペットがありません。`,
-        installedTag: 'インストール済み',
-        countCapped: (cap, total) => `${total} 件中 ${cap} 件を表示中——入力して絞り込めます。`,
-        count: n => `${n} 件のペット。`,
-        uninstall: name => `${name} をアンインストール`,
-        adoptFailed: slug => `${slug} を採用できませんでした`,
-        uninstallFailed: slug => `${slug} をアンインストールできませんでした`,
-        noneAvailable: 'オンにできるペットがありません。',
-        turnOnFailed: 'ペットをオンにできませんでした。',
-        turnOffFailed: 'ペットをオフにできませんでした。'
-      }
+      importedBadge: 'インポート済み'
     },
     fieldLabels: defineFieldCopy({
       model: 'デフォルトモデル',
@@ -859,37 +834,8 @@ export const ja = defineLocale({
     commandCenter: 'コマンドセンター',
     appearance: '外観',
     settings: '設定',
-    changeTheme: 'テーマを変更',
+    changeTheme: 'テーマを変更...',
     changeColorMode: 'カラーモードを変更...',
-    pets: {
-      title: 'ペット',
-      placeholder: 'ペットを検索…',
-      loading: 'petdex ギャラリーを読み込み中…',
-      error: 'petdex ギャラリーに接続できません。',
-      staleBackend: 'ペット機能を使うには Hermes を再起動してください。',
-      empty: '一致するペットがありません。',
-      turnOff: 'オフ',
-      turnOn: 'オン',
-      installed: 'インストール済み',
-      adoptFailed: 'ペットを採用できませんでした。',
-      toggleFailed: 'ペットを切り替えできませんでした。',
-      noneAvailable: '利用可能なペットがありません。'
-    },
-    generatePet: {
-      title: 'ペットを生成',
-      placeholder: '生成するペットを説明…',
-      promptHint: '説明を入力して Enter を押すと、4 つの見た目を生成します。',
-      readyHint: 'Enter を押すと、説明から 4 つの見た目を生成します。',
-      generate: '生成',
-      generating: '生成中…',
-      retry: '再試行',
-      hatch: '孵化',
-      hatching: 'ペットを孵化しています…',
-      namePlaceholder: 'ペットに名前を付ける',
-      staleBackend: 'ペットを生成するには Hermes を更新してください。',
-      adopt: '迎え入れる',
-      startOver: 'やり直す'
-    },
     installTheme: {
       title: 'テーマをインストール...',
       placeholder: 'VS Code Marketplace を検索...',
@@ -1918,6 +1864,7 @@ export const ja = defineLocale({
       refresh: '更新',
       moreActions: 'その他のアクション',
       branchNewChat: '新しいチャットでブランチ',
+      dismissError: 'エラーを閉じる',
       readAloudFailed: '読み上げに失敗しました',
       preparingAudio: '音声を準備中...',
       stopReading: '読み上げを停止',
@@ -2027,6 +1974,9 @@ export const ja = defineLocale({
     regenerateFailed: '再生成に失敗しました',
     editFailed: '編集に失敗しました',
     resumeFailed: '再開に失敗しました',
+    resumeStrandedTitle: 'このセッションを読み込めませんでした',
+    resumeStrandedBody: 'このセッションへの接続に失敗し、自動再試行も停止しました。ゲートウェイが実行中か確認してから、もう一度お試しください。',
+    resumeRetry: '再試行',
     nothingToBranch: 'ブランチするものがありません',
     branchNeedsChat: 'ブランチする前にチャットを開始または再開してください。',
     sessionBusy: 'セッションが使用中',

apps/desktop/src/i18n/types.ts

@@ -265,29 +265,6 @@ export interface Translations {
       installed: (name: string) => string
       removeTheme: string
       importedBadge: string
-      pet: {
-        title: string
-        intro: string
-        restartHint: string
-        on: string
-        off: string
-        scaleTitle: string
-        scaleDesc: string
-        chooseTitle: string
-        chooseDesc: string
-        searchPlaceholder: string
-        unreachable: string
-        noMatch: (query: string) => string
-        installedTag: string
-        countCapped: (cap: number, total: number) => string
-        count: (n: number) => string
-        uninstall: (name: string) => string
-        adoptFailed: (slug: string) => string
-        uninstallFailed: (slug: string) => string
-        noneAvailable: string
-        turnOnFailed: string
-        turnOffFailed: string
-      }
     }
     fieldLabels: Record<string, string>
     fieldDescriptions: Record<string, string>
@@ -453,6 +430,10 @@ export interface Translations {
       provider: string
       model: string
       applying: string
+      defaultsLabel: string
+      reasoning: string
+      reasoningOff: string
+      defaultsFailed: string
       auxiliaryTitle: string
       resetAllToMain: string
       auxiliaryDesc: string
@@ -613,35 +594,6 @@ export interface Translations {
     settings: string
     changeTheme: string
     changeColorMode: string
-    pets: {
-      title: string
-      placeholder: string
-      loading: string
-      error: string
-      staleBackend: string
-      empty: string
-      turnOff: string
-      turnOn: string
-      installed: string
-      adoptFailed: string
-      toggleFailed: string
-      noneAvailable: string
-    }
-    generatePet: {
-      title: string
-      placeholder: string
-      promptHint: string
-      readyHint: string
-      generate: string
-      generating: string
-      retry: string
-      hatch: string
-      hatching: string
-      namePlaceholder: string
-      staleBackend: string
-      adopt: string
-      startOver: string
-    }
     installTheme: {
       title: string
       placeholder: string
@@ -1421,6 +1373,7 @@ export interface Translations {
       refresh: string
       moreActions: string
       branchNewChat: string
+      dismissError: string
       readAloudFailed: string
       preparingAudio: string
       stopReading: string
@@ -1528,6 +1481,9 @@ export interface Translations {
     regenerateFailed: string
     editFailed: string
     resumeFailed: string
+    resumeStrandedTitle: string
+    resumeStrandedBody: string
+    resumeRetry: string
     nothingToBranch: string
     branchNeedsChat: string
     sessionBusy: string

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

@@ -271,30 +271,7 @@ export const zhHant = defineLocale({
       installError: '無法安裝該主題。',
       installed: name => `已安裝「${name}」。`,
       removeTheme: '移除主題',
-      importedBadge: '已匯入',
-      pet: {
-        title: '寵物',
-        intro: '領養一隻懸浮在應用上的 petdex 動畫寵物，它會根據 Hermes 的狀態做出反應——工具執行時奔跑、成功時歡呼、出錯時沮喪。',
-        restartHint: '寵物功能需要重新啟動——目前執行的應用在此功能加入前啟動。請結束並重新開啟 Hermes，然後回到此處。',
-        scaleTitle: '大小',
-        scaleDesc: '調整懸浮寵物的大小，所有介面即時生效。',
-        on: '開啟',
-        off: '關閉',
-        chooseTitle: '選擇寵物',
-        chooseDesc: '選擇後會自動安裝（如需）並設為目前寵物。',
-        searchPlaceholder: '搜尋寵物…',
-        unreachable: '無法連線至 petdex 畫廊。請檢查網路連線並重新開啟此頁面。',
-        noMatch: query => `沒有符合「${query}」的寵物。`,
-        installedTag: '已安裝',
-        countCapped: (cap, total) => `顯示 ${total} 個中的 ${cap} 個——輸入關鍵字以縮小範圍。`,
-        count: n => `${n} 個寵物。`,
-        uninstall: name => `解除安裝 ${name}`,
-        adoptFailed: slug => `無法領養 ${slug}`,
-        uninstallFailed: slug => `無法解除安裝 ${slug}`,
-        noneAvailable: '目前沒有可開啟的寵物。',
-        turnOnFailed: '無法開啟寵物。',
-        turnOffFailed: '無法關閉寵物。'
-      }
+      importedBadge: '已匯入'
     },
     fieldLabels: defineFieldCopy({
       model: '預設模型',
@@ -830,37 +807,8 @@ export const zhHant = defineLocale({
     commandCenter: '命令中心',
     appearance: '外觀',
     settings: '設定',
-    changeTheme: '變更主題',
+    changeTheme: '變更主題...',
     changeColorMode: '變更色彩模式...',
-    pets: {
-      title: '寵物',
-      placeholder: '搜尋寵物…',
-      loading: '正在載入 petdex 畫廊…',
-      error: '無法連線至 petdex 畫廊。',
-      staleBackend: '請重新啟動 Hermes 以使用寵物功能。',
-      empty: '沒有符合的寵物。',
-      turnOff: '關閉',
-      turnOn: '開啟',
-      installed: '已安裝',
-      adoptFailed: '無法領養該寵物。',
-      toggleFailed: '無法切換寵物顯示。',
-      noneAvailable: '尚無可用寵物——請在下方選擇一個安裝。'
-    },
-    generatePet: {
-      title: '生成寵物',
-      placeholder: '描述要生成的寵物……',
-      promptHint: '輸入描述，然後按 Enter 生成四種造型。',
-      readyHint: '按 Enter 依描述生成四種造型。',
-      generate: '生成',
-      generating: '生成中……',
-      retry: '重試',
-      hatch: '孵化',
-      hatching: '正在孵化你的寵物……',
-      namePlaceholder: '為寵物命名',
-      staleBackend: '請更新 Hermes 以生成寵物。',
-      adopt: '領養',
-      startOver: '重新開始'
-    },
     installTheme: {
       title: '安裝主題...',
       placeholder: '搜尋 VS Code Marketplace...',
@@ -1858,6 +1806,7 @@ export const zhHant = defineLocale({
       refresh: '重新整理',
       moreActions: '更多動作',
       branchNewChat: '在新聊天中分支',
+      dismissError: '关闭错误',
       readAloudFailed: '朗讀失敗',
       preparingAudio: '正在準備音訊...',
       stopReading: '停止朗讀',
@@ -1965,6 +1914,9 @@ export const zhHant = defineLocale({
     regenerateFailed: '重新生成失敗',
     editFailed: '編輯失敗',
     resumeFailed: '繼續失敗',
+    resumeStrandedTitle: '無法載入此工作階段',
+    resumeStrandedBody: '與此工作階段的連線失敗，自動重試已停止。請確認閘道正在執行，然後重試。',
+    resumeRetry: '重試',
     nothingToBranch: '沒有可分支的內容',
     branchNeedsChat: '分支前請先開始或繼續一個聊天。',
     sessionBusy: '工作階段忙碌中',

apps/desktop/src/i18n/zh.ts

@@ -359,30 +359,7 @@ export const zh: Translations = {
       installError: '无法安装该主题。',
       installed: name => `已安装「${name}」。`,
       removeTheme: '移除主题',
-      importedBadge: '已导入',
-      pet: {
-        title: '宠物',
-        intro: '领养一只悬浮在应用上的 petdex 动画宠物，它会根据 Hermes 的状态做出反应——工具执行时奔跑、成功时欢呼、出错时沮丧。',
-        restartHint: '宠物功能需要重启——当前运行的应用在此功能加入前启动。请退出并重新打开 Hermes，然后回到此处。',
-        scaleTitle: '大小',
-        scaleDesc: '调整悬浮宠物的大小，所有界面即时生效。',
-        on: '开启',
-        off: '关闭',
-        chooseTitle: '选择宠物',
-        chooseDesc: '选择后会自动安装（如需）并设为当前宠物。',
-        searchPlaceholder: '搜索宠物…',
-        unreachable: '无法连接到 petdex 画廊。请检查网络连接并重新打开此页面。',
-        noMatch: query => `没有匹配「${query}」的宠物。`,
-        installedTag: '已安装',
-        countCapped: (cap, total) => `显示 ${total} 个中的 ${cap} 个——输入关键词以缩小范围。`,
-        count: n => `${n} 个宠物。`,
-        uninstall: name => `卸载 ${name}`,
-        adoptFailed: slug => `无法领养 ${slug}`,
-        uninstallFailed: slug => `无法卸载 ${slug}`,
-        noneAvailable: '当前没有可开启的宠物。',
-        turnOnFailed: '无法开启宠物。',
-        turnOffFailed: '无法关闭宠物。'
-      }
+      importedBadge: '已导入'
     },
     fieldLabels: defineFieldCopy({
       model: '默认模型',
@@ -756,6 +733,10 @@ export const zh: Translations = {
       provider: '提供方',
       model: '模型',
       applying: '应用中...',
+      defaultsLabel: '默认值',
+      reasoning: '推理',
+      reasoningOff: '关闭',
+      defaultsFailed: '保存模型默认值失败',
       auxiliaryTitle: '辅助模型',
       resetAllToMain: '全部重置为主模型',
       auxiliaryDesc: '辅助任务默认使用主模型。你可以为任意任务指定专用模型。',
@@ -923,37 +904,8 @@ export const zh: Translations = {
     commandCenter: '命令中心',
     appearance: '外观',
     settings: '设置',
-    changeTheme: '更改主题',
+    changeTheme: '更改主题...',
     changeColorMode: '更改颜色模式...',
-    pets: {
-      title: '宠物',
-      placeholder: '搜索宠物…',
-      loading: '正在加载 petdex 画廊…',
-      error: '无法连接到 petdex 画廊。',
-      staleBackend: '请重启 Hermes 以使用宠物功能——当前后端版本过旧。',
-      empty: '没有匹配的宠物。',
-      turnOff: '关闭',
-      turnOn: '开启',
-      installed: '已安装',
-      adoptFailed: '无法领养该宠物。',
-      toggleFailed: '无法切换宠物显示。',
-      noneAvailable: '暂无可用宠物——请在下方选择一个安装。'
-    },
-    generatePet: {
-      title: '生成宠物',
-      placeholder: '描述要生成的宠物……',
-      promptHint: '输入描述，然后按 Enter 生成四种造型。',
-      readyHint: '按 Enter 根据描述生成四种造型。',
-      generate: '生成',
-      generating: '生成中……',
-      retry: '重试',
-      hatch: '孵化',
-      hatching: '正在孵化你的宠物……',
-      namePlaceholder: '给宠物起个名字',
-      staleBackend: '请更新 Hermes 以生成宠物。',
-      adopt: '领养',
-      startOver: '重新开始'
-    },
     installTheme: {
       title: '安装主题...',
       placeholder: '搜索 VS Code Marketplace...',
@@ -1960,6 +1912,7 @@ export const zh: Translations = {
       refresh: '刷新',
       moreActions: '更多操作',
       branchNewChat: '在新对话中分支',
+      dismissError: '关闭错误',
       readAloudFailed: '朗读失败',
       preparingAudio: '正在准备音频...',
       stopReading: '停止朗读',
@@ -2068,6 +2021,9 @@ export const zh: Translations = {
     regenerateFailed: '重新生成失败',
     editFailed: '编辑失败',
     resumeFailed: '恢复失败',
+    resumeStrandedTitle: '无法加载此会话',
+    resumeStrandedBody: '与此会话的连接失败，自动重试已停止。请确认网关正在运行，然后重试。',
+    resumeRetry: '重试',
     nothingToBranch: '没有可分支的内容',
     branchNeedsChat: '分支前请先开始或恢复一个对话。',
     sessionBusy: '会话忙碌中',

apps/desktop/src/lib/desktop-slash-commands.test.ts

@@ -52,16 +52,6 @@ describe('desktop slash command curation', () => {
     expect(desktopSlashUnavailableMessage('/personality')).toBeNull()
   })
 
-  it('routes /pet through the desktop action handler and drops /pets', () => {
-    expect(resolveDesktopCommand('/pet')?.surface).toEqual({ kind: 'action', action: 'pet' })
-    expect(resolveDesktopCommand('/pet')?.args).toBe(true)
-    expect(isDesktopSlashSuggestion('/pet')).toBe(true)
-    expect(isDesktopSlashCommand('/pet')).toBe(true)
-    expect(resolveDesktopCommand('/pets')?.surface).toEqual({ kind: 'unavailable', reason: 'settings' })
-    expect(isDesktopSlashSuggestion('/pets')).toBe(false)
-    expect(isDesktopSlashCommand('/pets')).toBe(false)
-  })
-
   it('treats /browser as an executable action command (local-gateway connect)', () => {
     // /browser used to be terminal-only; it now resolves to a desktop action
     // handler that routes browser.manage RPC when the gateway is local.

apps/desktop/src/lib/desktop-slash-commands.ts

@@ -34,7 +34,6 @@ export type DesktopActionId =
   | 'handoff'
   | 'help'
   | 'new'
-  | 'pet'
   | 'profile'
   | 'skin'
   | 'title'
@@ -129,7 +128,6 @@ const DESKTOP_COMMAND_SPECS: readonly DesktopCommandSpec[] = [
   { name: '/debug', description: 'Create a debug report', surface: exec() },
   { name: '/goal', description: 'Manage the standing goal for this session', surface: exec() },
   { name: '/personality', description: 'Switch personality for this session', surface: exec(), args: true },
-  { name: '/pet', description: 'Toggle or adopt a petdex mascot (/pet, /pet list, /pet boba)', surface: action('pet'), args: true },
   { name: '/queue', description: 'Queue a prompt for the next turn', aliases: ['/q'], surface: exec() },
   { name: '/retry', description: 'Retry the last user message', surface: exec() },
   { name: '/rollback', description: 'List or restore filesystem checkpoints', surface: exec() },
@@ -157,7 +155,7 @@ const NO_DESKTOP_SURFACE: Record<DesktopUnavailableReason, readonly string[]> =
     '/sb', '/set-home', '/sethome', '/snap', '/snapshot', '/statusbar', '/toolsets', '/update', '/verbose'
   ],
   messaging: ['/approve', '/deny'],
-  settings: ['/skills', '/pets'],
+  settings: ['/skills'],
   advanced: ['/curator', '/fast', '/insights', '/kanban', '/reasoning', '/voice']
 }
 

apps/desktop/src/lib/icons.ts

@@ -29,7 +29,6 @@ import {
   IconCopy as CopyIcon,
   IconCpu as Cpu,
   IconDownload as Download,
-  IconEgg as Egg,
   IconExternalLink as ExternalLink,
   IconEye as Eye,
   IconEyeOff as EyeOff,
@@ -52,7 +51,6 @@ import {
   IconLoader2 as Loader2Icon,
   IconLock as Lock,
   IconLogin as LogIn,
-  IconMail as Mail,
   IconMessageCircle as MessageCircle,
   IconMessage2 as MessageSquareText,
   IconMicrophone as Mic,
@@ -69,7 +67,6 @@ import {
   IconLayoutBottombar as PanelBottom,
   IconLayoutSidebar as PanelLeftIcon,
   IconPlayerPause as Pause,
-  IconPaw as PawPrint,
   IconPencil as Pencil,
   IconPencil as PencilIcon,
   IconPencil as PencilLine,
@@ -134,7 +131,6 @@ export {
   CopyIcon,
   Cpu,
   Download,
-  Egg,
   ExternalLink,
   Eye,
   EyeOff,
@@ -157,7 +153,6 @@ export {
   Loader2Icon,
   Lock,
   LogIn,
-  Mail,
   MessageCircle,
   MessageSquareText,
   Mic,
@@ -174,7 +169,6 @@ export {
   PanelBottom,
   PanelLeftIcon,
   Pause,
-  PawPrint,
   Pencil,
   PencilIcon,
   PencilLine,

apps/desktop/src/lib/markdown-preprocess.ts

@@ -151,12 +151,18 @@ function normalizeVisibleProse(text: string): string {
     .join('')
 }
 
+function extend(out: string[], lines: string[]) {
+  for (const line of lines) {
+    out.push(line)
+  }
+}
+
 function pushProseFence(out: string[], indent: string, info: string, lines: string[]) {
   if (info) {
     out.push(`${indent}${info}`.trimEnd())
   }
 
-  out.push(...lines)
+  extend(out, lines)
 }
 
 function findClosingFence(lines: string[], start: number, marker: string): number {
@@ -241,7 +247,7 @@ function normalizeFenceBlocks(text: string): string {
     }
 
     if (closeIndex !== -1 && isUrlOnlyBlock(bodyLines)) {
-      out.push(...bodyLines)
+      extend(out, bodyLines)
       index = closeIndex + 1
 
       continue
@@ -264,10 +270,10 @@ function normalizeFenceBlocks(text: string): string {
         // any literal `$$` characters in the body don't collide with
         // an outer math wrapper. No close emitted yet — streaming.
         out.push(`${indent}${marker}math`)
-        out.push(...bodyLines)
+        extend(out, bodyLines)
       } else {
         out.push(`${indent}${marker}${language}`)
-        out.push(...bodyLines)
+        extend(out, bodyLines)
       }
 
       break
@@ -288,7 +294,7 @@ function normalizeFenceBlocks(text: string): string {
       // colliding with our wrapper. Without this rewrite the block
       // would render as a syntax-highlighted "latex" code listing.
       out.push(`${indent}${marker}math`)
-      out.push(...bodyLines)
+      extend(out, bodyLines)
       out.push(`${indent}${marker}`)
       index = closeIndex + 1
 
@@ -296,7 +302,7 @@ function normalizeFenceBlocks(text: string): string {
     }
 
     out.push(`${indent}${marker}${language}`)
-    out.push(...bodyLines)
+    extend(out, bodyLines)
     out.push(`${indent}${marker}`)
     index = closeIndex + 1
   }

apps/desktop/src/lib/model-status-label.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
-import { displayModelName, formatModelStatusLabel, reasoningEffortLabel } from './model-status-label'
+import { currentPickerSelection, displayModelName, formatModelStatusLabel, reasoningEffortLabel } from './model-status-label'
 
 describe('model-status-label', () => {
   it('formats display names consistently', () => {
@@ -35,4 +35,25 @@ describe('model-status-label', () => {
   it('returns just the placeholder name when there is no model', () => {
     expect(formatModelStatusLabel('')).toBe('No model')
   })
+
+  describe('currentPickerSelection', () => {
+    const store = { model: 'opus', provider: 'anthropic' }
+    const options = { model: 'hermes-4', provider: 'nous' }
+
+    it('prefers the sticky composer pick over the profile default pre-session', () => {
+      expect(currentPickerSelection(false, store, options)).toEqual(store)
+    })
+
+    it('lets the live session model.options win when a session exists', () => {
+      expect(currentPickerSelection(true, store, options)).toEqual(options)
+    })
+
+    it('falls back to options when the store is empty', () => {
+      expect(currentPickerSelection(false, { model: '', provider: '' }, options)).toEqual(options)
+    })
+
+    it('falls back to the store while options are still loading', () => {
+      expect(currentPickerSelection(true, store, undefined)).toEqual(store)
+    })
+  })
 })

apps/desktop/src/lib/model-status-label.ts

@@ -17,6 +17,22 @@ export function reasoningEffortLabel(effort: string): string {
   return REASONING_LABELS[key] ?? effort
 }
 
+/** Which model/provider a picker should mark "current". With a live session the
+ *  gateway's `model.options` is authoritative; pre-session there is no server
+ *  "current", so the sticky composer pick wins over the profile default the
+ *  global options query returns — else the checkmark snaps back to the default
+ *  and the pick looks ignored. */
+export function currentPickerSelection(
+  hasSession: boolean,
+  store: { model: string; provider: string },
+  options?: { model?: string; provider?: string }
+): { model: string; provider: string } {
+  return {
+    model: String((hasSession && options?.model) || store.model || options?.model || ''),
+    provider: String((hasSession && options?.provider) || store.provider || options?.provider || '')
+  }
+}
+
 /** Strip provider prefix and normalize for display. */
 export function modelBaseId(model: string): string {
   const trimmed = model.trim()

apps/desktop/src/lib/selectable-card.ts

@@ -1,31 +0,0 @@
-import { cn } from '@/lib/utils'
-
-export interface SelectableCardState {
-  /** Currently selected / active — the strongest emphasis. */
-  active?: boolean
-  /**
-   * Configured / installed / "you have this" — solid surface + border. When
-   * false the card renders muted (transparent, dimmed) until hovered, so the
-   * eye lands on what you already have. Ignored when `active` is set.
-   */
-  prominent?: boolean
-}
-
-/**
- * Shared emphasis for selectable list cards across settings surfaces (theme
- * picker, pet picker, Marketplace results, provider rows…). Three tiers:
- * active > prominent > muted. Keeps the "installed = solid, not-installed =
- * quiet" pattern consistent everywhere instead of each picker rolling its own.
- *
- * Callers own layout (padding, flex, width); this owns only border + surface.
- */
-export function selectableCardClass({ active, prominent }: SelectableCardState): string {
-  return cn(
-    'rounded-lg border transition-colors',
-    active
-      ? 'border-primary bg-primary/[0.06] ring-2 ring-primary/20'
-      : prominent
-        ? 'border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) hover:bg-(--chrome-action-hover)'
-        : 'border-transparent bg-transparent text-(--ui-text-tertiary) hover:border-(--ui-stroke-tertiary) hover:bg-(--ui-bg-quinary)'
-  )
-}

apps/desktop/src/main.tsx

@@ -26,27 +26,20 @@ if (import.meta.env.MODE !== 'production') {
   import('./app/chat/perf-probe')
 }
 
-// The pet overlay rides this same bundle (`?win=overlay`) but mounts a tiny,
-// transparent, gateway-less surface instead of the full app. Branch before any
-// app-shell work so the overlay window stays cheap.
-if (new URLSearchParams(window.location.search).get('win') === 'overlay') {
-  void import('./app/pet-overlay/overlay-root').then(({ mountPetOverlay }) => mountPetOverlay())
-} else {
-  createRoot(document.getElementById('root')!).render(
-    <StrictMode>
-      <ErrorBoundary label="root">
-        <QueryClientProvider client={queryClient}>
-          <I18nProvider>
-            <ThemeProvider>
-              <HapticsProvider>
-                <HashRouter>
-                  <App />
-                </HashRouter>
-              </HapticsProvider>
-            </ThemeProvider>
-          </I18nProvider>
-        </QueryClientProvider>
-      </ErrorBoundary>
-    </StrictMode>
-  )
-}
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <ErrorBoundary label="root">
+      <QueryClientProvider client={queryClient}>
+        <I18nProvider>
+          <ThemeProvider>
+            <HapticsProvider>
+              <HashRouter>
+                <App />
+              </HashRouter>
+            </HapticsProvider>
+          </ThemeProvider>
+        </I18nProvider>
+      </QueryClientProvider>
+    </ErrorBoundary>
+  </StrictMode>
+)

apps/desktop/src/store/command-palette.ts

@@ -3,30 +3,16 @@ import { atom } from 'nanostores'
 /** Whether the global command palette (Cmd/Ctrl+K) is currently open. */
 export const $commandPaletteOpen = atom(false)
 
-/** Optional nested page to open when the palette next opens (e.g. `pets`). */
-export const $commandPalettePage = atom<string | null>(null)
-
 export function openCommandPalette(): void {
   $commandPaletteOpen.set(true)
 }
 
-/** Open the palette directly on a nested page (`theme`, `pets`, …). */
-export function openCommandPalettePage(page: string): void {
-  $commandPalettePage.set(page)
-  $commandPaletteOpen.set(true)
-}
-
 export function closeCommandPalette(): void {
   $commandPaletteOpen.set(false)
-  $commandPalettePage.set(null)
 }
 
 export function setCommandPaletteOpen(open: boolean): void {
   $commandPaletteOpen.set(open)
-
-  if (!open) {
-    $commandPalettePage.set(null)
-  }
 }
 
 export function toggleCommandPalette(): void {

apps/desktop/src/store/pet-gallery.ts

@@ -1,298 +0,0 @@
-import { atom } from 'nanostores'
-
-import { $petInfo, type PetInfo, setPetInfo } from '@/store/pet'
-
-/**
- * Feature store for the petdex gallery picker (Cmd+K "Pets…" + Settings).
- *
- * Why this exists: `pet.gallery` does a *network* manifest fetch on the gateway,
- * so re-pulling it after every adopt/toggle made the picker feel laggy and made
- * two components (palette + settings) each carry their own copy of the same
- * fetch / thumb-cache / optimistic-mutation logic. This store centralizes it:
- *
- *  - The gallery is fetched once and cached; reopening the picker is instant.
- *  - Mutations (adopt / enable / remove) patch local state and only re-pull the
- *    cheap, local `pet.info` — never the network manifest again.
- *  - Thumbnails are deduped in a process-global cache (the backend disk-caches
- *    too, so a slug is fetched at most once per session).
- *
- * Consumers just `useStore($petGallery)` and call the actions; no component
- * owns gallery state anymore.
- */
-
-export interface GalleryPet {
-  slug: string
-  displayName: string
-  installed: boolean
-  spritesheetUrl?: string
-  /** petdex's hand-picked set — used only to rank "popular" pets first. */
-  curated?: boolean
-}
-
-export interface PetGallery {
-  enabled: boolean
-  active: string
-  pets: GalleryPet[]
-}
-
-export type PetGalleryStatus = 'idle' | 'loading' | 'ready' | 'stale' | 'error'
-
-/** The recovering `requestGateway` from `useGatewayRequest` — passed in so the
- *  store reuses the hook's reconnect/reauth handling instead of duplicating it. */
-export type GatewayRequest = <T>(method: string, params?: Record<string, unknown>) => Promise<T>
-
-/** A JSON-RPC "method not found" — the backend predates the pet RPCs. */
-function isMissingMethod(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error)
-
-  return /method not found|-32601|unknown method|no such method/i.test(message)
-}
-
-export const $petGallery = atom<PetGallery | null>(null)
-export const $petGalleryStatus = atom<PetGalleryStatus>('idle')
-export const $petGalleryError = atom<string | null>(null)
-
-// Which action is in flight, so rows/buttons can show a spinner. A slug for a
-// per-pet mutation; the `TOGGLE_*` sentinels for the on/off switch.
-export const TOGGLE_ON = '\u0000on'
-export const TOGGLE_OFF = '\u0000off'
-export const $petBusy = atom<string | null>(null)
-
-// Process-global caches (survive component unmount → instant reopen).
-const thumbCache = new Map<string, Promise<string | null>>()
-let galleryLoad: Promise<void> | null = null
-
-export function loadPetThumb(request: GatewayRequest, slug: string, url?: string): Promise<string | null> {
-  let pending = thumbCache.get(slug)
-
-  if (!pending) {
-    pending = request<{ ok: boolean; dataUri?: string }>('pet.thumb', { slug, url: url ?? '' })
-      .then(result => (result?.ok && result.dataUri ? result.dataUri : null))
-      .catch(() => null)
-    thumbCache.set(slug, pending)
-  }
-
-  return pending
-}
-
-/**
- * Fetch the gallery once and cache it. Subsequent calls are no-ops while a
- * ready snapshot is held; pass `{ force: true }` to bypass the cache (e.g. a
- * manual refresh). Concurrent callers share a single in-flight request.
- */
-export function loadPetGallery(request: GatewayRequest, options: { force?: boolean } = {}): Promise<void> {
-  if (!options.force && $petGallery.get() && $petGalleryStatus.get() === 'ready') {
-    return Promise.resolve()
-  }
-
-  if (galleryLoad) {
-    return galleryLoad
-  }
-
-  galleryLoad = (async () => {
-    if (!$petGallery.get()) {
-      $petGalleryStatus.set('loading')
-    }
-
-    try {
-      const [next, info] = await Promise.all([request<PetGallery>('pet.gallery'), request<PetInfo>('pet.info')])
-
-      if (next) {
-        $petGallery.set(next)
-        $petGalleryStatus.set('ready')
-        $petGalleryError.set(null)
-      }
-
-      if (info) {
-        setPetInfo(info)
-      }
-    } catch (e) {
-      if (isMissingMethod(e)) {
-        $petGalleryStatus.set('stale')
-      } else if (!$petGallery.get()) {
-        // Only surface a hard error when we have nothing to show; a transient
-        // hiccup mid-session leaves the cached gallery intact.
-        $petGalleryStatus.set('error')
-        $petGalleryError.set(e instanceof Error ? e.message : 'Could not reach the petdex gallery.')
-      }
-    } finally {
-      galleryLoad = null
-    }
-  })()
-
-  return galleryLoad
-}
-
-// Push the live mascot state (cheap, local config read) without re-pulling the
-// network gallery — the floating pet repaints, the picker keeps its cache.
-async function syncInfo(request: GatewayRequest): Promise<void> {
-  try {
-    const info = await request<PetInfo>('pet.info')
-
-    if (info) {
-      setPetInfo(info)
-    }
-  } catch {
-    // The mutation already succeeded; a stale mascot self-heals on its poll.
-  }
-}
-
-/**
- * Filter (drop the internal `clawd*` pets + apply a search query) and rank the
- * gallery for a picker. Ranking has no popularity data, so it leans on the
- * signals we do have: active pet first, then installed, then curated. Shared by
- * the Cmd-K palette and the Settings grid so the two can't drift — each caller
- * applies its own cap and reads `.length` for the total.
- */
-export function rankedGalleryPets(gallery: PetGallery | null, query = ''): GalleryPet[] {
-  if (!gallery) {
-    return []
-  }
-
-  const needle = query.trim().toLowerCase()
-
-  const rank = (p: GalleryPet) =>
-    Number(gallery.enabled && p.slug === gallery.active) * 4 + Number(p.installed) * 2 + Number(p.curated)
-
-  return gallery.pets
-    .filter(
-      p =>
-        !/^clawd(-|$)/i.test(p.slug) &&
-        (!needle || p.slug.toLowerCase().includes(needle) || p.displayName.toLowerCase().includes(needle))
-    )
-    .sort((a, b) => rank(b) - rank(a))
-}
-
-function patchGallery(fn: (gallery: PetGallery) => PetGallery): void {
-  const current = $petGallery.get()
-
-  if (current) {
-    $petGallery.set(fn(current))
-  }
-}
-
-/** Shared mutation wrapper: spin, fire, patch on success, surface failures. */
-async function mutate(
-  busyKey: string,
-  fallback: string,
-  request: GatewayRequest,
-  run: () => Promise<void>
-): Promise<boolean> {
-  $petBusy.set(busyKey)
-  $petGalleryError.set(null)
-
-  try {
-    await run()
-    await syncInfo(request)
-
-    return true
-  } catch (e) {
-    if (isMissingMethod(e)) {
-      $petGalleryStatus.set('stale')
-    } else {
-      $petGalleryError.set(e instanceof Error ? e.message : fallback)
-    }
-
-    return false
-  } finally {
-    $petBusy.set(null)
-  }
-}
-
-/** Install (if needed) + activate a pet. Optimistically marks it active. */
-export function adoptPet(request: GatewayRequest, slug: string, fallback: string): Promise<boolean> {
-  return mutate(slug, fallback, request, async () => {
-    await request('pet.select', { slug })
-    patchGallery(g => ({
-      ...g,
-      enabled: true,
-      active: slug,
-      pets: g.pets.map(p => (p.slug === slug ? { ...p, installed: true } : p))
-    }))
-  })
-}
-
-/**
- * Turn the floating mascot on/off. On enable, activates the current pet (or the
- * first installed one). Returns false without firing if there's nothing to show.
- */
-export function setPetEnabled(
-  request: GatewayRequest,
-  on: boolean,
-  copy: { noneAvailable: string; fallback: string }
-): Promise<boolean> {
-  const gallery = $petGallery.get()
-
-  if (!on && !(gallery?.enabled ?? false)) {
-    return Promise.resolve(true)
-  }
-
-  let slug = gallery?.active || ''
-
-  if (on) {
-    slug = slug || gallery?.pets.find(p => p.installed)?.slug || ''
-
-    if (!slug) {
-      $petGalleryError.set(copy.noneAvailable)
-
-      return Promise.resolve(false)
-    }
-  }
-
-  return mutate(on ? TOGGLE_ON : TOGGLE_OFF, copy.fallback, request, async () => {
-    if (on) {
-      await request('pet.select', { slug })
-    } else {
-      await request('pet.disable')
-    }
-
-    patchGallery(g => ({ ...g, enabled: on, active: on ? slug : g.active }))
-  })
-}
-
-// Pet scale bounds — mirror `agent/pet/constants.py` (MIN_SCALE / MAX_SCALE) so
-// the slider and the server clamp to the same range.
-export const PET_SCALE_MIN = 0.1
-export const PET_SCALE_MAX = 3.0
-export const PET_SCALE_DEFAULT = 0.33
-export const clampPetScale = (n: number) => Math.max(PET_SCALE_MIN, Math.min(PET_SCALE_MAX, n))
-
-let scalePersist: ReturnType<typeof setTimeout> | undefined
-
-/**
- * Resize the floating pet. Updates `$petInfo` synchronously so the on-screen pet
- * (and the slider) react on the same frame, then debounce-persists to
- * `display.pet.scale` so a slider drag fires one RPC, not one per pixel. No poll
- * or event needed — the pet already renders from `$petInfo.scale`.
- */
-export function setPetScale(request: GatewayRequest, scale: number): void {
-  const next = clampPetScale(scale)
-
-  setPetInfo({ ...$petInfo.get(), scale: next })
-
-  clearTimeout(scalePersist)
-  scalePersist = setTimeout(() => {
-    request<{ ok: boolean; scale?: number }>('pet.scale', { scale: next })
-      .then(result => {
-        // Reconcile with the server's clamp (cheap; only matters at the bounds).
-        if (typeof result?.scale === 'number' && result.scale !== $petInfo.get().scale) {
-          setPetInfo({ ...$petInfo.get(), scale: result.scale })
-        }
-      })
-      .catch(() => {
-        // Cosmetic — the pet already resized; persistence self-heals next write.
-      })
-  }, 200)
-}
-
-/** Uninstall a pet; turns the mascot off if it was the active one. */
-export function removePet(request: GatewayRequest, slug: string, fallback: string): Promise<boolean> {
-  return mutate(slug, fallback, request, async () => {
-    await request('pet.remove', { slug })
-    patchGallery(g => ({
-      ...g,
-      enabled: g.active === slug ? false : g.enabled,
-      pets: g.pets.map(p => (p.slug === slug ? { ...p, installed: false } : p))
-    }))
-  })
-}

apps/desktop/src/store/pet-generate.ts

@@ -1,241 +0,0 @@
-import { atom } from 'nanostores'
-
-import { type PetInfo } from '@/store/pet'
-import { type GatewayRequest, loadPetGallery } from '@/store/pet-gallery'
-
-/**
- * Feature store for the "generate a pet" flow (Cmd-K → Pets → Generate).
- *
- * Three backend steps, mirrored as state here:
- *  - `pet.generate` produces N cheap base-look *drafts* keyed by a `token`.
- *  - `pet.hatch` turns the chosen draft into a full animated pet — installed but
- *    NOT active — and returns its renderer payload so we can preview all frames.
- *  - the user then *adopts* (`pet.select`) or *discards* (`pet.remove`) it.
- *
- * The store owns the draft set, the selected variant, the hatched preview, and
- * the busy/error status so the page is a thin view. Retry == regenerate (new
- * token). Kept separate from `pet-gallery` because its lifecycle (ephemeral
- * drafts + an unadopted preview) is unrelated to the long-lived gallery cache.
- */
-
-export interface PetDraft {
-  index: number
-  /** Downscaled PNG data URI preview from the gateway. */
-  dataUri: string
-}
-
-export type PetGenStatus =
-  | 'idle'
-  | 'generating'
-  | 'ready'
-  | 'hatching'
-  | 'preview'
-  | 'adopting'
-  | 'error'
-  | 'stale'
-
-export const $petGenStatus = atom<PetGenStatus>('idle')
-export const $petGenError = atom<string | null>(null)
-export const $petGenToken = atom<string | null>(null)
-/** Prompt that produced the current draft token; hatch uses this for consistency. */
-export const $petGenPrompt = atom<string>('')
-export const $petGenDrafts = atom<PetDraft[]>([])
-export const $petGenSelected = atom<number | null>(null)
-/** The hatched-but-unadopted pet: its renderer payload, played in the preview. */
-export const $petGenPreview = atom<PetInfo | null>(null)
-
-function isMissingMethod(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error)
-
-  return /method not found|-32601|unknown method|no such method/i.test(message)
-}
-
-/** Clear all generation state (on close, or before a fresh run). */
-export function resetPetGen(): void {
-  $petGenStatus.set('idle')
-  $petGenError.set(null)
-  $petGenToken.set(null)
-  $petGenPrompt.set('')
-  $petGenDrafts.set([])
-  $petGenSelected.set(null)
-  $petGenPreview.set(null)
-}
-
-/**
- * Reset on palette close, deleting an unadopted preview pet first so a hatched-
- * but-never-adopted creature doesn't linger in the gallery. Fire-and-forget.
- */
-export function cleanupPetGen(request: GatewayRequest): void {
-  const preview = $petGenPreview.get()
-
-  if ($petGenStatus.get() === 'preview' && preview?.slug) {
-    void request('pet.remove', { slug: preview.slug }).catch(() => {})
-  }
-
-  resetPetGen()
-}
-
-interface GenerateOptions {
-  prompt: string
-  style?: string
-  count?: number
-}
-
-/** Generate (or retry) a fresh set of base-look drafts for `prompt`. */
-export async function generateDrafts(request: GatewayRequest, options: GenerateOptions): Promise<boolean> {
-  const prompt = options.prompt.trim()
-
-  if (!prompt) {
-    return false
-  }
-
-  // Starting a fresh generation round supersedes any unadopted preview pet.
-  const preview = $petGenPreview.get()
-  if (preview?.slug) {
-    await request('pet.remove', { slug: preview.slug }).catch(() => {})
-  }
-
-  $petGenStatus.set('generating')
-  $petGenError.set(null)
-  $petGenPreview.set(null)
-  $petGenDrafts.set([])
-  $petGenSelected.set(null)
-
-  try {
-    const result = await request<{ ok: boolean; token: string; drafts: PetDraft[] }>('pet.generate', {
-      prompt,
-      style: options.style ?? 'auto',
-      count: options.count ?? 4
-    })
-
-    if (!result?.ok || !result.drafts?.length) {
-      throw new Error('generation produced no drafts')
-    }
-
-    $petGenToken.set(result.token)
-    $petGenPrompt.set(prompt)
-    $petGenDrafts.set(result.drafts)
-    $petGenSelected.set(result.drafts[0]?.index ?? 0)
-    $petGenStatus.set('ready')
-
-    return true
-  } catch (e) {
-    if (isMissingMethod(e)) {
-      $petGenStatus.set('stale')
-    } else {
-      $petGenStatus.set('error')
-      $petGenError.set(e instanceof Error ? e.message : 'Could not generate pet drafts.')
-    }
-
-    return false
-  }
-}
-
-interface HatchOptions {
-  name: string
-  description?: string
-  prompt?: string
-  style?: string
-}
-
-/**
- * Hatch the selected draft into a full pet (installed but NOT yet active) and
- * load its renderer payload into the preview. Adoption is a separate, explicit
- * step (`adoptHatched`) so the user sees every frame play before committing.
- * Returns true when the preview is ready.
- */
-export async function hatchSelected(request: GatewayRequest, options: HatchOptions): Promise<boolean> {
-  const token = $petGenToken.get()
-  const index = $petGenSelected.get()
-  const name = options.name.trim()
-  const concept = ($petGenPrompt.get() || options.prompt || name).trim()
-
-  if (token === null || index === null || !name) {
-    return false
-  }
-
-  $petGenStatus.set('hatching')
-  $petGenError.set(null)
-
-  try {
-    const result = await request<{ ok: boolean; slug: string; displayName: string; pet?: PetInfo }>('pet.hatch', {
-      token,
-      index,
-      name,
-      description: options.description ?? '',
-      prompt: concept,
-      style: options.style ?? 'auto'
-    })
-
-    if (!result?.ok || !result.pet?.spritesheetBase64) {
-      throw new Error('hatch produced no preview')
-    }
-
-    $petGenPreview.set({ ...result.pet, enabled: true })
-    $petGenStatus.set('preview')
-
-    return true
-  } catch (e) {
-    $petGenStatus.set('error')
-    $petGenError.set(e instanceof Error ? e.message : 'Could not hatch the pet.')
-
-    return false
-  }
-}
-
-export interface AdoptOutcome {
-  ok: boolean
-  slug?: string
-  displayName?: string
-}
-
-/**
- * Adopt the previewed pet: activate it (`pet.select`), refresh the gallery + live
- * mascot, and clear generation state. No-op unless a preview exists.
- */
-export async function adoptHatched(request: GatewayRequest): Promise<AdoptOutcome> {
-  const preview = $petGenPreview.get()
-
-  if (!preview?.slug) {
-    return { ok: false }
-  }
-
-  $petGenStatus.set('adopting')
-  $petGenError.set(null)
-
-  try {
-    const result = await request<{ ok: boolean; slug: string; displayName: string }>('pet.select', {
-      slug: preview.slug
-    })
-
-    if (!result?.ok) {
-      throw new Error('adopt failed')
-    }
-
-    await loadPetGallery(request, { force: true })
-    resetPetGen()
-
-    return { ok: true, slug: result.slug, displayName: result.displayName }
-  } catch (e) {
-    $petGenStatus.set('preview')
-    $petGenError.set(e instanceof Error ? e.message : 'Could not adopt the pet.')
-
-    return { ok: false }
-  }
-}
-
-/**
- * Throw away the previewed pet (`pet.remove`) and return to the draft picker so
- * the user can choose another base or regenerate. Best-effort on the delete.
- */
-export async function discardHatched(request: GatewayRequest): Promise<void> {
-  const preview = $petGenPreview.get()
-
-  if (preview?.slug) {
-    await request('pet.remove', { slug: preview.slug }).catch(() => {})
-  }
-
-  $petGenPreview.set(null)
-  $petGenError.set(null)
-  $petGenStatus.set($petGenDrafts.get().length > 0 ? 'ready' : 'idle')
-}

apps/desktop/src/store/pet-overlay.ts

@@ -1,260 +0,0 @@
-import { atom } from 'nanostores'
-
-import { persistBoolean, persistString, storedBoolean, storedString } from '@/lib/storage'
-import { $petActivity, $petInfo, $petUnread, clearPetUnread, type PetActivity, type PetInfo } from '@/store/pet'
-import { $awaitingResponse, $busy } from '@/store/session'
-
-/**
- * Controller for the pop-out pet overlay (main-renderer side).
- *
- * Shift-clicking the in-window pet "pops it out" into a transparent,
- * always-on-top OS window (created in electron/main.cjs) that can leave the
- * app's bounds and stays visible while Hermes is minimized. That window carries
- * NO gateway connection — this renderer remains the single source of truth and
- * pushes the live pet state to it over IPC. Control flows back (pop the pet back
- * in, submit a composer message) via `onControl`.
- *
- * The overlay renders the same `PetSprite` / `PetBubble` as the in-window pet by
- * mirroring the four reactive inputs of `$petState` (`$petInfo`, `$petActivity`,
- * `$busy`, `$awaitingResponse`) into its own copies of those atoms — so the
- * popped-out mascot is pixel-identical and needs zero bespoke render logic.
- */
-
-export interface PetOverlayBounds {
-  x: number
-  y: number
-  width: number
-  height: number
-}
-
-/**
- * Request to open the overlay window. `screen` says whether `bounds` are already
- * in absolute screen coordinates (a remembered/dragged spot) or in the main
- * window's viewport space (a fresh shift-click pop-out, which main.cjs converts
- * by adding the content origin).
- */
-export interface PetOverlayOpenRequest {
-  bounds: PetOverlayBounds
-  screen?: boolean
-}
-
-/** Everything the overlay needs to reproduce the live mascot. */
-export interface PetOverlayStatePayload {
-  info: PetInfo
-  activity: PetActivity
-  busy: boolean
-  awaiting: boolean
-  /** Drives the overlay's mail icon: a finish landed while you were away. */
-  unread: boolean
-}
-
-export type PetOverlayControl =
-  | { type: 'pop-in' }
-  | { type: 'ready' }
-  | { type: 'submit'; text: string }
-  | { type: 'bounds'; bounds: PetOverlayBounds }
-  | { type: 'open-app' }
-  | { type: 'toggle-app' }
-
-// Persisted across restarts: was the pet popped out, and where on the desktop
-// did the user leave it. Keyed v1; bump if the bounds shape ever changes.
-const OVERLAY_ACTIVE_KEY = 'hermes.desktop.pet-overlay-active.v1'
-const OVERLAY_BOUNDS_KEY = 'hermes.desktop.pet-overlay-bounds.v1'
-
-export const $petOverlayActive = atom(storedBoolean(OVERLAY_ACTIVE_KEY, false))
-
-// Persist the in/out choice so a popped-out pet comes back popped out.
-$petOverlayActive.subscribe(active => persistBoolean(OVERLAY_ACTIVE_KEY, active))
-
-function loadSavedBounds(): null | PetOverlayBounds {
-  try {
-    const raw = storedString(OVERLAY_BOUNDS_KEY)
-
-    if (!raw) {
-      return null
-    }
-
-    const parsed = JSON.parse(raw) as Partial<PetOverlayBounds>
-
-    if (
-      typeof parsed.x === 'number' &&
-      typeof parsed.y === 'number' &&
-      typeof parsed.width === 'number' &&
-      typeof parsed.height === 'number'
-    ) {
-      return { height: parsed.height, width: parsed.width, x: parsed.x, y: parsed.y }
-    }
-  } catch {
-    // fall through to null
-  }
-
-  return null
-}
-
-function saveBounds(bounds: PetOverlayBounds): void {
-  persistString(OVERLAY_BOUNDS_KEY, JSON.stringify(bounds))
-}
-
-// The overlay window is padded around the sprite so the bubble (above), the
-// drag area, and the pop-up composer all have room; the pet sits near the
-// bottom and the rest of the rectangle is transparent + click-through.
-const OVERLAY_PAD_X = 100
-const OVERLAY_PAD_Y = 200
-const OVERLAY_MIN_W = 240
-const OVERLAY_MIN_H = 300
-
-let stateUnsubs: Array<() => void> = []
-let controlUnsub: (() => void) | null = null
-let submitHandler: ((text: string) => void) | null = null
-let openAppHandler: (() => void) | null = null
-
-function currentPayload(): PetOverlayStatePayload {
-  return {
-    info: $petInfo.get(),
-    activity: $petActivity.get(),
-    busy: $busy.get(),
-    awaiting: $awaitingResponse.get(),
-    unread: $petUnread.get()
-  }
-}
-
-function pushNow(): void {
-  window.hermesDesktop?.petOverlay?.pushState(currentPayload())
-}
-
-/**
- * Open the overlay window and start mirroring live state into it. The main
- * process echoes back the actual screen bounds it used, which we persist so the
- * pet reopens exactly where the user left it.
- */
-function openOverlay(request: PetOverlayOpenRequest): void {
-  const api = window.hermesDesktop?.petOverlay
-
-  if (!api || stateUnsubs.length) {
-    return
-  }
-
-  $petOverlayActive.set(true)
-  void api.open(request).then(res => {
-    if (res?.bounds) {
-      saveBounds(res.bounds)
-    }
-
-    pushNow()
-  })
-
-  // Mirror live state into the overlay. subscribe() fires immediately, so the
-  // overlay also gets a first frame the moment it's ready (it asks via 'ready').
-  stateUnsubs = [
-    $petInfo.subscribe(pushNow),
-    $petActivity.subscribe(pushNow),
-    $busy.subscribe(pushNow),
-    $awaitingResponse.subscribe(pushNow),
-    $petUnread.subscribe(pushNow)
-  ]
-}
-
-/**
- * Pop the pet out of the window. `petRect` is the in-window sprite's viewport
- * rect; we grow it to the padded overlay size and center the window on the
- * pet's old spot (main.cjs adds the window's screen origin). If the user has
- * popped out before, reopen at that remembered desktop spot instead.
- */
-export function popOutPet(petRect: PetOverlayBounds): void {
-  if ($petOverlayActive.get() || stateUnsubs.length) {
-    return
-  }
-
-  const saved = loadSavedBounds()
-
-  if (saved) {
-    openOverlay({ bounds: saved, screen: true })
-
-    return
-  }
-
-  const width = Math.max(OVERLAY_MIN_W, Math.round(petRect.width + OVERLAY_PAD_X))
-  const height = Math.max(OVERLAY_MIN_H, Math.round(petRect.height + OVERLAY_PAD_Y))
-  const x = Math.round(petRect.x - (width - petRect.width) / 2)
-  const y = Math.round(petRect.y - (height - petRect.height) / 2)
-
-  openOverlay({ bounds: { height, width, x, y }, screen: false })
-}
-
-/**
- * Restore the overlay on boot if the pet was popped out when the app last
- * closed. Requires a remembered desktop spot — without one we fall back to the
- * in-window pet rather than spawning an orphan window at the origin.
- */
-export function restorePetOverlay(): void {
-  if (!window.hermesDesktop?.petOverlay || !$petOverlayActive.get() || stateUnsubs.length) {
-    return
-  }
-
-  const saved = loadSavedBounds()
-
-  if (!saved) {
-    $petOverlayActive.set(false)
-
-    return
-  }
-
-  openOverlay({ bounds: saved, screen: true })
-}
-
-/** Pop the pet back into the window (closes the overlay window). */
-export function popInPet(): void {
-  for (const off of stateUnsubs) {
-    off()
-  }
-
-  stateUnsubs = []
-  $petOverlayActive.set(false)
-  void window.hermesDesktop?.petOverlay?.close()
-}
-
-/** Register the handler that turns an overlay composer submit into a real send. */
-export function setPetOverlaySubmitHandler(fn: ((text: string) => void) | null): void {
-  submitHandler = fn
-}
-
-/** Register the handler that opens the app to the most recent thread (mail icon). */
-export function setPetOverlayOpenAppHandler(fn: (() => void) | null): void {
-  openAppHandler = fn
-}
-
-/**
- * Wire the overlay→renderer control channel once. Returns a disposer. Idempotent
- * — a second call while already wired is a no-op.
- */
-export function initPetOverlayBridge(): () => void {
-  const api = window.hermesDesktop?.petOverlay
-
-  if (!api || controlUnsub) {
-    return () => {}
-  }
-
-  controlUnsub = api.onControl(payload => {
-    if (payload?.type === 'pop-in') {
-      popInPet()
-    } else if (payload?.type === 'ready') {
-      // The overlay just mounted — hand it the current frame.
-      pushNow()
-    } else if (payload?.type === 'submit' && typeof payload.text === 'string') {
-      submitHandler?.(payload.text)
-    } else if (payload?.type === 'bounds' && payload.bounds) {
-      // The user dragged the overlay to a new desktop spot — remember it.
-      saveBounds(payload.bounds)
-    } else if (payload?.type === 'open-app') {
-      // Mail icon: surface the app on the most recent thread (main.cjs already
-      // focused the window before forwarding this) and mark it read.
-      clearPetUnread()
-      openAppHandler?.()
-    }
-  })
-
-  return () => {
-    controlUnsub?.()
-    controlUnsub = null
-  }
-}

apps/desktop/src/store/pet.test.ts

@@ -1,48 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { $petActivity, $petState, derivePetState, flashPetActivity, setPetActivity } from './pet'
-
-describe('derivePetState', () => {
-  it('rests at idle by default and uses waiting when awaiting input', () => {
-    expect(derivePetState({})).toBe('idle')
-    expect(derivePetState({ awaitingInput: true })).toBe('waiting')
-  })
-
-  it('runs when busy or a tool is executing', () => {
-    expect(derivePetState({ busy: true })).toBe('run')
-    expect(derivePetState({ toolRunning: true })).toBe('run')
-  })
-
-  it('reviews while reasoning (below tool, above bare busy)', () => {
-    expect(derivePetState({ reasoning: true })).toBe('review')
-    expect(derivePetState({ reasoning: true, busy: true })).toBe('review')
-    expect(derivePetState({ reasoning: true, toolRunning: true })).toBe('run')
-  })
-
-  it('waits (blocked on the user) above the in-flight signals', () => {
-    expect(derivePetState({ awaitingInput: true, toolRunning: true, busy: true })).toBe('waiting')
-    // but a finish beat still wins over waiting
-    expect(derivePetState({ justCompleted: true, awaitingInput: true })).toBe('wave')
-  })
-
-  it('honors the full priority chain: error > celebrate > complete > tool', () => {
-    expect(derivePetState({ error: true, celebrate: true, busy: true })).toBe('failed')
-    expect(derivePetState({ celebrate: true, justCompleted: true, toolRunning: true })).toBe('jump')
-    expect(derivePetState({ justCompleted: true, toolRunning: true })).toBe('wave')
-  })
-})
-
-describe('flashPetActivity', () => {
-  it('clears stale sibling beats so a completion never inherits a prior error', () => {
-    // A turn errors (sad), then the next turn finishes cleanly. The celebrate
-    // beat must win — error is highest priority, so a merge-only flash would
-    // keep the pet on the failed pose.
-    setPetActivity({ error: true })
-    flashPetActivity({ celebrate: true })
-
-    expect($petActivity.get().error).toBe(false)
-    expect($petState.get()).toBe('jump')
-
-    setPetActivity({})
-  })
-})

apps/desktop/src/store/pet.ts

@@ -1,147 +0,0 @@
-import { atom, computed } from 'nanostores'
-
-import { $busy } from '@/store/session'
-
-/**
- * Petdex mascot state for the desktop floating pet.
- *
- * The spritesheet payload comes from the gateway `pet.info` RPC (shared with
- * the TUI). The animation *state* is derived here from the same activity
- * signals the chat already tracks, mirroring the priority order documented in
- * `agent/pet/state.py` so the Python and TS surfaces never drift.
- */
-
-export type PetState = 'idle' | 'wave' | 'run' | 'failed' | 'review' | 'jump' | 'waiting'
-
-export interface PetInfo {
-  enabled: boolean
-  slug?: string
-  displayName?: string
-  mime?: string
-  spritesheetBase64?: string
-  frameW?: number
-  frameH?: number
-  framesPerState?: number
-  // Real (padding-trimmed) frame count per state row, from the engine. Lets the
-  // canvas step only frames that exist instead of a fixed framesPerState, which
-  // would animate into the transparent padding of ragged sheets (blank flash).
-  framesByState?: Record<string, number>
-  loopMs?: number
-  scale?: number
-  stateRows?: string[]
-}
-
-export interface PetActivity {
-  busy?: boolean
-  awaitingInput?: boolean
-  toolRunning?: boolean
-  reasoning?: boolean
-  error?: boolean
-  justCompleted?: boolean
-  celebrate?: boolean
-}
-
-/**
- * Resolve the animation state from coarse activity signals.
- *
- * Priority (highest first) mirrors `agent.pet.state.derive_pet_state`:
- * error → celebrate → justCompleted → awaitingInput → toolRunning → reasoning →
- * busy → idle. `awaitingInput` (a clarify/approval blocking on the user) outranks
- * the in-flight signals because the turn is paused on you, not working.
- */
-export function derivePetState(activity: PetActivity): PetState {
-  if (activity.error) {
-    return 'failed'
-  }
-
-  if (activity.celebrate) {
-    return 'jump'
-  }
-
-  if (activity.justCompleted) {
-    return 'wave'
-  }
-
-  if (activity.awaitingInput) {
-    return 'waiting'
-  }
-
-  if (activity.toolRunning) {
-    return 'run'
-  }
-
-  if (activity.reasoning) {
-    return 'review'
-  }
-
-  if (activity.busy) {
-    return 'run'
-  }
-
-  return 'idle'
-}
-
-export const $petInfo = atom<PetInfo>({ enabled: false })
-export const $petActivity = atom<PetActivity>({})
-
-/**
- * Pet-local "you have a new message" flag, surfaced as the overlay's mail icon.
- * Deliberately not real unread tracking: it flips on when a turn finishes while
- * the app isn't focused, and off when the user opens the app via the mail icon
- * (or returns to the window). No persistence — it's a glance hint, not state.
- */
-export const $petUnread = atom(false)
-export const markPetUnread = () => $petUnread.set(true)
-export const clearPetUnread = () => $petUnread.set(false)
-
-/** Steady activity flags (toolRunning / reasoning) set + cleared by the stream. */
-export const setPetActivity = (next: Partial<PetActivity>) =>
-  $petActivity.set({ ...$petActivity.get(), ...next })
-
-let flashTimer: ReturnType<typeof setTimeout> | undefined
-
-/** Fire a transient reaction beat (error / celebrate / justCompleted) that
- *  decays back to the steady state after `ms`.
- *
- *  Each beat first clears its siblings so a stale one can't win the priority
- *  race: without this, a completion beat (`celebrate`) would merge on top of a
- *  lingering `error`, and `derivePetState` checks `error` first — so a clean
- *  finish would render the sad/failed pose. */
-export const flashPetActivity = (next: Partial<PetActivity>, ms = 1600) => {
-  setPetActivity({ celebrate: false, error: false, justCompleted: false, ...next })
-  clearTimeout(flashTimer)
-  flashTimer = setTimeout(
-    () => setPetActivity({ celebrate: false, error: false, justCompleted: false }),
-    ms
-  )
-}
-
-export const setPetInfo = (info: PetInfo) => $petInfo.set(info)
-
-/**
- * The live pet state. Derives from the dedicated activity atom, falling back to
- * the always-present `$busy` chat signal so the pet reacts out of the box.
- *
- * `awaitingInput` (a clarify/approval blocking on the user) is an explicit flag
- * on `$petActivity` — set by the controller from `$attentionSessionIds` and
- * mirrored to the pop-out overlay through the same atom, so both surfaces agree
- * without the overlay needing the session list.
- */
-export const $petState = computed(
-  [$petActivity, $busy],
-  (activity, busy): PetState => {
-    const live = activity.busy ?? busy
-
-    return derivePetState({
-      busy: live,
-      awaitingInput: activity.awaitingInput,
-      // Steady flags only count mid-turn — ignore stale ones once at rest so an
-      // interrupted turn can't pin the pet on `run`/`review`.
-      toolRunning: live && activity.toolRunning,
-      reasoning: live && activity.reasoning,
-      error: activity.error,
-      justCompleted: activity.justCompleted,
-      celebrate: activity.celebrate
-    })
-  }
-)

apps/desktop/src/store/session.ts

@@ -218,6 +218,23 @@ export const $lastVisibleMessageIsUser = computed($messages, lastVisibleMessageI
 export const $freshDraftReady = atom(false)
 export const $busy = atom(false)
 export const $awaitingResponse = atom(false)
+// Stored-session id whose most recent resume FAILED terminally (the gateway RPC
+// rejected AND the REST transcript fallback also failed), leaving the window
+// with no runtime and an empty transcript. Drives use-route-resume's self-heal:
+// while this matches the routed session the loader would otherwise latch
+// forever (messagesEmpty && !activeSessionId), so the hook re-attempts the
+// resume on the next render/focus/reconnect instead of stranding the window.
+// Null whenever the active route has a healthy (or in-flight) resume.
+export const $resumeFailedSessionId = atom<string | null>(null)
+// Stored-session id whose resume has EXHAUSTED its bounded auto-retries (the
+// terminal-failure latch above kept failing through all MAX_RESUME_RETRIES
+// attempts). Distinct from $resumeFailedSessionId, which is armed *during* the
+// backoff window too: this fires only once auto-recovery has given up, so the
+// chat view can swap the perpetual loader for an explicit error + manual Retry
+// affordance. A fresh resumeSession() (manual Retry, reconnect, reselect)
+// clears it and resets the retry counter. Null whenever the active route has a
+// healthy, in-flight, or still-auto-retrying resume.
+export const $resumeExhaustedSessionId = atom<string | null>(null)
 export const $currentModel = atom(storedString(COMPOSER_MODEL_KEY) ?? '')
 export const $currentProvider = atom(storedString(COMPOSER_PROVIDER_KEY) ?? '')
 export const $currentReasoningEffort = atom(storedString(COMPOSER_EFFORT_KEY) ?? '')
@@ -262,6 +279,8 @@ export const setActiveSessionId = (next: Updater<string | null>) => updateAtom($
 export const setSelectedStoredSessionId = (next: Updater<string | null>) => updateAtom($selectedStoredSessionId, next)
 export const setMessages = (next: Updater<ChatMessage[]>) => updateAtom($messages, next)
 export const setFreshDraftReady = (next: Updater<boolean>) => updateAtom($freshDraftReady, next)
+export const setResumeFailedSessionId = (next: Updater<string | null>) => updateAtom($resumeFailedSessionId, next)
+export const setResumeExhaustedSessionId = (next: Updater<string | null>) => updateAtom($resumeExhaustedSessionId, next)
 export const setBusy = (next: Updater<boolean>) => updateAtom($busy, next)
 export const setAwaitingResponse = (next: Updater<boolean>) => updateAtom($awaitingResponse, next)
 

apps/desktop/src/store/updates.test.ts

@@ -41,7 +41,7 @@ vi.mock('@/hermes', () => ({
   getActionStatus: (...args: unknown[]) => getActionStatusSpy(...args)
 }))
 
-const { maybeNotifyUpdateAvailable, checkBackendUpdates, $backendUpdateStatus, applyBackendUpdate, $backendUpdateApply } = await import('./updates')
+const { maybeNotifyUpdateAvailable, checkBackendUpdates, $backendUpdateStatus, applyBackendUpdate, $backendUpdateApply, reportBackendContract } = await import('./updates')
 const { setConnection } = await import('./session')
 
 const status = (over: Partial<DesktopUpdateStatus> = {}): DesktopUpdateStatus => ({
@@ -95,6 +95,61 @@ describe('maybeNotifyUpdateAvailable', () => {
   })
 })
 
+describe('reportBackendContract', () => {
+  beforeEach(() => {
+    storage.clear()
+    notifySpy.mockClear()
+    dismissSpy.mockClear()
+    vi.useRealTimers()
+  })
+
+  it('dismisses the toast when the backend meets the contract', () => {
+    reportBackendContract(2)
+    expect(dismissSpy).toHaveBeenCalledWith('backend-contract-skew')
+    expect(notifySpy).not.toHaveBeenCalled()
+  })
+
+  it('warns when the backend is behind (or reports no contract)', () => {
+    reportBackendContract(undefined)
+    expect(notifySpy).toHaveBeenCalledTimes(1)
+    reportBackendContract(1)
+    expect(notifySpy).toHaveBeenCalledTimes(2)
+  })
+
+  it('stays quiet on later session opens once the user closed it', () => {
+    reportBackendContract(1)
+    lastToast().onDismiss() // user closes it → cooldown starts
+    notifySpy.mockClear()
+
+    // Opening another pre-existing session re-runs the check within cooldown.
+    reportBackendContract(1)
+    expect(notifySpy).not.toHaveBeenCalled()
+  })
+
+  it('reminds again after the cooldown elapses', () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(0)
+
+    reportBackendContract(1)
+    lastToast().onDismiss()
+    notifySpy.mockClear()
+
+    vi.setSystemTime(25 * 60 * 60 * 1000) // > 24h cooldown
+    reportBackendContract(1)
+    expect(notifySpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('clears the snooze once the backend catches up, so a regression warns again', () => {
+    reportBackendContract(1)
+    lastToast().onDismiss()
+    notifySpy.mockClear()
+
+    reportBackendContract(2) // backend updated → satisfied, snooze cleared
+    reportBackendContract(1) // a later regression must warn immediately
+    expect(notifySpy).toHaveBeenCalledTimes(1)
+  })
+})
+
 describe('checkBackendUpdates', () => {
   beforeEach(() => {
     storage.clear()

apps/desktop/src/store/updates.ts

@@ -91,26 +91,60 @@ function isUpdateToastSnoozed(): boolean {
 // v2: requires the file.attach RPC (remote-gateway non-image file upload).
 const REQUIRED_BACKEND_CONTRACT = 2
 const SKEW_TOAST_ID = 'backend-contract-skew'
+// The contract check runs on every session.resume (applyRuntimeInfo), so
+// without a snooze the warning re-popped on every thread the user opened, even
+// right after they closed it. Mirror the update toast: persist a cooldown when
+// the user dismisses it. It still reminds again after the window if the backend
+// is still behind, and clears immediately once the backend catches up.
+const SKEW_TOAST_SNOOZE_KEY = 'hermes:backend-skew-toast-snooze-until'
+const SKEW_TOAST_COOLDOWN_MS = 24 * 60 * 60 * 1000
+
+function snoozeSkewToast(): void {
+  persistString(SKEW_TOAST_SNOOZE_KEY, String(Date.now() + SKEW_TOAST_COOLDOWN_MS))
+}
+
+function isSkewToastSnoozed(): boolean {
+  const until = Number(storedString(SKEW_TOAST_SNOOZE_KEY) || 0)
+
+  return Number.isFinite(until) && Date.now() < until
+}
 
 /**
  * Guard against a desktop GUI talking to a backend that predates its contract
  * (e.g. a bb/gui-built app pointed at a `main` checkout). Rather than failing
- * cryptically downstream, surface a persistent warning with a one-click align
- * that runs the normal update flow (which self-heals to the right branch).
+ * cryptically downstream, surface a warning with a one-click align that runs
+ * the normal update flow (which self-heals to the right branch).
+ *
+ * Runs on every session open; closing the toast snoozes it for a cooldown so it
+ * doesn't nag on every thread switch.
  */
 export function reportBackendContract(contract: number | undefined): void {
   if ((contract ?? 0) >= REQUIRED_BACKEND_CONTRACT) {
     dismissNotification(SKEW_TOAST_ID)
+    // Backend caught up — forget any prior snooze so a future regression warns
+    // immediately rather than staying silent for the rest of the window.
+    persistString(SKEW_TOAST_SNOOZE_KEY, null)
 
     return
   }
 
+  if (isSkewToastSnoozed()) {
+    return
+  }
+
   notify({
-    action: { label: translateNow('notifications.updateHermes'), onClick: () => void applyBackendUpdate() },
+    action: {
+      label: translateNow('notifications.updateHermes'),
+      onClick: () => {
+        snoozeSkewToast()
+        void applyBackendUpdate()
+      }
+    },
     durationMs: 0,
     id: SKEW_TOAST_ID,
     kind: 'warning',
     message: translateNow('notifications.backendOutOfDateMessage'),
+    onDismiss: () => snoozeSkewToast(),
     title: translateNow('notifications.backendOutOfDateTitle')
   })
 }

cli.py

@@ -60,7 +60,7 @@ from prompt_toolkit.history import FileHistory
 from prompt_toolkit.styles import Style as PTStyle
 from prompt_toolkit.patch_stdout import patch_stdout
 from prompt_toolkit.application import Application
-from prompt_toolkit.layout import Layout, HSplit, Window, FormattedTextControl, ConditionalContainer, WindowAlign
+from prompt_toolkit.layout import Layout, HSplit, Window, FormattedTextControl, ConditionalContainer
 from prompt_toolkit.layout.processors import Processor, Transformation, PasswordProcessor, ConditionalProcessor
 from prompt_toolkit.filters import Condition
 from prompt_toolkit.layout.dimension import Dimension
@@ -3572,25 +3572,6 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
         self._last_scrollback_tool: str = ""  # last tool name printed to scrollback (for "new" dedup)
         self._command_running = False
         self._command_status = ""
-        # Petdex mascot (opt-in via display.pet). The base CLI mirrors the TUI's
-        # PetPane: a half-block sprite above the prompt that reacts to agent
-        # activity. Lazily resolved; an invalidate timer drives the animation.
-        self._pet_renderer = None  # agent.pet.render.PetRenderer | None
-        self._pet_slug: str = ""
-        self._pet_enabled: bool = False
-        self._pet_cols: int = 18
-        self._pet_scale: float = 0.7
-        self._pet_frames_cache: dict = {}  # state -> list[grid]
-        self._pet_frame_idx: int = 0
-        self._pet_lock = threading.Lock()
-        self._pet_cfg_checked: float = 0.0
-        self._pet_anim_running: bool = False
-        self._pet_anim_thread = None
-        # Transient reaction beats (wave/jump/failed) + steady reasoning flag.
-        self._pet_event: str = ""
-        self._pet_event_until: float = 0.0
-        self._pet_reasoning: bool = False
-        self._pet_turn_error: bool = False
         self._attached_images: list[Path] = []
         self._image_counter = 0
         self.preloaded_skills: list[str] = []
@@ -4131,218 +4112,6 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
             return f"  {txt}  ({elapsed_str})"
         return f"  {txt}"
 
-    # ── Petdex mascot (base-CLI pet pane) ───────────────────────────────
-    #
-    # Parity with the TUI: a half-block sprite rendered as a prompt_toolkit
-    # window above the prompt, reacting to agent state and animated by a timer
-    # that calls ``app.invalidate()``. Half-blocks only — the crisp Kitty image
-    # protocol can't coexist with prompt_toolkit's patch_stdout output layer
-    # (raw image escapes get swallowed/mangled), so we use truecolor styled
-    # text, which prompt_toolkit renders natively in any 24-bit terminal.
-
-    _PET_FRAME_INTERVAL = 0.16
-    _PET_CFG_INTERVAL = 2.5
-
-    def _pet_resolve_config(self) -> None:
-        """(Re)resolve the active pet from config — picks up live enable/disable/
-
-        switch made via ``/pet`` or ``hermes pets`` without a restart, mirroring
-        the TUI's steady poll. Cheap and fail-open: any problem disables the pet.
-        """
-        try:
-            from agent.pet import constants, store
-            from agent.pet.render import PetRenderer
-            from hermes_cli.config import load_config
-
-            cfg = load_config()
-            display = cfg.get("display", {}) if isinstance(cfg.get("display"), dict) else {}
-            pet_cfg = display.get("pet", {}) if isinstance(display.get("pet"), dict) else {}
-
-            enabled = bool(pet_cfg.get("enabled"))
-            slug = str(pet_cfg.get("slug", "") or "")
-            scale = float(pet_cfg.get("scale", constants.DEFAULT_SCALE) or constants.DEFAULT_SCALE)
-            cols = constants.resolve_cols(scale, pet_cfg.get("unicode_cols", 0))
-
-            if not enabled:
-                with self._pet_lock:
-                    self._pet_enabled = False
-                    self._pet_renderer = None
-                    self._pet_frames_cache.clear()
-                return
-
-            pet = store.resolve_active_pet(slug)
-            if pet is None or not pet.exists:
-                with self._pet_lock:
-                    self._pet_enabled = False
-                    self._pet_renderer = None
-                    self._pet_frames_cache.clear()
-                return
-
-            with self._pet_lock:
-                # Rebuild only when the resolved pet or geometry changes.
-                if (
-                    self._pet_renderer is None
-                    or self._pet_slug != pet.slug
-                    or self._pet_cols != cols
-                    or self._pet_scale != scale
-                ):
-                    self._pet_renderer = PetRenderer(
-                        str(pet.spritesheet), mode="unicode", scale=scale, unicode_cols=cols
-                    )
-                    self._pet_slug = pet.slug
-                    self._pet_cols = cols
-                    self._pet_scale = scale
-                    self._pet_frames_cache.clear()
-                    self._pet_frame_idx = 0
-                self._pet_enabled = True
-        except Exception:
-            with self._pet_lock:
-                self._pet_enabled = False
-                self._pet_renderer = None
-
-    def _pet_flash(self, state: str, secs: float = 1.6) -> None:
-        """Briefly force a transient reaction (wave/jump/failed) before resting."""
-        self._pet_event = state
-        self._pet_event_until = time.monotonic() + secs
-
-    def _pet_react_turn_end(self) -> None:
-        """Flash the end-of-turn beat: failed on error, jump on a finished plan, else wave."""
-        if not self._pet_enabled:
-            return
-        from agent.pet.state import todos_all_done
-
-        if self._pet_turn_error:
-            self._pet_flash("failed")
-            return
-        try:
-            store = getattr(self.agent, "_todo_store", None)
-            done = todos_all_done(store.read()) if store else False
-        except Exception:
-            done = False
-        self._pet_flash("jump" if done else "wave")
-
-    def _derive_pet_state(self) -> str:
-        """Map current CLI activity to a pet animation state.
-
-        A transient reaction beat (wave/jump/failed) wins while it's live;
-        otherwise the steady state comes from the shared
-        :func:`agent.pet.state.derive_pet_state` so the CLI can't drift from the
-        TUI/desktop priority order.
-        """
-        if self._pet_event and time.monotonic() < self._pet_event_until:
-            return self._pet_event
-        self._pet_event = ""
-        from agent.pet.state import derive_pet_state
-
-        # A live blocking modal (approval / clarify / sudo / secret / slash
-        # confirm) means the agent is paused on the user → the `waiting` pose,
-        # which outranks the in-flight signals in derive_pet_state.
-        awaiting_input = bool(
-            self._approval_state
-            or self._clarify_state
-            or self._sudo_state
-            or self._secret_state
-            or getattr(self, "_slash_confirm_state", None)
-        )
-
-        return derive_pet_state(
-            awaiting_input=awaiting_input,
-            busy=getattr(self, "_agent_running", False),
-            reasoning=self._pet_reasoning,
-        ).value
-
-    def _pet_frames_for(self, state: str) -> list:
-        """Return (and cache) the half-block grids for one state."""
-        cached = self._pet_frames_cache.get(state)
-        if cached is not None:
-            return cached
-        renderer = self._pet_renderer
-        if renderer is None:
-            return []
-        try:
-            count = renderer.frame_count(state) or 1
-            grids = [renderer.cells(state, i, cols=self._pet_cols) for i in range(count)]
-        except Exception:
-            grids = []
-        self._pet_frames_cache[state] = grids
-        return grids
-
-    def _pet_fragments(self):
-        """Return prompt_toolkit FormattedText for the current pet frame, or []."""
-        with self._pet_lock:
-            if not self._pet_enabled or self._pet_renderer is None:
-                return []
-            state = self._derive_pet_state()
-            grids = self._pet_frames_for(state)
-            if not grids:
-                return []
-            grid = grids[self._pet_frame_idx % len(grids)]
-
-        frags = []
-        for y, row in enumerate(grid):
-            if y:
-                frags.append(("", "\n"))
-            for top, bottom in row:
-                tr, tg, tb, ta = top
-                br, bg, bb, ba = bottom
-                top_op = ta >= 32
-                bot_op = ba >= 32
-                if not top_op and not bot_op:
-                    frags.append(("", " "))
-                elif top_op and bot_op:
-                    frags.append((f"fg:#{tr:02x}{tg:02x}{tb:02x} bg:#{br:02x}{bg:02x}{bb:02x}", "▀"))
-                elif top_op:
-                    # Upper half only — leave the lower half the terminal's bg
-                    # instead of painting it black (cleaner on light themes).
-                    frags.append((f"fg:#{tr:02x}{tg:02x}{tb:02x}", "▀"))
-                else:
-                    frags.append((f"fg:#{br:02x}{bg:02x}{bb:02x}", "▄"))
-        return frags
-
-    def _pet_widget_height(self) -> int:
-        """Visible rows for the pet window — 0 collapses it when no pet shows."""
-        with self._pet_lock:
-            if not self._pet_enabled or self._pet_renderer is None:
-                return 0
-            grids = self._pet_frames_for(self._derive_pet_state())
-            if not grids or not grids[0]:
-                return 0
-            return len(grids[0])
-
-    def _pet_anim_loop(self) -> None:
-        """Advance the frame + invalidate on a timer while a pet is enabled."""
-        while self._pet_anim_running:
-            time.sleep(self._PET_FRAME_INTERVAL)
-            now = time.monotonic()
-            if now - self._pet_cfg_checked >= self._PET_CFG_INTERVAL:
-                self._pet_cfg_checked = now
-                self._pet_resolve_config()
-            if not self._pet_enabled:
-                continue
-            with self._pet_lock:
-                self._pet_frame_idx += 1
-            app = getattr(self, "_app", None)
-            if app is not None:
-                try:
-                    app.invalidate()
-                except Exception:
-                    pass
-
-    def _pet_start_anim(self) -> None:
-        if self._pet_anim_running:
-            return
-        self._pet_resolve_config()
-        self._pet_anim_running = True
-        self._pet_anim_thread = threading.Thread(target=self._pet_anim_loop, daemon=True)
-        self._pet_anim_thread.start()
-
-    def _pet_stop_anim(self) -> None:
-        self._pet_anim_running = False
-        thread = self._pet_anim_thread
-        if thread is not None:
-            thread.join(timeout=0.3)
-        self._pet_anim_thread = None
-
     def _voice_record_key_label(self) -> str:
         """Return the configured voice push-to-talk key formatted for UI.
 
@@ -7665,8 +7434,6 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
         elif canonical == "personality":
             # Use original case (handler lowercases the personality name itself)
             self._handle_personality_command(cmd_original)
-        elif canonical == "pet":
-            self._handle_pet_command(cmd_original)
         elif canonical == "retry":
             retry_msg = self.retry_last()
             if retry_msg and hasattr(self, '_pending_input'):
@@ -9206,15 +8973,6 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
         stacked line to scrollback on tool.completed so users can see the
         full history of tool calls (not just the current one in the spinner).
         """
-        # Feed the pet: tools mean "running" (not reasoning); a failed tool
-        # latches the turn so it ends on a sulk.
-        if event_type == "tool.started":
-            self._pet_reasoning = False
-        elif event_type == "tool.completed" and kwargs.get("is_error"):
-            self._pet_turn_error = True
-        elif event_type and event_type.startswith("reasoning"):
-            self._pet_reasoning = True
-
         if event_type == "tool.completed":
             self._tool_start_time = 0.0
             # Print stacked scrollback line for "all" / "new" modes
@@ -11167,7 +10925,6 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
                 spinner_widget,
                 spacer,
                 *self._get_extra_tui_widgets(),
-                getattr(self, "_pet_widget", None),
                 status_bar,
                 input_rule_top,
                 image_bar,
@@ -12267,6 +12024,7 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
 
         # Create the input area with multiline (Alt+Enter), autocomplete, and paste handling
         from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
+        from prompt_toolkit.completion import ThreadedCompleter
 
 
         _completer = SlashCommandCompleter(
@@ -12282,7 +12040,13 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
             wrap_lines=True,
             read_only=Condition(lambda: bool(cli_ref._command_running)),
             history=FileHistory(str(self._history_file)),
-            completer=_completer,
+            # complete_while_typing fires the completer on every keystroke. The
+            # completer does blocking work — fuzzy @-file indexing shells out to
+            # rg/fd (up to a 2s timeout) and path completion hits os.listdir/stat
+            # — so running it inline would stall the render loop on each key (very
+            # noticeable on WSL2/slow filesystems). ThreadedCompleter moves it off
+            # the UI event loop, keeping typing responsive.
+            completer=ThreadedCompleter(_completer),
             complete_while_typing=True,
             auto_suggest=SlashCommandAutoSuggest(
                 history_suggest=AutoSuggestFromHistory(),
@@ -12509,16 +12273,6 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
             wrap_lines=True,
         )
 
-        # Petdex mascot — right-aligned half-block sprite above the prompt,
-        # mirroring the TUI's PetPane. Collapses to height 0 when no pet is
-        # enabled, so it's a no-op for everyone else. The _pet_anim_loop thread
-        # advances frames + invalidates; align=RIGHT pins it to the edge.
-        self._pet_widget = Window(
-            content=FormattedTextControl(self._pet_fragments),
-            height=self._pet_widget_height,
-            align=WindowAlign.RIGHT,
-        )
-
         spacer = Window(
             content=FormattedTextControl(get_hint_text),
             height=get_hint_height,
@@ -13289,8 +13043,6 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
 
                     # Regular chat - run agent
                     self._agent_running = True
-                    self._pet_turn_error = False
-                    self._pet_reasoning = False
                     app.invalidate()  # Refresh status line
 
                     try:
@@ -13301,8 +13053,6 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
                         self._tool_start_time = 0.0
                         self._pending_tool_info.clear()
                         self._last_scrollback_tool = ""
-                        self._pet_reasoning = False
-                        self._pet_react_turn_end()
 
                         app.invalidate()  # Refresh status line
 
@@ -13535,8 +13285,6 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
                 # The app enables focus reporting + mouse tracking; record that
                 # so _run_cleanup resets them on exit (#36823).
                 _mark_tui_input_modes_active()
-                # Drive the petdex mascot animation (no-op when no pet enabled).
-                self._pet_start_anim()
                 app.run()
         except (EOFError, KeyboardInterrupt, BrokenPipeError):
             pass
@@ -13563,7 +13311,6 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin):
                 raise
         finally:
             self._should_exit = True
-            self._pet_stop_anim()
             # Interrupt the agent immediately so its daemon thread stops making
             # API calls and exits promptly (agent_thread is daemon, so the
             # process will exit once the main thread finishes, but interrupting

docker/stage2-hook.sh

@@ -28,14 +28,13 @@ as_hermes() { [ "$(id -u)" = 0 ] || { "$@"; return; }; s6-setuidgid hermes "$@";
 # arbitrary host UID (the classic `--user $(id -u):$(id -g)` invocation people
 # used in the tini era to make container-written files match their host user).
 #
-# Under s6-overlay this no longer works: the bootstrap (UID remap, volume +
-# build-tree chown, config seeding) all require root, and they're skipped when
-# the container starts non-root. The baked image trees (/opt/data, /opt/hermes/
-# .venv, ui-tui, node_modules) stay owned by the hermes build UID (10000), so an
-# arbitrary `--user` UID can't write them — the runtime then fails with EACCES
-# on a bind mount, or hard-crashes on a named volume (Docker initialises the
-# volume from the image as UID 10000, and the non-root start can't even `cd`
-# into $HERMES_HOME). See #34837 for the supervision-tree side of this.
+# Under s6-overlay this no longer works: the bootstrap (UID remap, data-volume
+# ownership, config seeding) requires root, and it is skipped when the container
+# starts non-root. The baked install tree under /opt/hermes is intentionally
+# root-owned and non-writable; mutable runtime state must live under
+# $HERMES_HOME. An arbitrary `--user` UID therefore cannot repair or populate
+# the data volume, and startup fails with EACCES. See #34837 for the
+# supervision-tree side of this.
 #
 # The supported way to match host-side ownership is to start as root (the image
 # default) and pass HERMES_UID/HERMES_GID — or the PUID/PGID aliases — which the
@@ -53,9 +52,10 @@ if [ "$cur_uid" != 0 ] && [ "$cur_uid" != "$(id -u hermes)" ]; then
 [stage2] ERROR: container started with --user $cur_uid (an arbitrary, non-hermes UID).
 
 This is not supported under the s6-overlay image. The container bootstrap
-(UID remap, volume ownership, dependency installs) needs to start as root,
-and the baked image directories are owned by the hermes user (UID $(id -u hermes)),
-so a pinned --user UID cannot write them — startup will fail.
+(UID remap, data-volume ownership, config seeding) needs to start as root,
+and the baked /opt/hermes install tree is intentionally root-owned and
+non-writable, so a pinned --user UID cannot repair startup state — startup
+will fail.
 
 To make container-written files match your HOST user, DON'T use --user.
 Start the container as root (the default) and pass your host UID/GID instead:
@@ -207,49 +207,13 @@ if [ "$needs_chown" = true ]; then
     done
 fi
 
-# --- Fix ownership of build trees under $INSTALL_DIR ---
-# Hermes-owned trees under $INSTALL_DIR must be re-chowned whenever the
-# runtime hermes UID no longer owns them — otherwise:
-#   - .venv: lazy_deps.py cannot install platform packages (discord.py,
-#     telegram, slack, etc.) with EACCES (#15012, #21100)
-#   - ui-tui: esbuild rebuilds dist/entry.js on every TUI launch (when
-#     the source mtime is newer than dist/ or when HERMES_TUI_FORCE_BUILD
-#     is set) and writes to ui-tui/dist/. Without this chown the new
-#     hermes UID can't write the build output (#28851).
-#   - gateway: Python writes __pycache__ and runtime artifacts beneath the
-#     gateway package on first import. After a UID remap those source-owned
-#     paths still belong to the build-time UID (10000) unless repaired here,
-#     producing EACCES for the supervised gateway (#27221).
-#   - node_modules: root-level dependencies (puppeteer, web tooling)
-#     that runtime code may walk/update.
-# The set mirrors the build-time `chown -R hermes:hermes` line in the
-# Dockerfile — keep them in sync if the Dockerfile chown set changes.
-# These are under $INSTALL_DIR (not $HERMES_HOME), so the bind-mount
-# concern doesn't apply — recursive is fine.
-#
-# This MUST be gated independently of the $HERMES_HOME ownership check
-# above. `usermod -u <new> hermes` re-chowns the hermes home dir
-# ($HERMES_HOME == /opt/data) to the new UID as a side effect, so after a
-# HERMES_UID/PUID remap `stat $HERMES_HOME` always already matches the new
-# UID and `needs_chown` is false — but the build trees under /opt/hermes
-# are NOT touched by usermod and remain owned by the build-time UID
-# (10000). Gating them on $HERMES_HOME ownership (as #35027 did) silently
-# skipped this chown on the common PUID/NAS path, regressing lazy installs
-# and TUI rebuilds. Probe the build trees directly instead: chown only
-# when the venv is not already owned by the runtime hermes UID. Idempotent
-# and skips the expensive recursive chown on every restart once ownership
-# is settled.
-venv_owner=$(stat -c %u "$INSTALL_DIR/.venv" 2>/dev/null || echo "")
-if [ -n "$venv_owner" ] && [ "$venv_owner" != "$actual_hermes_uid" ]; then
-    echo "[stage2] Fixing ownership of build trees under $INSTALL_DIR to hermes ($actual_hermes_uid)"
-    chown -R hermes:hermes \
-        "$INSTALL_DIR/.venv" \
-        "$INSTALL_DIR/ui-tui" \
-        "$INSTALL_DIR/gateway" \
-        "$INSTALL_DIR/node_modules" \
-        2>/dev/null || \
-        echo "[stage2] Warning: chown of build trees failed (rootless container?) — continuing"
-fi
+# --- Immutable install tree ---
+# Do not chown runtime code or dependency trees under $INSTALL_DIR back to the
+# hermes user. Hosted/container instances keep mutable state under
+# $HERMES_HOME (/opt/data) and run with PYTHONDONTWRITEBYTECODE plus
+# HERMES_DISABLE_LAZY_INSTALLS=1. Keeping /opt/hermes root-owned and
+# non-writable prevents an agent session from self-modifying the installed
+# source, venv, TUI bundle, or node_modules and bricking the gateway.
 
 # Always reset ownership of $HERMES_HOME/profiles to hermes on every
 # boot. Profile dirs and files can land owned by root when commands
@@ -327,13 +291,25 @@ as_hermes mkdir -p \
     "$HERMES_HOME/pairing" \
     "$HERMES_HOME/platforms/pairing"
 
-# --- Install-method stamp (read by detect_install_method() in hermes status) ---
-# Preserved from the tini-era entrypoint (PR #27843). Must be written as
-# the hermes user so ownership matches the file's documented owner.
-# tee is invoked directly via s6-setuidgid (no `sh -c` wrapper) for the
-# same shell-metacharacter safety described above.
-printf 'docker\n' | as_hermes tee "$HERMES_HOME/.install_method" >/dev/null \
-    || true
+# --- Install-method stamp ---
+# The 'docker' stamp is baked into the immutable install tree at
+# /opt/hermes/.install_method (see Dockerfile), NOT written here into
+# $HERMES_HOME. detect_install_method() reads the code-scoped stamp first.
+#
+# Why we no longer stamp $HERMES_HOME: it is a shared DATA volume, commonly
+# bind-mounted from the host (~/.hermes:/opt/data) and sometimes shared with a
+# host-side Desktop/CLI install. Stamping 'docker' here clobbered that host
+# install's marker, so its in-app updater read 'docker' and refused to run
+# 'hermes update'. To heal homes already poisoned by older images, remove a
+# stale 'docker' stamp from $HERMES_HOME if one is present (the host install's
+# own installer re-creates its code-scoped stamp; a genuine container relies on
+# the baked /opt/hermes stamp, so deleting the data-dir copy is safe).
+if [ -f "$HERMES_HOME/.install_method" ]; then
+    stamped="$(tr -d '[:space:]' < "$HERMES_HOME/.install_method" 2>/dev/null || true)"
+    if [ "$stamped" = "docker" ]; then
+        rm -f "$HERMES_HOME/.install_method" 2>/dev/null || true
+    fi
+fi
 
 # --- Seed config files (only on first boot) ---
 seed_one() {