From 6cc7d54e1ad601e02fc9afac6d30b84e847ceac8 Mon Sep 17 00:00:00 2001
From: Alex Fournier <afournier@nvidia.com>
Date: Fri, 11 Sep 2026 08:38:33 -0700
Subject: [PATCH 01/61] fix(relay): include cwd in session and turn scopes

Signed-off-by: Alex Fournier <afournier@nvidia.com>
---
 agent/relay_cwd.py                         |  88 +++++++++++++++++
 agent/relay_runtime.py                     |  51 ++++++++--
 agent/runtime_cwd.py                       |  10 ++
 agent/turn_facade.py                       |   6 ++
 docs/observability/relay-shared-metrics.md |  14 +++
 tests/agent/test_relay_atof_cwd.py         | 109 +++++++++++++++++++++
 tests/agent/test_relay_cwd.py              |  61 ++++++++++++
 tests/agent/test_relay_session_segments.py |  33 ++++++-
 8 files changed, 360 insertions(+), 12 deletions(-)
 create mode 100644 agent/relay_cwd.py
 create mode 100644 tests/agent/test_relay_atof_cwd.py
 create mode 100644 tests/agent/test_relay_cwd.py

diff --git a/agent/relay_cwd.py b/agent/relay_cwd.py
new file mode 100644
index 0000000000..63e978b472
--- /dev/null
+++ b/agent/relay_cwd.py
@@ -0,0 +1,88 @@
+"""Resolve logical working directories for Hermes-owned Relay scopes."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_CWD_SENTINELS = frozenset({"", ".", "./", "auto", "cwd"})
+
+
+def _clean_cwd(value: Any) -> str:
+    if not isinstance(value, str):
+        return ""
+    value = value.strip()
+    return "" if value.lower() in _CWD_SENTINELS else value
+
+
+def _recorded_cwd(key: str) -> str:
+    if not key:
+        return ""
+    from tools.terminal_tool import get_session_cwd
+
+    return _clean_cwd(get_session_cwd(key))
+
+
+def resolve_relay_scope_cwds(
+    agent: Any, task_id: str, session_id: str, platform: str
+) -> tuple[str, str]:
+    """Return logical ``(session_cwd, turn_cwd)`` for Relay scope input.
+
+    A task may use a worktree distinct from its owning session. Preserve remote paths as
+    declared and omit unknown paths instead of substituting the Hermes host's cwd.
+    """
+    try:
+        task_cwd = _recorded_cwd(task_id)
+    except Exception:
+        logger.debug("Unable to read the Relay turn cwd", exc_info=True)
+        task_cwd = ""
+
+    session_cwd = ""
+    try:
+        from agent.runtime_cwd import scoped_session_cwd
+
+        session_cwd = _clean_cwd(scoped_session_cwd())
+    except Exception:
+        logger.debug("Unable to read the scoped Relay session cwd", exc_info=True)
+
+    if not session_cwd:
+        try:
+            from gateway.session_context import get_session_env
+
+            session_key = get_session_env("HERMES_SESSION_KEY", "")
+            for key in dict.fromkeys(key for key in (session_key, session_id) if key):
+                if recorded := _recorded_cwd(key):
+                    session_cwd = recorded
+                    break
+        except Exception:
+            logger.debug("Unable to read the recorded Relay session cwd", exc_info=True)
+
+    if not session_cwd:
+        session_cwd = _clean_cwd(getattr(agent, "session_cwd", None))
+
+    backend = ""
+    if not session_cwd:
+        try:
+            from tools.terminal_scope import terminal_env
+
+            backend = terminal_env("TERMINAL_ENV", "local").strip().lower()
+            session_cwd = _clean_cwd(terminal_env("TERMINAL_CWD", ""))
+        except Exception:
+            logger.debug(
+                "Unable to read the configured Relay session cwd", exc_info=True
+            )
+
+    if not session_cwd and platform == "cli" and backend in {"", "local"}:
+        try:
+            from agent.runtime_cwd import resolve_agent_cwd
+
+            session_cwd = _clean_cwd(str(resolve_agent_cwd()))
+        except Exception:
+            logger.debug("Unable to resolve the local Relay session cwd", exc_info=True)
+
+    turn_cwd = task_cwd or session_cwd
+    if platform in {"subagent", "cron"} and task_cwd:
+        session_cwd = task_cwd
+    return session_cwd or turn_cwd, turn_cwd
diff --git a/agent/relay_runtime.py b/agent/relay_runtime.py
index a204ec5b76..66ed367e88 100644
--- a/agent/relay_runtime.py
+++ b/agent/relay_runtime.py
@@ -73,6 +73,11 @@ def runtime_metadata(runtime_id: str, **extra: Any) -> dict[str, Any]:
     return {RUNTIME_SCHEMA_KEY: RUNTIME_SCHEMA_VERSION, RUNTIME_INSTANCE_KEY: runtime_id, **extra}
 
 
+def _scope_input(cwd: Any = None) -> dict[str, str]:
+    """Return Relay scope input for a known logical working directory."""
+    return {"cwd": cwd.strip()} if isinstance(cwd, str) and cwd.strip() else {}
+
+
 def _run_on_daemon_thread(
     fn: Callable[[], Any], *, name: str, timeout: float | None = None, timeout_message: str = ""
 ) -> Any:
@@ -154,6 +159,7 @@ class RelaySession:
     segment_turns: int = 0  # turns completed within the current segment
     rotate_pending: bool = False  # consumed at next begin_turn
     close_pending: bool = False  # rotating compaction hit a live turn; end_turn consumes it
+    cwd: str = ""  # latest logical working directory; reused when a session segment rotates
 
 
 def _load_segments_config() -> dict[str, Any]:
@@ -387,7 +393,7 @@ class RelayRuntime:
             scope_metadata["nemo_relay_scope_role"] = "subagent"
         context = contextvars.Context()
         args = (self.relay.scope.push, SESSION_SCOPE, self.relay.ScopeType.Agent)
-        push_kwargs.update(handle=parent_handle, metadata=scope_metadata, input={})
+        push_kwargs.update(handle=parent_handle, metadata=scope_metadata, input=_scope_input(session.cwd))
         try:
             future = _scope_op_executor().submit(context.run, *args, **push_kwargs)
             session.handle = future.result(timeout=_SCOPE_OP_TIMEOUT)
@@ -398,7 +404,12 @@ class RelayRuntime:
         session.context = context
 
     def ensure_session(
-        self, event: dict[str, Any], *, data: Any = None, metadata: dict[str, Any] | None = None
+        self,
+        event: dict[str, Any],
+        *,
+        data: Any = None,
+        metadata: dict[str, Any] | None = None,
+        cwd: str | None = None,
     ) -> RelaySession | None:
         """Return the existing session scope or create it once."""
         session_id = _session_id(event)
@@ -415,6 +426,8 @@ class RelayRuntime:
         with session.lock:
             if session.closing:
                 return None
+            if isinstance(cwd, str) and cwd.strip():
+                session.cwd = cwd.strip()
             if session.handle is None:
                 self._open_session_scope(
                     session, {**(metadata or {}), **runtime_metadata(self.runtime_id)},
@@ -455,7 +468,8 @@ class RelayRuntime:
                 )
 
     def register_subagent(
-        self, event: dict[str, Any], *, metadata: dict[str, Any] | None = None
+        self, event: dict[str, Any], *, metadata: dict[str, Any] | None = None,
+        cwd: str | None = None,
     ) -> RelaySession | None:
         """Open a child Agent scope under its spawning turn when available."""
         parent_session_id = str(event.get("parent_session_id") or "")
@@ -473,7 +487,7 @@ class RelayRuntime:
             self._subagent_parents[child_session_id] = parent_session_id
             if parent_handle is not None:
                 self._subagent_parent_handles[child_session_id] = parent_handle
-        return self.ensure_session({"session_id": child_session_id}, metadata=metadata)
+        return self.ensure_session({"session_id": child_session_id}, metadata=metadata, cwd=cwd)
 
     def unregister_subagent(self, event: dict[str, Any]) -> None:
         """Close a delegated session and forget its parent relationship."""
@@ -799,6 +813,7 @@ class ConversationLease:
     host: RelayHost
     session: RelaySession | None
     parent_session_id: str = ""
+    turn_cwd: str = ""
     released: bool = False
 
     def live_runtime(self) -> RelayRuntime | None:
@@ -898,29 +913,44 @@ class RelaySessionCoordinator:
                 logger.warning("Hermes Relay session initializer failed: %s", name, exc_info=True)
 
     def acquire_conversation(
-        self, *, profile_key: str, session_id: str, platform: str, parent_session_id: str = "", model: str = "",
+        self,
+        *,
+        profile_key: str,
+        session_id: str,
+        platform: str,
+        parent_session_id: str = "",
+        model: str = "",
+        session_cwd: str | None = None,
+        turn_cwd: str | None = None,
     ) -> ConversationLease:
         host = self.registry.for_profile(profile_key) or NoopRelayRuntime(profile_key, "Relay host creation was disabled")
         session = None
         if isinstance(host, RelayRuntime):
             context = {
                 "profile_key": profile_key, "session_id": session_id, "platform": platform,
-                "parent_session_id": parent_session_id, "model": model,
+                "parent_session_id": parent_session_id, "model": model, "cwd": session_cwd,
             }
             session = _warn_on_error("conversation initialization", self._open_conversation_session, host, context)
+        effective_turn_cwd = (
+            _scope_input(turn_cwd).get("cwd") or _scope_input(session_cwd).get("cwd") or ""
+        )
+        if not effective_turn_cwd and session is not None:
+            with session.lock:
+                effective_turn_cwd = session.cwd
         return ConversationLease(
             profile_key=profile_key, session_id=session_id, platform=platform, host=host,
-            session=session, parent_session_id=parent_session_id,
+            session=session, parent_session_id=parent_session_id, turn_cwd=effective_turn_cwd,
         )
 
     def _open_conversation_session(self, host: RelayRuntime, context: dict[str, Any]) -> RelaySession | None:
         self._prepare_session(host, context)
         session_id, parent_session_id = context["session_id"], context["parent_session_id"]
         metadata = {"hermes.execution_surface": context["platform"] or "unknown"}
+        cwd = context.get("cwd")
         if parent_session_id and parent_session_id != session_id:
             event = {"parent_session_id": parent_session_id, "child_session_id": session_id}
-            return host.register_subagent(event, metadata=metadata)
-        return host.ensure_session({"session_id": session_id}, metadata=metadata)
+            return host.register_subagent(event, metadata=metadata, cwd=cwd)
+        return host.ensure_session({"session_id": session_id}, metadata=metadata, cwd=cwd)
 
     def begin_turn(self, lease: ConversationLease, *, turn_id: str, task_id: str) -> RelayTurnContext:
         if lease.released:
@@ -944,7 +974,8 @@ class RelaySessionCoordinator:
             _warn_on_error("segment rotation", self._maybe_rotate_segment, host, lease.session)
             turn.handle = _warn_on_error(
                 "turn initialization", host.run_in_session, lease.session, host.relay.scope.push,
-                TURN_SCOPE, host.relay.ScopeType.Function, handle=lease.session.handle, input={},
+                TURN_SCOPE, host.relay.ScopeType.Function, handle=lease.session.handle,
+                input=_scope_input(lease.turn_cwd),
                 metadata=runtime_metadata(host.runtime_id, **{"hermes.execution_surface": lease.platform or "unknown"}),
                 timeout=_SCOPE_OP_TIMEOUT,
             )
diff --git a/agent/runtime_cwd.py b/agent/runtime_cwd.py
index b70f084c97..71d49587a2 100644
--- a/agent/runtime_cwd.py
+++ b/agent/runtime_cwd.py
@@ -44,6 +44,16 @@ def clear_session_cwd() -> None:
     _SESSION_CWD.set("")
 
 
+def scoped_session_cwd() -> str:
+    """Return the current session's declared cwd without local path validation.
+
+    Remote and container paths may not exist on the Hermes host. Callers that only need
+    logical workspace identity should preserve the declared value instead of resolving it.
+    """
+    value = _SESSION_CWD.get()
+    return "" if value is _UNSET else str(value).strip()
+
+
 def scope_terminal_cwd() -> str:
     """Scope-aware TERMINAL_CWD value (may be empty) — every cwd consumer reads through this.
 
diff --git a/agent/turn_facade.py b/agent/turn_facade.py
index acd3bc97ed..676f7886f7 100644
--- a/agent/turn_facade.py
+++ b/agent/turn_facade.py
@@ -46,6 +46,7 @@ class TurnFacadeMixin:
             set_conversation_context,
         )
         from agent.prompt_cache_scope import declared_conversation_scope_safe
+        from agent.relay_cwd import resolve_relay_scope_cwds
         from agent.review_idle_queue import QUEUE as _review_queue
         from agent.subagent_lifecycle import bind_subagent_parent
         from agent.interrupt_scope import track_in_interrupt_scope
@@ -88,11 +89,16 @@ class TurnFacadeMixin:
             lease = admission.lease
             conversation_history = admission.conversation_history
 
+            relay_session_cwd, relay_turn_cwd = resolve_relay_scope_cwds(
+                self, effective_task_id, session_id, task_context["platform"]
+            )
             relay_lease = relay_runtime.SESSION_COORDINATOR.acquire_conversation(
                 profile_key=relay_runtime.current_profile_key(),
                 session_id=task_context["session_id"], platform=task_context["platform"],
                 parent_session_id=relay_parent_session_id,
                 model=str(getattr(self, "model", None) or ""),
+                session_cwd=relay_session_cwd,
+                turn_cwd=relay_turn_cwd,
             )
             relay_turn = relay_runtime.SESSION_COORDINATOR.begin_turn(
                 relay_lease, turn_id=relay_turn_id, task_id=effective_task_id
diff --git a/docs/observability/relay-shared-metrics.md b/docs/observability/relay-shared-metrics.md
index 23d016659c..d12024321d 100644
--- a/docs/observability/relay-shared-metrics.md
+++ b/docs/observability/relay-shared-metrics.md
@@ -94,6 +94,20 @@ Both defaults preserve one session scope for the full session. Rotated spans
 retain the same `session_id` and add `hermes.session.segment` plus
 `hermes.session.segment_reason` (`compaction` or `max_turns`).
 
+## Working-Directory Scope Data
+
+When Hermes knows a session or task's logical working directory, its
+`hermes.session` and `hermes.turn` start scopes include it as `data.cwd` in
+ATOF. A turn running in a task worktree can therefore differ from its owning
+session. Unknown directories are omitted, and scope-end data remains reserved
+for the outcome.
+
+The working directory is Relay scope input, so it is visible to every enabled
+Relay subscriber, not only ATOF. Paths can reveal usernames, repository names,
+or mount layouts. Relay does not filter events by working directory; if a path
+must not leave the host, use a trusted local collector or do not enable a remote
+exporter for that process.
+
 ## Process-Wide Plugin Policy and Profile Isolation
 
 Relay plugin configuration is a process-level deployment choice, not a Hermes
diff --git a/tests/agent/test_relay_atof_cwd.py b/tests/agent/test_relay_atof_cwd.py
new file mode 100644
index 0000000000..041ec0ad70
--- /dev/null
+++ b/tests/agent/test_relay_atof_cwd.py
@@ -0,0 +1,109 @@
+"""Hermes scope cwd export through the real NeMo Relay ATOF plugin."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+
+def test_run_conversation_exports_session_and_turn_cwds(tmp_path, monkeypatch):
+    relay = pytest.importorskip("nemo_relay")
+    if getattr(relay, "_native", None) is None:
+        pytest.skip("NeMo Relay native binding is unavailable on this platform")
+
+    from agent import relay_runtime
+    from hermes_cli.lifecycle import finalize_session
+    from run_agent import AIAgent
+    from tools.terminal_tool import clear_session_cwd, record_session_cwd
+
+    hermes_home = tmp_path / "hermes-home"
+    session_cwd = tmp_path / "session"
+    turn_cwd = tmp_path / "task"
+    atof_dir = tmp_path / "atof"
+    for directory in (hermes_home, session_cwd, turn_cwd, atof_dir):
+        directory.mkdir()
+
+    config = tmp_path / "plugins.toml"
+    config.write_text(
+        f"""version = 1
+
+[[components]]
+kind = "observability"
+enabled = true
+
+[components.config]
+version = 4
+
+[components.config.atof]
+enabled = true
+
+[[components.config.atof.sinks]]
+type = "file"
+output_directory = {json.dumps(str(atof_dir))}
+filename = "events.jsonl"
+mode = "overwrite"
+""",
+        encoding="utf-8",
+    )
+    session_id = "cwd-e2e-session"
+    task_id = "cwd-e2e-task"
+    monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+    monkeypatch.setenv(relay_runtime.RELAY_PLUGINS_CONFIG_ENV, str(config))
+    monkeypatch.chdir(session_cwd)
+    monkeypatch.setattr(
+        "agent.conversation_loop.run_conversation",
+        lambda *_args, **_kwargs: {"final_response": "ok", "completed": True},
+    )
+
+    relay_runtime._reset_for_tests()
+    relay.plugin.clear()
+    record_session_cwd(task_id, str(turn_cwd))
+    agent = None
+    try:
+        agent = AIAgent(
+            api_key="test-key",
+            base_url="https://example.invalid/v1",
+            provider="openai",
+            model="test-model",
+            session_id=session_id,
+            platform="cli",
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+            disabled_toolsets=["*"],
+        )
+        result = agent.run_conversation("hello", task_id=task_id)
+        assert result["final_response"] == "ok"
+        finalize_session(session_id=session_id)
+    finally:
+        if agent is not None:
+            agent.close()
+        clear_session_cwd(task_id)
+        relay_runtime._reset_for_tests()
+
+    events = [
+        json.loads(line)
+        for line in (atof_dir / "events.jsonl").read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]
+
+    def only_event(name: str, category: str) -> dict:
+        matches = [
+            event
+            for event in events
+            if event.get("name") == name and event.get("scope_category") == category
+        ]
+        assert len(matches) == 1
+        return matches[0]
+
+    session_start = only_event("hermes.session", "start")
+    turn_start = only_event("hermes.turn", "start")
+    session_end = only_event("hermes.session", "end")
+    turn_end = only_event("hermes.turn", "end")
+
+    assert session_start["data"] == {"cwd": str(session_cwd)}
+    assert turn_start["data"] == {"cwd": str(turn_cwd)}
+    assert turn_start["parent_uuid"] == session_start["uuid"]
+    assert "cwd" not in session_end["data"]
+    assert "cwd" not in turn_end["data"]
diff --git a/tests/agent/test_relay_cwd.py b/tests/agent/test_relay_cwd.py
new file mode 100644
index 0000000000..da53e06fda
--- /dev/null
+++ b/tests/agent/test_relay_cwd.py
@@ -0,0 +1,61 @@
+"""Logical working directories attached to Hermes-owned Relay scopes."""
+
+from agent import relay_cwd, runtime_cwd
+from tools.terminal_tool import clear_session_cwd, record_session_cwd
+
+
+def test_session_context_and_task_record_remain_distinct(monkeypatch):
+    token = runtime_cwd.set_session_cwd("/workspace/session")
+    record_session_cwd("task-1", "/workspace/task")
+    monkeypatch.setattr(
+        "gateway.session_context.get_session_env", lambda _name, _default: ""
+    )
+    try:
+        assert relay_cwd.resolve_relay_scope_cwds(
+            object(), "task-1", "session-1", "cli"
+        ) == ("/workspace/session", "/workspace/task")
+        assert relay_cwd.resolve_relay_scope_cwds(
+            object(), "task-1", "session-1", "subagent"
+        ) == ("/workspace/task", "/workspace/task")
+    finally:
+        clear_session_cwd("task-1")
+        runtime_cwd._SESSION_CWD.reset(token)
+
+
+def test_remote_scoped_cwd_is_preserved_without_host_resolution(monkeypatch):
+    token = runtime_cwd.set_session_cwd("~/remote-project")
+    monkeypatch.setattr("tools.terminal_tool.get_session_cwd", lambda _key: None)
+    monkeypatch.setattr(
+        runtime_cwd,
+        "resolve_agent_cwd",
+        lambda: (_ for _ in ()).throw(AssertionError("must not resolve on this host")),
+    )
+    try:
+        assert relay_cwd.resolve_relay_scope_cwds(
+            object(), "task-1", "session-1", "gateway"
+        ) == ("~/remote-project", "~/remote-project")
+    finally:
+        runtime_cwd._SESSION_CWD.reset(token)
+
+
+def test_gateway_session_key_uses_its_recorded_cwd(monkeypatch):
+    token = runtime_cwd.set_session_cwd(None)
+    record_session_cwd("gateway-key", "/remote/gateway-workspace")
+    monkeypatch.setattr(
+        "gateway.session_context.get_session_env",
+        lambda name, default: (
+            "gateway-key" if name == "HERMES_SESSION_KEY" else default
+        ),
+    )
+    monkeypatch.setattr(
+        runtime_cwd,
+        "resolve_agent_cwd",
+        lambda: (_ for _ in ()).throw(AssertionError("must not resolve on this host")),
+    )
+    try:
+        assert relay_cwd.resolve_relay_scope_cwds(
+            object(), "task-1", "session-1", "gateway"
+        ) == ("/remote/gateway-workspace", "/remote/gateway-workspace")
+    finally:
+        clear_session_cwd("gateway-key")
+        runtime_cwd._SESSION_CWD.reset(token)
diff --git a/tests/agent/test_relay_session_segments.py b/tests/agent/test_relay_session_segments.py
index 2e778c4d47..92eb0c0772 100644
--- a/tests/agent/test_relay_session_segments.py
+++ b/tests/agent/test_relay_session_segments.py
@@ -39,7 +39,7 @@ class _FakeScopeModule:
     def __init__(self, wedge_pop: threading.Event | None = None) -> None:
         self._wedge = wedge_pop
         self._seq = 0
-        self.pushes: list[dict[str, Any]] = []  # {name, metadata, handle}
+        self.pushes: list[dict[str, Any]] = []  # {name, metadata, handle, input}
         self.pops: list[_ScopeHandle] = []
 
     def push(self, name: str, scope_type: Any, **kwargs: Any) -> _ScopeHandle:
@@ -49,6 +49,7 @@ class _FakeScopeModule:
                 "name": name,
                 "metadata": dict(kwargs.get("metadata") or {}),
                 "parent": kwargs.get("handle"),
+                "input": dict(kwargs.get("input") or {}),
                 "seq": self._seq,
             }
         )
@@ -143,7 +144,7 @@ def coordinator() -> RelaySessionCoordinator:
     return RelaySessionCoordinator()
 
 
-def _acquire(coordinator, runtime, session_id="sess-1"):
+def _acquire(coordinator, runtime, session_id="sess-1", **kwargs):
     class _Registry:
         def for_profile(self, key):
             return runtime
@@ -154,6 +155,7 @@ def _acquire(coordinator, runtime, session_id="sess-1"):
         profile_key=runtime.profile_key,
         session_id=session_id,
         platform="test",
+        **kwargs,
     )
 
 
@@ -186,6 +188,33 @@ class TestDefaultsNeverRotate:
         )
 
 
+class TestCwdProjection:
+    def test_distinct_session_and_turn_cwds_survive_segment_rotation(self, coordinator):
+        fake = _FakeRelay()
+        runtime = _make_runtime(fake)
+        lease = _acquire(
+            coordinator, runtime,
+            session_cwd="/workspace/session", turn_cwd="/workspace/task",
+        )
+
+        turn = coordinator.begin_turn(lease, turn_id="t1", task_id="task1")
+
+        assert _session_pushes(fake)[-1]["input"] == {"cwd": "/workspace/session"}
+        assert fake.scope.pushes[-1]["input"] == {"cwd": "/workspace/task"}
+        coordinator.end_turn(turn, outcome="success")
+
+        lease = _acquire(
+            coordinator, runtime,
+            session_cwd="/workspace/moved", turn_cwd="/workspace/next-task",
+        )
+        runtime.rotate_session_scope(lease.session, reason="compaction")
+        turn = coordinator.begin_turn(lease, turn_id="t2", task_id="task2")
+
+        assert _session_pushes(fake)[-1]["input"] == {"cwd": "/workspace/moved"}
+        assert fake.scope.pushes[-1]["input"] == {"cwd": "/workspace/next-task"}
+        coordinator.end_turn(turn, outcome="success")
+
+
 class TestCompactionRotation:
     def test_compaction_rotates_at_next_begin_turn_not_immediately(
         self, coordinator, monkeypatch

From 6bfd5bce4801f3add8688b778c5aec04456917ab Mon Sep 17 00:00:00 2001
From: Alex Fournier <afournier@nvidia.com>
Date: Fri, 11 Sep 2026 09:31:13 -0700
Subject: [PATCH 02/61] fix(relay): harden cwd resolution

Signed-off-by: Alex Fournier <afournier@nvidia.com>
---
 agent/relay_cwd.py                 |  7 ++-
 agent/relay_runtime.py             |  3 +-
 tests/agent/test_relay_atof_cwd.py |  1 -
 tests/agent/test_relay_cwd.py      | 76 ++++++++++++++++++++++++++++--
 4 files changed, 80 insertions(+), 7 deletions(-)

diff --git a/agent/relay_cwd.py b/agent/relay_cwd.py
index 63e978b472..3eee3a44ef 100644
--- a/agent/relay_cwd.py
+++ b/agent/relay_cwd.py
@@ -74,11 +74,14 @@ def resolve_relay_scope_cwds(
                 "Unable to read the configured Relay session cwd", exc_info=True
             )
 
-    if not session_cwd and platform == "cli" and backend in {"", "local"}:
+    if not session_cwd and platform in {"", "cli"} and backend in {"", "local"}:
         try:
             from agent.runtime_cwd import resolve_agent_cwd
 
-            session_cwd = _clean_cwd(str(resolve_agent_cwd()))
+            resolved = resolve_agent_cwd()
+            session_cwd = _clean_cwd(
+                str(resolved if resolved.is_absolute() else resolved.resolve())
+            )
         except Exception:
             logger.debug("Unable to resolve the local Relay session cwd", exc_info=True)
 
diff --git a/agent/relay_runtime.py b/agent/relay_runtime.py
index 66ed367e88..3ca978c61c 100644
--- a/agent/relay_runtime.py
+++ b/agent/relay_runtime.py
@@ -813,8 +813,9 @@ class ConversationLease:
     host: RelayHost
     session: RelaySession | None
     parent_session_id: str = ""
-    turn_cwd: str = ""
     released: bool = False
+    # Keep new fields after the pre-existing positional constructor fields.
+    turn_cwd: str = ""
 
     def live_runtime(self) -> RelayRuntime | None:
         """Return the real Relay host when this lease owns an open session."""
diff --git a/tests/agent/test_relay_atof_cwd.py b/tests/agent/test_relay_atof_cwd.py
index 041ec0ad70..bb19406b98 100644
--- a/tests/agent/test_relay_atof_cwd.py
+++ b/tests/agent/test_relay_atof_cwd.py
@@ -67,7 +67,6 @@ mode = "overwrite"
             provider="openai",
             model="test-model",
             session_id=session_id,
-            platform="cli",
             quiet_mode=True,
             skip_context_files=True,
             skip_memory=True,
diff --git a/tests/agent/test_relay_cwd.py b/tests/agent/test_relay_cwd.py
index da53e06fda..7932931b4d 100644
--- a/tests/agent/test_relay_cwd.py
+++ b/tests/agent/test_relay_cwd.py
@@ -1,9 +1,23 @@
 """Logical working directories attached to Hermes-owned Relay scopes."""
 
+from pathlib import Path
+
+import pytest
+
 from agent import relay_cwd, runtime_cwd
+from agent.relay_runtime import ConversationLease
 from tools.terminal_tool import clear_session_cwd, record_session_cwd
 
 
+def test_conversation_lease_keeps_released_in_its_original_position():
+    lease = ConversationLease(
+        "profile", "session", "cli", object(), None, "parent", True
+    )
+
+    assert lease.released is True
+    assert lease.turn_cwd == ""
+
+
 def test_session_context_and_task_record_remain_distinct(monkeypatch):
     token = runtime_cwd.set_session_cwd("/workspace/session")
     record_session_cwd("task-1", "/workspace/task")
@@ -22,8 +36,13 @@ def test_session_context_and_task_record_remain_distinct(monkeypatch):
         runtime_cwd._SESSION_CWD.reset(token)
 
 
-def test_remote_scoped_cwd_is_preserved_without_host_resolution(monkeypatch):
-    token = runtime_cwd.set_session_cwd("~/remote-project")
+@pytest.mark.parametrize(
+    "logical_cwd", ["~/remote-project", r"C:\work\project", r"\\server\share\project"]
+)
+def test_remote_scoped_cwd_is_preserved_without_host_resolution(
+    monkeypatch, logical_cwd
+):
+    token = runtime_cwd.set_session_cwd(logical_cwd)
     monkeypatch.setattr("tools.terminal_tool.get_session_cwd", lambda _key: None)
     monkeypatch.setattr(
         runtime_cwd,
@@ -33,7 +52,7 @@ def test_remote_scoped_cwd_is_preserved_without_host_resolution(monkeypatch):
     try:
         assert relay_cwd.resolve_relay_scope_cwds(
             object(), "task-1", "session-1", "gateway"
-        ) == ("~/remote-project", "~/remote-project")
+        ) == (logical_cwd, logical_cwd)
     finally:
         runtime_cwd._SESSION_CWD.reset(token)
 
@@ -59,3 +78,54 @@ def test_gateway_session_key_uses_its_recorded_cwd(monkeypatch):
     finally:
         clear_session_cwd("gateway-key")
         runtime_cwd._SESSION_CWD.reset(token)
+
+
+@pytest.mark.parametrize(
+    ("platform", "backend", "resolved", "expected", "uses_host"),
+    [
+        ("cli", "local", Path("/workspace"), "/workspace", True),
+        ("", "local", Path("."), str(Path.cwd().resolve()), True),
+        ("cli", "ssh", Path("/host"), "", False),
+        ("gateway", "local", Path("/host"), "", False),
+    ],
+)
+def test_only_local_cli_uses_host_cwd(
+    monkeypatch, platform, backend, resolved, expected, uses_host
+):
+    token = runtime_cwd.set_session_cwd(None)
+    host_lookups = []
+
+    def resolve_host_cwd():
+        host_lookups.append(True)
+        return resolved
+
+    monkeypatch.setattr("tools.terminal_tool.get_session_cwd", lambda _key: None)
+    monkeypatch.setattr(
+        "gateway.session_context.get_session_env", lambda _name, default: default
+    )
+    monkeypatch.setattr(
+        "tools.terminal_scope.terminal_env",
+        lambda name, default: backend if name == "TERMINAL_ENV" else default,
+    )
+    monkeypatch.setattr(runtime_cwd, "resolve_agent_cwd", resolve_host_cwd)
+    try:
+        assert relay_cwd.resolve_relay_scope_cwds(
+            object(), "task-1", "session-1", platform
+        ) == (expected, expected)
+        assert bool(host_lookups) is uses_host
+    finally:
+        runtime_cwd._SESSION_CWD.reset(token)
+
+
+def test_cwd_lookup_failures_do_not_break_the_turn(monkeypatch):
+    def unavailable(*_args):
+        raise RuntimeError("unavailable")
+
+    monkeypatch.setattr("tools.terminal_tool.get_session_cwd", unavailable)
+    monkeypatch.setattr(runtime_cwd, "scoped_session_cwd", unavailable)
+    monkeypatch.setattr("gateway.session_context.get_session_env", unavailable)
+    monkeypatch.setattr("tools.terminal_scope.terminal_env", unavailable)
+
+    assert relay_cwd.resolve_relay_scope_cwds(
+        object(), "task-1", "session-1", "gateway"
+    ) == ("", "")

From 03616c2e245f9b3d25a9b1d542b395537fe5a5b3 Mon Sep 17 00:00:00 2001
From: Alex Fournier <afournier@nvidia.com>
Date: Thu, 17 Sep 2026 19:51:57 +0200
Subject: [PATCH 03/61] test(relay): make cwd expectation portable

Signed-off-by: Alex Fournier <afournier@nvidia.com>
---
 tests/agent/test_relay_cwd.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/tests/agent/test_relay_cwd.py b/tests/agent/test_relay_cwd.py
index 7932931b4d..8ebf1e8895 100644
--- a/tests/agent/test_relay_cwd.py
+++ b/tests/agent/test_relay_cwd.py
@@ -83,7 +83,13 @@ def test_gateway_session_key_uses_its_recorded_cwd(monkeypatch):
 @pytest.mark.parametrize(
     ("platform", "backend", "resolved", "expected", "uses_host"),
     [
-        ("cli", "local", Path("/workspace"), "/workspace", True),
+        (
+            "cli",
+            "local",
+            Path("/workspace"),
+            str(Path("/workspace").resolve()),
+            True,
+        ),
         ("", "local", Path("."), str(Path.cwd().resolve()), True),
         ("cli", "ssh", Path("/host"), "", False),
         ("gateway", "local", Path("/host"), "", False),

From d7c657bf3c95368e46b1798e66603966fd3c9434 Mon Sep 17 00:00:00 2001
From: Alex Fournier <afournier@nvidia.com>
Date: Wed, 23 Sep 2026 07:46:43 -0400
Subject: [PATCH 04/61] fix(relay): clear stale cwd scope data

Signed-off-by: Alex Fournier <afournier@nvidia.com>
---
 agent/relay_runtime.py                     | 15 +++++++++------
 agent/turn_facade.py                       |  5 ++++-
 tests/agent/test_relay_session_segments.py | 20 ++++++++++++++++++++
 3 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/agent/relay_runtime.py b/agent/relay_runtime.py
index 5434cbe4a5..8981001c1b 100644
--- a/agent/relay_runtime.py
+++ b/agent/relay_runtime.py
@@ -445,8 +445,8 @@ class RelayRuntime:
         with session.lock:
             if session.closing:
                 return None
-            if isinstance(cwd, str) and cwd.strip():
-                session.cwd = cwd.strip()
+            if cwd is not None:
+                session.cwd = _scope_input(cwd).get("cwd", "")
             if session.handle is None:
                 self._open_session_scope(
                     session, {**(metadata or {}), **runtime_metadata(self.runtime_id)},
@@ -950,12 +950,15 @@ class RelaySessionCoordinator:
                 "parent_session_id": parent_session_id, "model": model, "cwd": session_cwd,
             }
             session = _warn_on_error("conversation initialization", self._open_conversation_session, host, context)
-        effective_turn_cwd = (
-            _scope_input(turn_cwd).get("cwd") or _scope_input(session_cwd).get("cwd") or ""
-        )
-        if not effective_turn_cwd and session is not None:
+        if turn_cwd is not None:
+            effective_turn_cwd = _scope_input(turn_cwd).get("cwd", "")
+        elif session_cwd is not None:
+            effective_turn_cwd = _scope_input(session_cwd).get("cwd", "")
+        elif session is not None:
             with session.lock:
                 effective_turn_cwd = session.cwd
+        else:
+            effective_turn_cwd = ""
         return ConversationLease(
             profile_key=profile_key, session_id=session_id, platform=platform, host=host,
             session=session, parent_session_id=parent_session_id, turn_cwd=effective_turn_cwd,
diff --git a/agent/turn_facade.py b/agent/turn_facade.py
index 67a2834d4f..3c901a41cb 100644
--- a/agent/turn_facade.py
+++ b/agent/turn_facade.py
@@ -96,7 +96,10 @@ class TurnFacadeMixin:
             conversation_history = admission.conversation_history
 
             relay_session_cwd, relay_turn_cwd = resolve_relay_scope_cwds(
-                self, effective_task_id, session_id, task_context["platform"]
+                self,
+                effective_task_id,
+                task_context["session_id"],
+                task_context["platform"],
             )
             relay_lease = relay_runtime.SESSION_COORDINATOR.acquire_conversation(
                 profile_key=relay_runtime.current_profile_key(),
diff --git a/tests/agent/test_relay_session_segments.py b/tests/agent/test_relay_session_segments.py
index 9287d6141a..72feeb06f2 100644
--- a/tests/agent/test_relay_session_segments.py
+++ b/tests/agent/test_relay_session_segments.py
@@ -297,6 +297,26 @@ class TestCwdProjection:
         assert fake.scope.pushes[-1]["input"] == {"cwd": "/workspace/next-task"}
         coordinator.end_turn(turn, outcome="success")
 
+    def test_explicit_unknown_cwd_clears_prior_scope_input(self, coordinator):
+        fake = _FakeRelay()
+        runtime = _make_runtime(fake)
+        lease = _acquire(
+            coordinator, runtime,
+            session_cwd="/workspace/session", turn_cwd="/workspace/task",
+        )
+        coordinator.end_turn(
+            coordinator.begin_turn(lease, turn_id="t1", task_id="task1"),
+            outcome="success",
+        )
+
+        lease = _acquire(coordinator, runtime, session_cwd="", turn_cwd="")
+        runtime.rotate_session_scope(lease.session, reason="compaction")
+        turn = coordinator.begin_turn(lease, turn_id="t2", task_id="task2")
+
+        assert _session_pushes(fake)[-1]["input"] == {}
+        assert fake.scope.pushes[-1]["input"] == {}
+        coordinator.end_turn(turn, outcome="success")
+
 
 class TestCompactionRotation:
     def test_compaction_rotates_at_next_begin_turn_not_immediately(

From 706f296d5abc6955c278882b824c79b659cf077e Mon Sep 17 00:00:00 2001
From: Alex Fournier <afournier@nvidia.com>
Date: Wed, 23 Sep 2026 07:50:12 -0400
Subject: [PATCH 05/61] test(relay): cover cwd lifecycle handoffs

Signed-off-by: Alex Fournier <afournier@nvidia.com>
---
 tests/agent/test_cross_process_turn_lease.py |  6 ++++++
 tests/agent/test_relay_session_segments.py   | 14 +-------------
 2 files changed, 7 insertions(+), 13 deletions(-)

diff --git a/tests/agent/test_cross_process_turn_lease.py b/tests/agent/test_cross_process_turn_lease.py
index 2c306f0d34..017c5c9025 100644
--- a/tests/agent/test_cross_process_turn_lease.py
+++ b/tests/agent/test_cross_process_turn_lease.py
@@ -82,6 +82,10 @@ def test_run_conversation_acquires_then_reloads_latest_tip(monkeypatch):
         observed["session_id"] = _agent.session_id
         return {"final_response": "ok", "messages": history, "failed": False}
 
+    def resolve_relay_cwds(_agent, _task_id, session_id, _platform):
+        observed["relay_cwd_session_id"] = session_id
+        return "", ""
+
     # Simulate a contended wait so the resume status path is covered.
     def acquire_with_wait(session_id, holder, **kwargs):
         db.events.append(("acquire", session_id, holder))
@@ -93,6 +97,7 @@ def test_run_conversation_acquires_then_reloads_latest_tip(monkeypatch):
     db.acquire_session_turn_lease = acquire_with_wait
 
     monkeypatch.setattr("agent.conversation_loop.run_conversation", fake_run)
+    monkeypatch.setattr("agent.relay_cwd.resolve_relay_scope_cwds", resolve_relay_cwds)
     result = AIAgent.run_conversation(
         agent,
         "new message",
@@ -103,6 +108,7 @@ def test_run_conversation_acquires_then_reloads_latest_tip(monkeypatch):
     assert observed == {
         "history": [{"role": "user", "content": "durable latest"}],
         "session_id": "compressed-tip",
+        "relay_cwd_session_id": "compressed-tip",
     }
     assert [event[0] for event in db.events] == [
         "acquire",
diff --git a/tests/agent/test_relay_session_segments.py b/tests/agent/test_relay_session_segments.py
index 72feeb06f2..901e23346e 100644
--- a/tests/agent/test_relay_session_segments.py
+++ b/tests/agent/test_relay_session_segments.py
@@ -297,21 +297,9 @@ class TestCwdProjection:
         assert fake.scope.pushes[-1]["input"] == {"cwd": "/workspace/next-task"}
         coordinator.end_turn(turn, outcome="success")
 
-    def test_explicit_unknown_cwd_clears_prior_scope_input(self, coordinator):
-        fake = _FakeRelay()
-        runtime = _make_runtime(fake)
-        lease = _acquire(
-            coordinator, runtime,
-            session_cwd="/workspace/session", turn_cwd="/workspace/task",
-        )
-        coordinator.end_turn(
-            coordinator.begin_turn(lease, turn_id="t1", task_id="task1"),
-            outcome="success",
-        )
-
         lease = _acquire(coordinator, runtime, session_cwd="", turn_cwd="")
         runtime.rotate_session_scope(lease.session, reason="compaction")
-        turn = coordinator.begin_turn(lease, turn_id="t2", task_id="task2")
+        turn = coordinator.begin_turn(lease, turn_id="t3", task_id="task3")
 
         assert _session_pushes(fake)[-1]["input"] == {}
         assert fake.scope.pushes[-1]["input"] == {}

From 122ffd3f398cc6aae33604d8cc5d8b7b3ae2921c Mon Sep 17 00:00:00 2001
From: brooklyn! <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 23 Sep 2026 21:21:52 -0500
Subject: [PATCH 06/61] =?UTF-8?q?fix(desktop):=20=E2=8C=98K=20session=20se?=
 =?UTF-8?q?arch=20reflects=20renames=20and=20archives=20immediately?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The palette fetched its own 200-row page through react-query with the
client's 60s staleTime, and nothing invalidated it: a rename, pin, or
archive lands in the sidebar's session stores while the palette is
unmounted, so ⌘K kept showing the old title (or an archived row) for up
to a minute, and painted it stale-first even after.

Revalidate on every open (staleTime 0; the cached page still paints
instantly) and overlay the sidebar's live stores on the fetched page by
id, so title and pin come from what the sidebar already knows and rows
the user just archived or deleted are dropped.
---
 .../desktop/src/app/command-palette/index.tsx | 59 +++++++++++++------
 1 file changed, 42 insertions(+), 17 deletions(-)

diff --git a/apps/desktop/src/app/command-palette/index.tsx b/apps/desktop/src/app/command-palette/index.tsx
index 98a3cf7f39..3bed6c48bf 100644
--- a/apps/desktop/src/app/command-palette/index.tsx
+++ b/apps/desktop/src/app/command-palette/index.tsx
@@ -74,7 +74,8 @@ import { $dismissedAutoProjectIds, filterVisibleProjects } from '@/store/layout'
 import { openPetGenerate } from '@/store/pet-generate'
 import { openBrowserTab } from '@/store/preview'
 import { $projectTree, goToProject, openFolderAsProject, requestStartWorkSession } from '@/store/projects'
-import { $connection } from '@/store/session'
+import { $connection, $cronSessions, $messagingSessions, $sessions } from '@/store/session'
+import { $removedSessionIds } from '@/store/session-removal'
 import { runGatewayRestart } from '@/store/system-actions'
 import {
   $backendUpdateApply,
@@ -393,6 +394,11 @@ const toSessionEntry = (session: SessionRow): SessionEntry => ({
   title: sessionTitle(session)
 })
 
+// Search terms beyond the label: the preview and branch, so a session is
+// findable by what it's about, not only what it's called.
+const sessionKeywords = (session: SessionEntry, ...tags: string[]): string[] =>
+  [...tags, 'chat', 'session', session.preview, session.git_branch].filter((word): word is string => !!word)
+
 type NonConfigSettingsLabel =
   'about' | 'archivedChats' | 'gateway' | 'keysSettings' | 'keysTools' | 'mcp' | 'providerAccounts' | 'providerApiKeys'
 
@@ -637,21 +643,51 @@ function CommandPaletteBody({ onExited }: { onExited: () => void }) {
     queryFn: () => getHermesConfigRecord()
   })
 
+  // staleTime 0 (not the 60s client default): renames, pins, and archives
+  // happen in the sidebar while this component is unmounted, so nothing can
+  // invalidate these keys — every open must revalidate. The cached page
+  // still paints instantly; the live-store overlay below covers the gap.
   const sessionsQuery = useQuery({
     queryKey: ['command-palette', 'sessions'],
-    queryFn: () => listAllProfileSessions(200, 1, 'exclude')
+    queryFn: () => listAllProfileSessions(200, 1, 'exclude'),
+    staleTime: 0
   })
 
   const archivedQuery = useQuery({
     queryKey: ['command-palette', 'archived'],
-    queryFn: () => listAllProfileSessions(200, 0, 'only')
+    queryFn: () => listAllProfileSessions(200, 0, 'only'),
+    staleTime: 0
   })
 
+  const liveSessions = useStore($sessions)
+  const liveCronSessions = useStore($cronSessions)
+  const liveMessagingSessions = useStore($messagingSessions)
+  const removedSessionIds = useStore($removedSessionIds)
+
   // getServers is the shared choke point that also drops malformed (null/
   // scalar) entries, so the palette never lists a server the MCP tab dropped.
   const mcpServers = useMemo(() => Object.keys(getServers(configQuery.data ?? null)).sort(), [configQuery.data])
 
-  const sessions = useMemo(() => (sessionsQuery.data?.sessions ?? []).map(toSessionEntry), [sessionsQuery.data])
+  // The sidebar's stores are where a rename / pin / archive lands first (the
+  // server page confirms later). Overlay them on the fetched 200-row page so
+  // the palette says what the sidebar says: same title, same pin, and no row
+  // the user just archived or deleted.
+  const liveRows = useMemo(() => {
+    const byId = new Map(
+      [...liveCronSessions, ...liveMessagingSessions, ...liveSessions].map(row => [row.id, row] as const)
+    )
+
+    return (sessionsQuery.data?.sessions ?? [])
+      .filter(session => !removedSessionIds.has(session.id))
+      .map(session => {
+        const live = byId.get(session.id)
+
+        return live ? { ...session, pinned: live.pinned, title: live.title } : session
+      })
+  }, [liveCronSessions, liveMessagingSessions, liveSessions, removedSessionIds, sessionsQuery.data])
+
+  const sessions = useMemo(() => liveRows.map(toSessionEntry), [liveRows])
+
   const archivedSessions = useMemo(() => (archivedQuery.data?.sessions ?? []).map(toSessionEntry), [archivedQuery.data])
 
   // Search/sub-page are local to a mount, and this component remounts per open
@@ -1168,12 +1204,7 @@ function CommandPaletteBody({ onExited }: { onExited: () => void }) {
         items: sessions.map(session => ({
           icon: MessageCircle,
           id: `session-${session.id}`,
-          keywords: [
-            'chat',
-            'session',
-            ...(session.preview ? [session.preview] : []),
-            ...(session.git_branch ? [session.git_branch] : [])
-          ],
+          keywords: sessionKeywords(session),
           label: session.title,
           runWithEvent: goSession(session.id)
         }))
@@ -1230,13 +1261,7 @@ function CommandPaletteBody({ onExited }: { onExited: () => void }) {
         items: archivedSessions.map(session => ({
           icon: Archive,
           id: `archived-${session.id}`,
-          keywords: [
-            'archived',
-            'chat',
-            'session',
-            ...(session.preview ? [session.preview] : []),
-            ...(session.git_branch ? [session.git_branch] : [])
-          ],
+          keywords: sessionKeywords(session, 'archived'),
           label: session.title,
           run: go(`${SETTINGS_ROUTE}?tab=sessions&session=${encodeURIComponent(session.id)}`)
         }))

From 3fd49606fa194e11979ae60bacd5e33d7b9d055a Mon Sep 17 00:00:00 2001
From: brooklyn! <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 23 Sep 2026 21:21:52 -0500
Subject: [PATCH 07/61] =?UTF-8?q?feat(desktop):=20=E2=8C=98K=20groups=20pi?=
 =?UTF-8?q?nned=20sessions=20first?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pinned sessions were mixed into Sessions with no group, icon, or ranking
advantage. Resolve them the way the sidebar's Pinned section does
(resolvePinnedSessions: local pin order, then server-flagged pins, minus
in-flight unpins) and list them under a Pinned heading ahead of Sessions;
rankGroups' stable sort then lets a pin win a tie on equal scores.
---
 .../desktop/src/app/command-palette/index.tsx | 37 ++++++++++++++++++-
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/apps/desktop/src/app/command-palette/index.tsx b/apps/desktop/src/app/command-palette/index.tsx
index 3bed6c48bf..695b1c8975 100644
--- a/apps/desktop/src/app/command-palette/index.tsx
+++ b/apps/desktop/src/app/command-palette/index.tsx
@@ -46,6 +46,7 @@ import {
   Package,
   Palette,
   PawPrint,
+  Pin,
   Plus,
   RefreshCw,
   Settings,
@@ -70,11 +71,12 @@ import {
   setCommandPaletteOpen
 } from '@/store/command-palette'
 import { $bindings, bindingsFor } from '@/store/keybinds'
-import { $dismissedAutoProjectIds, filterVisibleProjects } from '@/store/layout'
+import { $dismissedAutoProjectIds, $pinnedSessionIds, filterVisibleProjects } from '@/store/layout'
 import { openPetGenerate } from '@/store/pet-generate'
 import { openBrowserTab } from '@/store/preview'
 import { $projectTree, goToProject, openFolderAsProject, requestStartWorkSession } from '@/store/projects'
 import { $connection, $cronSessions, $messagingSessions, $sessions } from '@/store/session'
+import { $unconfirmedPinWrites } from '@/store/session-pin-sync'
 import { $removedSessionIds } from '@/store/session-removal'
 import { runGatewayRestart } from '@/store/system-actions'
 import {
@@ -90,6 +92,7 @@ import { luminance } from '@/themes/color'
 import { type ThemeMode, useTheme } from '@/themes/context'
 import { isUserTheme, resolveTheme } from '@/themes/user-themes'
 
+import { buildSessionByAnyId, resolvePinnedSessions } from '../chat/sidebar/session-index'
 import { openSessionFromPicker, openSessionIntentFromModifiers } from '../open-session'
 import {
   AGENTS_ROUTE,
@@ -662,6 +665,8 @@ function CommandPaletteBody({ onExited }: { onExited: () => void }) {
   const liveSessions = useStore($sessions)
   const liveCronSessions = useStore($cronSessions)
   const liveMessagingSessions = useStore($messagingSessions)
+  const pinnedSessionIds = useStore($pinnedSessionIds)
+  const unconfirmedPinWrites = useStore($unconfirmedPinWrites)
   const removedSessionIds = useStore($removedSessionIds)
 
   // getServers is the shared choke point that also drops malformed (null/
@@ -686,7 +691,19 @@ function CommandPaletteBody({ onExited }: { onExited: () => void }) {
       })
   }, [liveCronSessions, liveMessagingSessions, liveSessions, removedSessionIds, sessionsQuery.data])
 
-  const sessions = useMemo(() => liveRows.map(toSessionEntry), [liveRows])
+  // Same resolution as the sidebar's Pinned section: local pin order first,
+  // then server-flagged pins, minus our own in-flight unpins.
+  const pinnedSessions = useMemo(() => {
+    const byAnyId = buildSessionByAnyId(liveRows, [], [])
+
+    return resolvePinnedSessions(pinnedSessionIds, byAnyId, liveRows, unconfirmedPinWrites).map(toSessionEntry)
+  }, [liveRows, pinnedSessionIds, unconfirmedPinWrites])
+
+  const sessions = useMemo(() => {
+    const pinned = new Set(pinnedSessions.map(session => session.id))
+
+    return liveRows.filter(session => !pinned.has(session.id)).map(toSessionEntry)
+  }, [liveRows, pinnedSessions])
 
   const archivedSessions = useMemo(() => (archivedQuery.data?.sessions ?? []).map(toSessionEntry), [archivedQuery.data])
 
@@ -1198,6 +1215,21 @@ function CommandPaletteBody({ onExited }: { onExited: () => void }) {
       }))
     })
 
+    // Pinned before Sessions: rankGroups' stable sort keeps source order on
+    // equal scores, so a pin wins a tie with an unpinned row of the same name.
+    if (pinnedSessions.length > 0) {
+      result.push({
+        heading: t.sidebar.pinned,
+        items: pinnedSessions.map(session => ({
+          icon: Pin,
+          id: `pinned-${session.id}`,
+          keywords: sessionKeywords(session, 'pinned'),
+          label: session.title,
+          runWithEvent: goSession(session.id)
+        }))
+      })
+    }
+
     if (sessions.length > 0) {
       result.push({
         heading: t.commandCenter.sections.sessions,
@@ -1276,6 +1308,7 @@ function CommandPaletteBody({ onExited }: { onExited: () => void }) {
     goSession,
     mcpServers,
     mode,
+    pinnedSessions,
     previewTheme,
     resolvedMode,
     resolveThemeMode,

From 3cc24b01308f6a75865563541a15edfe2f1a9def Mon Sep 17 00:00:00 2001
From: KoNit-K <konit.block@protonmail.com>
Date: Thu, 17 Sep 2026 16:49:35 +0800
Subject: [PATCH 08/61] feat(desktop): add composer dictation keybind

(cherry picked from commit bb6e188bb6fe6b59ac8f829b3461b2b50ef571e2)
---
 .../src/app/chat/composer/focus.test.ts       | 18 +++++++++++++++++
 apps/desktop/src/app/chat/composer/focus.ts   |  9 +++++++++
 .../chat/composer/hooks/use-composer-voice.ts | 10 +++++++++-
 apps/desktop/src/app/hooks/use-keybinds.ts    |  3 ++-
 apps/desktop/src/i18n/ar.ts                   |  1 +
 apps/desktop/src/i18n/en.ts                   |  1 +
 apps/desktop/src/i18n/ru.ts                   |  1 +
 apps/desktop/src/i18n/zh.ts                   |  1 +
 apps/desktop/src/lib/keybinds/actions.test.ts | 20 ++++++++++++++++++-
 apps/desktop/src/lib/keybinds/actions.ts      |  3 +++
 apps/desktop/src/lib/keybinds/combo.test.ts   |  3 +++
 apps/desktop/src/lib/keybinds/combo.ts        |  1 +
 12 files changed, 68 insertions(+), 3 deletions(-)

diff --git a/apps/desktop/src/app/chat/composer/focus.test.ts b/apps/desktop/src/app/chat/composer/focus.test.ts
index 2b3cb782e1..dbb7292ba8 100644
--- a/apps/desktop/src/app/chat/composer/focus.test.ts
+++ b/apps/desktop/src/app/chat/composer/focus.test.ts
@@ -7,9 +7,11 @@ import {
   focusComposerInput,
   getActiveComposer,
   markActiveComposer,
+  onComposerDictationRequest,
   onComposerFocusRequest,
   onComposerModelMenuRequest,
   releaseActiveComposer,
+  requestComposerDictation,
   requestComposerFocus,
   requestModelMenuToggle
 } from './focus'
@@ -317,3 +319,19 @@ describe('requestModelMenuToggle', () => {
     expect(await collectModelMenuTargets()).toEqual([])
   })
 })
+
+describe('requestComposerDictation', () => {
+  it('delivers the request only to the active visible composer', async () => {
+    mountSurface('main', true)
+    mountSurface('tile:front')
+    markActiveComposer('tile:front')
+    const targets: string[] = []
+    const off = onComposerDictationRequest(target => targets.push(target))
+
+    requestComposerDictation('active')
+    await new Promise(resolve => window.setTimeout(resolve, 0))
+    off()
+
+    expect(targets).toEqual(['tile:front'])
+  })
+})
diff --git a/apps/desktop/src/app/chat/composer/focus.ts b/apps/desktop/src/app/chat/composer/focus.ts
index b9d6caf863..82b6374820 100644
--- a/apps/desktop/src/app/chat/composer/focus.ts
+++ b/apps/desktop/src/app/chat/composer/focus.ts
@@ -50,6 +50,7 @@ const ATTACH_IMAGES_EVENT = 'hermes:composer-attach-images'
 const INSERT_REFS_EVENT = 'hermes:composer-insert-refs'
 const SUBMIT_EVENT = 'hermes:composer-submit'
 const VOICE_TOGGLE_EVENT = 'hermes:composer-voice-toggle'
+const DICTATION_EVENT = 'hermes:composer-dictation'
 const MODEL_MENU_EVENT = 'hermes:composer-model-menu'
 
 /** Inline edit composer root — mounted only while a user bubble is being edited. */
@@ -366,6 +367,14 @@ export const requestVoiceToggle = (target: ComposerTarget | 'active' = 'active')
 export const onComposerVoiceToggleRequest = (handler: (target: ComposerTarget) => void) =>
   subscribe<{ target: ComposerTarget }>(VOICE_TOGGLE_EVENT, ({ target }) => handler(target))
 
+/** Start or stop dictation on one composer. Like voice conversation, the
+ * rebindable action targets only the active visible composer. */
+export const requestComposerDictation = (target: ComposerTarget | 'active' = 'active') =>
+  dispatch<{ target: ComposerTarget }>(DICTATION_EVENT, { target: resolve(target) })
+
+export const onComposerDictationRequest = (handler: (target: ComposerTarget) => void) =>
+  subscribe<{ target: ComposerTarget }>(DICTATION_EVENT, ({ target }) => handler(target))
+
 /** The chat surface inside the zone the pointer is over, if any. Mirrors the
  *  tab verbs' hover-first targeting (`tabTargetGroupId`, #74447): the model
  *  hotkey lands in the pane you're pointing at without clicking into it first.
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-voice.ts b/apps/desktop/src/app/chat/composer/hooks/use-composer-voice.ts
index a46513802c..a411dbcc62 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-composer-voice.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-voice.ts
@@ -19,7 +19,7 @@ import { resumeWakeAfterVoice } from '@/store/wake-word'
 
 import { pinFloatingComposerCapture } from '../floating-target'
 import type { ComposerTarget } from '../focus'
-import { onComposerVoiceToggleRequest } from '../focus'
+import { onComposerDictationRequest, onComposerVoiceToggleRequest } from '../focus'
 import { useComposerScope, useComposerSurfaceId } from '../scope'
 import type { ChatBarProps } from '../types'
 
@@ -313,6 +313,14 @@ export function useComposerVoice({
     [target, toggleVoiceConversation]
   )
 
+  // The bindable `composer.dictate` action shares the mic button's callback,
+  // including its recording/transcribing state machine. Ignore disabled
+  // composers so an unavailable draft cannot acquire the microphone.
+  useEffect(
+    () => onComposerDictationRequest(requested => requested === target && !disabled && dictate()),
+    [dictate, disabled, target]
+  )
+
   useEffect(() => {
     if (target === 'main' && !disabled && takeVoiceConversationStart(voiceStartRequest) && !voiceConversationActive) {
       activateConversation()
diff --git a/apps/desktop/src/app/hooks/use-keybinds.ts b/apps/desktop/src/app/hooks/use-keybinds.ts
index 347f6ebe9e..9efd2d8758 100644
--- a/apps/desktop/src/app/hooks/use-keybinds.ts
+++ b/apps/desktop/src/app/hooks/use-keybinds.ts
@@ -69,7 +69,7 @@ import { toggleStatusbarVisible } from '@/store/statusbar-prefs'
 import { openNewWindow } from '@/store/windows'
 import { useTheme } from '@/themes/context'
 
-import { requestComposerFocus, requestModelMenuToggle, requestVoiceToggle } from '../chat/composer/focus'
+import { requestComposerDictation, requestComposerFocus, requestModelMenuToggle, requestVoiceToggle } from '../chat/composer/focus'
 import { handleComposerFocusChord } from '../chat/composer/focus-chord'
 import { handleWindowPaste } from '../chat/composer/paste-to-focus'
 import { openSession } from '../open-session'
@@ -197,6 +197,7 @@ export function useKeybinds(deps: KeybindRuntimeDeps): void {
       }
     },
     'composer.voice': requestVoiceToggle,
+    'composer.dictate': requestComposerDictation,
 
     // On the Settings overlay, ⌘K scopes to settings search; the second press
     // (or Esc) still closes as usual via toggle.
diff --git a/apps/desktop/src/i18n/ar.ts b/apps/desktop/src/i18n/ar.ts
index fb1b022ab7..0e3e7ad456 100644
--- a/apps/desktop/src/i18n/ar.ts
+++ b/apps/desktop/src/i18n/ar.ts
@@ -311,6 +311,7 @@ export const ar = defineLocale({
       'composer.focus': 'التركيز على المحرّر',
       'composer.modelPicker': 'فتح منتقي النموذج',
       'composer.voice': 'بدء / إيقاف المحادثة الصوتية',
+      'composer.dictate': 'بدء / إيقاف الإملاء',
       'view.toggleSidebar': 'تبديل الشريط الجانبي للجلسات',
       'view.toggleRightSidebar': 'تبديل متصفح الملفات',
       'view.toggleReview': 'تبديل لوحة المراجعة',
diff --git a/apps/desktop/src/i18n/en.ts b/apps/desktop/src/i18n/en.ts
index 4a0b524887..6b1ed6af50 100644
--- a/apps/desktop/src/i18n/en.ts
+++ b/apps/desktop/src/i18n/en.ts
@@ -661,6 +661,7 @@ export const en: Translations = {
       'composer.focus': 'Focus composer',
       'composer.modelPicker': 'Open model picker',
       'composer.voice': 'Start / stop voice conversation',
+      'composer.dictate': 'Start / stop dictation',
       'view.toggleSidebar': 'Toggle sessions sidebar',
       'view.cycleSidebarGrouping': 'Cycle session grouping',
       'view.toggleRightSidebar': 'Toggle file browser',
diff --git a/apps/desktop/src/i18n/ru.ts b/apps/desktop/src/i18n/ru.ts
index 1d02c77451..e3f6dbcc0d 100644
--- a/apps/desktop/src/i18n/ru.ts
+++ b/apps/desktop/src/i18n/ru.ts
@@ -333,6 +333,7 @@ export const ru = defineLocale({
       'composer.focus': 'Сфокусировать композер',
       'composer.modelPicker': 'Открыть выбор модели',
       'composer.voice': 'Начать / остановить голосовой диалог',
+      'composer.dictate': 'Начать / остановить диктовку',
       'view.toggleSidebar': 'Показать / скрыть панель сеансов',
       'view.toggleRightSidebar': 'Показать / скрыть браузер файлов',
       'view.toggleReview': 'Показать / скрыть панель ревью',
diff --git a/apps/desktop/src/i18n/zh.ts b/apps/desktop/src/i18n/zh.ts
index 41eb6100dc..b58b0afd83 100644
--- a/apps/desktop/src/i18n/zh.ts
+++ b/apps/desktop/src/i18n/zh.ts
@@ -379,6 +379,7 @@ export const zh = defineLocale({
       'composer.focus': '聚焦输入框',
       'composer.modelPicker': '打开模型选择器',
       'composer.voice': '开始 / 停止语音对话',
+      'composer.dictate': '开始 / 停止听写',
       'view.toggleSidebar': '切换会话侧边栏',
       'view.toggleRightSidebar': '切换文件浏览器',
       'view.toggleReview': '切换审查面板',
diff --git a/apps/desktop/src/lib/keybinds/actions.test.ts b/apps/desktop/src/lib/keybinds/actions.test.ts
index 25acc27356..b3ad202d61 100644
--- a/apps/desktop/src/lib/keybinds/actions.test.ts
+++ b/apps/desktop/src/lib/keybinds/actions.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 
 import { en } from '@/i18n/en'
 
-import { KEYBIND_ACTIONS } from './actions'
+import { defaultBindings, KEYBIND_ACTIONS, keybindAction } from './actions'
 
 // Relationship checks between the action table and its consumers, not the
 // specific chord or wording any one action ships with.
@@ -19,4 +19,22 @@ describe('KEYBIND_ACTIONS', () => {
 
     expect(missing).toEqual([])
   })
+
+  it('keeps session archive registered and unbound by default', () => {
+    const action = keybindAction('session.archive')
+
+    expect(action).toMatchObject({ category: 'session', defaults: [] })
+    expect(defaultBindings()['session.archive']).toEqual([])
+    expect(en.keybinds.actions['session.archive']).toBe('Archive current session')
+    expect(KEYBIND_ACTIONS.filter(candidate => candidate.id === 'session.archive')).toHaveLength(1)
+  })
+
+  it('registers dictation with an English label and no default chord', () => {
+    const action = keybindAction('composer.dictate')
+
+    expect(action).toMatchObject({ category: 'composer', defaults: [] })
+    expect(defaultBindings()['composer.dictate']).toEqual([])
+    expect(en.keybinds.actions['composer.dictate']).toBe('Start / stop dictation')
+    expect(KEYBIND_ACTIONS.filter(candidate => candidate.id === 'composer.dictate')).toHaveLength(1)
+  })
 })
diff --git a/apps/desktop/src/lib/keybinds/actions.ts b/apps/desktop/src/lib/keybinds/actions.ts
index be9efa3c3a..cdcd62dc66 100644
--- a/apps/desktop/src/lib/keybinds/actions.ts
+++ b/apps/desktop/src/lib/keybinds/actions.ts
@@ -67,6 +67,9 @@ export const KEYBIND_ACTIONS: readonly KeybindActionMeta[] = [
   // chord, so ship it unbound there (rebindable in the panel) rather than
   // stealing the long-standing sidebar binding.
   { id: 'composer.voice', category: 'composer', defaults: IS_MAC ? ['ctrl+b'] : [] },
+  // Dictation is intentionally unbound: it is available for users who prefer
+  // a keyboard trigger without claiming a chord from text entry by default.
+  { id: 'composer.dictate', category: 'composer', defaults: [] },
 
   // ── Profiles ─────────────────────────────────────────────────────────────
   { id: 'profile.default', category: 'profiles', defaults: ['mod+d'] },
diff --git a/apps/desktop/src/lib/keybinds/combo.test.ts b/apps/desktop/src/lib/keybinds/combo.test.ts
index cbc9592c74..4a8a035f3d 100644
--- a/apps/desktop/src/lib/keybinds/combo.test.ts
+++ b/apps/desktop/src/lib/keybinds/combo.test.ts
@@ -92,6 +92,9 @@ describe('actionAllowedInInput', () => {
     // (or the pre-#76185 'shift+n') must not fire while the user types N.
     expect(actionAllowedInInput('session.new', 'n')).toBe(false)
     expect(actionAllowedInInput('session.new', 'shift+n')).toBe(false)
+    // Dictation is intentionally bindable without a shipped chord. A user who
+    // assigns a bare/Shift chord expects it to remain reachable from the draft.
+    expect(actionAllowedInInput('composer.dictate', 'shift+d')).toBe(true)
   })
 
   it('leaves text navigation chords with the focused input even when rebound to an allowed action', () => {
diff --git a/apps/desktop/src/lib/keybinds/combo.ts b/apps/desktop/src/lib/keybinds/combo.ts
index b844de725f..e63da9a74a 100644
--- a/apps/desktop/src/lib/keybinds/combo.ts
+++ b/apps/desktop/src/lib/keybinds/combo.ts
@@ -258,6 +258,7 @@ export function isEditableTarget(target: EventTarget | null): boolean {
 const INPUT_SAFE_ACTIONS = new Set([
   'composer.modelPicker',
   'composer.voice',
+  'composer.dictate',
   'keybinds.openPanel',
   'nav.commandPalette',
   'session.next',

From 352b89d466a5af8f24427087b42c369b6b67fd18 Mon Sep 17 00:00:00 2001
From: brooklyn! <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 23 Sep 2026 21:22:52 -0500
Subject: [PATCH 09/61] feat(desktop): add function-key voice shortcuts

---
 .../electron/desktop-profile-preload.test.ts  |  13 ++
 apps/desktop/electron/f12-shortcut.test.ts    |  32 ++++
 apps/desktop/electron/f12-shortcut.ts         |  40 ++++
 apps/desktop/electron/main.ts                 |  33 +++-
 apps/desktop/electron/preload.ts              |   7 +
 .../use-composer-voice-shortcuts.test.tsx     | 174 ++++++++++++++++++
 apps/desktop/src/app/hooks/use-keybinds.ts    |  44 ++++-
 .../src/app/settings/config-settings.tsx      |   3 +
 .../src/app/settings/config-subpages.ts       |   2 +-
 apps/desktop/src/app/settings/constants.ts    |   2 -
 .../app/settings/voice-field-visible.test.ts  |   2 +-
 apps/desktop/src/global.d.ts                  |  12 ++
 apps/desktop/src/i18n/ar.ts                   |   6 +-
 apps/desktop/src/i18n/de.ts                   |   1 -
 apps/desktop/src/i18n/en.ts                   |   3 +
 apps/desktop/src/i18n/es.ts                   |   1 -
 apps/desktop/src/i18n/fr.ts                   |   1 -
 apps/desktop/src/i18n/ja.ts                   |   6 +-
 apps/desktop/src/i18n/ru.ts                   |   6 +-
 apps/desktop/src/i18n/types.ts                |   2 +
 apps/desktop/src/i18n/zh-hant.ts              |   4 +-
 apps/desktop/src/i18n/zh.ts                   |   4 +-
 apps/desktop/src/lib/keybinds/actions.ts      |   8 +-
 apps/desktop/src/lib/keybinds/combo.test.ts   |  12 ++
 apps/desktop/src/lib/keybinds/combo.ts        |   4 +
 25 files changed, 399 insertions(+), 23 deletions(-)
 create mode 100644 apps/desktop/electron/f12-shortcut.test.ts
 create mode 100644 apps/desktop/electron/f12-shortcut.ts
 create mode 100644 apps/desktop/src/app/chat/composer/hooks/use-composer-voice-shortcuts.test.tsx

diff --git a/apps/desktop/electron/desktop-profile-preload.test.ts b/apps/desktop/electron/desktop-profile-preload.test.ts
index d8e07a0a79..954f8cdd48 100644
--- a/apps/desktop/electron/desktop-profile-preload.test.ts
+++ b/apps/desktop/electron/desktop-profile-preload.test.ts
@@ -8,6 +8,7 @@ const electron = vi.hoisted(() => ({
     invoke: vi.fn(async () => ({ ok: true })),
     on: vi.fn(),
     removeListener: vi.fn(),
+    send: vi.fn(),
     sendSync: vi.fn(() => ({}))
   },
   webFrame: {},
@@ -30,6 +31,18 @@ test('the native preload exposes routed peer opening and default preference even
   assert.deepEqual(electron.ipcRenderer.invoke.mock.lastCall, ['hermes:profile:default:set', route])
   await bridge.profile.getDefault()
   assert.deepEqual(electron.ipcRenderer.invoke.mock.lastCall, ['hermes:profile:default:get'])
+  bridge.setF12ShortcutActive(true)
+  assert.equal(electron.ipcRenderer.send.mock.lastCall?.[0], 'hermes:f12ShortcutActive')
+  assert.equal(electron.ipcRenderer.send.mock.lastCall?.[1], true)
+
+  const shortcutInputs: unknown[] = []
+  const stopShortcut = bridge.onF12Shortcut((input: unknown) => shortcutInputs.push(input))
+  const [shortcutChannel, shortcutListener] = electron.ipcRenderer.on.mock.lastCall!
+  assert.equal(shortcutChannel, 'hermes:f12-shortcut')
+  shortcutListener({}, { key: 'F12', repeat: true })
+  assert.deepEqual(shortcutInputs, [{ key: 'F12', repeat: true }])
+  stopShortcut()
+  assert.deepEqual(electron.ipcRenderer.removeListener.mock.lastCall, [shortcutChannel, shortcutListener])
 
   const changes: unknown[] = []
   const unsubscribe = bridge.profile.onDefaultChanged((value: unknown) => changes.push(value))
diff --git a/apps/desktop/electron/f12-shortcut.test.ts b/apps/desktop/electron/f12-shortcut.test.ts
new file mode 100644
index 0000000000..5efe4b7388
--- /dev/null
+++ b/apps/desktop/electron/f12-shortcut.test.ts
@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict'
+
+import { test } from 'vitest'
+
+import { f12ShortcutDecision, toF12KeyboardEventPayload } from './f12-shortcut'
+
+test('arbitrates only native F12 keydown and preserves repeat/modifiers for forwarding', () => {
+  const input = {
+    alt: true,
+    code: 'F12',
+    control: false,
+    isAutoRepeat: true,
+    key: 'F12',
+    meta: true,
+    shift: false,
+    type: 'keyDown'
+  }
+
+  assert.equal(f12ShortcutDecision(input, true, false), 'forward')
+  assert.equal(f12ShortcutDecision({ ...input, type: 'keyUp' }, true, false), 'ignore')
+  assert.equal(f12ShortcutDecision(input, false, true), 'block')
+  assert.equal(f12ShortcutDecision(input, false, false), 'devtools')
+  assert.deepEqual(toF12KeyboardEventPayload(input), {
+    alt: true,
+    code: 'F12',
+    control: false,
+    key: 'F12',
+    meta: true,
+    repeat: true,
+    shift: false
+  })
+})
diff --git a/apps/desktop/electron/f12-shortcut.ts b/apps/desktop/electron/f12-shortcut.ts
new file mode 100644
index 0000000000..b976df0a17
--- /dev/null
+++ b/apps/desktop/electron/f12-shortcut.ts
@@ -0,0 +1,40 @@
+export interface F12Input {
+  alt?: boolean
+  code?: string
+  control?: boolean
+  isAutoRepeat?: boolean
+  key: string
+  meta?: boolean
+  shift?: boolean
+  type: string
+}
+
+export type F12ShortcutDecision = 'block' | 'devtools' | 'forward' | 'ignore'
+
+export function f12ShortcutDecision(input: F12Input, shortcutActive: boolean, disabled: boolean): F12ShortcutDecision {
+  if (input.type !== 'keyDown') {
+    return 'ignore'
+  }
+
+  if (shortcutActive) {
+    return 'forward'
+  }
+
+  if (disabled) {
+    return 'block'
+  }
+
+  return 'devtools'
+}
+
+export function toF12KeyboardEventPayload(input: F12Input) {
+  return {
+    alt: Boolean(input.alt),
+    code: input.code,
+    control: Boolean(input.control),
+    key: input.key,
+    meta: Boolean(input.meta),
+    repeat: Boolean(input.isAutoRepeat),
+    shift: Boolean(input.shift)
+  }
+}
diff --git a/apps/desktop/electron/main.ts b/apps/desktop/electron/main.ts
index b6b23d8d4c..cc4c5ceb3a 100644
--- a/apps/desktop/electron/main.ts
+++ b/apps/desktop/electron/main.ts
@@ -203,6 +203,7 @@ import {
   terminalScriptExtension,
   tuiResumeArgs
 } from './external-terminal'
+import { f12ShortcutDecision, toF12KeyboardEventPayload } from './f12-shortcut'
 import { type FaviconIo, resolveFavicon } from './favicon'
 import { findGitBash as _findGitBash } from './find-git-bash'
 import {
@@ -1816,6 +1817,7 @@ const remoteHeaderSessions = new WeakSet<object>()
 const remoteWsHeaderStore = createRemoteWsHeaderStore()
 const previewWatchers = new Map()
 let previewShortcutActive = false
+const f12ShortcutActiveWindows = new Set<number>()
 let nativeThemeListenerInstalled = false
 
 let bootProgressState = {
@@ -7415,11 +7417,26 @@ function installDevToolsShortcut(window) {
   // Only Ctrl+Shift+I (or Cmd+Opt+I on Mac) opens DevTools.
   // F12 is explicitly blocked so Chromium's built-in handler doesn't open it.
   window.webContents.on('before-input-event', (event, input) => {
+    if (input.type !== 'keyDown') {
+      return
+    }
+
     const key = input.key.toLowerCase()
 
-    // F12 opens DevTools by default; block only when the user disabled it.
+    // A renderer binding gets first refusal. Chromium otherwise claims F12
+    // before the renderer can capture or dispatch it.
     if (input.key === 'F12') {
-      if (f12Blocked) {
+      const decision = f12ShortcutDecision(input, f12ShortcutActiveWindows.has(window.webContents.id), f12Blocked)
+
+      if (decision === 'forward') {
+        event.preventDefault()
+
+        window.webContents.send('hermes:f12-shortcut', toF12KeyboardEventPayload(input))
+
+        return
+      }
+
+      if (decision === 'block') {
         event.preventDefault()
 
         return
@@ -16825,6 +16842,18 @@ ipcMain.on('hermes:previewShortcutActive', (_event, active) => {
   previewShortcutActive = Boolean(active)
 })
 
+ipcMain.on('hermes:f12ShortcutActive', (event, active) => {
+  if (active) {
+    f12ShortcutActiveWindows.add(event.sender.id)
+  } else {
+    f12ShortcutActiveWindows.delete(event.sender.id)
+  }
+})
+
+app.on('web-contents-created', (_event, contents) => {
+  contents.once('destroyed', () => f12ShortcutActiveWindows.delete(contents.id))
+})
+
 ipcMain.handle('hermes:requestMicrophoneAccess', async () => {
   if (!IS_MAC || typeof systemPreferences.askForMediaAccess !== 'function') {
     return true
diff --git a/apps/desktop/electron/preload.ts b/apps/desktop/electron/preload.ts
index 5adc951aea..f6f772acf4 100644
--- a/apps/desktop/electron/preload.ts
+++ b/apps/desktop/electron/preload.ts
@@ -380,6 +380,13 @@ contextBridge.exposeInMainWorld('hermesDesktop', {
     }
   },
   setDisableF12: blocked => ipcRenderer.send('hermes:devtools:disable-f12', blocked),
+  setF12ShortcutActive: active => ipcRenderer.send('hermes:f12ShortcutActive', Boolean(active)),
+  onF12Shortcut: callback => {
+    const listener = (_event, input) => callback(input)
+    ipcRenderer.on('hermes:f12-shortcut', listener)
+
+    return () => ipcRenderer.removeListener('hermes:f12-shortcut', listener)
+  },
   setPreviewShortcutActive: active => ipcRenderer.send('hermes:previewShortcutActive', Boolean(active)),
   openExternal: url => ipcRenderer.invoke('hermes:openExternal', url),
   mcpOauth: {
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-voice-shortcuts.test.tsx b/apps/desktop/src/app/chat/composer/hooks/use-composer-voice-shortcuts.test.tsx
new file mode 100644
index 0000000000..7d80e2211d
--- /dev/null
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-voice-shortcuts.test.tsx
@@ -0,0 +1,174 @@
+import { act, cleanup, render } from '@testing-library/react'
+import type { ReactNode } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { markActiveComposer, requestComposerDictation, requestVoiceToggle } from '../focus'
+import { ComposerScopeProvider, ComposerSurfaceProvider, MAIN_COMPOSER_SCOPE } from '../scope'
+
+import { useComposerVoice } from './use-composer-voice'
+
+const mocks = vi.hoisted(() => ({
+  conversationEnabled: [] as boolean[],
+  dictate: vi.fn(),
+  endConversation: vi.fn(async () => undefined)
+}))
+
+vi.mock('./use-voice-recorder', () => ({
+  useVoiceRecorder: () => ({
+    dictate: mocks.dictate,
+    voiceActivityState: { elapsedSeconds: 0, level: 0, status: 'idle' },
+    voiceStatus: 'idle'
+  })
+}))
+
+vi.mock('./use-voice-conversation', () => ({
+  useVoiceConversation: ({ enabled }: { enabled: boolean }) => {
+    mocks.conversationEnabled.push(enabled)
+
+    return { end: mocks.endConversation, start: vi.fn(), status: 'idle' }
+  }
+}))
+
+vi.mock('./use-voice-live-conversation', () => ({
+  useVoiceLiveConversation: () => ({ end: mocks.endConversation, start: vi.fn(), status: 'idle' })
+}))
+
+vi.mock('./use-auto-speak-replies', () => ({ useAutoSpeakReplies: vi.fn() }))
+
+vi.mock('@/i18n', () => ({
+  useI18n: () => ({
+    t: {
+      notifications: { voice: {} },
+      assistant: { thread: { readAloudFailed: '' } },
+      settings: { config: { autosaveFailed: '' } }
+    }
+  })
+}))
+
+vi.mock('@/lib/haptics', () => ({ triggerHaptic: vi.fn() }))
+vi.mock('@/lib/spoken-reply', () => ({
+  adoptSpokenReplySession: vi.fn(),
+  markAssistantIdSpoken: vi.fn(),
+  resolveSpokenReply: vi.fn(() => null)
+}))
+vi.mock('@/lib/tts-lease', () => ({
+  CONVERSATION_LEASE: 'conversation',
+  READ_ALOUD_LEASE: 'read-aloud',
+  syncTtsLease: vi.fn(async () => undefined)
+}))
+vi.mock('@/lib/wake-indicator', () => ({ clearWakeIndicator: vi.fn(), syncWakeIndicatorWithVoice: vi.fn() }))
+vi.mock('@/lib/voice-live', () => ({ toLiveHistory: vi.fn(() => []) }))
+vi.mock('@/store/notifications', () => ({ notify: vi.fn(), notifyError: vi.fn() }))
+vi.mock('@/store/voice-live', async () => {
+  const { atom } = await import('nanostores')
+
+  return {
+    $voiceLiveStatus: atom(null),
+    refreshVoiceLiveStatus: vi.fn(async () => undefined),
+    selectedVoiceChatMode: vi.fn(() => 'chained')
+  }
+})
+vi.mock('@/store/voice-prefs', async () => {
+  const { atom } = await import('nanostores')
+
+  return {
+    $autoSpeakReplies: atom(false),
+    $voiceStopPhrase: atom(null),
+    setAutoSpeakReplies: vi.fn(async () => undefined)
+  }
+})
+vi.mock('@/store/gateway', async () => {
+  const { atom } = await import('nanostores')
+
+  return { $gateway: atom(null) }
+})
+vi.mock('@/store/composer-input-history', () => ({ resetBrowseState: vi.fn() }))
+vi.mock('@/store/wake-word', () => ({ resumeWakeAfterVoice: vi.fn(async () => undefined) }))
+vi.mock('../floating-target', () => ({ pinFloatingComposerCapture: vi.fn(() => undefined) }))
+
+function Composer({ disabled, target }: { disabled: boolean; target: string }) {
+  useComposerVoice({
+    busy: false,
+    clearDraft: vi.fn(),
+    disabled,
+    focusInput: vi.fn(),
+    insertText: vi.fn(),
+    maxRecordingSeconds: 60,
+    onSubmit: vi.fn(async () => true),
+    onTranscribeAudio: vi.fn(async () => 'spoken text'),
+    sessionId: null,
+    target
+  })
+
+  return null
+}
+
+function mountComposer(target: string, disabled: boolean, hidden = false) {
+  const scope = { ...MAIN_COMPOSER_SCOPE, target }
+
+  return (
+    <ComposerScopeProvider value={scope}>
+      <ComposerSurfaceProvider value={`${target}-surface`}>
+        <div data-composer-target={target} data-pane-hidden={hidden ? '' : undefined}>
+          <Composer disabled={disabled} target={target} />
+        </div>
+      </ComposerSurfaceProvider>
+    </ComposerScopeProvider>
+  )
+}
+
+function renderComposers(children: ReactNode) {
+  return render(children)
+}
+
+afterEach(() => {
+  cleanup()
+  document.body.innerHTML = ''
+  mocks.dictate.mockClear()
+  mocks.endConversation.mockClear()
+  mocks.conversationEnabled.length = 0
+  markActiveComposer('main')
+})
+
+describe('composer voice shortcuts', () => {
+  it('dictates only on the active visible target and ignores a disabled target', async () => {
+    renderComposers(
+      <>
+        {mountComposer('main', true, true)}
+        {mountComposer('tile:front', false)}
+      </>
+    )
+    markActiveComposer('tile:front')
+
+    await act(async () => {
+      requestComposerDictation('active')
+      await new Promise(resolve => window.setTimeout(resolve, 0))
+    })
+    expect(mocks.dictate).toHaveBeenCalledTimes(1)
+
+    await act(async () => {
+      requestComposerDictation('main')
+      await new Promise(resolve => window.setTimeout(resolve, 0))
+    })
+    expect(mocks.dictate).toHaveBeenCalledTimes(1)
+  })
+
+  it('forwards repeated dictation requests without toggling voice conversation', async () => {
+    renderComposers(mountComposer('main', false))
+
+    await act(async () => {
+      requestComposerDictation('active')
+      requestComposerDictation('active')
+      await new Promise(resolve => window.setTimeout(resolve, 0))
+    })
+    expect(mocks.dictate).toHaveBeenCalledTimes(2)
+    expect(mocks.endConversation).not.toHaveBeenCalled()
+
+    await act(async () => {
+      requestVoiceToggle('active')
+      await new Promise(resolve => window.setTimeout(resolve, 0))
+    })
+    expect(mocks.dictate).toHaveBeenCalledTimes(2)
+    expect(mocks.conversationEnabled).toContain(true)
+  })
+})
diff --git a/apps/desktop/src/app/hooks/use-keybinds.ts b/apps/desktop/src/app/hooks/use-keybinds.ts
index 9efd2d8758..d28a663554 100644
--- a/apps/desktop/src/app/hooks/use-keybinds.ts
+++ b/apps/desktop/src/app/hooks/use-keybinds.ts
@@ -69,7 +69,12 @@ import { toggleStatusbarVisible } from '@/store/statusbar-prefs'
 import { openNewWindow } from '@/store/windows'
 import { useTheme } from '@/themes/context'
 
-import { requestComposerDictation, requestComposerFocus, requestModelMenuToggle, requestVoiceToggle } from '../chat/composer/focus'
+import {
+  requestComposerDictation,
+  requestComposerFocus,
+  requestModelMenuToggle,
+  requestVoiceToggle
+} from '../chat/composer/focus'
 import { handleComposerFocusChord } from '../chat/composer/focus-chord'
 import { handleWindowPaste } from '../chat/composer/paste-to-focus'
 import { openSession } from '../open-session'
@@ -326,6 +331,43 @@ export function useKeybinds(deps: KeybindRuntimeDeps): void {
     []
   )
 
+  useEffect(() => {
+    const updateF12Ownership = () => {
+      const hasF12Binding = [...$comboIndex.get().keys()].some(combo => combo === 'f12' || combo.endsWith('+f12'))
+      window.hermesDesktop?.setF12ShortcutActive?.(hasF12Binding || $capture.get() !== null)
+    }
+
+    const stopBindings = $comboIndex.subscribe(updateF12Ownership)
+    const stopCapture = $capture.subscribe(updateF12Ownership)
+
+    return () => {
+      stopBindings()
+      stopCapture()
+      window.hermesDesktop?.setF12ShortcutActive?.(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    const stopF12Shortcut = window.hermesDesktop?.onF12Shortcut?.(input => {
+      const target = document.activeElement ?? document.body ?? document.documentElement
+      target.dispatchEvent(
+        new KeyboardEvent('keydown', {
+          altKey: input.alt,
+          bubbles: true,
+          cancelable: true,
+          code: input.code,
+          ctrlKey: input.control,
+          key: input.key,
+          metaKey: input.meta,
+          repeat: input.repeat,
+          shiftKey: input.shift
+        })
+      )
+    })
+
+    return () => stopF12Shortcut?.()
+  }, [])
+
   useEffect(() => {
     const onKeyDown = (event: KeyboardEvent) => {
       // An active IME composition owns the keyboard. Windows Chinese IMEs
diff --git a/apps/desktop/src/app/settings/config-settings.tsx b/apps/desktop/src/app/settings/config-settings.tsx
index acb7a5e371..defe752199 100644
--- a/apps/desktop/src/app/settings/config-settings.tsx
+++ b/apps/desktop/src/app/settings/config-settings.tsx
@@ -455,6 +455,9 @@ function ConfigSettingsInner({
           where image-attachment behavior already lives, so this sits above the
           schema fields for that section. */}
       {showAttachments ? <AttachmentSizeSetting /> : null}
+      {activeSectionId === 'voice' ? (
+        <ListRow description={c.voiceShortcutHintDesc} title={c.voiceShortcutHintTitle} />
+      ) : null}
       {showEmptyState ? (
         <EmptyState description={c.emptyDesc} title={c.emptyTitle} />
       ) : visibleFields.length === 0 ? null : (
diff --git a/apps/desktop/src/app/settings/config-subpages.ts b/apps/desktop/src/app/settings/config-subpages.ts
index d3bc519aea..fe6f9d335c 100644
--- a/apps/desktop/src/app/settings/config-subpages.ts
+++ b/apps/desktop/src/app/settings/config-subpages.ts
@@ -72,7 +72,7 @@ const CONFIG_SUBPAGE_DEFINITIONS: Record<string, ConfigSubpageDefinition[]> = {
     {
       id: 'conversation',
       labelKey: 'voiceConversation',
-      fields: ['voice.voice_chat_mode', 'voice.record_key', 'voice.max_recording_seconds', 'voice.client_direct'],
+      fields: ['voice.voice_chat_mode', 'voice.max_recording_seconds', 'voice.client_direct'],
       prefixes: ['voice.gpt_live.']
     },
     { id: 'transcription', labelKey: 'voiceTranscription', prefixes: ['stt.'] },
diff --git a/apps/desktop/src/app/settings/constants.ts b/apps/desktop/src/app/settings/constants.ts
index 28930d893d..4dd955dddb 100644
--- a/apps/desktop/src/app/settings/constants.ts
+++ b/apps/desktop/src/app/settings/constants.ts
@@ -466,7 +466,6 @@ export const FIELD_LABELS: Record<string, string> = defineFieldCopy({
     maxSnapshots: 'Checkpoint Limit'
   },
   voice: {
-    recordKey: 'Voice Shortcut',
     maxRecordingSeconds: 'Max Recording Length',
     autoTts: 'Read Responses Aloud',
     voiceChatMode: 'Voice Chat Mode',
@@ -805,7 +804,6 @@ export const SECTIONS: DesktopConfigSection[] = [
       'stt.elevenlabs.language_code',
       'stt.elevenlabs.tag_audio_events',
       'stt.elevenlabs.diarize',
-      'voice.record_key',
       'voice.max_recording_seconds',
       'voice.client_direct'
     ]
diff --git a/apps/desktop/src/app/settings/voice-field-visible.test.ts b/apps/desktop/src/app/settings/voice-field-visible.test.ts
index 9873da79fb..897fb72e89 100644
--- a/apps/desktop/src/app/settings/voice-field-visible.test.ts
+++ b/apps/desktop/src/app/settings/voice-field-visible.test.ts
@@ -15,7 +15,7 @@ describe('voiceFieldVisible', () => {
   it('always shows top-level + non-provider keys', () => {
     const config = cfg()
 
-    for (const key of ['tts.provider', 'stt.enabled', 'stt.provider', 'voice.auto_tts', 'voice.record_key']) {
+    for (const key of ['tts.provider', 'stt.enabled', 'stt.provider', 'voice.auto_tts']) {
       expect(voiceFieldVisible(key, config)).toBe(true)
     }
   })
diff --git a/apps/desktop/src/global.d.ts b/apps/desktop/src/global.d.ts
index f0e1fa45a4..a10fe6e89b 100644
--- a/apps/desktop/src/global.d.ts
+++ b/apps/desktop/src/global.d.ts
@@ -386,6 +386,18 @@ declare global {
         onChanged: (callback: (status: { enabled: boolean; available: boolean }) => void) => () => void
       }
       setDisableF12?: (blocked: boolean) => void
+      setF12ShortcutActive?: (active: boolean) => void
+      onF12Shortcut?: (
+        callback: (input: {
+          alt?: boolean
+          code?: string
+          control?: boolean
+          key: string
+          meta?: boolean
+          repeat?: boolean
+          shift?: boolean
+        }) => void
+      ) => () => void
       setPreviewShortcutActive?: (active: boolean) => void
       openExternal: (url: string) => Promise<void>
       /** One-shot loopback callback listener for MCP OAuth against remote
diff --git a/apps/desktop/src/i18n/ar.ts b/apps/desktop/src/i18n/ar.ts
index 0e3e7ad456..18e3eecad9 100644
--- a/apps/desktop/src/i18n/ar.ts
+++ b/apps/desktop/src/i18n/ar.ts
@@ -763,7 +763,6 @@ export const ar = defineLocale({
       'browser.autoLocalForPrivateUrls': 'متصفح محلي للروابط الخاصة',
       'checkpoints.enabled': 'نقاط حفظ الملفات',
       'checkpoints.maxSnapshots': 'حد نقاط الحفظ',
-      'voice.recordKey': 'اختصار الصوت',
       'voice.maxRecordingSeconds': 'أقصى مدة للتسجيل',
       'voice.autoTts': 'قراءة الردود صوتياً',
       'stt.enabled': 'تحويل الكلام إلى نص',
@@ -909,7 +908,10 @@ export const ar = defineLocale({
       failedLoad: 'فشل تحميل الإعدادات',
       autosaveFailed: 'فشل الحفظ التلقائي',
       imported: 'تم استيراد الإعدادات',
-      invalidJson: 'JSON غير صالح'
+      invalidJson: 'JSON غير صالح',
+      voiceShortcutHintTitle: 'اختصار تسجيل الصوت',
+      voiceShortcutHintDesc:
+        'اضبط اختصار تسجيل الصوت من الإعدادات ← اختصارات لوحة المفاتيح («بدء / إيقاف الإملاء»). قيمة voice.record_key مخصصة لـ CLI وTUI فقط.'
     },
     hudModifier: {
       title: 'استدعاء HUD بضغطة',
diff --git a/apps/desktop/src/i18n/de.ts b/apps/desktop/src/i18n/de.ts
index 537a81dee4..689d129cc6 100644
--- a/apps/desktop/src/i18n/de.ts
+++ b/apps/desktop/src/i18n/de.ts
@@ -1303,7 +1303,6 @@ export const de = defineLocale({
         maxSnapshots: 'Checkpoint-Limit'
       },
       voice: {
-        recordKey: 'Sprach-Tastenkürzel',
         maxRecordingSeconds: 'Maximale Aufnahmelänge',
         autoTts: 'Antworten vorlesen',
         voiceChatMode: 'Sprachchat-Modus',
diff --git a/apps/desktop/src/i18n/en.ts b/apps/desktop/src/i18n/en.ts
index 6b1ed6af50..59d5e97359 100644
--- a/apps/desktop/src/i18n/en.ts
+++ b/apps/desktop/src/i18n/en.ts
@@ -1342,6 +1342,9 @@ export const en: Translations = {
         'How big a local file Desktop will load for previews and image attach, in MB. Default is 16. Remote non-image attach uses a separate 256 MB cap. Setting this very high loads the whole file into memory and can freeze or crash the app.',
       attachmentSizeUnit: 'MB',
       attachmentSizeLabel: 'Max preview / image load size in megabytes',
+      voiceShortcutHintTitle: 'Voice recording shortcut',
+      voiceShortcutHintDesc:
+        'Set the voice recording shortcut in Settings → Keyboard Shortcuts ("Start / stop dictation"). The voice.record_key config value only applies to the CLI and TUI.',
       showOptions: 'Show options'
     },
     hudModifier: {
diff --git a/apps/desktop/src/i18n/es.ts b/apps/desktop/src/i18n/es.ts
index 29c8c17bf6..6859777cb8 100644
--- a/apps/desktop/src/i18n/es.ts
+++ b/apps/desktop/src/i18n/es.ts
@@ -1300,7 +1300,6 @@ export const es = defineLocale({
         maxSnapshots: 'Límite de checkpoints'
       },
       voice: {
-        recordKey: 'Atajo de voz',
         maxRecordingSeconds: 'Duración máxima de grabación',
         autoTts: 'Leer respuestas en voz alta',
         voiceChatMode: 'Modo de chat de voz',
diff --git a/apps/desktop/src/i18n/fr.ts b/apps/desktop/src/i18n/fr.ts
index 9304114b88..e536dc18c3 100644
--- a/apps/desktop/src/i18n/fr.ts
+++ b/apps/desktop/src/i18n/fr.ts
@@ -1304,7 +1304,6 @@ export const fr = defineLocale({
         maxSnapshots: 'Limite de points de contrôle'
       },
       voice: {
-        recordKey: 'Raccourci vocal',
         maxRecordingSeconds: "Durée maximale d'enregistrement",
         autoTts: 'Lire les réponses à haute voix',
         voiceChatMode: 'Mode de conversation vocale',
diff --git a/apps/desktop/src/i18n/ja.ts b/apps/desktop/src/i18n/ja.ts
index 43fe2f8096..0de1a486f1 100644
--- a/apps/desktop/src/i18n/ja.ts
+++ b/apps/desktop/src/i18n/ja.ts
@@ -794,7 +794,6 @@ export const ja = defineLocale({
         maxSnapshots: 'チェックポイント上限'
       },
       voice: {
-        recordKey: '音声ショートカット',
         maxRecordingSeconds: '最大録音時間',
         autoTts: '応答を読み上げる'
       },
@@ -1027,7 +1026,10 @@ export const ja = defineLocale({
       imported: '設定をインポートしました',
       invalidJson: '設定 JSON が無効です',
       keepAwakeTitle: 'コンピューターをスリープさせない',
-      keepAwakeDesc: '本体のスリープを防ぎ、長時間や夜通しの実行を継続します。画面は暗転できます。'
+      keepAwakeDesc: '本体のスリープを防ぎ、長時間や夜通しの実行を継続します。画面は暗転できます。',
+      voiceShortcutHintTitle: '音声録音ショートカット',
+      voiceShortcutHintDesc:
+        '「設定 → キーボードショートカット」で音声録音ショートカット（「音声入力を開始 / 停止」）を設定します。voice.record_key は CLI と TUI 専用です。'
     },
     hudModifier: {
       title: 'キーをタップして HUD を呼び出す',
diff --git a/apps/desktop/src/i18n/ru.ts b/apps/desktop/src/i18n/ru.ts
index e3f6dbcc0d..e94ede5072 100644
--- a/apps/desktop/src/i18n/ru.ts
+++ b/apps/desktop/src/i18n/ru.ts
@@ -821,7 +821,6 @@ export const ru = defineLocale({
         maxSnapshots: 'Лимит чекпоинтов'
       },
       voice: {
-        recordKey: 'Горячая клавиша голосового ввода',
         maxRecordingSeconds: 'Макс. длительность записи',
         autoTts: 'Зачитывать ответы вслух'
       },
@@ -1089,7 +1088,10 @@ export const ru = defineLocale({
       attachmentSizeDesc:
         'Насколько большой локальный файл приложение будет загружать для превью и вложений, в МБ. По умолчанию 16. Для удалённых неграфических вложений действует отдельный лимит 256 МБ. Слишком большое значение загружает весь файл в память и может подвесить или уронить приложение.',
       attachmentSizeUnit: 'МБ',
-      attachmentSizeLabel: 'Макс. размер превью / загрузки изображений в мегабайтах'
+      attachmentSizeLabel: 'Макс. размер превью / загрузки изображений в мегабайтах',
+      voiceShortcutHintTitle: 'Горячая клавиша записи голоса',
+      voiceShortcutHintDesc:
+        'Настройте горячую клавишу записи голоса в разделе «Настройки → Горячие клавиши» («Начать / остановить диктовку»). Параметр voice.record_key действует только в CLI и TUI.'
     },
     hudModifier: {
       title: 'Вызов HUD коротким нажатием',
diff --git a/apps/desktop/src/i18n/types.ts b/apps/desktop/src/i18n/types.ts
index 3ba6192076..6581d8022d 100644
--- a/apps/desktop/src/i18n/types.ts
+++ b/apps/desktop/src/i18n/types.ts
@@ -1119,6 +1119,8 @@ export interface Translations {
       attachmentSizeDesc: string
       attachmentSizeUnit: string
       attachmentSizeLabel: string
+      voiceShortcutHintTitle: string
+      voiceShortcutHintDesc: string
       showOptions: string
     }
     hudModifier: {
diff --git a/apps/desktop/src/i18n/zh-hant.ts b/apps/desktop/src/i18n/zh-hant.ts
index 3e0194cf50..fc51a2f023 100644
--- a/apps/desktop/src/i18n/zh-hant.ts
+++ b/apps/desktop/src/i18n/zh-hant.ts
@@ -736,7 +736,6 @@ export const zhHant = defineLocale({
         maxSnapshots: '檢查點上限'
       },
       voice: {
-        recordKey: '語音快捷鍵',
         maxRecordingSeconds: '最長錄音時間',
         autoTts: '朗讀回覆',
         voiceChatMode: '語音聊天模式',
@@ -1088,6 +1087,9 @@ export const zhHant = defineLocale({
       invalidJson: '設定 JSON 無效',
       keepAwakeTitle: '保持電腦喚醒',
       keepAwakeDesc: '阻止本機睡眠，讓長時間或整夜執行持續進行。螢幕仍可變暗。',
+      voiceShortcutHintTitle: '語音錄製快捷鍵',
+      voiceShortcutHintDesc:
+        '請在「設定 → 鍵盤快捷鍵」中設定語音錄製快捷鍵（「開始 / 停止聽寫」）。voice.record_key 設定僅適用於 CLI 和 TUI。',
       showOptions: '顯示選項'
     },
     hudModifier: {
diff --git a/apps/desktop/src/i18n/zh.ts b/apps/desktop/src/i18n/zh.ts
index b58b0afd83..f10244c84b 100644
--- a/apps/desktop/src/i18n/zh.ts
+++ b/apps/desktop/src/i18n/zh.ts
@@ -947,7 +947,6 @@ export const zh = defineLocale({
         maxSnapshots: '检查点上限'
       },
       voice: {
-        recordKey: '语音快捷键',
         maxRecordingSeconds: '最长录音时长',
         autoTts: '朗读回复',
         voiceChatMode: '语音聊天模式',
@@ -1307,6 +1306,9 @@ export const zh = defineLocale({
         '桌面端为预览和图片附件加载本地文件的大小上限（MB）。默认为 16。远程非图片附件使用单独的 256 MB 上限。设置过大会将整个文件读入内存，可能导致应用卡死或崩溃。',
       attachmentSizeUnit: 'MB',
       attachmentSizeLabel: '预览 / 图片加载大小上限（MB）',
+      voiceShortcutHintTitle: '语音录制快捷键',
+      voiceShortcutHintDesc:
+        '请在“设置 → 键盘快捷键”中设置语音录制快捷键（“开始 / 停止听写”）。voice.record_key 配置项仅适用于 CLI 和 TUI。',
       showOptions: '显示选项'
     },
     hudModifier: {
diff --git a/apps/desktop/src/lib/keybinds/actions.ts b/apps/desktop/src/lib/keybinds/actions.ts
index cdcd62dc66..fa59fa0e87 100644
--- a/apps/desktop/src/lib/keybinds/actions.ts
+++ b/apps/desktop/src/lib/keybinds/actions.ts
@@ -61,11 +61,9 @@ export const KEYBIND_ACTIONS: readonly KeybindActionMeta[] = [
   // Open WebUI, and Cherry Studio all ship the same chord). Opens the pill's
   // live dropdown on the pane under the pointer, else the active composer.
   { id: 'composer.modelPicker', category: 'composer', defaults: ['mod+shift+m'] },
-  // Voice conversation toggle. Matches the documented `voice.record_key`
-  // (Ctrl+B). On macOS that's literally ⌃B — distinct from the ⌘B sidebar
-  // toggle. Off macOS `ctrl` folds to `mod`, which IS the ⌘B/Ctrl+B sidebar
-  // chord, so ship it unbound there (rebindable in the panel) rather than
-  // stealing the long-standing sidebar binding.
+  // Voice conversation toggle. On macOS that's literally ⌃B — distinct from
+  // the ⌘B sidebar toggle. Off macOS `ctrl` folds to `mod`, which IS the
+  // ⌘B/Ctrl+B sidebar chord, so ship it unbound there.
   { id: 'composer.voice', category: 'composer', defaults: IS_MAC ? ['ctrl+b'] : [] },
   // Dictation is intentionally unbound: it is available for users who prefer
   // a keyboard trigger without claiming a chord from text entry by default.
diff --git a/apps/desktop/src/lib/keybinds/combo.test.ts b/apps/desktop/src/lib/keybinds/combo.test.ts
index 4a8a035f3d..1cb16dcc1d 100644
--- a/apps/desktop/src/lib/keybinds/combo.test.ts
+++ b/apps/desktop/src/lib/keybinds/combo.test.ts
@@ -47,6 +47,18 @@ describe('comboFromEvent', () => {
     expect(comboFromEvent(keydown({ code: 'Tab', ctrlKey: true }))).toBe('mod+tab')
     expect(comboFromEvent(keydown({ code: 'Tab', ctrlKey: true, shiftKey: true }))).toBe('mod+shift+tab')
   })
+
+  it('keeps function and special keys available for custom bindings', () => {
+    expect(comboFromEvent(keydown({ code: 'F1', key: 'F1' }))).toBe('f1')
+    expect(comboFromEvent(keydown({ code: 'F12', key: 'F12' }))).toBe('f12')
+    expect(comboFromEvent(keydown({ code: 'F19', key: 'F19' }))).toBe('f19')
+    expect(comboFromEvent(keydown({ code: 'F18', key: 'F18' }))).toBe('f18')
+    expect(comboFromEvent(keydown({ code: 'CapsLock', key: 'CapsLock' }))).toBe('capslock')
+    expect(comboFromEvent(keydown({ code: 'Space', key: ' ', altKey: true }))).toBe('alt+space')
+    expect(comboFromEvent(keydown({ code: 'KeyV', key: 'v', metaKey: true, shiftKey: true }))).toBe('mod+shift+v')
+    expect(comboFromEvent(keydown({ code: 'F18', key: 'F18', metaKey: true, shiftKey: true }))).toBe('mod+shift+f18')
+    expect(comboFromEvent(keydown({ code: 'F13', key: 'F13', altKey: true }))).toBe('alt+f13')
+  })
 })
 
 describe('canonicalizeCombo', () => {
diff --git a/apps/desktop/src/lib/keybinds/combo.ts b/apps/desktop/src/lib/keybinds/combo.ts
index e63da9a74a..7815c3e445 100644
--- a/apps/desktop/src/lib/keybinds/combo.ts
+++ b/apps/desktop/src/lib/keybinds/combo.ts
@@ -32,6 +32,8 @@ const CODE_TO_KEY: Record<string, string> = {
   Enter: 'enter',
   Escape: 'escape',
   Backspace: 'backspace',
+  Delete: 'delete',
+  CapsLock: 'capslock',
   Tab: 'tab',
   PageUp: 'pageup',
   PageDown: 'pagedown',
@@ -170,6 +172,8 @@ const TOKEN_LABELS: Record<string, string> = {
   enter: '↵',
   escape: 'Esc',
   backspace: '⌫',
+  delete: 'Del',
+  capslock: 'Caps Lock',
   tab: '⇥',
   pageup: 'PgUp',
   pagedown: 'PgDn',

From 1b7e8c45d62f25d30775b6b02c625172c58a891a Mon Sep 17 00:00:00 2001
From: brooklyn! <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 23 Sep 2026 21:50:05 -0500
Subject: [PATCH 10/61] fix(desktop): every settings row renders through one
 ListRow/ToggleRow/Slider/SearchField

Appearance was the only page drawing booleans as an Off | On segmented
control, and two rows hand-wrapped their control in items-end, so the same
kind of setting sat in a different place depending on the page. ListRow now
owns the action slot's alignment (left when stacked, right when wide) and
every on/off preference is a ToggleRow; the two hand-rolled range inputs share
a Slider, the three boxed search inputs use SearchField, and the rows that
cannot be a ListRow lay out on the exported LIST_ROW_COLUMNS token.
---
 .../src/app/settings/appearance-settings.tsx  | 292 ++++++------------
 .../settings/billing/account-row-value.tsx    |   5 +-
 .../app/settings/billing/auto-reload-row.tsx  |   4 +-
 .../settings/billing/current-plan-card.tsx    |   5 +-
 .../src/app/settings/billing/index.tsx        |   4 +-
 .../desktop/src/app/settings/config-field.tsx |  75 +++--
 .../src/app/settings/credential-key-ui.tsx    |   6 +-
 .../app/settings/local-models-settings.tsx    |  17 +-
 .../src/app/settings/model-settings.tsx       |  18 +-
 .../app/settings/notifications-settings.tsx   |   4 +-
 .../desktop/src/app/settings/pet-settings.tsx |  54 +---
 apps/desktop/src/app/settings/primitives.tsx  |  77 ++++-
 apps/desktop/src/components/ui/slider.tsx     |  18 ++
 apps/desktop/src/i18n/ar.ts                   |   2 -
 apps/desktop/src/i18n/de.ts                   |   2 -
 apps/desktop/src/i18n/en.ts                   |   2 -
 apps/desktop/src/i18n/es.ts                   |   2 -
 apps/desktop/src/i18n/fr.ts                   |   2 -
 apps/desktop/src/i18n/ja.ts                   |   2 -
 apps/desktop/src/i18n/ru.ts                   |   2 -
 apps/desktop/src/i18n/types.ts                |   2 -
 apps/desktop/src/i18n/zh-hant.ts              |   2 -
 apps/desktop/src/i18n/zh.ts                   |   2 -
 23 files changed, 253 insertions(+), 346 deletions(-)
 create mode 100644 apps/desktop/src/components/ui/slider.tsx

diff --git a/apps/desktop/src/app/settings/appearance-settings.tsx b/apps/desktop/src/app/settings/appearance-settings.tsx
index 9d38106a30..837cc46b54 100644
--- a/apps/desktop/src/app/settings/appearance-settings.tsx
+++ b/apps/desktop/src/app/settings/appearance-settings.tsx
@@ -4,8 +4,9 @@ import { useEffect, useState } from 'react'
 
 import { useDebounced } from '@/app/hooks/use-debounced'
 import { LanguageSwitcher } from '@/components/language-switcher'
-import { Button } from '@/components/ui/button'
+import { SearchField } from '@/components/ui/search-field'
 import { SegmentedControl } from '@/components/ui/segmented-control'
+import { Slider } from '@/components/ui/slider'
 import type { DesktopMarketplaceSearchItem } from '@/global'
 import { saveHermesConfig } from '@/hermes'
 import { useI18n } from '@/i18n'
@@ -72,14 +73,13 @@ import { $marketplaceInstalls, isUserTheme, removeUserTheme } from '@/themes/use
 
 import { setHermesConfigCache, useHermesConfigRecord } from '../hooks/use-config-record'
 
-import { appearanceSubpageForSetting, type AppearanceSubpageId } from './appearance-subpages'
+import { APPEARANCE_SETTING_IDS, appearanceSubpageForSetting, type AppearanceSubpageId } from './appearance-subpages'
 import { ChatFontSetting } from './chat-font-setting'
 import { MODE_OPTIONS } from './constants'
 import { setNested } from './helpers'
 import { MinimizeToTraySetting } from './minimize-to-tray-setting'
 import { PetSettings } from './pet-settings'
-import { ListRow, SectionHeading, SettingsContent, ToggleRow } from './primitives'
-import { APPEARANCE_SETTING_IDS } from './settings-search'
+import { ListRow, RowFootnoteAction, SectionHeading, SettingsContent, ToggleRow } from './primitives'
 import { TerminalFontSetting } from './terminal-font-setting'
 import { useDeepLinkHighlight } from './use-deep-link-highlight'
 
@@ -121,6 +121,7 @@ function ResumeLastSessionSetting() {
       checked={checked}
       description={a.resumeLastSessionDesc}
       disabled={!config}
+      id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.resumeLastSession)}
       label={a.resumeLastSessionTitle}
       onChange={update}
     />
@@ -362,9 +363,8 @@ interface TranslucencySliderProps {
 function TranslucencySlider({ label, onChange, value }: TranslucencySliderProps) {
   return (
     <>
-      <input
+      <Slider
         aria-label={label}
-        className="h-1 w-40 cursor-pointer appearance-none rounded-full bg-(--ui-stroke-tertiary)"
         max={TRANSLUCENCY_MAX}
         min={TRANSLUCENCY_MIN}
         onBlur={endTranslucencyPeek}
@@ -381,8 +381,6 @@ function TranslucencySlider({ label, onChange, value }: TranslucencySliderProps)
         onPointerDown={beginTranslucencyPeek}
         onPointerUp={endTranslucencyPeek}
         step={TRANSLUCENCY_STEP}
-        style={{ accentColor: 'var(--dt-primary)' }}
-        type="range"
         value={value}
       />
       <span className="w-9 text-right text-[length:var(--conversation-caption-font-size)] tabular-nums text-(--ui-text-tertiary)">
@@ -579,19 +577,27 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
 
           {show('theme') && (
             <ListRow
+              action={
+                <SegmentedControl
+                  onChange={id => {
+                    triggerHaptic('crisp')
+                    setMode(id)
+                  }}
+                  options={modeOptions}
+                  value={mode}
+                />
+              }
               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={a.themeSearchPlaceholder}
-                      spellCheck={false}
-                      value={query}
-                    />
-                  </div>
+                  <SearchField
+                    containerClassName="mt-3 w-full"
+                    inputClassName="flex-1"
+                    onChange={setQuery}
+                    placeholder={a.themeSearchPlaceholder}
+                    value={query}
+                  />
 
                   {/* The dedicated theme page uses the page scroller rather
                       than clipping its gallery inside another scroll area. */}
@@ -662,19 +668,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
               }
               description={a.themeDesc}
               id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.theme)}
-              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>
-              }
+              title={a.themeTitle}
               wide
             />
           )}
@@ -738,6 +732,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                 />
               }
               description={a.sessionDensityDesc}
+              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.sessionDensity)}
               title={a.sessionDensityTitle}
             />
           )}
@@ -755,6 +750,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                 />
               }
               description={a.tabStripDesc}
+              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.tabStrip)}
               title={a.tabStripTitle}
             />
           )}
@@ -906,65 +902,32 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
           )}
 
           {show('window-layout') && (
-            <ListRow
-              action={
-                <SegmentedControl
-                  onChange={id => {
-                    triggerHaptic('selection')
-                    setBackdrop(id === 'on')
-                  }}
-                  options={[
-                    { id: 'off', label: t.common.off },
-                    { id: 'on', label: t.common.on }
-                  ]}
-                  value={backdrop ? 'on' : 'off'}
-                />
-              }
+            <ToggleRow
+              checked={backdrop}
               description={a.backdropDesc}
               id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.backdrop)}
-              title={a.backdropTitle}
+              label={a.backdropTitle}
+              onChange={setBackdrop}
             />
           )}
 
           {show('chat-display') && (
-            <ListRow
-              action={
-                <SegmentedControl
-                  onChange={id => {
-                    triggerHaptic('selection')
-                    setHideThreadTimeline(id === 'on')
-                  }}
-                  options={[
-                    { id: 'off', label: t.common.off },
-                    { id: 'on', label: t.common.on }
-                  ]}
-                  value={hideThreadTimeline ? 'on' : 'off'}
-                />
-              }
+            <ToggleRow
+              checked={hideThreadTimeline}
               description={a.hideThreadTimelineDesc}
               id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.hideThreadTimeline)}
-              title={a.hideThreadTimelineTitle}
+              label={a.hideThreadTimelineTitle}
+              onChange={setHideThreadTimeline}
             />
           )}
 
           {show('general') && (
-            <ListRow
-              action={
-                <SegmentedControl
-                  onChange={id => {
-                    triggerHaptic('selection')
-                    setIntroSplash(id === 'on')
-                  }}
-                  options={[
-                    { id: 'off', label: t.common.off },
-                    { id: 'on', label: t.common.on }
-                  ]}
-                  value={introSplash ? 'on' : 'off'}
-                />
-              }
+            <ToggleRow
+              checked={introSplash}
               description={a.introSplashDesc}
               id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.introSplash)}
-              title={a.introSplashTitle}
+              label={a.introSplashTitle}
+              onChange={setIntroSplash}
             />
           )}
 
@@ -972,6 +935,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
             <ToggleRow
               checked={composerPopoutGesturesEnabled}
               description={a.composerPopoutDesc}
+              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.composerPopout)}
               label={a.composerPopoutTitle}
               onChange={setComposerPopoutGesturesEnabled}
             />
@@ -980,98 +944,47 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
           {show('general') && <ResumeLastSessionSetting />}
 
           {show('chat-display') && (
-            <ListRow
-              action={
-                <SegmentedControl
-                  onChange={id => {
-                    triggerHaptic('selection')
-                    setReactionsEnabled(id === 'on')
-                  }}
-                  options={[
-                    { id: 'off', label: t.common.off },
-                    { id: 'on', label: t.common.on }
-                  ]}
-                  value={reactionsEnabled ? 'on' : 'off'}
-                />
-              }
+            <ToggleRow
+              checked={reactionsEnabled}
               description={a.reactionsDesc}
-              title={a.reactionsTitle}
+              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.reactions)}
+              label={a.reactionsTitle}
+              onChange={setReactionsEnabled}
             />
           )}
 
           {show('general') && (
-            <ListRow
-              action={
-                <div className="flex flex-col items-end gap-1.5">
-                  <SegmentedControl
-                    onChange={id => {
-                      triggerHaptic('selection')
-                      setTipsEnabled(id === 'on')
-                    }}
-                    options={[
-                      { id: 'off', label: t.common.off },
-                      { id: 'on', label: t.common.on }
-                    ]}
-                    value={tipsEnabled ? 'on' : 'off'}
-                  />
-                  {/* A tip shows once (✕ or timer), so this is the only way to a
-                      second lap. It appears once there is something to bring back. */}
-                  {spentTips > 0 && (
-                    <Button
-                      onClick={() => {
-                        triggerHaptic('selection')
-                        resetTips()
-                      }}
-                      size="inline"
-                      variant="text"
-                    >
-                      {a.tipsReset(spentTips)}
-                    </Button>
-                  )}
-                </div>
+            <ToggleRow
+              below={
+                // A tip shows once (✕ or timer), so this is the only way to a
+                // second lap. It appears once there is something to bring back.
+                spentTips > 0 && <RowFootnoteAction onClick={resetTips}>{a.tipsReset(spentTips)}</RowFootnoteAction>
               }
+              checked={tipsEnabled}
               description={a.tipsDesc}
-              title={a.tipsTitle}
+              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.tips)}
+              label={a.tipsTitle}
+              onChange={setTipsEnabled}
             />
           )}
 
           {show('general') && (
-            <ListRow
-              action={
-                <SegmentedControl
-                  onChange={id => {
-                    triggerHaptic('selection')
-                    setToursEnabled(id === 'on')
-                  }}
-                  options={[
-                    { id: 'off', label: t.common.off },
-                    { id: 'on', label: t.common.on }
-                  ]}
-                  value={toursEnabled ? 'on' : 'off'}
-                />
-              }
+            <ToggleRow
+              checked={toursEnabled}
               description={a.toursDesc}
-              title={a.toursTitle}
+              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.tours)}
+              label={a.toursTitle}
+              onChange={setToursEnabled}
             />
           )}
 
           {show('chat-display') && (
-            <ListRow
-              action={
-                <SegmentedControl
-                  onChange={id => {
-                    triggerHaptic('selection')
-                    setVibeHeartsEnabled(id === 'on')
-                  }}
-                  options={[
-                    { id: 'off', label: t.common.off },
-                    { id: 'on', label: t.common.on }
-                  ]}
-                  value={vibeHeartsEnabled ? 'on' : 'off'}
-                />
-              }
+            <ToggleRow
+              checked={vibeHeartsEnabled}
               description={a.vibeHeartsDesc}
-              title={a.vibeHeartsTitle}
+              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.vibeHearts)}
+              label={a.vibeHeartsTitle}
+              onChange={setVibeHeartsEnabled}
             />
           )}
 
@@ -1094,23 +1007,22 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
           )}
 
           {show('chat-display') && (
-            <ListRow
-              action={
-                <SegmentedControl
-                  onChange={id => {
-                    triggerHaptic('selection')
-                    setHideCodeDiffs(id === 'on')
-                  }}
-                  options={[
-                    { id: 'off', label: t.common.off },
-                    { id: 'on', label: t.common.on }
-                  ]}
-                  value={hideCodeDiffs ? 'on' : 'off'}
-                />
-              }
+            <ToggleRow
+              checked={hideCodeDiffs}
               description={withModeNote(a.hideCodeDiffsDesc, hideCodeDiffsShadowed)}
               id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.hideCodeDiffs)}
-              title={a.hideCodeDiffsTitle}
+              label={a.hideCodeDiffsTitle}
+              onChange={setHideCodeDiffs}
+            />
+          )}
+
+          {show('chat-display') && (
+            <ToggleRow
+              checked={reasoningCollapsedByDefault}
+              description={withModeNote(a.reasoningCollapsedDesc, reasoningCollapsedShadowed)}
+              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.reasoningCollapsed)}
+              label={a.reasoningCollapsedTitle}
+              onChange={setReasoningCollapsedByDefault}
             />
           )}
 
@@ -1120,45 +1032,18 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                 <SegmentedControl
                   onChange={id => {
                     triggerHaptic('selection')
-                    setReasoningCollapsedByDefault(id === 'on')
+                    setEmbedMode(id)
                   }}
-                  options={[
-                    { id: 'off', label: t.common.off },
-                    { id: 'on', label: t.common.on }
-                  ]}
-                  value={reasoningCollapsedByDefault ? 'on' : 'off'}
+                  options={embedOptions}
+                  value={embedMode}
                 />
               }
-              description={withModeNote(a.reasoningCollapsedDesc, reasoningCollapsedShadowed)}
-              title={a.reasoningCollapsedTitle}
-            />
-          )}
-
-          {show('chat-display') && (
-            <ListRow
-              action={
-                <div className="flex flex-col items-end gap-1.5">
-                  <SegmentedControl
-                    onChange={id => {
-                      triggerHaptic('selection')
-                      setEmbedMode(id)
-                    }}
-                    options={embedOptions}
-                    value={embedMode}
-                  />
-                  {embedAllowed.length > 0 && (
-                    <Button
-                      onClick={() => {
-                        triggerHaptic('selection')
-                        clearEmbedAllowed()
-                      }}
-                      size="inline"
-                      variant="text"
-                    >
-                      {a.embedsReset(embedAllowed.length)}
-                    </Button>
-                  )}
-                </div>
+              below={
+                embedAllowed.length > 0 && (
+                  <RowFootnoteAction onClick={clearEmbedAllowed}>
+                    {a.embedsReset(embedAllowed.length)}
+                  </RowFootnoteAction>
+                )
               }
               description={a.embedsDesc}
               id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.embeds)}
@@ -1169,7 +1054,10 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
       </div>
 
       {show('pet') && (
-        <div className={subpage === undefined ? 'mt-6' : undefined} id={appearanceSettingElementId('appearance.pet')}>
+        <div
+          className={subpage === undefined ? 'mt-6' : undefined}
+          id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.pet)}
+        >
           <PetSettings />
         </div>
       )}
diff --git a/apps/desktop/src/app/settings/billing/account-row-value.tsx b/apps/desktop/src/app/settings/billing/account-row-value.tsx
index 4c54e4cbac..9ab65424fb 100644
--- a/apps/desktop/src/app/settings/billing/account-row-value.tsx
+++ b/apps/desktop/src/app/settings/billing/account-row-value.tsx
@@ -10,8 +10,9 @@ export function RowValue({ onAction, row }: { onAction?: () => void; row: Billin
   // Destructure to a const so narrowing survives into the onClick closure below.
   const { action } = row
 
+  // Rendered as a ListRow `action`; the row owns wrapping and alignment.
   return (
-    <div className="flex min-w-0 flex-wrap items-center justify-start gap-2 @2xl:justify-end">
+    <>
       {row.value && (
         <span className="min-w-0 truncate text-[length:var(--conversation-text-font-size)] font-medium text-foreground">
           {row.value}
@@ -43,6 +44,6 @@ export function RowValue({ onAction, row }: { onAction?: () => void; row: Billin
           {!action.disabled && action.url && <ExternalLink className="size-3.5" />}
         </Button>
       )}
-    </div>
+    </>
   )
 }
diff --git a/apps/desktop/src/app/settings/billing/auto-reload-row.tsx b/apps/desktop/src/app/settings/billing/auto-reload-row.tsx
index d430945d1a..4b75a4d99f 100644
--- a/apps/desktop/src/app/settings/billing/auto-reload-row.tsx
+++ b/apps/desktop/src/app/settings/billing/auto-reload-row.tsx
@@ -6,7 +6,7 @@ import { Input } from '@/components/ui/input'
 import { useI18n } from '@/i18n'
 import { cn } from '@/lib/utils'
 
-import { ListRow, Pill } from '../primitives'
+import { LIST_ROW_COLUMNS, ListRow, Pill } from '../primitives'
 
 import { RowValue } from './account-row-value'
 import type { BillingRefusal } from './api'
@@ -168,7 +168,7 @@ export function AutoReloadRow({
   // panes. The form is `invisible` + `aria-hidden` when not editing.
   return (
     <div className="@container">
-      <div className="grid gap-3 py-3 @2xl:grid-cols-[minmax(0,1fr)_minmax(15rem,22rem)] @2xl:items-start">
+      <div className={cn('grid gap-3 py-3 @2xl:items-start', LIST_ROW_COLUMNS)}>
         <div className="min-w-0">
           <div className="text-[length:var(--conversation-text-font-size)] font-medium text-foreground">
             {row.title}
diff --git a/apps/desktop/src/app/settings/billing/current-plan-card.tsx b/apps/desktop/src/app/settings/billing/current-plan-card.tsx
index 638aae9748..997adcffe3 100644
--- a/apps/desktop/src/app/settings/billing/current-plan-card.tsx
+++ b/apps/desktop/src/app/settings/billing/current-plan-card.tsx
@@ -1,6 +1,9 @@
 import { Button } from '@/components/ui/button'
 import { useI18n } from '@/i18n'
 import { ExternalLink } from '@/lib/icons'
+import { cn } from '@/lib/utils'
+
+import { LIST_ROW_COLUMNS } from '../primitives'
 
 import { BillingRefusalInline } from './inline-feedback'
 import { openExternal } from './open-external'
@@ -15,7 +18,7 @@ export function CurrentPlanCard({ onViewPlans, plan }: { onViewPlans: () => void
 
   return (
     <div className="@container">
-      <div className="grid gap-3 py-3 @2xl:grid-cols-[minmax(0,1fr)_minmax(15rem,22rem)] @2xl:items-center">
+      <div className={cn('grid gap-3 py-3 @2xl:items-center', LIST_ROW_COLUMNS)}>
         <div className="flex min-w-0 items-center gap-3">
           <TierArt name={plan.tierName} />
           <div className="min-w-0">
diff --git a/apps/desktop/src/app/settings/billing/index.tsx b/apps/desktop/src/app/settings/billing/index.tsx
index c97130dd43..2fe4760f64 100644
--- a/apps/desktop/src/app/settings/billing/index.tsx
+++ b/apps/desktop/src/app/settings/billing/index.tsx
@@ -195,7 +195,7 @@ function BuyCreditsRow({ billing, row }: { billing: BillingStateResponse; row: B
   return (
     <ListRow
       action={
-        <div className="flex min-w-0 flex-wrap items-center justify-start gap-2 @2xl:justify-end">
+        <>
           <SegmentedControl
             disabled={controlsDisabled}
             onChange={value => setAmount(value)}
@@ -224,7 +224,7 @@ function BuyCreditsRow({ billing, row }: { billing: BillingStateResponse; row: B
           <Button disabled={!canBuy} onClick={startBuy} size="xs" type="button" variant="secondary">
             {b.buyCredits.buyButton}
           </Button>
-        </div>
+        </>
       }
       below={
         <BuyCreditsOutcome
diff --git a/apps/desktop/src/app/settings/config-field.tsx b/apps/desktop/src/app/settings/config-field.tsx
index 08126bebf8..6681811706 100644
--- a/apps/desktop/src/app/settings/config-field.tsx
+++ b/apps/desktop/src/app/settings/config-field.tsx
@@ -2,7 +2,6 @@ import type { ReactNode } from 'react'
 
 import { Input } from '@/components/ui/input'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
-import { Switch } from '@/components/ui/switch'
 import { Textarea } from '@/components/ui/textarea'
 import { useI18n } from '@/i18n'
 import { prettyName } from '@/lib/text'
@@ -13,7 +12,7 @@ import { ComboboxInput } from './combobox-input'
 import { CONTROL_TEXT, EMPTY_SELECT_VALUE, FIELD_DESCRIPTIONS, FIELD_LABELS, FREE_INPUT_KEYS } from './constants'
 import { FallbackModelsField } from './fallback-models-field'
 import { fieldCopyForSchemaKey } from './field-copy'
-import { ListRow } from './primitives'
+import { ListRow, ToggleRow } from './primitives'
 import { SearchableSelect } from './searchable-select'
 
 /**
@@ -81,22 +80,40 @@ export function ConfigField({
   // Every config row is addressable by its canonical schema key, so a tour can
   // point at one setting (`[data-tour="field-model"]`) without hunting through
   // the section for an nth-child path. See lib/tour.
-  const row = (action: ReactNode, wide = false) => (
-    <ListRow action={action} data-tour={`field-${schemaKey}`} description={descriptionNode} title={label} wide={wide} />
+  const dataTour = `field-${schemaKey}`
+
+  const row = (action: ReactNode) => (
+    <ListRow action={action} data-tour={dataTour} description={descriptionNode} title={label} />
+  )
+
+  // Editors too big for the control column (textareas, structured lists) take
+  // the full width under the description.
+  const wideRow = (editor: ReactNode) => (
+    <ListRow
+      below={<div className="mt-3">{editor}</div>}
+      data-tour={dataTour}
+      description={descriptionNode}
+      title={label}
+      wide
+    />
   )
 
   // `fallback_providers` is a list of {provider, model} objects; the generic
   // `list` branch below would stringify them to "[object Object]". Render the
   // dedicated structured editor instead.
   if (schemaKey === 'fallback_providers') {
-    return row(<FallbackModelsField onChange={onChange} value={value} />, true)
+    return wideRow(<FallbackModelsField onChange={onChange} value={value} />)
   }
 
   if (schema.type === 'boolean') {
-    return row(
-      <div className="flex items-center justify-end">
-        <Switch checked={Boolean(value)} onCheckedChange={onChange} />
-      </div>
+    return (
+      <ToggleRow
+        checked={Boolean(value)}
+        data-tour={dataTour}
+        description={descriptionNode}
+        label={label}
+        onChange={onChange}
+      />
     )
   }
 
@@ -201,7 +218,7 @@ export function ConfigField({
   }
 
   if (typeof value === 'object' && value !== null) {
-    return row(
+    return wideRow(
       <Textarea
         className={cn('min-h-28 resize-y bg-background font-mono', CONTROL_TEXT)}
         onChange={e => {
@@ -214,29 +231,27 @@ export function ConfigField({
         placeholder={c.notSet}
         spellCheck={false}
         value={JSON.stringify(value, null, 2)}
-      />,
-      true
+      />
     )
   }
 
   const isLong = schema.type === 'text' || String(value ?? '').length > 100
 
-  return row(
-    isLong ? (
-      <Textarea
-        className={cn('min-h-24 resize-y bg-background', CONTROL_TEXT)}
-        onChange={e => onChange(e.target.value)}
-        placeholder={c.notSet}
-        value={String(value ?? '')}
-      />
-    ) : (
-      <Input
-        className={CONTROL_TEXT}
-        onChange={e => onChange(e.target.value)}
-        placeholder={c.notSet}
-        value={String(value ?? '')}
-      />
-    ),
-    isLong
-  )
+  return isLong
+    ? wideRow(
+        <Textarea
+          className={cn('min-h-24 resize-y bg-background', CONTROL_TEXT)}
+          onChange={e => onChange(e.target.value)}
+          placeholder={c.notSet}
+          value={String(value ?? '')}
+        />
+      )
+    : row(
+        <Input
+          className={CONTROL_TEXT}
+          onChange={e => onChange(e.target.value)}
+          placeholder={c.notSet}
+          value={String(value ?? '')}
+        />
+      )
 }
diff --git a/apps/desktop/src/app/settings/credential-key-ui.tsx b/apps/desktop/src/app/settings/credential-key-ui.tsx
index cd22aed474..ff017bde48 100644
--- a/apps/desktop/src/app/settings/credential-key-ui.tsx
+++ b/apps/desktop/src/app/settings/credential-key-ui.tsx
@@ -10,7 +10,7 @@ import type { EnvVarInfo } from '@/types/hermes'
 
 import { CONTROL_TEXT } from './constants'
 import { prettyName, withoutKey } from './helpers'
-import { ListRow } from './primitives'
+import { LIST_ROW_COLUMNS, ListRow } from './primitives'
 import type { EnvRowProps } from './types'
 
 export type KeyRowProps = Omit<EnvRowProps, 'info' | 'varKey'>
@@ -204,7 +204,7 @@ export function CredentialKeyCard({
       {/* One CSS grid: 1 col stacked, 2 cols at @2xl. p-3 card padding = gap-3
           row/col gaps, everything top-left aligned (items-start), no indents.
           The label row is h-8 to line up with the input row beside it. */}
-      <div className="grid grid-cols-1 items-start gap-x-3 gap-y-1.5 @2xl:grid-cols-[minmax(0,1fr)_minmax(15rem,22rem)] @2xl:gap-y-3">
+      <div className={cn('grid grid-cols-1 items-start gap-x-3 gap-y-1.5 @2xl:gap-y-3', LIST_ROW_COLUMNS)}>
         <div className="flex h-8 min-w-0 items-center gap-2">
           <span
             className={cn('size-2 shrink-0 rounded-full', info.is_set ? 'bg-primary' : 'bg-(--ui-stroke-secondary)')}
@@ -290,7 +290,7 @@ export function ProviderKeyRows({ expanded, group, onExpand, onToggle, rowProps
     >
       {/* Same grid as CredentialKeyCard: 1 col stacked, 2 cols at @2xl, p-3 =
           gap-3, items-start, label row h-8 to line up with the input row. */}
-      <div className="grid grid-cols-1 items-start gap-x-3 gap-y-1.5 @2xl:grid-cols-[minmax(0,1fr)_minmax(15rem,22rem)] @2xl:gap-y-3">
+      <div className={cn('grid grid-cols-1 items-start gap-x-3 gap-y-1.5 @2xl:gap-y-3', LIST_ROW_COLUMNS)}>
         <div className="flex h-8 min-w-0 items-center gap-2">
           <span
             className={cn(
diff --git a/apps/desktop/src/app/settings/local-models-settings.tsx b/apps/desktop/src/app/settings/local-models-settings.tsx
index b5ac9ffa00..c68babdb5e 100644
--- a/apps/desktop/src/app/settings/local-models-settings.tsx
+++ b/apps/desktop/src/app/settings/local-models-settings.tsx
@@ -4,6 +4,7 @@ import { useNavigate } from 'react-router'
 
 import { NEW_CHAT_ROUTE } from '@/app/routes'
 import { Button } from '@/components/ui/button'
+import { SearchField } from '@/components/ui/search-field'
 import { Tip } from '@/components/ui/tooltip'
 import {
   activateLocalModel,
@@ -1003,15 +1004,13 @@ function BrowseSection({ onChanged }: { onChanged: () => void }) {
       <div id="local-model-browse">
         <p className="text-[0.75rem] text-muted-foreground">{copy.browseHint}</p>
 
-        <div className="relative">
-          <Search className="pointer-events-none absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
-          <input
-            className="w-full rounded-md border border-(--ui-border) bg-transparent py-1.5 pl-8 pr-3 text-[0.8rem] outline-none placeholder:text-muted-foreground focus:border-primary"
-            onChange={e => setQuery(e.target.value)}
-            placeholder={copy.browsePlaceholder}
-            value={query}
-          />
-        </div>
+        <SearchField
+          containerClassName="w-full"
+          inputClassName="flex-1"
+          onChange={setQuery}
+          placeholder={copy.browsePlaceholder}
+          value={query}
+        />
 
         {searching && (
           <p className="flex items-center gap-2 text-[0.75rem] text-muted-foreground">
diff --git a/apps/desktop/src/app/settings/model-settings.tsx b/apps/desktop/src/app/settings/model-settings.tsx
index d1dc4d4974..c984f0a911 100644
--- a/apps/desktop/src/app/settings/model-settings.tsx
+++ b/apps/desktop/src/app/settings/model-settings.tsx
@@ -43,7 +43,7 @@ import { PanelEmpty } from '../overlays/panel'
 import { CONTROL_TEXT } from './constants'
 import { getNested, setNested } from './helpers'
 import { ModelSelect, withActive } from './model-select'
-import { ListRow, Pill, SectionHeading } from './primitives'
+import { ListRow, ListRowSkeleton, Pill, SectionHeading, SectionHeadingSkeleton } from './primitives'
 import { useDeepLinkHighlight } from './use-deep-link-highlight'
 
 // Skeleton mirror of the Model settings DOM so the page keeps its shape while
@@ -70,22 +70,10 @@ export function ModelSettingsSkeleton({ subpage }: Pick<ModelSettingsProps, 'sub
 
       {(subpage === undefined || subpage === 'auxiliary' || subpage === 'moa') && (
         <section>
-          <div className="mb-2.5 flex items-center gap-2 pt-2">
-            <Skeleton className="size-4" />
-            <Skeleton className="h-4 w-36" />
-          </div>
+          <SectionHeadingSkeleton />
           <div className="grid gap-1">
             {[0, 1, 2, 3].map(row => (
-              <div
-                className="grid gap-3 py-3 @2xl:grid-cols-[minmax(0,1fr)_minmax(15rem,22rem)] @2xl:items-center"
-                key={row}
-              >
-                <div className="min-w-0 space-y-1.5">
-                  <Skeleton className="h-3.5 w-32" />
-                  <Skeleton className="h-3 w-52 max-w-full" />
-                </div>
-                <Skeleton className="h-8 w-full @2xl:justify-self-end @2xl:w-56" />
-              </div>
+              <ListRowSkeleton key={row} />
             ))}
           </div>
         </section>
diff --git a/apps/desktop/src/app/settings/notifications-settings.tsx b/apps/desktop/src/app/settings/notifications-settings.tsx
index 86a24d4e8b..6e6a0fefe3 100644
--- a/apps/desktop/src/app/settings/notifications-settings.tsx
+++ b/apps/desktop/src/app/settings/notifications-settings.tsx
@@ -75,7 +75,7 @@ export function NotificationsSettings({ subpage }: NotificationsSettingsProps =
       {showSounds && (
         <ListRow
           action={
-            <div className="flex flex-wrap items-center justify-end gap-2">
+            <>
               <Select
                 onValueChange={value => {
                   const variantId = Number.parseInt(value, 10)
@@ -112,7 +112,7 @@ export function NotificationsSettings({ subpage }: NotificationsSettingsProps =
                 <Play className="size-3.5" />
                 {copy.completionSoundPreview}
               </Button>
-            </div>
+            </>
           }
           description={copy.completionSoundDesc}
           title={copy.completionSoundTitle}
diff --git a/apps/desktop/src/app/settings/pet-settings.tsx b/apps/desktop/src/app/settings/pet-settings.tsx
index 376af5e89f..dd0615ee12 100644
--- a/apps/desktop/src/app/settings/pet-settings.tsx
+++ b/apps/desktop/src/app/settings/pet-settings.tsx
@@ -7,8 +7,9 @@ import { Button } from '@/components/ui/button'
 import { ConfirmDialog } from '@/components/ui/confirm-dialog'
 import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle } from '@/components/ui/dialog'
 import { Input } from '@/components/ui/input'
-import { SegmentedControl } from '@/components/ui/segmented-control'
+import { SearchField } from '@/components/ui/search-field'
 import { Skeleton } from '@/components/ui/skeleton'
+import { Slider } from '@/components/ui/slider'
 import { Tip } from '@/components/ui/tooltip'
 import { useI18n } from '@/i18n'
 import { triggerHaptic } from '@/lib/haptics'
@@ -38,7 +39,7 @@ import {
 } from '@/store/pet-gallery'
 import { $gatewayState } from '@/store/session'
 
-import { ListRow, SectionHeading } from './primitives'
+import { ListRow, SectionHeading, ToggleRow } from './primitives'
 
 /**
  * Appearance opt-in for the floating petdex mascot. A thin view over the shared
@@ -128,14 +129,14 @@ export function PetSettings() {
       )}
 
       <div className="mt-2">
-        <ListRow
+        <ToggleRow
           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)}
+              <SearchField
+                containerClassName="mt-3 w-full"
+                inputClassName="flex-1"
+                onChange={setQuery}
                 placeholder={copy.searchPlaceholder}
-                spellCheck={false}
                 value={query}
               />
               {/* Fixed-height scroll area so filtering never grows/shrinks the
@@ -253,20 +254,10 @@ export function PetSettings() {
               </p>
             </>
           }
+          checked={enabled}
           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>
-          }
+          label={copy.chooseTitle}
+          onChange={toggle}
           wide
         />
 
@@ -274,9 +265,8 @@ export function PetSettings() {
           <ListRow
             action={
               <div className="flex items-center gap-3">
-                <input
+                <Slider
                   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 => {
@@ -284,8 +274,6 @@ export function PetSettings() {
                     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)">
@@ -299,23 +287,7 @@ export function PetSettings() {
         )}
 
         {enabled && (
-          <ListRow
-            action={
-              <SegmentedControl
-                onChange={id => {
-                  setPetRoam(id === 'on')
-                  triggerHaptic('crisp')
-                }}
-                options={[
-                  { id: 'off', label: copy.off },
-                  { id: 'on', label: copy.on }
-                ]}
-                value={roam ? 'on' : 'off'}
-              />
-            }
-            description={copy.roamDesc}
-            title={copy.roamTitle}
-          />
+          <ToggleRow checked={roam} description={copy.roamDesc} label={copy.roamTitle} onChange={setPetRoam} />
         )}
       </div>
 
diff --git a/apps/desktop/src/app/settings/primitives.tsx b/apps/desktop/src/app/settings/primitives.tsx
index 1bbe1f03af..72edda00a0 100644
--- a/apps/desktop/src/app/settings/primitives.tsx
+++ b/apps/desktop/src/app/settings/primitives.tsx
@@ -140,6 +140,16 @@ export function NavLink({
   )
 }
 
+// The label/control split every settings-style row keys on. Rows that cannot
+// be a ListRow (expandable credential cards, the billing plan card with its
+// tier art) still lay out on these exact columns so their controls line up.
+export const LIST_ROW_COLUMNS = '@2xl:grid-cols-[minmax(0,1fr)_minmax(15rem,22rem)]'
+
+// The one settings row. `action` is the row's control: beside the label on a
+// wide pane, under the description on a narrow one — the row owns that
+// alignment, so callers never wrap a control in `justify-end`/`items-end`.
+// `wide` rows (galleries, editors) keep the control on the title line and give
+// the full width to `below`.
 export function ListRow({
   title,
   description,
@@ -167,14 +177,12 @@ export function ListRow({
     // the row's own pane width, so a narrow detail column (messaging, split
     // views) stacks instead of squishing the label against minmax(15rem,…).
     <div className={cn('@container', className)} data-tour={dataTour} id={id}>
-      <div
-        className={cn(
-          'grid gap-3 py-3',
-          !wide && '@2xl:grid-cols-[minmax(0,1fr)_minmax(15rem,22rem)] @2xl:items-center'
-        )}
-      >
+      <div className={cn('grid gap-3 py-3', !wide && [LIST_ROW_COLUMNS, '@2xl:items-center'])}>
         <div className="min-w-0">
-          <div className="text-[length:var(--conversation-text-font-size)] font-medium text-foreground">{title}</div>
+          <div className="flex items-center justify-between gap-3 text-[length:var(--conversation-text-font-size)] font-medium text-foreground">
+            <span className="min-w-0">{title}</span>
+            {wide && action && <div className="flex shrink-0 items-center gap-2">{action}</div>}
+          </div>
           {description && (
             <div className="mt-1 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
               {description}
@@ -183,25 +191,40 @@ export function ListRow({
           {hint && <div className="mt-1 block font-mono text-[0.68rem] text-muted-foreground/45">{hint}</div>}
           {below}
         </div>
-        {action && <div className={cn('min-w-0', !wide && '@2xl:justify-self-end')}>{action}</div>}
+        {!wide && action && (
+          <div className="flex min-w-0 flex-wrap items-center gap-2 @2xl:justify-self-end @2xl:justify-end">
+            {action}
+          </div>
+        )}
       </div>
     </div>
   )
 }
 
-// A labelled on/off row — the canonical device-pref switch (haptic baked in).
+// The one boolean row: every on/off setting is a Switch in a ListRow (haptic
+// baked in). Never a two-option SegmentedControl — that is for choices.
 export function ToggleRow({
   checked,
+  below,
+  'data-tour': dataTour,
   description,
   disabled,
+  hint,
+  id,
   label,
-  onChange
+  onChange,
+  wide
 }: {
   checked: boolean
-  description?: string
+  below?: ReactNode
+  'data-tour'?: string
+  description?: ReactNode
   disabled?: boolean
+  hint?: ReactNode
+  id?: string
   label: string
   onChange: (on: boolean) => void
+  wide?: boolean
 }) {
   return (
     <ListRow
@@ -216,12 +239,37 @@ export function ToggleRow({
           }}
         />
       }
+      below={below}
+      data-tour={dataTour}
       description={description}
+      hint={hint}
+      id={id}
       title={label}
+      wide={wide}
     />
   )
 }
 
+// A quiet follow-up under a row's description ("Show 9 tips again", "Reset")
+// — the one place a row's secondary action lives, so it never floats beside
+// or under the control.
+export function RowFootnoteAction({ children, onClick }: { children: ReactNode; onClick: () => void }) {
+  return (
+    <div className="mt-1.5">
+      <Button
+        onClick={() => {
+          triggerHaptic('selection')
+          onClick()
+        }}
+        size="inline"
+        variant="text"
+      >
+        {children}
+      </Button>
+    </div>
+  )
+}
+
 // Skeleton primitives mirroring the settings layout rhythm — a loading page keeps
 // its shape (like ModelSettings) instead of collapsing to a centered spinner.
 export function SectionHeadingSkeleton() {
@@ -236,12 +284,7 @@ export function SectionHeadingSkeleton() {
 export function ListRowSkeleton({ wide = false }: { wide?: boolean }) {
   return (
     <div className="@container">
-      <div
-        className={cn(
-          'grid gap-3 py-3',
-          !wide && '@2xl:grid-cols-[minmax(0,1fr)_minmax(15rem,22rem)] @2xl:items-center'
-        )}
-      >
+      <div className={cn('grid gap-3 py-3', !wide && [LIST_ROW_COLUMNS, '@2xl:items-center'])}>
         <div className="min-w-0 space-y-1.5">
           <Skeleton className="h-3.5 w-40 max-w-full" />
           <Skeleton className="h-3 w-64 max-w-full" />
diff --git a/apps/desktop/src/components/ui/slider.tsx b/apps/desktop/src/components/ui/slider.tsx
new file mode 100644
index 0000000000..4fc313ec74
--- /dev/null
+++ b/apps/desktop/src/components/ui/slider.tsx
@@ -0,0 +1,18 @@
+import type { ComponentProps } from 'react'
+
+import { cn } from '@/lib/utils'
+
+// The one range control: a hairline track in the app's stroke tint with the
+// native thumb in the primary accent. Settings rows compose it beside a
+// readout or inside a labelled group; nothing hand-rolls `type="range"`.
+export function Slider({ className, style, ...props }: Omit<ComponentProps<'input'>, 'type'>) {
+  return (
+    <input
+      className={cn('h-1 w-40 cursor-pointer appearance-none rounded-full bg-(--ui-stroke-tertiary)', className)}
+      data-slot="slider"
+      style={{ accentColor: 'var(--dt-primary)', ...style }}
+      type="range"
+      {...props}
+    />
+  )
+}
diff --git a/apps/desktop/src/i18n/ar.ts b/apps/desktop/src/i18n/ar.ts
index fb1b022ab7..ba97c4976f 100644
--- a/apps/desktop/src/i18n/ar.ts
+++ b/apps/desktop/src/i18n/ar.ts
@@ -692,8 +692,6 @@ export const ar = defineLocale({
           'تبنَّ تعويذة petdex متحركة تطفو فوق التطبيق وتتفاعل مع ما يفعله Hermes — تجري أثناء تنفيذ الأدوات، وتحتفل عند النجاح، وتعبس عند الأخطاء.',
         restartHint:
           'تحتاج الحيوانات الأليفة إلى إعادة تشغيل سريعة — بدأ التطبيق العامل قبل إضافة هذه الميزة. أغلق Hermes وأعد فتحه، ثم ارجع إلى هنا.',
-        on: 'تشغيل',
-        off: 'إيقاف',
         scaleTitle: 'الحجم',
         scaleDesc: 'غيّر حجم التعويذة الطافية. يُطبّق في كل مكان فورا.',
         chooseTitle: 'اختر حيوانا أليفا',
diff --git a/apps/desktop/src/i18n/de.ts b/apps/desktop/src/i18n/de.ts
index 537a81dee4..90bb35927e 100644
--- a/apps/desktop/src/i18n/de.ts
+++ b/apps/desktop/src/i18n/de.ts
@@ -1206,8 +1206,6 @@ export const de = defineLocale({
           'Adoptieren Sie ein animiertes Petdex-Maskottchen, das über der App schwebt und darauf reagiert, was Hermes gerade tut – es rennt, während Tools laufen, feiert bei Erfolg und schmollt bei Fehlern.',
         restartHint:
           'Haustiere erfordern einen kurzen Neustart – die laufende App wurde gestartet, bevor diese Funktion hinzugefügt wurde. Schließen Sie Hermes, öffnen Sie es erneut und kehren Sie dann hierher zurück.',
-        on: 'An',
-        off: 'Aus',
         scaleTitle: 'Größe',
         scaleDesc: 'Ändert die Größe des schwebenden Maskottchens. Wirkt überall sofort.',
         roamTitle: 'Herumstreifen',
diff --git a/apps/desktop/src/i18n/en.ts b/apps/desktop/src/i18n/en.ts
index 4a0b524887..f3b10134d2 100644
--- a/apps/desktop/src/i18n/en.ts
+++ b/apps/desktop/src/i18n/en.ts
@@ -1153,8 +1153,6 @@ export const en: Translations = {
           '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.',
         roamTitle: 'Roam',
diff --git a/apps/desktop/src/i18n/es.ts b/apps/desktop/src/i18n/es.ts
index 29c8c17bf6..6ba0efbcfe 100644
--- a/apps/desktop/src/i18n/es.ts
+++ b/apps/desktop/src/i18n/es.ts
@@ -1204,8 +1204,6 @@ export const es = defineLocale({
           'Adopta una mascota animada de petdex que flota sobre la app y reacciona a lo que hace Hermes: corre mientras se ejecutan herramientas, celebra los éxitos y se entristece con los errores.',
         restartHint:
           'Las mascotas necesitan un reinicio rápido: la aplicación en ejecución se inició antes de que se añadiera esta función. Cierra y vuelve a abrir Hermes y luego vuelve aquí.',
-        on: 'Activada',
-        off: 'Desactivada',
         scaleTitle: 'Tamaño',
         scaleDesc: 'Cambia el tamaño de la mascota flotante. Se aplica al instante en todas partes.',
         roamTitle: 'Moverse libremente',
diff --git a/apps/desktop/src/i18n/fr.ts b/apps/desktop/src/i18n/fr.ts
index 9304114b88..c98390403b 100644
--- a/apps/desktop/src/i18n/fr.ts
+++ b/apps/desktop/src/i18n/fr.ts
@@ -1208,8 +1208,6 @@ export const fr = defineLocale({
           "Adoptez une mascotte petdex animée qui flotte au-dessus de l'application et réagit aux actions de Hermes — court pendant l'exécution des outils, fête les réussites, boude les erreurs.",
         restartHint:
           "Les animaux de compagnie nécessitent un redémarrage rapide — l'application en cours a démarré avant l'ajout de cette fonctionnalité. Fermez et rouvrez Hermes, puis revenez ici.",
-        on: 'Activé',
-        off: 'Désactivé',
         scaleTitle: 'Taille',
         scaleDesc: "Redimensionnez la mascotte flottante. S'applique partout instantanément.",
         roamTitle: 'Errer',
diff --git a/apps/desktop/src/i18n/ja.ts b/apps/desktop/src/i18n/ja.ts
index 43fe2f8096..c8473aad89 100644
--- a/apps/desktop/src/i18n/ja.ts
+++ b/apps/desktop/src/i18n/ja.ts
@@ -702,8 +702,6 @@ export const ja = defineLocale({
         scaleDesc: '浮遊マスコットの大きさを変更します。すべての画面に即時反映されます。',
         roamTitle: '散歩',
         roamDesc: 'アイドル中にペットがウィンドウ内を自由に歩き回ります。',
-        on: 'オン',
-        off: 'オフ',
         chooseTitle: 'ペットを選ぶ',
         chooseDesc: '選ぶと（必要に応じて）インストールされ、アクティブになります。',
         searchPlaceholder: 'ペットを検索…',
diff --git a/apps/desktop/src/i18n/ru.ts b/apps/desktop/src/i18n/ru.ts
index 1d02c77451..a51e5925af 100644
--- a/apps/desktop/src/i18n/ru.ts
+++ b/apps/desktop/src/i18n/ru.ts
@@ -724,8 +724,6 @@ export const ru = defineLocale({
           'Заберите анимированного питомца из petdex, который парит над приложением и реагирует на действия Hermes — «бегает», пока выполняются инструменты, радуется успеху и хмурится при ошибках.',
         restartHint:
           'Питомцам нужен быстрый перезапуск — текущее приложение запустилось до появления этой функции. Выйдите из Hermes и откройте снова, затем вернитесь сюда.',
-        on: 'Вкл',
-        off: 'Выкл',
         scaleTitle: 'Размер',
         scaleDesc: 'Меняет размер парящего питомца. Применяется мгновенно везде.',
         roamTitle: 'Блуждание',
diff --git a/apps/desktop/src/i18n/types.ts b/apps/desktop/src/i18n/types.ts
index 3ba6192076..6232a0187e 100644
--- a/apps/desktop/src/i18n/types.ts
+++ b/apps/desktop/src/i18n/types.ts
@@ -952,8 +952,6 @@ export interface Translations {
         title: string
         intro: string
         restartHint: string
-        on: string
-        off: string
         scaleTitle: string
         scaleDesc: string
         roamTitle: string
diff --git a/apps/desktop/src/i18n/zh-hant.ts b/apps/desktop/src/i18n/zh-hant.ts
index 3e0194cf50..bd728a4162 100644
--- a/apps/desktop/src/i18n/zh-hant.ts
+++ b/apps/desktop/src/i18n/zh-hant.ts
@@ -643,8 +643,6 @@ export const zhHant = defineLocale({
         scaleDesc: '調整懸浮寵物的大小，所有介面即時生效。',
         roamTitle: '漫遊',
         roamDesc: '閒置時讓寵物自己在視窗內四處走動。',
-        on: '開啟',
-        off: '關閉',
         chooseTitle: '選擇寵物',
         chooseDesc: '選擇後會自動安裝（如需）並設為目前寵物。',
         searchPlaceholder: '搜尋寵物…',
diff --git a/apps/desktop/src/i18n/zh.ts b/apps/desktop/src/i18n/zh.ts
index 41eb6100dc..163b2aae55 100644
--- a/apps/desktop/src/i18n/zh.ts
+++ b/apps/desktop/src/i18n/zh.ts
@@ -853,8 +853,6 @@ export const zh = defineLocale({
         scaleDesc: '调整悬浮宠物的大小，所有界面即时生效。',
         roamTitle: '漫游',
         roamDesc: '空闲时让宠物自己在窗口内四处走动。',
-        on: '开启',
-        off: '关闭',
         chooseTitle: '选择宠物',
         chooseDesc: '选择后会自动安装（如需）并设为当前宠物。',
         searchPlaceholder: '搜索宠物…',

From 7d63f57c7d29f6058713c350fb65ddfacd3f75fd Mon Sep 17 00:00:00 2001
From: brooklyn! <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 23 Sep 2026 21:50:05 -0500
Subject: [PATCH 11/61] feat(sdk): export ListRow/ToggleRow so plugin panes lay
 out like core Settings

The Bots group dialog hand-rolled a label + hint + Switch row; it now uses
the same ToggleRow, and the SDK surfaces the two row primitives next to
ToolsetConfigPanel.
---
 .../hermes-bots/group-chat-timeline.test.tsx      |  2 +-
 .../group-chat-view.inline-code.test.tsx          |  2 +-
 .../hermes-bots/group-chat-view.render.test.tsx   |  2 +-
 .../src/plugins/hermes-bots/group-chat-view.tsx   | 15 +++++++--------
 .../plugins/hermes-bots/group-compress.test.tsx   |  2 +-
 .../hermes-bots/group-hold-status.test.tsx        |  2 +-
 apps/desktop/src/sdk/index.ts                     |  5 +++++
 7 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/apps/desktop/src/plugins/hermes-bots/group-chat-timeline.test.tsx b/apps/desktop/src/plugins/hermes-bots/group-chat-timeline.test.tsx
index 7ba9495dfb..3c61896ef8 100644
--- a/apps/desktop/src/plugins/hermes-bots/group-chat-timeline.test.tsx
+++ b/apps/desktop/src/plugins/hermes-bots/group-chat-timeline.test.tsx
@@ -21,7 +21,7 @@ vi.mock('@hermes/plugin-sdk', async () => {
     cn: (...values: unknown[]) => values.filter(Boolean).join(' '),
     Codicon: () => null,
     CopyButton: () => null,
-    Switch: () => null,
+    ToggleRow: () => null,
     ConfirmDialog: () => null,
     Dialog: () => null,
     DialogContent: () => null,
diff --git a/apps/desktop/src/plugins/hermes-bots/group-chat-view.inline-code.test.tsx b/apps/desktop/src/plugins/hermes-bots/group-chat-view.inline-code.test.tsx
index 6e58b8e197..06cdc814b1 100644
--- a/apps/desktop/src/plugins/hermes-bots/group-chat-view.inline-code.test.tsx
+++ b/apps/desktop/src/plugins/hermes-bots/group-chat-view.inline-code.test.tsx
@@ -31,7 +31,7 @@ vi.mock('@hermes/plugin-sdk', async () => {
     cn: (...values: unknown[]) => values.filter(Boolean).join(' '),
     Codicon: () => null,
     CopyButton: () => null,
-    Switch: () => null,
+    ToggleRow: () => null,
     ConfirmDialog: () => null,
     Dialog: () => null,
     DialogContent: () => null,
diff --git a/apps/desktop/src/plugins/hermes-bots/group-chat-view.render.test.tsx b/apps/desktop/src/plugins/hermes-bots/group-chat-view.render.test.tsx
index 43f7ff341f..4cd5a670b9 100644
--- a/apps/desktop/src/plugins/hermes-bots/group-chat-view.render.test.tsx
+++ b/apps/desktop/src/plugins/hermes-bots/group-chat-view.render.test.tsx
@@ -37,7 +37,7 @@ vi.mock('@hermes/plugin-sdk', async () => {
         {text}
       </span>
     ),
-    Switch: () => null,
+    ToggleRow: () => null,
     Tip: ({ children }: { children: ReactNode }) => children,
     relativeTime: () => 'now',
     useI18n: () => ({ t: { common: { cancel: 'Cancel', save: 'Save' } } }),
diff --git a/apps/desktop/src/plugins/hermes-bots/group-chat-view.tsx b/apps/desktop/src/plugins/hermes-bots/group-chat-view.tsx
index 55c5d680a7..e417eef23f 100644
--- a/apps/desktop/src/plugins/hermes-bots/group-chat-view.tsx
+++ b/apps/desktop/src/plugins/hermes-bots/group-chat-view.tsx
@@ -29,8 +29,8 @@ import {
   queryClient,
   relativeTime,
   RowButton,
-  Switch,
   Tip,
+  ToggleRow,
   useI18n,
   useValue
 } from '@hermes/plugin-sdk'
@@ -496,13 +496,12 @@ function GroupChatSettingsDialog({
             value={name}
           />
         </form>
-        <label className="flex items-center justify-between gap-3 text-sm">
-          <span>
-            <span className="block">{b.group.holdDetection}</span>
-            <span className="block text-xs text-(--ui-text-tertiary)">{b.group.holdDetectionHint}</span>
-          </span>
-          <Switch checked={holdDetection} onCheckedChange={setHoldDetection} />
-        </label>
+        <ToggleRow
+          checked={holdDetection}
+          description={b.group.holdDetectionHint}
+          label={b.group.holdDetection}
+          onChange={setHoldDetection}
+        />
         {(members || []).length > 0 ? (
           <ul className="flex flex-col gap-1" data-testid="group-settings-members">
             {(members || []).map(member => {
diff --git a/apps/desktop/src/plugins/hermes-bots/group-compress.test.tsx b/apps/desktop/src/plugins/hermes-bots/group-compress.test.tsx
index 66cbfe79b4..d01f87783d 100644
--- a/apps/desktop/src/plugins/hermes-bots/group-compress.test.tsx
+++ b/apps/desktop/src/plugins/hermes-bots/group-compress.test.tsx
@@ -42,7 +42,7 @@ vi.mock('@hermes/plugin-sdk', async () => {
     cn: (...values: unknown[]) => values.filter(Boolean).join(' '),
     Codicon: () => null,
     CopyButton: () => null,
-    Switch: () => null,
+    ToggleRow: () => null,
     ConfirmDialog: () => null,
     Dialog: Passthrough,
     DialogContent: Passthrough,
diff --git a/apps/desktop/src/plugins/hermes-bots/group-hold-status.test.tsx b/apps/desktop/src/plugins/hermes-bots/group-hold-status.test.tsx
index e8f119d293..789af11948 100644
--- a/apps/desktop/src/plugins/hermes-bots/group-hold-status.test.tsx
+++ b/apps/desktop/src/plugins/hermes-bots/group-hold-status.test.tsx
@@ -17,7 +17,7 @@ vi.mock('@hermes/plugin-sdk', async () => {
     Codicon: ({ name }: { name: string }) => <span aria-hidden data-icon={name} />,
     ConfirmDialog: () => null,
     CopyButton: () => null,
-    Switch: () => null,
+    ToggleRow: () => null,
     Dialog: () => null,
     DialogContent: ({ children }: { children?: React.ReactNode }) => <>{children}</>,
     DialogDescription: ({ children }: { children?: React.ReactNode }) => <>{children}</>,
diff --git a/apps/desktop/src/sdk/index.ts b/apps/desktop/src/sdk/index.ts
index d6f4b95e3d..546ebf999a 100644
--- a/apps/desktop/src/sdk/index.ts
+++ b/apps/desktop/src/sdk/index.ts
@@ -1648,6 +1648,11 @@ export {
   WORKSPACE_PAGE_HEADER_AREA
 } from '@/app/routes'
 
+/** THE settings rows: `ListRow` is label + description with the control beside
+ *  it (wide) or under it (narrow); `ToggleRow` is the one on/off row — a Switch,
+ *  never an Off/On pill pair. Use them for preference rows in plugin panes and
+ *  dialogs so they line up with core Settings. */
+export { ListRow, ToggleRow } from '@/app/settings/primitives'
 /** THE full per-toolset config panel core Settings renders — provider picker,
  *  env vars / API keys, model catalog picker, and post-setup runners. Route-
  *  decoupled (the "manage keys" deep link is a no-op outside the router); pass

From 0fb230b82e621848c7a00408efe5d9d72e9956a9 Mon Sep 17 00:00:00 2001
From: brooklyn! <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 23 Sep 2026 21:50:05 -0500
Subject: [PATCH 12/61] fix(desktop): every Appearance row is a command-palette
 hit

The palette's Appearance entries were a hand-maintained list that had fallen
nine rows behind the page (In-App Tips, Guided Tours, Reopen Last Chat,
Session List Density, Tab Strip, Floating Composer, Message Reactions, Vibe
Hearts, Collapse thinking). One manifest now owns each row's id, subpage, copy
and keywords; the page, the router and the search catalog all derive from it,
a test pins the contract, and a subpage named after its single setting no
longer shows up twice.
---
 .../src/app/settings/appearance-subpages.ts   | 188 +++++++++++++++--
 .../src/app/settings/settings-search.ts       |  18 --
 .../desktop/src/app/settings/subpages.test.ts |  35 ++++
 .../src/app/settings/use-settings-search.ts   | 191 +++---------------
 4 files changed, 232 insertions(+), 200 deletions(-)

diff --git a/apps/desktop/src/app/settings/appearance-subpages.ts b/apps/desktop/src/app/settings/appearance-subpages.ts
index ca1c67a484..390f41bd75 100644
--- a/apps/desktop/src/app/settings/appearance-subpages.ts
+++ b/apps/desktop/src/app/settings/appearance-subpages.ts
@@ -1,3 +1,6 @@
+import type { Translations } from '@/i18n'
+import { TRANSLUCENCY_SUPPORTED } from '@/store/translucency'
+
 export const APPEARANCE_SUBPAGES = [
   { id: 'general', labelKey: 'appearanceGeneral' },
   { id: 'theme', labelKey: 'appearanceTheme' },
@@ -9,28 +12,177 @@ export const APPEARANCE_SUBPAGES = [
 
 export type AppearanceSubpageId = (typeof APPEARANCE_SUBPAGES)[number]['id']
 
-// Keep routing metadata independent of settings-search, which consumes it.
+interface AppearanceSettingCopy {
+  description?: string
+  label: string
+}
+
+interface AppearanceSetting {
+  /** Rows that only exist on some platforms stay out of search, where a hit would scroll to nothing. */
+  available?: () => boolean
+  copy: (t: Translations) => AppearanceSettingCopy
+  keywords: readonly string[]
+  subpage: AppearanceSubpageId
+}
+
+type AppearanceCopy = Translations['settings']['appearance']
+type TitledKey = { [K in keyof AppearanceCopy]: K extends `${infer Base}Title` ? Base : never }[keyof AppearanceCopy]
+
+// Most rows read `<key>Title` / `<key>Desc` straight from the appearance
+// catalog; a Desc that is a formatter (uiScale) is left to the row itself.
+const appearanceCopy =
+  <K extends TitledKey>(key: K) =>
+  (t: Translations): AppearanceSettingCopy => {
+    const catalog: Record<string, unknown> = t.settings.appearance
+    const description = catalog[`${key}Desc`]
+
+    return {
+      label: t.settings.appearance[`${key}Title`],
+      description: typeof description === 'string' ? description : undefined
+    }
+  }
+
+/**
+ * The manifest of every hand-built Appearance row. A key becomes the row's
+ * deep-link id (`appearance.<kebab-case>`), its subpage routes that id, and its
+ * copy + keywords feed the command palette — so a row cannot exist without
+ * being searchable, and search cannot point at a row that is not there.
+ * Schema-driven rows (`desktop.font_family`) are indexed from the schema and
+ * only need a subpage here.
+ */
+export const APPEARANCE_SETTINGS = {
+  language: {
+    subpage: 'general',
+    keywords: ['locale'],
+    copy: t => ({ label: t.language.label, description: t.language.description })
+  },
+  introSplash: {
+    subpage: 'general',
+    keywords: ['splash', 'wordmark', 'empty chat', 'new chat'],
+    copy: appearanceCopy('introSplash')
+  },
+  resumeLastSession: {
+    subpage: 'general',
+    keywords: ['resume', 'reopen', 'launch', 'startup', 'last chat', 'session'],
+    copy: appearanceCopy('resumeLastSession')
+  },
+  tips: {
+    subpage: 'general',
+    keywords: ['tips', 'hints', 'coach marks', 'onboarding', 'help'],
+    copy: appearanceCopy('tips')
+  },
+  tours: {
+    subpage: 'general',
+    keywords: ['tour', 'walkthrough', 'guide', 'onboarding', 'help'],
+    copy: appearanceCopy('tours')
+  },
+  theme: { subpage: 'theme', keywords: ['color mode', 'skin', 'light', 'dark'], copy: appearanceCopy('theme') },
+  uiScale: { subpage: 'typography', keywords: ['zoom', 'size'], copy: appearanceCopy('uiScale') },
+  interfaceMode: {
+    subpage: 'window-layout',
+    keywords: ['simple', 'advanced', 'mode', 'interface', 'chrome', 'minimal', 'focus'],
+    copy: t => ({ label: t.interfaceMode.title, description: t.interfaceMode.hint })
+  },
+  sessionDensity: {
+    subpage: 'window-layout',
+    keywords: ['sidebar', 'sessions', 'compact', 'comfortable', 'density'],
+    copy: appearanceCopy('sessionDensity')
+  },
+  tabStrip: { subpage: 'window-layout', keywords: ['tabs', 'tab bar', 'strip'], copy: appearanceCopy('tabStrip') },
+  appActions: {
+    subpage: 'window-layout',
+    keywords: ['titlebar', 'settings gear', 'layout', 'HUD', 'left', 'right', 'tabs'],
+    copy: appearanceCopy('appActions')
+  },
+  minimizeToTray: {
+    subpage: 'window-layout',
+    keywords: ['tray', 'background', 'minimize', 'dock', 'taskbar', 'menu bar'],
+    available: () => Boolean(window.hermesDesktop?.minimizeToTray),
+    copy: t => ({ label: t.settings.config.minimizeToTrayTitle, description: t.settings.config.minimizeToTrayDesc })
+  },
+  translucency: {
+    subpage: 'window-layout',
+    keywords: ['opacity', 'transparent', 'glass', 'blur'],
+    available: () => TRANSLUCENCY_SUPPORTED,
+    copy: appearanceCopy('translucency')
+  },
+  backdrop: { subpage: 'window-layout', keywords: ['background', 'blur'], copy: appearanceCopy('backdrop') },
+  composerPopout: {
+    subpage: 'window-layout',
+    keywords: ['composer', 'floating', 'drag', 'popout', 'dock', 'input'],
+    copy: appearanceCopy('composerPopout')
+  },
+  userBubble: {
+    subpage: 'chat-display',
+    keywords: ['opacity', 'transparent', 'message', 'bubble'],
+    copy: appearanceCopy('userBubble')
+  },
+  textDirection: {
+    subpage: 'chat-display',
+    keywords: ['rtl', 'ltr', 'right to left', 'left to right', 'bidi', 'arabic', 'hebrew', 'persian', 'align'],
+    copy: appearanceCopy('textDirection')
+  },
+  hideThreadTimeline: {
+    subpage: 'chat-display',
+    keywords: ['thread', 'conversation', 'timeline', 'bars', 'rail', 'navigation', 'hide'],
+    copy: appearanceCopy('hideThreadTimeline')
+  },
+  reactions: {
+    subpage: 'chat-display',
+    keywords: ['emoji', 'tapback', 'react', 'reactions'],
+    copy: appearanceCopy('reactions')
+  },
+  vibeHearts: {
+    subpage: 'chat-display',
+    keywords: ['hearts', 'vibe', 'celebrate', 'confetti', 'fun'],
+    copy: appearanceCopy('vibeHearts')
+  },
+  toolView: { subpage: 'chat-display', keywords: ['tool display', 'technical'], copy: appearanceCopy('toolView') },
+  hideCodeDiffs: {
+    subpage: 'chat-display',
+    keywords: ['code', 'diff', 'patch', 'file edits', 'inline', 'added', 'removed'],
+    copy: appearanceCopy('hideCodeDiffs')
+  },
+  reasoningCollapsed: {
+    subpage: 'chat-display',
+    keywords: ['thinking', 'reasoning', 'collapse', 'expand', 'chain of thought'],
+    copy: appearanceCopy('reasoningCollapsed')
+  },
+  embeds: { subpage: 'chat-display', keywords: ['external content', 'privacy'], copy: appearanceCopy('embeds') },
+  pet: {
+    subpage: 'pet',
+    keywords: ['pet', 'mascot', 'petdex', 'companion', 'buddy'],
+    copy: t => ({ label: t.settings.appearance.pet.chooseTitle, description: t.settings.appearance.pet.chooseDesc })
+  }
+} as const satisfies Record<string, AppearanceSetting>
+
+export type AppearanceSettingKey = keyof typeof APPEARANCE_SETTINGS
+
+const APPEARANCE_SETTING_KEYS = Object.keys(APPEARANCE_SETTINGS) as AppearanceSettingKey[]
+const appearanceSetting = (key: AppearanceSettingKey): AppearanceSetting => APPEARANCE_SETTINGS[key]
+
+const kebab = (key: string) => key.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)
+
+export const APPEARANCE_SETTING_IDS = Object.fromEntries(
+  APPEARANCE_SETTING_KEYS.map(key => [key, `appearance.${kebab(key)}`])
+) as Readonly<Record<AppearanceSettingKey, string>>
+
 const SETTING_SUBPAGES: Readonly<Record<string, AppearanceSubpageId>> = {
-  'appearance.app-actions': 'window-layout',
-  'appearance.backdrop': 'window-layout',
-  'appearance.embeds': 'chat-display',
-  'appearance.hide-code-diffs': 'chat-display',
-  'appearance.hide-thread-timeline': 'chat-display',
-  'appearance.intro-splash': 'general',
-  'appearance.language': 'general',
-  'appearance.minimize-to-tray': 'window-layout',
-  'appearance.pet': 'pet',
-  'appearance.text-direction': 'chat-display',
-  'appearance.theme': 'theme',
-  'appearance.tool-view': 'chat-display',
-  'appearance.interface-mode': 'window-layout',
-  'appearance.translucency': 'window-layout',
-  'appearance.ui-scale': 'typography',
-  'appearance.user-bubble': 'chat-display',
+  // Schema-driven rows that render on an Appearance subpage.
   'desktop.font_family': 'typography',
-  'terminal.font_family': 'typography'
+  'terminal.font_family': 'typography',
+  ...Object.fromEntries(
+    APPEARANCE_SETTING_KEYS.map(key => [APPEARANCE_SETTING_IDS[key], appearanceSetting(key).subpage])
+  )
 }
 
 export function appearanceSubpageForSetting(setting: string): AppearanceSubpageId | undefined {
   return Object.hasOwn(SETTING_SUBPAGES, setting) ? SETTING_SUBPAGES[setting] : undefined
 }
+
+/** The Appearance rows the command palette can land on right now, with their copy resolved. */
+export function appearanceSearchTargets(t: Translations) {
+  return APPEARANCE_SETTING_KEYS.map(key => [key, appearanceSetting(key)] as const)
+    .filter(([, setting]) => setting.available?.() ?? true)
+    .map(([key, setting]) => ({ id: APPEARANCE_SETTING_IDS[key], keywords: [...setting.keywords], ...setting.copy(t) }))
+}
diff --git a/apps/desktop/src/app/settings/settings-search.ts b/apps/desktop/src/app/settings/settings-search.ts
index 3e768e1b20..a04863e2da 100644
--- a/apps/desktop/src/app/settings/settings-search.ts
+++ b/apps/desktop/src/app/settings/settings-search.ts
@@ -11,24 +11,6 @@ import type { DesktopConfigSection, SettingsView } from './types'
 
 export type CredentialSettingsView = 'settings' | 'tools'
 
-export const APPEARANCE_SETTING_IDS = {
-  appActions: 'appearance.app-actions',
-  backdrop: 'appearance.backdrop',
-  embeds: 'appearance.embeds',
-  hideCodeDiffs: 'appearance.hide-code-diffs',
-  hideThreadTimeline: 'appearance.hide-thread-timeline',
-  introSplash: 'appearance.intro-splash',
-  language: 'appearance.language',
-  minimizeToTray: 'appearance.minimize-to-tray',
-  textDirection: 'appearance.text-direction',
-  theme: 'appearance.theme',
-  toolView: 'appearance.tool-view',
-  interfaceMode: 'appearance.interface-mode',
-  translucency: 'appearance.translucency',
-  uiScale: 'appearance.ui-scale',
-  userBubble: 'appearance.user-bubble'
-} as const
-
 export interface SettingsSearchTarget {
   subpage?: string
   field?: string
diff --git a/apps/desktop/src/app/settings/subpages.test.ts b/apps/desktop/src/app/settings/subpages.test.ts
index b176bc2c16..3307da34ce 100644
--- a/apps/desktop/src/app/settings/subpages.test.ts
+++ b/apps/desktop/src/app/settings/subpages.test.ts
@@ -2,6 +2,13 @@ import { describe, expect, it } from 'vitest'
 
 import { TRANSLATIONS } from '@/i18n'
 
+import {
+  APPEARANCE_SETTING_IDS,
+  APPEARANCE_SETTINGS,
+  APPEARANCE_SUBPAGES,
+  appearanceSearchTargets,
+  appearanceSubpageForSetting
+} from './appearance-subpages'
 import { CONFIG_SUBPAGES, configSubpageForField } from './config-subpages'
 import { SECTIONS } from './constants'
 import { OTHER_SUBPAGES } from './other-subpages'
@@ -63,4 +70,32 @@ describe('settings subpage routing', () => {
       expect(resolveSettingsSubpage(view, new URLSearchParams(search))).toBe(expected)
     }
   })
+
+  it('makes every Appearance row a routed, translated palette hit', () => {
+    const subpages = APPEARANCE_SUBPAGES.map(page => page.id)
+
+    for (const [key, setting] of Object.entries(APPEARANCE_SETTINGS)) {
+      const id = APPEARANCE_SETTING_IDS[key as keyof typeof APPEARANCE_SETTING_IDS]
+      expect(id).toMatch(/^appearance\.[a-z-]+$/)
+      expect(subpages).toContain(setting.subpage)
+      expect(appearanceSubpageForSetting(id)).toBe(setting.subpage)
+      expect(
+        resolveSettingsSubpage(
+          'config:appearance',
+          new URLSearchParams(settingsSearchTargetQuery({ view: 'config:appearance', setting: id }))
+        )
+      ).toBe(setting.subpage)
+      expect(setting.keywords.length).toBeGreaterThan(0)
+
+      for (const locale of Object.values(TRANSLATIONS)) {
+        expect(setting.copy(locale).label).toBeTruthy()
+      }
+    }
+
+    // Platform-gated rows aside, the whole manifest reaches the palette.
+    const targets = appearanceSearchTargets(TRANSLATIONS.en)
+    const gated = Object.values(APPEARANCE_SETTINGS).filter(setting => 'available' in setting).length
+    expect(targets.length).toBeGreaterThanOrEqual(Object.keys(APPEARANCE_SETTINGS).length - gated)
+    expect(targets.map(target => target.label)).toEqual(expect.arrayContaining(['In-App Tips', 'Guided Tours']))
+  })
 })
diff --git a/apps/desktop/src/app/settings/use-settings-search.ts b/apps/desktop/src/app/settings/use-settings-search.ts
index fbf0d92836..afa21893a0 100644
--- a/apps/desktop/src/app/settings/use-settings-search.ts
+++ b/apps/desktop/src/app/settings/use-settings-search.ts
@@ -9,19 +9,14 @@ import { useI18n } from '@/i18n'
 import { type IconComponent, Monitor, Package, Palette, Settings2, Wrench } from '@/lib/icons'
 import { $agentPlugins, isDesktopRelevantPlugin, loadAgentPlugins } from '@/store/agent-plugins'
 import { $gatewayState } from '@/store/session'
-import { TRANSLUCENCY_SUPPORTED } from '@/store/translucency'
 
 import { useHermesConfigRecord } from '../hooks/use-config-record'
 import { useOnProfileSwitch } from '../hooks/use-on-profile-switch'
 
+import { appearanceSearchTargets } from './appearance-subpages'
 import { SECTIONS } from './constants'
 import { OTHER_SUBPAGES } from './other-subpages'
-import {
-  APPEARANCE_SETTING_IDS,
-  buildConfigSearchEntries,
-  buildCredentialSearchEntries,
-  type SettingsSearchEntry
-} from './settings-search'
+import { buildConfigSearchEntries, buildCredentialSearchEntries, type SettingsSearchEntry } from './settings-search'
 import { settingsSubpages } from './subpages'
 import type { SettingsView } from './types'
 
@@ -122,154 +117,16 @@ export function useSettingsSearchCatalog(enabled: boolean) {
         })
 
   const appearanceContext = t.settings.sections.appearance
-  const appearance = t.settings.appearance
 
-  const appearanceEntries: SettingsSearchEntry[] = [
-    ...(window.hermesDesktop?.minimizeToTray
-      ? [
-          {
-            context: appearanceContext,
-            description: t.settings.config.minimizeToTrayDesc,
-            icon: Monitor,
-            id: `setting:${APPEARANCE_SETTING_IDS.minimizeToTray}`,
-            keywords: ['tray', 'background', 'minimize', 'dock', 'taskbar', 'menu bar'],
-            label: t.settings.config.minimizeToTrayTitle,
-            target: { view: 'config:appearance' as const, setting: APPEARANCE_SETTING_IDS.minimizeToTray }
-          }
-        ]
-      : []),
-    {
-      context: appearanceContext,
-      description: t.language.description,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.language}`,
-      keywords: ['locale'],
-      label: t.language.label,
-      target: { setting: APPEARANCE_SETTING_IDS.language, view: 'config:appearance' }
-    },
-    {
-      context: appearanceContext,
-      description: appearance.themeDesc,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.theme}`,
-      keywords: ['color mode', 'skin'],
-      label: appearance.themeTitle,
-      target: { setting: APPEARANCE_SETTING_IDS.theme, view: 'config:appearance' }
-    },
-    {
-      context: appearanceContext,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.uiScale}`,
-      keywords: ['zoom', 'size'],
-      label: appearance.uiScaleTitle,
-      target: { setting: APPEARANCE_SETTING_IDS.uiScale, view: 'config:appearance' }
-    },
-    // Linux has no translucency row to land on, and a palette hit that scrolls
-    // to nothing is worse than no hit.
-    ...(TRANSLUCENCY_SUPPORTED
-      ? [
-          {
-            context: appearanceContext,
-            description: appearance.translucencyDesc,
-            icon: Palette,
-            id: `setting:${APPEARANCE_SETTING_IDS.translucency}`,
-            keywords: ['opacity', 'transparent'],
-            label: appearance.translucencyTitle,
-            target: { setting: APPEARANCE_SETTING_IDS.translucency, view: 'config:appearance' as const }
-          }
-        ]
-      : []),
-    {
-      context: appearanceContext,
-      description: appearance.userBubbleDesc,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.userBubble}`,
-      keywords: ['opacity', 'transparent', 'message', 'bubble'],
-      label: appearance.userBubbleTitle,
-      target: { setting: APPEARANCE_SETTING_IDS.userBubble, view: 'config:appearance' }
-    },
-    {
-      context: appearanceContext,
-      description: appearance.textDirectionDesc,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.textDirection}`,
-      keywords: ['rtl', 'ltr', 'right to left', 'left to right', 'bidi', 'arabic', 'hebrew', 'persian', 'align'],
-      label: appearance.textDirectionTitle,
-      target: { setting: APPEARANCE_SETTING_IDS.textDirection, view: 'config:appearance' }
-    },
-    {
-      context: appearanceContext,
-      description: appearance.backdropDesc,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.backdrop}`,
-      keywords: ['background', 'blur'],
-      label: appearance.backdropTitle,
-      target: { setting: APPEARANCE_SETTING_IDS.backdrop, view: 'config:appearance' }
-    },
-    {
-      context: appearanceContext,
-      description: appearance.introSplashDesc,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.introSplash}`,
-      keywords: ['splash', 'wordmark', 'empty chat', 'new chat'],
-      label: appearance.introSplashTitle,
-      target: { setting: APPEARANCE_SETTING_IDS.introSplash, view: 'config:appearance' }
-    },
-    {
-      context: appearanceContext,
-      description: t.interfaceMode.hint,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.interfaceMode}`,
-      keywords: ['simple', 'advanced', 'mode', 'interface', 'chrome', 'minimal', 'focus'],
-      label: t.interfaceMode.title,
-      target: { setting: APPEARANCE_SETTING_IDS.interfaceMode, view: 'config:appearance' }
-    },
-    {
-      context: appearanceContext,
-      description: appearance.toolViewDesc,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.toolView}`,
-      keywords: ['tool display', 'technical'],
-      label: appearance.toolViewTitle,
-      target: { setting: APPEARANCE_SETTING_IDS.toolView, view: 'config:appearance' }
-    },
-    {
-      context: appearanceContext,
-      description: appearance.hideCodeDiffsDesc,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.hideCodeDiffs}`,
-      keywords: ['code', 'diff', 'patch', 'file edits', 'inline', 'added', 'removed'],
-      label: appearance.hideCodeDiffsTitle,
-      target: { setting: APPEARANCE_SETTING_IDS.hideCodeDiffs, view: 'config:appearance' }
-    },
-    {
-      context: appearanceContext,
-      description: appearance.hideThreadTimelineDesc,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.hideThreadTimeline}`,
-      keywords: ['thread', 'conversation', 'timeline', 'bars', 'rail', 'navigation', 'hide'],
-      label: appearance.hideThreadTimelineTitle,
-      target: { setting: APPEARANCE_SETTING_IDS.hideThreadTimeline, view: 'config:appearance' }
-    },
-    {
-      context: appearanceContext,
-      description: appearance.appActionsDesc,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.appActions}`,
-      keywords: ['titlebar', 'settings gear', 'layout', 'HUD', 'left', 'right', 'tabs'],
-      label: appearance.appActionsTitle,
-      target: { setting: APPEARANCE_SETTING_IDS.appActions, view: 'config:appearance' }
-    },
-    {
-      context: appearanceContext,
-      description: appearance.embedsDesc,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.embeds}`,
-      keywords: ['external content', 'privacy'],
-      label: appearance.embedsTitle,
-      target: { setting: APPEARANCE_SETTING_IDS.embeds, view: 'config:appearance' }
-    }
-  ]
+  // Every hand-built Appearance row, straight from the manifest that also
+  // routes and ids them — the palette cannot drift from the page.
+  const appearanceEntries: SettingsSearchEntry[] = appearanceSearchTargets(t).map(({ id, ...entry }) => ({
+    ...entry,
+    context: appearanceContext,
+    icon: Palette,
+    id: `setting:${id}`,
+    target: { setting: id, view: 'config:appearance' }
+  }))
 
   const credentialEntries = buildCredentialSearchEntries(
     envVarsFetching || envVarsError ? null : envVars,
@@ -285,6 +142,10 @@ export function useSettingsSearchCatalog(enabled: boolean) {
     sessions: t.settings.nav.archivedChats
   }
 
+  // A page named after its one setting (Appearance › Theme) would show up as
+  // two identical rows; the setting wins because it lands on the row itself.
+  const settingLabels = new Set(appearanceEntries.map(entry => `${entry.context}\u0000${entry.label}`))
+
   const subpageEntries: SettingsSearchEntry[] = [
     ...SECTIONS.map(section => ({
       view: `config:${section.id}` as SettingsView,
@@ -296,16 +157,18 @@ export function useSettingsSearchCatalog(enabled: boolean) {
       label: pageLabels[view],
       icon: Settings2
     }))
-  ].flatMap(parent =>
-    settingsSubpages(parent.view).map(page => ({
-      context: parent.label,
-      icon: parent.icon,
-      id: `settings-page:${parent.view}:${page.id}`,
-      keywords: [parent.label, page.id],
-      label: t.settings.subpages[page.labelKey],
-      target: { view: parent.view, subpage: page.id }
-    }))
-  )
+  ]
+    .flatMap(parent =>
+      settingsSubpages(parent.view).map(page => ({
+        context: parent.label,
+        icon: parent.icon,
+        id: `settings-page:${parent.view}:${page.id}`,
+        keywords: [parent.label, page.id],
+        label: t.settings.subpages[page.labelKey],
+        target: { view: parent.view, subpage: page.id }
+      }))
+    )
+    .filter(entry => !settingLabels.has(`${entry.context}\u0000${entry.label}`))
 
   return {
     subpageEntries: [

From 686c34d3f6f3c433bbfed8f45b60f208a18849d1 Mon Sep 17 00:00:00 2001
From: IAvecilla <ignacio.avecilla@lambdaclass.com>
Date: Wed, 23 Sep 2026 18:52:15 -0700
Subject: [PATCH 13/61] feat(bot_desktop): ship Bot Screen on hosted images
 (-desktop tags)

The published image had no Xvnc/Xfce because nothing set the Dockerfile's
HERMES_BOT_DESKTOP argument, and a hosted instance (unprivileged, no sudo,
sealed /opt/hermes) cannot install at run time. The image layer is the only
delivery path.

- docker.yml: variant axis [slim, desktop]. :latest / :main / :v* stay the
  image they are today; :latest-desktop / :main-desktop / :v*-desktop carry
  the packages plus Playwright's headed Chromium. Slim owns the build cache
  scope; one manifest per variant so a desktop publish failure never skips
  slim's :latest.
- Dockerfile / stage2-hook.sh: XDG_RUNTIME_DIR=/tmp/hermes-runtime seeded
  0700 as hermes (containers have no logind; the $HOME/.cache fallback was
  the shared /opt/data volume), refused when foreign-owned; deterministic
  Chromium discovery exporting the headless shell for ordinary browsing.
- bot_desktop: memory gate reads the cgroup working set (usage minus
  inactive_file) so it cannot tighten over uptime and refuse to restart a
  screen idle-stop just stopped; installable() gives three distinct dead-end
  messages instead of a sudo line nobody there can run; env_for_agent
  replaces a headless-shell pin so agent and dock share one Chromium.

Squash of IAvecilla/hermes-agent:bot-desktop-cloud-image (#112381, 13
commits), which GitHub auto-closed when its base branch merged as #108914.
Review fixes from pefontana (cache scope, per-variant merge, red browser
test) are included.

Co-authored-by: pefontana <pefontana@users.noreply.github.com>
---
 .github/workflows/docker.yml                  |  65 +++++++----
 Dockerfile                                    |  42 ++++++-
 docker/stage2-hook.sh                         |  47 ++++++--
 hermes_cli/config.py                          |   3 +
 hermes_cli/config_defaults.py                 |   8 +-
 tests/tools/test_bot_desktop_browser.py       |  37 ++++++
 tests/tools/test_bot_desktop_resources.py     |  34 ++++++
 tests/tools/test_bot_desktop_runtime.py       | 106 ++++++++++++++++++
 tools/bot_desktop/browser.py                  |  19 +++-
 tools/bot_desktop/resources.py                |  38 ++++++-
 tools/bot_desktop/runtime.py                  |  55 +++++++--
 .../docs/user-guide/features/bot-screen.md    |  24 +++-
 12 files changed, 422 insertions(+), 56 deletions(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 7e6b916f2a..df6c3fb501 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -74,19 +74,21 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
+        # Two images per arch. `slim` is what :latest has always been; `desktop`
+        # adds the Bot Screen packages and a headed Chromium (+1.4 GB) for the
+        # tier that offers a screen. Both are built on a PR so a change that only
+        # breaks the gated layers cannot reach publish.
+        arch: [amd64, arm64]
+        variant: [slim, desktop]
         include:
           - arch: amd64
             runner: ubuntu-latest-32-core
             platform: linux/amd64
-            cache-from: type=gha,scope=docker-amd64
-            cache-to: type=gha,mode=max,scope=docker-amd64
           # arm64 builds on the native arm64 larger runner. A build of
           # linux/arm64 on an x64 host uses emulation.
           - arch: arm64
             runner: ubuntu-latest-32-arm-core
             platform: linux/arm64
-            cache-from: type=gha,scope=docker-arm64
-            cache-to: type=gha,mode=max,scope=docker-arm64
 
     runs-on: ${{ matrix.runner }}
     timeout-minutes: 45
@@ -124,8 +126,11 @@ jobs:
           tags: ${{ env.IMAGE_NAME }}:test
           build-args: |
             HERMES_GIT_SHA=${{ github.sha }}
-          cache-from: ${{ matrix.cache-from }}
-          cache-to: ${{ (github.event_name != 'pull_request') && matrix.cache-to || '' }}
+            HERMES_BOT_DESKTOP=${{ matrix.variant == 'desktop' && '1' || '0' }}
+          # Slim owns the scope; desktop is slim plus two RUN steps, so it reads
+          # and writes nothing — a 5.5 GB mode=max scope would blow the 10 GB cap.
+          cache-from: type=gha,scope=docker-${{ matrix.arch }}
+          cache-to: ${{ (github.event_name != 'pull_request' && matrix.variant == 'slim') && format('type=gha,mode=max,scope=docker-{0}', matrix.arch) || '' }}
 
 
       # Run the docker-integration test suite against the freshly-built
@@ -191,18 +196,16 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
+        arch: [amd64, arm64]
+        variant: [slim, desktop]
         include:
           - arch: amd64
             runner: ubuntu-latest-32-core
             platform: linux/amd64
-            cache-from: type=gha,scope=docker-amd64
-            cache-to: type=gha,mode=max,scope=docker-amd64
           # Native arm64 for the same reason as the build matrix above.
           - arch: arm64
             runner: ubuntu-latest-32-arm-core
             platform: linux/arm64
-            cache-from: type=gha,scope=docker-arm64
-            cache-to: type=gha,mode=max,scope=docker-arm64
     runs-on: ${{ matrix.runner }}
     timeout-minutes: 30
     steps:
@@ -242,9 +245,10 @@ jobs:
             org.opencontainers.image.revision=${{ github.sha }}
           build-args: |
             HERMES_GIT_SHA=${{ github.sha }}
+            HERMES_BOT_DESKTOP=${{ matrix.variant == 'desktop' && '1' || '0' }}
           outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
-          cache-from: ${{ matrix.cache-from }}
-          cache-to: ${{ matrix.cache-to }}
+          cache-from: type=gha,scope=docker-${{ matrix.arch }}
+          cache-to: ${{ matrix.variant == 'slim' && format('type=gha,mode=max,scope=docker-{0}', matrix.arch) || '' }}
 
       - name: Export digest
         run: |
@@ -255,7 +259,7 @@ jobs:
       - name: Upload digest artifact
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
-          name: digest-${{ matrix.arch }}
+          name: digest-${{ matrix.variant }}-${{ matrix.arch }}
           path: /tmp/digests/*
           if-no-files-found: error
           retention-days: 1
@@ -269,17 +273,30 @@ jobs:
   # On releases: tags :<release_tag_name>.
   # ---------------------------------------------------------------------------
   merge:
-    if: github.repository == 'NousResearch/hermes-agent' && (github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release')
+    # `needs` is the whole 4-leg matrix and a failed need skips the job, so a
+    # transient desktop push would take slim's :latest with it. Guard below.
+    if: ${{ !cancelled() && github.repository == 'NousResearch/hermes-agent' && (github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release') }}
     runs-on: ubuntu-latest
     needs: [publish]
     timeout-minutes: 10
     environment: container-publish
+    strategy:
+      fail-fast: false
+      matrix:
+        # One manifest list per variant. `slim` keeps the unsuffixed tags it has
+        # always had, so nothing that pulls :latest today changes; `desktop`
+        # publishes the same digests under a -desktop suffix.
+        include:
+          - variant: slim
+            suffix: ""
+          - variant: desktop
+            suffix: "-desktop"
     steps:
       - name: Download digests
         uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           path: /tmp/digests
-          pattern: digest-*
+          pattern: digest-${{ matrix.variant }}-*
           merge-multiple: true
 
       # Retry once on transient Docker Hub / buildkit pull failures.
@@ -304,16 +321,25 @@ jobs:
         env:
           IMAGE_NAME: ${{ env.IMAGE_NAME }}
           RELEASE_TAG: ${{ github.event.release.tag_name }}
+          SUFFIX: ${{ matrix.suffix }}
         run: |
           set -euo pipefail
+          # Without nullglob an empty dir yields the literal `*`: one bogus entry.
+          shopt -s nullglob
           args=()
           for digest_file in *; do
             args+=("${IMAGE_NAME}@sha256:${digest_file}")
           done
+          # One per arch in the publish matrix; a short set means a leg failed, and
+          # stitching it would publish a single-arch :latest. Keep in step with it.
+          if [ "${#args[@]}" -ne 2 ]; then
+            echo "::error::variant ${{ matrix.variant }}: want 2 digests, found ${#args[@]} (a publish leg failed)"
+            exit 1
+          fi
           if [ "${{ github.event_name }}" = "release" ]; then
-            tags=(-t "${IMAGE_NAME}:${RELEASE_TAG}")
+            tags=(-t "${IMAGE_NAME}:${RELEASE_TAG}${SUFFIX}")
           else
-            tags=(-t "${IMAGE_NAME}:main" -t "${IMAGE_NAME}:latest")
+            tags=(-t "${IMAGE_NAME}:main${SUFFIX}" -t "${IMAGE_NAME}:latest${SUFFIX}")
           fi
           # Retry: Docker Hub API + just-pushed digest eventual consistency
           # can transiently fail the create; the operation is idempotent.
@@ -333,9 +359,10 @@ jobs:
         env:
           IMAGE_NAME: ${{ env.IMAGE_NAME }}
           RELEASE_TAG: ${{ github.event.release.tag_name }}
+          SUFFIX: ${{ matrix.suffix }}
         run: |
           if [ "${{ github.event_name }}" = "release" ]; then
-            docker buildx imagetools inspect "${IMAGE_NAME}:${RELEASE_TAG}"
+            docker buildx imagetools inspect "${IMAGE_NAME}:${RELEASE_TAG}${SUFFIX}"
           else
-            docker buildx imagetools inspect "${IMAGE_NAME}:main"
+            docker buildx imagetools inspect "${IMAGE_NAME}:main${SUFFIX}"
           fi
diff --git a/Dockerfile b/Dockerfile
index 1fece52ce7..ba9cbe8724 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -73,11 +73,14 @@ RUN apt-get -o Acquire::Retries=3 update && \
     ca-certificates curl iputils-ping python3 python-is-python3 ripgrep ffmpeg gcc g++ make cmake python3-dev python3-venv libffi-dev libolm-dev libatomic1 procps git openssh-client docker-cli xz-utils && \
     rm -rf /var/lib/apt/lists/*
 
-# Bot Screen (opt-in): TigerVNC + the Xfce components + a headed chromium, so a
-# container that cannot run apt at run time (unprivileged user, no sudo — every
-# hosted instance) can still stream a desktop. ~550 MB. Nothing here starts at
-# boot; the layer costs no memory until a screen is started. Same package list
-# as tools/bot_desktop/runtime.py::PACKAGES["apt"].
+# Bot Screen (opt-in): PACKAGES["apt"] from tools/bot_desktop/runtime.py plus apt
+# `chromium` for the dock's Browser icon. ~930 MB apt on debian:13.4 (~1.4 GB of
+# image once the gated headed Chromium below is counted); nothing starts
+# at boot. docker.yml builds both variants and publishes these packages under
+# the `-desktop` tags: hosted sandboxes pull a prebuilt image and never run a
+# build, and cannot apt at run time either (unprivileged, no sudo). Only this
+# build step needs root —
+# Xvnc is a userspace X server, so the runtime user can drive it.
 #   docker build --build-arg HERMES_BOT_DESKTOP=1 .
 ARG HERMES_BOT_DESKTOP=0
 RUN if [ "$HERMES_BOT_DESKTOP" = "1" ]; then \
@@ -211,13 +214,25 @@ COPY apps/shared/ apps/shared/
 # guards against a future regression if the source npm version changes.
 ENV npm_config_install_links=false
 
+# chrome-headless-shell: what the browser tool has always driven headlessly.
+# Smaller, no window code paths. --with-deps pulls the shared system libraries.
 RUN npm install --prefer-offline --no-audit --fetch-retries=5 && \
     for i in 1 2 3; do \
         npx playwright install --with-deps chromium --only-shell && break || \
-        { [ "$i" = 3 ] && exit 1; echo "playwright install failed (attempt $i); retrying in 10s"; sleep 10; }; \
+        { [ "$i" = 3 ] && exit 1; echo "playwright headless-shell install failed (attempt $i); retrying in 10s"; sleep 10; }; \
     done && \
     npm cache clean --force
 
+# chrome-headless-shell cannot open a window, so the dock's Browser icon needs the
+# full build. Same Chromium family as the shell, so agent and human share one
+# --user-data-dir. Gated: a build with no desktop has nothing to show it on.
+RUN if [ "$HERMES_BOT_DESKTOP" = "1" ]; then \
+        for i in 1 2 3; do \
+            npx playwright install chromium && break || \
+            { [ "$i" = 3 ] && exit 1; echo "playwright chromium install failed (attempt $i); retrying in 10s"; sleep 10; }; \
+        done; \
+    fi
+
 # ---------- Photon iMessage sidecar deps (baked, NS-606) ----------
 # The photon plugin's Node sidecar needs its own node_modules
 # (spectrum-ts). The install tree is immutable at runtime, so a lazy
@@ -293,6 +308,15 @@ COPY apps/shared/ apps/shared/
 RUN cd web && npm run build && \
     cd ../ui-tui && npm run build
 
+# ---------- Bot Screen X socket directory ----------
+# Xvnc would create this itself (/tmp is 1777); pre-creating it keeps ownership
+# deterministic when HERMES_UID is remapped between boots.
+RUN mkdir -p /tmp/.X11-unix && chmod 1777 /tmp/.X11-unix
+
+# XDG_RUNTIME_DIR (set below) sits under a predictable name in world-writable /tmp.
+# Shipping it root-owned means stage2 finds a directory it trusts and chowns it.
+RUN mkdir -p /tmp/hermes-runtime && chmod 0700 /tmp/hermes-runtime
+
 # ---------- Source code ----------
 # .dockerignore excludes node_modules, so the installs above survive.
 # --link decouples this layer from parents for cache purposes; --chmod bakes
@@ -418,6 +442,12 @@ ENV HERMES_DISABLE_LAZY_INSTALLS=1
 # updates (an ABI stamp invalidates it if a rebuild bumps the interpreter).
 ENV HERMES_LAZY_INSTALL_TARGET=/opt/data/lazy-packages
 
+# Xfce, dbus and the display-allocation lock need one; containers have no logind
+# to create /run/user/<uid>. The default fallback ($HOME/.cache) is the /opt/data
+# volume, which a host-side install may share — two instances would then contend
+# for one lock. Container-scoped instead; seeded 0700 by docker/stage2-hook.sh.
+ENV XDG_RUNTIME_DIR=/tmp/hermes-runtime
+
 # `docker exec` privilege-drop shim. When operators run
 # `docker exec <c> hermes ...` they default to root, and any file the
 # command writes under $HERMES_HOME (auth.json, .env, config.yaml) ends
diff --git a/docker/stage2-hook.sh b/docker/stage2-hook.sh
index 61d5d12b57..9b8e489aa9 100755
--- a/docker/stage2-hook.sh
+++ b/docker/stage2-hook.sh
@@ -395,6 +395,31 @@ as_hermes mkdir -p \
     "$HERMES_HOME/platforms/pairing" \
     "$HERMES_HOME/lazy-packages"
 
+# --- XDG_RUNTIME_DIR ---
+# 0700 as dbus requires. It lives in world-writable /tmp under a predictable name
+# and holds the display-allocation lock, so it is a security boundary: refuse a
+# symlink or a directory someone else owns (chowning that one would hand hermes a
+# directory whose creator keeps an fd into it), and chown rather than assume —
+# `usermod -u` above does not chown outside the home dir, so a HERMES_UID remap
+# would leave it owned by the old uid and every Xfce/dbus/lock open would EACCES.
+if [ -n "${XDG_RUNTIME_DIR:-}" ]; then
+    xdg_owner=""
+    if [ -e "$XDG_RUNTIME_DIR" ]; then xdg_owner=$(stat -c %u "$XDG_RUNTIME_DIR" 2>/dev/null || echo unknown); fi
+    if refuse_symlinked_path "create" "$XDG_RUNTIME_DIR"; then
+        :
+    elif [ -n "$xdg_owner" ] && [ "$xdg_owner" != "0" ] && [ "$xdg_owner" != "$actual_hermes_uid" ]; then
+        echo "[stage2] Warning: $XDG_RUNTIME_DIR is owned by uid $xdg_owner (not root or hermes) — refusing to adopt it"
+    else
+        mkdir -p "$XDG_RUNTIME_DIR" 2>/dev/null || \
+            echo "[stage2] Warning: could not create XDG_RUNTIME_DIR $XDG_RUNTIME_DIR (continuing)"
+        if [ -d "$XDG_RUNTIME_DIR" ]; then
+            chown hermes:hermes "$XDG_RUNTIME_DIR" 2>/dev/null || \
+                echo "[stage2] Warning: could not chown XDG_RUNTIME_DIR $XDG_RUNTIME_DIR (rootless?)"
+            chmod 0700 "$XDG_RUNTIME_DIR" 2>/dev/null || true
+        fi
+    fi
+fi
+
 # --- Install-method stamp ---
 # The 'docker' stamp is baked into the immutable install tree at
 # /opt/hermes/.install_method (see Dockerfile), NOT written here into
@@ -718,10 +743,10 @@ if [ -d "$INSTALL_DIR/skills" ]; then
 fi
 
 # --- Discover agent-browser's Chromium binary ---
-# The image's Dockerfile runs `npx playwright install chromium`, which
-# populates ``$PLAYWRIGHT_BROWSERS_PATH`` (=/opt/hermes/.playwright) with
-# a ``chromium_headless_shell-<build>/chrome-headless-shell-linux64/``
-# directory. agent-browser (the runtime CLI Hermes spawns for the
+# The image populates ``$PLAYWRIGHT_BROWSERS_PATH`` (=/opt/hermes/.playwright)
+# with ``chromium_headless_shell-<build>/chrome-headless-shell-linux64/``, plus
+# ``chromium-<build>/chrome-linux64/`` on a HERMES_BOT_DESKTOP build.
+# agent-browser (the runtime CLI Hermes spawns for the
 # browser tool) doesn't recognise this layout in its own cache scan and
 # fails with "Auto-launch failed: Chrome not found" — even though the
 # binary is right there (#15697).
@@ -746,11 +771,19 @@ fi
 if [ -z "${AGENT_BROWSER_EXECUTABLE_PATH:-}" ] && \
         [ -n "${PLAYWRIGHT_BROWSERS_PATH:-}" ] && \
         [ -d "$PLAYWRIGHT_BROWSERS_PATH" ]; then
+    # Two ordered finds, not one with alternated -name predicates: that returns
+    # them in directory order, i.e. whichever Playwright unpacked first. Shell
+    # first, because this is what agent-browser launches for ordinary headless
+    # browsing everywhere and it is the lighter build; browser.py::env_for_agent
+    # swaps in the headed one for the agent while a screen is up.
     browser_bin=$(find "$PLAYWRIGHT_BROWSERS_PATH" -type f -executable \
-        \( -name 'chrome' -o -name 'chromium' \
-           -o -name 'chrome-headless-shell' -o -name 'headless_shell' \
-           -o -name 'chromium-browser' \) \
+        \( -name 'chrome-headless-shell' -o -name 'headless_shell' \) \
         2>/dev/null | head -n 1)
+    if [ -z "$browser_bin" ]; then
+        browser_bin=$(find "$PLAYWRIGHT_BROWSERS_PATH" -type f -executable \
+            \( -name 'chrome' -o -name 'chromium' -o -name 'chromium-browser' \) \
+            2>/dev/null | head -n 1)
+    fi
     if [ -n "$browser_bin" ]; then
         echo "[stage2] Found agent-browser Chromium binary: $browser_bin"
         # Write to s6's container_environment so with-contenv picks it
diff --git a/hermes_cli/config.py b/hermes_cli/config.py
index bb29e67b37..ca846e01b7 100644
--- a/hermes_cli/config.py
+++ b/hermes_cli/config.py
@@ -355,6 +355,9 @@ Notes:
     won't move your container — pull the newer tag you actually want, or
     switch to ``:latest`` / ``:main`` for rolling updates.  See available
     tags at https://hub.docker.com/r/nousresearch/hermes-agent/tags
+  • On a ``-desktop`` tag (the one carrying Bot Screen)?  Keep the suffix:
+    the unsuffixed image has no Xvnc/Xfce and no sudo to add them, so
+    pulling it stops the bots' screens from starting.
   • Your config and session history live under ``$HERMES_HOME`` (``/opt/data``
     in the container, typically bind-mounted from the host) and persist
     across image upgrades — re-pulling doesn't lose any state.
diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.py
index c2bfcce914..5ded10e044 100644
--- a/hermes_cli/config_defaults.py
+++ b/hermes_cli/config_defaults.py
@@ -2470,9 +2470,11 @@ DEFAULT_CONFIG = {
         # host. Off by default so installing TigerVNC for other reasons never yields a screen nobody asked
         # for; Hermes Desktop's Screen pane offers Start and this toggle.
         "auto_start": False,
-        # Refuse to start the screen while the host (or its container cgroup) has less than this free.
-        # Xvnc + Xfce idle at ~220 MB and a takeover's browser adds 0.5-1 GB; on a small instance the
-        # loser is Chromium mid-login or the gateway itself. 0 disables the check.
+        # Refuse to start below this much free memory (MB), measured on the host or its container cgroup,
+        # whichever is tighter. Xvnc + Xfce idle at ~220 MB and a takeover's browser adds 0.5-1 GB, so a
+        # screen with one page runs past 1 GB; the kernel OOM killer picks its victim by score, so on a
+        # small instance the loser is the dashboard or the gateway rather than the desktop. 0 disables the
+        # check.
         "min_free_memory_mb": 1536,
         # Stop a screen nobody has used (no computer_use action, browser spawn, viewer or takeover) for this
         # long; it restarts on the next use. Idle Xvnc + Xfce hold ~220 MB, an abandoned browser far more.
diff --git a/tests/tools/test_bot_desktop_browser.py b/tests/tools/test_bot_desktop_browser.py
index 61e57244bf..b5bdab304f 100644
--- a/tests/tools/test_bot_desktop_browser.py
+++ b/tests/tools/test_bot_desktop_browser.py
@@ -315,3 +315,40 @@ def test_daemon_idle_timer_defers_to_the_janitor_only_for_the_shared_headed_brow
     monkeypatch.setattr(session._cloud, "_is_headed_mode", lambda: True)
     monkeypatch.setattr(runtime, "published_env", lambda: {})
     assert session._daemon_idle_timeout_seconds() == 120
+
+
+def test_a_headless_shell_pin_is_replaced_while_a_screen_is_up(tmp_path, monkeypatch):
+    """The boot hook exports a chrome-headless-shell path; leaving it would put the agent and the dock on
+    two binaries over one --user-data-dir, where the singleton swallows the dock's launch."""
+    shell = tmp_path / "chrome-headless-shell"
+    shell.write_text("#!/bin/sh\n", encoding="utf-8")
+    shell.chmod(0o755)
+    headed = tmp_path / "chrome"
+    headed.write_text("#!/bin/sh\n", encoding="utf-8")
+    headed.chmod(0o755)
+    monkeypatch.setattr(runtime, "state_dir", lambda: tmp_path / "bot-desktop")
+    monkeypatch.setattr(browser, "_playwright_executable", lambda: str(headed))
+    monkeypatch.delenv("AGENT_BROWSER_PROFILE", raising=False)
+    # Unpinned, the ubuntu runner (non-root, userns-restricted) flips executable() to
+    # its own /usr/bin/google-chrome; host policy is not the subject here.
+    monkeypatch.setattr(browser, "_userns_restricted", lambda: False)
+
+    agent_env = browser.env_for_agent({"AGENT_BROWSER_EXECUTABLE_PATH": str(shell)})
+    dock_exe, _ = browser.dock_launch()
+    assert agent_env["AGENT_BROWSER_EXECUTABLE_PATH"] == dock_exe == str(headed), \
+        "the agent and the dock must share one binary once a screen is up"
+
+
+def test_a_real_user_pin_is_still_honoured(tmp_path, monkeypatch):
+    """Only a headless-shell pin is overridden; a human's own headed browser stays put."""
+    mine = tmp_path / "my-chrome"
+    mine.write_text("#!/bin/sh\n", encoding="utf-8")
+    mine.chmod(0o755)
+    other = tmp_path / "chrome"
+    other.write_text("#!/bin/sh\n", encoding="utf-8")
+    other.chmod(0o755)
+    monkeypatch.setattr(runtime, "state_dir", lambda: tmp_path / "bot-desktop")
+    monkeypatch.setattr(browser, "_playwright_executable", lambda: str(other))
+
+    env = browser.env_for_agent({"AGENT_BROWSER_EXECUTABLE_PATH": str(mine)})
+    assert env["AGENT_BROWSER_EXECUTABLE_PATH"] == str(mine)
diff --git a/tests/tools/test_bot_desktop_resources.py b/tests/tools/test_bot_desktop_resources.py
index f49d90e3e1..5564b09376 100644
--- a/tests/tools/test_bot_desktop_resources.py
+++ b/tests/tools/test_bot_desktop_resources.py
@@ -62,3 +62,37 @@ def test_memory_info_takes_the_tighter_of_cgroup_and_host(tmp_path, monkeypatch)
     assert info.available_mb == 1024 and info.limit_mb == 2048
     (v2 / "memory.max").write_text("max")  # no limit: host numbers
     assert resources.memory_info() == resources.MemoryInfo(available_mb=3072, limit_mb=4096)
+
+
+def _cgroup(monkeypatch, tmp_path, *, v2=True, limit, usage, cache):
+    """A cgroup tree: ``usage`` consumed, ``cache`` of it reclaimable."""
+    root = tmp_path / "cg"
+    root.mkdir(exist_ok=True)
+    monkeypatch.setattr(resources, "_MEMINFO", tmp_path / "no-meminfo")  # cgroup numbers only
+    if v2:
+        monkeypatch.setattr(resources, "_CGROUP_V2", root)
+        monkeypatch.setattr(resources, "_CGROUP_V1", tmp_path / "nope")
+        (root / "memory.max").write_text(str(limit))
+        (root / "memory.current").write_text(str(usage))
+        (root / "memory.stat").write_text(f"anon 123\ninactive_file {cache}\nslab 7\n")
+    else:
+        monkeypatch.setattr(resources, "_CGROUP_V2", tmp_path / "nope")
+        monkeypatch.setattr(resources, "_CGROUP_V1", root)
+        (root / "memory.limit_in_bytes").write_text(str(limit))
+        (root / "memory.usage_in_bytes").write_text(str(usage))
+        (root / "memory.stat").write_text(f"total_inactive_file {cache}\n")
+
+
+@pytest.mark.parametrize("v2", [True, False], ids=["cgroup-v2", "cgroup-v1"])
+def test_page_cache_does_not_count_against_the_limit(tmp_path, monkeypatch, v2):
+    """643 MiB of mostly page cache must not read as 643 MiB consumed: charging it would tighten the gate
+    over uptime, and refuse to restart a screen the idle auto-stop had just stopped."""
+    MB = 1024 * 1024
+    _cgroup(monkeypatch, tmp_path, v2=v2, limit=4096 * MB, usage=643 * MB, cache=340 * MB)
+    assert resources.memory_info().available_mb == 4096 - (643 - 340)
+
+
+def test_a_zero_floor_disables_the_gate(monkeypatch):
+    """config_defaults documents "0 disables the check"."""
+    monkeypatch.setattr(resources, "min_free_mb", lambda: 0)
+    assert resources.memory_blocker(resources.MemoryInfo(available_mb=10, limit_mb=4096)) is None
diff --git a/tests/tools/test_bot_desktop_runtime.py b/tests/tools/test_bot_desktop_runtime.py
index 45500aee83..e4a96c9304 100644
--- a/tests/tools/test_bot_desktop_runtime.py
+++ b/tests/tools/test_bot_desktop_runtime.py
@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import contextlib
+import re
 import threading
 import time
 import sys
@@ -23,6 +24,21 @@ def test_every_required_binary_maps_to_an_installed_package(pm):
     assert not {"xorg-x11-server-utils", "xorg-x11-utils"} & set(runtime.PACKAGES["dnf"]), "retired on Fedora"
 
 
+def test_the_image_bakes_the_same_apt_packages_the_runtime_would_install() -> None:
+    """The image layer is the only delivery path on a hosted instance, so a package added here but not
+    there stalls the screen with no error until someone presses Start."""
+    dockerfile = Path(__file__).resolve().parents[2] / "Dockerfile"
+    text = dockerfile.read_text()
+    assert "ARG HERMES_BOT_DESKTOP" in text, "the Bot Screen apt layer is gone from the Dockerfile"
+    body = text.split("ARG HERMES_BOT_DESKTOP", 1)[1].split("--no-install-recommends", 1)[1].split("rm -rf", 1)[0]
+    baked = {tok for tok in re.split(r"[\s\\&]+", body) if tok and not tok.startswith("-")}
+    required = set(runtime.PACKAGES["apt"])
+    assert required <= baked, f"the image would not install: {sorted(required - baked)}"
+    # apt `chromium` on top of the operator's list: a headed browser for the dock's Browser icon that
+    # does not depend on Playwright's copy being unpacked yet.
+    assert baked - required <= {"chromium"}, f"unexpected extra packages: {sorted(baked - required)}"
+
+
 def test_no_running_screen_returns_none_without_grabbing(monkeypatch):
     monkeypatch.setattr(runtime, "published_env", lambda: {"DISPLAY": ":99"})
     monkeypatch.setattr(runtime, "_launcher_pid", lambda: None)
@@ -365,3 +381,93 @@ def test_allocation_lock_is_released_once_xvnc_claims_the_number(in_process_runt
     t.join()
     assert st.running
     assert seen.get("free") is True, "allocation lock still held after Xvnc wrote its X lock"
+
+
+def _startable_host(monkeypatch, tmp_path, *, running=False):
+    """A Linux host with the packages present, so only the check under test can block a start."""
+    from tools.bot_desktop import resources
+    monkeypatch.setattr(runtime, "is_supported_host", lambda: True)
+    monkeypatch.setattr(runtime, "missing_binaries", lambda: [])
+    monkeypatch.setattr(runtime, "state_dir", lambda: tmp_path / "bd")
+    monkeypatch.setattr(runtime, "_launcher_pid", lambda: 4242 if running else None)
+    monkeypatch.setattr(runtime, "published_env", lambda: {"DISPLAY": ":7"} if running else {})
+    monkeypatch.setattr(runtime, "_reap_orphaned_server", lambda sd: None)
+    monkeypatch.setattr(resources, "min_free_mb", lambda: 1536)
+    monkeypatch.setattr(resources, "memory_info",
+                        lambda: resources.MemoryInfo(available_mb=400, limit_mb=4096))
+    spawned: list = []
+    monkeypatch.setattr(runtime, "_spawn_and_wait", lambda *a, **k: spawned.append(a))
+    return spawned
+
+
+def test_a_running_desktop_is_never_refused_for_the_memory_it_is_using(tmp_path, monkeypatch):
+    """The gate guards the allocation, not the session: a running desktop is itself what consumes the
+    memory, so checking before the running-check made Start fail on a healthy screen."""
+    _startable_host(monkeypatch, tmp_path, running=True)
+    runtime.start()  # returns status(); must not raise about headroom
+
+
+def test_a_root_host_without_a_package_manager_is_told_the_truth(tmp_path, monkeypatch):
+    """Root with no package manager: installable() is False for a reason unrelated to privilege."""
+    _startable_host(monkeypatch, tmp_path)
+    monkeypatch.setattr(runtime, "missing_binaries", lambda: ["Xvnc"])
+    monkeypatch.setattr(runtime, "package_manager", lambda: None)
+    monkeypatch.setattr(runtime, "is_root", lambda: True)
+    assert runtime.installable() is False
+    with pytest.raises(RuntimeError) as excinfo:
+        runtime.start()
+    message = str(excinfo.value)
+    assert "package manager" in message
+    assert "unprivileged" not in message and "sudo" not in message, f"wrong diagnosis: {message}"
+
+
+def test_an_unprivileged_host_is_pointed_at_the_image(tmp_path, monkeypatch):
+    """The published image: a package manager exists but there is no way to reach root."""
+    _startable_host(monkeypatch, tmp_path)
+    monkeypatch.setattr(runtime, "missing_binaries", lambda: ["Xvnc"])
+    monkeypatch.setattr(runtime, "package_manager", lambda: "apt")
+    monkeypatch.setattr(runtime, "is_root", lambda: False)
+    monkeypatch.setattr(runtime.shutil, "which", lambda name: None if name == "sudo" else "/usr/bin/" + name)
+    assert runtime.installable() is False
+    with pytest.raises(RuntimeError, match="baked in"):
+        runtime.start()
+
+
+def test_a_host_that_can_install_gets_the_command(tmp_path, monkeypatch):
+    """The branch that used to be unreachable behind an `or` fallback."""
+    _startable_host(monkeypatch, tmp_path)
+    monkeypatch.setattr(runtime, "missing_binaries", lambda: ["Xvnc"])
+    monkeypatch.setattr(runtime, "package_manager", lambda: "apt")
+    monkeypatch.setattr(runtime, "is_root", lambda: True)
+    with pytest.raises(RuntimeError, match="tigervnc-standalone-server"):
+        runtime.start()
+
+
+def test_a_tight_but_sufficient_start_is_logged(tmp_path, monkeypatch, caplog):
+    """Above the floor but below the derived threshold the start proceeds and says so. It is the only
+    signal an operator gets that a screen came up with no room for the browser that is the point of it,
+    so it has to actually fire rather than merely be computable."""
+    from tools.bot_desktop import resources
+
+    spawned = _startable_host(monkeypatch, tmp_path)
+    monkeypatch.setattr(resources, "min_free_mb", lambda: 1536)  # threshold -> 2048
+    monkeypatch.setattr(resources, "memory_info",
+                        lambda: resources.MemoryInfo(available_mb=1800, limit_mb=2048))
+    with caplog.at_level("WARNING", logger="tools.bot_desktop.runtime"):
+        runtime.start()
+    assert spawned, "1800 MB clears the 1536 MB floor, so the screen still starts"
+    logged = [r.getMessage() for r in caplog.records]
+    assert any("1800 MB available" in m for m in logged), f"no tight-headroom warning in {logged}"
+
+
+def test_a_comfortable_start_is_not_logged(tmp_path, monkeypatch, caplog):
+    """And it stays quiet with real headroom, or it would fire on every start and mean nothing."""
+    from tools.bot_desktop import resources
+
+    _startable_host(monkeypatch, tmp_path)
+    monkeypatch.setattr(resources, "min_free_mb", lambda: 1536)
+    monkeypatch.setattr(resources, "memory_info",
+                        lambda: resources.MemoryInfo(available_mb=7210, limit_mb=8182))
+    with caplog.at_level("WARNING", logger="tools.bot_desktop.runtime"):
+        runtime.start()
+    assert not [m for m in (r.getMessage() for r in caplog.records) if "available" in m]
diff --git a/tools/bot_desktop/browser.py b/tools/bot_desktop/browser.py
index fa44c63719..f8e094c68f 100644
--- a/tools/bot_desktop/browser.py
+++ b/tools/bot_desktop/browser.py
@@ -62,9 +62,10 @@ def _playwright_executable() -> Optional[str]:
 
 
 def _is_headless_shell(exe: str) -> bool:
-    """Playwright's ``chrome-headless-shell`` can drive pages but cannot open a window: the official Docker
-    image ships only that build and its boot hook exports it as ``AGENT_BROWSER_EXECUTABLE_PATH``, so
-    trusting the override blindly would pin a windowless binary to the dock's Browser icon."""
+    """Playwright's ``chrome-headless-shell`` can drive pages but cannot open a window. The image's boot
+    hook exports it as ``AGENT_BROWSER_EXECUTABLE_PATH`` (it is the only build the unsuffixed tags carry,
+    and the lighter one everywhere), so trusting that override blindly would pin a windowless binary to
+    the dock's Browser icon."""
     return "headless" in os.path.basename(exe).lower() or "headless_shell" in exe
 
 
@@ -168,9 +169,17 @@ def _pid_alive(pid: int) -> bool:
 
 
 def env_for_agent(env: dict) -> dict:
-    """Pin agent-browser to the screen's browser identity unless the user pinned their own."""
+    """Pin agent-browser to the screen's browser identity unless the user pinned their own.
+
+    A headless-shell pin is replaced, not kept: the image's boot hook exports one for ordinary browsing,
+    and leaving it would put the agent and the dock on different binaries over one ``--user-data-dir``,
+    where Chromium's singleton swallows the dock's launch into the windowless process. Only runs while a
+    screen is up (:func:`runtime.desktop_env`), so the heavier build is pinned just when it is the point.
+    """
     env.setdefault("AGENT_BROWSER_PROFILE", str(profile_dir()))
     exe = executable()
     if exe:
-        env.setdefault("AGENT_BROWSER_EXECUTABLE_PATH", exe)
+        pinned = env.get("AGENT_BROWSER_EXECUTABLE_PATH", "").strip()
+        if not pinned or _is_headless_shell(pinned):
+            env["AGENT_BROWSER_EXECUTABLE_PATH"] = exe
     return env
diff --git a/tools/bot_desktop/resources.py b/tools/bot_desktop/resources.py
index 99f3e93e72..599d878863 100644
--- a/tools/bot_desktop/resources.py
+++ b/tools/bot_desktop/resources.py
@@ -54,14 +54,36 @@ def _meminfo() -> dict[str, int]:
     return out
 
 
+def _stat_value(path: Path, key: str) -> Optional[int]:
+    """One ``<key> <bytes>`` line out of a cgroup ``memory.stat``."""
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            name, _, rest = line.partition(" ")
+            if name == key:
+                return int(rest.strip())
+    except (OSError, ValueError):
+        return None
+    return None
+
+
 def _cgroup_limit_and_usage() -> tuple[Optional[int], Optional[int]]:
+    """The cgroup's limit and its *working set* — usage minus reclaimable page cache.
+
+    ``memory.current`` counts page cache, so a container reads several hundred MB above idle right after a
+    desktop stops with every process gone. Charging that would make the gate tighten over uptime, so we
+    subtract ``inactive_file``, the working-set convention kubelet uses.
+    """
     limit = _read_int(_CGROUP_V2 / "memory.max")
     usage = _read_int(_CGROUP_V2 / "memory.current")
+    cache = _stat_value(_CGROUP_V2 / "memory.stat", "inactive_file")
     if limit is None and usage is None:
         limit = _read_int(_CGROUP_V1 / "memory.limit_in_bytes")
         usage = _read_int(_CGROUP_V1 / "memory.usage_in_bytes")
+        cache = _stat_value(_CGROUP_V1 / "memory.stat", "total_inactive_file")
         if limit is not None and limit >= 1 << 60:  # v1 "unlimited" is a huge sentinel
             limit = None
+    if usage is not None and cache:
+        usage = max(usage - cache, 0)
     return limit, usage
 
 
@@ -79,6 +101,8 @@ def memory_info() -> MemoryInfo:
 
 
 def min_free_mb() -> int:
+    """``bot_desktop.min_free_memory_mb``; 0 disables the gate. A hosted deployment sets it in the
+    instance's config.yaml (or the managed overlay), not an env var."""
     from hermes_cli.config import load_config_readonly
     cfg = load_config_readonly().get("bot_desktop") or {}
     try:
@@ -87,10 +111,18 @@ def min_free_mb() -> int:
         return DEFAULT_MIN_FREE_MB
 
 
-def memory_blocker(info: Optional[MemoryInfo] = None) -> Optional[str]:
+def tight_headroom_mb(floor: Optional[int] = None) -> int:
+    """Above the floor but below this, a start is allowed and logged: the desktop fits, a few browser tabs
+    would not. Derived from the floor so raising the floor cannot silently retire the warning."""
+    floor = min_free_mb() if floor is None else floor
+    return floor + floor // 3
+
+
+def memory_blocker(info: Optional[MemoryInfo] = None, need: Optional[int] = None) -> Optional[str]:
     """Why the screen must not start now, or None. Unknown memory is not a blocker: a host we cannot
-    read is not a host we know to be small."""
-    need = min_free_mb()
+    read is not a host we know to be small. ``need`` lets a caller that also wants
+    :func:`tight_headroom_mb` read the floor once instead of loading the config twice."""
+    need = min_free_mb() if need is None else need
     if need == 0:
         return None
     info = info or memory_info()
diff --git a/tools/bot_desktop/runtime.py b/tools/bot_desktop/runtime.py
index 1af9d16625..f9d5591479 100644
--- a/tools/bot_desktop/runtime.py
+++ b/tools/bot_desktop/runtime.py
@@ -92,8 +92,12 @@ def package_manager() -> Optional[str]:
 
 def install_command() -> Optional[str]:
     """The distro command that installs the Bot Desktop packages, as the human would type it on THIS host:
-    prefixed with ``sudo`` unless Hermes already runs as root (the official Docker image is uid 0 with no
-    sudo binary), so it is both what the pane shows and what :mod:`tools.bot_desktop.install` runs."""
+    prefixed with ``sudo`` unless Hermes already runs as root, so it is both what the pane shows and what
+    :mod:`tools.bot_desktop.install` runs. ``None`` when no package manager is present.
+
+    Not a promise that it can run here: see :func:`installable`. The published Docker image supervises
+    every service under ``s6-setuidgid hermes`` (UID 10000 by default) and ships no ``sudo`` binary, so an
+    install on a hosted instance is impossible no matter what this returns."""
     pm = package_manager()
     if pm is None:
         return None
@@ -110,6 +114,20 @@ def is_root() -> bool:
     return hasattr(os, "geteuid") and os.geteuid() == 0
 
 
+def installable() -> bool:
+    """Whether :func:`install_command` could actually succeed on this host.
+
+    False on an unprivileged process with no ``sudo`` to reach for, which is exactly the published Docker
+    image: services drop to the ``hermes`` user and no ``sudo`` binary is installed. The packages can only
+    arrive in the image there, so :func:`start` says that instead of printing a sudo line the user has no
+    way to run. ``status()`` still reports ``install_command`` for the pane; surfacing this there needs a
+    wire-contract change and is deliberately out of scope.
+    """
+    if package_manager() is None:
+        return False
+    return is_root() or shutil.which("sudo") is not None
+
+
 @dataclass
 class DesktopStatus:
     profile: str
@@ -285,8 +303,9 @@ def _kill_group_then_wait(pgid: Optional[int], pid: int, grace: float = 2.0) ->
     _reap_if_ours()
 
 
-# Host-wide (every profile allocates from one band), so it lives outside any profile home — but not in
-# world-writable /tmp, where a predictable name lets another local user pre-create or squat the file.
+# Host-wide (every profile allocates from one band), so it lives outside any profile home. A predictable
+# name must not be squattable: XDG_RUNTIME_DIR is the boundary — 0700 from logind, or from
+# docker/stage2-hook.sh in containers, which have none.
 _ALLOC_LOCK = Path(os.environ.get("XDG_RUNTIME_DIR") or Path.home() / ".cache") / "hermes-bot-desktop-alloc.lock"
 
 
@@ -475,6 +494,12 @@ def _profile_name() -> str:
         return "default"
 
 
+# The gate lives in ``resources`` so start() and status() cannot disagree about it. Measured in the
+# official image: gateway idle 304 MiB, +216 for Xvnc/Xfce, 1073 MiB with one Chromium page. The OOM
+# killer picks by score, so on a small instance the casualty is the dashboard or the gateway, not the
+# desktop that caused the pressure.
+
+
 def start(*, wait_seconds: float = 15.0) -> DesktopStatus:
     """Start this profile's desktop (idempotent). Blocks until the launcher publishes its env file or
     ``wait_seconds`` pass; raises ``RuntimeError`` naming the blocker.
@@ -488,8 +513,18 @@ def start(*, wait_seconds: float = 15.0) -> DesktopStatus:
         raise RuntimeError("Bot Desktop runs on Linux gateway hosts only")
     missing = missing_binaries()
     if missing:
-        hint = install_command() or "install TigerVNC (Xvnc) and the Xfce core components"
-        raise RuntimeError(f"Bot Desktop needs {', '.join(missing)} on the gateway host. Install: {hint}")
+        # Three dead ends: an operator told "unprivileged, no sudo" while running as root hunts the wrong bug.
+        need = f"Bot Desktop needs {', '.join(missing)} on the gateway host"
+        if package_manager() is None:
+            raise RuntimeError(
+                f"{need}, and no supported package manager (apt/dnf/pacman) is available to install them. "
+                "Install TigerVNC (Xvnc) and the Xfce core components with this distro's own tooling.")
+        if not installable():
+            raise RuntimeError(
+                f"{need}, and this host cannot install them: the process is unprivileged and there is no "
+                "sudo. On the published Docker image the packages have to be baked in, so this needs a "
+                "newer image rather than an install.")
+        raise RuntimeError(f"{need}. Install: {install_command()}")
     sd = state_dir()
     sd.mkdir(parents=True, exist_ok=True)
     os.chmod(sd, 0o700)
@@ -497,8 +532,14 @@ def start(*, wait_seconds: float = 15.0) -> DesktopStatus:
         if _launcher_pid() is not None and published_env().get("DISPLAY"):
             return status()
         from tools.bot_desktop import resources
-        if (blocker := resources.memory_blocker()) is not None:
+        floor = resources.min_free_mb()
+        mem = resources.memory_info()
+        if (blocker := resources.memory_blocker(mem, need=floor)) is not None:
             raise RuntimeError(blocker)
+        if mem.available_mb is not None and mem.available_mb < resources.tight_headroom_mb(floor):
+            logger.warning(
+                "Bot Desktop starting with %d MB available; a browser with a few pages open can use most "
+                "of that.", mem.available_mb)
         if _launcher_pid() is None:
             _reap_orphaned_server(sd)
         _ALLOC_LOCK.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
diff --git a/website/docs/user-guide/features/bot-screen.md b/website/docs/user-guide/features/bot-screen.md
index 52c7962a66..67a0d8f39e 100644
--- a/website/docs/user-guide/features/bot-screen.md
+++ b/website/docs/user-guide/features/bot-screen.md
@@ -76,11 +76,12 @@ reverse proxy's access log may record an already-spent ticket.
   0.5–1 GB (one page: ~550 MB). Plan on **~1.1–1.5 GB per open screen with a
   browser**; the desktop alone is cheap, the browser is the cost. CPU is not a
   constraint (idle desktop ≈ 0.01 core, live streaming ≈ 0.03 core). The packages
-  take ~550 MB of disk on Debian.
+  take ~930 MB of disk on Debian 13.
 
   Before starting a screen, Hermes checks that the host — or its container
   cgroup, whichever is tighter — has `bot_desktop.min_free_memory_mb` free
-  (default 1536). Below that the pane shows why in place of **Start screen** and
+  (default 1536; `0` disables the check). Below that the pane shows why in place
+  of **Start screen** and
   `hermes computer-use screen start` refuses; a screen already running is never
   taken down by this check. A screen nobody uses is stopped after
   `bot_desktop.idle_stop_minutes` (default 30) and comes back on the next use, so
@@ -91,16 +92,27 @@ reverse proxy's access log may record an already-spent ticket.
 ### Baking the packages into a container image
 
 An image for a hosted or unprivileged deployment cannot install anything at run
-time, so build the packages in. The official `Dockerfile` has an opt-in build
-argument:
+time, so the packages have to be built in. CI publishes two variants of every
+version: the unsuffixed tags (`:latest`, `:v*`) without them, and the
+**`-desktop` tags** (`:latest-desktop`, `:v*-desktop`) with them. A hosted
+deployment (Fly Machines, Azure container instances) gets Bot Screen by pulling
+the suffixed tag; a build argument could not reach it anyway, since it never
+runs a build. Nothing in the provisioner selects `-desktop` yet, so a hosted
+instance still comes up slim; pulling the suffixed tag yourself works today.
+
+Build your own only if you want the packages in a custom image. The official
+`Dockerfile` has an opt-in build argument, off by default so a plain
+`docker build .` stays lean:
 
 ```bash
 docker build --build-arg HERMES_BOT_DESKTOP=1 -t hermes-agent:screen .
 ```
 
 It adds TigerVNC, the Xfce components and a headed `chromium` (for the dock's
-Browser icon) as one layer (~550 MB). Nothing starts at boot; an image built this
-way costs no memory until a screen is started.
+Browser icon), plus Playwright's headed Chromium build — about **1.4 GB** of
+image (measured: 4.1 GB without the argument, 5.5 GB with it on arm64), of which
+~930 MB is the apt layer. Nothing starts at boot; an image built this way costs
+no memory until a screen is started.
 
 ## Using it
 

From 65d01a7c22d3c62576bfe5f0fd875cbc9ab42be5 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 19:19:26 -0700
Subject: [PATCH 14/61] test: allowlist installable()'s sudo probe for the
 command-resolution ratchet

installable() asks whether the gateway host can run the package manager at all
(root, or sudo present) so a hosted instance gets 'needs a newer image' instead
of a sudo line it cannot run. The probe is on the control host and never
installs or starts anything.
---
 tests/fixtures/resolution_allowlist.json | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/tests/fixtures/resolution_allowlist.json b/tests/fixtures/resolution_allowlist.json
index 040864f3ce..f310260418 100644
--- a/tests/fixtures/resolution_allowlist.json
+++ b/tests/fixtures/resolution_allowlist.json
@@ -723,5 +723,10 @@
     "path": "tools/bot_desktop/runtime.py",
     "symbol": "package_manager",
     "kind": "bare_which"
+  },
+  {
+    "path": "tools/bot_desktop/runtime.py",
+    "symbol": "installable",
+    "kind": "bare_which"
   }
 ]

From 771eb809c83517ed89fe78381b7001099700aca2 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 20:28:53 -0700
Subject: [PATCH 15/61] fix(tests): stop tui_gateway subagent snapshot fixture
 forking the live-subagent registry

Mechanism: tests/tui_gateway/test_subagent_snapshot.py::runtime reset the
registries with monkeypatch.setattr(delegate_tool_registry, "_active_subagents", {})
(same for _recent_subagents and async_delegation._records). Rebinding the module
attribute forks the registry: tools.delegate_tool_progress binds _active_subagents
BY NAME at import (`from tools.delegate_tool_registry import _active_subagents`),
so once that module is loaded, _ChildProgressRelay._on_tool_started writes
last_tool/tool_count into the ORIGINAL dict while _register_subagent and
subagent.list read the replacement. Run alone, the victim imports
delegate_tool_progress inside the test body, AFTER the patch, so both names point
at the new dict. Any earlier test that imports run_agent (test_auto_continue does)
pre-loads delegate_tool_progress with the original binding, and the projection
reads last_tool=None.

Fix at the seam: the fixture now empties the shared registries in place
(clear() + restore snapshot on teardown), so every by-name alias sees the same dict,
exactly as in production where the dict is never rebound.

Harness-only: production never rebinds these module attributes; a real second
session mutates the one shared dict through the same alias.

Repro (base): python -m pytest -q -p no:cacheprovider \
  tests/tui_gateway/test_auto_continue.py tests/tui_gateway/test_subagent_snapshot.py \
  -k "auto_continue or only_this_sessions"  -> 1 failed (last_tool None == 'read_file')
Fixed: 21 passed; both files whole 27 passed; each file alone green.
---
 tests/tui_gateway/test_subagent_snapshot.py | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/tests/tui_gateway/test_subagent_snapshot.py b/tests/tui_gateway/test_subagent_snapshot.py
index eee4eeff1a..acc8f51827 100644
--- a/tests/tui_gateway/test_subagent_snapshot.py
+++ b/tests/tui_gateway/test_subagent_snapshot.py
@@ -15,15 +15,25 @@ def runtime(monkeypatch):
     transport = SimpleNamespace(write=lambda frame: True)
     owner = {"session_key": "parent", "history": [], "transport": transport}
     monkeypatch.setattr(server, "_sessions", {"ui-owner": owner})
-    monkeypatch.setattr(delegate_tool_registry, "_active_subagents", {})
-    monkeypatch.setattr(delegate_tool_registry, "_recent_subagents", {})
-    monkeypatch.setattr(async_delegation, "_records", {})
+    # Empty the shared registries IN PLACE rather than rebinding the module attributes:
+    # tools.delegate_tool_progress binds ``_active_subagents`` by name at import, so a rebound
+    # registry dict forks the two views whenever that module was imported by an earlier test
+    # (run_agent pulls it in) — the relay then writes last_tool into the orphaned original while
+    # ``_register_subagent`` and ``subagent.list`` use the replacement.
+    registries = (delegate_tool_registry._active_subagents, delegate_tool_registry._recent_subagents,
+                  async_delegation._records)
+    saved = [(reg, dict(reg)) for reg in registries]
+    for reg in registries:
+        reg.clear()
 
     def call(method, *, via=transport, **params):
         return server.dispatch({"id": 1, "method": method,
                                 "params": {"session_id": "ui-owner", **params}}, transport=via)
 
-    return server, owner, transport, call
+    yield server, owner, transport, call
+    for reg, snapshot in saved:
+        reg.clear()
+        reg.update(snapshot)
 
 
 def test_snapshot_projects_only_this_sessions_runtime_records(runtime):

From e7cc3836e156507b42101a6084a46ac4c157b061 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:00:18 -0700
Subject: [PATCH 16/61] fix: TUI auth fallback no longer crashes on `model:
 <id>` config shorthand
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`_resolve_agent_model_runtime` builds the pre-agent fallback notice from
`(_load_cfg().get("model") or {}).get("provider")`. `load_user_config_effective`
keeps the `model: <id>` string shorthand as a string (every other reader —
gateway/run.py, cron/scheduler.py, hermes_cli/main.py — accepts it), so a
primary AuthError on such a config raised `'str' object has no attribute
'get'` inside the fallback branch: `setup.runtime_check` answered ok=False
("'str' object has no attribute 'get'") and `_make_agent` failed, on a
backend whose configured fallback chain was perfectly usable.

Repro: `tests/tui_gateway/test_pre_agent_fallback_notice.py::
test_fallback_build_survives_model_string_shorthand` (red on base).
Surfaced as the cross-file leak `test_protocol.py::test_config_roundtrip`
(writes `model: test/model` into a home left bound on `server._hermes_home`)
→ `test_tui_gateway_server.py::test_setup_runtime_check_agrees_with_
session_fallback_chain`.
---
 .../test_pre_agent_fallback_notice.py         | 26 +++++++++++++++++++
 tui_gateway/server.py                         |  6 +++--
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/tests/tui_gateway/test_pre_agent_fallback_notice.py b/tests/tui_gateway/test_pre_agent_fallback_notice.py
index 3fdcea87a3..f3cdc11544 100644
--- a/tests/tui_gateway/test_pre_agent_fallback_notice.py
+++ b/tests/tui_gateway/test_pre_agent_fallback_notice.py
@@ -45,3 +45,29 @@ def test_primary_build_carries_no_notice(monkeypatch, tmp_path):
     agent = _build(monkeypatch, tmp_path, primary_fails=False)
     assert agent.kwargs["provider"] == "openai-codex"
     assert not hasattr(agent, "_pending_fallback_notice")
+
+
+def test_fallback_build_survives_model_string_shorthand(monkeypatch, tmp_path):
+    """``model: <id>`` (the string shorthand every other reader accepts) must not crash the fallback
+    build while it names the primary in the notice."""
+    from tui_gateway import server
+
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    monkeypatch.setenv("HERMES_IGNORE_RULES", "1")
+    (tmp_path / "config.yaml").write_text("model: gpt-5.6-sol\n", encoding="utf-8")
+    monkeypatch.setattr(server, "_hermes_home", tmp_path)
+    monkeypatch.setattr(server, "_get_db", lambda: None)
+    monkeypatch.setattr(server, "_load_fallback_model",
+                        lambda: [{"provider": "anthropic", "model": "claude-sonnet-5", "api_key": "fb"}])
+
+    def _resolve(**kwargs):
+        if kwargs.get("requested") != "anthropic":
+            raise AuthError("expired")
+        return {"api_key": "k", "base_url": "https://example.invalid/v1",
+                "provider": "anthropic", "api_mode": "chat_completions"}
+
+    with patch("hermes_cli.runtime_provider.resolve_runtime_provider", side_effect=_resolve), \
+         patch("run_agent.AIAgent", _StubAgent):
+        agent = server._make_agent("sid", "key", context_cwd_is_launch_artifact=False)
+    assert (agent.kwargs["provider"], agent.kwargs["model"]) == ("anthropic", "claude-sonnet-5")
+    assert "gpt-5.6-sol" in agent._pending_fallback_notice and "anthropic/claude-sonnet-5" in agent._pending_fallback_notice
diff --git a/tui_gateway/server.py b/tui_gateway/server.py
index 88ae448518..475d106c4a 100644
--- a/tui_gateway/server.py
+++ b/tui_gateway/server.py
@@ -2347,8 +2347,10 @@ def _resolve_agent_model_runtime(model_override, provider_override) -> tuple[str
         # Same pre-agent switch the messaging gateway surfaces (#74349); _make_agent pops it onto the
         # agent's one-shot notice so the TUI/Desktop user sees which provider actually answered.
         from hermes_cli.fallback_config import pre_agent_fallback_notice
-        # requested_provider=None means resolve_runtime_provider read the persisted config provider.
-        primary_provider = requested_provider or (_load_cfg().get("model") or {}).get("provider")
+        # requested_provider=None means resolve_runtime_provider read the persisted config provider;
+        # ``model: <id>`` (string shorthand) names no provider.
+        cfg_model = _load_cfg().get("model")
+        primary_provider = requested_provider or (cfg_model.get("provider") if isinstance(cfg_model, dict) else None)
         resolution.runtime["_fallback_notice"] = pre_agent_fallback_notice(
             primary_provider, model, resolution.runtime.get("provider"), resolution.selected_model)
         return resolution.selected_model, resolution.runtime

From 8ae1dc11a0b0197a057459f21fcbd8d4175acfe7 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:00:18 -0700
Subject: [PATCH 17/61] test: tui_gateway/test_protocol stops leaking
 _hermes_home and a fresh transport module
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two harness leaks, both in tests/tui_gateway/test_protocol.py:

1. `test_config_roundtrip` did `server._hermes_home = tmp_path` by direct
   assignment; the `server` fixture never restores it, so every later
   `_load_cfg()` in the process (any file after it) read that test's
   `model: test/model` config. Victims: `test_setup_runtime_check_agrees_with_
   session_fallback_chain` (fallback branch → product bug, fixed in the
   previous commit) and `test_notification_poller_live_loop_drops_addressed_
   orphan` (the per-turn config sync tried to switch a stub agent to
   `test/model` and emitted `error` events). monkeypatch.setattr restores it.

2. The `server` fixture's `patch.dict(sys.modules)` window drops every module
   FIRST imported inside it; `tui_gateway.transport` was one, so when
   test_protocol ran first in a process, a test's own `from tui_gateway.transport
   import bind_transport` got a fresh module whose ContextVar the server's
   `current_transport()` never read — `client.capabilities` advertised
   `_stdio_transport` instead of the test's WS peer and `send()` failed fast
   (`test_server_request_waits_for_a_ws_client_that_advertised` red alone,
   green after any test that imported transport). Pre-import it like
   server_requests.

Repro (base): `python -m pytest -q -p no:cacheprovider
tests/tui_gateway/test_protocol.py
tests/tui_gateway/test_tui_gateway_server.py::test_setup_runtime_check_agrees_with_session_fallback_chain`
→ 1 failed; `python -m pytest -q tests/tui_gateway/test_protocol.py::
test_server_request_waits_for_a_ws_client_that_advertised` → 1 failed.
---
 tests/tui_gateway/test_protocol.py | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/tests/tui_gateway/test_protocol.py b/tests/tui_gateway/test_protocol.py
index 84cbe7f275..0f95eb1bff 100644
--- a/tests/tui_gateway/test_protocol.py
+++ b/tests/tui_gateway/test_protocol.py
@@ -31,11 +31,14 @@ def server():
     # (a fixed shared path) forever, leaking active-session registry entries
     # across every later test in the process. Scope the patch to the import.
     #
-    # Import server_requests (pure stdlib) BEFORE the window: the patch drops every module first imported
-    # inside it, so otherwise the module server.py binds its sinks on (write/emit/answerable) would vanish
+    # Import server_requests (pure stdlib) and transport BEFORE the window: the patch drops every module first
+    # imported inside it, so otherwise the module server.py binds its sinks on (write/emit/answerable) would vanish
     # from sys.modules and a test's own ``from tui_gateway import server_requests`` would get a fresh,
-    # unbound copy whose default sinks drop frames and treat every client as answerable.
+    # unbound copy whose default sinks drop frames and treat every client as answerable. Likewise a test's
+    # ``from tui_gateway.transport import bind_transport`` would bind a fresh module's ContextVar that the
+    # server's ``current_transport()`` never reads (first-in-process test sees ``_stdio_transport`` as caller).
     import tui_gateway.server_requests  # noqa: F401
+    import tui_gateway.transport  # noqa: F401
     with patch.dict("sys.modules", {
         "hermes_constants": MagicMock(get_hermes_home=MagicMock(return_value="/tmp/hermes_test")),
         "hermes_cli.env_loader": MagicMock(),
@@ -1162,8 +1165,10 @@ def test_make_agent_accepts_list_system_prompt(server, monkeypatch):
 # ── Config I/O ───────────────────────────────────────────────────────
 
 
-def test_config_roundtrip(server, tmp_path):
-    server._hermes_home = tmp_path
+def test_config_roundtrip(server, tmp_path, monkeypatch):
+    # monkeypatch, not assignment: a bare ``server._hermes_home = tmp_path`` outlives this test and every
+    # later ``_load_cfg()`` in the process reads this file's ``model: test/model`` shorthand.
+    monkeypatch.setattr(server, "_hermes_home", tmp_path)
     server._save_cfg({"model": "test/model"})
     assert server._load_cfg()["model"] == "test/model"
 

From 5dbbc9a9c0932835c1aac8a2404acfcb9381db8d Mon Sep 17 00:00:00 2001
From: Gille <4317663+helix4u@users.noreply.github.com>
Date: Wed, 23 Sep 2026 20:11:11 -0600
Subject: [PATCH 18/61] fix(cli): make plugin clone timeout configurable

---
 cli-config.yaml.example                     |  8 ++++
 hermes_cli/config_defaults.py               |  3 ++
 hermes_cli/plugins_cmd.py                   | 28 ++++++++++--
 tests/hermes_cli/test_plugin_install_ref.py | 47 +++++++++++++++++++++
 website/docs/user-guide/features/plugins.md |  4 ++
 5 files changed, 86 insertions(+), 4 deletions(-)

diff --git a/cli-config.yaml.example b/cli-config.yaml.example
index 179a9e5374..58bf136aa7 100644
--- a/cli-config.yaml.example
+++ b/cli-config.yaml.example
@@ -37,6 +37,14 @@ database:
 runtime:
   nofile_soft_limit: 4096
 
+# =============================================================================
+# Plugin Installation
+# =============================================================================
+plugins:
+  # Deadline for each Git clone or pinned-commit fetch. Default: 300 seconds.
+  # Raise this for large repositories or slow connections. Maximum: 3600.
+  clone_timeout_seconds: 300
+
 # =============================================================================
 # Model Configuration
 # =============================================================================
diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.py
index 5ded10e044..1516fad8f9 100644
--- a/hermes_cli/config_defaults.py
+++ b/hermes_cli/config_defaults.py
@@ -1684,6 +1684,9 @@ DEFAULT_CONFIG = {
     # Plugin system. `enabled`/`disabled` lists are written by `hermes plugins enable|disable` and
     # deliberately omitted here so an empty default never clobbers a user allow-list.
     "plugins": {
+        # Deadline (seconds) for one plugin Git clone or pinned-commit fetch. Slow repositories may
+        # need more time; each network operation is capped at one hour.
+        "clone_timeout_seconds": 300,
         # Wall-clock cap (seconds) for one in-process Python plugin hook callback; shell hooks keep
         # their own per-entry `timeout`. 0 = no cap (sync call on agent thread). Max 600.
         "hook_callback_timeout": 30,
diff --git a/hermes_cli/plugins_cmd.py b/hermes_cli/plugins_cmd.py
index 760331751c..4d2dcca78b 100644
--- a/hermes_cli/plugins_cmd.py
+++ b/hermes_cli/plugins_cmd.py
@@ -26,6 +26,8 @@ from hermes_cli.secret_prompt import masked_secret_prompt
 from utils import atomic_write_text, rmtree_readonly
 
 logger = logging.getLogger(__name__)
+_DEFAULT_CLONE_TIMEOUT_SECONDS = 300
+_MAX_CLONE_TIMEOUT_SECONDS = 3600
 
 
 @functools.lru_cache(maxsize=1)
@@ -103,6 +105,19 @@ def _config_value(*keys: str, default: Any) -> Any:
         return default
 
 
+def _clone_timeout_seconds() -> int:
+    """Deadline for plugin clone and pinned fetch, scoped to the active profile."""
+    value = _config_value("plugins", "clone_timeout_seconds", default=_DEFAULT_CLONE_TIMEOUT_SECONDS)
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        logger.warning("plugins.clone_timeout_seconds must be a positive integer; using %ss",
+                       _DEFAULT_CLONE_TIMEOUT_SECONDS)
+        return _DEFAULT_CLONE_TIMEOUT_SECONDS
+    if value > _MAX_CLONE_TIMEOUT_SECONDS:
+        logger.warning("plugins.clone_timeout_seconds exceeds %ss; clamping", _MAX_CLONE_TIMEOUT_SECONDS)
+        return _MAX_CLONE_TIMEOUT_SECONDS
+    return value
+
+
 def _config_name_set(*keys: str) -> set:
     """A list-valued config key as a set (empty on any failure or non-list)."""
     value = _config_value(*keys, default=[])
@@ -597,15 +612,18 @@ def _git_resolve_commit(repo: Path, git_exe: str, revision: str) -> str:
 
 def _checkout_exact_revision(repo: Path, git_exe: str, revision: str, source_url: str = "") -> None:
     """Fetch and detach at one immutable commit, then verify the resulting HEAD."""
+    fetch_timeout = _clone_timeout_seconds()
     for verb, args, failure_prefix in (
         ("fetch", ("fetch", "--depth", "1", "origin", revision), f"Git commit '{revision}' could not be fetched:\n"),
         ("checkout", ("checkout", "--detach", revision), f"Git checkout of commit '{revision}' failed:\n"),
     ):
         try:
             _git_or_raise(git_exe, repo, *args, failure_prefix=failure_prefix, source_url=source_url,
-                          auth_url=source_url if verb == "fetch" else "")
+                          auth_url=source_url if verb == "fetch" else "",
+                          timeout=fetch_timeout if verb == "fetch" else 60)
         except subprocess.TimeoutExpired as exc:
-            raise PluginOperationError(f"Git {verb} of commit '{revision}' timed out after 60 seconds.") from exc
+            timeout = fetch_timeout if verb == "fetch" else 60
+            raise PluginOperationError(f"Git {verb} of commit '{revision}' timed out after {timeout} seconds.") from exc
     actual = _git_head_revision(repo, git_exe)
     if actual != _git_resolve_commit(repo, git_exe, revision):
         raise PluginOperationError(
@@ -666,13 +684,15 @@ def _clone_plugin_repo(tmp_clone: Path, git_url: str, revision: Optional[str]) -
     git_exe = _resolve_git_executable()
     if not git_exe:
         raise PluginOperationError("git is not installed or not in PATH.")
+    clone_timeout = _clone_timeout_seconds()
     clone_args = ["clone", "--depth", "1", *(["--no-checkout"] if revision else []), git_url, str(tmp_clone)]
     try:
-        result = _run_plugin_git(git_exe, tmp_clone.parent, *clone_args, auth_url=git_url)
+        result = _run_plugin_git(git_exe, tmp_clone.parent, *clone_args, auth_url=git_url,
+                                 timeout=clone_timeout)
     except FileNotFoundError as e:
         raise PluginOperationError("git is not installed or not in PATH.") from e
     except subprocess.TimeoutExpired as e:
-        raise PluginOperationError("Git clone timed out after 60 seconds.") from e
+        raise PluginOperationError(f"Git clone timed out after {clone_timeout} seconds.") from e
     if result.returncode != 0:
         raise PluginOperationError(_clone_failure_message(git_url, _safe_git_error(result, git_url)))
     _scrub_cloned_origin(tmp_clone, git_exe, git_url)
diff --git a/tests/hermes_cli/test_plugin_install_ref.py b/tests/hermes_cli/test_plugin_install_ref.py
index 2241959c69..ee58b6520d 100644
--- a/tests/hermes_cli/test_plugin_install_ref.py
+++ b/tests/hermes_cli/test_plugin_install_ref.py
@@ -169,6 +169,53 @@ def test_subdir_pin_records_source_identity_and_installs_requested_tree(
     }
 
 
+def test_clone_timeout_applies_to_real_pinned_subdir_install(monkeypatch, tmp_path):
+    from hermes_cli import plugins_cmd
+
+    repo, old_sha, _new_sha = _plugin_repo(tmp_path)
+    home = tmp_path / "home"
+    home.mkdir()
+    (home / "config.yaml").write_text("plugins:\n  clone_timeout_seconds: 137\n", encoding="utf-8")
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    run_git = plugins_cmd._run_plugin_git
+    calls = []
+
+    def record_git(git_exe, target, *args, **kwargs):
+        calls.append((args[0], kwargs.get("timeout")))
+        return run_git(git_exe, target, *args, **kwargs)
+
+    monkeypatch.setattr(plugins_cmd, "_run_plugin_git", record_git)
+    target, _manifest, _name = plugins_cmd._install_plugin_core(
+        repo.as_uri(), force=False, ref=old_sha
+    )
+
+    assert _git(target, "rev-parse", "HEAD") == old_sha
+    assert ("clone", 137) in calls
+    assert ("fetch", 137) in calls
+    assert ("checkout", 60) in calls
+
+
+def test_clone_timeout_uses_active_profile_and_bounds_invalid_values(monkeypatch, tmp_path):
+    from hermes_cli.plugins_cmd import _clone_timeout_seconds
+
+    home = tmp_path / "home"
+    home.mkdir()
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    config = home / "config.yaml"
+    config.write_text("plugins:\n  clone_timeout_seconds: 137\n", encoding="utf-8")
+    assert _clone_timeout_seconds() == 137
+
+    other = tmp_path / "other"
+    other.mkdir()
+    monkeypatch.setenv("HERMES_HOME", str(other))
+    assert _clone_timeout_seconds() == 300
+    other_config = other / "config.yaml"
+    other_config.write_text("plugins:\n  clone_timeout_seconds: 0\n", encoding="utf-8")
+    assert _clone_timeout_seconds() == 300
+    other_config.write_text("plugins:\n  clone_timeout_seconds: 7200\n", encoding="utf-8")
+    assert _clone_timeout_seconds() == 3600
+
+
 def test_force_reinstall_does_not_drift_pin_without_explicit_new_ref(
     monkeypatch, tmp_path
 ):
diff --git a/website/docs/user-guide/features/plugins.md b/website/docs/user-guide/features/plugins.md
index 1d6a1a49e4..12732262b0 100644
--- a/website/docs/user-guide/features/plugins.md
+++ b/website/docs/user-guide/features/plugins.md
@@ -161,6 +161,10 @@ plugins:
     - disk-cleanup
   disabled:       # optional deny-list — always wins if a name appears in both
     - noisy-plugin
+  # Optional: deadline (seconds) for each Git clone or pinned-commit fetch
+  # during plugin installation, including automatic memory-provider migration.
+  # Default 300; values above 3600 are clamped.
+  clone_timeout_seconds: 300
   # Optional: wall-clock cap (seconds) for timeout-bounded in-process Python
   # plugin hook callbacks (hot-path observers + pre_tool_call). Default 30;
   # set 0 to disable; values above 600 are clamped. Timed-out pre_tool_call

From 72d18ce59fbd1015b8074742426dad96cf687826 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 20:02:40 -0700
Subject: [PATCH 19/61] fix(plugins): subdirectory installs download only that
 folder

A plugin that lives in a monorepo subdirectory (the Hindsight catalog entry:
vectorize-io/hindsight#hindsight-integrations/hermes) was cloned with every
file in the repository even at --depth 1: 170 MB for a 2 MB plugin folder.
On a slow link that exceeds any reasonable deadline, so `hermes update`'s
Hindsight migration failed with "Git clone timed out" every time.

Subdirectory installs now do a blobless clone (--filter=blob:none
--no-checkout) and a sparse checkout of just that folder, written as the
classic info/sparse-checkout file so older Git clients work too. Servers
without partial-clone support ignore the filter and fall back to the old
download.

Because a partial clone downloads file contents at checkout time, the
checkout step (pinned and unpinned) now gets the configured network
deadline and the credential fallback, same as clone and fetch. Every
timeout error names plugins.clone_timeout_seconds so users can find the
knob.

Existing test fakes of _clone_plugin_repo accept the new subdir argument.
---
 cli-config.yaml.example                     |  3 +-
 hermes_cli/config_defaults.py               |  2 +-
 hermes_cli/plugins_cmd.py                   | 50 ++++++++++++++++-----
 tests/hermes_cli/test_plugin_install_ref.py | 38 +++++++++++++++-
 tests/hermes_cli/test_plugins_cmd.py        |  4 +-
 website/docs/user-guide/features/plugins.md |  5 ++-
 6 files changed, 83 insertions(+), 19 deletions(-)

diff --git a/cli-config.yaml.example b/cli-config.yaml.example
index 58bf136aa7..21ff9ea6e4 100644
--- a/cli-config.yaml.example
+++ b/cli-config.yaml.example
@@ -41,7 +41,8 @@ runtime:
 # Plugin Installation
 # =============================================================================
 plugins:
-  # Deadline for each Git clone or pinned-commit fetch. Default: 300 seconds.
+  # Deadline for each Git clone, fetch or checkout during plugin install. Default: 300
+  # seconds. Subdirectory installs download only that folder.
   # Raise this for large repositories or slow connections. Maximum: 3600.
   clone_timeout_seconds: 300
 
diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.py
index 1516fad8f9..cb95e732ae 100644
--- a/hermes_cli/config_defaults.py
+++ b/hermes_cli/config_defaults.py
@@ -1684,7 +1684,7 @@ DEFAULT_CONFIG = {
     # Plugin system. `enabled`/`disabled` lists are written by `hermes plugins enable|disable` and
     # deliberately omitted here so an empty default never clobbers a user allow-list.
     "plugins": {
-        # Deadline (seconds) for one plugin Git clone or pinned-commit fetch. Slow repositories may
+        # Deadline (seconds) for one plugin Git clone, fetch or checkout. Slow repositories may
         # need more time; each network operation is capped at one hour.
         "clone_timeout_seconds": 300,
         # Wall-clock cap (seconds) for one in-process Python plugin hook callback; shell hooks keep
diff --git a/hermes_cli/plugins_cmd.py b/hermes_cli/plugins_cmd.py
index 4d2dcca78b..744ad0bafc 100644
--- a/hermes_cli/plugins_cmd.py
+++ b/hermes_cli/plugins_cmd.py
@@ -28,6 +28,7 @@ from utils import atomic_write_text, rmtree_readonly
 logger = logging.getLogger(__name__)
 _DEFAULT_CLONE_TIMEOUT_SECONDS = 300
 _MAX_CLONE_TIMEOUT_SECONDS = 3600
+_CLONE_TIMEOUT_HINT = "On a slow connection, raise plugins.clone_timeout_seconds in config.yaml."
 
 
 @functools.lru_cache(maxsize=1)
@@ -611,19 +612,19 @@ def _git_resolve_commit(repo: Path, git_exe: str, revision: str) -> str:
 
 
 def _checkout_exact_revision(repo: Path, git_exe: str, revision: str, source_url: str = "") -> None:
-    """Fetch and detach at one immutable commit, then verify the resulting HEAD."""
-    fetch_timeout = _clone_timeout_seconds()
+    """Fetch and detach at one immutable commit, then verify the resulting HEAD. The checkout is
+    a network verb too: in a partial (subdirectory) clone it downloads the file contents."""
+    timeout = _clone_timeout_seconds()
     for verb, args, failure_prefix in (
         ("fetch", ("fetch", "--depth", "1", "origin", revision), f"Git commit '{revision}' could not be fetched:\n"),
         ("checkout", ("checkout", "--detach", revision), f"Git checkout of commit '{revision}' failed:\n"),
     ):
         try:
             _git_or_raise(git_exe, repo, *args, failure_prefix=failure_prefix, source_url=source_url,
-                          auth_url=source_url if verb == "fetch" else "",
-                          timeout=fetch_timeout if verb == "fetch" else 60)
+                          auth_url=source_url, timeout=timeout)
         except subprocess.TimeoutExpired as exc:
-            timeout = fetch_timeout if verb == "fetch" else 60
-            raise PluginOperationError(f"Git {verb} of commit '{revision}' timed out after {timeout} seconds.") from exc
+            raise PluginOperationError(
+                f"Git {verb} of commit '{revision}' timed out after {timeout} seconds. {_CLONE_TIMEOUT_HINT}") from exc
     actual = _git_head_revision(repo, git_exe)
     if actual != _git_resolve_commit(repo, git_exe, revision):
         raise PluginOperationError(
@@ -678,26 +679,53 @@ def _check_manifest_version(manifest: dict, plugin_name: str) -> None:
         ) from None
 
 
-def _clone_plugin_repo(tmp_clone: Path, git_url: str, revision: Optional[str]) -> str:
+def _restrict_checkout_to_subdir(repo: Path, git_exe: str, subdir: str) -> None:
+    """Sparse-check-out only *subdir*. Written as the classic ``info/sparse-checkout`` file
+    rather than ``git sparse-checkout set`` so older Git clients work too."""
+    _git_or_raise(git_exe, repo, "config", "core.sparseCheckout", "true", timeout=15,
+                  failure_prefix="Could not enable sparse checkout:\n")
+    pattern_file = repo / ".git" / "info" / "sparse-checkout"
+    pattern_file.parent.mkdir(parents=True, exist_ok=True)
+    escaped = re.sub(r"([\\*?\[])", r"\\\1", subdir.strip("/"))
+    pattern_file.write_text(f"/{escaped}/\n", encoding="utf-8")
+
+
+def _clone_plugin_repo(tmp_clone: Path, git_url: str, revision: Optional[str],
+                       subdir: Optional[str] = None) -> str:
     """Shallow-clone *git_url* into *tmp_clone* (detached at *revision* when given), scrub any
-    credentials from the recorded origin, and return the installed HEAD SHA."""
+    credentials from the recorded origin, and return the installed HEAD SHA.
+
+    A *subdir* install is a blobless clone with a sparse checkout of that subdirectory: a plugin
+    living in a monorepo (Hindsight: 170 MB at depth 1, 2 MB for its plugin folder) otherwise
+    downloads every file in the repository, which times out on slow connections."""
     git_exe = _resolve_git_executable()
     if not git_exe:
         raise PluginOperationError("git is not installed or not in PATH.")
     clone_timeout = _clone_timeout_seconds()
-    clone_args = ["clone", "--depth", "1", *(["--no-checkout"] if revision else []), git_url, str(tmp_clone)]
+    partial = ["--filter=blob:none"] if subdir else []
+    no_checkout = ["--no-checkout"] if revision or subdir else []
+    clone_args = ["clone", "--depth", "1", *partial, *no_checkout, git_url, str(tmp_clone)]
     try:
         result = _run_plugin_git(git_exe, tmp_clone.parent, *clone_args, auth_url=git_url,
                                  timeout=clone_timeout)
     except FileNotFoundError as e:
         raise PluginOperationError("git is not installed or not in PATH.") from e
     except subprocess.TimeoutExpired as e:
-        raise PluginOperationError(f"Git clone timed out after {clone_timeout} seconds.") from e
+        raise PluginOperationError(f"Git clone timed out after {clone_timeout} seconds. {_CLONE_TIMEOUT_HINT}") from e
     if result.returncode != 0:
         raise PluginOperationError(_clone_failure_message(git_url, _safe_git_error(result, git_url)))
     _scrub_cloned_origin(tmp_clone, git_exe, git_url)
+    if subdir:
+        _restrict_checkout_to_subdir(tmp_clone, git_exe, subdir)
     if revision:
         _checkout_exact_revision(tmp_clone, git_exe, revision, source_url=git_url)
+    elif subdir:
+        try:
+            _git_or_raise(git_exe, tmp_clone, "checkout", "HEAD", timeout=clone_timeout, source_url=git_url,
+                          auth_url=git_url, failure_prefix="Git checkout of the plugin subdirectory failed:\n")
+        except subprocess.TimeoutExpired as e:
+            raise PluginOperationError(
+                f"Git checkout timed out after {clone_timeout} seconds. {_CLONE_TIMEOUT_HINT}") from e
     return _git_head_revision(tmp_clone, git_exe)
 
 
@@ -835,7 +863,7 @@ def _install_plugin_core(
 
     with tempfile.TemporaryDirectory(prefix=".install-", dir=plugins_dir) as tmp:
         tmp_clone = Path(tmp) / "plugin"
-        installed_revision = _clone_plugin_repo(tmp_clone, git_url, requested_revision)
+        installed_revision = _clone_plugin_repo(tmp_clone, git_url, requested_revision, subdir)
         git_exe = _resolve_git_executable()
         at_reviewed_pin = bool(reviewed_pin) and installed_revision == (
             _git_resolve_commit(tmp_clone, git_exe, reviewed_pin) if git_exe and reviewed_pin else reviewed_pin)
diff --git a/tests/hermes_cli/test_plugin_install_ref.py b/tests/hermes_cli/test_plugin_install_ref.py
index ee58b6520d..a02a7e78b2 100644
--- a/tests/hermes_cli/test_plugin_install_ref.py
+++ b/tests/hermes_cli/test_plugin_install_ref.py
@@ -169,7 +169,7 @@ def test_subdir_pin_records_source_identity_and_installs_requested_tree(
     }
 
 
-def test_clone_timeout_applies_to_real_pinned_subdir_install(monkeypatch, tmp_path):
+def test_clone_timeout_applies_to_every_network_step_of_a_pinned_install(monkeypatch, tmp_path):
     from hermes_cli import plugins_cmd
 
     repo, old_sha, _new_sha = _plugin_repo(tmp_path)
@@ -192,7 +192,41 @@ def test_clone_timeout_applies_to_real_pinned_subdir_install(monkeypatch, tmp_pa
     assert _git(target, "rev-parse", "HEAD") == old_sha
     assert ("clone", 137) in calls
     assert ("fetch", 137) in calls
-    assert ("checkout", 60) in calls
+    assert ("checkout", 137) in calls
+
+
+@pytest.mark.parametrize("pinned", [False, True])
+def test_subdir_install_downloads_only_that_subdirectory(monkeypatch, tmp_path, pinned):
+    from hermes_cli.plugins_cmd import _install_plugin_core
+
+    repo = tmp_path / "monorepo"
+    plugin = repo / "integrations" / "hermes"
+    plugin.mkdir(parents=True)
+    _git(repo, "init", "-q")
+    _git(repo, "config", "user.email", "fixture@example.com")
+    _git(repo, "config", "user.name", "Fixture")
+    _git(repo, "config", "uploadpack.allowFilter", "true")
+    (plugin / "plugin.yaml").write_text("name: nested-demo\n", encoding="utf-8")
+    (repo / "unrelated.bin").write_bytes(b"x" * 4096)
+    _git(repo, "add", ".")
+    _git(repo, "commit", "-qm", "init")
+    sha = _git(repo, "rev-parse", "HEAD")
+    unrelated_blob = _git(repo, "rev-parse", "HEAD:unrelated.bin")
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path / "home"))
+    seen = {}
+
+    def inspect_clone(_manifest, tree):
+        clone = tree.parents[1]
+        seen["worktree"] = sorted(p.name for p in clone.iterdir() if p.name != ".git")
+        seen["missing"] = _git(clone, "rev-list", "--objects", "--missing=print", "HEAD")
+
+    target, _manifest, _name = _install_plugin_core(
+        f"{repo.as_uri()}#integrations/hermes", force=False,
+        ref=sha if pinned else None, before_swap=inspect_clone)
+
+    assert (target / "plugin.yaml").is_file()
+    assert seen["worktree"] == ["integrations"]
+    assert f"?{unrelated_blob}" in seen["missing"].splitlines()
 
 
 def test_clone_timeout_uses_active_profile_and_bounds_invalid_values(monkeypatch, tmp_path):
diff --git a/tests/hermes_cli/test_plugins_cmd.py b/tests/hermes_cli/test_plugins_cmd.py
index 6d96be902c..b024c722c9 100644
--- a/tests/hermes_cli/test_plugins_cmd.py
+++ b/tests/hermes_cli/test_plugins_cmd.py
@@ -765,7 +765,7 @@ class TestReviewedPinScanTrust:
     SHA = "a" * 40
 
     def _fake_clone(self, pc, monkeypatch, plugins_dir, extra_file, body):
-        def fake_clone(tmp_clone, git_url, revision):
+        def fake_clone(tmp_clone, git_url, revision, subdir=None):
             tmp_clone.mkdir()
             (tmp_clone / "plugin.yaml").write_text("name: scanme\nmanifest_version: 1\n", encoding="utf-8")
             (tmp_clone / extra_file).write_text(body, encoding="utf-8")
@@ -807,7 +807,7 @@ class TestInstallReadabilityGate:
     def _clone_with_unreadable_manifest(self, monkeypatch, pc):
         real_chmod = os.chmod  # the rollback test replaces os.chmod after this fixture runs
 
-        def fake_clone(tmp_clone, git_url, revision):
+        def fake_clone(tmp_clone, git_url, revision, subdir=None):
             tmp_clone.mkdir()
             (tmp_clone / "plugin.yaml").write_text("name: badperm\nmanifest_version: 1\n", encoding="utf-8")
             real_chmod(tmp_clone / "plugin.yaml", 0)
diff --git a/website/docs/user-guide/features/plugins.md b/website/docs/user-guide/features/plugins.md
index 12732262b0..1fa3b52fd7 100644
--- a/website/docs/user-guide/features/plugins.md
+++ b/website/docs/user-guide/features/plugins.md
@@ -161,9 +161,10 @@ plugins:
     - disk-cleanup
   disabled:       # optional deny-list — always wins if a name appears in both
     - noisy-plugin
-  # Optional: deadline (seconds) for each Git clone or pinned-commit fetch
+  # Optional: deadline (seconds) for each Git clone, fetch or checkout
   # during plugin installation, including automatic memory-provider migration.
-  # Default 300; values above 3600 are clamped.
+  # Default 300; values above 3600 are clamped. A subdirectory install
+  # (owner/repo/path/to/plugin) downloads only that folder's files.
   clone_timeout_seconds: 300
   # Optional: wall-clock cap (seconds) for timeout-bounded in-process Python
   # plugin hook callbacks (hot-path observers + pre_tool_call). Default 30;

From d188a47e9a47cad78d27bbe42706c4d468a9251d Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 20:11:27 -0700
Subject: [PATCH 20/61] fix(desktop): plugin probe/install from a repo
 subfolder downloads only that folder

Desktop's own Git plugin probe and install (cloneToTemp) had the same
full-tree clone and a hard-coded 60 s deadline, so pasting
vectorize-io/hindsight/hindsight-integrations/hermes into Desktop failed
exactly like the CLI did. A subdirectory identifier now takes the same
blobless clone + sparse checkout of that folder, and the Git deadline
matches the backend default of 300 s. The timeout message names the Git
verb that actually ran.
---
 .../electron/desktop-plugin-install.test.ts   | 33 ++++++++++++++-
 .../electron/desktop-plugin-install.ts        | 41 +++++++++++++++----
 2 files changed, 65 insertions(+), 9 deletions(-)

diff --git a/apps/desktop/electron/desktop-plugin-install.test.ts b/apps/desktop/electron/desktop-plugin-install.test.ts
index f455cc9826..4aefbccd80 100644
--- a/apps/desktop/electron/desktop-plugin-install.test.ts
+++ b/apps/desktop/electron/desktop-plugin-install.test.ts
@@ -1,7 +1,8 @@
+import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 import { afterEach, describe, expect, it } from 'vitest'
 
@@ -9,6 +10,7 @@ import {
   desktopPluginFolderName,
   detectPluginComponents,
   findDesktopEntry,
+  probePluginRepo,
   resolvePluginGitUrl,
   resolveSubdirWithin
 } from './desktop-plugin-install'
@@ -119,3 +121,32 @@ describe('detectPluginComponents', () => {
     })
   })
 })
+
+describe('probePluginRepo', () => {
+  const roots: string[] = []
+
+  afterEach(() => {
+    for (const root of roots.splice(0)) {
+      fs.rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('probes a monorepo subdirectory through the sparse partial clone', async () => {
+    const repo = mkdtemp('hermes-plugin-monorepo-')
+    roots.push(repo)
+    const git = (...args: string[]) => execFileSync('git', args, { cwd: repo, stdio: 'pipe' })
+    const plugin = path.join(repo, 'integrations', 'hermes')
+    fs.mkdirSync(plugin, { recursive: true })
+    fs.writeFileSync(path.join(plugin, 'plugin.yaml'), 'name: nested-agent\n')
+    fs.writeFileSync(path.join(plugin, '__init__.py'), 'def register(ctx): pass\n')
+    fs.writeFileSync(path.join(repo, 'unrelated.bin'), 'x'.repeat(4096))
+    git('init', '-q')
+    git('config', 'uploadpack.allowFilter', 'true')
+    git('add', '.')
+    git('-c', 'user.email=fixture@example.com', '-c', 'user.name=Fixture', 'commit', '-qm', 'init')
+
+    const result = await probePluginRepo('git', `${pathToFileURL(repo).href}#integrations/hermes`)
+
+    expect(result).toMatchObject({ ok: true, agent: true, agentName: 'nested-agent' })
+  })
+})
diff --git a/apps/desktop/electron/desktop-plugin-install.ts b/apps/desktop/electron/desktop-plugin-install.ts
index d34cea1c37..abdc538bf5 100644
--- a/apps/desktop/electron/desktop-plugin-install.ts
+++ b/apps/desktop/electron/desktop-plugin-install.ts
@@ -262,6 +262,9 @@ function noninteractiveGitEnv(): NodeJS.ProcessEnv {
   }
 }
 
+// Matches the backend's default `plugins.clone_timeout_seconds`.
+const GIT_TIMEOUT_MS = 300_000
+
 function runGit(gitBin: string, args: string[], cwd?: string): Promise<{ code: number; stderr: string }> {
   return new Promise((resolve, reject) => {
     const child = spawn(gitBin, args, {
@@ -275,8 +278,8 @@ function runGit(gitBin: string, args: string[], cwd?: string): Promise<{ code: n
 
     const timer = setTimeout(() => {
       child.kill('SIGKILL')
-      reject(new Error('Git clone timed out after 60 seconds.'))
-    }, 60_000)
+      reject(new Error(`Git ${args[0]} timed out after ${GIT_TIMEOUT_MS / 1000} seconds.`))
+    }, GIT_TIMEOUT_MS)
 
     child.stderr?.on('data', chunk => {
       stderr += String(chunk)
@@ -294,16 +297,38 @@ function runGit(gitBin: string, args: string[], cwd?: string): Promise<{ code: n
   })
 }
 
-async function cloneToTemp(gitBin: string, gitUrl: string): Promise<string> {
+async function runGitOrThrow(gitBin: string, args: string[], cwd?: string): Promise<void> {
+  const { code, stderr } = await runGit(gitBin, args, cwd)
+
+  if (code !== 0) {
+    throw new Error(`Git ${args[0]} failed:\n${stderr.trim()}`)
+  }
+}
+
+/** Sparse-check-out only `subdir` via the classic pattern file, which older Git clients understand. */
+function sparseCheckoutPattern(subdir: string): string {
+  return `/${subdir.replace(/^\/+|\/+$/g, '').replace(/([\\*?[])/g, '\\$1')}/\n`
+}
+
+// A subdirectory install is a blobless clone with a sparse checkout of that folder: a plugin inside
+// a monorepo (Hindsight: 170 MB at depth 1, 2 MB for its plugin folder) otherwise downloads every
+// file in the repository and times out on slow connections.
+async function cloneToTemp(gitBin: string, gitUrl: string, subdir: string | null): Promise<string> {
   const tmpRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'hermes-plugin-'))
 
   try {
-    const { code, stderr } = await runGit(gitBin, ['clone', '--depth', '1', gitUrl, tmpRoot])
+    if (!subdir) {
+      await runGitOrThrow(gitBin, ['clone', '--depth', '1', gitUrl, tmpRoot])
 
-    if (code !== 0) {
-      throw new Error(`Git clone failed:\n${stderr.trim()}`)
+      return tmpRoot
     }
 
+    await runGitOrThrow(gitBin, ['clone', '--depth', '1', '--filter=blob:none', '--no-checkout', gitUrl, tmpRoot])
+    await runGitOrThrow(gitBin, ['config', 'core.sparseCheckout', 'true'], tmpRoot)
+    await fsp.mkdir(path.join(tmpRoot, '.git', 'info'), { recursive: true })
+    await fsp.writeFile(path.join(tmpRoot, '.git', 'info', 'sparse-checkout'), sparseCheckoutPattern(subdir), 'utf8')
+    await runGitOrThrow(gitBin, ['checkout', 'HEAD'], tmpRoot)
+
     return tmpRoot
   } catch (err) {
     await fsp.rm(tmpRoot, { recursive: true, force: true }).catch(() => undefined)
@@ -340,7 +365,7 @@ export async function probePluginRepo(gitBin: string, identifier: string): Promi
   try {
     const { gitUrl, subdir } = resolvePluginGitUrl(identifier)
     const { warnings, insecure } = insecureSchemeWarnings(gitUrl)
-    const cloneRoot = await cloneToTemp(gitBin, gitUrl)
+    const cloneRoot = await cloneToTemp(gitBin, gitUrl, subdir)
 
     try {
       const pluginRoot = await resolvePluginRoot(cloneRoot, subdir)
@@ -390,7 +415,7 @@ export async function installDesktopPluginFromGit(
 ): Promise<DesktopPluginInstallResult> {
   try {
     const { gitUrl, subdir } = resolvePluginGitUrl(identifier)
-    const cloneRoot = await cloneToTemp(gitBin, gitUrl)
+    const cloneRoot = await cloneToTemp(gitBin, gitUrl, subdir)
 
     try {
       const pluginRoot = await resolvePluginRoot(cloneRoot, subdir)

From 11b0bccf845cfef9958464b761b6415d3ca84452 Mon Sep 17 00:00:00 2001
From: brooklyn! <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 23 Sep 2026 23:43:32 -0500
Subject: [PATCH 21/61] feat(desktop): index every hand-built settings row in
 the command palette

Only Appearance rows were searchable; ~20 preference rows across Advanced,
Chat, Keyboard, Notifications, Archived Chats, Gateways and About had no
palette entry at all (Keep Awake, Disable F12, pool limits, Quick Entry,
attachment limit, Chat/Terminal Font, every notification toggle, Completion
Sound, Auto-archive, gateway mode/keychain/diagnostics, Automatic updates).

One manifest (`settings-manifest.ts`) now owns every hand-built row's id,
subpage, copy, keywords and platform availability. Row element ids, deep-link
routing (`?setting=<view>.<key>`) and the palette catalog all derive from it,
and a contract test walks the whole manifest: each row routes to a real
subpage, resolves copy in every locale, and reaches the palette.

`useSettingDeepLink(view, show)` replaces the per-page highlight hooks; the
HUD modifier special case folds into the manifest as `keybinds.hud-modifier`.
---
 .../desktop/src/app/command-palette/index.tsx |   4 +-
 .../src/app/settings/about-settings.tsx       |   5 +
 .../src/app/settings/appearance-settings.tsx  |  75 ++--
 .../src/app/settings/appearance-subpages.ts   | 178 ----------
 .../src/app/settings/config-settings.tsx      |   7 +
 .../src/app/settings/gateway-settings.tsx     |   8 +-
 .../app/settings/hud-modifier-settings.tsx    |   8 +-
 .../src/app/settings/keybind-settings.tsx     |   3 +
 .../app/settings/notifications-settings.tsx   |   7 +
 .../src/app/settings/pool-limits-setting.tsx  |   3 +
 .../src/app/settings/quick-entry-settings.tsx |   3 +
 .../src/app/settings/screenshot-settings.tsx  |   2 +
 .../src/app/settings/sessions-settings.tsx    |   5 +
 .../src/app/settings/settings-manifest.ts     | 328 ++++++++++++++++++
 .../desktop/src/app/settings/subpages.test.ts |  75 ++--
 apps/desktop/src/app/settings/subpages.ts     |  11 +-
 .../src/app/settings/use-setting-deep-link.ts |  24 ++
 .../src/app/settings/use-settings-search.ts   |  64 ++--
 18 files changed, 508 insertions(+), 302 deletions(-)
 create mode 100644 apps/desktop/src/app/settings/settings-manifest.ts
 create mode 100644 apps/desktop/src/app/settings/use-setting-deep-link.ts

diff --git a/apps/desktop/src/app/command-palette/index.tsx b/apps/desktop/src/app/command-palette/index.tsx
index 695b1c8975..3e5873b8d8 100644
--- a/apps/desktop/src/app/command-palette/index.tsx
+++ b/apps/desktop/src/app/command-palette/index.tsx
@@ -1245,7 +1245,7 @@ function CommandPaletteBody({ onExited }: { onExited: () => void }) {
 
     const fieldItems = [
       ...settingsCatalog.subpageEntries,
-      ...settingsCatalog.appearanceEntries,
+      ...settingsCatalog.settingEntries,
       ...settingsCatalog.configEntries
     ].map(settingsEntryItem)
 
@@ -1366,7 +1366,7 @@ function CommandPaletteBody({ onExited }: { onExited: () => void }) {
         heading: cc.settingsFields,
         items: [
           ...settingsCatalog.subpageEntries,
-          ...settingsCatalog.appearanceEntries,
+          ...settingsCatalog.settingEntries,
           ...settingsCatalog.configEntries
         ].map(settingsEntryItem)
       })
diff --git a/apps/desktop/src/app/settings/about-settings.tsx b/apps/desktop/src/app/settings/about-settings.tsx
index fda946eaa2..1194750651 100644
--- a/apps/desktop/src/app/settings/about-settings.tsx
+++ b/apps/desktop/src/app/settings/about-settings.tsx
@@ -19,7 +19,9 @@ import {
 } from '@/store/updates'
 
 import { ListRow, SectionHeading, SettingsContent } from './primitives'
+import { SETTING_IDS, settingElementId } from './settings-manifest'
 import { UninstallSection } from './uninstall-section'
+import { useSettingDeepLink } from './use-setting-deep-link'
 
 const RELEASE_NOTES_URL = 'https://github.com/NousResearch/hermes-agent/releases'
 const INSTALLER_URL = 'https://hermes-agent.nousresearch.com/'
@@ -51,6 +53,8 @@ interface AboutSettingsProps {
 }
 
 export function AboutSettings({ subpage }: AboutSettingsProps = {}) {
+  useSettingDeepLink('about', page => subpage === undefined || page === subpage)
+
   if (subpage === 'uninstall') {
     return (
       <SettingsContent>
@@ -243,6 +247,7 @@ function AppUpdatesSettings({ includeUninstall }: { includeUninstall: boolean })
         <ListRow
           description={a.automaticUpdatesDesc}
           hint={a.branchCommit(status?.branch ?? 'unknown', status?.currentSha?.slice(0, 7) ?? 'unknown')}
+          id={settingElementId(SETTING_IDS.about.automaticUpdates)}
           title={a.automaticUpdates}
         />
 
diff --git a/apps/desktop/src/app/settings/appearance-settings.tsx b/apps/desktop/src/app/settings/appearance-settings.tsx
index 837cc46b54..c7f8a53f57 100644
--- a/apps/desktop/src/app/settings/appearance-settings.tsx
+++ b/apps/desktop/src/app/settings/appearance-settings.tsx
@@ -73,15 +73,16 @@ import { $marketplaceInstalls, isUserTheme, removeUserTheme } from '@/themes/use
 
 import { setHermesConfigCache, useHermesConfigRecord } from '../hooks/use-config-record'
 
-import { APPEARANCE_SETTING_IDS, appearanceSubpageForSetting, type AppearanceSubpageId } from './appearance-subpages'
+import type { AppearanceSubpageId } from './appearance-subpages'
 import { ChatFontSetting } from './chat-font-setting'
 import { MODE_OPTIONS } from './constants'
 import { setNested } from './helpers'
 import { MinimizeToTraySetting } from './minimize-to-tray-setting'
 import { PetSettings } from './pet-settings'
 import { ListRow, RowFootnoteAction, SectionHeading, SettingsContent, ToggleRow } from './primitives'
+import { SETTING_IDS, settingElementId } from './settings-manifest'
 import { TerminalFontSetting } from './terminal-font-setting'
-import { useDeepLinkHighlight } from './use-deep-link-highlight'
+import { useSettingDeepLink } from './use-setting-deep-link'
 
 // display.resume_last_session lives in the backend config record (shared with
 // config.yaml and the cold-start restore in use-desktop-integrations), not a
@@ -121,7 +122,7 @@ function ResumeLastSessionSetting() {
       checked={checked}
       description={a.resumeLastSessionDesc}
       disabled={!config}
-      id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.resumeLastSession)}
+      id={settingElementId(ids.resumeLastSession)}
       label={a.resumeLastSessionTitle}
       onChange={update}
     />
@@ -171,8 +172,7 @@ function ThemePreview({ name, mode }: { name: string; mode: 'light' | 'dark' })
 // presets highlights nothing, and the row description keeps showing the
 // exact current percent.
 const UI_SCALE_PRESETS = ['90', '100', '110', '125', '150', '175'] as const
-const appearanceSettingElementId = (id: string) => `setting-field-${id}`
-
+const ids = SETTING_IDS.appearance
 type UiScalePreset = (typeof UI_SCALE_PRESETS)[number]
 
 function matchUiScalePreset(percent: number): UiScalePreset | null {
@@ -468,15 +468,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
   const [query, setQuery] = useState('')
   const show = (id: AppearanceSubpageId) => subpage === undefined || subpage === id
 
-  useDeepLinkHighlight({
-    elementId: appearanceSettingElementId,
-    param: 'setting',
-    ready: id => {
-      const targetSubpage = appearanceSubpageForSetting(id)
-
-      return targetSubpage !== undefined && show(targetSubpage)
-    }
-  })
+  useSettingDeepLink('config:appearance', page => page !== undefined && show(page as AppearanceSubpageId))
 
   // 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…"
@@ -570,7 +562,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
             <ListRow
               action={<LanguageSwitcher />}
               description={isSavingLocale ? t.language.saving : t.language.description}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.language)}
+              id={settingElementId(ids.language)}
               title={t.language.label}
             />
           )}
@@ -667,7 +659,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                 </>
               }
               description={a.themeDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.theme)}
+              id={settingElementId(ids.theme)}
               title={a.themeTitle}
               wide
             />
@@ -687,15 +679,15 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                   />
                 }
                 description={a.uiScaleDesc(zoomPercent)}
-                id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.uiScale)}
+                id={settingElementId(ids.uiScale)}
                 title={a.uiScaleTitle}
               />
 
-              <div id={appearanceSettingElementId('desktop.font_family')}>
+              <div id={settingElementId(ids.chatFont)}>
                 <ChatFontSetting />
               </div>
 
-              <div id={appearanceSettingElementId('terminal.font_family')}>
+              <div id={settingElementId(ids.terminalFont)}>
                 <TerminalFontSetting />
               </div>
             </>
@@ -714,7 +706,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                 />
               }
               description={t.interfaceMode.hint}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.interfaceMode)}
+              id={settingElementId(ids.interfaceMode)}
               title={t.interfaceMode.title}
             />
           )}
@@ -732,7 +724,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                 />
               }
               description={a.sessionDensityDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.sessionDensity)}
+              id={settingElementId(ids.sessionDensity)}
               title={a.sessionDensityTitle}
             />
           )}
@@ -750,7 +742,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                 />
               }
               description={a.tabStripDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.tabStrip)}
+              id={settingElementId(ids.tabStrip)}
               title={a.tabStripTitle}
             />
           )}
@@ -768,13 +760,13 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                 />
               }
               description={a.appActionsDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.appActions)}
+              id={settingElementId(ids.appActions)}
               title={a.appActionsTitle}
             />
           )}
 
           {show('window-layout') && (
-            <div id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.minimizeToTray)}>
+            <div id={settingElementId(ids.minimizeToTray)}>
               <MinimizeToTraySetting />
             </div>
           )}
@@ -858,7 +850,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                 ) : undefined
               }
               description={glassMode ? a.translucencyGlassDesc : a.translucencyDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.translucency)}
+              id={settingElementId(ids.translucency)}
               title={a.translucencyTitle}
             />
           )}
@@ -878,7 +870,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                 </div>
               }
               description={a.userBubbleDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.userBubble)}
+              id={settingElementId(ids.userBubble)}
               title={a.userBubbleTitle}
             />
           )}
@@ -896,7 +888,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                 />
               }
               description={a.textDirectionDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.textDirection)}
+              id={settingElementId(ids.textDirection)}
               title={a.textDirectionTitle}
             />
           )}
@@ -905,7 +897,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
             <ToggleRow
               checked={backdrop}
               description={a.backdropDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.backdrop)}
+              id={settingElementId(ids.backdrop)}
               label={a.backdropTitle}
               onChange={setBackdrop}
             />
@@ -915,7 +907,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
             <ToggleRow
               checked={hideThreadTimeline}
               description={a.hideThreadTimelineDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.hideThreadTimeline)}
+              id={settingElementId(ids.hideThreadTimeline)}
               label={a.hideThreadTimelineTitle}
               onChange={setHideThreadTimeline}
             />
@@ -925,7 +917,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
             <ToggleRow
               checked={introSplash}
               description={a.introSplashDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.introSplash)}
+              id={settingElementId(ids.introSplash)}
               label={a.introSplashTitle}
               onChange={setIntroSplash}
             />
@@ -935,7 +927,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
             <ToggleRow
               checked={composerPopoutGesturesEnabled}
               description={a.composerPopoutDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.composerPopout)}
+              id={settingElementId(ids.composerPopout)}
               label={a.composerPopoutTitle}
               onChange={setComposerPopoutGesturesEnabled}
             />
@@ -947,7 +939,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
             <ToggleRow
               checked={reactionsEnabled}
               description={a.reactionsDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.reactions)}
+              id={settingElementId(ids.reactions)}
               label={a.reactionsTitle}
               onChange={setReactionsEnabled}
             />
@@ -962,7 +954,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
               }
               checked={tipsEnabled}
               description={a.tipsDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.tips)}
+              id={settingElementId(ids.tips)}
               label={a.tipsTitle}
               onChange={setTipsEnabled}
             />
@@ -972,7 +964,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
             <ToggleRow
               checked={toursEnabled}
               description={a.toursDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.tours)}
+              id={settingElementId(ids.tours)}
               label={a.toursTitle}
               onChange={setToursEnabled}
             />
@@ -982,7 +974,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
             <ToggleRow
               checked={vibeHeartsEnabled}
               description={a.vibeHeartsDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.vibeHearts)}
+              id={settingElementId(ids.vibeHearts)}
               label={a.vibeHeartsTitle}
               onChange={setVibeHeartsEnabled}
             />
@@ -1001,7 +993,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                 />
               }
               description={withModeNote(a.toolViewDesc, toolViewShadowed)}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.toolView)}
+              id={settingElementId(ids.toolView)}
               title={a.toolViewTitle}
             />
           )}
@@ -1010,7 +1002,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
             <ToggleRow
               checked={hideCodeDiffs}
               description={withModeNote(a.hideCodeDiffsDesc, hideCodeDiffsShadowed)}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.hideCodeDiffs)}
+              id={settingElementId(ids.hideCodeDiffs)}
               label={a.hideCodeDiffsTitle}
               onChange={setHideCodeDiffs}
             />
@@ -1020,7 +1012,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
             <ToggleRow
               checked={reasoningCollapsedByDefault}
               description={withModeNote(a.reasoningCollapsedDesc, reasoningCollapsedShadowed)}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.reasoningCollapsed)}
+              id={settingElementId(ids.reasoningCollapsed)}
               label={a.reasoningCollapsedTitle}
               onChange={setReasoningCollapsedByDefault}
             />
@@ -1046,7 +1038,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
                 )
               }
               description={a.embedsDesc}
-              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.embeds)}
+              id={settingElementId(ids.embeds)}
               title={a.embedsTitle}
             />
           )}
@@ -1054,10 +1046,7 @@ export function AppearanceSettings({ subpage }: AppearanceSettingsProps = {}) {
       </div>
 
       {show('pet') && (
-        <div
-          className={subpage === undefined ? 'mt-6' : undefined}
-          id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.pet)}
-        >
+        <div className={subpage === undefined ? 'mt-6' : undefined} id={settingElementId(ids.pet)}>
           <PetSettings />
         </div>
       )}
diff --git a/apps/desktop/src/app/settings/appearance-subpages.ts b/apps/desktop/src/app/settings/appearance-subpages.ts
index 390f41bd75..6d8c1b48b9 100644
--- a/apps/desktop/src/app/settings/appearance-subpages.ts
+++ b/apps/desktop/src/app/settings/appearance-subpages.ts
@@ -1,6 +1,3 @@
-import type { Translations } from '@/i18n'
-import { TRANSLUCENCY_SUPPORTED } from '@/store/translucency'
-
 export const APPEARANCE_SUBPAGES = [
   { id: 'general', labelKey: 'appearanceGeneral' },
   { id: 'theme', labelKey: 'appearanceTheme' },
@@ -11,178 +8,3 @@ export const APPEARANCE_SUBPAGES = [
 ] as const
 
 export type AppearanceSubpageId = (typeof APPEARANCE_SUBPAGES)[number]['id']
-
-interface AppearanceSettingCopy {
-  description?: string
-  label: string
-}
-
-interface AppearanceSetting {
-  /** Rows that only exist on some platforms stay out of search, where a hit would scroll to nothing. */
-  available?: () => boolean
-  copy: (t: Translations) => AppearanceSettingCopy
-  keywords: readonly string[]
-  subpage: AppearanceSubpageId
-}
-
-type AppearanceCopy = Translations['settings']['appearance']
-type TitledKey = { [K in keyof AppearanceCopy]: K extends `${infer Base}Title` ? Base : never }[keyof AppearanceCopy]
-
-// Most rows read `<key>Title` / `<key>Desc` straight from the appearance
-// catalog; a Desc that is a formatter (uiScale) is left to the row itself.
-const appearanceCopy =
-  <K extends TitledKey>(key: K) =>
-  (t: Translations): AppearanceSettingCopy => {
-    const catalog: Record<string, unknown> = t.settings.appearance
-    const description = catalog[`${key}Desc`]
-
-    return {
-      label: t.settings.appearance[`${key}Title`],
-      description: typeof description === 'string' ? description : undefined
-    }
-  }
-
-/**
- * The manifest of every hand-built Appearance row. A key becomes the row's
- * deep-link id (`appearance.<kebab-case>`), its subpage routes that id, and its
- * copy + keywords feed the command palette — so a row cannot exist without
- * being searchable, and search cannot point at a row that is not there.
- * Schema-driven rows (`desktop.font_family`) are indexed from the schema and
- * only need a subpage here.
- */
-export const APPEARANCE_SETTINGS = {
-  language: {
-    subpage: 'general',
-    keywords: ['locale'],
-    copy: t => ({ label: t.language.label, description: t.language.description })
-  },
-  introSplash: {
-    subpage: 'general',
-    keywords: ['splash', 'wordmark', 'empty chat', 'new chat'],
-    copy: appearanceCopy('introSplash')
-  },
-  resumeLastSession: {
-    subpage: 'general',
-    keywords: ['resume', 'reopen', 'launch', 'startup', 'last chat', 'session'],
-    copy: appearanceCopy('resumeLastSession')
-  },
-  tips: {
-    subpage: 'general',
-    keywords: ['tips', 'hints', 'coach marks', 'onboarding', 'help'],
-    copy: appearanceCopy('tips')
-  },
-  tours: {
-    subpage: 'general',
-    keywords: ['tour', 'walkthrough', 'guide', 'onboarding', 'help'],
-    copy: appearanceCopy('tours')
-  },
-  theme: { subpage: 'theme', keywords: ['color mode', 'skin', 'light', 'dark'], copy: appearanceCopy('theme') },
-  uiScale: { subpage: 'typography', keywords: ['zoom', 'size'], copy: appearanceCopy('uiScale') },
-  interfaceMode: {
-    subpage: 'window-layout',
-    keywords: ['simple', 'advanced', 'mode', 'interface', 'chrome', 'minimal', 'focus'],
-    copy: t => ({ label: t.interfaceMode.title, description: t.interfaceMode.hint })
-  },
-  sessionDensity: {
-    subpage: 'window-layout',
-    keywords: ['sidebar', 'sessions', 'compact', 'comfortable', 'density'],
-    copy: appearanceCopy('sessionDensity')
-  },
-  tabStrip: { subpage: 'window-layout', keywords: ['tabs', 'tab bar', 'strip'], copy: appearanceCopy('tabStrip') },
-  appActions: {
-    subpage: 'window-layout',
-    keywords: ['titlebar', 'settings gear', 'layout', 'HUD', 'left', 'right', 'tabs'],
-    copy: appearanceCopy('appActions')
-  },
-  minimizeToTray: {
-    subpage: 'window-layout',
-    keywords: ['tray', 'background', 'minimize', 'dock', 'taskbar', 'menu bar'],
-    available: () => Boolean(window.hermesDesktop?.minimizeToTray),
-    copy: t => ({ label: t.settings.config.minimizeToTrayTitle, description: t.settings.config.minimizeToTrayDesc })
-  },
-  translucency: {
-    subpage: 'window-layout',
-    keywords: ['opacity', 'transparent', 'glass', 'blur'],
-    available: () => TRANSLUCENCY_SUPPORTED,
-    copy: appearanceCopy('translucency')
-  },
-  backdrop: { subpage: 'window-layout', keywords: ['background', 'blur'], copy: appearanceCopy('backdrop') },
-  composerPopout: {
-    subpage: 'window-layout',
-    keywords: ['composer', 'floating', 'drag', 'popout', 'dock', 'input'],
-    copy: appearanceCopy('composerPopout')
-  },
-  userBubble: {
-    subpage: 'chat-display',
-    keywords: ['opacity', 'transparent', 'message', 'bubble'],
-    copy: appearanceCopy('userBubble')
-  },
-  textDirection: {
-    subpage: 'chat-display',
-    keywords: ['rtl', 'ltr', 'right to left', 'left to right', 'bidi', 'arabic', 'hebrew', 'persian', 'align'],
-    copy: appearanceCopy('textDirection')
-  },
-  hideThreadTimeline: {
-    subpage: 'chat-display',
-    keywords: ['thread', 'conversation', 'timeline', 'bars', 'rail', 'navigation', 'hide'],
-    copy: appearanceCopy('hideThreadTimeline')
-  },
-  reactions: {
-    subpage: 'chat-display',
-    keywords: ['emoji', 'tapback', 'react', 'reactions'],
-    copy: appearanceCopy('reactions')
-  },
-  vibeHearts: {
-    subpage: 'chat-display',
-    keywords: ['hearts', 'vibe', 'celebrate', 'confetti', 'fun'],
-    copy: appearanceCopy('vibeHearts')
-  },
-  toolView: { subpage: 'chat-display', keywords: ['tool display', 'technical'], copy: appearanceCopy('toolView') },
-  hideCodeDiffs: {
-    subpage: 'chat-display',
-    keywords: ['code', 'diff', 'patch', 'file edits', 'inline', 'added', 'removed'],
-    copy: appearanceCopy('hideCodeDiffs')
-  },
-  reasoningCollapsed: {
-    subpage: 'chat-display',
-    keywords: ['thinking', 'reasoning', 'collapse', 'expand', 'chain of thought'],
-    copy: appearanceCopy('reasoningCollapsed')
-  },
-  embeds: { subpage: 'chat-display', keywords: ['external content', 'privacy'], copy: appearanceCopy('embeds') },
-  pet: {
-    subpage: 'pet',
-    keywords: ['pet', 'mascot', 'petdex', 'companion', 'buddy'],
-    copy: t => ({ label: t.settings.appearance.pet.chooseTitle, description: t.settings.appearance.pet.chooseDesc })
-  }
-} as const satisfies Record<string, AppearanceSetting>
-
-export type AppearanceSettingKey = keyof typeof APPEARANCE_SETTINGS
-
-const APPEARANCE_SETTING_KEYS = Object.keys(APPEARANCE_SETTINGS) as AppearanceSettingKey[]
-const appearanceSetting = (key: AppearanceSettingKey): AppearanceSetting => APPEARANCE_SETTINGS[key]
-
-const kebab = (key: string) => key.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)
-
-export const APPEARANCE_SETTING_IDS = Object.fromEntries(
-  APPEARANCE_SETTING_KEYS.map(key => [key, `appearance.${kebab(key)}`])
-) as Readonly<Record<AppearanceSettingKey, string>>
-
-const SETTING_SUBPAGES: Readonly<Record<string, AppearanceSubpageId>> = {
-  // Schema-driven rows that render on an Appearance subpage.
-  'desktop.font_family': 'typography',
-  'terminal.font_family': 'typography',
-  ...Object.fromEntries(
-    APPEARANCE_SETTING_KEYS.map(key => [APPEARANCE_SETTING_IDS[key], appearanceSetting(key).subpage])
-  )
-}
-
-export function appearanceSubpageForSetting(setting: string): AppearanceSubpageId | undefined {
-  return Object.hasOwn(SETTING_SUBPAGES, setting) ? SETTING_SUBPAGES[setting] : undefined
-}
-
-/** The Appearance rows the command palette can land on right now, with their copy resolved. */
-export function appearanceSearchTargets(t: Translations) {
-  return APPEARANCE_SETTING_KEYS.map(key => [key, appearanceSetting(key)] as const)
-    .filter(([, setting]) => setting.available?.() ?? true)
-    .map(([key, setting]) => ({ id: APPEARANCE_SETTING_IDS[key], keywords: [...setting.keywords], ...setting.copy(t) }))
-}
diff --git a/apps/desktop/src/app/settings/config-settings.tsx b/apps/desktop/src/app/settings/config-settings.tsx
index defe752199..583a6fdcd0 100644
--- a/apps/desktop/src/app/settings/config-settings.tsx
+++ b/apps/desktop/src/app/settings/config-settings.tsx
@@ -51,6 +51,8 @@ import { PoolLimitsSetting } from './pool-limits-setting'
 import { EmptyState, ListRow, SettingsContent, SettingsSkeleton, ToggleRow } from './primitives'
 import { SettingsProfileScope } from './profile-scope'
 import { QuickEntrySettings } from './quick-entry-settings'
+import { SETTING_IDS, settingElementId } from './settings-manifest'
+import { useSettingDeepLink } from './use-setting-deep-link'
 
 export function ConfigSettings({
   activeSectionId,
@@ -302,6 +304,8 @@ function ConfigSettingsInner({
   const [searchParams, setSearchParams] = useSearchParams()
   const targetField = searchParams.get('field')
 
+  useSettingDeepLink(`config:${activeSectionId}`, page => subpage === undefined || page === subpage)
+
   useEffect(() => {
     if (!targetField || !config || !schema) {
       return
@@ -438,12 +442,14 @@ function ConfigSettingsInner({
           <ToggleRow
             checked={keepAwake}
             description={c.keepAwakeDesc}
+            id={settingElementId(SETTING_IDS.advanced.keepAwake)}
             label={c.keepAwakeTitle}
             onChange={setKeepAwake}
           />
           <ToggleRow
             checked={disableF12}
             description={c.disableF12Desc}
+            id={settingElementId(SETTING_IDS.advanced.disableF12)}
             label={c.disableF12Title}
             onChange={setDisableF12}
           />
@@ -561,6 +567,7 @@ function AttachmentSizeSetting() {
         </div>
       }
       description={c.attachmentSizeDesc}
+      id={settingElementId(SETTING_IDS.chat.attachmentSize)}
       title={c.attachmentSizeTitle}
     />
   )
diff --git a/apps/desktop/src/app/settings/gateway-settings.tsx b/apps/desktop/src/app/settings/gateway-settings.tsx
index c555b5f118..432c570479 100644
--- a/apps/desktop/src/app/settings/gateway-settings.tsx
+++ b/apps/desktop/src/app/settings/gateway-settings.tsx
@@ -45,7 +45,9 @@ import { ConnectionsRegistrySection } from './connections-registry'
 import { CONTROL_TEXT } from './constants'
 import { ManagedUpdatesSection } from './managed-updates-section'
 import { EmptyState, ListRow, Pill, SettingsContent, SettingsSkeleton, ToggleRow } from './primitives'
+import { SETTING_IDS, settingElementId } from './settings-manifest'
 import { enrichSelectedSshHost, selectSshHost } from './ssh-host-selection'
+import { useSettingDeepLink } from './use-setting-deep-link'
 
 type Mode = 'local' | 'remote' | 'cloud' | 'ssh'
 type AuthMode = 'oauth' | 'token'
@@ -168,6 +170,8 @@ interface GatewaySettingsProps {
 }
 
 export function GatewaySettings({ embedded = false, subpage }: GatewaySettingsProps = {}) {
+  useSettingDeepLink('gateway', page => subpage === undefined || page === subpage)
+
   // Recovery always keeps the complete connection form, regardless of a
   // settings destination. Other tasks never mount that form or its probes.
   if (!embedded && subpage === 'devices') {
@@ -1251,7 +1255,7 @@ function GatewayConnectionSettings({ embedded, standalone }: { embedded: boolean
         </div>
       ) : null}
 
-      <div className="mb-5 grid gap-2">
+      <div className="mb-5 grid gap-2" id={settingElementId(SETTING_IDS.gateway.connectionMode)}>
         <div className="text-[length:var(--conversation-caption-font-size)] font-medium text-(--ui-text-secondary)">
           {g.modeTitle}
         </div>
@@ -1743,6 +1747,7 @@ function GatewayConnectionSettings({ embedded, standalone }: { embedded: boolean
             checked={keychainEncryption}
             description={g.keychainEncryptionDesc}
             disabled={keychainEncryptionBusy}
+            id={settingElementId(SETTING_IDS.gateway.keychainEncryption)}
             label={g.keychainEncryptionTitle}
             onChange={on => void setKeychainEncryption(on)}
           />
@@ -1754,6 +1759,7 @@ function GatewayConnectionSettings({ embedded, standalone }: { embedded: boolean
               </Button>
             }
             description={g.diagnosticsDesc}
+            id={settingElementId(SETTING_IDS.gateway.diagnostics)}
             title={g.diagnostics}
           />
         </div>
diff --git a/apps/desktop/src/app/settings/hud-modifier-settings.tsx b/apps/desktop/src/app/settings/hud-modifier-settings.tsx
index 29c765b9fe..4f41143cf3 100644
--- a/apps/desktop/src/app/settings/hud-modifier-settings.tsx
+++ b/apps/desktop/src/app/settings/hud-modifier-settings.tsx
@@ -7,10 +7,7 @@ import { useI18n } from '@/i18n'
 import type { HudModifierStatus } from '../../../electron/hud-modifier-types'
 
 import { ToggleRow } from './primitives'
-import { useDeepLinkHighlight } from './use-deep-link-highlight'
-
-const isHudModifierSetting = (target: string) => target === 'hud-modifier'
-const hudModifierElementId = () => 'setting-hud-modifier'
+import { SETTING_IDS, settingElementId } from './settings-manifest'
 
 export function HudModifierSettings() {
   const { t } = useI18n()
@@ -22,7 +19,6 @@ export function HudModifierSettings() {
   const [error, setError] = useState<string | null>(null)
   const request = useRef(0)
   const revision = useRef(0)
-  useDeepLinkHighlight({ param: 'setting', ready: isHudModifierSetting, elementId: hudModifierElementId })
 
   const refresh = useCallback(
     async (enabled?: boolean) => {
@@ -96,7 +92,7 @@ export function HudModifierSettings() {
     (status?.enabled && status.state === 'unavailable' ? unavailableNotice : null)
 
   return (
-    <div id={hudModifierElementId()}>
+    <div id={settingElementId(SETTING_IDS.keybinds.hudModifier)}>
       <ToggleRow
         checked={status?.enabled ?? false}
         description={copy.description}
diff --git a/apps/desktop/src/app/settings/keybind-settings.tsx b/apps/desktop/src/app/settings/keybind-settings.tsx
index 1d294e0856..9412fba7ef 100644
--- a/apps/desktop/src/app/settings/keybind-settings.tsx
+++ b/apps/desktop/src/app/settings/keybind-settings.tsx
@@ -33,12 +33,15 @@ import {
 import { HudModifierSettings } from './hud-modifier-settings'
 import { SettingsBreadcrumbContext, SettingsContent } from './primitives'
 import { ScreenshotSettings } from './screenshot-settings'
+import { useSettingDeepLink } from './use-setting-deep-link'
 
 interface KeybindSettingsProps {
   subpage?: string
 }
 
 export function KeybindSettings({ subpage }: KeybindSettingsProps = {}) {
+  useSettingDeepLink('keybinds', page => subpage === undefined || page === subpage)
+
   if (subpage === 'hud-gesture') {
     return (
       <SettingsContent>
diff --git a/apps/desktop/src/app/settings/notifications-settings.tsx b/apps/desktop/src/app/settings/notifications-settings.tsx
index 6e6a0fefe3..c210cca8f0 100644
--- a/apps/desktop/src/app/settings/notifications-settings.tsx
+++ b/apps/desktop/src/app/settings/notifications-settings.tsx
@@ -20,6 +20,8 @@ import { notify } from '@/store/notifications'
 
 import { CONTROL_TEXT } from './constants'
 import { ListRow, SectionHeading, SettingsContent, ToggleRow } from './primitives'
+import { notificationKindSettingId, SETTING_IDS, settingElementId } from './settings-manifest'
+import { useSettingDeepLink } from './use-setting-deep-link'
 
 const CAPTION = 'text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)'
 
@@ -39,6 +41,8 @@ export function NotificationsSettings({ subpage }: NotificationsSettingsProps =
   const showAlerts = subpage === undefined || subpage === 'alerts'
   const showSounds = subpage === undefined || subpage === 'sounds'
 
+  useSettingDeepLink('notifications', page => subpage === undefined || page === subpage)
+
   const runTest = async () => {
     triggerHaptic('open')
     const ok = await sendTestNativeNotification(copy.testTitle, copy.testBody)
@@ -55,6 +59,7 @@ export function NotificationsSettings({ subpage }: NotificationsSettingsProps =
           <ToggleRow
             checked={prefs.enabled}
             description={copy.enableAllDesc}
+            id={settingElementId(SETTING_IDS.notifications.enableAll)}
             label={copy.enableAll}
             onChange={setNativeNotifyEnabled}
           />
@@ -64,6 +69,7 @@ export function NotificationsSettings({ subpage }: NotificationsSettingsProps =
               checked={prefs.enabled && prefs.kinds[kind]}
               description={copy.kinds[kind].description}
               disabled={!prefs.enabled}
+              id={settingElementId(notificationKindSettingId(kind))}
               key={kind}
               label={copy.kinds[kind].label}
               onChange={on => setNativeNotifyKind(kind, on)}
@@ -115,6 +121,7 @@ export function NotificationsSettings({ subpage }: NotificationsSettingsProps =
             </>
           }
           description={copy.completionSoundDesc}
+          id={settingElementId(SETTING_IDS.notifications.completionSound)}
           title={copy.completionSoundTitle}
         />
       )}
diff --git a/apps/desktop/src/app/settings/pool-limits-setting.tsx b/apps/desktop/src/app/settings/pool-limits-setting.tsx
index 19a4c87b7a..2081ac3c12 100644
--- a/apps/desktop/src/app/settings/pool-limits-setting.tsx
+++ b/apps/desktop/src/app/settings/pool-limits-setting.tsx
@@ -2,6 +2,7 @@ import { useStore } from '@nanostores/react'
 import { useEffect, useState } from 'react'
 
 import { ListRow } from '@/app/settings/primitives'
+import { SETTING_IDS, settingElementId } from '@/app/settings/settings-manifest'
 import { Input } from '@/components/ui/input'
 import { useI18n } from '@/i18n'
 import { $poolLimits, loadPoolLimits, savePoolLimits } from '@/store/pool-limits'
@@ -83,6 +84,7 @@ export function PoolLimitsSetting() {
           </div>
         }
         description="How many bot backends stay running for instant switching. Higher = faster switches, more memory (~60MB per backend). Applies immediately."
+        id={settingElementId(SETTING_IDS.advanced.warmBotBackends)}
         title={t.settings.poolLimits.warmBotBackendsTitle}
       />
       <ListRow
@@ -108,6 +110,7 @@ export function PoolLimitsSetting() {
           </div>
         }
         description="How long an unused bot backend stays warm before it is shut down. Raise this so bots you revisit every few minutes never pay a cold start."
+        id={settingElementId(SETTING_IDS.advanced.backendIdleTimeout)}
         title={t.settings.poolLimits.backendIdleTimeoutTitle}
       />
     </>
diff --git a/apps/desktop/src/app/settings/quick-entry-settings.tsx b/apps/desktop/src/app/settings/quick-entry-settings.tsx
index 3daf56f8f2..da829b68e5 100644
--- a/apps/desktop/src/app/settings/quick-entry-settings.tsx
+++ b/apps/desktop/src/app/settings/quick-entry-settings.tsx
@@ -13,6 +13,7 @@ import {
 } from '@/store/quick-entry'
 
 import { ListRow, ToggleRow } from './primitives'
+import { SETTING_IDS, settingElementId } from './settings-manifest'
 
 /**
  * Quick Entry — the global-hotkey mini composer's settings rows.
@@ -63,6 +64,7 @@ export function QuickEntrySettings() {
       <ToggleRow
         checked={state.enabled}
         description={q.enabledDesc}
+        id={settingElementId(SETTING_IDS.advanced.quickEntry)}
         label={q.enabledTitle}
         onChange={enabled => void saveQuickEntrySettings({ enabled })}
       />
@@ -97,6 +99,7 @@ export function QuickEntrySettings() {
           )
         }
         description={q.shortcutDesc}
+        id={settingElementId(SETTING_IDS.advanced.quickEntryShortcut)}
         title={q.shortcutTitle}
       />
     </>
diff --git a/apps/desktop/src/app/settings/screenshot-settings.tsx b/apps/desktop/src/app/settings/screenshot-settings.tsx
index 64325031b4..2df4b454cb 100644
--- a/apps/desktop/src/app/settings/screenshot-settings.tsx
+++ b/apps/desktop/src/app/settings/screenshot-settings.tsx
@@ -8,6 +8,7 @@ import { useI18n } from '@/i18n'
 import type { ScreenshotStatus } from '../../../electron/command-screenshot-types'
 
 import { ListRow, ToggleRow } from './primitives'
+import { SETTING_IDS, settingElementId } from './settings-manifest'
 
 type SettingsError = 'loadFailed' | 'saveFailed' | 'permissionFailed'
 
@@ -122,6 +123,7 @@ export function ScreenshotSettings() {
         checked={status?.enabled ?? false}
         description={s.enabledDesc}
         disabled={!status || busy}
+        id={settingElementId(SETTING_IDS.keybinds.screenshot)}
         label={s.enabledTitle}
         onChange={enabled => void refresh(enabled)}
       />
diff --git a/apps/desktop/src/app/settings/sessions-settings.tsx b/apps/desktop/src/app/settings/sessions-settings.tsx
index 8e8f08da5d..f10fad821d 100644
--- a/apps/desktop/src/app/settings/sessions-settings.tsx
+++ b/apps/desktop/src/app/settings/sessions-settings.tsx
@@ -26,7 +26,9 @@ import { forgetSessionUnread } from '@/store/session-unread'
 import type { HermesConfigRecord, SessionInfo } from '@/types/hermes'
 
 import { EmptyState, ListRow, SectionHeading, SettingsContent, SettingsSkeleton, ToggleRow } from './primitives'
+import { SETTING_IDS, settingElementId } from './settings-manifest'
 import { useDeepLinkHighlight } from './use-deep-link-highlight'
+import { useSettingDeepLink } from './use-setting-deep-link'
 
 const DEFAULT_AUTO_ARCHIVE_DAYS = 3
 
@@ -37,6 +39,8 @@ interface SessionsSettingsProps {
 }
 
 export function SessionsSettings({ subpage }: SessionsSettingsProps = {}) {
+  useSettingDeepLink('sessions', page => subpage === undefined || page === subpage)
+
   if (subpage === 'default-directory') {
     return (
       <SettingsContent>
@@ -281,6 +285,7 @@ function AutoArchiveSetting() {
       <ToggleRow
         checked={enabled}
         description={s.autoArchiveDesc}
+        id={settingElementId(SETTING_IDS.sessions.autoArchive)}
         label={s.autoArchiveTitle}
         onChange={on => {
           setEnabled(on)
diff --git a/apps/desktop/src/app/settings/settings-manifest.ts b/apps/desktop/src/app/settings/settings-manifest.ts
new file mode 100644
index 0000000000..df49699700
--- /dev/null
+++ b/apps/desktop/src/app/settings/settings-manifest.ts
@@ -0,0 +1,328 @@
+import type { Translations } from '@/i18n'
+import { NATIVE_NOTIFICATION_KINDS } from '@/store/native-notifications'
+import { canUseQuickEntry } from '@/store/quick-entry'
+import { TRANSLUCENCY_SUPPORTED } from '@/store/translucency'
+
+import type { AppearanceSubpageId } from './appearance-subpages'
+import type { SettingsView } from './types'
+
+interface SettingCopy {
+  description?: string
+  label: string
+}
+
+export interface SettingDefinition {
+  /** Rows that only exist on some platforms stay out of search, where a hit would scroll to nothing. */
+  available?: () => boolean
+  copy: (t: Translations) => SettingCopy
+  keywords: readonly string[]
+  /** The child page the row lives on; omitted when the view has no subpages. */
+  subpage?: string
+}
+
+type AppearanceCopy = Translations['settings']['appearance']
+type TitledKey = { [K in keyof AppearanceCopy]: K extends `${infer Base}Title` ? Base : never }[keyof AppearanceCopy]
+
+// Most Appearance rows read `<key>Title` / `<key>Desc` straight from the
+// appearance catalog; a Desc that is a formatter (uiScale) is left to the row.
+const appearanceCopy =
+  <K extends TitledKey>(key: K) =>
+  (t: Translations): SettingCopy => {
+    const catalog: Record<string, unknown> = t.settings.appearance
+    const description = catalog[`${key}Desc`]
+
+    return {
+      label: t.settings.appearance[`${key}Title`],
+      description: typeof description === 'string' ? description : undefined
+    }
+  }
+
+const appearanceSetting = (subpage: AppearanceSubpageId, keywords: readonly string[], key: TitledKey) =>
+  ({ subpage, keywords, copy: appearanceCopy(key) }) satisfies SettingDefinition
+
+/**
+ * The manifest of every hand-built settings row — the ones that are not a
+ * config-schema field, a credential, or a plugin (those index themselves from
+ * backend metadata). A key becomes the row's deep-link id
+ * (`<view>.<kebab-case>`), its subpage routes that id, and its copy + keywords
+ * feed the command palette — so a row cannot exist without being searchable,
+ * and search cannot point at a row that is not there.
+ *
+ * List *items* (an archived chat, a saved connection, a credential) are not
+ * settings and do not belong here; their pages own their own deep links.
+ */
+export const SETTINGS_MANIFEST = {
+  appearance: {
+    language: {
+      subpage: 'general',
+      keywords: ['locale'],
+      copy: t => ({ label: t.language.label, description: t.language.description })
+    },
+    introSplash: appearanceSetting('general', ['splash', 'wordmark', 'empty chat', 'new chat'], 'introSplash'),
+    resumeLastSession: appearanceSetting(
+      'general',
+      ['resume', 'reopen', 'launch', 'startup', 'last chat', 'session'],
+      'resumeLastSession'
+    ),
+    tips: appearanceSetting('general', ['tips', 'hints', 'coach marks', 'onboarding', 'help'], 'tips'),
+    tours: appearanceSetting('general', ['tour', 'walkthrough', 'guide', 'onboarding', 'help'], 'tours'),
+    theme: appearanceSetting('theme', ['color mode', 'skin', 'light', 'dark'], 'theme'),
+    uiScale: appearanceSetting('typography', ['zoom', 'size'], 'uiScale'),
+    chatFont: appearanceSetting('typography', ['font', 'typeface', 'family', 'text'], 'chatFont'),
+    terminalFont: appearanceSetting(
+      'typography',
+      ['font', 'monospace', 'nerd font', 'glyphs', 'shell'],
+      'terminalFont'
+    ),
+    interfaceMode: {
+      subpage: 'window-layout',
+      keywords: ['simple', 'advanced', 'mode', 'interface', 'chrome', 'minimal', 'focus'],
+      copy: t => ({ label: t.interfaceMode.title, description: t.interfaceMode.hint })
+    },
+    sessionDensity: appearanceSetting(
+      'window-layout',
+      ['sidebar', 'sessions', 'compact', 'comfortable', 'density'],
+      'sessionDensity'
+    ),
+    tabStrip: appearanceSetting('window-layout', ['tabs', 'tab bar', 'strip'], 'tabStrip'),
+    appActions: appearanceSetting(
+      'window-layout',
+      ['titlebar', 'settings gear', 'layout', 'HUD', 'left', 'right', 'tabs'],
+      'appActions'
+    ),
+    minimizeToTray: {
+      subpage: 'window-layout',
+      keywords: ['tray', 'background', 'minimize', 'dock', 'taskbar', 'menu bar'],
+      available: () => Boolean(window.hermesDesktop?.minimizeToTray),
+      copy: t => ({ label: t.settings.config.minimizeToTrayTitle, description: t.settings.config.minimizeToTrayDesc })
+    },
+    translucency: {
+      ...appearanceSetting('window-layout', ['opacity', 'transparent', 'glass', 'blur'], 'translucency'),
+      available: () => TRANSLUCENCY_SUPPORTED
+    },
+    backdrop: appearanceSetting('window-layout', ['background', 'blur'], 'backdrop'),
+    composerPopout: appearanceSetting(
+      'window-layout',
+      ['composer', 'floating', 'drag', 'popout', 'dock', 'input'],
+      'composerPopout'
+    ),
+    userBubble: appearanceSetting('chat-display', ['opacity', 'transparent', 'message', 'bubble'], 'userBubble'),
+    textDirection: appearanceSetting(
+      'chat-display',
+      ['rtl', 'ltr', 'right to left', 'left to right', 'bidi', 'arabic', 'hebrew', 'persian', 'align'],
+      'textDirection'
+    ),
+    hideThreadTimeline: appearanceSetting(
+      'chat-display',
+      ['thread', 'conversation', 'timeline', 'bars', 'rail', 'navigation', 'hide'],
+      'hideThreadTimeline'
+    ),
+    reactions: appearanceSetting('chat-display', ['emoji', 'tapback', 'react', 'reactions'], 'reactions'),
+    vibeHearts: appearanceSetting('chat-display', ['hearts', 'vibe', 'celebrate', 'confetti', 'fun'], 'vibeHearts'),
+    toolView: appearanceSetting('chat-display', ['tool display', 'technical'], 'toolView'),
+    hideCodeDiffs: appearanceSetting(
+      'chat-display',
+      ['code', 'diff', 'patch', 'file edits', 'inline', 'added', 'removed'],
+      'hideCodeDiffs'
+    ),
+    reasoningCollapsed: appearanceSetting(
+      'chat-display',
+      ['thinking', 'reasoning', 'collapse', 'expand', 'chain of thought'],
+      'reasoningCollapsed'
+    ),
+    embeds: appearanceSetting('chat-display', ['external content', 'privacy'], 'embeds'),
+    pet: {
+      subpage: 'pet',
+      keywords: ['pet', 'mascot', 'petdex', 'companion', 'buddy'],
+      copy: t => ({ label: t.settings.appearance.pet.chooseTitle, description: t.settings.appearance.pet.chooseDesc })
+    }
+  },
+  chat: {
+    attachmentSize: {
+      subpage: 'attachments',
+      keywords: ['attachment', 'image', 'preview', 'upload', 'file size', 'limit', 'MB'],
+      copy: t => ({ label: t.settings.config.attachmentSizeTitle, description: t.settings.config.attachmentSizeDesc })
+    }
+  },
+  advanced: {
+    keepAwake: {
+      subpage: 'desktop',
+      keywords: ['sleep', 'awake', 'caffeinate', 'idle', 'overnight', 'power'],
+      copy: t => ({ label: t.settings.config.keepAwakeTitle, description: t.settings.config.keepAwakeDesc })
+    },
+    disableF12: {
+      subpage: 'desktop',
+      keywords: ['devtools', 'developer tools', 'f12', 'inspector', 'debug'],
+      copy: t => ({ label: t.settings.config.disableF12Title, description: t.settings.config.disableF12Desc })
+    },
+    warmBotBackends: {
+      subpage: 'desktop',
+      keywords: ['pool', 'backends', 'bots', 'warm', 'concurrency', 'limit'],
+      copy: t => ({ label: t.settings.poolLimits.warmBotBackendsTitle })
+    },
+    backendIdleTimeout: {
+      subpage: 'desktop',
+      keywords: ['pool', 'backends', 'idle', 'timeout', 'milliseconds'],
+      copy: t => ({ label: t.settings.poolLimits.backendIdleTimeoutTitle })
+    },
+    quickEntry: {
+      subpage: 'desktop',
+      keywords: ['quick entry', 'global shortcut', 'spotlight', 'summon', 'prompt anywhere'],
+      available: canUseQuickEntry,
+      copy: t => ({ label: t.settings.quickEntry.enabledTitle, description: t.settings.quickEntry.enabledDesc })
+    },
+    quickEntryShortcut: {
+      subpage: 'desktop',
+      keywords: ['quick entry', 'shortcut', 'hotkey', 'keybind', 'chord'],
+      available: canUseQuickEntry,
+      copy: t => ({ label: t.settings.quickEntry.shortcutTitle, description: t.settings.quickEntry.shortcutDesc })
+    }
+  },
+  keybinds: {
+    hudModifier: {
+      subpage: 'hud-gesture',
+      keywords: ['HUD', 'summon', 'modifier', 'tap', 'Ctrl', 'Alt', 'Command', 'Option'],
+      available: () => Boolean(window.hermesDesktop?.hudModifier),
+      copy: t => ({ label: t.settings.hudModifier.title, description: t.settings.hudModifier.description })
+    },
+    screenshot: {
+      subpage: 'screen-capture',
+      keywords: ['screenshot', 'screen capture', 'window', 'attach', 'command keys'],
+      available: () => Boolean(window.hermesDesktop?.screenshot),
+      copy: t => ({ label: t.settings.screenshot.enabledTitle, description: t.settings.screenshot.enabledDesc })
+    }
+  },
+  notifications: {
+    enableAll: {
+      subpage: 'alerts',
+      keywords: ['notifications', 'alerts', 'native', 'banner', 'mute', 'do not disturb'],
+      copy: t => ({ label: t.settings.notifications.enableAll, description: t.settings.notifications.enableAllDesc })
+    },
+    ...Object.fromEntries(
+      NATIVE_NOTIFICATION_KINDS.map(kind => [
+        `kind-${kind}`,
+        {
+          subpage: 'alerts',
+          keywords: ['notification', 'alert', kind],
+          copy: (t: Translations) => ({
+            label: t.settings.notifications.kinds[kind].label,
+            description: t.settings.notifications.kinds[kind].description
+          })
+        } satisfies SettingDefinition
+      ])
+    ),
+    completionSound: {
+      subpage: 'sounds',
+      keywords: ['sound', 'chime', 'ding', 'audio', 'done', 'complete', 'mute'],
+      copy: t => ({
+        label: t.settings.notifications.completionSoundTitle,
+        description: t.settings.notifications.completionSoundDesc
+      })
+    }
+  },
+  sessions: {
+    autoArchive: {
+      subpage: 'archived',
+      keywords: ['archive', 'stale', 'cleanup', 'old chats', 'days', 'after'],
+      copy: t => ({ label: t.settings.sessions.autoArchiveTitle, description: t.settings.sessions.autoArchiveDesc })
+    }
+  },
+  gateway: {
+    connectionMode: {
+      subpage: 'connection',
+      keywords: ['gateway', 'connection', 'local', 'cloud', 'remote', 'ssh', 'url', 'token', 'host', 'port', 'key'],
+      copy: t => ({ label: t.settings.gateway.modeTitle, description: t.settings.gateway.intro })
+    },
+    keychainEncryption: {
+      subpage: 'connection',
+      keywords: ['keychain', 'encrypt', 'secrets', 'secure storage', 'plain text'],
+      copy: t => ({
+        label: t.settings.gateway.keychainEncryptionTitle,
+        description: t.settings.gateway.keychainEncryptionDesc
+      })
+    },
+    diagnostics: {
+      subpage: 'connection',
+      keywords: ['diagnostics', 'logs', 'debug', 'report', 'troubleshoot'],
+      copy: t => ({ label: t.settings.gateway.diagnostics, description: t.settings.gateway.diagnosticsDesc })
+    }
+  },
+  about: {
+    automaticUpdates: {
+      subpage: 'updates',
+      keywords: ['update', 'auto update', 'download', 'release', 'version'],
+      copy: t => ({ label: t.settings.about.automaticUpdates, description: t.settings.about.automaticUpdatesDesc })
+    }
+  }
+} as const satisfies Record<string, Record<string, SettingDefinition>>
+
+export type ManifestViewKey = keyof typeof SETTINGS_MANIFEST
+
+/** Manifest keys that are config sections route as `config:<key>`; the rest are views of their own. */
+const CONFIG_SECTION_KEYS: readonly ManifestViewKey[] = ['appearance', 'chat', 'advanced']
+
+export const manifestView = (key: ManifestViewKey): SettingsView =>
+  CONFIG_SECTION_KEYS.includes(key) ? `config:${key}` : (key as SettingsView)
+
+const manifestKeyForView = (view: SettingsView): ManifestViewKey | undefined => {
+  const key = view.startsWith('config:') ? view.slice('config:'.length) : view
+
+  return Object.hasOwn(SETTINGS_MANIFEST, key) ? (key as ManifestViewKey) : undefined
+}
+
+const kebab = (key: string) => key.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)
+
+/** The deep-link id of a manifest row: `settingId('appearance', 'tips') === 'appearance.tips'`. */
+export const settingId = (view: ManifestViewKey, key: string) => `${view}.${kebab(key)}`
+
+/** Notification kinds are generated from the store's kind list, so their ids are looked up by kind. */
+export const notificationKindSettingId = (kind: (typeof NATIVE_NOTIFICATION_KINDS)[number]) =>
+  settingId('notifications', `kind-${kind}`)
+
+type SettingIds = { readonly [V in ManifestViewKey]: { readonly [K in keyof (typeof SETTINGS_MANIFEST)[V]]: string } }
+
+/** `SETTING_IDS.appearance.tips === 'appearance.tips'` — the id a row carries and a palette hit targets. */
+export const SETTING_IDS = Object.fromEntries(
+  (Object.keys(SETTINGS_MANIFEST) as ManifestViewKey[]).map(view => [
+    view,
+    Object.fromEntries(Object.keys(SETTINGS_MANIFEST[view]).map(key => [key, settingId(view, key)]))
+  ])
+) as SettingIds
+
+/** The DOM id a settings row carries so a deep link can scroll to and flash it. */
+export const settingElementId = (id: string) => `setting-field-${id}`
+
+const definitions = (view: ManifestViewKey): Record<string, SettingDefinition> => SETTINGS_MANIFEST[view]
+
+/** The manifest row behind a deep-link id on a view, if the view owns one. */
+export function settingDefinition(view: SettingsView, id: string): SettingDefinition | undefined {
+  const key = manifestKeyForView(view)
+
+  if (!key) {
+    return undefined
+  }
+
+  const [settingKey] = Object.entries(SETTING_IDS[key]).find(([, candidate]) => candidate === id) ?? []
+
+  return settingKey ? definitions(key)[settingKey] : undefined
+}
+
+export interface SettingSearchTarget extends SettingCopy {
+  id: string
+  keywords: string[]
+  view: SettingsView
+}
+
+/** Every manifest row the command palette can land on right now, copy resolved. */
+export function settingSearchTargets(t: Translations): SettingSearchTarget[] {
+  return (Object.keys(SETTINGS_MANIFEST) as ManifestViewKey[]).flatMap(viewKey =>
+    Object.entries(definitions(viewKey))
+      .filter(([, setting]) => setting.available?.() ?? true)
+      .map(([key, setting]) => ({
+        id: SETTING_IDS[viewKey][key as keyof (typeof SETTING_IDS)[typeof viewKey]],
+        keywords: [...setting.keywords],
+        view: manifestView(viewKey),
+        ...setting.copy(t)
+      }))
+  )
+}
diff --git a/apps/desktop/src/app/settings/subpages.test.ts b/apps/desktop/src/app/settings/subpages.test.ts
index 3307da34ce..3ce0d7d99e 100644
--- a/apps/desktop/src/app/settings/subpages.test.ts
+++ b/apps/desktop/src/app/settings/subpages.test.ts
@@ -2,16 +2,17 @@ import { describe, expect, it } from 'vitest'
 
 import { TRANSLATIONS } from '@/i18n'
 
-import {
-  APPEARANCE_SETTING_IDS,
-  APPEARANCE_SETTINGS,
-  APPEARANCE_SUBPAGES,
-  appearanceSearchTargets,
-  appearanceSubpageForSetting
-} from './appearance-subpages'
 import { CONFIG_SUBPAGES, configSubpageForField } from './config-subpages'
 import { SECTIONS } from './constants'
 import { OTHER_SUBPAGES } from './other-subpages'
+import {
+  manifestView,
+  type ManifestViewKey,
+  SETTING_IDS,
+  settingDefinition,
+  SETTINGS_MANIFEST,
+  settingSearchTargets
+} from './settings-manifest'
 import { settingsSearchTargetQuery } from './settings-search'
 import { resolveSettingsSubpage, settingsSubpages } from './subpages'
 import type { SettingsView } from './types'
@@ -57,8 +58,10 @@ describe('settings subpage routing', () => {
 
     const cases: [SettingsView, string, string][] = [
       ['config:model', 'aux=vision', 'auxiliary'],
-      ['keybinds', 'setting=hud-modifier', 'hud-gesture'],
-      ['keybinds', 'page=shortcuts&setting=hud-modifier', 'hud-gesture'],
+      ['keybinds', 'setting=keybinds.hud-modifier', 'hud-gesture'],
+      ['keybinds', 'page=shortcuts&setting=keybinds.hud-modifier', 'hud-gesture'],
+      ['notifications', 'setting=notifications.completion-sound', 'sounds'],
+      ['config:advanced', 'setting=advanced.keep-awake', 'desktop'],
       ['sessions', 'session=archived-id', 'archived'],
       ['vault', 'kind=login', 'credentials'],
       ['vault', 'label=Example', 'credentials'],
@@ -71,31 +74,45 @@ describe('settings subpage routing', () => {
     }
   })
 
-  it('makes every Appearance row a routed, translated palette hit', () => {
-    const subpages = APPEARANCE_SUBPAGES.map(page => page.id)
+  it('makes every manifest row a routed, translated palette hit on a real page', () => {
+    for (const viewKey of Object.keys(SETTINGS_MANIFEST) as ManifestViewKey[]) {
+      const view = manifestView(viewKey)
+      const subpages = settingsSubpages(view).map(page => page.id)
+      expect(views).toContain(view)
 
-    for (const [key, setting] of Object.entries(APPEARANCE_SETTINGS)) {
-      const id = APPEARANCE_SETTING_IDS[key as keyof typeof APPEARANCE_SETTING_IDS]
-      expect(id).toMatch(/^appearance\.[a-z-]+$/)
-      expect(subpages).toContain(setting.subpage)
-      expect(appearanceSubpageForSetting(id)).toBe(setting.subpage)
-      expect(
-        resolveSettingsSubpage(
-          'config:appearance',
-          new URLSearchParams(settingsSearchTargetQuery({ view: 'config:appearance', setting: id }))
-        )
-      ).toBe(setting.subpage)
-      expect(setting.keywords.length).toBeGreaterThan(0)
+      for (const [key, setting] of Object.entries(SETTINGS_MANIFEST[viewKey])) {
+        const id = SETTING_IDS[viewKey][key as keyof (typeof SETTING_IDS)[typeof viewKey]]
+        expect(id).toBe(`${viewKey}.${key.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)}`)
+        expect(settingDefinition(view, id)).toBe(setting)
+        expect(setting.keywords.length).toBeGreaterThan(0)
 
-      for (const locale of Object.values(TRANSLATIONS)) {
-        expect(setting.copy(locale).label).toBeTruthy()
+        if (setting.subpage) {
+          expect(subpages).toContain(setting.subpage)
+          expect(
+            resolveSettingsSubpage(view, new URLSearchParams(settingsSearchTargetQuery({ view, setting: id })))
+          ).toBe(setting.subpage)
+        }
+
+        for (const locale of Object.values(TRANSLATIONS)) {
+          expect(setting.copy(locale).label).toBeTruthy()
+        }
       }
     }
 
     // Platform-gated rows aside, the whole manifest reaches the palette.
-    const targets = appearanceSearchTargets(TRANSLATIONS.en)
-    const gated = Object.values(APPEARANCE_SETTINGS).filter(setting => 'available' in setting).length
-    expect(targets.length).toBeGreaterThanOrEqual(Object.keys(APPEARANCE_SETTINGS).length - gated)
-    expect(targets.map(target => target.label)).toEqual(expect.arrayContaining(['In-App Tips', 'Guided Tours']))
+    const definitions = Object.values(SETTINGS_MANIFEST).flatMap(rows => Object.values(rows))
+    const gated = definitions.filter(setting => 'available' in setting).length
+    const targets = settingSearchTargets(TRANSLATIONS.en)
+    expect(targets.length).toBeGreaterThanOrEqual(definitions.length - gated)
+    expect(new Set(targets.map(target => target.id)).size).toBe(targets.length)
+    expect(targets.map(target => target.label)).toEqual(
+      expect.arrayContaining([
+        'In-App Tips',
+        'Guided Tours',
+        'Keep computer awake',
+        'Auto-archive stale chats',
+        'Automatic updates'
+      ])
+    )
   })
 })
diff --git a/apps/desktop/src/app/settings/subpages.ts b/apps/desktop/src/app/settings/subpages.ts
index 490dc0a5a0..f618229282 100644
--- a/apps/desktop/src/app/settings/subpages.ts
+++ b/apps/desktop/src/app/settings/subpages.ts
@@ -29,9 +29,10 @@ import {
   Wrench
 } from '@/lib/icons'
 
-import { APPEARANCE_SUBPAGES, appearanceSubpageForSetting } from './appearance-subpages'
+import { APPEARANCE_SUBPAGES } from './appearance-subpages'
 import { CONFIG_SUBPAGES, configSubpageForField } from './config-subpages'
 import { OTHER_SUBPAGES } from './other-subpages'
+import { settingDefinition } from './settings-manifest'
 import type { SettingsView } from './types'
 
 export interface SettingsSubpage {
@@ -105,12 +106,8 @@ export function settingsSubpages(view: SettingsView): readonly SettingsSubpage[]
 
 /** Shared by search serialization and saved links that predate subpages. */
 export function settingsSubpageForTarget(view: SettingsView, field?: string, setting?: string): string | undefined {
-  if (view === 'keybinds' && setting === 'hud-modifier') {
-    return 'hud-gesture'
-  }
-
-  if (view === 'config:appearance' && setting) {
-    return appearanceSubpageForSetting(setting)
+  if (setting) {
+    return settingDefinition(view, setting)?.subpage
   }
 
   if (view.startsWith('config:') && field) {
diff --git a/apps/desktop/src/app/settings/use-setting-deep-link.ts b/apps/desktop/src/app/settings/use-setting-deep-link.ts
new file mode 100644
index 0000000000..ef92d15a6b
--- /dev/null
+++ b/apps/desktop/src/app/settings/use-setting-deep-link.ts
@@ -0,0 +1,24 @@
+import { useCallback } from 'react'
+
+import { settingDefinition, settingElementId } from './settings-manifest'
+import type { SettingsView } from './types'
+import { useDeepLinkHighlight } from './use-deep-link-highlight'
+
+/**
+ * Land a palette hit (`?setting=<id>`) on a manifest row of this view: once
+ * the row's subpage is showing, scroll to it and flash it. Pages with no
+ * subpages pass no `show`; pages with subpages pass the same predicate that
+ * gates their rows so the highlight waits for the right child page.
+ */
+export function useSettingDeepLink(view: SettingsView, show: (subpage: string | undefined) => boolean = () => true) {
+  const ready = useCallback(
+    (id: string) => {
+      const setting = settingDefinition(view, id)
+
+      return setting !== undefined && show(setting.subpage)
+    },
+    [show, view]
+  )
+
+  return useDeepLinkHighlight({ elementId: settingElementId, param: 'setting', ready })
+}
diff --git a/apps/desktop/src/app/settings/use-settings-search.ts b/apps/desktop/src/app/settings/use-settings-search.ts
index afa21893a0..384ef0c8eb 100644
--- a/apps/desktop/src/app/settings/use-settings-search.ts
+++ b/apps/desktop/src/app/settings/use-settings-search.ts
@@ -6,16 +6,16 @@ import { useGatewayRequest } from '@/app/gateway/hooks/use-gateway-request'
 import { $pluginRecords } from '@/contrib/plugins-store'
 import { getEnvVars, getHermesConfigSchema } from '@/hermes'
 import { useI18n } from '@/i18n'
-import { type IconComponent, Monitor, Package, Palette, Settings2, Wrench } from '@/lib/icons'
+import { type IconComponent, Monitor, Package, Settings2, Wrench } from '@/lib/icons'
 import { $agentPlugins, isDesktopRelevantPlugin, loadAgentPlugins } from '@/store/agent-plugins'
 import { $gatewayState } from '@/store/session'
 
 import { useHermesConfigRecord } from '../hooks/use-config-record'
 import { useOnProfileSwitch } from '../hooks/use-on-profile-switch'
 
-import { appearanceSearchTargets } from './appearance-subpages'
 import { SECTIONS } from './constants'
 import { OTHER_SUBPAGES } from './other-subpages'
+import { settingSearchTargets } from './settings-manifest'
 import { buildConfigSearchEntries, buildCredentialSearchEntries, type SettingsSearchEntry } from './settings-search'
 import { settingsSubpages } from './subpages'
 import type { SettingsView } from './types'
@@ -116,18 +116,6 @@ export function useSettingsSearchCatalog(enabled: boolean) {
           sections: t.settings.sections
         })
 
-  const appearanceContext = t.settings.sections.appearance
-
-  // Every hand-built Appearance row, straight from the manifest that also
-  // routes and ids them — the palette cannot drift from the page.
-  const appearanceEntries: SettingsSearchEntry[] = appearanceSearchTargets(t).map(({ id, ...entry }) => ({
-    ...entry,
-    context: appearanceContext,
-    icon: Palette,
-    id: `setting:${id}`,
-    target: { setting: id, view: 'config:appearance' }
-  }))
-
   const credentialEntries = buildCredentialSearchEntries(
     envVarsFetching || envVarsError ? null : envVars,
     {
@@ -142,11 +130,8 @@ export function useSettingsSearchCatalog(enabled: boolean) {
     sessions: t.settings.nav.archivedChats
   }
 
-  // A page named after its one setting (Appearance › Theme) would show up as
-  // two identical rows; the setting wins because it lands on the row itself.
-  const settingLabels = new Set(appearanceEntries.map(entry => `${entry.context}\u0000${entry.label}`))
-
-  const subpageEntries: SettingsSearchEntry[] = [
+  // The pages that own rows: config sections and the standalone views.
+  const parents = [
     ...SECTIONS.map(section => ({
       view: `config:${section.id}` as SettingsView,
       label: t.settings.sections[section.id] ?? section.label,
@@ -158,6 +143,28 @@ export function useSettingsSearchCatalog(enabled: boolean) {
       icon: Settings2
     }))
   ]
+
+  const parentOf = (view: SettingsView) => parents.find(parent => parent.view === view)
+
+  // Every hand-built settings row, straight from the manifest that also
+  // routes and ids them — the palette cannot drift from the pages.
+  const settingEntries: SettingsSearchEntry[] = settingSearchTargets(t).map(({ id, view, ...entry }) => {
+    const parent = parentOf(view)
+
+    return {
+      ...entry,
+      context: parent?.label ?? view,
+      icon: parent?.icon ?? Settings2,
+      id: `setting:${id}`,
+      target: { setting: id, view }
+    }
+  })
+
+  // A page named after its one setting (Appearance › Theme) would show up as
+  // two identical rows; the setting wins because it lands on the row itself.
+  const settingLabels = new Set(settingEntries.map(entry => `${entry.context}\u0000${entry.label}`))
+
+  const subpageEntries: SettingsSearchEntry[] = parents
     .flatMap(parent =>
       settingsSubpages(parent.view).map(page => ({
         context: parent.label,
@@ -171,23 +178,8 @@ export function useSettingsSearchCatalog(enabled: boolean) {
     .filter(entry => !settingLabels.has(`${entry.context}\u0000${entry.label}`))
 
   return {
-    subpageEntries: [
-      ...subpageEntries,
-      ...(window.hermesDesktop?.hudModifier
-        ? [
-            {
-              context: t.keybinds.title,
-              icon: Settings2,
-              id: 'setting:hud-modifier',
-              keywords: ['HUD', 'summon', 'modifier', 'tap', 'Ctrl', 'Alt', 'Command', 'Option'],
-              label: t.settings.hudModifier.title,
-              description: t.settings.hudModifier.description,
-              target: { view: 'keybinds' as const, subpage: 'hud-gesture', setting: 'hud-modifier' }
-            }
-          ]
-        : [])
-    ],
-    appearanceEntries,
+    subpageEntries,
+    settingEntries,
     configEntries,
     credentialEntries,
     pluginEntries

From 983532311f8e06950cdbe6cc4016053cb70f4cd2 Mon Sep 17 00:00:00 2001
From: Mehmet Ali <mxd383@student.bham.ac.uk>
Date: Sat, 5 Sep 2026 00:17:29 +0300
Subject: [PATCH 22/61] fix(agent/gemini): count thinking tokens in usage and
 cost
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`_usage_from_metadata` (agent/gemini_native_adapter.py:476) read
`candidatesTokenCount` for `completion_tokens` and never read
`thoughtsTokenCount`; a repo-wide grep found that field nowhere. Gemini
reports hidden thinking in its own counter — `candidatesTokenCount` covers
visible output only, while `totalTokenCount` already includes thoughts. So on
any thinking turn the emitted usage contradicted itself: prompt + completion
did not add up to total.

Both the non-streaming assembly (translate_gemini_response) and the streaming
one (the finish chunk in translate_stream_event) share this helper, so both
under-billed identically. `normalize_usage` takes `completion_tokens` for
`output_tokens` and looks for reasoning under
`completion_tokens_details.reasoning_tokens`, which the adapter never set, so
the reasoning column read 0 for models whose spend is mostly reasoning.

Thoughts are now folded into `completion_tokens` (OpenAI's counter includes
reasoning) and surfaced under `completion_tokens_details.reasoning_tokens`,
matching the nesting the adapter already uses for
`prompt_tokens_details.cached_tokens`. The field is absent on non-thinking and
older responses; those count 0 and their numbers do not move.

Live: for usageMetadata {prompt 10, candidates 200, thoughts 5000, total 5210}
the adapter emitted completion_tokens=200 (10 + 200 != 5210) and
normalize_usage returned output_tokens=200, reasoning_tokens=0. It now emits
completion_tokens=5200 (10 + 5200 == 5210) with
completion_tokens_details.reasoning_tokens=5000, and normalize_usage returns
output_tokens=5200, reasoning_tokens=5000.
---
 agent/gemini_native_adapter.py            | 13 +++-
 tests/agent/test_gemini_native_adapter.py | 73 +++++++++++++++++++++++
 2 files changed, 85 insertions(+), 1 deletion(-)

diff --git a/agent/gemini_native_adapter.py b/agent/gemini_native_adapter.py
index d06255bc1e..35385fb677 100644
--- a/agent/gemini_native_adapter.py
+++ b/agent/gemini_native_adapter.py
@@ -551,10 +551,21 @@ def _dump_call_args(fc: Dict[str, Any], **kwargs: Any) -> str:
 
 
 def _usage_from_metadata(usage_meta: Dict[str, Any]) -> SimpleNamespace:
+    """Gemini ``usageMetadata`` → OpenAI-shaped usage.
+
+    Hidden thinking is reported separately in ``thoughtsTokenCount``:
+    ``candidatesTokenCount`` counts visible output only, while ``totalTokenCount``
+    already includes thoughts. OpenAI's ``completion_tokens`` covers reasoning, so
+    thoughts are folded in (otherwise a thinking turn bills a few percent of its
+    real output and ``prompt + completion != total``) and also surfaced under
+    ``completion_tokens_details.reasoning_tokens``, where ``normalize_usage`` reads
+    them. Absent on non-thinking/older responses, which keeps their numbers as-is."""
     count = lambda key: int(usage_meta.get(key) or 0)  # noqa: E731
+    reasoning_tokens = count("thoughtsTokenCount")
     return SimpleNamespace(
-        prompt_tokens=count("promptTokenCount"), completion_tokens=count("candidatesTokenCount"),
+        prompt_tokens=count("promptTokenCount"), completion_tokens=count("candidatesTokenCount") + reasoning_tokens,
         total_tokens=count("totalTokenCount"), prompt_tokens_details=SimpleNamespace(cached_tokens=count("cachedContentTokenCount")),
+        completion_tokens_details=SimpleNamespace(reasoning_tokens=reasoning_tokens),
     )
 
 
diff --git a/tests/agent/test_gemini_native_adapter.py b/tests/agent/test_gemini_native_adapter.py
index f218584ec0..5d65cd4d7a 100644
--- a/tests/agent/test_gemini_native_adapter.py
+++ b/tests/agent/test_gemini_native_adapter.py
@@ -819,3 +819,76 @@ def test_native_gemini_detection_covers_express_but_not_vertex_oauth_openapi():
     assert not is_native_gemini_base_url(
         "https://aiplatform.googleapis.com/v1beta1/projects/p/locations/global/endpoints/openapi"
     )
+
+
+def test_thinking_tokens_are_counted_as_output_and_surfaced_as_reasoning():
+    """Gemini bills hidden thinking under its own ``thoughtsTokenCount``;
+    ``candidatesTokenCount`` covers visible output only while ``totalTokenCount``
+    includes thoughts. Dropping thoughts made the emitted usage internally
+    inconsistent (prompt + completion != total) and billed a thinking turn at a
+    fraction of its real output."""
+    from agent.gemini_native_adapter import translate_gemini_response
+    from agent.usage_pricing import normalize_usage
+
+    prompt, visible, thoughts = 10, 200, 5000
+    payload = {
+        "candidates": [{"content": {"parts": [{"text": "done"}]}, "finishReason": "STOP"}],
+        "usageMetadata": {
+            "promptTokenCount": prompt,
+            "candidatesTokenCount": visible,
+            "thoughtsTokenCount": thoughts,
+            "totalTokenCount": prompt + visible + thoughts,
+        },
+    }
+
+    usage = translate_gemini_response(payload, model="gemini-2.5-flash").usage
+    assert usage.prompt_tokens + usage.completion_tokens == usage.total_tokens
+    assert usage.completion_tokens_details.reasoning_tokens == thoughts
+
+    canonical = normalize_usage(usage, provider="google")
+    assert canonical.output_tokens == visible + thoughts
+    assert canonical.reasoning_tokens == thoughts
+
+
+def test_streaming_usage_counts_thinking_tokens_like_the_non_streaming_path():
+    """Usage rides on the stream's finish chunk; it must agree with the
+    non-streaming assembly rather than under-reporting thinking."""
+    from agent.gemini_native_adapter import translate_stream_event
+
+    prompt, visible, thoughts = 7, 3, 900
+    event = {
+        "candidates": [{"content": {"parts": [{"text": "done"}]}, "finishReason": "STOP"}],
+        "usageMetadata": {
+            "promptTokenCount": prompt,
+            "candidatesTokenCount": visible,
+            "thoughtsTokenCount": thoughts,
+            "totalTokenCount": prompt + visible + thoughts,
+        },
+    }
+
+    chunks = translate_stream_event(event, model="gemini-2.5-flash", tool_call_indices={})
+    usage = chunks[-1].usage
+    assert usage.prompt_tokens + usage.completion_tokens == usage.total_tokens
+    assert usage.completion_tokens_details.reasoning_tokens == thoughts
+
+
+def test_response_without_thinking_tokens_keeps_its_output_count():
+    """Non-thinking / older responses omit ``thoughtsTokenCount``; their numbers
+    must not move, and reasoning stays zero."""
+    from agent.gemini_native_adapter import translate_gemini_response
+    from agent.usage_pricing import normalize_usage
+
+    prompt, visible = 10, 5
+    payload = {
+        "candidates": [{"content": {"parts": [{"text": "hi"}]}, "finishReason": "STOP"}],
+        "usageMetadata": {
+            "promptTokenCount": prompt,
+            "candidatesTokenCount": visible,
+            "totalTokenCount": prompt + visible,
+        },
+    }
+
+    usage = translate_gemini_response(payload, model="gemini-2.5-flash").usage
+    assert usage.completion_tokens == visible
+    assert usage.prompt_tokens + usage.completion_tokens == usage.total_tokens
+    assert normalize_usage(usage, provider="google").reasoning_tokens == 0

From a980c35fad0ff2d9aedf1609661eaff92dc90f05 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:38:02 -0700
Subject: [PATCH 23/61] test(gemini): trim salvaged thinking-token tests to the
 two invariants

Keep the non-streaming invariant (prompt + completion == total, thoughts
surfaced as reasoning_tokens) and the no-thoughts control; the streaming
case exercised the same _usage_from_metadata helper and added no new
property.
---
 tests/agent/test_gemini_native_adapter.py | 22 ----------------------
 1 file changed, 22 deletions(-)

diff --git a/tests/agent/test_gemini_native_adapter.py b/tests/agent/test_gemini_native_adapter.py
index 5d65cd4d7a..145cc4289e 100644
--- a/tests/agent/test_gemini_native_adapter.py
+++ b/tests/agent/test_gemini_native_adapter.py
@@ -850,28 +850,6 @@ def test_thinking_tokens_are_counted_as_output_and_surfaced_as_reasoning():
     assert canonical.reasoning_tokens == thoughts
 
 
-def test_streaming_usage_counts_thinking_tokens_like_the_non_streaming_path():
-    """Usage rides on the stream's finish chunk; it must agree with the
-    non-streaming assembly rather than under-reporting thinking."""
-    from agent.gemini_native_adapter import translate_stream_event
-
-    prompt, visible, thoughts = 7, 3, 900
-    event = {
-        "candidates": [{"content": {"parts": [{"text": "done"}]}, "finishReason": "STOP"}],
-        "usageMetadata": {
-            "promptTokenCount": prompt,
-            "candidatesTokenCount": visible,
-            "thoughtsTokenCount": thoughts,
-            "totalTokenCount": prompt + visible + thoughts,
-        },
-    }
-
-    chunks = translate_stream_event(event, model="gemini-2.5-flash", tool_call_indices={})
-    usage = chunks[-1].usage
-    assert usage.prompt_tokens + usage.completion_tokens == usage.total_tokens
-    assert usage.completion_tokens_details.reasoning_tokens == thoughts
-
-
 def test_response_without_thinking_tokens_keeps_its_output_count():
     """Non-thinking / older responses omit ``thoughtsTokenCount``; their numbers
     must not move, and reasoning stays zero."""

From 2364cde85a9c8d44a66e5ced05d025198f66542e Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:38:09 -0700
Subject: [PATCH 24/61] chore(contributors): map Maero47's commit email

---
 contributors/emails/mxd383@student.bham.ac.uk | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/mxd383@student.bham.ac.uk

diff --git a/contributors/emails/mxd383@student.bham.ac.uk b/contributors/emails/mxd383@student.bham.ac.uk
new file mode 100644
index 0000000000..bc7c729937
--- /dev/null
+++ b/contributors/emails/mxd383@student.bham.ac.uk
@@ -0,0 +1 @@
+Maero47

From 994074c789adf0fb380553c24fec2bdd5abee600 Mon Sep 17 00:00:00 2001
From: BearHuddleston <bear@bearhuddleston.dev>
Date: Tue, 22 Sep 2026 08:50:35 -0500
Subject: [PATCH 25/61] fix(desktop): retain provider setup connection and
 profile ownership

---
 apps/desktop/e2e/provider-setup-owner.spec.ts | 451 ++++++++++++++++++
 apps/desktop/src/api/config.ts                |  41 +-
 apps/desktop/src/api/models.ts                |  21 +-
 .../src/app/settings/model-settings.test.tsx  |  18 +-
 .../src/app/settings/model-settings.tsx       |   8 +-
 apps/desktop/src/components/model-picker.tsx  |   7 +-
 .../onboarding/connection-owner.test.tsx      | 183 +++++++
 .../src/components/onboarding/flow.tsx        |  18 +-
 .../src/components/onboarding/index.tsx       |  31 +-
 apps/desktop/src/store/model-assignment.ts    |   4 +-
 .../src/store/onboarding-owner.test.ts        | 183 +++++++
 apps/desktop/src/store/onboarding-scope.ts    |  54 +++
 apps/desktop/src/store/onboarding.test.ts     |   2 +-
 apps/desktop/src/store/onboarding.ts          |  86 ++--
 14 files changed, 1007 insertions(+), 100 deletions(-)
 create mode 100644 apps/desktop/e2e/provider-setup-owner.spec.ts
 create mode 100644 apps/desktop/src/components/onboarding/connection-owner.test.tsx
 create mode 100644 apps/desktop/src/store/onboarding-owner.test.ts
 create mode 100644 apps/desktop/src/store/onboarding-scope.ts

diff --git a/apps/desktop/e2e/provider-setup-owner.spec.ts b/apps/desktop/e2e/provider-setup-owner.spec.ts
new file mode 100644
index 0000000000..4141b840a6
--- /dev/null
+++ b/apps/desktop/e2e/provider-setup-owner.spec.ts
@@ -0,0 +1,451 @@
+/**
+ * Provider setup must keep the Settings owner's gateway AND profile.
+ * Two real serve backends; only OpenAI-compatible model discovery is a fixture.
+ * Build dist/ separately, then run this spec with HERMES_DESKTOP_PYTHON pointing
+ * at a dependency-complete interpreter. No OAuth account or inference is used.
+ */
+import { type ChildProcess, spawn, spawnSync } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as http from 'node:http'
+import * as net from 'node:net'
+import * as path from 'node:path'
+
+import { createSandbox, findElectron, type Sandbox } from './fixtures'
+import {
+  _electron,
+  collectErrorBanners,
+  type ElectronApplication,
+  expect,
+  installErrorBannerGuard,
+  type Page,
+  test
+} from './test'
+
+const DESKTOP_ROOT = path.resolve(import.meta.dirname, '..')
+const REPO_ROOT = path.resolve(DESKTOP_ROOT, '..', '..')
+const REMOTE_ID = 'athena-fixture'
+const REMOTE_LABEL = 'Athena fixture'
+const PROFILE = 'leverage-ai'
+const REMOTE_TOKEN = 'provider-owner-fixture-token'
+
+interface RpcReceipt {
+  endpoint: string
+  socketProfile: string | null
+  method: string
+  params: Record<string, unknown>
+  result?: unknown
+  error?: unknown
+}
+
+function isolatedEnv(home: string, hermesHome: string): Record<string, string> {
+  // Allowlist rather than inheriting real provider keys, profile selection,
+  // browser account state, live desktop overrides, or the host session bus.
+  const env: Record<string, string> = {
+    PATH: process.env.PATH ?? '',
+    HOME: home,
+    USERPROFILE: home,
+    HERMES_HOME: hermesHome,
+    PYTHONPATH: REPO_ROOT,
+    PYTHONNOUSERSITE: '1',
+    PYTHONDONTWRITEBYTECODE: '1',
+    TMPDIR: process.env.TMPDIR ?? path.dirname(home),
+    LANG: 'C.UTF-8',
+    TZ: 'UTC',
+    XDG_SESSION_TYPE: 'x11',
+    ELECTRON_OZONE_PLATFORM_HINT: 'x11'
+  }
+
+  for (const key of ['DISPLAY', 'XAUTHORITY', 'TEST_WORKER_INDEX', 'SYSTEMROOT', 'WINDIR']) {
+    if (process.env[key]) {
+      env[key] = process.env[key]!
+    }
+  }
+
+  for (const kind of ['CONFIG', 'CACHE', 'DATA', 'STATE', 'RUNTIME']) {
+    const dir = path.join(home, `xdg-${kind.toLowerCase()}`)
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+    env[`XDG_${kind}_${kind === 'RUNTIME' ? 'DIR' : 'HOME'}`] = dir
+  }
+
+  return env
+}
+
+function pythonBinary(): string {
+  const python =
+    process.env.HERMES_DESKTOP_PYTHON ??
+    path.join(REPO_ROOT, '.venv', process.platform === 'win32' ? 'Scripts/python.exe' : 'bin/python')
+
+  if (!fs.existsSync(python)) {
+    throw new Error('Set HERMES_DESKTOP_PYTHON to an isolated dependency-complete interpreter')
+  }
+
+  return python
+}
+
+function verifyImports(python: string, env: Record<string, string>): string {
+  const probe = spawnSync(
+    python,
+    [
+      '-c',
+      [
+        'import json, pathlib, sys',
+        'import hermes_cli.main, hermes_cli.web_server, tui_gateway.server',
+        'root = pathlib.Path.cwd().resolve()',
+        'paths = {name: str(pathlib.Path(sys.modules[name].__file__).resolve()) for name in ("hermes_cli.main", "hermes_cli.web_server", "tui_gateway.server")}',
+        'assert all(pathlib.Path(p).is_relative_to(root) for p in paths.values()), paths',
+        'sys.__stdout__.write(json.dumps(paths))'
+      ].join('\n')
+    ],
+    { cwd: REPO_ROOT, env, encoding: 'utf8', timeout: 60_000 }
+  )
+
+  expect(probe.status, probe.stderr).toBe(0)
+
+  return probe.stdout
+}
+
+function seedConfig(home: string, endpoint: string, model: string): void {
+  fs.mkdirSync(home, { recursive: true })
+  // JSON is YAML, and these fixtures need no secret file at all.
+  fs.writeFileSync(
+    path.join(home, 'config.yaml'),
+    JSON.stringify(
+      {
+        model: { provider: 'custom', default: model, base_url: `${endpoint}/v1` },
+        auxiliary: { title_generation: { enabled: false } }
+      },
+      null,
+      2
+    )
+  )
+}
+
+function configModel(python: string, env: Record<string, string>, home: string): unknown {
+  const read = spawnSync(
+    python,
+    [
+      '-c',
+      'import json, pathlib, sys, yaml; print(json.dumps(yaml.safe_load(pathlib.Path(sys.argv[1]).read_text())["model"]))',
+      path.join(home, 'config.yaml')
+    ],
+    { cwd: REPO_ROOT, env, encoding: 'utf8', timeout: 10_000 }
+  )
+
+  expect(read.status, read.stderr).toBe(0)
+
+  return JSON.parse(read.stdout)
+}
+
+async function listen(server: net.Server): Promise<number> {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => resolve((server.address() as net.AddressInfo).port))
+  })
+}
+
+async function stopChild(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return
+  }
+
+  await new Promise<void>(resolve => {
+    const timer = setTimeout(() => child.kill('SIGKILL'), 10_000)
+    child.once('exit', () => {
+      clearTimeout(timer)
+      resolve()
+    })
+    child.kill('SIGTERM')
+  })
+}
+
+async function startRemote(python: string, env: Record<string, string>, logPath: string) {
+  const reservation = net.createServer()
+  const port = await listen(reservation)
+  await new Promise<void>(resolve => reservation.close(() => resolve()))
+  const url = `http://127.0.0.1:${port}`
+  const log = fs.openSync(logPath, 'w')
+
+  const child = spawn(
+    python,
+    ['-m', 'hermes_cli.main', 'serve', '--isolated', '--host', '127.0.0.1', '--port', String(port), '--skip-build'],
+    {
+      cwd: REPO_ROOT,
+      env: { ...env, HERMES_DASHBOARD_SESSION_TOKEN: REMOTE_TOKEN },
+      stdio: ['ignore', log, log]
+    }
+  )
+
+  fs.closeSync(log)
+
+  try {
+    await expect
+      .poll(
+        async () => {
+          if (child.exitCode !== null) {
+            throw new Error(`Remote serve exited: ${child.exitCode}; see ${logPath}`)
+          }
+
+          return fetch(`${url}/api/status`, {
+            headers: { 'X-Hermes-Session-Token': REMOTE_TOKEN },
+            signal: AbortSignal.timeout(2_000)
+          })
+            .then(response => response.status)
+            .catch(() => 0)
+        },
+        { timeout: 90_000, intervals: [200, 500, 1000] }
+      )
+      .toBe(200)
+  } catch (error) {
+    await stopChild(child)
+    throw error
+  }
+
+  return { url, child }
+}
+
+function watchRpc(page: Page, receipts: RpcReceipt[]): void {
+  page.on('websocket', socket => {
+    const url = new URL(socket.url())
+    const pending = new Map<unknown, RpcReceipt>()
+    socket.on('framesent', ({ payload }) => {
+      const message = JSON.parse(payload.toString())
+
+      if (!message.method) {
+        return
+      }
+
+      const receipt: RpcReceipt = {
+        endpoint: url.origin,
+        socketProfile: url.searchParams.get('profile'),
+        method: message.method,
+        params: message.params ?? {}
+      }
+
+      receipts.push(receipt)
+      pending.set(message.id, receipt)
+    })
+    socket.on('framereceived', ({ payload }) => {
+      const message = JSON.parse(payload.toString())
+      const receipt = pending.get(message.id)
+
+      if (receipt) {
+        receipt.result = message.result
+        receipt.error = message.error
+      }
+    })
+  })
+}
+
+const gatewayGroup = (page: Page, id: string) =>
+  page.locator(`[data-slot="profile-rail-gateway"][data-connection-id="${id}"]`)
+
+async function selectGateway(page: Page, id: string, label: string, profile: string): Promise<void> {
+  const group = gatewayGroup(page, id)
+  await expect(group).toBeVisible({ timeout: 60_000 })
+  await group.getByRole('button', { name: `${profile} · ${label}`, exact: true }).click()
+  await expect(page.getByRole('button', { name: /^Registered gateways: / })).toHaveAttribute(
+    'aria-label',
+    `Registered gateways: ${label}`,
+    { timeout: 90_000 }
+  )
+  await expect(group).toHaveAttribute('data-active', 'true')
+  await expect(group.getByRole('button', { name: profile, exact: true })).toHaveAttribute('aria-pressed', 'true')
+  await expect(page.locator('[data-slot="statusbar"]').getByText('ready', { exact: true })).toBeVisible({
+    timeout: 60_000
+  })
+}
+
+async function openProviderKeys(page: Page): Promise<void> {
+  await page.getByRole('button', { name: 'Open settings', exact: true }).click()
+  await page.getByRole('button', { name: 'Providers', exact: true }).click()
+  await page.getByRole('button', { name: 'API keys', exact: true }).click()
+  await expect(page.getByRole('button', { name: /^Local \/ custom endpoint/ })).toBeVisible()
+}
+
+test('Settings provider setup stays on its gateway/profile across A → B → A', async () => {
+  test.setTimeout(300_000)
+  const original = createSandbox('provider-owner')
+  const localHome = path.join(original.root, 'local')
+  const remoteHome = path.join(original.root, 'remote')
+  const sandbox: Sandbox = { ...original, hermesHome: path.join(localHome, '.hermes') }
+  const remoteHermesHome = path.join(remoteHome, '.hermes')
+  const remoteProfileHome = path.join(remoteHermesHome, 'profiles', PROFILE)
+  const python = pythonBinary()
+  const localEnv = isolatedEnv(localHome, sandbox.hermesHome)
+  const remoteEnv = isolatedEnv(remoteHome, remoteHermesHome)
+  const receipts: RpcReceipt[] = []
+  const discoveryRequests: string[] = []
+  let advertisedModel = 'remote-first'
+
+  const endpoint = http.createServer((request, response) => {
+    discoveryRequests.push(request.url ?? '')
+    // Discovery only. An unexpected inference request must not look successful.
+    response.writeHead(request.url === '/v1/models' ? 200 : 404, { 'Content-Type': 'application/json' })
+    response.end(
+      JSON.stringify(
+        request.url === '/v1/models'
+          ? { object: 'list', data: [{ id: advertisedModel, object: 'model', owned_by: 'e2e-fixture' }] }
+          : { error: 'This regression fixture only serves model discovery' }
+      )
+    )
+  })
+
+  let app: ElectronApplication | undefined
+  let page: Page | undefined
+  let remote: Awaited<ReturnType<typeof startRemote>> | undefined
+
+  try {
+    const endpointUrl = `http://127.0.0.1:${await listen(endpoint)}`
+    seedConfig(sandbox.hermesHome, endpointUrl, 'local-sentinel')
+    seedConfig(remoteHermesHome, endpointUrl, 'remote-default-sentinel')
+    seedConfig(remoteProfileHome, endpointUrl, 'remote-before-setup')
+    await test
+      .info()
+      .attach('worktree-imports', { body: verifyImports(python, remoteEnv), contentType: 'application/json' })
+    remote = await startRemote(python, remoteEnv, test.info().outputPath('remote-serve.log'))
+    fs.writeFileSync(
+      path.join(sandbox.userDataDir, 'connections.json'),
+      JSON.stringify({
+        version: 2,
+        primary: 'local',
+        launchMode: 'primary',
+        lastUsed: 'local',
+        connections: [
+          { id: 'local', kind: 'local', label: 'This device' },
+          {
+            id: REMOTE_ID,
+            kind: 'remote',
+            label: REMOTE_LABEL,
+            url: remote.url,
+            authMode: 'token',
+            token: { encoding: 'plain', value: REMOTE_TOKEN }
+          }
+        ]
+      })
+    )
+    expect(fs.existsSync(path.join(DESKTOP_ROOT, 'dist/electron-main.mjs')), 'Build desktop dist before E2E').toBe(true)
+    app = await _electron.launch({
+      executablePath: findElectron(),
+      args: [DESKTOP_ROOT, '--disable-gpu', '--no-sandbox'],
+      cwd: DESKTOP_ROOT,
+      ...(process.env.PROVIDER_SETUP_VIDEO === '1'
+        ? {
+            recordVideo: { dir: test.info().outputPath('video'), size: { width: 1220, height: 800 } }
+          }
+        : {}),
+      env: {
+        ...localEnv,
+        HERMES_DESKTOP_PYTHON: python,
+        HERMES_DESKTOP_USER_DATA_DIR: sandbox.userDataDir,
+        HERMES_DESKTOP_IGNORE_EXISTING: '1',
+        HERMES_DESKTOP_HERMES_ROOT: REPO_ROOT,
+        HERMES_DESKTOP_APP_NAME: `ProviderOwnerE2E-${Date.now()}`,
+        HERMES_DESKTOP_SKIP_QUIT_CONFIRM: '1'
+      }
+    })
+    page = await app.firstWindow()
+    installErrorBannerGuard(page)
+    watchRpc(page, receipts)
+    await expect(page.getByRole('button', { name: 'Open settings', exact: true })).toBeVisible({ timeout: 90_000 })
+    await expect(page.locator('[data-slot="statusbar"]').getByText('ready', { exact: true })).toBeVisible({
+      timeout: 60_000
+    })
+    const localConfig = fs.readFileSync(path.join(sandbox.hermesHome, 'config.yaml'), 'utf8')
+    const remoteDefault = fs.readFileSync(path.join(remoteHermesHome, 'config.yaml'), 'utf8')
+
+    const localProfiles = () =>
+      fs.existsSync(path.join(sandbox.hermesHome, 'profiles'))
+        ? fs.readdirSync(path.join(sandbox.hermesHome, 'profiles')).sort()
+        : []
+
+    expect(localProfiles()).toEqual([])
+
+    // A: inspect the local default through Settings, without changing it.
+    await openProviderKeys(page)
+    await page.getByRole('button', { name: 'Close settings', exact: true }).click()
+    await selectGateway(page, REMOTE_ID, REMOTE_LABEL, PROFILE)
+
+    for (const model of ['remote-first', 'remote-second']) {
+      advertisedModel = model
+      await openProviderKeys(page)
+      await expect(page.getByText(new RegExp(`Changes on this page apply to.*${PROFILE}`))).toBeVisible()
+      await page.getByRole('button', { name: /^Local \/ custom endpoint/ }).click()
+      const input = page.getByPlaceholder('http://127.0.0.1:8000/v1')
+      await expect(input).toBeVisible()
+      await input.fill(`${endpointUrl}/v1`)
+      await input.scrollIntoViewIfNeeded()
+      await page.screenshot({ path: test.info().outputPath(`${model}-endpoint-form.png`) })
+      const start = receipts.length
+      await page.getByRole('button', { name: 'Connect', exact: true }).click()
+      await expect(input).toBeHidden({ timeout: 45_000 })
+      await expect
+        .poll(() => configModel(python, remoteEnv, remoteProfileHome))
+        .toMatchObject({
+          provider: expect.stringMatching(/^custom(?::.+)?$/),
+          default: model,
+          base_url: `${endpointUrl}/v1`
+        })
+
+      const setupCalls = receipts
+        .slice(start)
+        .filter(row => ['reload.env', 'setup.status', 'setup.runtime_check'].includes(row.method))
+
+      // A scoped setup must not mutate the launch profile's process environment.
+      expect(setupCalls.some(row => row.method === 'reload.env')).toBe(false)
+
+      for (const method of ['setup.status', 'setup.runtime_check']) {
+        const calls = setupCalls.filter(row => row.method === method)
+        expect(calls, `wire request for ${method}`).not.toHaveLength(0)
+
+        for (const call of calls) {
+          expect(new URL(call.endpoint).host).toBe(new URL(remote.url).host)
+          expect(call.params.profile).toBe(PROFILE)
+          expect(call.error).toBeUndefined()
+        }
+      }
+
+      expect
+        .soft(
+          setupCalls.find(row => row.method === 'setup.runtime_check')?.result,
+          'readiness must resolve the model just saved in the owning profile'
+        )
+        .toMatchObject({ ok: true, model, profile: PROFILE })
+      expect(fs.readFileSync(path.join(sandbox.hermesHome, 'config.yaml'), 'utf8')).toBe(localConfig)
+      expect(localProfiles()).toEqual([])
+      expect(fs.readFileSync(path.join(remoteHermesHome, 'config.yaml'), 'utf8')).toBe(remoteDefault)
+      await page.screenshot({ path: test.info().outputPath(`${model}-saved.png`) })
+      await page.getByRole('button', { name: 'Close settings', exact: true }).click()
+      await selectGateway(page, 'local', 'This device', 'default')
+      await openProviderKeys(page)
+      expect(configModel(python, localEnv, sandbox.hermesHome)).toMatchObject({ default: 'local-sentinel' })
+      await page.screenshot({ path: test.info().outputPath(`${model}-back-on-local.png`) })
+      await page.getByRole('button', { name: 'Close settings', exact: true }).click()
+
+      if (model === 'remote-first') {
+        await selectGateway(page, REMOTE_ID, REMOTE_LABEL, PROFILE)
+      }
+    }
+
+    expect(discoveryRequests).toContain('/v1/models')
+    expect(await collectErrorBanners(page)).toEqual([])
+  } finally {
+    if (page && !page.isClosed()) {
+      await test.info().attach('last-ui', { body: await page.locator('body').innerText(), contentType: 'text/plain' })
+      await page.screenshot({ path: test.info().outputPath('last-ui.png') })
+      await collectErrorBanners(page)
+    }
+
+    fs.writeFileSync(test.info().outputPath('setup-wire.json'), JSON.stringify(receipts, null, 2))
+    await test
+      .info()
+      .attach('setup-wire', { path: test.info().outputPath('setup-wire.json'), contentType: 'application/json' })
+    await app?.close()
+
+    if (remote) {
+      await stopChild(remote.child)
+    }
+
+    await new Promise<void>(resolve => endpoint.close(() => resolve()))
+    sandbox.cleanup()
+  }
+})
diff --git a/apps/desktop/src/api/config.ts b/apps/desktop/src/api/config.ts
index f0ce96655f..d17f4a4d2e 100644
--- a/apps/desktop/src/api/config.ts
+++ b/apps/desktop/src/api/config.ts
@@ -238,16 +238,21 @@ export function revealEnvVar(key: string, profile?: ProfileScope): Promise<{ key
 export function validateProviderCredential(
   key: string,
   value: string,
-  apiKey?: string
+  apiKey?: string,
+  profile?: ProfileScope
 ): Promise<{ ok: boolean; reachable: boolean; message: string; models?: string[]; resolved_base_url?: string }> {
-  return hermesApi<{ ok: boolean; reachable: boolean; message: string; models?: string[]; resolved_base_url?: string }>(
-    {
-      ...profileScoped(),
-      path: '/api/providers/validate',
-      method: 'POST',
-      body: { key, value, api_key: apiKey ?? '' }
-    }
-  )
+  return window.hermesDesktop.api<{
+    ok: boolean
+    reachable: boolean
+    message: string
+    models?: string[]
+    resolved_base_url?: string
+  }>({
+    ...capabilityScoped(profile),
+    path: '/api/providers/validate',
+    method: 'POST',
+    body: { key, value, api_key: apiKey ?? '' }
+  })
 }
 
 export function getCustomEndpoints(profile?: null | string): Promise<CustomEndpointsResponse> {
@@ -300,9 +305,9 @@ export function deleteCustomEndpoint(id: string, profile?: null | string): Promi
   })
 }
 
-export function listOAuthProviders(profile?: null | string): Promise<OAuthProvidersResponse> {
-  return hermesApi<OAuthProvidersResponse>({
-    ...profileScoped(profile),
+export function listOAuthProviders(profile?: ProfileScope): Promise<OAuthProvidersResponse> {
+  return window.hermesDesktop.api<OAuthProvidersResponse>({
+    ...capabilityScoped(profile),
     path: '/api/providers/oauth'
   })
 }
@@ -331,10 +336,10 @@ export function submitOAuthCode(
   providerId: string,
   sessionId: string,
   code: string,
-  profile?: null | string
+  profile?: ProfileScope
 ): Promise<OAuthSubmitResponse> {
-  return hermesApi<OAuthSubmitResponse>({
-    ...profileScoped(profile),
+  return window.hermesDesktop.api<OAuthSubmitResponse>({
+    ...capabilityScoped(profile),
     path: `/api/providers/oauth/${encodeURIComponent(providerId)}/submit`,
     method: 'POST',
     body: { session_id: sessionId, code }
@@ -352,9 +357,9 @@ export function pollOAuthSession(
   })
 }
 
-export function cancelOAuthSession(sessionId: string, profile?: null | string): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    ...profileScoped(profile),
+export function cancelOAuthSession(sessionId: string, profile?: ProfileScope): Promise<{ ok: boolean }> {
+  return window.hermesDesktop.api<{ ok: boolean }>({
+    ...capabilityScoped(profile),
     path: `/api/providers/oauth/sessions/${encodeURIComponent(sessionId)}`,
     method: 'DELETE'
   })
diff --git a/apps/desktop/src/api/models.ts b/apps/desktop/src/api/models.ts
index 9f3e34ecf8..6f38cfcc2d 100644
--- a/apps/desktop/src/api/models.ts
+++ b/apps/desktop/src/api/models.ts
@@ -32,7 +32,7 @@ export function getGlobalModelOptions(
     includeUnconfigured?: boolean
     explicitOnly?: boolean
   },
-  profile?: null | string
+  profile?: ProfileScope
 ): Promise<ModelOptionsResult> {
   const params = new URLSearchParams()
 
@@ -48,8 +48,8 @@ export function getGlobalModelOptions(
     params.set('explicit_only', '1')
   }
 
-  return hermesApi<ModelOptionsResult>({
-    ...profileScoped(profile),
+  return window.hermesDesktop.api<ModelOptionsResult>({
+    ...capabilityScoped(profile),
     path: params.size > 0 ? `/api/model/options?${params.toString()}` : '/api/model/options',
     timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
   })
@@ -65,12 +65,9 @@ export interface RecommendedDefaultModel {
 // Recommended default model for a freshly-authenticated provider. Mirrors the
 // curation `hermes model` does — for Nous it honors the free/paid tier so a
 // free user gets a free model instead of a paid default.
-export function getRecommendedDefaultModel(
-  provider: string,
-  profile?: null | string
-): Promise<RecommendedDefaultModel> {
-  return hermesApi<RecommendedDefaultModel>({
-    ...profileScoped(profile),
+export function getRecommendedDefaultModel(provider: string, profile?: ProfileScope): Promise<RecommendedDefaultModel> {
+  return window.hermesDesktop.api<RecommendedDefaultModel>({
+    ...capabilityScoped(profile),
     path: `/api/model/recommended-default?provider=${encodeURIComponent(provider)}`
   })
 }
@@ -119,10 +116,10 @@ export function saveMoaModels(
 
 export function setModelAssignment(
   body: ModelAssignmentRequest,
-  profile?: null | string
+  profile?: ProfileScope
 ): Promise<ModelAssignmentResponse> {
-  return hermesApi<ModelAssignmentResponse>({
-    ...profileScoped(profile),
+  return window.hermesDesktop.api<ModelAssignmentResponse>({
+    ...capabilityScoped(profile),
     path: '/api/model/set',
     method: 'POST',
     body
diff --git a/apps/desktop/src/app/settings/model-settings.test.tsx b/apps/desktop/src/app/settings/model-settings.test.tsx
index 653ae73585..c7a59dd32e 100644
--- a/apps/desktop/src/app/settings/model-settings.test.tsx
+++ b/apps/desktop/src/app/settings/model-settings.test.tsx
@@ -49,9 +49,9 @@ vi.mock('@/hermes', async () => ({
 }))
 
 vi.mock('@/store/onboarding', () => ({
-  startManualLocalEndpoint: () => startManualLocalEndpoint(),
-  startManualOnboarding: () => startManualOnboarding(),
-  startManualProviderOAuth: (slug: string) => startManualProviderOAuth(slug)
+  startManualLocalEndpoint: (...args: unknown[]) => startManualLocalEndpoint(...args),
+  startManualOnboarding: (...args: unknown[]) => startManualOnboarding(...args),
+  startManualProviderOAuth: (...args: unknown[]) => startManualProviderOAuth(...args)
 }))
 
 vi.mock('../hooks/use-on-profile-switch', () => ({
@@ -137,7 +137,7 @@ describe('ModelSettings', () => {
       getGlobalModelInfo.mockResolvedValueOnce({ provider, model: '' })
       getGlobalModelOptions.mockResolvedValueOnce({ providers: [] })
 
-      await renderModelSettings()
+      await renderModelSettings('leverage-ai')
 
       const providerSelect = (await screen.findAllByRole('combobox'))[0]
 
@@ -148,6 +148,7 @@ describe('ModelSettings', () => {
       fireEvent.click(await screen.findByRole('button', { name: 'Set up provider' }))
 
       expect(startManualLocalEndpoint).toHaveBeenCalledOnce()
+      expect(startManualLocalEndpoint).toHaveBeenCalledWith(null, 'leverage-ai')
       expect(startManualOnboarding).not.toHaveBeenCalled()
       expect(startManualProviderOAuth).not.toHaveBeenCalled()
     }
@@ -157,16 +158,17 @@ describe('ModelSettings', () => {
     getGlobalModelInfo.mockResolvedValueOnce({ provider: 'retired-provider', model: '' })
     getGlobalModelOptions.mockResolvedValueOnce({ providers: [] })
 
-    await renderModelSettings()
+    await renderModelSettings('leverage-ai')
 
     fireEvent.click(await screen.findByRole('button', { name: 'Set up provider' }))
 
     expect(startManualOnboarding).toHaveBeenCalledOnce()
+    expect(startManualOnboarding).toHaveBeenCalledWith(undefined, 'leverage-ai')
     expect(startManualLocalEndpoint).not.toHaveBeenCalled()
     expect(startManualProviderOAuth).not.toHaveBeenCalled()
   })
 
-  it('deep-links a known OAuth provider row into its setup flow', async () => {
+  it('deep-links a known OAuth provider row into its scoped setup flow', async () => {
     getGlobalModelInfo.mockResolvedValueOnce({ provider: 'anthropic', model: '' })
     getGlobalModelOptions.mockResolvedValueOnce({
       providers: [
@@ -180,11 +182,11 @@ describe('ModelSettings', () => {
       ]
     })
 
-    await renderModelSettings()
+    await renderModelSettings('leverage-ai')
 
     fireEvent.click(await screen.findByRole('button', { name: 'Set up Anthropic' }))
 
-    expect(startManualProviderOAuth).toHaveBeenCalledWith('anthropic')
+    expect(startManualProviderOAuth).toHaveBeenCalledWith('anthropic', 'leverage-ai')
     expect(startManualLocalEndpoint).not.toHaveBeenCalled()
     expect(startManualOnboarding).not.toHaveBeenCalled()
   })
diff --git a/apps/desktop/src/app/settings/model-settings.tsx b/apps/desktop/src/app/settings/model-settings.tsx
index c984f0a911..9b0663b17c 100644
--- a/apps/desktop/src/app/settings/model-settings.tsx
+++ b/apps/desktop/src/app/settings/model-settings.tsx
@@ -658,15 +658,15 @@ export function ModelSettings({ onMainModelChanged, scopeProfile, subpage }: Mod
     const lower = slug.toLowerCase()
 
     if (lower === 'custom' || lower === 'local' || lower.startsWith('custom:')) {
-      startManualLocalEndpoint()
+      startManualLocalEndpoint(null, scopeProfile)
     } else if (rowSlug) {
-      startManualProviderOAuth(rowSlug)
+      startManualProviderOAuth(rowSlug, scopeProfile)
     } else {
       // An absent row has no trustworthy auth metadata. Open the generic
       // provider picker instead of deep-linking an unknown or stale slug.
-      startManualOnboarding()
+      startManualOnboarding(undefined, scopeProfile)
     }
-  }, [selectedProvider, selectedProviderRow])
+  }, [scopeProfile, selectedProvider, selectedProviderRow])
 
   const applyMainModel = useCallback(async () => {
     if (!selectedProvider || !selectedModel) {
diff --git a/apps/desktop/src/components/model-picker.tsx b/apps/desktop/src/components/model-picker.tsx
index 99a65357a8..df5e0b0378 100644
--- a/apps/desktop/src/components/model-picker.tsx
+++ b/apps/desktop/src/components/model-picker.tsx
@@ -34,7 +34,7 @@ interface ModelPickerDialogProps {
   currentModel: string
   currentProvider: string
   onSelect: (selection: { provider: string; model: string }) => void
-  ownerConnectionId?: string
+  ownerConnectionId?: null | string
   profile?: string
   request?: <T>(method: string, params?: Record<string, unknown>) => Promise<T>
   /**
@@ -184,7 +184,10 @@ export function ModelPickerDialog({
   // model-confirm) instead of duplicating provider UI here. Closes the picker
   // so the onboarding overlay isn't rendered underneath it.
   const addProvider = () => {
-    startManualOnboarding()
+    startManualOnboarding(
+      undefined,
+      ownerConnectionId !== undefined ? { connectionId: ownerConnectionId, profile } : profile
+    )
     onOpenChange(false)
   }
 
diff --git a/apps/desktop/src/components/onboarding/connection-owner.test.tsx b/apps/desktop/src/components/onboarding/connection-owner.test.tsx
new file mode 100644
index 0000000000..d6ee3e6aff
--- /dev/null
+++ b/apps/desktop/src/components/onboarding/connection-owner.test.tsx
@@ -0,0 +1,183 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, expect, it, vi } from 'vitest'
+
+import { setApiRequestConnection, setApiRequestProfile } from '@/api/client'
+import { startOAuthLogin } from '@/api/config'
+import type { HermesApiRequest } from '@/global'
+import type * as HermesApi from '@/hermes'
+import {
+  closeSecondaryGateways,
+  configureGatewayRegistry,
+  ensureGatewayForAgent,
+  requestGatewayForAgent,
+  setPrimaryGateway,
+  setPrimaryGatewayConnection
+} from '@/store/gateway'
+import type * as OnboardingStore from '@/store/onboarding'
+import {
+  $desktopOnboarding,
+  closeManualOnboarding,
+  type OnboardingContext,
+  startManualProviderOAuth
+} from '@/store/onboarding'
+import { stubMenuDomApis, stubResizeObserver } from '@/test/jsdom'
+import { makeOAuthProvider } from '@/test/oauth-provider'
+
+import { FlowPanel } from './flow'
+
+import { DesktopOnboardingOverlay } from '.'
+
+stubResizeObserver()
+stubMenuDomApis()
+
+// Boundary test: real overlay/API helpers/gateway router; no OAuth
+// account or production backend. Intercept acquisition to inspect its context.
+const mocks = vi.hoisted(() => ({
+  begin: vi.fn(),
+  rpc: vi.fn(async () => ({ ok: true }))
+}))
+
+vi.mock('@/store/onboarding', async importOriginal => ({
+  ...(await importOriginal<typeof OnboardingStore>()),
+  startProviderOAuth: mocks.begin
+}))
+vi.mock('@/hermes', async importOriginal => ({
+  ...(await importOriginal<typeof HermesApi>()),
+  HermesGateway: class {
+    connectionState = 'closed'
+    connect = async () => {
+      this.connectionState = 'open'
+    }
+    request = mocks.rpc
+    close = () => {
+      this.connectionState = 'closed'
+    }
+    onEvent = () => () => {}
+    onState = () => () => {}
+  }
+}))
+vi.mock('@/store/notify-baseline', () => ({ markNativeNotifyBaseline: vi.fn() }))
+
+const provider = { ...makeOAuthProvider('openai-codex'), flow: 'device_code' as const }
+
+afterEach(() => {
+  cleanup()
+  closeManualOnboarding()
+  closeSecondaryGateways()
+  setApiRequestConnection(null)
+  setApiRequestProfile(null)
+  vi.clearAllMocks()
+  delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
+})
+
+it.each([
+  { profile: 'leverage-ai', sharedRemote: true },
+  { profile: 'custom', sharedRemote: true },
+  { profile: 'mara', sharedRemote: false }
+])('keeps Settings readiness on its owner ($profile, shared=$sharedRemote)', async ({ profile, sharedRemote }) => {
+  const localRequest = vi.fn(async () => ({ ok: true }))
+
+  const localDial = vi.fn(async () => {
+    throw new Error('Diagnostic local backend has no remote-only profile')
+  })
+
+  const remoteDial = vi.fn(async ({ connectionId, profile: routeProfile }) => ({
+    connectionId,
+    profile: routeProfile,
+    sharedRemote,
+    ...(sharedRemote ? {} : { remoteKind: 'ssh', remoteProfile: 'remote-research' }),
+    mode: 'remote',
+    authMode: 'token',
+    baseUrl: 'https://athena.invalid',
+    wsUrl: 'wss://athena.invalid/api/ws',
+    token: 'fixture-only'
+  }))
+
+  const api = vi.fn(async () => ({ providers: [provider] }))
+  Object.defineProperty(window, 'hermesDesktop', {
+    configurable: true,
+    value: {
+      api,
+      getConnection: localDial,
+      getConnectionFor: remoteDial,
+      touchBackend: vi.fn(async () => undefined)
+    }
+  })
+  configureGatewayRegistry({ onEvent: vi.fn() })
+  setPrimaryGateway({ connectionState: 'open', request: localRequest } as never, 'default')
+  setPrimaryGatewayConnection({ connectionId: 'local' })
+  await ensureGatewayForAgent('athena', profile)
+  setApiRequestConnection('athena')
+  setApiRequestProfile(profile)
+  localDial.mockClear()
+
+  await act(async () => {
+    startManualProviderOAuth('openai-codex', profile)
+  })
+  render(
+    <DesktopOnboardingOverlay
+      enabled={false}
+      profile={profile}
+      requestGateway={(method, params) => requestGatewayForAgent('athena', profile, method, params)}
+    />
+  )
+  await waitFor(() => expect(mocks.begin).toHaveBeenCalledOnce())
+  const context = mocks.begin.mock.calls[0][1] as OnboardingContext
+
+  // Switching the foreground device must not retarget a pending setup.
+  setApiRequestConnection('local')
+  setApiRequestProfile('default')
+  await startOAuthLogin('openai-codex', context.scope)
+  expect(api).toHaveBeenLastCalledWith(
+    expect.objectContaining({
+      connectionId: 'athena',
+      profile,
+      path: '/api/providers/oauth/openai-codex/start'
+    })
+  )
+  await context.requestGateway('setup.status')
+  await context.requestGateway('setup.runtime_check', { provider: 'openai-codex' })
+  await context.requestGateway('model.options', { profile, explicit_only: true })
+  const params = sharedRemote ? { profile } : {}
+  expect(mocks.rpc).toHaveBeenCalledWith('setup.status', params)
+  expect(localDial).not.toHaveBeenCalled()
+  expect(mocks.rpc).toHaveBeenCalledWith('setup.runtime_check', { provider: 'openai-codex', ...params })
+  expect(mocks.rpc).toHaveBeenCalledWith('model.options', { explicit_only: true, ...params })
+  expect(localRequest).not.toHaveBeenCalled()
+})
+
+it('keeps an explicitly untagged owner through Change → Add provider', async () => {
+  const owner = { connectionId: null, profile: 'legacy' }
+  const api = vi.fn(async (_request: HermesApiRequest) => ({ providers: [] }))
+  Object.defineProperty(window, 'hermesDesktop', { configurable: true, value: { api } })
+  startManualProviderOAuth('openai-codex', owner)
+  setApiRequestConnection('athena')
+  setApiRequestProfile('default')
+  const client = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+
+  render(
+    <QueryClientProvider client={client}>
+      <FlowPanel
+        ctx={{ scope: owner, profile: owner.profile, requestGateway: async () => ({ providers: [] }) as never }}
+        flow={{
+          status: 'confirming_model',
+          currentModel: 'fixture-model',
+          providerSlug: 'openai-codex',
+          label: 'Codex',
+          saving: false
+        }}
+        leaving={false}
+        onBegin={() => undefined}
+      />
+    </QueryClientProvider>
+  )
+  fireEvent.click(screen.getByRole('button', { name: 'Change' }))
+  fireEvent.click(await screen.findByRole('button', { name: 'Add provider' }))
+  expect($desktopOnboarding.get().targetScope).toEqual(owner)
+  await waitFor(() =>
+    expect(api).toHaveBeenCalledWith(expect.objectContaining({ path: '/api/providers/oauth', profile: 'legacy' }))
+  )
+  expect(api.mock.calls.every(([request]) => !(request as { connectionId?: string }).connectionId)).toBe(true)
+  client.clear()
+})
diff --git a/apps/desktop/src/components/onboarding/flow.tsx b/apps/desktop/src/components/onboarding/flow.tsx
index ed4fff038e..01c9c190bb 100644
--- a/apps/desktop/src/components/onboarding/flow.tsx
+++ b/apps/desktop/src/components/onboarding/flow.tsx
@@ -6,7 +6,7 @@ import { Button } from '@/components/ui/button'
 import { ErrorIcon } from '@/components/ui/error-state'
 import { Input } from '@/components/ui/input'
 import { Loader } from '@/components/ui/loader'
-import { getGlobalModelOptions } from '@/hermes'
+import { getGlobalModelOptions, profileScopeKey } from '@/hermes'
 import { useI18n } from '@/i18n'
 import { ExternalLink, Loader2 } from '@/lib/icons'
 import { cn } from '@/lib/utils'
@@ -54,7 +54,7 @@ export function FlowPanel({
   }
 
   if (flow.status === 'confirming_model') {
-    return <ConfirmingModelPanel flow={flow} leaving={leaving} onBegin={onBegin} profile={ctx.profile} />
+    return <ConfirmingModelPanel ctx={ctx} flow={flow} leaving={leaving} onBegin={onBegin} />
   }
 
   if (flow.status === 'error') {
@@ -79,7 +79,7 @@ export function FlowPanel({
           <Button onClick={cancelOnboardingFlow} variant="text">
             {t.onboarding.pickDifferentProvider}
           </Button>
-          <Button onClick={() => startManualOnboarding(null, ctx.profile)} variant="outline">
+          <Button onClick={() => startManualOnboarding(null, ctx.scope ?? ctx.profile)} variant="outline">
             {t.onboarding.useApiKeyInstead}
           </Button>
           {failedProvider ? (
@@ -237,12 +237,12 @@ function ConfirmingModelPanel({
   flow,
   leaving,
   onBegin,
-  profile
+  ctx
 }: {
   flow: Extract<OnboardingFlow, { status: 'confirming_model' }>
   leaving: boolean
   onBegin: () => void
-  profile?: string
+  ctx: OnboardingContext
 }) {
   const { t } = useI18n()
   const scrambledModel = useScramble(flow.currentModel, leaving)
@@ -257,8 +257,8 @@ function ConfirmingModelPanel({
   // Pull pricing + tier for the just-picked default so the confirm card
   // shows the same $/Mtok + Free/Pro info the picker and CLI do.
   const options = useQuery({
-    queryKey: ['onboarding-model-options', flow.providerSlug],
-    queryFn: () => getGlobalModelOptions({ includeUnconfigured: true, explicitOnly: false })
+    queryKey: ['onboarding-model-options', profileScopeKey(ctx.scope ?? ctx.profile), flow.providerSlug],
+    queryFn: () => getGlobalModelOptions({ includeUnconfigured: true, explicitOnly: false }, ctx.scope ?? ctx.profile)
   })
 
   const providerRow = options.data?.providers?.find(
@@ -352,7 +352,9 @@ function ConfirmingModelPanel({
           setPickerOpen(false)
         }}
         open={pickerOpen}
-        profile={profile}
+        ownerConnectionId={ctx.scope ? (ctx.scope.connectionId ?? null) : undefined}
+        profile={ctx.profile}
+        request={ctx.requestGateway}
       />
     </div>
   )
diff --git a/apps/desktop/src/components/onboarding/index.tsx b/apps/desktop/src/components/onboarding/index.tsx
index 42482347a0..742ec86365 100644
--- a/apps/desktop/src/components/onboarding/index.tsx
+++ b/apps/desktop/src/components/onboarding/index.tsx
@@ -63,7 +63,8 @@ export {
   sortProviders
 } from './providers'
 
-import { requestGatewayForProfile } from '@/store/gateway'
+import { $gateway, activeGatewayConnectionId } from '@/store/gateway'
+import { requestOnboardingGateway } from '@/store/onboarding-scope'
 
 interface DesktopOnboardingOverlayProps {
   enabled: boolean
@@ -131,7 +132,7 @@ const API_KEY_OPTIONS: ApiKeyOption[] = [
 // other api_key provider is appended with a generic "paste {KEY}" affordance.
 // OAuth / external providers are intentionally excluded here — they go through
 // the OAuth picker / sign-in flow, not a pasted key.
-function useApiKeyCatalog(): ApiKeyOption[] {
+function useApiKeyCatalog(scope: OnboardingContext['scope']): ApiKeyOption[] {
   const [rows, setRows] = useState<ModelOptionProvider[]>([])
 
   useEffect(() => {
@@ -141,7 +142,7 @@ function useApiKeyCatalog(): ApiKeyOption[] {
     // Promise.resolve().then so a synchronous throw (e.g. no desktop bridge in
     // tests) is funneled into the same .catch instead of escaping.
     void Promise.resolve()
-      .then(() => getGlobalModelOptions({ includeUnconfigured: true, explicitOnly: false }))
+      .then(() => getGlobalModelOptions({ includeUnconfigured: true, explicitOnly: false }, scope))
       .then(res => {
         if (!cancelled) {
           setRows(res.providers ?? [])
@@ -154,7 +155,7 @@ function useApiKeyCatalog(): ApiKeyOption[] {
     return () => {
       cancelled = true
     }
-  }, [])
+  }, [scope])
 
   return useMemo(() => {
     const curatedByEnv = new Map(API_KEY_OPTIONS.map(o => [o.envKey, o]))
@@ -210,18 +211,26 @@ export function DesktopOnboardingOverlay({
   useStore($onboardingSurfaces)
   const onCompletedRef = useRef(onCompleted)
   onCompletedRef.current = onCompleted
-  const targetProfile = onboarding.targetProfile ?? profile
+  useStore($gateway)
+  const connectionId = activeGatewayConnectionId()
+
+  const scope = useMemo(
+    () => onboarding.targetScope ?? { connectionId, profile },
+    [onboarding.targetScope, profile, connectionId]
+  )
 
   // Async flows retain the initiating route even after the overlay closes.
   const ctx = useMemo<OnboardingContext>(
     () => ({
-      profile: targetProfile,
-      requestGateway: onboarding.targetProfile
-        ? (method, params) => requestGatewayForProfile(targetProfile, method, params)
-        : requestGateway,
+      scope,
+      profile: scope.profile ?? undefined,
+      requestGateway:
+        scope.profile && (onboarding.targetScope || scope.connectionId)
+          ? (method, params) => requestOnboardingGateway(scope, method, params)
+          : requestGateway,
       onCompleted: () => onCompletedRef.current?.()
     }),
-    [onboarding.targetProfile, targetProfile, requestGateway]
+    [onboarding.targetScope, scope, requestGateway]
   )
 
   // Cinematic exit on "Begin": dissolve the panel + overlay (revealing the chat
@@ -606,7 +615,7 @@ export function Picker({ ctx }: { ctx: OnboardingContext }) {
 
   const ordered = useMemo(() => (providers ? sortProviders(providers) : []), [providers])
   const hasOauth = ordered.length > 0
-  const apiKeyOptions = useApiKeyCatalog()
+  const apiKeyOptions = useApiKeyCatalog(ctx.scope)
 
   // localEndpoint forces the key form regardless of `mode` (which a manual
   // provider refresh may flip back to 'oauth'); it preselects the local option
diff --git a/apps/desktop/src/store/model-assignment.ts b/apps/desktop/src/store/model-assignment.ts
index c044e1f7a9..6af72a8967 100644
--- a/apps/desktop/src/store/model-assignment.ts
+++ b/apps/desktop/src/store/model-assignment.ts
@@ -1,4 +1,4 @@
-import { setModelAssignment } from '@/hermes'
+import { type ProfileScope, setModelAssignment } from '@/hermes'
 import { translateNow } from '@/i18n'
 import { dismissNotification, notify } from '@/store/notifications'
 import type { ModelAssignmentRequest, ModelAssignmentResponse } from '@/types/hermes'
@@ -41,7 +41,7 @@ function confirmModelWarning(message: string): Promise<boolean> {
 
 export async function setMainModelAssignment(
   request: Omit<ModelAssignmentRequest, 'scope'>,
-  scopeProfile?: null | string,
+  scopeProfile?: ProfileScope,
   options?: { skipConfirmPrompt?: boolean }
 ): Promise<ModelAssignmentResponse> {
   // Only pass the extra arg when a scope override exists, so unscoped callers
diff --git a/apps/desktop/src/store/onboarding-owner.test.ts b/apps/desktop/src/store/onboarding-owner.test.ts
new file mode 100644
index 0000000000..015f150157
--- /dev/null
+++ b/apps/desktop/src/store/onboarding-owner.test.ts
@@ -0,0 +1,183 @@
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+
+import { setApiRequestConnection, setApiRequestProfile } from '@/api/client'
+import type { HermesApiRequest } from '@/global'
+import { makeOAuthProvider } from '@/test/oauth-provider'
+
+import {
+  $desktopOnboarding,
+  closeManualOnboarding,
+  type OnboardingContext,
+  saveOnboardingLocalEndpoint,
+  setOnboardingCode,
+  setOnboardingModel,
+  startManualProviderOAuth,
+  startProviderOAuth,
+  submitOnboardingCode
+} from './onboarding'
+import { captureOnboardingScope } from './onboarding-scope'
+
+const owner = { connectionId: 'athena', profile: 'leverage-ai' }
+const requests: HermesApiRequest[] = []
+let authFlow: 'device_code' | 'pkce'
+let deferStart: (() => Promise<void>) | undefined
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  authFlow = 'device_code'
+  deferStart = undefined
+  requests.length = 0
+  setApiRequestConnection(owner.connectionId)
+  setApiRequestProfile(owner.profile)
+  Object.defineProperty(window, 'hermesDesktop', {
+    configurable: true,
+    value: {
+      openExternal: vi.fn(async () => undefined),
+      api: vi.fn(async (request: HermesApiRequest) => {
+        requests.push(request)
+        const { path } = request
+
+        if (path === '/api/providers/oauth') {
+          return { providers: [makeOAuthProvider('openai-codex')] }
+        }
+
+        if (path.endsWith('/start')) {
+          await deferStart?.()
+
+          return {
+            flow: authFlow,
+            session_id: 'fixture-session',
+            auth_url: 'https://example.invalid/authorize',
+            verification_url: 'https://example.invalid/device',
+            user_code: 'fixture-code',
+            expires_in: 600
+          }
+        }
+
+        if (path.includes('/poll/') || path.endsWith('/submit')) {
+          return { ok: true, status: 'approved' }
+        }
+
+        if (path.startsWith('/api/model/options')) {
+          return { providers: [{ slug: 'openai-codex', models: ['fixture-model'] }] }
+        }
+
+        if (path.startsWith('/api/model/recommended-default')) {
+          return { model: 'fixture-model' }
+        }
+
+        if (path === '/api/providers/validate') {
+          return { ok: true, reachable: true, models: ['endpoint-model'] }
+        }
+
+        return { ok: true }
+      })
+    }
+  })
+})
+
+afterEach(() => {
+  closeManualOnboarding()
+  setApiRequestConnection(null)
+  setApiRequestProfile(null)
+  vi.useRealTimers()
+  delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
+})
+
+function beginContext(): OnboardingContext {
+  startManualProviderOAuth('openai-codex', 'leverage-ai')
+
+  return {
+    scope: $desktopOnboarding.get().targetScope,
+    requestGateway: vi.fn(
+      async method => (method === 'setup.status' ? { provider_configured: true } : { ok: true }) as never
+    )
+  }
+}
+
+function switchForeground() {
+  setApiRequestConnection('local')
+  setApiRequestProfile('default')
+}
+
+function expectOwnerRequests() {
+  expect(requests.length).toBeGreaterThan(0)
+
+  for (const request of requests) {
+    expect(request).toMatchObject(owner)
+  }
+}
+
+it.each(['device_code', 'pkce'] as const)(
+  'pins %s completion and model edits after a foreground switch',
+  async flow => {
+    authFlow = flow
+    const ctx = beginContext()
+    await startProviderOAuth({ ...makeOAuthProvider('openai-codex'), flow }, ctx)
+    switchForeground()
+
+    if (flow === 'pkce') {
+      setOnboardingCode('fixture-code')
+      await submitOnboardingCode(ctx)
+    } else {
+      await vi.advanceTimersByTimeAsync(3000)
+    }
+
+    expect($desktopOnboarding.get().flow.status).toBe('confirming_model')
+    expect(ctx.requestGateway).not.toHaveBeenCalledWith('reload.env')
+    expect(ctx.requestGateway).toHaveBeenCalledWith('setup.runtime_check', { provider: 'openai-codex' })
+    await setOnboardingModel('other-fixture-model', 'openai-codex')
+    expect(requests.filter(request => request.path === '/api/model/set')).toHaveLength(2)
+    expect(requests.some(request => request.path.includes(flow === 'pkce' ? '/submit' : '/poll/'))).toBe(true)
+    expectOwnerRequests()
+  }
+)
+
+it('cancels on the original owner after the foreground changes', async () => {
+  const ctx = beginContext()
+  await startProviderOAuth({ ...makeOAuthProvider('openai-codex'), flow: 'device_code' }, ctx)
+  switchForeground()
+  closeManualOnboarding()
+  expect(requests.at(-1)).toMatchObject({ method: 'DELETE', path: '/api/providers/oauth/sessions/fixture-session' })
+  expectOwnerRequests()
+})
+
+it('cancels a late OAuth start on its retired owner, not a newly opened flow', async () => {
+  let release!: () => void
+  deferStart = () =>
+    new Promise<void>(resolve => {
+      release = resolve
+    })
+  const ctx = beginContext()
+  const pending = startProviderOAuth(makeOAuthProvider('openai-codex'), ctx)
+  expect(release).toBeTypeOf('function')
+  closeManualOnboarding()
+  switchForeground()
+  startManualProviderOAuth('openai-codex', 'default')
+  release()
+  await pending
+  expect(requests.at(-1)).toMatchObject({ ...owner, method: 'DELETE' })
+  expect($desktopOnboarding.get().targetScope).toEqual({ connectionId: 'local', profile: 'default' })
+  expect($desktopOnboarding.get().flow.status).toBe('idle')
+})
+
+it('pins local-endpoint validation and persistence to the setup owner', async () => {
+  const ctx = beginContext()
+  switchForeground()
+  await saveOnboardingLocalEndpoint('http://127.0.0.1:11434/v1', '', ctx)
+  expect(requests.some(request => request.path === '/api/providers/validate')).toBe(true)
+  expect(requests.some(request => request.path === '/api/model/set')).toBe(true)
+  expectOwnerRequests()
+})
+
+it('preserves explicit local and untagged legacy routes instead of filling ambient halves', () => {
+  expect(captureOnboardingScope({ connectionId: 'local', profile: 'default' })).toEqual({
+    connectionId: 'local',
+    profile: 'default'
+  })
+  expect(captureOnboardingScope({ profile: 'legacy' })).toEqual({ profile: 'legacy' })
+  setApiRequestConnection(null)
+  const legacy = captureOnboardingScope('legacy')
+  setApiRequestConnection('athena')
+  expect(legacy).toEqual({ connectionId: null, profile: 'legacy' })
+})
diff --git a/apps/desktop/src/store/onboarding-scope.ts b/apps/desktop/src/store/onboarding-scope.ts
new file mode 100644
index 0000000000..f73dafa4ad
--- /dev/null
+++ b/apps/desktop/src/store/onboarding-scope.ts
@@ -0,0 +1,54 @@
+import { getApiRequestConnection, getApiRequestProfile, type ProfileScope } from '@/hermes'
+import { RECONNECT_ATTEMPT_TIMEOUT_MS, withTimeout } from '@/lib/with-timeout'
+import { requestGatewayForAgent } from '@/store/gateway'
+
+export interface OnboardingScope {
+  connectionId?: null | string
+  profile?: null | string
+}
+
+/** Capture both halves once. An absent connection keeps legacy per-profile
+ * routing; it must not acquire a different ambient registry owner later. */
+export function captureOnboardingScope(scope?: ProfileScope): OnboardingScope {
+  if (scope && typeof scope === 'object') {
+    return { ...scope }
+  }
+
+  return {
+    connectionId: getApiRequestConnection(),
+    profile: scope === undefined ? getApiRequestProfile() : scope
+  }
+}
+
+/** Desktop profile keys can be SSH aliases. Only shared descriptors interpret
+ * them as backend request scopes; dedicated backends already own their home. */
+export async function requestOnboardingGateway<T>(
+  scope: OnboardingScope,
+  method: string,
+  params: Record<string, unknown> = {}
+): Promise<T> {
+  const profile = scope.profile || 'default'
+  const desktop = window.hermesDesktop
+
+  if (scope.connectionId && !desktop.getConnectionFor) {
+    throw new Error('This Desktop build cannot dial registry connections. Update Hermes Desktop.')
+  }
+
+  const connection = await withTimeout(
+    scope.connectionId
+      ? desktop.getConnectionFor!({ connectionId: scope.connectionId, profile })
+      : desktop.getConnection(profile),
+    RECONNECT_ATTEMPT_TIMEOUT_MS,
+    `Timed out resolving provider setup for "${profile}"`
+  )
+
+  const routedParams = { ...params }
+
+  delete routedParams.profile
+
+  if (connection.sharedPrimary || connection.sharedRemote) {
+    routedParams.profile = profile
+  }
+
+  return requestGatewayForAgent<T>(scope.connectionId ?? null, profile, method, routedParams)
+}
diff --git a/apps/desktop/src/store/onboarding.test.ts b/apps/desktop/src/store/onboarding.test.ts
index cdbb4b1584..38be4b6f1d 100644
--- a/apps/desktop/src/store/onboarding.test.ts
+++ b/apps/desktop/src/store/onboarding.test.ts
@@ -147,7 +147,7 @@ describe('refreshOnboarding', () => {
       release()
       await pending
       expect(requests.some(r => r.path === '/api/model/set')).toBe(false)
-      expect($desktopOnboarding.get()).toMatchObject({ targetProfile: 'alpha', flow: { status: 'idle' } })
+      expect($desktopOnboarding.get()).toMatchObject({ targetScope: { profile: 'alpha' }, flow: { status: 'idle' } })
       closeManualOnboarding()
       delayKey = false
       profile = 'beta'
diff --git a/apps/desktop/src/store/onboarding.ts b/apps/desktop/src/store/onboarding.ts
index e839e9fc61..85f82edbed 100644
--- a/apps/desktop/src/store/onboarding.ts
+++ b/apps/desktop/src/store/onboarding.ts
@@ -7,6 +7,7 @@ import {
   getRecommendedDefaultModel,
   listOAuthProviders,
   pollOAuthSession,
+  type ProfileScope,
   setEnvVar,
   startOAuthLogin,
   submitOAuthCode,
@@ -19,6 +20,7 @@ import { ackFreeTierNotice, freeTierReadyPending, refreshFreeTierStatus, setFree
 import { setMainModelAssignment } from '@/store/model-assignment'
 import { notify, notifyError } from '@/store/notifications'
 import { guidedOnboardingActive } from '@/store/onboarding-gate'
+import { captureOnboardingScope, type OnboardingScope } from '@/store/onboarding-scope'
 import type { OAuthProvider, OAuthStartResponse } from '@/types/hermes'
 
 type PkceStart = Extract<OAuthStartResponse, { flow: 'pkce' }>
@@ -72,7 +74,7 @@ export interface DesktopOnboardingState {
    *  picker's "Add provider" button). Forces the overlay to show the picker
    *  even when configured === true, and adds a close affordance. */
   manual: boolean
-  targetProfile?: string
+  targetScope?: OnboardingScope
   /** True when the overlay was opened specifically to configure a local /
    *  custom OpenAI-compatible endpoint (e.g. from Settings → Model's "Set up
    *  custom endpoint"). Forces the API-key form with the local option
@@ -89,6 +91,7 @@ export interface DesktopOnboardingState {
 export interface OnboardingContext {
   onCompleted?: () => void
   profile?: string
+  scope?: OnboardingScope
   requestGateway: <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T>
 }
 
@@ -171,12 +174,16 @@ const INITIAL: DesktopOnboardingState = {
 export const $desktopOnboarding = atom<DesktopOnboardingState>(INITIAL)
 
 let flowGeneration = 0
-let flowProfile: string | undefined
+let flowScope: OnboardingScope | undefined
 let pollTimer: number | null = null
 let providersRefreshPromise: null | Promise<void> = null
 
 const errMessage = (e: unknown) => (e instanceof Error ? e.message : String(e))
 
+function captureContext(ctx: OnboardingContext): OnboardingContext & { scope: OnboardingScope } {
+  return { ...ctx, scope: captureOnboardingScope(ctx.scope ?? ctx.profile) }
+}
+
 // One plain sentence for every way a provider sign-in can fail (start, poll,
 // code exchange); the raw error text rides along as `detail` (desktop-09).
 function signInDidNotFinish(provider: OAuthProvider, raw: unknown): { message: string; detail?: string } {
@@ -282,7 +289,7 @@ function notifyGatewayTools(tools: string[] | undefined) {
 // opportunistic polish, not a hard requirement for onboarding.
 async function fetchProviderDefaultModel(
   preferredSlugs: string[],
-  profile?: string
+  profile?: ProfileScope
 ): Promise<null | { providerSlug: string; defaultModel: string }> {
   let options
 
@@ -370,13 +377,18 @@ async function completeWithModelConfirm(
   ignoreRuntimeGate = false
 ) {
   const generation = flowGeneration
-  await ctx.requestGateway('reload.env').catch(() => undefined)
+
+  // Scoped readiness reads fresh credentials; reload.env only mutates the
+  // launch process environment and cannot reload another profile safely.
+  if (!ctx.scope?.profile) {
+    await ctx.requestGateway('reload.env').catch(() => undefined)
+  }
 
   if (generation !== flowGeneration) {
     return
   }
 
-  const defaults = await fetchProviderDefaultModel(preferredSlugs, ctx.profile)
+  const defaults = await fetchProviderDefaultModel(preferredSlugs, ctx.scope)
 
   if (generation !== flowGeneration) {
     return
@@ -392,7 +404,7 @@ async function completeWithModelConfirm(
           provider: defaults.providerSlug,
           model: defaults.defaultModel
         },
-        ctx.profile,
+        ctx.scope,
         // Headless automated flow: nothing is mounted to click a guard
         // prompt, so fail with the message instead of hanging.
         { skipConfirmPrompt: true }
@@ -470,7 +482,7 @@ async function refreshProviders() {
   const generation = flowGeneration
   providersRefreshPromise = (async () => {
     try {
-      const { providers } = await listOAuthProviders($desktopOnboarding.get().targetProfile)
+      const { providers } = await listOAuthProviders($desktopOnboarding.get().targetScope)
 
       if (generation !== flowGeneration) {
         return
@@ -545,12 +557,15 @@ export function consumePendingCredentialWarning(): null | string {
 // onboarding flow (OAuth rows, API-key form, model-confirm) instead of
 // duplicating provider UI. Sets manual=true so the overlay shows the picker
 // even though configured===true, and refreshes the provider list.
-export function startManualOnboarding(reason: null | string = DEFAULT_MANUAL_ONBOARDING_REASON, profile?: string) {
+export function startManualOnboarding(
+  reason: null | string = DEFAULT_MANUAL_ONBOARDING_REASON,
+  profile?: ProfileScope
+) {
   cancelOnboardingFlow()
   providersRefreshPromise = null
   patch({
     manual: true,
-    targetProfile: profile,
+    targetScope: captureOnboardingScope(profile),
     providers: null,
     requested: true,
     localEndpoint: false,
@@ -570,12 +585,12 @@ export function startManualOnboarding(reason: null | string = DEFAULT_MANUAL_ONB
 // configure the endpoint instead of dead-ending on the OAuth provider list
 // (`custom` is not an OAuth provider, so the generic manual flow would just
 // re-show the picker — the original "booted back to the first screen" loop).
-export function startManualLocalEndpoint(reason: null | string = null, profile?: string) {
+export function startManualLocalEndpoint(reason: null | string = null, profile?: ProfileScope) {
   cancelOnboardingFlow()
   pendingProviderOAuthId = null
   patch({
     manual: true,
-    targetProfile: profile,
+    targetScope: captureOnboardingScope(profile),
     providers: null,
     requested: true,
     localEndpoint: true,
@@ -593,7 +608,7 @@ export function startManualLocalEndpoint(reason: null | string = null, profile?:
 // overlay render and never needs to persist or re-render anything itself.
 let pendingProviderOAuthId: null | string = null
 
-export function startManualProviderOAuth(providerId: string, profile?: string) {
+export function startManualProviderOAuth(providerId: string, profile?: ProfileScope) {
   pendingProviderOAuthId = providerId
   startManualOnboarding(null, profile)
 }
@@ -619,7 +634,7 @@ export function closeManualOnboarding() {
   pendingProviderOAuthId = null
 
   patch({
-    targetProfile: undefined,
+    targetScope: undefined,
     manual: false,
     requested: false,
     localEndpoint: false,
@@ -798,9 +813,9 @@ async function openSignInUrl(url: string) {
 }
 
 export async function startProviderOAuth(provider: OAuthProvider, ctx: OnboardingContext) {
-  ctx = { ...ctx }
+  ctx = captureContext(ctx)
   const generation = flowGeneration
-  flowProfile = ctx.profile
+  flowScope = ctx.scope
   clearPoll()
 
   if (provider.flow === 'external') {
@@ -812,10 +827,10 @@ export async function startProviderOAuth(provider: OAuthProvider, ctx: Onboardin
   setFlow({ status: 'starting', provider })
 
   try {
-    const start = await startOAuthLogin(provider.id, ctx.profile)
+    const start = await startOAuthLogin(provider.id, ctx.scope)
 
     if (generation !== flowGeneration) {
-      void cancelOAuthSession(start.session_id, ctx.profile).catch(() => undefined)
+      void cancelOAuthSession(start.session_id, ctx.scope).catch(() => undefined)
 
       return
     }
@@ -824,7 +839,7 @@ export async function startProviderOAuth(provider: OAuthProvider, ctx: Onboardin
     await openSignInUrl(browserUrl)
 
     if (generation !== flowGeneration) {
-      void cancelOAuthSession(start.session_id, ctx.profile).catch(() => undefined)
+      void cancelOAuthSession(start.session_id, ctx.scope).catch(() => undefined)
 
       return
     }
@@ -857,7 +872,7 @@ export async function startProviderOAuth(provider: OAuthProvider, ctx: Onboardin
 // Poll a session-backed device-code flow until it resolves.
 async function pollSession(provider: OAuthProvider, start: DeviceStart, ctx: OnboardingContext, generation: number) {
   try {
-    const { error_message, status } = await pollOAuthSession(provider.id, start.session_id, ctx.profile)
+    const { error_message, status } = await pollOAuthSession(provider.id, start.session_id, ctx.scope)
 
     if (generation !== flowGeneration) {
       return
@@ -896,9 +911,9 @@ export function setOnboardingCode(code: string) {
 }
 
 export async function submitOnboardingCode(ctx: OnboardingContext) {
-  ctx = { ...ctx }
+  ctx = captureContext(ctx)
   const generation = flowGeneration
-  flowProfile = ctx.profile
+  flowScope = ctx.scope
   const { flow } = $desktopOnboarding.get()
 
   if (flow.status !== 'awaiting_user' || !flow.code.trim()) {
@@ -909,7 +924,7 @@ export async function submitOnboardingCode(ctx: OnboardingContext) {
   setFlow({ status: 'submitting', provider, start })
 
   try {
-    const resp = await submitOAuthCode(provider.id, start.session_id, code.trim(), ctx.profile)
+    const resp = await submitOAuthCode(provider.id, start.session_id, code.trim(), ctx.scope)
 
     if (generation !== flowGeneration) {
       return
@@ -942,9 +957,10 @@ export function cancelOnboardingFlow() {
   const sessionId = sessionIdFor($desktopOnboarding.get().flow)
 
   if (sessionId) {
-    cancelOAuthSession(sessionId, flowProfile ?? $desktopOnboarding.get().targetProfile).catch(() => undefined)
+    cancelOAuthSession(sessionId, flowScope ?? $desktopOnboarding.get().targetScope).catch(() => undefined)
   }
 
+  flowScope = undefined
   setFlow({ status: 'idle' })
 }
 
@@ -994,8 +1010,8 @@ export async function copyExternalCommand() {
 }
 
 export async function recheckExternalSignin(ctx: OnboardingContext) {
-  ctx = { ...ctx }
-  flowProfile = ctx.profile
+  ctx = captureContext(ctx)
+  flowScope = ctx.scope
   const { flow } = $desktopOnboarding.get()
 
   if (flow.status !== 'external_pending') {
@@ -1024,9 +1040,9 @@ export async function saveOnboardingApiKey(
   // providers (their key IS `value`).
   endpointApiKey?: string
 ) {
-  ctx = { ...ctx }
+  ctx = captureContext(ctx)
   const generation = flowGeneration
-  flowProfile = ctx.profile
+  flowScope = ctx.scope
   const trimmed = value.trim()
 
   if (!trimmed) {
@@ -1047,7 +1063,7 @@ export async function saveOnboardingApiKey(
   // provider probes, self-hosted endpoints). We now save the value as-is and
   // let the user proceed; an actually-bad key surfaces later at chat time.
   try {
-    await setEnvVar(envKey, trimmed, ctx.profile)
+    await setEnvVar(envKey, trimmed, ctx.scope)
 
     if (generation !== flowGeneration) {
       return { ok: false }
@@ -1088,9 +1104,9 @@ export async function saveOnboardingApiKey(
 // wipe the base_url we just wrote. We have a concrete model already, so we
 // verify the runtime directly and finish.
 export async function saveOnboardingLocalEndpoint(baseUrl: string, apiKey: string, ctx: OnboardingContext) {
-  ctx = { ...ctx }
+  ctx = captureContext(ctx)
   const generation = flowGeneration
-  flowProfile = ctx.profile
+  flowScope = ctx.scope
   const url = baseUrl.trim()
   const key = apiKey.trim()
 
@@ -1108,7 +1124,7 @@ export async function saveOnboardingLocalEndpoint(baseUrl: string, apiKey: strin
   let resolvedUrl = url
 
   try {
-    const probe = await validateProviderCredential('OPENAI_BASE_URL', url, key)
+    const probe = await validateProviderCredential('OPENAI_BASE_URL', url, key, ctx.scope)
 
     if (generation !== flowGeneration) {
       return { ok: false }
@@ -1136,13 +1152,15 @@ export async function saveOnboardingLocalEndpoint(baseUrl: string, apiKey: strin
   }
 
   try {
-    await setMainModelAssignment({ provider: 'custom', model, base_url: resolvedUrl, api_key: key }, ctx.profile)
+    await setMainModelAssignment({ provider: 'custom', model, base_url: resolvedUrl, api_key: key }, ctx.scope)
 
     if (generation !== flowGeneration) {
       return { ok: false }
     }
 
-    await ctx.requestGateway('reload.env').catch(() => undefined)
+    if (!ctx.scope?.profile) {
+      await ctx.requestGateway('reload.env').catch(() => undefined)
+    }
 
     if (generation !== flowGeneration) {
       return { ok: false }
@@ -1204,7 +1222,7 @@ export async function setOnboardingModel(model: string, providerSlug: string, la
         provider: providerSlug,
         model
       },
-      flowProfile ?? $desktopOnboarding.get().targetProfile
+      flowScope ?? $desktopOnboarding.get().targetScope
     )
 
     if (generation !== flowGeneration) {

From 7213ebb3a85e517e9ab37ee8700022cddb0c04ea Mon Sep 17 00:00:00 2001
From: BearHuddleston <bear@bearhuddleston.dev>
Date: Tue, 22 Sep 2026 15:24:17 -0500
Subject: [PATCH 26/61] test(desktop): cover provider setup route lookup
 failures

---
 .../src/store/onboarding-scope.test.ts        | 76 +++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 apps/desktop/src/store/onboarding-scope.test.ts

diff --git a/apps/desktop/src/store/onboarding-scope.test.ts b/apps/desktop/src/store/onboarding-scope.test.ts
new file mode 100644
index 0000000000..f7e9e662ef
--- /dev/null
+++ b/apps/desktop/src/store/onboarding-scope.test.ts
@@ -0,0 +1,76 @@
+import { afterEach, expect, it, vi } from 'vitest'
+
+import { isTimeoutError, RECONNECT_ATTEMPT_TIMEOUT_MS } from '@/lib/with-timeout'
+
+import { requestOnboardingGateway } from './onboarding-scope'
+
+const mocks = vi.hoisted(() => ({ request: vi.fn(async () => ({ ok: true })) }))
+
+vi.mock('@/store/gateway', () => ({ requestGatewayForAgent: mocks.request }))
+
+const owner = { connectionId: 'athena', profile: 'leverage-ai' }
+
+function installDesktop(bridge: Record<string, unknown>) {
+  const getConnection = vi.fn(async () => ({ sharedPrimary: true }))
+  Object.defineProperty(window, 'hermesDesktop', { configurable: true, value: { getConnection, ...bridge } })
+
+  return getConnection
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+  vi.clearAllMocks()
+  delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
+})
+
+// Each failure must surface without sending the RPC anywhere, and without
+// falling back to the profile-only resolver that would pick another device.
+it('rejects a registry owner on a bridge that cannot dial registry connections', async () => {
+  const getConnection = installDesktop({})
+
+  await expect(requestOnboardingGateway(owner, 'setup.runtime_check')).rejects.toThrow(/Update Hermes Desktop/)
+  expect(getConnection).not.toHaveBeenCalled()
+  expect(mocks.request).not.toHaveBeenCalled()
+})
+
+it('surfaces a removed registry connection instead of retargeting setup', async () => {
+  const getConnectionFor = vi.fn(async () => {
+    throw new Error('No connection with id "athena"')
+  })
+
+  const getConnection = installDesktop({ getConnectionFor })
+
+  await expect(requestOnboardingGateway(owner, 'setup.runtime_check')).rejects.toThrow('No connection with id "athena"')
+  expect(getConnectionFor).toHaveBeenCalledWith({ connectionId: 'athena', profile: 'leverage-ai' })
+  expect(getConnection).not.toHaveBeenCalled()
+  expect(mocks.request).not.toHaveBeenCalled()
+})
+
+it('times out a wedged connection lookup', async () => {
+  vi.useFakeTimers()
+  const getConnectionFor = vi.fn(() => new Promise(() => undefined))
+  const getConnection = installDesktop({ getConnectionFor })
+  const pending = requestOnboardingGateway(owner, 'setup.runtime_check').catch((error: unknown) => error)
+
+  await vi.advanceTimersByTimeAsync(RECONNECT_ATTEMPT_TIMEOUT_MS)
+  const error = await pending
+
+  expect(isTimeoutError(error)).toBe(true)
+  expect((error as Error).message).toBe('Timed out resolving provider setup for "leverage-ai"')
+  expect(getConnection).not.toHaveBeenCalled()
+  expect(mocks.request).not.toHaveBeenCalled()
+})
+
+it('surfaces a failed legacy lookup for an untagged owner', async () => {
+  const getConnection = vi.fn(async () => {
+    throw new Error('Profile "legacy" is unavailable')
+  })
+
+  installDesktop({ getConnection, getConnectionFor: vi.fn() })
+
+  await expect(requestOnboardingGateway({ connectionId: null, profile: 'legacy' }, 'setup.status')).rejects.toThrow(
+    'Profile "legacy" is unavailable'
+  )
+  expect(getConnection).toHaveBeenCalledWith('legacy')
+  expect(mocks.request).not.toHaveBeenCalled()
+})

From 690813ba9232ecc75f1d5caf0f6e32ec47693469 Mon Sep 17 00:00:00 2001
From: BearHuddleston <bear@bearhuddleston.dev>
Date: Tue, 22 Sep 2026 17:58:14 -0500
Subject: [PATCH 27/61] fix(desktop): keep the Desktop route alias when the
 picker opens provider setup

The model picker reads its catalog with the backend target profile, but
Add provider reused that name as the setup owner. For SSH aliases this
changed the registry scope key and could dial a second pooled backend.
Pass the Desktop route profile separately for the setup handoff.
---
 .../src/app/model-picker-overlay.test.tsx     | 82 +++++++++++++++++++
 apps/desktop/src/app/model-picker-overlay.tsx |  1 +
 apps/desktop/src/components/model-picker.tsx  |  7 +-
 3 files changed, 89 insertions(+), 1 deletion(-)
 create mode 100644 apps/desktop/src/app/model-picker-overlay.test.tsx

diff --git a/apps/desktop/src/app/model-picker-overlay.test.tsx b/apps/desktop/src/app/model-picker-overlay.test.tsx
new file mode 100644
index 0000000000..347fa6b8c6
--- /dev/null
+++ b/apps/desktop/src/app/model-picker-overlay.test.tsx
@@ -0,0 +1,82 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import type { WritableAtom } from 'nanostores'
+import { afterEach, expect, it, vi } from 'vitest'
+
+import { I18nProvider } from '@/i18n'
+import { requestModelOptions } from '@/lib/model-options'
+import { startManualOnboarding } from '@/store/onboarding'
+import { $gatewayState, $modelPickerOpen, $selectedStoredSessionId } from '@/store/session'
+import { $focusedTreePaneId as $focusedTreePaneIdMock } from '@/store/session-focus'
+import { $sessionTiles } from '@/store/session-states'
+import { stubMenuDomApis, stubResizeObserver } from '@/test/jsdom'
+
+import { ModelPickerOverlay } from './model-picker-overlay'
+
+// The mock below replaces the computed store with a writable atom.
+const $focusedTreePaneId = $focusedTreePaneIdMock as unknown as WritableAtom<null | string>
+
+vi.mock('@/store/session-focus', async () => {
+  const { atom } = await import('nanostores')
+
+  return { $focusedTreePaneId: atom<null | string>(null) }
+})
+vi.mock('@/hermes', async importOriginal => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  getLocalModelsStatus: vi.fn().mockResolvedValue({ loading: {} })
+}))
+vi.mock('@/lib/model-options', async importOriginal => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  requestModelOptions: vi.fn().mockResolvedValue({ model: '', provider: '', providers: [] })
+}))
+vi.mock('@/store/onboarding', async importOriginal => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  startManualOnboarding: vi.fn()
+}))
+
+stubResizeObserver()
+stubMenuDomApis()
+
+afterEach(() => {
+  cleanup()
+  vi.clearAllMocks()
+  $sessionTiles.set([])
+  $focusedTreePaneId.set(null)
+  $selectedStoredSessionId.set(null)
+  $modelPickerOpen.set(false)
+  $gatewayState.set('idle')
+})
+
+it('reads the catalog from the backend profile but hands the Desktop alias to provider setup', async () => {
+  $gatewayState.set('open')
+  $modelPickerOpen.set(true)
+  $selectedStoredSessionId.set('primary-a')
+  $sessionTiles.set([
+    {
+      ownerRoute: { connectionId: 'connection-b', profile: 'desktop-b', targetProfile: 'backend-b' },
+      storedSessionId: 'tile-b'
+    }
+  ])
+  $focusedTreePaneId.set('session-tile:tile-b')
+  const client = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+
+  render(
+    <QueryClientProvider client={client}>
+      <I18nProvider>
+        <ModelPickerOverlay
+          onSelect={() => undefined}
+          ownerConnectionId="connection-a"
+          profile="default"
+          requestGateway={async () => undefined as never}
+        />
+      </I18nProvider>
+    </QueryClientProvider>
+  )
+
+  await waitFor(() => expect(requestModelOptions).toHaveBeenCalled())
+  expect(vi.mocked(requestModelOptions).mock.calls.every(([options]) => options.profile === 'backend-b')).toBe(true)
+
+  fireEvent.click(await screen.findByRole('button', { name: 'Add provider' }))
+  expect(startManualOnboarding).toHaveBeenCalledWith(undefined, { connectionId: 'connection-b', profile: 'desktop-b' })
+  client.clear()
+})
diff --git a/apps/desktop/src/app/model-picker-overlay.tsx b/apps/desktop/src/app/model-picker-overlay.tsx
index 34c8806d9d..9ad25f312d 100644
--- a/apps/desktop/src/app/model-picker-overlay.tsx
+++ b/apps/desktop/src/app/model-picker-overlay.tsx
@@ -97,6 +97,7 @@ export function ModelPickerOverlay({
       profile={pickerOwner.profile}
       request={pickerOwner.route ? requestPickerGateway : undefined}
       sessionId={sessionId}
+      setupProfile={pickerOwner.route?.profile ?? pickerOwner.profile}
     />
   )
 }
diff --git a/apps/desktop/src/components/model-picker.tsx b/apps/desktop/src/components/model-picker.tsx
index df5e0b0378..e30c2dcff5 100644
--- a/apps/desktop/src/components/model-picker.tsx
+++ b/apps/desktop/src/components/model-picker.tsx
@@ -36,6 +36,8 @@ interface ModelPickerDialogProps {
   onSelect: (selection: { provider: string; model: string }) => void
   ownerConnectionId?: null | string
   profile?: string
+  /** Desktop route profile for provider setup; `profile` may be the backend-side target. */
+  setupProfile?: string
   request?: <T>(method: string, params?: Record<string, unknown>) => Promise<T>
   /**
    * Optional class for DialogContent. Use it to lift the picker onto a higher
@@ -57,6 +59,7 @@ export function ModelPickerDialog({
   ownerConnectionId,
   profile = 'default',
   request,
+  setupProfile,
   contentClassName
 }: ModelPickerDialogProps) {
   const { t } = useI18n()
@@ -184,9 +187,11 @@ export function ModelPickerDialog({
   // model-confirm) instead of duplicating provider UI here. Closes the picker
   // so the onboarding overlay isn't rendered underneath it.
   const addProvider = () => {
+    const ownerProfile = setupProfile ?? profile
+
     startManualOnboarding(
       undefined,
-      ownerConnectionId !== undefined ? { connectionId: ownerConnectionId, profile } : profile
+      ownerConnectionId !== undefined ? { connectionId: ownerConnectionId, profile: ownerProfile } : ownerProfile
     )
     onOpenChange(false)
   }

From 4340fa497439e973f1451fbe0aa2c4bc0e3d18c8 Mon Sep 17 00:00:00 2001
From: BearHuddleston <bear@bearhuddleston.dev>
Date: Tue, 22 Sep 2026 17:58:14 -0500
Subject: [PATCH 28/61] fix(desktop): pin provider setup readiness to an
 explicit connection

An explicit scope carrying only connectionId routed OAuth REST to that
connection while readiness stayed on the ambient gateway. Select the
scoped dispatcher whenever a connection is pinned.
---
 .../onboarding/connection-owner.test.tsx      | 60 +++++++++++++++++++
 .../src/components/onboarding/index.tsx       |  2 +-
 2 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/components/onboarding/connection-owner.test.tsx b/apps/desktop/src/components/onboarding/connection-owner.test.tsx
index d6ee3e6aff..35bddedbd0 100644
--- a/apps/desktop/src/components/onboarding/connection-owner.test.tsx
+++ b/apps/desktop/src/components/onboarding/connection-owner.test.tsx
@@ -181,3 +181,63 @@ it('keeps an explicitly untagged owner through Change → Add provider', async (
   expect(api.mock.calls.every(([request]) => !(request as { connectionId?: string }).connectionId)).toBe(true)
   client.clear()
 })
+
+it.each([null, undefined])('pins a registry owner when its profile is %s', async profile => {
+  const localRequest = vi.fn(async (_method: string, _params?: Record<string, unknown>) => ({ ok: true }))
+
+  const localDial = vi.fn(async () => {
+    throw new Error('A registry-owned setup must not dial the legacy connection')
+  })
+
+  const remoteDial = vi.fn(async () => ({
+    connectionId: 'athena',
+    profile: 'default',
+    sharedRemote: true,
+    mode: 'remote',
+    authMode: 'token',
+    baseUrl: 'https://athena.invalid',
+    wsUrl: 'wss://athena.invalid/api/ws',
+    token: 'fixture-only'
+  }))
+
+  const api = vi.fn(async () => ({ providers: [provider] }))
+  Object.defineProperty(window, 'hermesDesktop', {
+    configurable: true,
+    value: {
+      api,
+      getConnection: localDial,
+      getConnectionFor: remoteDial,
+      touchBackend: vi.fn(async () => undefined)
+    }
+  })
+  configureGatewayRegistry({ onEvent: vi.fn() })
+  setPrimaryGateway({ connectionState: 'open', request: localRequest } as never, 'default')
+  setPrimaryGatewayConnection({ connectionId: 'local' })
+  setApiRequestConnection('local')
+  setApiRequestProfile('default')
+
+  await act(async () => {
+    startManualProviderOAuth('openai-codex', { connectionId: 'athena', profile })
+  })
+  render(
+    <DesktopOnboardingOverlay
+      enabled={false}
+      profile="default"
+      requestGateway={async (method, params) => (await localRequest(method, params)) as never}
+    />
+  )
+  await waitFor(() => expect(mocks.begin).toHaveBeenCalledOnce())
+  const context = mocks.begin.mock.calls[0][1] as OnboardingContext
+
+  await startOAuthLogin('openai-codex', context.scope)
+  expect(api).toHaveBeenLastCalledWith(
+    expect.objectContaining({ connectionId: 'athena', path: '/api/providers/oauth/openai-codex/start' })
+  )
+  await context.requestGateway('setup.status')
+  await context.requestGateway('setup.runtime_check', { provider: 'openai-codex' })
+  expect(remoteDial).toHaveBeenCalledWith({ connectionId: 'athena', profile: 'default' })
+  expect(mocks.rpc).toHaveBeenCalledWith('setup.status', { profile: 'default' })
+  expect(mocks.rpc).toHaveBeenCalledWith('setup.runtime_check', { provider: 'openai-codex', profile: 'default' })
+  expect(localDial).not.toHaveBeenCalled()
+  expect(localRequest).not.toHaveBeenCalled()
+})
diff --git a/apps/desktop/src/components/onboarding/index.tsx b/apps/desktop/src/components/onboarding/index.tsx
index 742ec86365..5008872b65 100644
--- a/apps/desktop/src/components/onboarding/index.tsx
+++ b/apps/desktop/src/components/onboarding/index.tsx
@@ -225,7 +225,7 @@ export function DesktopOnboardingOverlay({
       scope,
       profile: scope.profile ?? undefined,
       requestGateway:
-        scope.profile && (onboarding.targetScope || scope.connectionId)
+        scope.connectionId || (scope.profile && onboarding.targetScope)
           ? (method, params) => requestOnboardingGateway(scope, method, params)
           : requestGateway,
       onCompleted: () => onCompletedRef.current?.()

From db20d39df58081a6c8f1c0b0963dbaedf3389671 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:37:07 -0700
Subject: [PATCH 29/61] fix(desktop): keep provider readiness on the profile
 REST setup writes

captureOnboardingScope now normalizes a blank profile to null once, and
requestOnboardingGateway only sends params.profile to a shared backend when
the owner actually has one.

Why: REST setup writes (setEnvVar, setModelAssignment, OAuth) with no profile
carry no ?profile= and land in the backend's launch home, but readiness
hard-coded params.profile = 'default'. On a shared/remote backend launched
as another profile, setup would write one profile and verify another. The
Desktop routing key stays 'default' (it names the launch home locally); only
the wire param is omitted, so both halves target the same home. The overlay's
fallback scope goes through the same capture so a blank label cannot leak.
---
 .../src/components/onboarding/index.tsx       |  4 +-
 .../src/store/onboarding-owner.test.ts        | 39 ++++++++++++++++++-
 apps/desktop/src/store/onboarding-scope.ts    | 21 +++++-----
 3 files changed, 50 insertions(+), 14 deletions(-)

diff --git a/apps/desktop/src/components/onboarding/index.tsx b/apps/desktop/src/components/onboarding/index.tsx
index 5008872b65..b53bcd83e0 100644
--- a/apps/desktop/src/components/onboarding/index.tsx
+++ b/apps/desktop/src/components/onboarding/index.tsx
@@ -64,7 +64,7 @@ export {
 } from './providers'
 
 import { $gateway, activeGatewayConnectionId } from '@/store/gateway'
-import { requestOnboardingGateway } from '@/store/onboarding-scope'
+import { captureOnboardingScope, requestOnboardingGateway } from '@/store/onboarding-scope'
 
 interface DesktopOnboardingOverlayProps {
   enabled: boolean
@@ -215,7 +215,7 @@ export function DesktopOnboardingOverlay({
   const connectionId = activeGatewayConnectionId()
 
   const scope = useMemo(
-    () => onboarding.targetScope ?? { connectionId, profile },
+    () => onboarding.targetScope ?? captureOnboardingScope({ connectionId, profile }),
     [onboarding.targetScope, profile, connectionId]
   )
 
diff --git a/apps/desktop/src/store/onboarding-owner.test.ts b/apps/desktop/src/store/onboarding-owner.test.ts
index 015f150157..55e7bb15ae 100644
--- a/apps/desktop/src/store/onboarding-owner.test.ts
+++ b/apps/desktop/src/store/onboarding-owner.test.ts
@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, expect, it, vi } from 'vitest'
 
 import { setApiRequestConnection, setApiRequestProfile } from '@/api/client'
+import { setEnvVar } from '@/api/config'
 import type { HermesApiRequest } from '@/global'
 import { makeOAuthProvider } from '@/test/oauth-provider'
 
@@ -15,7 +16,14 @@ import {
   startProviderOAuth,
   submitOnboardingCode
 } from './onboarding'
-import { captureOnboardingScope } from './onboarding-scope'
+import { captureOnboardingScope, requestOnboardingGateway } from './onboarding-scope'
+
+const gatewayMocks = vi.hoisted(() => ({ requestGatewayForAgent: vi.fn(async () => ({ ok: true })) }))
+
+vi.mock('@/store/gateway', async importOriginal => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  requestGatewayForAgent: gatewayMocks.requestGatewayForAgent
+}))
 
 const owner = { connectionId: 'athena', profile: 'leverage-ai' }
 const requests: HermesApiRequest[] = []
@@ -175,9 +183,36 @@ it('preserves explicit local and untagged legacy routes instead of filling ambie
     connectionId: 'local',
     profile: 'default'
   })
-  expect(captureOnboardingScope({ profile: 'legacy' })).toEqual({ profile: 'legacy' })
+  expect(captureOnboardingScope({ profile: 'legacy' })).toEqual({ connectionId: null, profile: 'legacy' })
   setApiRequestConnection(null)
   const legacy = captureOnboardingScope('legacy')
   setApiRequestConnection('athena')
   expect(legacy).toEqual({ connectionId: null, profile: 'legacy' })
 })
+
+// A setup owner without a profile writes REST settings to the backend's launch
+// home (no ?profile=). Readiness on a shared backend must target that same home,
+// not a hard-coded `default` profile that may be a different one.
+it('keeps readiness on the same profile as REST writes when the owner has none', async () => {
+  const getConnectionFor = vi.fn(async () => ({ sharedRemote: true }))
+  Object.assign(window.hermesDesktop, { getConnection: vi.fn(), getConnectionFor })
+  setApiRequestProfile(null)
+  const scope = captureOnboardingScope()
+
+  expect(scope).toEqual({ connectionId: 'athena', profile: null })
+  expect(captureOnboardingScope({ connectionId: 'athena', profile: '  ' })).toEqual(scope)
+
+  await setEnvVar('OPENAI_API_KEY', 'fixture', scope)
+  expect(requests.at(-1)).toMatchObject({ connectionId: 'athena' })
+  expect(requests.at(-1)).not.toHaveProperty('profile')
+
+  await requestOnboardingGateway(scope, 'setup.runtime_check', { provider: 'custom' })
+  expect(gatewayMocks.requestGatewayForAgent).toHaveBeenLastCalledWith('athena', 'default', 'setup.runtime_check', {
+    provider: 'custom'
+  })
+
+  await requestOnboardingGateway(owner, 'setup.runtime_check', {})
+  expect(gatewayMocks.requestGatewayForAgent).toHaveBeenLastCalledWith('athena', 'leverage-ai', 'setup.runtime_check', {
+    profile: 'leverage-ai'
+  })
+})
diff --git a/apps/desktop/src/store/onboarding-scope.ts b/apps/desktop/src/store/onboarding-scope.ts
index f73dafa4ad..7004c18d1f 100644
--- a/apps/desktop/src/store/onboarding-scope.ts
+++ b/apps/desktop/src/store/onboarding-scope.ts
@@ -8,16 +8,16 @@ export interface OnboardingScope {
 }
 
 /** Capture both halves once. An absent connection keeps legacy per-profile
- * routing; it must not acquire a different ambient registry owner later. */
+ * routing; it must not acquire a different ambient registry owner later.
+ * A blank profile is normalized to null: REST writes then carry no profile
+ * (the backend's launch home), and readiness must omit it the same way. */
 export function captureOnboardingScope(scope?: ProfileScope): OnboardingScope {
-  if (scope && typeof scope === 'object') {
-    return { ...scope }
-  }
+  const captured =
+    scope && typeof scope === 'object'
+      ? scope
+      : { connectionId: getApiRequestConnection(), profile: scope === undefined ? getApiRequestProfile() : scope }
 
-  return {
-    connectionId: getApiRequestConnection(),
-    profile: scope === undefined ? getApiRequestProfile() : scope
-  }
+  return { connectionId: captured.connectionId ?? null, profile: captured.profile?.trim() || null }
 }
 
 /** Desktop profile keys can be SSH aliases. Only shared descriptors interpret
@@ -27,6 +27,7 @@ export async function requestOnboardingGateway<T>(
   method: string,
   params: Record<string, unknown> = {}
 ): Promise<T> {
+  // `default` is only the Desktop routing key for the launch home here.
   const profile = scope.profile || 'default'
   const desktop = window.hermesDesktop
 
@@ -46,8 +47,8 @@ export async function requestOnboardingGateway<T>(
 
   delete routedParams.profile
 
-  if (connection.sharedPrimary || connection.sharedRemote) {
-    routedParams.profile = profile
+  if (scope.profile && (connection.sharedPrimary || connection.sharedRemote)) {
+    routedParams.profile = scope.profile
   }
 
   return requestGatewayForAgent<T>(scope.connectionId ?? null, profile, method, routedParams)

From 6fa17e8728670d6c0525cf9fa35710cbe3cd40e9 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:37:07 -0700
Subject: [PATCH 30/61] test: trim salvage tests to invariants

Keep the real-Electron e2e spec (provider-setup-owner.spec.ts, the live repro: it fails on origin/main with setup readiness sent to the local backend) and one store-level invariant file (onboarding-owner.test.ts: OAuth start/poll/submit/cancel, local endpoint, model edits and readiness stay on the captured owner across a foreground switch). The component-level and route-lookup duplicates cover the same invariant through mocks.
---
 .../src/app/model-picker-overlay.test.tsx     |  82 ------
 .../onboarding/connection-owner.test.tsx      | 243 ------------------
 .../src/store/onboarding-scope.test.ts        |  76 ------
 3 files changed, 401 deletions(-)
 delete mode 100644 apps/desktop/src/app/model-picker-overlay.test.tsx
 delete mode 100644 apps/desktop/src/components/onboarding/connection-owner.test.tsx
 delete mode 100644 apps/desktop/src/store/onboarding-scope.test.ts

diff --git a/apps/desktop/src/app/model-picker-overlay.test.tsx b/apps/desktop/src/app/model-picker-overlay.test.tsx
deleted file mode 100644
index 347fa6b8c6..0000000000
--- a/apps/desktop/src/app/model-picker-overlay.test.tsx
+++ /dev/null
@@ -1,82 +0,0 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
-import type { WritableAtom } from 'nanostores'
-import { afterEach, expect, it, vi } from 'vitest'
-
-import { I18nProvider } from '@/i18n'
-import { requestModelOptions } from '@/lib/model-options'
-import { startManualOnboarding } from '@/store/onboarding'
-import { $gatewayState, $modelPickerOpen, $selectedStoredSessionId } from '@/store/session'
-import { $focusedTreePaneId as $focusedTreePaneIdMock } from '@/store/session-focus'
-import { $sessionTiles } from '@/store/session-states'
-import { stubMenuDomApis, stubResizeObserver } from '@/test/jsdom'
-
-import { ModelPickerOverlay } from './model-picker-overlay'
-
-// The mock below replaces the computed store with a writable atom.
-const $focusedTreePaneId = $focusedTreePaneIdMock as unknown as WritableAtom<null | string>
-
-vi.mock('@/store/session-focus', async () => {
-  const { atom } = await import('nanostores')
-
-  return { $focusedTreePaneId: atom<null | string>(null) }
-})
-vi.mock('@/hermes', async importOriginal => ({
-  ...(await importOriginal<Record<string, unknown>>()),
-  getLocalModelsStatus: vi.fn().mockResolvedValue({ loading: {} })
-}))
-vi.mock('@/lib/model-options', async importOriginal => ({
-  ...(await importOriginal<Record<string, unknown>>()),
-  requestModelOptions: vi.fn().mockResolvedValue({ model: '', provider: '', providers: [] })
-}))
-vi.mock('@/store/onboarding', async importOriginal => ({
-  ...(await importOriginal<Record<string, unknown>>()),
-  startManualOnboarding: vi.fn()
-}))
-
-stubResizeObserver()
-stubMenuDomApis()
-
-afterEach(() => {
-  cleanup()
-  vi.clearAllMocks()
-  $sessionTiles.set([])
-  $focusedTreePaneId.set(null)
-  $selectedStoredSessionId.set(null)
-  $modelPickerOpen.set(false)
-  $gatewayState.set('idle')
-})
-
-it('reads the catalog from the backend profile but hands the Desktop alias to provider setup', async () => {
-  $gatewayState.set('open')
-  $modelPickerOpen.set(true)
-  $selectedStoredSessionId.set('primary-a')
-  $sessionTiles.set([
-    {
-      ownerRoute: { connectionId: 'connection-b', profile: 'desktop-b', targetProfile: 'backend-b' },
-      storedSessionId: 'tile-b'
-    }
-  ])
-  $focusedTreePaneId.set('session-tile:tile-b')
-  const client = new QueryClient({ defaultOptions: { queries: { retry: false } } })
-
-  render(
-    <QueryClientProvider client={client}>
-      <I18nProvider>
-        <ModelPickerOverlay
-          onSelect={() => undefined}
-          ownerConnectionId="connection-a"
-          profile="default"
-          requestGateway={async () => undefined as never}
-        />
-      </I18nProvider>
-    </QueryClientProvider>
-  )
-
-  await waitFor(() => expect(requestModelOptions).toHaveBeenCalled())
-  expect(vi.mocked(requestModelOptions).mock.calls.every(([options]) => options.profile === 'backend-b')).toBe(true)
-
-  fireEvent.click(await screen.findByRole('button', { name: 'Add provider' }))
-  expect(startManualOnboarding).toHaveBeenCalledWith(undefined, { connectionId: 'connection-b', profile: 'desktop-b' })
-  client.clear()
-})
diff --git a/apps/desktop/src/components/onboarding/connection-owner.test.tsx b/apps/desktop/src/components/onboarding/connection-owner.test.tsx
deleted file mode 100644
index 35bddedbd0..0000000000
--- a/apps/desktop/src/components/onboarding/connection-owner.test.tsx
+++ /dev/null
@@ -1,243 +0,0 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
-import { afterEach, expect, it, vi } from 'vitest'
-
-import { setApiRequestConnection, setApiRequestProfile } from '@/api/client'
-import { startOAuthLogin } from '@/api/config'
-import type { HermesApiRequest } from '@/global'
-import type * as HermesApi from '@/hermes'
-import {
-  closeSecondaryGateways,
-  configureGatewayRegistry,
-  ensureGatewayForAgent,
-  requestGatewayForAgent,
-  setPrimaryGateway,
-  setPrimaryGatewayConnection
-} from '@/store/gateway'
-import type * as OnboardingStore from '@/store/onboarding'
-import {
-  $desktopOnboarding,
-  closeManualOnboarding,
-  type OnboardingContext,
-  startManualProviderOAuth
-} from '@/store/onboarding'
-import { stubMenuDomApis, stubResizeObserver } from '@/test/jsdom'
-import { makeOAuthProvider } from '@/test/oauth-provider'
-
-import { FlowPanel } from './flow'
-
-import { DesktopOnboardingOverlay } from '.'
-
-stubResizeObserver()
-stubMenuDomApis()
-
-// Boundary test: real overlay/API helpers/gateway router; no OAuth
-// account or production backend. Intercept acquisition to inspect its context.
-const mocks = vi.hoisted(() => ({
-  begin: vi.fn(),
-  rpc: vi.fn(async () => ({ ok: true }))
-}))
-
-vi.mock('@/store/onboarding', async importOriginal => ({
-  ...(await importOriginal<typeof OnboardingStore>()),
-  startProviderOAuth: mocks.begin
-}))
-vi.mock('@/hermes', async importOriginal => ({
-  ...(await importOriginal<typeof HermesApi>()),
-  HermesGateway: class {
-    connectionState = 'closed'
-    connect = async () => {
-      this.connectionState = 'open'
-    }
-    request = mocks.rpc
-    close = () => {
-      this.connectionState = 'closed'
-    }
-    onEvent = () => () => {}
-    onState = () => () => {}
-  }
-}))
-vi.mock('@/store/notify-baseline', () => ({ markNativeNotifyBaseline: vi.fn() }))
-
-const provider = { ...makeOAuthProvider('openai-codex'), flow: 'device_code' as const }
-
-afterEach(() => {
-  cleanup()
-  closeManualOnboarding()
-  closeSecondaryGateways()
-  setApiRequestConnection(null)
-  setApiRequestProfile(null)
-  vi.clearAllMocks()
-  delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
-})
-
-it.each([
-  { profile: 'leverage-ai', sharedRemote: true },
-  { profile: 'custom', sharedRemote: true },
-  { profile: 'mara', sharedRemote: false }
-])('keeps Settings readiness on its owner ($profile, shared=$sharedRemote)', async ({ profile, sharedRemote }) => {
-  const localRequest = vi.fn(async () => ({ ok: true }))
-
-  const localDial = vi.fn(async () => {
-    throw new Error('Diagnostic local backend has no remote-only profile')
-  })
-
-  const remoteDial = vi.fn(async ({ connectionId, profile: routeProfile }) => ({
-    connectionId,
-    profile: routeProfile,
-    sharedRemote,
-    ...(sharedRemote ? {} : { remoteKind: 'ssh', remoteProfile: 'remote-research' }),
-    mode: 'remote',
-    authMode: 'token',
-    baseUrl: 'https://athena.invalid',
-    wsUrl: 'wss://athena.invalid/api/ws',
-    token: 'fixture-only'
-  }))
-
-  const api = vi.fn(async () => ({ providers: [provider] }))
-  Object.defineProperty(window, 'hermesDesktop', {
-    configurable: true,
-    value: {
-      api,
-      getConnection: localDial,
-      getConnectionFor: remoteDial,
-      touchBackend: vi.fn(async () => undefined)
-    }
-  })
-  configureGatewayRegistry({ onEvent: vi.fn() })
-  setPrimaryGateway({ connectionState: 'open', request: localRequest } as never, 'default')
-  setPrimaryGatewayConnection({ connectionId: 'local' })
-  await ensureGatewayForAgent('athena', profile)
-  setApiRequestConnection('athena')
-  setApiRequestProfile(profile)
-  localDial.mockClear()
-
-  await act(async () => {
-    startManualProviderOAuth('openai-codex', profile)
-  })
-  render(
-    <DesktopOnboardingOverlay
-      enabled={false}
-      profile={profile}
-      requestGateway={(method, params) => requestGatewayForAgent('athena', profile, method, params)}
-    />
-  )
-  await waitFor(() => expect(mocks.begin).toHaveBeenCalledOnce())
-  const context = mocks.begin.mock.calls[0][1] as OnboardingContext
-
-  // Switching the foreground device must not retarget a pending setup.
-  setApiRequestConnection('local')
-  setApiRequestProfile('default')
-  await startOAuthLogin('openai-codex', context.scope)
-  expect(api).toHaveBeenLastCalledWith(
-    expect.objectContaining({
-      connectionId: 'athena',
-      profile,
-      path: '/api/providers/oauth/openai-codex/start'
-    })
-  )
-  await context.requestGateway('setup.status')
-  await context.requestGateway('setup.runtime_check', { provider: 'openai-codex' })
-  await context.requestGateway('model.options', { profile, explicit_only: true })
-  const params = sharedRemote ? { profile } : {}
-  expect(mocks.rpc).toHaveBeenCalledWith('setup.status', params)
-  expect(localDial).not.toHaveBeenCalled()
-  expect(mocks.rpc).toHaveBeenCalledWith('setup.runtime_check', { provider: 'openai-codex', ...params })
-  expect(mocks.rpc).toHaveBeenCalledWith('model.options', { explicit_only: true, ...params })
-  expect(localRequest).not.toHaveBeenCalled()
-})
-
-it('keeps an explicitly untagged owner through Change → Add provider', async () => {
-  const owner = { connectionId: null, profile: 'legacy' }
-  const api = vi.fn(async (_request: HermesApiRequest) => ({ providers: [] }))
-  Object.defineProperty(window, 'hermesDesktop', { configurable: true, value: { api } })
-  startManualProviderOAuth('openai-codex', owner)
-  setApiRequestConnection('athena')
-  setApiRequestProfile('default')
-  const client = new QueryClient({ defaultOptions: { queries: { retry: false } } })
-
-  render(
-    <QueryClientProvider client={client}>
-      <FlowPanel
-        ctx={{ scope: owner, profile: owner.profile, requestGateway: async () => ({ providers: [] }) as never }}
-        flow={{
-          status: 'confirming_model',
-          currentModel: 'fixture-model',
-          providerSlug: 'openai-codex',
-          label: 'Codex',
-          saving: false
-        }}
-        leaving={false}
-        onBegin={() => undefined}
-      />
-    </QueryClientProvider>
-  )
-  fireEvent.click(screen.getByRole('button', { name: 'Change' }))
-  fireEvent.click(await screen.findByRole('button', { name: 'Add provider' }))
-  expect($desktopOnboarding.get().targetScope).toEqual(owner)
-  await waitFor(() =>
-    expect(api).toHaveBeenCalledWith(expect.objectContaining({ path: '/api/providers/oauth', profile: 'legacy' }))
-  )
-  expect(api.mock.calls.every(([request]) => !(request as { connectionId?: string }).connectionId)).toBe(true)
-  client.clear()
-})
-
-it.each([null, undefined])('pins a registry owner when its profile is %s', async profile => {
-  const localRequest = vi.fn(async (_method: string, _params?: Record<string, unknown>) => ({ ok: true }))
-
-  const localDial = vi.fn(async () => {
-    throw new Error('A registry-owned setup must not dial the legacy connection')
-  })
-
-  const remoteDial = vi.fn(async () => ({
-    connectionId: 'athena',
-    profile: 'default',
-    sharedRemote: true,
-    mode: 'remote',
-    authMode: 'token',
-    baseUrl: 'https://athena.invalid',
-    wsUrl: 'wss://athena.invalid/api/ws',
-    token: 'fixture-only'
-  }))
-
-  const api = vi.fn(async () => ({ providers: [provider] }))
-  Object.defineProperty(window, 'hermesDesktop', {
-    configurable: true,
-    value: {
-      api,
-      getConnection: localDial,
-      getConnectionFor: remoteDial,
-      touchBackend: vi.fn(async () => undefined)
-    }
-  })
-  configureGatewayRegistry({ onEvent: vi.fn() })
-  setPrimaryGateway({ connectionState: 'open', request: localRequest } as never, 'default')
-  setPrimaryGatewayConnection({ connectionId: 'local' })
-  setApiRequestConnection('local')
-  setApiRequestProfile('default')
-
-  await act(async () => {
-    startManualProviderOAuth('openai-codex', { connectionId: 'athena', profile })
-  })
-  render(
-    <DesktopOnboardingOverlay
-      enabled={false}
-      profile="default"
-      requestGateway={async (method, params) => (await localRequest(method, params)) as never}
-    />
-  )
-  await waitFor(() => expect(mocks.begin).toHaveBeenCalledOnce())
-  const context = mocks.begin.mock.calls[0][1] as OnboardingContext
-
-  await startOAuthLogin('openai-codex', context.scope)
-  expect(api).toHaveBeenLastCalledWith(
-    expect.objectContaining({ connectionId: 'athena', path: '/api/providers/oauth/openai-codex/start' })
-  )
-  await context.requestGateway('setup.status')
-  await context.requestGateway('setup.runtime_check', { provider: 'openai-codex' })
-  expect(remoteDial).toHaveBeenCalledWith({ connectionId: 'athena', profile: 'default' })
-  expect(mocks.rpc).toHaveBeenCalledWith('setup.status', { profile: 'default' })
-  expect(mocks.rpc).toHaveBeenCalledWith('setup.runtime_check', { provider: 'openai-codex', profile: 'default' })
-  expect(localDial).not.toHaveBeenCalled()
-  expect(localRequest).not.toHaveBeenCalled()
-})
diff --git a/apps/desktop/src/store/onboarding-scope.test.ts b/apps/desktop/src/store/onboarding-scope.test.ts
deleted file mode 100644
index f7e9e662ef..0000000000
--- a/apps/desktop/src/store/onboarding-scope.test.ts
+++ /dev/null
@@ -1,76 +0,0 @@
-import { afterEach, expect, it, vi } from 'vitest'
-
-import { isTimeoutError, RECONNECT_ATTEMPT_TIMEOUT_MS } from '@/lib/with-timeout'
-
-import { requestOnboardingGateway } from './onboarding-scope'
-
-const mocks = vi.hoisted(() => ({ request: vi.fn(async () => ({ ok: true })) }))
-
-vi.mock('@/store/gateway', () => ({ requestGatewayForAgent: mocks.request }))
-
-const owner = { connectionId: 'athena', profile: 'leverage-ai' }
-
-function installDesktop(bridge: Record<string, unknown>) {
-  const getConnection = vi.fn(async () => ({ sharedPrimary: true }))
-  Object.defineProperty(window, 'hermesDesktop', { configurable: true, value: { getConnection, ...bridge } })
-
-  return getConnection
-}
-
-afterEach(() => {
-  vi.useRealTimers()
-  vi.clearAllMocks()
-  delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
-})
-
-// Each failure must surface without sending the RPC anywhere, and without
-// falling back to the profile-only resolver that would pick another device.
-it('rejects a registry owner on a bridge that cannot dial registry connections', async () => {
-  const getConnection = installDesktop({})
-
-  await expect(requestOnboardingGateway(owner, 'setup.runtime_check')).rejects.toThrow(/Update Hermes Desktop/)
-  expect(getConnection).not.toHaveBeenCalled()
-  expect(mocks.request).not.toHaveBeenCalled()
-})
-
-it('surfaces a removed registry connection instead of retargeting setup', async () => {
-  const getConnectionFor = vi.fn(async () => {
-    throw new Error('No connection with id "athena"')
-  })
-
-  const getConnection = installDesktop({ getConnectionFor })
-
-  await expect(requestOnboardingGateway(owner, 'setup.runtime_check')).rejects.toThrow('No connection with id "athena"')
-  expect(getConnectionFor).toHaveBeenCalledWith({ connectionId: 'athena', profile: 'leverage-ai' })
-  expect(getConnection).not.toHaveBeenCalled()
-  expect(mocks.request).not.toHaveBeenCalled()
-})
-
-it('times out a wedged connection lookup', async () => {
-  vi.useFakeTimers()
-  const getConnectionFor = vi.fn(() => new Promise(() => undefined))
-  const getConnection = installDesktop({ getConnectionFor })
-  const pending = requestOnboardingGateway(owner, 'setup.runtime_check').catch((error: unknown) => error)
-
-  await vi.advanceTimersByTimeAsync(RECONNECT_ATTEMPT_TIMEOUT_MS)
-  const error = await pending
-
-  expect(isTimeoutError(error)).toBe(true)
-  expect((error as Error).message).toBe('Timed out resolving provider setup for "leverage-ai"')
-  expect(getConnection).not.toHaveBeenCalled()
-  expect(mocks.request).not.toHaveBeenCalled()
-})
-
-it('surfaces a failed legacy lookup for an untagged owner', async () => {
-  const getConnection = vi.fn(async () => {
-    throw new Error('Profile "legacy" is unavailable')
-  })
-
-  installDesktop({ getConnection, getConnectionFor: vi.fn() })
-
-  await expect(requestOnboardingGateway({ connectionId: null, profile: 'legacy' }, 'setup.status')).rejects.toThrow(
-    'Profile "legacy" is unavailable'
-  )
-  expect(getConnection).toHaveBeenCalledWith('legacy')
-  expect(mocks.request).not.toHaveBeenCalled()
-})

From fec49203b612728f3a04279f4fee152ad152698d Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:31:57 -0700
Subject: [PATCH 31/61] test: restore picker alias handoff coverage

The trim commit dropped model-picker-overlay.test.tsx, the only test
pinning the picker's Add provider handoff: provider setup must receive the
Desktop route alias (ownerRoute.profile), while the catalog keeps reading
from the backend targetProfile. Without it, deleting the overlay's
setupProfile prop left every suite green and SSH-alias setup would scope
onboarding to the backend profile again.

Restored from BearHuddleston's 5062e9165a7. Removing the setupProfile line
turns it red (profile "backend-b" instead of "desktop-b").
---
 .../src/app/model-picker-overlay.test.tsx     | 82 +++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 apps/desktop/src/app/model-picker-overlay.test.tsx

diff --git a/apps/desktop/src/app/model-picker-overlay.test.tsx b/apps/desktop/src/app/model-picker-overlay.test.tsx
new file mode 100644
index 0000000000..347fa6b8c6
--- /dev/null
+++ b/apps/desktop/src/app/model-picker-overlay.test.tsx
@@ -0,0 +1,82 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import type { WritableAtom } from 'nanostores'
+import { afterEach, expect, it, vi } from 'vitest'
+
+import { I18nProvider } from '@/i18n'
+import { requestModelOptions } from '@/lib/model-options'
+import { startManualOnboarding } from '@/store/onboarding'
+import { $gatewayState, $modelPickerOpen, $selectedStoredSessionId } from '@/store/session'
+import { $focusedTreePaneId as $focusedTreePaneIdMock } from '@/store/session-focus'
+import { $sessionTiles } from '@/store/session-states'
+import { stubMenuDomApis, stubResizeObserver } from '@/test/jsdom'
+
+import { ModelPickerOverlay } from './model-picker-overlay'
+
+// The mock below replaces the computed store with a writable atom.
+const $focusedTreePaneId = $focusedTreePaneIdMock as unknown as WritableAtom<null | string>
+
+vi.mock('@/store/session-focus', async () => {
+  const { atom } = await import('nanostores')
+
+  return { $focusedTreePaneId: atom<null | string>(null) }
+})
+vi.mock('@/hermes', async importOriginal => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  getLocalModelsStatus: vi.fn().mockResolvedValue({ loading: {} })
+}))
+vi.mock('@/lib/model-options', async importOriginal => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  requestModelOptions: vi.fn().mockResolvedValue({ model: '', provider: '', providers: [] })
+}))
+vi.mock('@/store/onboarding', async importOriginal => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  startManualOnboarding: vi.fn()
+}))
+
+stubResizeObserver()
+stubMenuDomApis()
+
+afterEach(() => {
+  cleanup()
+  vi.clearAllMocks()
+  $sessionTiles.set([])
+  $focusedTreePaneId.set(null)
+  $selectedStoredSessionId.set(null)
+  $modelPickerOpen.set(false)
+  $gatewayState.set('idle')
+})
+
+it('reads the catalog from the backend profile but hands the Desktop alias to provider setup', async () => {
+  $gatewayState.set('open')
+  $modelPickerOpen.set(true)
+  $selectedStoredSessionId.set('primary-a')
+  $sessionTiles.set([
+    {
+      ownerRoute: { connectionId: 'connection-b', profile: 'desktop-b', targetProfile: 'backend-b' },
+      storedSessionId: 'tile-b'
+    }
+  ])
+  $focusedTreePaneId.set('session-tile:tile-b')
+  const client = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+
+  render(
+    <QueryClientProvider client={client}>
+      <I18nProvider>
+        <ModelPickerOverlay
+          onSelect={() => undefined}
+          ownerConnectionId="connection-a"
+          profile="default"
+          requestGateway={async () => undefined as never}
+        />
+      </I18nProvider>
+    </QueryClientProvider>
+  )
+
+  await waitFor(() => expect(requestModelOptions).toHaveBeenCalled())
+  expect(vi.mocked(requestModelOptions).mock.calls.every(([options]) => options.profile === 'backend-b')).toBe(true)
+
+  fireEvent.click(await screen.findByRole('button', { name: 'Add provider' }))
+  expect(startManualOnboarding).toHaveBeenCalledWith(undefined, { connectionId: 'connection-b', profile: 'desktop-b' })
+  client.clear()
+})

From 03a7bf3047c5b95a6c44be88ac51ffada09b5261 Mon Sep 17 00:00:00 2001
From: Gabby Ong <gabbyong@google.com>
Date: Thu, 24 Sep 2026 09:18:55 +0800
Subject: [PATCH 32/61] fix(gemini): wire response_format into native Gemini
 generationConfig

Translates OpenAI-style response_format into Gemini's generationConfig as
responseMimeType plus responseJsonSchema on v1beta or responseSchema elsewhere,
reusing the existing tool-schema preparation so $ref inlining and key stripping
stay consistent. The translation is skipped when tool_choice forces function
calling, since Gemini rejects mode ANY combined with a JSON response type.
---
 agent/gemini_native_adapter.py            | 39 +++++++++--
 tests/agent/test_gemini_native_adapter.py | 80 +++++++++++++++++++++++
 2 files changed, 114 insertions(+), 5 deletions(-)

diff --git a/agent/gemini_native_adapter.py b/agent/gemini_native_adapter.py
index 35385fb677..c09d34ba69 100644
--- a/agent/gemini_native_adapter.py
+++ b/agent/gemini_native_adapter.py
@@ -503,18 +503,38 @@ def _effective_gemini_max_output_tokens(max_tokens: Optional[int], thinking_conf
     return requested
 
 
+def _translate_response_format(response_format: Any, *, json_schema: bool = False) -> Dict[str, Any]:
+    """OpenAI ``response_format`` → Gemini ``generationConfig`` JSON-output keys.
+
+    Full-JSON-Schema ``responseJsonSchema`` exists only on the generativelanguage ``v1beta``
+    surface (same gate as ``parametersJsonSchema``); ``v1`` / ``v1alpha``, Vertex express
+    ``v1beta1`` and unknown proxies take the OpenAPI-subset ``responseSchema`` path.
+    """
+    if not isinstance(response_format, dict) or response_format.get("type") not in ("json_object", "json_schema"):
+        return {}
+    spec = response_format.get("json_schema") if response_format.get("type") == "json_schema" else None
+    # A ``json_schema`` spec with no ``schema`` key has nothing to constrain with (the Anthropic
+    # translator bails the same way) — ask for JSON and let the model shape it.
+    schema = spec.get("schema") if isinstance(spec, dict) else None
+    if not isinstance(schema, dict):
+        return {"responseMimeType": "application/json"}
+    key, prep = ("responseJsonSchema", prepare_gemini_tool_parameters) if json_schema else ("responseSchema", sanitize_gemini_tool_parameters)
+    return {"responseMimeType": "application/json", key: prep(schema)}
+
+
 def build_gemini_request(
     *, messages: List[Dict[str, Any]], tools: Any = None, tool_choice: Any = None, temperature: Optional[float] = None,
     max_tokens: Optional[int] = None, top_p: Optional[float] = None, stop: Any = None, thinking_config: Any = None,
-    model: str = "", tools_as_json_schema: bool = False,
+    response_format: Any = None, model: str = "", tools_as_json_schema: bool = False,
 ) -> Dict[str, Any]:
     # Gemini 3+ both requires tool-call ids and accepts multimodal functionResponse parts.
     is_gemini3 = gemini_requires_tool_call_ids(model)
     contents, system_instruction = _build_gemini_contents(messages, include_tool_call_ids=is_gemini3, is_gemini3=is_gemini3)
+    tool_config = _translate_tool_choice_to_gemini(tool_choice)
     optional = (
         ("systemInstruction", system_instruction),
         ("tools", _translate_tools_to_gemini(tools, json_schema=tools_as_json_schema)),
-        ("toolConfig", _translate_tool_choice_to_gemini(tool_choice)),
+        ("toolConfig", tool_config),
     )
     request: Dict[str, Any] = {"contents": contents, **{k: v for k, v in optional if v}}
     # Key order is part of the wire format (prompt-cache parity): temperature, maxOutputTokens, topP, stop, thinking.
@@ -523,7 +543,14 @@ def build_gemini_request(
         ("topP", top_p), ("stopSequences", (stop if isinstance(stop, list) else [str(stop)]) if stop else None),
         ("thinkingConfig", _normalize_thinking_config(thinking_config)),
     )
-    request["generationConfig"] = {k: v for k, v in generation if v is not None}
+    json_output = _translate_response_format(response_format, json_schema=tools_as_json_schema)
+    # Gemini 400s when forced function calling (mode ANY, from ``tool_choice="required"`` or a named
+    # function) is combined with a JSON responseMimeType — pre-Gemini-3 models reject JSON output
+    # alongside function declarations at all. The forced call wins; JSON can come on a later turn.
+    if json_output and (tool_config or {}).get("functionCallingConfig", {}).get("mode") == "ANY":
+        logger.debug("Gemini: dropping JSON response_format — tool_choice forces function calling (mode ANY)")
+        json_output = {}
+    request["generationConfig"] = {**{k: v for k, v in generation if v is not None}, **json_output}
     return request
 
 
@@ -824,12 +851,14 @@ class GeminiNativeClient:
     def _create_chat_completion(
         self, *, model: str = "gemini-3.7-flash", messages: Optional[List[Dict[str, Any]]] = None, stream: bool = False,
         tools: Any = None, tool_choice: Any = None, temperature: Optional[float] = None, max_tokens: Optional[int] = None,
-        top_p: Optional[float] = None, stop: Any = None, extra_body: Optional[Dict[str, Any]] = None, timeout: Any = None, **_: Any,
+        top_p: Optional[float] = None, stop: Any = None, response_format: Any = None, extra_body: Optional[Dict[str, Any]] = None,
+        timeout: Any = None, **_: Any,
     ) -> Any:
         extra = extra_body if isinstance(extra_body, dict) else {}
         request = build_gemini_request(
             messages=messages or [], tools=tools, tool_choice=tool_choice, temperature=temperature, max_tokens=max_tokens,
-            top_p=top_p, stop=stop, thinking_config=extra.get("thinking_config") or extra.get("thinkingConfig"), model=model,
+            top_p=top_p, stop=stop, thinking_config=extra.get("thinking_config") or extra.get("thinkingConfig"),
+            response_format=response_format or extra.get("response_format"), model=model,
             tools_as_json_schema=gemini_accepts_parameters_json_schema(self.base_url),
         )
         model = bare_gemini_model_id(model)
diff --git a/tests/agent/test_gemini_native_adapter.py b/tests/agent/test_gemini_native_adapter.py
index 145cc4289e..403c9c50d2 100644
--- a/tests/agent/test_gemini_native_adapter.py
+++ b/tests/agent/test_gemini_native_adapter.py
@@ -870,3 +870,83 @@ def test_response_without_thinking_tokens_keeps_its_output_count():
     assert usage.completion_tokens == visible
     assert usage.prompt_tokens + usage.completion_tokens == usage.total_tokens
     assert normalize_usage(usage, provider="google").reasoning_tokens == 0
+
+
+def test_build_gemini_request_translates_response_format():
+    from agent.gemini_native_adapter import build_gemini_request
+
+    schema = {"type": "object", "properties": {"ok": {"type": "boolean"}}, "required": ["ok"]}
+    req = build_gemini_request(
+        messages=[{"role": "user", "content": "hi"}],
+        response_format={"type": "json_schema", "json_schema": {"name": "out", "schema": schema}},
+        tools_as_json_schema=True,
+    )
+    assert req["generationConfig"]["responseMimeType"] == "application/json"
+    assert req["generationConfig"]["responseJsonSchema"] == schema
+
+
+def test_build_gemini_request_json_object_sets_mime_type_only():
+    from agent.gemini_native_adapter import build_gemini_request
+
+    generation = build_gemini_request(
+        messages=[{"role": "user", "content": "hi"}],
+        response_format={"type": "json_object"},
+        tools_as_json_schema=True,
+    )["generationConfig"]
+    assert generation["responseMimeType"] == "application/json"
+    assert "responseJsonSchema" not in generation and "responseSchema" not in generation
+
+
+def test_build_gemini_request_response_schema_path_sanitizes_schema():
+    """Non-v1beta surfaces (v1, Vertex express v1beta1) take the OpenAPI-subset responseSchema key."""
+    from agent.gemini_native_adapter import build_gemini_request
+
+    schema = {"type": "object", "properties": {"ok": {"type": "boolean"}}, "additionalProperties": False}
+    generation = build_gemini_request(
+        messages=[{"role": "user", "content": "hi"}],
+        response_format={"type": "json_schema", "json_schema": {"name": "out", "schema": schema}},
+        tools_as_json_schema=False,
+    )["generationConfig"]
+    assert "responseJsonSchema" not in generation
+    assert generation["responseSchema"] == {"type": "object", "properties": {"ok": {"type": "boolean"}}}
+
+
+def test_build_gemini_request_json_schema_without_schema_key_falls_back_to_mime_type():
+    from agent.gemini_native_adapter import build_gemini_request
+
+    generation = build_gemini_request(
+        messages=[{"role": "user", "content": "hi"}],
+        response_format={"type": "json_schema", "json_schema": {"name": "out"}},
+        tools_as_json_schema=True,
+    )["generationConfig"]
+    assert generation["responseMimeType"] == "application/json"
+    assert "responseJsonSchema" not in generation and "responseSchema" not in generation
+
+
+@pytest.mark.parametrize("tool_choice", ["required", {"type": "function", "function": {"name": "lookup"}}])
+def test_build_gemini_request_drops_json_output_when_tool_choice_forces_calls(tool_choice):
+    """Gemini 400s on forced function calling (mode ANY) combined with a JSON responseMimeType."""
+    from agent.gemini_native_adapter import build_gemini_request
+
+    generation = build_gemini_request(
+        messages=[{"role": "user", "content": "hi"}],
+        tools=[{"type": "function", "function": {"name": "lookup", "parameters": {"type": "object"}}}],
+        tool_choice=tool_choice,
+        response_format={"type": "json_schema", "json_schema": {"name": "out", "schema": {"type": "object"}}},
+        tools_as_json_schema=True,
+    )["generationConfig"]
+    assert "responseMimeType" not in generation
+    assert "responseJsonSchema" not in generation and "responseSchema" not in generation
+
+
+def test_build_gemini_request_keeps_json_output_when_tool_choice_is_auto():
+    from agent.gemini_native_adapter import build_gemini_request
+
+    generation = build_gemini_request(
+        messages=[{"role": "user", "content": "hi"}],
+        tools=[{"type": "function", "function": {"name": "lookup", "parameters": {"type": "object"}}}],
+        tool_choice="auto",
+        response_format={"type": "json_object"},
+        tools_as_json_schema=True,
+    )["generationConfig"]
+    assert generation["responseMimeType"] == "application/json"

From b6d38fddd42ec96fcaaf43b14b5f00efd90a4e0c Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:41:49 -0700
Subject: [PATCH 33/61] fix(gemini): drop JSON response_format alongside tools
 on pre-Gemini-3 models

Wiring response_format into generationConfig exposed a regression main never
had: any aux call that sends tools with tool_choice=auto AND a json_schema
format (a proxy/relay shape, or a caller that declares tools and asks for
JSON) now 400s on gemini-2.5-* with "Function calling with a response mime
type: 'application/json' is unsupported", where main silently ignored the
format and answered. Only Gemini 3+ combines function declarations with
structured output (ai.google.dev/gemini-api/docs/structured-output), so the
JSON keys are dropped whenever tools are declared on a pre-Gemini-3 model,
reusing the is_gemini3 flag build_gemini_request already computes.

Tests: the seven salvaged tests are trimmed to three invariants. The
former "keeps json output when tool_choice is auto" case asserted the
regressed behaviour (model="" is pre-Gemini-3) and is replaced by the
parametrized gemini-2.5 (drops) / gemini-3 (keeps) pair; the two schema
surfaces collapse into one parametrized test; the json_object-only and
missing-schema-key fallbacks were change-detectors on the translator.

Live (gemini-2.5-flash): tools + json_schema -> HTTP 400 on the PR head,
finish=stop on this commit; json_schema without tools still returns JSON.
---
 agent/gemini_native_adapter.py            | 19 ++++---
 tests/agent/test_gemini_native_adapter.py | 68 ++++++-----------------
 2 files changed, 27 insertions(+), 60 deletions(-)

diff --git a/agent/gemini_native_adapter.py b/agent/gemini_native_adapter.py
index c09d34ba69..85ce5f3659 100644
--- a/agent/gemini_native_adapter.py
+++ b/agent/gemini_native_adapter.py
@@ -530,12 +530,9 @@ def build_gemini_request(
     # Gemini 3+ both requires tool-call ids and accepts multimodal functionResponse parts.
     is_gemini3 = gemini_requires_tool_call_ids(model)
     contents, system_instruction = _build_gemini_contents(messages, include_tool_call_ids=is_gemini3, is_gemini3=is_gemini3)
+    gemini_tools = _translate_tools_to_gemini(tools, json_schema=tools_as_json_schema)
     tool_config = _translate_tool_choice_to_gemini(tool_choice)
-    optional = (
-        ("systemInstruction", system_instruction),
-        ("tools", _translate_tools_to_gemini(tools, json_schema=tools_as_json_schema)),
-        ("toolConfig", tool_config),
-    )
+    optional = (("systemInstruction", system_instruction), ("tools", gemini_tools), ("toolConfig", tool_config))
     request: Dict[str, Any] = {"contents": contents, **{k: v for k, v in optional if v}}
     # Key order is part of the wire format (prompt-cache parity): temperature, maxOutputTokens, topP, stop, thinking.
     generation = (
@@ -545,10 +542,14 @@ def build_gemini_request(
     )
     json_output = _translate_response_format(response_format, json_schema=tools_as_json_schema)
     # Gemini 400s when forced function calling (mode ANY, from ``tool_choice="required"`` or a named
-    # function) is combined with a JSON responseMimeType — pre-Gemini-3 models reject JSON output
-    # alongside function declarations at all. The forced call wins; JSON can come on a later turn.
-    if json_output and (tool_config or {}).get("functionCallingConfig", {}).get("mode") == "ANY":
-        logger.debug("Gemini: dropping JSON response_format — tool_choice forces function calling (mode ANY)")
+    # function) is combined with a JSON responseMimeType, and pre-Gemini-3 models reject JSON output
+    # alongside ANY function declarations ("Function calling with a response mime type:
+    # 'application/json' is unsupported"); only Gemini 3+ combines tools with structured output.
+    # The tools win; JSON can come on a later turn, and callers tolerate an unconstrained reply.
+    forced_call = (tool_config or {}).get("functionCallingConfig", {}).get("mode") == "ANY"
+    if json_output and (forced_call or (gemini_tools and not is_gemini3)):
+        logger.debug("Gemini: dropping JSON response_format — %s",
+                     "tool_choice forces function calling (mode ANY)" if forced_call else "pre-Gemini-3 model with tools")
         json_output = {}
     request["generationConfig"] = {**{k: v for k, v in generation if v is not None}, **json_output}
     return request
diff --git a/tests/agent/test_gemini_native_adapter.py b/tests/agent/test_gemini_native_adapter.py
index 403c9c50d2..7130035452 100644
--- a/tests/agent/test_gemini_native_adapter.py
+++ b/tests/agent/test_gemini_native_adapter.py
@@ -872,81 +872,47 @@ def test_response_without_thinking_tokens_keeps_its_output_count():
     assert normalize_usage(usage, provider="google").reasoning_tokens == 0
 
 
-def test_build_gemini_request_translates_response_format():
+@pytest.mark.parametrize("json_schema_surface, key", [(True, "responseJsonSchema"), (False, "responseSchema")])
+def test_build_gemini_request_translates_response_format_on_both_schema_surfaces(json_schema_surface, key):
+    """OpenAI response_format reaches generationConfig: full JSON Schema under ``responseJsonSchema`` on
+    v1beta, the OpenAPI subset under ``responseSchema`` elsewhere (with unsupported keys stripped)."""
     from agent.gemini_native_adapter import build_gemini_request
 
-    schema = {"type": "object", "properties": {"ok": {"type": "boolean"}}, "required": ["ok"]}
-    req = build_gemini_request(
-        messages=[{"role": "user", "content": "hi"}],
-        response_format={"type": "json_schema", "json_schema": {"name": "out", "schema": schema}},
-        tools_as_json_schema=True,
-    )
-    assert req["generationConfig"]["responseMimeType"] == "application/json"
-    assert req["generationConfig"]["responseJsonSchema"] == schema
-
-
-def test_build_gemini_request_json_object_sets_mime_type_only():
-    from agent.gemini_native_adapter import build_gemini_request
-
-    generation = build_gemini_request(
-        messages=[{"role": "user", "content": "hi"}],
-        response_format={"type": "json_object"},
-        tools_as_json_schema=True,
-    )["generationConfig"]
-    assert generation["responseMimeType"] == "application/json"
-    assert "responseJsonSchema" not in generation and "responseSchema" not in generation
-
-
-def test_build_gemini_request_response_schema_path_sanitizes_schema():
-    """Non-v1beta surfaces (v1, Vertex express v1beta1) take the OpenAPI-subset responseSchema key."""
-    from agent.gemini_native_adapter import build_gemini_request
-
-    schema = {"type": "object", "properties": {"ok": {"type": "boolean"}}, "additionalProperties": False}
+    schema = {"type": "object", "properties": {"ok": {"type": "boolean"}}, "required": ["ok"], "additionalProperties": False}
     generation = build_gemini_request(
         messages=[{"role": "user", "content": "hi"}],
         response_format={"type": "json_schema", "json_schema": {"name": "out", "schema": schema}},
-        tools_as_json_schema=False,
-    )["generationConfig"]
-    assert "responseJsonSchema" not in generation
-    assert generation["responseSchema"] == {"type": "object", "properties": {"ok": {"type": "boolean"}}}
-
-
-def test_build_gemini_request_json_schema_without_schema_key_falls_back_to_mime_type():
-    from agent.gemini_native_adapter import build_gemini_request
-
-    generation = build_gemini_request(
-        messages=[{"role": "user", "content": "hi"}],
-        response_format={"type": "json_schema", "json_schema": {"name": "out"}},
-        tools_as_json_schema=True,
+        tools_as_json_schema=json_schema_surface,
     )["generationConfig"]
     assert generation["responseMimeType"] == "application/json"
-    assert "responseJsonSchema" not in generation and "responseSchema" not in generation
+    assert generation[key]["properties"] == schema["properties"] and generation[key]["required"] == ["ok"]
+    assert ("additionalProperties" in generation[key]) is json_schema_surface
 
 
 @pytest.mark.parametrize("tool_choice", ["required", {"type": "function", "function": {"name": "lookup"}}])
 def test_build_gemini_request_drops_json_output_when_tool_choice_forces_calls(tool_choice):
-    """Gemini 400s on forced function calling (mode ANY) combined with a JSON responseMimeType."""
+    """Gemini 400s on forced function calling (mode ANY) combined with a JSON responseMimeType, on every model."""
     from agent.gemini_native_adapter import build_gemini_request
 
     generation = build_gemini_request(
         messages=[{"role": "user", "content": "hi"}],
         tools=[{"type": "function", "function": {"name": "lookup", "parameters": {"type": "object"}}}],
-        tool_choice=tool_choice,
+        tool_choice=tool_choice, model="gemini-3-flash",
         response_format={"type": "json_schema", "json_schema": {"name": "out", "schema": {"type": "object"}}},
         tools_as_json_schema=True,
     )["generationConfig"]
-    assert "responseMimeType" not in generation
-    assert "responseJsonSchema" not in generation and "responseSchema" not in generation
+    assert not {"responseMimeType", "responseJsonSchema", "responseSchema"} & set(generation)
 
 
-def test_build_gemini_request_keeps_json_output_when_tool_choice_is_auto():
+@pytest.mark.parametrize("model, keeps_json", [("gemini-2.5-flash", False), ("gemini-3-flash", True)])
+def test_build_gemini_request_tools_plus_json_output_only_on_gemini3(model, keeps_json):
+    """Pre-Gemini-3 rejects function declarations alongside a JSON mime type (HTTP 400 "Function calling
+    with a response mime type: 'application/json' is unsupported"); Gemini 3+ accepts the combination."""
     from agent.gemini_native_adapter import build_gemini_request
 
     generation = build_gemini_request(
         messages=[{"role": "user", "content": "hi"}],
         tools=[{"type": "function", "function": {"name": "lookup", "parameters": {"type": "object"}}}],
-        tool_choice="auto",
-        response_format={"type": "json_object"},
-        tools_as_json_schema=True,
+        tool_choice="auto", model=model, response_format={"type": "json_object"}, tools_as_json_schema=True,
     )["generationConfig"]
-    assert generation["responseMimeType"] == "application/json"
+    assert ("responseMimeType" in generation) is keeps_json

From 236aab3e8f13ee93f10fbc82ab2ba6841f68152a Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:41:49 -0700
Subject: [PATCH 34/61] fix(auxiliary): recognise Gemini's structured-output
 400 wording

Gemini rejects an unsupported schema by naming its own generationConfig
keys ("Unknown name response_json_schema", "Invalid value at
generation_config.response_schema...", "response mime type ... is
unsupported"), never OpenAI's response_format, so such 400s bypassed the
one-retry-without-format rung and surfaced as hard failures now that the
native adapter actually sends the schema. Teach _is_structured_output_rejection
the three Gemini phrasings; the status gate (400/422 only) is unchanged.
---
 agent/auxiliary_client.py                             | 6 ++++++
 tests/agent/test_structured_output_rejection_retry.py | 4 ++++
 2 files changed, 10 insertions(+)

diff --git a/agent/auxiliary_client.py b/agent/auxiliary_client.py
index f16ef1529e..c075858bb2 100644
--- a/agent/auxiliary_client.py
+++ b/agent/auxiliary_client.py
@@ -3346,6 +3346,12 @@ def _is_structured_output_rejection(exc: Exception) -> bool:
     # without it is the same remedy, so treat the shape error as a rejection too.
     if "response_format" in err_lower and "json_schema" in err_lower:
         return True
+    # Gemini native names its own generationConfig keys, never ours: "Function calling with a response
+    # mime type: 'application/json' is unsupported" (pre-Gemini-3 + tools via a proxy), or an
+    # "Unknown name"/"Invalid value" 400 on response_schema / response_json_schema for a schema the
+    # surface cannot express. Same remedy: one retry without the format.
+    if _contains_any(err_lower, ("response mime type", "response_schema", "response_json_schema")):
+        return True
     return _is_unsupported_parameter_error(exc, "response_format") or _is_unsupported_parameter_error(exc, "output_config")
 
 
diff --git a/tests/agent/test_structured_output_rejection_retry.py b/tests/agent/test_structured_output_rejection_retry.py
index 397f40c998..ee72671134 100644
--- a/tests/agent/test_structured_output_rejection_retry.py
+++ b/tests/agent/test_structured_output_rejection_retry.py
@@ -76,6 +76,10 @@ class TestIsStructuredOutputRejection:
         # (422, verbatim body from the gateway) -- no unsupported-parameter wording
         'HTTP 422: {"detail":[{"loc":["body","response_format","json_schema"],'
         '"msg":"str type expected","type":"type_error.str"}]}',
+        # Gemini native generationConfig wording (verbatim 400s from generativelanguage)
+        "Gemini HTTP 400 (INVALID_ARGUMENT): Function calling with a response mime type: 'application/json' is unsupported",
+        "Gemini HTTP 400 (INVALID_ARGUMENT): Invalid JSON payload received. Unknown name \"response_json_schema\" at 'generation_config'",
+        "Gemini HTTP 400 (INVALID_ARGUMENT): Invalid value at 'generation_config.response_schema.properties[0].value.type'",
     ])
     def test_matches_real_provider_messages(self, message):
         assert _is_structured_output_rejection(RuntimeError(message)) is True

From 04fa849e70165336ba73e6750257a1ebd7ff998d Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:41:55 -0700
Subject: [PATCH 35/61] chore(contributors): map gabbyong's commit email

---
 contributors/emails/gabbyong@google.com | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/gabbyong@google.com

diff --git a/contributors/emails/gabbyong@google.com b/contributors/emails/gabbyong@google.com
new file mode 100644
index 0000000000..5c3d853f64
--- /dev/null
+++ b/contributors/emails/gabbyong@google.com
@@ -0,0 +1 @@
+gabbyong

From a69f86042c67719b177a6230b7c8f0ee94348a3b Mon Sep 17 00:00:00 2001
From: BearHuddleston <bear@bearhuddleston.dev>
Date: Tue, 22 Sep 2026 09:23:10 -0500
Subject: [PATCH 36/61] fix(desktop): keep image frames stable through delayed
 loads

---
 .../components/assistant-ui/markdown-text.tsx | 128 +++++++---------
 .../chat/generated-image-result.tsx           | 135 +++++------------
 .../components/chat/image-geometry.test.tsx   | 142 ++++++++++++++++++
 apps/desktop/src/hooks/use-media-image.ts     |  95 ++++++++++++
 apps/desktop/src/lib/generated-images.test.ts |  18 +++
 apps/desktop/src/lib/generated-images.ts      |  17 +++
 apps/desktop/src/lib/media-dimensions.test.ts |  45 ++++++
 apps/desktop/src/lib/media.ts                 |  68 ++++++++-
 8 files changed, 474 insertions(+), 174 deletions(-)
 create mode 100644 apps/desktop/src/components/chat/image-geometry.test.tsx
 create mode 100644 apps/desktop/src/hooks/use-media-image.ts
 create mode 100644 apps/desktop/src/lib/media-dimensions.test.ts

diff --git a/apps/desktop/src/components/assistant-ui/markdown-text.tsx b/apps/desktop/src/components/assistant-ui/markdown-text.tsx
index 73d8eb47db..c7c955d167 100644
--- a/apps/desktop/src/components/assistant-ui/markdown-text.tsx
+++ b/apps/desktop/src/components/assistant-ui/markdown-text.tsx
@@ -16,6 +16,7 @@ import { chunkByLines, SyntaxHighlighter } from '@/components/chat/shiki-highlig
 import { TranscriptVideo } from '@/components/chat/transcript-video'
 import { ZoomableImage } from '@/components/chat/zoomable-image'
 import { ErrorBoundary } from '@/components/error-boundary'
+import { useMediaImage } from '@/hooks/use-media-image'
 import { detectArtifact } from '@/lib/artifact-detect'
 import { renderMediaTags } from '@/lib/chat-messages/parts'
 import { normalizeExternalUrl, openExternalLink, PrettyLink } from '@/lib/external-link'
@@ -25,15 +26,14 @@ import { preprocessMarkdown } from '@/lib/markdown-preprocess'
 import {
   downloadGatewayMediaFile,
   isFileMediaPath,
-  isInlineMediaSrc,
   isMarkdownDocumentPath,
   isRemoteGateway,
   mediaExternalUrl,
   mediaKind,
   mediaName,
   mediaPathFromMarkdownHref,
-  resolveMediaDisplaySrc,
-  resolveMediaPlaybackSrc
+  resolveMediaPlaybackSrc,
+  validImageDimensions
 } from '@/lib/media'
 import { isOnboardingEnabled } from '@/lib/onboarding-enabled'
 import { previewTargetFromMarkdownHref } from '@/lib/preview-targets'
@@ -151,6 +151,14 @@ function OpenMediaButton({ kind, path }: { kind: 'audio' | 'video'; path: string
 }
 
 function MediaAttachment({ path }: { path: string }) {
+  return mediaKind(path) === 'image' ? (
+    <MarkdownImage alt={mediaName(path)} src={path} />
+  ) : (
+    <MediaPlaybackAttachment path={path} />
+  )
+}
+
+function MediaPlaybackAttachment({ path }: { path: string }) {
   const [src, setSrc] = useState('')
   const [failed, setFailed] = useState(false)
   const { open, openFailed } = useOpenMediaFile(path)
@@ -199,14 +207,6 @@ function MediaAttachment({ path }: { path: string }) {
     }
   }, [kind, path])
 
-  if (kind === 'image' && src) {
-    return (
-      <span className="block">
-        <MarkdownImage alt={name} src={src} />
-      </span>
-    )
-  }
-
   if (kind === 'audio' && src) {
     return (
       <span className="my-3 block max-w-md rounded-xl border border-(--ui-stroke-tertiary) bg-muted/35 p-3">
@@ -374,78 +374,60 @@ export function MarkdownImage(props: ComponentProps<'img'>) {
   return <MarkdownImageContent {...props} />
 }
 
-function MarkdownImageContent({ className, src, alt, ...props }: ComponentProps<'img'>) {
+function MarkdownImageContent({
+  className,
+  src,
+  alt,
+  width,
+  height,
+  onLoad,
+  onError,
+  style,
+  ...props
+}: ComponentProps<'img'>) {
   const rawSrc = typeof src === 'string' ? src : ''
-  const [resolvedSrc, setResolvedSrc] = useState(() => (rawSrc && isInlineMediaSrc(rawSrc) ? rawSrc : ''))
-  const [failed, setFailed] = useState(false)
+  const image = useMediaImage(rawSrc, 16 / 9, validImageDimensions(width, height))
   const { open, openFailed } = useOpenMediaFile(rawSrc)
   const name = mediaName(rawSrc || String(alt || 'image'))
 
-  useEffect(() => {
-    let cancelled = false
-
-    setFailed(false)
-    setResolvedSrc(rawSrc && isInlineMediaSrc(rawSrc) ? rawSrc : '')
-
-    if (!rawSrc || isInlineMediaSrc(rawSrc)) {
-      return () => {
-        cancelled = true
-      }
-    }
-
-    void resolveMediaDisplaySrc(rawSrc)
-      .then(value => {
-        if (!cancelled) {
-          setResolvedSrc(value)
-        }
-      })
-      .catch(() => {
-        if (!cancelled) {
-          setFailed(true)
-        }
-      })
-
-    return () => {
-      cancelled = true
-    }
-  }, [rawSrc])
-
   if (!rawSrc) {
     return null
   }
 
-  if (failed) {
-    return (
-      <span className="my-2 block text-sm text-muted-foreground">
-        Couldn&apos;t load {name}.{' '}
-        <button className="ref font-medium text-foreground" onClick={open} type="button">
-          Open image
-        </button>
-        {openFailed && <OpenMediaFailedNote name={name} />}
-      </span>
-    )
-  }
-
-  if (!resolvedSrc) {
-    return <span className="my-2 block text-sm text-muted-foreground">Loading {name}...</span>
-  }
-
-  // The width cap belongs on the container, not the <img>: a percentage
-  // max-width resolves to none while the container measures its fit-content
-  // width, so the box overshoots the rendered image and strands the download
-  // button — which anchors to the container — out in the margin.
   return (
-    <ZoomableImage
-      alt={alt}
-      className={cn(
-        'm-0 block h-auto w-auto max-h-(--image-preview-height) max-w-full rounded-lg object-contain shadow-[0_0.0625rem_0.125rem_color-mix(in_srgb,#000_4%,transparent),0_0.625rem_1.5rem_color-mix(in_srgb,#000_5%,transparent)]',
-        className
+    <span className="relative my-2 block max-w-full" data-slot="aui_markdown-image" style={image.frameStyle}>
+      {image.failed ? (
+        <span className="absolute inset-0 block overflow-auto text-sm text-muted-foreground">
+          Couldn&apos;t load {name}.{' '}
+          <button className="ref font-medium text-foreground" onClick={open} type="button">
+            Open image
+          </button>
+          {openFailed && <OpenMediaFailedNote name={name} />}
+        </span>
+      ) : image.src ? (
+        <ZoomableImage
+          {...props}
+          alt={alt}
+          className={cn(
+            'm-0 block size-full rounded-lg object-contain shadow-[0_0.0625rem_0.125rem_color-mix(in_srgb,#000_4%,transparent),0_0.625rem_1.5rem_color-mix(in_srgb,#000_5%,transparent)]',
+            className
+          )}
+          containerClassName="absolute inset-0 block size-full"
+          onError={event => {
+            image.onError()
+            onError?.(event)
+          }}
+          onLoad={event => {
+            image.onLoad(event.currentTarget)
+            onLoad?.(event)
+          }}
+          src={image.src}
+          style={style}
+        />
+      ) : (
+        <span className="absolute inset-0 block overflow-hidden text-sm text-muted-foreground">Loading {name}...</span>
       )}
-      containerClassName="my-2 block w-fit max-w-[min(100%,var(--image-preview-max-width))]"
-      slot="aui_markdown-image"
-      src={resolvedSrc}
-      {...props}
-    />
+    </span>
   )
 }
 
diff --git a/apps/desktop/src/components/chat/generated-image-result.tsx b/apps/desktop/src/components/chat/generated-image-result.tsx
index 89d35e5470..f03ac7878d 100644
--- a/apps/desktop/src/components/chat/generated-image-result.tsx
+++ b/apps/desktop/src/components/chat/generated-image-result.tsx
@@ -1,17 +1,17 @@
 'use client'
 
-import { type FC, useEffect, useState } from 'react'
+import { type FC, useState } from 'react'
 
 import { DiffusionCanvas } from '@/components/chat/image-generation-placeholder'
 import { ImageActionButton, ImageLightbox } from '@/components/chat/zoomable-image'
 import { useImageDownload } from '@/hooks/use-image-download'
+import { useMediaImage } from '@/hooks/use-media-image'
 import { useI18n } from '@/i18n'
-import { generatedImageFromResult } from '@/lib/generated-images'
-import { filePathFromMediaPath, gatewayMediaDataUrl, isRemoteGateway, mediaExternalUrl, mediaName } from '@/lib/media'
+import { generatedImageDimensionsFromResult, generatedImageFromResult } from '@/lib/generated-images'
+import { mediaExternalUrl, mediaName } from '@/lib/media'
 import { cn } from '@/lib/utils'
 
-// Aspect hint from the tool args sizes the frame *before* the image loads, so
-// the placeholder and the resolved image occupy the same box — no layout shift.
+// A hint is only a placeholder shape, not a promise about the delivered image.
 const ASPECT_HINTS: Record<string, number> = {
   landscape: 16 / 9,
   square: 1,
@@ -28,115 +28,60 @@ function hintedRatio(aspectRatio?: string): number {
   )
 }
 
-function isInlineSrc(path: string): boolean {
-  return /^(?:https?|data):/i.test(path)
-}
-
-async function resolveImageSrc(path: string): Promise<string> {
-  if (isInlineSrc(path)) {
-    return path
-  }
-
-  if (window.hermesDesktop && isRemoteGateway()) {
-    return gatewayMediaDataUrl(path)
-  }
-
-  if (!window.hermesDesktop?.readFileDataUrl) {
-    return mediaExternalUrl(path)
-  }
-
-  return window.hermesDesktop.readFileDataUrl(filePathFromMediaPath(path))
-}
-
 export const GeneratedImage: FC<{ aspectRatio?: string; result?: unknown }> = ({ aspectRatio, result }) => {
   const { t } = useI18n()
   const copy = t.desktop
   const image = result === undefined ? null : generatedImageFromResult(result)
   const pending = result === undefined
 
-  const [ratio, setRatio] = useState(() => hintedRatio(aspectRatio))
-  const [src, setSrc] = useState(() => (image && isInlineSrc(image) ? image : ''))
-  const [loaded, setLoaded] = useState(false)
-  const [canvasGone, setCanvasGone] = useState(false)
-  const [failed, setFailed] = useState(false)
-  const [lightboxOpen, setLightboxOpen] = useState(false)
+  const media = useMediaImage(image ?? '', hintedRatio(aspectRatio), generatedImageDimensionsFromResult(result))
+  const { src, loaded, failed } = media
+  const [canvasGone, setCanvasGone] = useState<string | null>(null)
+  const [lightboxOpen, setLightboxOpen] = useState<string | null>(null)
   const { download, saving } = useImageDownload(src)
 
-  useEffect(() => setRatio(hintedRatio(aspectRatio)), [aspectRatio])
-
-  // Resolve the deliverable path (local read / gateway proxy / remote URL). The
-  // <img> stays mounted under the placeholder and only fades in once it decodes,
-  // so the frame keeps its hinted size and never jumps.
-  useEffect(() => {
-    let cancelled = false
-    setFailed(false)
-    setLoaded(false)
-    setCanvasGone(false)
-    setSrc(image && isInlineSrc(image) ? image : '')
-
-    if (!image || isInlineSrc(image)) {
-      return
-    }
-
-    void resolveImageSrc(image)
-      .then(resolved => !cancelled && setSrc(resolved))
-      .catch(() => !cancelled && setFailed(true))
-
-    return () => {
-      cancelled = true
-    }
-  }, [image])
-
   // Completed but no usable image (generation failed): the agent's prose carries
   // the explanation, so render nothing here.
   if (!pending && !image) {
     return null
   }
 
-  if (failed && image) {
-    return (
-      <a
-        className="mt-2 ref inline-block wrap-anywhere"
-        href="#"
-        onClick={event => {
-          event.preventDefault()
-          void window.hermesDesktop?.openExternal(mediaExternalUrl(image))
-        }}
-      >
-        {copy.openImage}: {mediaName(image)}
-      </a>
-    )
-  }
-
   return (
     <>
       <span
         aria-label={pending ? t.assistant.tool.renderingImage : undefined}
         aria-live={pending ? 'polite' : undefined}
-        className="group/image relative block max-w-full overflow-hidden rounded-2xl transition-[width,height] duration-300 ease-out"
+        className="group/image relative block max-w-full overflow-hidden rounded-2xl"
         data-slot="aui_generated-image"
         role={pending ? 'status' : undefined}
-        style={{
-          aspectRatio: ratio,
-          // Width is capped so the derived height (width / ratio) never exceeds
-          // --image-preview-height; the box then matches the image exactly with
-          // no letterboxing.
-          width: `min(calc(var(--image-preview-height) * ${ratio}), var(--image-preview-max-width), 100%)`
-        }}
+        style={media.frameStyle}
       >
-        {!canvasGone && (
-          <div
-            className={cn('absolute inset-0 transition-opacity duration-500 ease-out', loaded && 'opacity-0')}
-            onTransitionEnd={() => loaded && setCanvasGone(true)}
+        {failed && image ? (
+          <a
+            className="absolute inset-0 ref block overflow-auto wrap-anywhere"
+            href="#"
+            onClick={event => {
+              event.preventDefault()
+              void window.hermesDesktop?.openExternal(mediaExternalUrl(image))
+            }}
           >
-            <DiffusionCanvas />
-          </div>
+            {copy.openImage}: {mediaName(image)}
+          </a>
+        ) : (
+          canvasGone !== media.key && (
+            <div
+              className={cn('absolute inset-0 transition-opacity duration-500 ease-out', loaded && 'opacity-0')}
+              onTransitionEnd={() => loaded && setCanvasGone(media.key)}
+            >
+              <DiffusionCanvas />
+            </div>
+          )
         )}
-        {src && (
+        {src && !failed && (
           <button
             aria-label={copy.openImage}
             className="absolute inset-0 block size-full cursor-zoom-in"
-            onClick={() => setLightboxOpen(true)}
+            onClick={() => setLightboxOpen(media.key)}
             type="button"
           >
             <img
@@ -146,16 +91,8 @@ export const GeneratedImage: FC<{ aspectRatio?: string; result?: unknown }> = ({
                 loaded && 'opacity-100'
               )}
               draggable={false}
-              onError={() => setFailed(true)}
-              onLoad={event => {
-                const { naturalHeight, naturalWidth } = event.currentTarget
-
-                if (naturalWidth && naturalHeight) {
-                  setRatio(naturalWidth / naturalHeight)
-                }
-
-                setLoaded(true)
-              }}
+              onError={media.onError}
+              onLoad={event => media.onLoad(event.currentTarget)}
               src={src}
             />
           </button>
@@ -169,8 +106,8 @@ export const GeneratedImage: FC<{ aspectRatio?: string; result?: unknown }> = ({
           alt="Generated image"
           copy={copy}
           onClick={download}
-          onOpenChange={setLightboxOpen}
-          open={lightboxOpen}
+          onOpenChange={open => setLightboxOpen(open ? media.key : null)}
+          open={lightboxOpen === media.key}
           saving={saving}
           src={src}
         />
diff --git a/apps/desktop/src/components/chat/image-geometry.test.tsx b/apps/desktop/src/components/chat/image-geometry.test.tsx
new file mode 100644
index 0000000000..d2dfdc6aad
--- /dev/null
+++ b/apps/desktop/src/components/chat/image-geometry.test.tsx
@@ -0,0 +1,142 @@
+import { act, cleanup, fireEvent, render } from '@testing-library/react'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+
+import { ComposerScopeProvider, MAIN_COMPOSER_SCOPE } from '@/app/chat/composer/scope'
+import { MarkdownImage, MessageTextContent } from '@/components/assistant-ui/markdown-text'
+import { $connection } from '@/store/session'
+
+import { GeneratedImage } from './generated-image-result'
+
+vi.mock('./image-generation-placeholder', () => ({ DiffusionCanvas: () => null }))
+
+const paths = { first: '/geometry/first.svg', second: '/geometry/second.svg' }
+const data = 'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="800" height="800"/>'
+let reads: Array<{ resolve: (value: string) => void; reject: (error: Error) => void }>
+const read = vi.fn(() => new Promise<string>((resolve, reject) => reads.push({ resolve, reject })))
+
+beforeEach(() => {
+  reads = []
+  read.mockClear()
+  vi.stubGlobal('hermesDesktop', { readFileDataUrl: read, api: vi.fn(() => read().then(dataUrl => ({ dataUrl }))) })
+  $connection.set({ connectionId: 'geometry-local', mode: 'local', profile: 'a' } as never)
+})
+afterEach(() => {
+  cleanup()
+  $connection.set(null)
+  vi.unstubAllGlobals()
+})
+
+const cases = [
+  { kind: 'markdown', hint: undefined },
+  { kind: 'media', hint: undefined },
+  ...[undefined, 'landscape', 'square'].map(hint => ({ kind: 'generated', hint })),
+  { kind: 'markdown', hint: 'intrinsic' },
+  { kind: 'generated', hint: 'intrinsic' }
+]
+
+function content(kind: string, path: string, hint?: string) {
+  if (kind === 'generated') {
+    return (
+      <GeneratedImage
+        aspectRatio={hint}
+        result={{ success: true, image: path, pixel_size: hint === 'intrinsic' ? '800x800' : undefined }}
+      />
+    )
+  }
+
+  if (kind === 'media') {
+    return <MessageTextContent text={`MEDIA:${path}`} />
+  }
+
+  return (
+    <MarkdownImage
+      alt="geometry"
+      height={hint === 'intrinsic' ? 800 : undefined}
+      src={path}
+      width={hint === 'intrinsic' ? 800 : undefined}
+    />
+  )
+}
+
+function frame(container: HTMLElement) {
+  return container.querySelector<HTMLElement>('[data-slot="aui_generated-image"], [data-slot="aui_markdown-image"]')!
+}
+
+async function decode(container: HTMLElement, width = 800, height = 800) {
+  await act(async () => reads.shift()!.resolve(data))
+  const img = container.querySelector('img')!
+  Object.defineProperties(img, { naturalWidth: { value: width }, naturalHeight: { value: height } })
+  fireEvent.load(img)
+}
+
+it.each(cases)('reserves $kind frames through cold decode, warm return and failure ($hint)', async ({ kind, hint }) => {
+  // Unique paths keep parameter rows independent without a production cache-reset API.
+  const path = `${paths.first}?${kind}-${hint}`
+  const first = render(content(kind, path, hint))
+  const cold = frame(first.container)
+  expect(cold).not.toBeNull()
+  const coldSize = cold.style.cssText
+
+  if (hint === 'intrinsic') {
+    expect(parseFloat(cold.style.aspectRatio)).toBe(1)
+  }
+
+  await decode(first.container)
+  expect(frame(first.container).style.cssText).toBe(coldSize)
+  first.unmount()
+
+  const warm = render(content(kind, path, hint))
+  const reserved = frame(warm.container)
+  expect(parseFloat(reserved.style.aspectRatio)).toBe(1)
+  const warmSize = reserved.style.cssText
+  await decode(warm.container)
+  expect(frame(warm.container).style.cssText).toBe(warmSize)
+  fireEvent.error(warm.container.querySelector('img')!)
+  expect(frame(warm.container).style.cssText).toBe(warmSize)
+  expect(warm.container.textContent).toMatch(/Open image/i)
+})
+
+it.each(['markdown', 'generated'])('%s dimensions follow owner and source, not stale reads or hints', async kind => {
+  const path = `${paths.second}?${kind}`
+
+  const view = (connectionId: string, profile: string, src = path) => (
+    <ComposerScopeProvider value={{ ...MAIN_COMPOSER_SCOPE, connectionId, profile }}>
+      {content(kind, src, 'portrait')}
+    </ComposerScopeProvider>
+  )
+
+  const first = render(view('owner-a', 'a'))
+  await decode(first.container, 900, 600)
+  first.unmount()
+
+  const mounted = render(view('owner-b', 'a'))
+  expect(parseFloat(frame(mounted.container).style.aspectRatio)).not.toBe(1.5)
+  mounted.rerender(view('owner-a', 'b'))
+  expect(parseFloat(frame(mounted.container).style.aspectRatio)).not.toBe(1.5)
+  mounted.rerender(view('owner-a', 'a'))
+  expect(parseFloat(frame(mounted.container).style.aspectRatio)).toBe(1.5)
+  const reserved = frame(mounted.container).style.cssText
+  // Settle the two superseded owners after A has become visible again.
+  await act(async () => {
+    reads.shift()!.resolve(data)
+    reads.shift()!.reject(new Error('retired'))
+  })
+  expect(frame(mounted.container).style.cssText).toBe(reserved)
+  expect(mounted.container.querySelector('img')).toBeNull()
+  // Same path, changed bytes: update the next mount's intrinsic dimensions,
+  // but never reshape the frame currently being read.
+  await decode(mounted.container, 600, 900)
+  expect(frame(mounted.container).style.cssText).toBe(reserved)
+  mounted.rerender(view('owner-a', 'a', `${path}-revision`))
+  expect(parseFloat(frame(mounted.container).style.aspectRatio)).not.toBe(1.5)
+  expect(mounted.container.querySelector('img')).toBeNull()
+  await act(async () => reads.shift()!.reject(new Error('missing')))
+  expect(mounted.container.textContent).toMatch(/Open image/i)
+  mounted.rerender(view('owner-a', 'a'))
+  expect(parseFloat(frame(mounted.container).style.aspectRatio)).toBeCloseTo(600 / 900)
+  expect(window.hermesDesktop.api).toHaveBeenLastCalledWith({
+    connectionId: 'owner-a',
+    profile: 'a',
+    path: `/api/fs/read-data-url?path=${encodeURIComponent(path)}`
+  })
+})
diff --git a/apps/desktop/src/hooks/use-media-image.ts b/apps/desktop/src/hooks/use-media-image.ts
new file mode 100644
index 0000000000..feefe79af9
--- /dev/null
+++ b/apps/desktop/src/hooks/use-media-image.ts
@@ -0,0 +1,95 @@
+import { useStore } from '@nanostores/react'
+import { type CSSProperties, useEffect, useMemo, useState } from 'react'
+
+import { useComposerScope } from '@/app/chat/composer/scope'
+import {
+  forgetMediaImageDimensions,
+  getMediaImageDimensions,
+  isInlineMediaSrc,
+  type MediaImageDimensions,
+  mediaImageKey,
+  rememberMediaImageDimensions,
+  resolveMediaDisplaySrc
+} from '@/lib/media'
+import { $connection } from '@/store/session'
+
+/** Keep a frame for one source/owner for its mounted lifetime. Hints are not
+ * intrinsic dimensions: a cold image is contained in that frame, not allowed
+ * to resize it at decode. The next mount can use the measured dimensions. */
+export function useMediaImage(path: string, fallbackRatio: number, intrinsic?: MediaImageDimensions) {
+  const connection = useStore($connection)
+  const scope = useComposerScope()
+  const connectionId = scope.connectionId || connection?.connectionId
+  const profile = scope.profile ?? connection?.profile
+
+  const owner = useMemo(
+    () => (scope.connectionId || scope.profile ? { connectionId, profile } : undefined),
+    [scope.connectionId, scope.profile, connectionId, profile]
+  )
+
+  const key = mediaImageKey(path, connection, owner)
+
+  const initialState = () => {
+    const dimensions = intrinsic ?? getMediaImageDimensions(key)
+    const ratio = dimensions ? dimensions.width / dimensions.height : fallbackRatio
+
+    return {
+      key,
+      frameStyle: {
+        aspectRatio: ratio,
+        width: `min(calc(var(--image-preview-height) * ${ratio}), var(--image-preview-max-width), 100%${dimensions ? `, ${dimensions.width}px` : ''})`
+      } satisfies CSSProperties,
+      src: path && isInlineMediaSrc(path) ? path : '',
+      loaded: false,
+      failed: false
+    }
+  }
+
+  const [state, setState] = useState(initialState)
+
+  // Source changes must not paint the previous image/geometry even for one
+  // commit. React retries this component before committing its children.
+  if (state.key !== key) {
+    setState(initialState())
+  }
+
+  useEffect(() => {
+    let cancelled = false
+
+    if (path && !isInlineMediaSrc(path)) {
+      void resolveMediaDisplaySrc(path, owner).then(
+        src => {
+          if (!cancelled) {
+            if (!src) {
+              forgetMediaImageDimensions(key)
+            }
+
+            setState(current => ({ ...current, src, failed: !src }))
+          }
+        },
+        () => {
+          if (!cancelled) {
+            forgetMediaImageDimensions(key)
+            setState(current => ({ ...current, failed: true }))
+          }
+        }
+      )
+    }
+
+    return () => {
+      cancelled = true
+    }
+  }, [key, path, owner])
+
+  return {
+    ...state,
+    onLoad: (image: HTMLImageElement) => {
+      rememberMediaImageDimensions(key, image.naturalWidth, image.naturalHeight)
+      setState(current => ({ ...current, loaded: true }))
+    },
+    onError: () => {
+      forgetMediaImageDimensions(key)
+      setState(current => ({ ...current, failed: true, loaded: false }))
+    }
+  }
+}
diff --git a/apps/desktop/src/lib/generated-images.test.ts b/apps/desktop/src/lib/generated-images.test.ts
index 7fb3210510..7eb1e85cbf 100644
--- a/apps/desktop/src/lib/generated-images.test.ts
+++ b/apps/desktop/src/lib/generated-images.test.ts
@@ -2,12 +2,30 @@ import { describe, expect, it } from 'vitest'
 
 import {
   dedupeGeneratedImageEchoesInParts,
+  generatedImageDimensionsFromResult,
   generatedImageEchoSources,
   generatedImageFromResult,
   stripGeneratedImageEchoes
 } from './generated-images'
 
 describe('generatedImageFromResult', () => {
+  it('uses decoded pixel_size, never requested sizing, for intrinsic geometry', () => {
+    const dimensions = { width: 900, height: 600 }
+
+    const result = {
+      success: true,
+      image: '/image.png',
+      pixel_size: `${dimensions.width}x${dimensions.height}`,
+      size: '1024x1024'
+    }
+
+    expect(generatedImageDimensionsFromResult(JSON.stringify(result))).toEqual(dimensions)
+
+    for (const pixel_size of [undefined, 'auto', '0x600', '9'.repeat(400) + 'x600']) {
+      expect(generatedImageDimensionsFromResult({ ...result, pixel_size })).toBeUndefined()
+    }
+  })
+
   it('prefers the host-visible image path', () => {
     expect(
       generatedImageFromResult({
diff --git a/apps/desktop/src/lib/generated-images.ts b/apps/desktop/src/lib/generated-images.ts
index 4ee990bd6d..233e44ce83 100644
--- a/apps/desktop/src/lib/generated-images.ts
+++ b/apps/desktop/src/lib/generated-images.ts
@@ -1,3 +1,5 @@
+import type { MediaImageDimensions } from '@/lib/media'
+
 type ToolLike = {
   result?: unknown
   toolName?: unknown
@@ -66,6 +68,21 @@ export function generatedImageFromResult(result: unknown): string | null {
   return stringFields(record, DISPLAY_KEYS)[0] ?? null
 }
 
+/** Codex reports decoded PNG geometry separately from its requested `size`.
+ * Never use requested_size/size or aspect_ratio as intrinsic metadata. */
+export function generatedImageDimensionsFromResult(result: unknown): MediaImageDimensions | undefined {
+  const record = recordFromUnknown(result)
+  const match = typeof record?.pixel_size === 'string' ? /^(\d+)x(\d+)$/.exec(record.pixel_size) : null
+
+  return match &&
+    Number.isSafeInteger(Number(match[1])) &&
+    Number.isSafeInteger(Number(match[2])) &&
+    Number(match[1]) > 0 &&
+    Number(match[2]) > 0
+    ? { width: Number(match[1]), height: Number(match[2]) }
+    : undefined
+}
+
 /** Every path/URL a generated image might appear as in prose, for de-duping. */
 export function generatedImageEchoSources(parts: readonly ToolLike[]): string[] {
   // Runs on every streamed tool event over the whole timeline; skip the
diff --git a/apps/desktop/src/lib/media-dimensions.test.ts b/apps/desktop/src/lib/media-dimensions.test.ts
new file mode 100644
index 0000000000..bc0c4c9a99
--- /dev/null
+++ b/apps/desktop/src/lib/media-dimensions.test.ts
@@ -0,0 +1,45 @@
+import { expect, it } from 'vitest'
+
+import type { HermesConnection } from '@/global'
+
+import {
+  forgetMediaImageDimensions,
+  getMediaImageDimensions,
+  mediaImageKey,
+  rememberMediaImageDimensions,
+  validImageDimensions
+} from './media'
+
+it('shares proven path aliases only within an owner and bounds regenerated metadata by LRU', () => {
+  const a = { connectionId: 'a', profile: 'work', mode: 'remote' } as HermesConnection
+  const b = { ...a, connectionId: 'b' }
+  const key = mediaImageKey('/images/a b.png', a)
+  const dimensions = { width: 900, height: 600 }
+
+  rememberMediaImageDimensions(key, dimensions.width, dimensions.height)
+  expect(getMediaImageDimensions(mediaImageKey('file:///images/a%20b.png', a))).toEqual(dimensions)
+  expect(getMediaImageDimensions(mediaImageKey('/images/a b.png', b))).toBeUndefined()
+  expect(getMediaImageDimensions(mediaImageKey('/images/a b.png', { ...a, profile: 'personal' }))).toBeUndefined()
+  expect(getMediaImageDimensions(mediaImageKey('/images/a b.png?revision=2', a))).toBeUndefined()
+  expect(getMediaImageDimensions(mediaImageKey('file:///images/a%20b.png?revision=2', a))).toBeUndefined()
+  expect(getMediaImageDimensions(mediaImageKey('/images/a b.png', b, a))).toEqual(dimensions)
+
+  // Discover the finite capacity behaviorally, not by pinning its current value.
+  const cold = mediaImageKey('/images/old.png', a)
+  rememberMediaImageDimensions(cold, 100, 100)
+
+  for (let i = 0; i < 10000; i++) {
+    rememberMediaImageDimensions(`bounded-${i}`, 100, 100)
+    expect(getMediaImageDimensions(key)).toEqual(dimensions)
+  }
+
+  expect(getMediaImageDimensions(cold)).toBeUndefined()
+  expect(validImageDimensions(0, 100)).toBeUndefined()
+  expect(validImageDimensions(Infinity, 100)).toBeUndefined()
+  rememberMediaImageDimensions(key, 0, 100)
+  expect(getMediaImageDimensions(key)).toEqual(dimensions)
+  rememberMediaImageDimensions('x'.repeat(100000), 100, 100)
+  expect(getMediaImageDimensions('x'.repeat(100000))).toBeUndefined()
+  forgetMediaImageDimensions(key)
+  expect(getMediaImageDimensions(key)).toBeUndefined()
+})
diff --git a/apps/desktop/src/lib/media.ts b/apps/desktop/src/lib/media.ts
index 7847bc0e28..830603e53a 100644
--- a/apps/desktop/src/lib/media.ts
+++ b/apps/desktop/src/lib/media.ts
@@ -1,4 +1,7 @@
-import { readDesktopFileDataUrl } from '@/lib/desktop-fs'
+import { hermesApi, type OwnerScope } from '@/api/client'
+import type { HermesConnection } from '@/global'
+import { desktopFsCacheKey, readDesktopFileDataUrl } from '@/lib/desktop-fs'
+import { LruCache } from '@/lib/lru-cache'
 import { capitalize } from '@/lib/text'
 import { $connection } from '@/store/session'
 
@@ -84,11 +87,23 @@ export function isFileMediaPath(path: string): boolean {
   return /^(?:file:|\/|~\/|[a-z]:[\\/]|\\\\)/i.test(path)
 }
 
-export async function resolveMediaDisplaySrc(path: string): Promise<string> {
+export async function resolveMediaDisplaySrc(path: string, owner?: OwnerScope): Promise<string> {
   if (isInlineMediaSrc(path) || !isFileMediaPath(path)) {
     return path
   }
 
+  // A tile can belong to a different gateway than the foreground. Pin both
+  // halves at read admission rather than resolving them when the read settles.
+  if (window.hermesDesktop && (owner?.connectionId || owner?.profile)) {
+    const result = await hermesApi<string | { dataUrl?: string }>({
+      path: `/api/fs/read-data-url?path=${encodeURIComponent(filePathFromMediaPath(path))}`,
+      ...(owner.connectionId ? { connectionId: owner.connectionId } : {}),
+      ...(owner.profile ? { profile: owner.profile } : {})
+    })
+
+    return typeof result === 'string' ? result : result.dataUrl || ''
+  }
+
   if (window.hermesDesktop && isRemoteGateway()) {
     return gatewayMediaDataUrl(path)
   }
@@ -100,6 +115,55 @@ export async function resolveMediaDisplaySrc(path: string): Promise<string> {
   return window.hermesDesktop.readFileDataUrl(filePathFromMediaPath(path))
 }
 
+export interface MediaImageDimensions {
+  width: number
+  height: number
+}
+
+// Decoded geometry only: never retain image bytes/data URLs for every visited
+// transcript. A miss costs a letterboxed first display, not a collapsed row.
+const imageDimensions = new LruCache<string, MediaImageDimensions>(512)
+
+export function mediaImageKey(path: string, connection: HermesConnection | null, owner?: OwnerScope): string {
+  // File reads ignore URL query/fragment, but callers can use them to identify
+  // a new revision. Keep them in the geometry key while joining proven aliases.
+  const revision = /^file:/i.test(path) ? (path.match(/[?#].*$/)?.[0] ?? '') : ''
+
+  return JSON.stringify([
+    owner?.connectionId ||
+      connection?.connectionId ||
+      desktopFsCacheKey(connection && { ...connection, profile: owner?.profile ?? connection.profile }),
+    owner?.profile ?? connection?.profile ?? '',
+    filePathFromMediaPath(path),
+    revision
+  ])
+}
+
+export function validImageDimensions(width: unknown, height: unknown): MediaImageDimensions | undefined {
+  const w = Number(width)
+  const h = Number(height)
+
+  return Number.isFinite(w) && w > 0 && Number.isFinite(h) && h > 0 ? { width: w, height: h } : undefined
+}
+
+export function getMediaImageDimensions(key: string): MediaImageDimensions | undefined {
+  return imageDimensions.get(key)
+}
+
+export function rememberMediaImageDimensions(key: string, width: number, height: number): void {
+  const dimensions = validImageDimensions(width, height)
+
+  // Embedded images can have multi-megabyte source keys. Their bytes stay with
+  // the message; do not turn this small metadata cache into a second copy.
+  if (dimensions && key.length <= 4096) {
+    imageDimensions.set(key, dimensions)
+  }
+}
+
+export function forgetMediaImageDimensions(key: string): void {
+  imageDimensions.delete(key)
+}
+
 // Audio/video need a seekable source instead of a whole-file data URL. Keep
 // remote URLs untouched and route filesystem paths through the Electron media
 // protocol. Its main-process handler reads local files directly or proxies a

From 39cca5f9aee1486c90be8486e3e4ebeb118bbd86 Mon Sep 17 00:00:00 2001
From: BearHuddleston <bear@bearhuddleston.dev>
Date: Tue, 22 Sep 2026 17:56:32 -0500
Subject: [PATCH 37/61] fix(desktop): keep the pending generated-image frame
 when its result arrives
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

GeneratedImage stays mounted across pending→result, so the source-key reset replaced the visible placeholder frame before the file read or decode. Callers can now opt in to inheriting the frame for a same-owner empty→first-source transition; Markdown images, owner changes, and real source replacements still select their own geometry.

Co-authored-by: Xipong <Xipong@users.noreply.github.com>
---
 .../chat/generated-image-result.tsx           |   5 +-
 .../chat/image-geometry-lifecycle.test.tsx    | 106 ++++++++++++++++++
 apps/desktop/src/hooks/use-media-image.ts     |  18 ++-
 3 files changed, 126 insertions(+), 3 deletions(-)
 create mode 100644 apps/desktop/src/components/chat/image-geometry-lifecycle.test.tsx

diff --git a/apps/desktop/src/components/chat/generated-image-result.tsx b/apps/desktop/src/components/chat/generated-image-result.tsx
index f03ac7878d..7b27c969aa 100644
--- a/apps/desktop/src/components/chat/generated-image-result.tsx
+++ b/apps/desktop/src/components/chat/generated-image-result.tsx
@@ -34,7 +34,10 @@ export const GeneratedImage: FC<{ aspectRatio?: string; result?: unknown }> = ({
   const image = result === undefined ? null : generatedImageFromResult(result)
   const pending = result === undefined
 
-  const media = useMediaImage(image ?? '', hintedRatio(aspectRatio), generatedImageDimensionsFromResult(result))
+  const media = useMediaImage(image ?? '', hintedRatio(aspectRatio), generatedImageDimensionsFromResult(result), {
+    preservePendingFrame: true
+  })
+
   const { src, loaded, failed } = media
   const [canvasGone, setCanvasGone] = useState<string | null>(null)
   const [lightboxOpen, setLightboxOpen] = useState<string | null>(null)
diff --git a/apps/desktop/src/components/chat/image-geometry-lifecycle.test.tsx b/apps/desktop/src/components/chat/image-geometry-lifecycle.test.tsx
new file mode 100644
index 0000000000..a93ef18626
--- /dev/null
+++ b/apps/desktop/src/components/chat/image-geometry-lifecycle.test.tsx
@@ -0,0 +1,106 @@
+import { act, cleanup, fireEvent, render, renderHook } from '@testing-library/react'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+
+import { ComposerScopeProvider, MAIN_COMPOSER_SCOPE } from '@/app/chat/composer/scope'
+import { useMediaImage } from '@/hooks/use-media-image'
+import { mediaImageKey, rememberMediaImageDimensions } from '@/lib/media'
+import { $connection } from '@/store/session'
+
+import { GeneratedImage } from './generated-image-result'
+
+vi.mock('./image-generation-placeholder', () => ({ DiffusionCanvas: () => null }))
+
+const data = 'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="900" height="600"/>'
+let reads: Array<(value: string) => void>
+const read = vi.fn(() => new Promise<string>(resolve => reads.push(resolve)))
+
+beforeEach(() => {
+  reads = []
+  read.mockClear()
+  vi.stubGlobal('hermesDesktop', { readFileDataUrl: read, api: vi.fn(() => read().then(dataUrl => ({ dataUrl }))) })
+  $connection.set({ connectionId: 'lifecycle-local', mode: 'local', profile: 'a' } as never)
+})
+
+afterEach(() => {
+  cleanup()
+  $connection.set(null)
+  vi.unstubAllGlobals()
+})
+
+function frame(container: HTMLElement) {
+  return container.querySelector<HTMLElement>('[data-slot="aui_generated-image"]')!
+}
+
+async function decode(container: HTMLElement, width: number, height: number) {
+  await act(async () => reads.shift()!(data))
+  const img = container.querySelector('img')!
+  Object.defineProperties(img, { naturalWidth: { value: width }, naturalHeight: { value: height } })
+  fireEvent.load(img)
+}
+
+it.each([
+  { name: 'result metadata', width: 900, height: 600, cached: false },
+  { name: 'warm cache', width: 800, height: 800, cached: true },
+  { name: 'same aspect but smaller intrinsic width', width: 160, height: 90, cached: false }
+])('keeps the pending frame when the result arrives with $name', async ({ name, width, height, cached }) => {
+  const path = `/lifecycle/${name}.svg`
+  const result = { success: true, image: path, pixel_size: cached ? undefined : `${width}x${height}` }
+
+  if (cached) {
+    rememberMediaImageDimensions(mediaImageKey(path, $connection.get()), width, height)
+  }
+
+  const mounted = render(<GeneratedImage aspectRatio="landscape" />)
+  const pendingStyle = frame(mounted.container).style.cssText
+  mounted.rerender(<GeneratedImage aspectRatio="landscape" result={result} />)
+
+  // This must hold before the file read settles, not just after img.onload.
+  expect(frame(mounted.container).style.cssText).toBe(pendingStyle)
+  expect(mounted.container.querySelector('img')).toBeNull()
+  await decode(mounted.container, width, height)
+  expect(frame(mounted.container).style.cssText).toBe(pendingStyle)
+  mounted.unmount()
+
+  // A fresh mount of the completed result still benefits from intrinsic size.
+  const warm = render(<GeneratedImage aspectRatio="landscape" result={result} />)
+  expect(parseFloat(frame(warm.container).style.aspectRatio)).toBeCloseTo(width / height)
+  const warmStyle = frame(warm.container).style.cssText
+  await decode(warm.container, width, height)
+  fireEvent.error(warm.container.querySelector('img')!)
+  expect(frame(warm.container).style.cssText).toBe(warmStyle)
+})
+
+it.each([
+  { connectionId: 'owner-b', profile: 'a' },
+  { connectionId: 'owner-a', profile: 'b' }
+])('does not inherit a pending frame across owner $connectionId/$profile', owner => {
+  const view = (connectionId: string, profile: string, result?: unknown) => (
+    <ComposerScopeProvider value={{ ...MAIN_COMPOSER_SCOPE, connectionId, profile }}>
+      <GeneratedImage aspectRatio="landscape" result={result} />
+    </ComposerScopeProvider>
+  )
+
+  const mounted = render(view('owner-a', 'a'))
+  mounted.rerender(view(owner.connectionId, owner.profile, { image: '/lifecycle/other.svg', pixel_size: '600x900' }))
+  expect(parseFloat(frame(mounted.container).style.aspectRatio)).toBeCloseTo(600 / 900)
+})
+
+it('still resets the frame between two actual image sources', () => {
+  const mounted = render(<GeneratedImage result={{ image: '/lifecycle/first.svg', pixel_size: '900x600' }} />)
+  mounted.rerender(<GeneratedImage result={{ image: '/lifecycle/second.svg', pixel_size: '600x900' }} />)
+  expect(parseFloat(frame(mounted.container).style.aspectRatio)).toBeCloseTo(600 / 900)
+})
+
+it('does not reserve an empty markdown image unless the caller opts in', () => {
+  const mounted = renderHook(
+    ({ path }) => useMediaImage(path, 16 / 9, path ? { width: 600, height: 900 } : undefined),
+    {
+      initialProps: { path: '' }
+    }
+  )
+
+  expect(mounted.result.current.frameStyle.aspectRatio).toBeCloseTo(16 / 9)
+  // Markdown callers keep the default source-based lifetime.
+  mounted.rerender({ path: '/lifecycle/markdown.svg' })
+  expect(mounted.result.current.frameStyle.aspectRatio).toBeCloseTo(600 / 900)
+})
diff --git a/apps/desktop/src/hooks/use-media-image.ts b/apps/desktop/src/hooks/use-media-image.ts
index feefe79af9..e51f9366ca 100644
--- a/apps/desktop/src/hooks/use-media-image.ts
+++ b/apps/desktop/src/hooks/use-media-image.ts
@@ -16,7 +16,12 @@ import { $connection } from '@/store/session'
 /** Keep a frame for one source/owner for its mounted lifetime. Hints are not
  * intrinsic dimensions: a cold image is contained in that frame, not allowed
  * to resize it at decode. The next mount can use the measured dimensions. */
-export function useMediaImage(path: string, fallbackRatio: number, intrinsic?: MediaImageDimensions) {
+export function useMediaImage(
+  path: string,
+  fallbackRatio: number,
+  intrinsic?: MediaImageDimensions,
+  { preservePendingFrame = false }: { preservePendingFrame?: boolean } = {}
+) {
   const connection = useStore($connection)
   const scope = useComposerScope()
   const connectionId = scope.connectionId || connection?.connectionId
@@ -28,6 +33,7 @@ export function useMediaImage(path: string, fallbackRatio: number, intrinsic?: M
   )
 
   const key = mediaImageKey(path, connection, owner)
+  const ownerKey = mediaImageKey('', connection, owner)
 
   const initialState = () => {
     const dimensions = intrinsic ?? getMediaImageDimensions(key)
@@ -35,6 +41,8 @@ export function useMediaImage(path: string, fallbackRatio: number, intrinsic?: M
 
     return {
       key,
+      ownerKey,
+      path,
       frameStyle: {
         aspectRatio: ratio,
         width: `min(calc(var(--image-preview-height) * ${ratio}), var(--image-preview-max-width), 100%${dimensions ? `, ${dimensions.width}px` : ''})`
@@ -50,7 +58,13 @@ export function useMediaImage(path: string, fallbackRatio: number, intrinsic?: M
   // Source changes must not paint the previous image/geometry even for one
   // commit. React retries this component before committing its children.
   if (state.key !== key) {
-    setState(initialState())
+    const next = initialState()
+    // A generated result fills the frame already visible while its tool was
+    // pending. Media state still resets; geometry is never inherited across
+    // owners or between two non-empty sources.
+    const inheritsPendingFrame = preservePendingFrame && state.ownerKey === ownerKey && !state.path && Boolean(path)
+
+    setState(inheritsPendingFrame ? { ...next, frameStyle: state.frameStyle } : next)
   }
 
   useEffect(() => {

From 77bb69516524d5ecaba1d9ab6ba403e0500488a0 Mon Sep 17 00:00:00 2001
From: BearHuddleston <bear@bearhuddleston.dev>
Date: Tue, 22 Sep 2026 17:56:32 -0500
Subject: [PATCH 38/61] fix(desktop): read explicitly local-owned media through
 the native bridge

An owner of connectionId 'local' was routed to /api/fs/read-data-url, which has a fixed 16 MiB cap instead of the configurable native data-URL limit. Explicit remote owners stay pinned to their API with no local fallback.

Co-authored-by: Xipong <Xipong@users.noreply.github.com>
---
 .../src/lib/media-owner-routing.test.ts       | 56 +++++++++++++++++++
 apps/desktop/src/lib/media.ts                 |  9 +++
 2 files changed, 65 insertions(+)
 create mode 100644 apps/desktop/src/lib/media-owner-routing.test.ts

diff --git a/apps/desktop/src/lib/media-owner-routing.test.ts b/apps/desktop/src/lib/media-owner-routing.test.ts
new file mode 100644
index 0000000000..04861c6643
--- /dev/null
+++ b/apps/desktop/src/lib/media-owner-routing.test.ts
@@ -0,0 +1,56 @@
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+
+import { setApiRequestConnection } from '@/api/client'
+import { $connection } from '@/store/session'
+
+import { resolveMediaDisplaySrc } from './media'
+
+const localData = 'data:image/png;base64,bG9jYWw='
+const remoteData = 'data:image/png;base64,cmVtb3Rl'
+const read = vi.fn(async () => localData)
+const api = vi.fn(async () => ({ dataUrl: remoteData }))
+
+beforeEach(() => {
+  read.mockClear()
+  api.mockReset()
+  api.mockResolvedValue({ dataUrl: remoteData })
+  vi.stubGlobal('hermesDesktop', { readFileDataUrl: read, api })
+  $connection.set({ connectionId: 'foreground-remote', mode: 'remote', profile: 'active' } as never)
+  setApiRequestConnection('foreground-remote')
+})
+
+afterEach(() => {
+  $connection.set(null)
+  setApiRequestConnection(null)
+  vi.unstubAllGlobals()
+})
+
+it('uses the native bridge for an explicit local owner, even with a remote foreground', async () => {
+  await expect(resolveMediaDisplaySrc('/local/image.png', { connectionId: 'local', profile: 'work' })).resolves.toBe(
+    localData
+  )
+  expect(read).toHaveBeenCalledTimes(1)
+  expect(read).toHaveBeenCalledWith('/local/image.png')
+  expect(api).not.toHaveBeenCalled()
+})
+
+it('keeps an explicit remote owner pinned to the API', async () => {
+  await expect(
+    resolveMediaDisplaySrc('/remote/image.png', { connectionId: 'owner-remote', profile: 'work' })
+  ).resolves.toBe(remoteData)
+  expect(api).toHaveBeenCalledTimes(1)
+  expect(api).toHaveBeenCalledWith({
+    connectionId: 'owner-remote',
+    profile: 'work',
+    path: '/api/fs/read-data-url?path=%2Fremote%2Fimage.png'
+  })
+  expect(read).not.toHaveBeenCalled()
+})
+
+it('never falls back to this device after a remote owner read fails', async () => {
+  api.mockRejectedValueOnce(new Error('remote read failed'))
+  await expect(
+    resolveMediaDisplaySrc('/same/path.png', { connectionId: 'owner-remote', profile: 'work' })
+  ).rejects.toThrow('remote read failed')
+  expect(read).not.toHaveBeenCalled()
+})
diff --git a/apps/desktop/src/lib/media.ts b/apps/desktop/src/lib/media.ts
index 830603e53a..a9e0b04109 100644
--- a/apps/desktop/src/lib/media.ts
+++ b/apps/desktop/src/lib/media.ts
@@ -1,3 +1,5 @@
+import { LOCAL_CONNECTION_ID } from '@hermes/shared'
+
 import { hermesApi, type OwnerScope } from '@/api/client'
 import type { HermesConnection } from '@/global'
 import { desktopFsCacheKey, readDesktopFileDataUrl } from '@/lib/desktop-fs'
@@ -92,6 +94,13 @@ export async function resolveMediaDisplaySrc(path: string, owner?: OwnerScope):
     return path
   }
 
+  // An explicit local owner is this device, even with a remote foreground.
+  // Keep the native reader and its configured size cap; the backend preview
+  // endpoint has a separate fixed limit.
+  if (owner?.connectionId === LOCAL_CONNECTION_ID && window.hermesDesktop?.readFileDataUrl) {
+    return window.hermesDesktop.readFileDataUrl(filePathFromMediaPath(path))
+  }
+
   // A tile can belong to a different gateway than the foreground. Pin both
   // halves at read admission rather than resolving them when the read settles.
   if (window.hermesDesktop && (owner?.connectionId || owner?.profile)) {

From 99d9b628b19c7e018f652bfcb143246c1326968d Mon Sep 17 00:00:00 2001
From: BearHuddleston <bear@bearhuddleston.dev>
Date: Tue, 22 Sep 2026 20:31:25 -0500
Subject: [PATCH 39/61] fix(desktop): drop stale tool-output image size
 overrides

The tool-output caller passed h-auto w-full object-cover to MarkdownImage. Merged over the fixed frame's size-full object-contain, a cold portrait image grew past its frame and was clipped by the wrapper. The frame now owns image sizing.
---
 .../tool/fallback-vision-image.test.tsx       | 25 +++++++++++++++++++
 .../components/assistant-ui/tool/fallback.tsx |  2 +-
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/components/assistant-ui/tool/fallback-vision-image.test.tsx b/apps/desktop/src/components/assistant-ui/tool/fallback-vision-image.test.tsx
index cf0806d96d..f1b4787f40 100644
--- a/apps/desktop/src/components/assistant-ui/tool/fallback-vision-image.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/tool/fallback-vision-image.test.tsx
@@ -82,6 +82,31 @@ describe('vision_analyze activity image', () => {
     expect(await screen.findByRole('dialog')).toBeTruthy()
   })
 
+  it('keeps a cold portrait image contained in its fixed frame instead of overriding its size', async () => {
+    $connection.set({ mode: 'local' } as never)
+    renderVisionRow()
+
+    fireEvent.click(screen.getByRole('button', { expanded: false }))
+
+    const img = await screen.findByRole('img')
+
+    await waitFor(() => expect(img.getAttribute('src')).toBe(DATA_URL))
+    Object.defineProperties(img, { naturalWidth: { value: 400 }, naturalHeight: { value: 800 } })
+    fireEvent.load(img)
+
+    // A cold image has no intrinsic dimensions yet, so its frame keeps the
+    // fallback shape and the image must fit inside it rather than size itself.
+    const frame = img.closest<HTMLElement>('[data-slot="aui_markdown-image"]')!
+
+    expect(parseFloat(frame.style.aspectRatio)).toBeCloseTo(16 / 9)
+    expect(img.classList).toContain('size-full')
+    expect(img.classList).toContain('object-contain')
+
+    for (const override of ['h-auto', 'w-full', 'object-cover']) {
+      expect(img.classList).not.toContain(override)
+    }
+  })
+
   it('reads a remote-gateway image through the profile-scoped fs API, never the local reader', async () => {
     $connection.set({ mode: 'remote', profile: 'wsl-work' } as never)
     renderVisionRow()
diff --git a/apps/desktop/src/components/assistant-ui/tool/fallback.tsx b/apps/desktop/src/components/assistant-ui/tool/fallback.tsx
index d591a97bd7..97155c5a58 100644
--- a/apps/desktop/src/components/assistant-ui/tool/fallback.tsx
+++ b/apps/desktop/src/components/assistant-ui/tool/fallback.tsx
@@ -651,7 +651,7 @@ function ToolEntry({ part }: ToolEntryProps) {
           )}
           {view.imageUrl && (
             <div className="max-w-72 overflow-hidden rounded-[0.25rem] border border-(--ui-stroke-tertiary)">
-              <MarkdownImage alt={copy.outputAlt} className="h-auto w-full object-cover" src={view.imageUrl} />
+              <MarkdownImage alt={copy.outputAlt} src={view.imageUrl} />
             </div>
           )}
           {hasSearchHits && view.searchHits && (

From 81235c9add42d125d0f3f8b9cefe84739d84b174 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:58:34 -0700
Subject: [PATCH 40/61] test: trim salvage tests to invariants

Keep the two files that pin the contract: image-geometry.test.tsx (a
markdown, MEDIA or generated image keeps one frame through cold decode,
warm return and owner/source changes, now including the pending
generated-image frame surviving its result) and media-dimensions.test.ts
(the intrinsic-size cache key: owner scope, path aliases, bounded LRU).

Dropped: the lifecycle file (its pending-frame case moved into
image-geometry), the owner-routing and pixel_size parser tests, and the
tool-output class-name assertions, which pinned implementation details
rather than behavior.
---
 .../tool/fallback-vision-image.test.tsx       |  25 -----
 .../chat/image-geometry-lifecycle.test.tsx    | 106 ------------------
 .../components/chat/image-geometry.test.tsx   |  12 ++
 apps/desktop/src/lib/generated-images.test.ts |  18 ---
 .../src/lib/media-owner-routing.test.ts       |  56 ---------
 5 files changed, 12 insertions(+), 205 deletions(-)
 delete mode 100644 apps/desktop/src/components/chat/image-geometry-lifecycle.test.tsx
 delete mode 100644 apps/desktop/src/lib/media-owner-routing.test.ts

diff --git a/apps/desktop/src/components/assistant-ui/tool/fallback-vision-image.test.tsx b/apps/desktop/src/components/assistant-ui/tool/fallback-vision-image.test.tsx
index f1b4787f40..cf0806d96d 100644
--- a/apps/desktop/src/components/assistant-ui/tool/fallback-vision-image.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/tool/fallback-vision-image.test.tsx
@@ -82,31 +82,6 @@ describe('vision_analyze activity image', () => {
     expect(await screen.findByRole('dialog')).toBeTruthy()
   })
 
-  it('keeps a cold portrait image contained in its fixed frame instead of overriding its size', async () => {
-    $connection.set({ mode: 'local' } as never)
-    renderVisionRow()
-
-    fireEvent.click(screen.getByRole('button', { expanded: false }))
-
-    const img = await screen.findByRole('img')
-
-    await waitFor(() => expect(img.getAttribute('src')).toBe(DATA_URL))
-    Object.defineProperties(img, { naturalWidth: { value: 400 }, naturalHeight: { value: 800 } })
-    fireEvent.load(img)
-
-    // A cold image has no intrinsic dimensions yet, so its frame keeps the
-    // fallback shape and the image must fit inside it rather than size itself.
-    const frame = img.closest<HTMLElement>('[data-slot="aui_markdown-image"]')!
-
-    expect(parseFloat(frame.style.aspectRatio)).toBeCloseTo(16 / 9)
-    expect(img.classList).toContain('size-full')
-    expect(img.classList).toContain('object-contain')
-
-    for (const override of ['h-auto', 'w-full', 'object-cover']) {
-      expect(img.classList).not.toContain(override)
-    }
-  })
-
   it('reads a remote-gateway image through the profile-scoped fs API, never the local reader', async () => {
     $connection.set({ mode: 'remote', profile: 'wsl-work' } as never)
     renderVisionRow()
diff --git a/apps/desktop/src/components/chat/image-geometry-lifecycle.test.tsx b/apps/desktop/src/components/chat/image-geometry-lifecycle.test.tsx
deleted file mode 100644
index a93ef18626..0000000000
--- a/apps/desktop/src/components/chat/image-geometry-lifecycle.test.tsx
+++ /dev/null
@@ -1,106 +0,0 @@
-import { act, cleanup, fireEvent, render, renderHook } from '@testing-library/react'
-import { afterEach, beforeEach, expect, it, vi } from 'vitest'
-
-import { ComposerScopeProvider, MAIN_COMPOSER_SCOPE } from '@/app/chat/composer/scope'
-import { useMediaImage } from '@/hooks/use-media-image'
-import { mediaImageKey, rememberMediaImageDimensions } from '@/lib/media'
-import { $connection } from '@/store/session'
-
-import { GeneratedImage } from './generated-image-result'
-
-vi.mock('./image-generation-placeholder', () => ({ DiffusionCanvas: () => null }))
-
-const data = 'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="900" height="600"/>'
-let reads: Array<(value: string) => void>
-const read = vi.fn(() => new Promise<string>(resolve => reads.push(resolve)))
-
-beforeEach(() => {
-  reads = []
-  read.mockClear()
-  vi.stubGlobal('hermesDesktop', { readFileDataUrl: read, api: vi.fn(() => read().then(dataUrl => ({ dataUrl }))) })
-  $connection.set({ connectionId: 'lifecycle-local', mode: 'local', profile: 'a' } as never)
-})
-
-afterEach(() => {
-  cleanup()
-  $connection.set(null)
-  vi.unstubAllGlobals()
-})
-
-function frame(container: HTMLElement) {
-  return container.querySelector<HTMLElement>('[data-slot="aui_generated-image"]')!
-}
-
-async function decode(container: HTMLElement, width: number, height: number) {
-  await act(async () => reads.shift()!(data))
-  const img = container.querySelector('img')!
-  Object.defineProperties(img, { naturalWidth: { value: width }, naturalHeight: { value: height } })
-  fireEvent.load(img)
-}
-
-it.each([
-  { name: 'result metadata', width: 900, height: 600, cached: false },
-  { name: 'warm cache', width: 800, height: 800, cached: true },
-  { name: 'same aspect but smaller intrinsic width', width: 160, height: 90, cached: false }
-])('keeps the pending frame when the result arrives with $name', async ({ name, width, height, cached }) => {
-  const path = `/lifecycle/${name}.svg`
-  const result = { success: true, image: path, pixel_size: cached ? undefined : `${width}x${height}` }
-
-  if (cached) {
-    rememberMediaImageDimensions(mediaImageKey(path, $connection.get()), width, height)
-  }
-
-  const mounted = render(<GeneratedImage aspectRatio="landscape" />)
-  const pendingStyle = frame(mounted.container).style.cssText
-  mounted.rerender(<GeneratedImage aspectRatio="landscape" result={result} />)
-
-  // This must hold before the file read settles, not just after img.onload.
-  expect(frame(mounted.container).style.cssText).toBe(pendingStyle)
-  expect(mounted.container.querySelector('img')).toBeNull()
-  await decode(mounted.container, width, height)
-  expect(frame(mounted.container).style.cssText).toBe(pendingStyle)
-  mounted.unmount()
-
-  // A fresh mount of the completed result still benefits from intrinsic size.
-  const warm = render(<GeneratedImage aspectRatio="landscape" result={result} />)
-  expect(parseFloat(frame(warm.container).style.aspectRatio)).toBeCloseTo(width / height)
-  const warmStyle = frame(warm.container).style.cssText
-  await decode(warm.container, width, height)
-  fireEvent.error(warm.container.querySelector('img')!)
-  expect(frame(warm.container).style.cssText).toBe(warmStyle)
-})
-
-it.each([
-  { connectionId: 'owner-b', profile: 'a' },
-  { connectionId: 'owner-a', profile: 'b' }
-])('does not inherit a pending frame across owner $connectionId/$profile', owner => {
-  const view = (connectionId: string, profile: string, result?: unknown) => (
-    <ComposerScopeProvider value={{ ...MAIN_COMPOSER_SCOPE, connectionId, profile }}>
-      <GeneratedImage aspectRatio="landscape" result={result} />
-    </ComposerScopeProvider>
-  )
-
-  const mounted = render(view('owner-a', 'a'))
-  mounted.rerender(view(owner.connectionId, owner.profile, { image: '/lifecycle/other.svg', pixel_size: '600x900' }))
-  expect(parseFloat(frame(mounted.container).style.aspectRatio)).toBeCloseTo(600 / 900)
-})
-
-it('still resets the frame between two actual image sources', () => {
-  const mounted = render(<GeneratedImage result={{ image: '/lifecycle/first.svg', pixel_size: '900x600' }} />)
-  mounted.rerender(<GeneratedImage result={{ image: '/lifecycle/second.svg', pixel_size: '600x900' }} />)
-  expect(parseFloat(frame(mounted.container).style.aspectRatio)).toBeCloseTo(600 / 900)
-})
-
-it('does not reserve an empty markdown image unless the caller opts in', () => {
-  const mounted = renderHook(
-    ({ path }) => useMediaImage(path, 16 / 9, path ? { width: 600, height: 900 } : undefined),
-    {
-      initialProps: { path: '' }
-    }
-  )
-
-  expect(mounted.result.current.frameStyle.aspectRatio).toBeCloseTo(16 / 9)
-  // Markdown callers keep the default source-based lifetime.
-  mounted.rerender({ path: '/lifecycle/markdown.svg' })
-  expect(mounted.result.current.frameStyle.aspectRatio).toBeCloseTo(600 / 900)
-})
diff --git a/apps/desktop/src/components/chat/image-geometry.test.tsx b/apps/desktop/src/components/chat/image-geometry.test.tsx
index d2dfdc6aad..b78f070cbe 100644
--- a/apps/desktop/src/components/chat/image-geometry.test.tsx
+++ b/apps/desktop/src/components/chat/image-geometry.test.tsx
@@ -96,6 +96,18 @@ it.each(cases)('reserves $kind frames through cold decode, warm return and failu
   expect(warm.container.textContent).toMatch(/Open image/i)
 })
 
+it('keeps the pending generated-image frame when its result arrives', async () => {
+  const path = '/geometry/pending.svg'
+  const mounted = render(<GeneratedImage aspectRatio="landscape" />)
+  const pendingStyle = frame(mounted.container).style.cssText
+  mounted.rerender(<GeneratedImage aspectRatio="landscape" result={{ success: true, image: path, pixel_size: '900x600' }} />)
+
+  // Must hold before the file read settles, not just after img.onload.
+  expect(frame(mounted.container).style.cssText).toBe(pendingStyle)
+  await decode(mounted.container, 900, 600)
+  expect(frame(mounted.container).style.cssText).toBe(pendingStyle)
+})
+
 it.each(['markdown', 'generated'])('%s dimensions follow owner and source, not stale reads or hints', async kind => {
   const path = `${paths.second}?${kind}`
 
diff --git a/apps/desktop/src/lib/generated-images.test.ts b/apps/desktop/src/lib/generated-images.test.ts
index 7eb1e85cbf..7fb3210510 100644
--- a/apps/desktop/src/lib/generated-images.test.ts
+++ b/apps/desktop/src/lib/generated-images.test.ts
@@ -2,30 +2,12 @@ import { describe, expect, it } from 'vitest'
 
 import {
   dedupeGeneratedImageEchoesInParts,
-  generatedImageDimensionsFromResult,
   generatedImageEchoSources,
   generatedImageFromResult,
   stripGeneratedImageEchoes
 } from './generated-images'
 
 describe('generatedImageFromResult', () => {
-  it('uses decoded pixel_size, never requested sizing, for intrinsic geometry', () => {
-    const dimensions = { width: 900, height: 600 }
-
-    const result = {
-      success: true,
-      image: '/image.png',
-      pixel_size: `${dimensions.width}x${dimensions.height}`,
-      size: '1024x1024'
-    }
-
-    expect(generatedImageDimensionsFromResult(JSON.stringify(result))).toEqual(dimensions)
-
-    for (const pixel_size of [undefined, 'auto', '0x600', '9'.repeat(400) + 'x600']) {
-      expect(generatedImageDimensionsFromResult({ ...result, pixel_size })).toBeUndefined()
-    }
-  })
-
   it('prefers the host-visible image path', () => {
     expect(
       generatedImageFromResult({
diff --git a/apps/desktop/src/lib/media-owner-routing.test.ts b/apps/desktop/src/lib/media-owner-routing.test.ts
deleted file mode 100644
index 04861c6643..0000000000
--- a/apps/desktop/src/lib/media-owner-routing.test.ts
+++ /dev/null
@@ -1,56 +0,0 @@
-import { afterEach, beforeEach, expect, it, vi } from 'vitest'
-
-import { setApiRequestConnection } from '@/api/client'
-import { $connection } from '@/store/session'
-
-import { resolveMediaDisplaySrc } from './media'
-
-const localData = 'data:image/png;base64,bG9jYWw='
-const remoteData = 'data:image/png;base64,cmVtb3Rl'
-const read = vi.fn(async () => localData)
-const api = vi.fn(async () => ({ dataUrl: remoteData }))
-
-beforeEach(() => {
-  read.mockClear()
-  api.mockReset()
-  api.mockResolvedValue({ dataUrl: remoteData })
-  vi.stubGlobal('hermesDesktop', { readFileDataUrl: read, api })
-  $connection.set({ connectionId: 'foreground-remote', mode: 'remote', profile: 'active' } as never)
-  setApiRequestConnection('foreground-remote')
-})
-
-afterEach(() => {
-  $connection.set(null)
-  setApiRequestConnection(null)
-  vi.unstubAllGlobals()
-})
-
-it('uses the native bridge for an explicit local owner, even with a remote foreground', async () => {
-  await expect(resolveMediaDisplaySrc('/local/image.png', { connectionId: 'local', profile: 'work' })).resolves.toBe(
-    localData
-  )
-  expect(read).toHaveBeenCalledTimes(1)
-  expect(read).toHaveBeenCalledWith('/local/image.png')
-  expect(api).not.toHaveBeenCalled()
-})
-
-it('keeps an explicit remote owner pinned to the API', async () => {
-  await expect(
-    resolveMediaDisplaySrc('/remote/image.png', { connectionId: 'owner-remote', profile: 'work' })
-  ).resolves.toBe(remoteData)
-  expect(api).toHaveBeenCalledTimes(1)
-  expect(api).toHaveBeenCalledWith({
-    connectionId: 'owner-remote',
-    profile: 'work',
-    path: '/api/fs/read-data-url?path=%2Fremote%2Fimage.png'
-  })
-  expect(read).not.toHaveBeenCalled()
-})
-
-it('never falls back to this device after a remote owner read fails', async () => {
-  api.mockRejectedValueOnce(new Error('remote read failed'))
-  await expect(
-    resolveMediaDisplaySrc('/same/path.png', { connectionId: 'owner-remote', profile: 'work' })
-  ).rejects.toThrow('remote read failed')
-  expect(read).not.toHaveBeenCalled()
-})

From 4c6137fa89e943aecd30b2deacef0864e5cc0038 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:58:50 -0700
Subject: [PATCH 41/61] fix(desktop): never upscale a cold chat image or shrink
 its portrait

An uncached image got a 16:9 frame with a size-full object-contain
<img>, so an 88x20 image rendered at 544x124 and a 1080x1920 portrait
at 172x306 (main: 225x400). The frame box also carried the image's
shadow and download button out on the letterbox.

The image now keeps its natural size, capped by the frame (w-auto
h-auto max-w/max-h-full, object-scale-down), inside a w-fit container
anchored top-left, and the cold frame is 4:3: that approximates the
34rem x 26.25rem envelope an image could already occupy, so every shape
renders within a few percent of its pre-frame size while the frame
still never resizes during a mount. Warm mounts keep using the measured
size.
---
 .../components/assistant-ui/markdown-text.tsx    | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/apps/desktop/src/components/assistant-ui/markdown-text.tsx b/apps/desktop/src/components/assistant-ui/markdown-text.tsx
index c7c955d167..d5bc7d3988 100644
--- a/apps/desktop/src/components/assistant-ui/markdown-text.tsx
+++ b/apps/desktop/src/components/assistant-ui/markdown-text.tsx
@@ -374,6 +374,13 @@ export function MarkdownImage(props: ComponentProps<'img'>) {
   return <MarkdownImageContent {...props} />
 }
 
+// A cold frame is ~4:3 because that is the envelope an image can occupy here
+// (--image-preview-max-width x --image-preview-height, 34rem x 26.25rem): every
+// shape, portrait included, fits at the size it would have without a reserved
+// frame. A 16:9 box shrank every narrower image (a 1080x1920 portrait to
+// 172x306). Warm mounts use the measured size instead.
+const COLD_IMAGE_RATIO = 4 / 3
+
 function MarkdownImageContent({
   className,
   src,
@@ -386,7 +393,7 @@ function MarkdownImageContent({
   ...props
 }: ComponentProps<'img'>) {
   const rawSrc = typeof src === 'string' ? src : ''
-  const image = useMediaImage(rawSrc, 16 / 9, validImageDimensions(width, height))
+  const image = useMediaImage(rawSrc, COLD_IMAGE_RATIO, validImageDimensions(width, height))
   const { open, openFailed } = useOpenMediaFile(rawSrc)
   const name = mediaName(rawSrc || String(alt || 'image'))
 
@@ -394,6 +401,9 @@ function MarkdownImageContent({
     return null
   }
 
+  // The image keeps its natural size (never upscaled) inside the fixed frame;
+  // the w-fit container hugs it so the download button and shadow sit on the
+  // image, not on the letterbox.
   return (
     <span className="relative my-2 block max-w-full" data-slot="aui_markdown-image" style={image.frameStyle}>
       {image.failed ? (
@@ -409,10 +419,10 @@ function MarkdownImageContent({
           {...props}
           alt={alt}
           className={cn(
-            'm-0 block size-full rounded-lg object-contain shadow-[0_0.0625rem_0.125rem_color-mix(in_srgb,#000_4%,transparent),0_0.625rem_1.5rem_color-mix(in_srgb,#000_5%,transparent)]',
+            'm-0 block h-auto max-h-full w-auto max-w-full rounded-lg object-scale-down shadow-[0_0.0625rem_0.125rem_color-mix(in_srgb,#000_4%,transparent),0_0.625rem_1.5rem_color-mix(in_srgb,#000_5%,transparent)]',
             className
           )}
-          containerClassName="absolute inset-0 block size-full"
+          containerClassName="absolute left-0 top-0 block h-full w-fit"
           onError={event => {
             image.onError()
             onError?.(event)

From d113cfc20851ef0c03be3fa340ee065f36f2c238 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:59:12 -0700
Subject: [PATCH 42/61] fix(desktop): remember the size of inline data-URL chat
 images

The intrinsic-size cache key embedded the whole source, and keys over
4096 chars were never stored, so every inline base64 image (tool output,
MEDIA data URLs) letterboxed on every mount. The key was also a
JSON.stringify over the multi-megabyte data URL on every render.

Data URLs over 512 chars are now keyed by length + a head/tail slice
(the head carries the format header, usually the pixel size). A
collision can only lend another image's frame shape, never its pixels.
---
 .../src/components/chat/image-geometry.test.tsx     | 13 +++++++++++++
 apps/desktop/src/lib/media-dimensions.test.ts       |  9 +++++++++
 apps/desktop/src/lib/media.ts                       | 12 +++++++++++-
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/components/chat/image-geometry.test.tsx b/apps/desktop/src/components/chat/image-geometry.test.tsx
index b78f070cbe..c82c629a91 100644
--- a/apps/desktop/src/components/chat/image-geometry.test.tsx
+++ b/apps/desktop/src/components/chat/image-geometry.test.tsx
@@ -108,6 +108,19 @@ it('keeps the pending generated-image frame when its result arrives', async () =
   expect(frame(mounted.container).style.cssText).toBe(pendingStyle)
 })
 
+it('keys inline data sources by a bounded digest so they are remembered', async () => {
+  const big = (fill: string) => `data:image/png;base64,${fill.repeat(200_000)}`
+  const first = render(<MarkdownImage alt="inline" src={big('A')} />)
+  expect(first.container.querySelector('img')).not.toBeNull()
+  const img = first.container.querySelector('img')!
+  Object.defineProperties(img, { naturalWidth: { value: 900 }, naturalHeight: { value: 600 } })
+  fireEvent.load(img)
+  first.unmount()
+
+  expect(parseFloat(frame(render(<MarkdownImage alt="inline" src={big('A')} />).container).style.aspectRatio)).toBe(1.5)
+  expect(parseFloat(frame(render(<MarkdownImage alt="inline" src={big('B')} />).container).style.aspectRatio)).not.toBe(1.5)
+})
+
 it.each(['markdown', 'generated'])('%s dimensions follow owner and source, not stale reads or hints', async kind => {
   const path = `${paths.second}?${kind}`
 
diff --git a/apps/desktop/src/lib/media-dimensions.test.ts b/apps/desktop/src/lib/media-dimensions.test.ts
index bc0c4c9a99..1f9052a04d 100644
--- a/apps/desktop/src/lib/media-dimensions.test.ts
+++ b/apps/desktop/src/lib/media-dimensions.test.ts
@@ -43,3 +43,12 @@ it('shares proven path aliases only within an owner and bounds regenerated metad
   forgetMediaImageDimensions(key)
   expect(getMediaImageDimensions(key)).toBeUndefined()
 })
+
+it('keeps multi-megabyte inline sources to a small, distinct key', () => {
+  const a = { connectionId: 'a', profile: 'work', mode: 'local' } as HermesConnection
+  const inline = (tail: string) => `data:image/png;base64,${'A'.repeat(4_000_000)}${tail}`
+
+  expect(mediaImageKey(inline('x'), a).length).toBeLessThan(1024)
+  expect(mediaImageKey(inline('x'), a)).toBe(mediaImageKey(inline('x'), a))
+  expect(mediaImageKey(inline('x'), a)).not.toBe(mediaImageKey(inline('y'), a))
+})
diff --git a/apps/desktop/src/lib/media.ts b/apps/desktop/src/lib/media.ts
index a9e0b04109..8d32a720f3 100644
--- a/apps/desktop/src/lib/media.ts
+++ b/apps/desktop/src/lib/media.ts
@@ -143,11 +143,21 @@ export function mediaImageKey(path: string, connection: HermesConnection | null,
       connection?.connectionId ||
       desktopFsCacheKey(connection && { ...connection, profile: owner?.profile ?? connection.profile }),
     owner?.profile ?? connection?.profile ?? '',
-    filePathFromMediaPath(path),
+    mediaSourceIdentity(path),
     revision
   ])
 }
 
+// Inline sources are the bytes themselves (often megabytes) and this key is
+// rebuilt every render. Length plus head (format header, usually the size)
+// and tail keeps it small and cacheable; a collision can only borrow another
+// image's frame shape, never its pixels.
+function mediaSourceIdentity(path: string): string {
+  return /^data:/i.test(path) && path.length > 512
+    ? `data#${path.length}:${path.slice(0, 160)}:${path.slice(-96)}`
+    : filePathFromMediaPath(path)
+}
+
 export function validImageDimensions(width: unknown, height: unknown): MediaImageDimensions | undefined {
   const w = Number(width)
   const h = Number(height)

From 06616b4985f5d08008d0ba65964c38d4c248d36a Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:59:33 -0700
Subject: [PATCH 43/61] fix(desktop): collapse a broken chat image to one line

A failed markdown/MEDIA image kept its reserved frame, so a broken link
left an empty ~544x306 box with the error text in its corner, and a
failed generated image left an empty rounded frame. Both now collapse to
the single "Couldn't load ... Open image" / "Open image: name" line, as
before frames existed; the one-time shift on error is the lesser cost.

The failure is remembered in the same bounded size cache, so the next
mount of that source (turn completion remounts every part) starts as a
text line instead of reserving a frame that would collapse again. A
later successful load overwrites the entry.
---
 .../components/assistant-ui/markdown-text.tsx | 42 ++++++++++++------
 .../chat/generated-image-result.tsx           | 43 ++++++++++---------
 .../components/chat/image-geometry.test.tsx   | 12 +++++-
 apps/desktop/src/hooks/use-media-image.ts     | 21 +++++----
 apps/desktop/src/lib/media-dimensions.test.ts |  8 +++-
 apps/desktop/src/lib/media.ts                 | 30 +++++++++----
 6 files changed, 104 insertions(+), 52 deletions(-)

diff --git a/apps/desktop/src/components/assistant-ui/markdown-text.tsx b/apps/desktop/src/components/assistant-ui/markdown-text.tsx
index d5bc7d3988..f14b3d78ee 100644
--- a/apps/desktop/src/components/assistant-ui/markdown-text.tsx
+++ b/apps/desktop/src/components/assistant-ui/markdown-text.tsx
@@ -401,28 +401,42 @@ function MarkdownImageContent({
     return null
   }
 
+  // A broken link has nothing to reserve space for: one line, not an empty
+  // frame. The one-time shift on error is the lesser cost.
+  if (image.failed) {
+    return (
+      <span className="my-2 block text-sm text-muted-foreground" data-slot="aui_markdown-image">
+        Couldn&apos;t load {name}.{' '}
+        <button className="ref font-medium text-foreground" onClick={open} type="button">
+          Open image
+        </button>
+        {openFailed && <OpenMediaFailedNote name={name} />}
+      </span>
+    )
+  }
+
   // The image keeps its natural size (never upscaled) inside the fixed frame;
   // the w-fit container hugs it so the download button and shadow sit on the
-  // image, not on the letterbox.
+  // image, not on the letterbox. Without a frame (a source that failed last
+  // time) it lays out as a plain capped image, like before frames existed.
+  const framed = Boolean(image.frameStyle)
+
   return (
     <span className="relative my-2 block max-w-full" data-slot="aui_markdown-image" style={image.frameStyle}>
-      {image.failed ? (
-        <span className="absolute inset-0 block overflow-auto text-sm text-muted-foreground">
-          Couldn&apos;t load {name}.{' '}
-          <button className="ref font-medium text-foreground" onClick={open} type="button">
-            Open image
-          </button>
-          {openFailed && <OpenMediaFailedNote name={name} />}
-        </span>
-      ) : image.src ? (
+      {image.src ? (
         <ZoomableImage
           {...props}
           alt={alt}
           className={cn(
-            'm-0 block h-auto max-h-full w-auto max-w-full rounded-lg object-scale-down shadow-[0_0.0625rem_0.125rem_color-mix(in_srgb,#000_4%,transparent),0_0.625rem_1.5rem_color-mix(in_srgb,#000_5%,transparent)]',
+            'm-0 block h-auto w-auto max-w-full rounded-lg object-scale-down shadow-[0_0.0625rem_0.125rem_color-mix(in_srgb,#000_4%,transparent),0_0.625rem_1.5rem_color-mix(in_srgb,#000_5%,transparent)]',
+            framed ? 'max-h-full' : 'max-h-(--image-preview-height)',
             className
           )}
-          containerClassName="absolute left-0 top-0 block h-full w-fit"
+          containerClassName={
+            framed
+              ? 'absolute left-0 top-0 block h-full w-fit'
+              : 'block w-fit max-w-[min(100%,var(--image-preview-max-width))]'
+          }
           onError={event => {
             image.onError()
             onError?.(event)
@@ -435,7 +449,9 @@ function MarkdownImageContent({
           style={style}
         />
       ) : (
-        <span className="absolute inset-0 block overflow-hidden text-sm text-muted-foreground">Loading {name}...</span>
+        <span className={cn('block overflow-hidden text-sm text-muted-foreground', framed && 'absolute inset-0')}>
+          Loading {name}...
+        </span>
       )}
     </span>
   )
diff --git a/apps/desktop/src/components/chat/generated-image-result.tsx b/apps/desktop/src/components/chat/generated-image-result.tsx
index 7b27c969aa..5ae4384c4b 100644
--- a/apps/desktop/src/components/chat/generated-image-result.tsx
+++ b/apps/desktop/src/components/chat/generated-image-result.tsx
@@ -49,6 +49,22 @@ export const GeneratedImage: FC<{ aspectRatio?: string; result?: unknown }> = ({
     return null
   }
 
+  // Nothing will fill the frame, so collapse to the link line.
+  if (failed && image) {
+    return (
+      <a
+        className="mt-2 ref inline-block wrap-anywhere"
+        href="#"
+        onClick={event => {
+          event.preventDefault()
+          void window.hermesDesktop?.openExternal(mediaExternalUrl(image))
+        }}
+      >
+        {copy.openImage}: {mediaName(image)}
+      </a>
+    )
+  }
+
   return (
     <>
       <span
@@ -59,28 +75,15 @@ export const GeneratedImage: FC<{ aspectRatio?: string; result?: unknown }> = ({
         role={pending ? 'status' : undefined}
         style={media.frameStyle}
       >
-        {failed && image ? (
-          <a
-            className="absolute inset-0 ref block overflow-auto wrap-anywhere"
-            href="#"
-            onClick={event => {
-              event.preventDefault()
-              void window.hermesDesktop?.openExternal(mediaExternalUrl(image))
-            }}
+        {canvasGone !== media.key && (
+          <div
+            className={cn('absolute inset-0 transition-opacity duration-500 ease-out', loaded && 'opacity-0')}
+            onTransitionEnd={() => loaded && setCanvasGone(media.key)}
           >
-            {copy.openImage}: {mediaName(image)}
-          </a>
-        ) : (
-          canvasGone !== media.key && (
-            <div
-              className={cn('absolute inset-0 transition-opacity duration-500 ease-out', loaded && 'opacity-0')}
-              onTransitionEnd={() => loaded && setCanvasGone(media.key)}
-            >
-              <DiffusionCanvas />
-            </div>
-          )
+            <DiffusionCanvas />
+          </div>
         )}
-        {src && !failed && (
+        {src && (
           <button
             aria-label={copy.openImage}
             className="absolute inset-0 block size-full cursor-zoom-in"
diff --git a/apps/desktop/src/components/chat/image-geometry.test.tsx b/apps/desktop/src/components/chat/image-geometry.test.tsx
index c82c629a91..b1a213c75b 100644
--- a/apps/desktop/src/components/chat/image-geometry.test.tsx
+++ b/apps/desktop/src/components/chat/image-geometry.test.tsx
@@ -91,9 +91,19 @@ it.each(cases)('reserves $kind frames through cold decode, warm return and failu
   const warmSize = reserved.style.cssText
   await decode(warm.container)
   expect(frame(warm.container).style.cssText).toBe(warmSize)
+
+  // A broken image collapses to its text line instead of an empty frame, and
+  // the next mount of that source does not reserve a frame just to collapse it.
   fireEvent.error(warm.container.querySelector('img')!)
-  expect(frame(warm.container).style.cssText).toBe(warmSize)
   expect(warm.container.textContent).toMatch(/Open image/i)
+  expect(frame(warm.container)?.style.aspectRatio ?? '').toBe('')
+  warm.unmount()
+
+  const retry = render(content(kind, path, hint))
+
+  if (hint !== 'intrinsic') {
+    expect(frame(retry.container)?.style.aspectRatio ?? '').toBe('')
+  }
 })
 
 it('keeps the pending generated-image frame when its result arrives', async () => {
diff --git a/apps/desktop/src/hooks/use-media-image.ts b/apps/desktop/src/hooks/use-media-image.ts
index e51f9366ca..bdb5c2e5f4 100644
--- a/apps/desktop/src/hooks/use-media-image.ts
+++ b/apps/desktop/src/hooks/use-media-image.ts
@@ -3,12 +3,13 @@ import { type CSSProperties, useEffect, useMemo, useState } from 'react'
 
 import { useComposerScope } from '@/app/chat/composer/scope'
 import {
-  forgetMediaImageDimensions,
   getMediaImageDimensions,
   isInlineMediaSrc,
+  isKnownBrokenMediaImage,
   type MediaImageDimensions,
   mediaImageKey,
   rememberMediaImageDimensions,
+  rememberMediaImageFailure,
   resolveMediaDisplaySrc
 } from '@/lib/media'
 import { $connection } from '@/store/session'
@@ -43,10 +44,14 @@ export function useMediaImage(
       key,
       ownerKey,
       path,
-      frameStyle: {
-        aspectRatio: ratio,
-        width: `min(calc(var(--image-preview-height) * ${ratio}), var(--image-preview-max-width), 100%${dimensions ? `, ${dimensions.width}px` : ''})`
-      } satisfies CSSProperties,
+      // A source that just failed gets no frame: it would only collapse again.
+      frameStyle:
+        !dimensions && isKnownBrokenMediaImage(key)
+          ? undefined
+          : ({
+              aspectRatio: ratio,
+              width: `min(calc(var(--image-preview-height) * ${ratio}), var(--image-preview-max-width), 100%${dimensions ? `, ${dimensions.width}px` : ''})`
+            } satisfies CSSProperties),
       src: path && isInlineMediaSrc(path) ? path : '',
       loaded: false,
       failed: false
@@ -75,7 +80,7 @@ export function useMediaImage(
         src => {
           if (!cancelled) {
             if (!src) {
-              forgetMediaImageDimensions(key)
+              rememberMediaImageFailure(key)
             }
 
             setState(current => ({ ...current, src, failed: !src }))
@@ -83,7 +88,7 @@ export function useMediaImage(
         },
         () => {
           if (!cancelled) {
-            forgetMediaImageDimensions(key)
+            rememberMediaImageFailure(key)
             setState(current => ({ ...current, failed: true }))
           }
         }
@@ -102,7 +107,7 @@ export function useMediaImage(
       setState(current => ({ ...current, loaded: true }))
     },
     onError: () => {
-      forgetMediaImageDimensions(key)
+      rememberMediaImageFailure(key)
       setState(current => ({ ...current, failed: true, loaded: false }))
     }
   }
diff --git a/apps/desktop/src/lib/media-dimensions.test.ts b/apps/desktop/src/lib/media-dimensions.test.ts
index 1f9052a04d..72f83507a5 100644
--- a/apps/desktop/src/lib/media-dimensions.test.ts
+++ b/apps/desktop/src/lib/media-dimensions.test.ts
@@ -3,10 +3,11 @@ import { expect, it } from 'vitest'
 import type { HermesConnection } from '@/global'
 
 import {
-  forgetMediaImageDimensions,
   getMediaImageDimensions,
+  isKnownBrokenMediaImage,
   mediaImageKey,
   rememberMediaImageDimensions,
+  rememberMediaImageFailure,
   validImageDimensions
 } from './media'
 
@@ -40,8 +41,11 @@ it('shares proven path aliases only within an owner and bounds regenerated metad
   expect(getMediaImageDimensions(key)).toEqual(dimensions)
   rememberMediaImageDimensions('x'.repeat(100000), 100, 100)
   expect(getMediaImageDimensions('x'.repeat(100000))).toBeUndefined()
-  forgetMediaImageDimensions(key)
+  rememberMediaImageFailure(key)
   expect(getMediaImageDimensions(key)).toBeUndefined()
+  expect(isKnownBrokenMediaImage(key)).toBe(true)
+  rememberMediaImageDimensions(key, dimensions.width, dimensions.height)
+  expect(isKnownBrokenMediaImage(key)).toBe(false)
 })
 
 it('keeps multi-megabyte inline sources to a small, distinct key', () => {
diff --git a/apps/desktop/src/lib/media.ts b/apps/desktop/src/lib/media.ts
index 8d32a720f3..93804c0b95 100644
--- a/apps/desktop/src/lib/media.ts
+++ b/apps/desktop/src/lib/media.ts
@@ -131,7 +131,9 @@ export interface MediaImageDimensions {
 
 // Decoded geometry only: never retain image bytes/data URLs for every visited
 // transcript. A miss costs a letterboxed first display, not a collapsed row.
-const imageDimensions = new LruCache<string, MediaImageDimensions>(512)
+// 'broken' remembers a failed load so a remount starts as a text line instead
+// of reserving a frame that collapses again.
+const imageDimensions = new LruCache<string, 'broken' | MediaImageDimensions>(512)
 
 export function mediaImageKey(path: string, connection: HermesConnection | null, owner?: OwnerScope): string {
   // File reads ignore URL query/fragment, but callers can use them to identify
@@ -166,21 +168,33 @@ export function validImageDimensions(width: unknown, height: unknown): MediaImag
 }
 
 export function getMediaImageDimensions(key: string): MediaImageDimensions | undefined {
-  return imageDimensions.get(key)
+  const entry = imageDimensions.get(key)
+
+  return entry === 'broken' ? undefined : entry
+}
+
+export function isKnownBrokenMediaImage(key: string): boolean {
+  return imageDimensions.get(key) === 'broken'
+}
+
+// A pathological URL can still make a huge key; keep this metadata cache from
+// becoming a second copy of it.
+function rememberMediaImage(key: string, entry: 'broken' | MediaImageDimensions): void {
+  if (key.length <= 4096) {
+    imageDimensions.set(key, entry)
+  }
 }
 
 export function rememberMediaImageDimensions(key: string, width: number, height: number): void {
   const dimensions = validImageDimensions(width, height)
 
-  // Embedded images can have multi-megabyte source keys. Their bytes stay with
-  // the message; do not turn this small metadata cache into a second copy.
-  if (dimensions && key.length <= 4096) {
-    imageDimensions.set(key, dimensions)
+  if (dimensions) {
+    rememberMediaImage(key, dimensions)
   }
 }
 
-export function forgetMediaImageDimensions(key: string): void {
-  imageDimensions.delete(key)
+export function rememberMediaImageFailure(key: string): void {
+  rememberMediaImage(key, 'broken')
 }
 
 // Audio/video need a seekable source instead of a whole-file data URL. Keep

From 51f8b7c3bef85af1729f78736dccbb6b4b46b75b Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:02:11 -0700
Subject: [PATCH 44/61] chore(desktop): neutral wording in the pixel_size
 comment

Name the field contract instead of one backend, so the comment stays true
for any image plugin that reports decoded geometry.
---
 apps/desktop/src/lib/generated-images.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/desktop/src/lib/generated-images.ts b/apps/desktop/src/lib/generated-images.ts
index 233e44ce83..d88f5e463a 100644
--- a/apps/desktop/src/lib/generated-images.ts
+++ b/apps/desktop/src/lib/generated-images.ts
@@ -68,7 +68,7 @@ export function generatedImageFromResult(result: unknown): string | null {
   return stringFields(record, DISPLAY_KEYS)[0] ?? null
 }
 
-/** Codex reports decoded PNG geometry separately from its requested `size`.
+/** Image backends can report decoded PNG geometry (`pixel_size`) separately from the requested `size`.
  * Never use requested_size/size or aspect_ratio as intrinsic metadata. */
 export function generatedImageDimensionsFromResult(result: unknown): MediaImageDimensions | undefined {
   const record = recordFromUnknown(result)

From ee8ffffd45350ceb27361ac05734c53658c4ade8 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:37:37 -0700
Subject: [PATCH 45/61] fix(desktop): keep a generated image visible after a
 remembered failure

After a generated image failed once, the next mount of the same result
(session switch, reconnect) took the known-broken shortcut and got no
frame. GeneratedImage's outer span has only absolutely positioned
children, so when the retry then succeeded the image rendered into a
zero-height box: invisible, with no fallback link either. The
known-broken shortcut only makes sense for markdown images, which lay out
as a plain capped image without a frame; a generated image now always
keeps its hinted frame.

While the tool is still pending (no path yet), an aspect-ratio hint that
arrives after mount was ignored because the frame was computed once per
source key. With nothing painted yet there is no shift to avoid, so the
pending frame now follows the hint.

Also guard the resolved-read setState with current.key === key so a read
for a superseded source can never write into the new source's state.

image-geometry.test.tsx: a successful retry after a remembered failure
must render with a non-zero frame (red on 375c0f31d6: aspectRatio NaN),
and a pending card must reshape when its hint changes (red: stayed 1:1).
The markdown/media rows still assert no frame on the retry.
---
 .../components/chat/image-geometry.test.tsx   | 19 ++++++++++++++++---
 apps/desktop/src/hooks/use-media-image.ts     | 17 ++++++++++++-----
 2 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/apps/desktop/src/components/chat/image-geometry.test.tsx b/apps/desktop/src/components/chat/image-geometry.test.tsx
index b1a213c75b..9ccc41b489 100644
--- a/apps/desktop/src/components/chat/image-geometry.test.tsx
+++ b/apps/desktop/src/components/chat/image-geometry.test.tsx
@@ -93,7 +93,9 @@ it.each(cases)('reserves $kind frames through cold decode, warm return and failu
   expect(frame(warm.container).style.cssText).toBe(warmSize)
 
   // A broken image collapses to its text line instead of an empty frame, and
-  // the next mount of that source does not reserve a frame just to collapse it.
+  // the next markdown mount of that source does not reserve a frame just to
+  // collapse it. A generated image's children are all absolutely positioned,
+  // so it keeps its hinted frame: a successful retry must still be visible.
   fireEvent.error(warm.container.querySelector('img')!)
   expect(warm.container.textContent).toMatch(/Open image/i)
   expect(frame(warm.container)?.style.aspectRatio ?? '').toBe('')
@@ -101,14 +103,25 @@ it.each(cases)('reserves $kind frames through cold decode, warm return and failu
 
   const retry = render(content(kind, path, hint))
 
-  if (hint !== 'intrinsic') {
+  if (kind !== 'generated' && hint !== 'intrinsic') {
     expect(frame(retry.container)?.style.aspectRatio ?? '').toBe('')
   }
+
+  await decode(retry.container)
+  expect(retry.container.querySelector('img')).not.toBeNull()
+
+  if (kind === 'generated') {
+    expect(parseFloat(frame(retry.container).style.aspectRatio)).toBeGreaterThan(0)
+  }
 })
 
 it('keeps the pending generated-image frame when its result arrives', async () => {
   const path = '/geometry/pending.svg'
-  const mounted = render(<GeneratedImage aspectRatio="landscape" />)
+  const mounted = render(<GeneratedImage aspectRatio="square" />)
+  expect(parseFloat(frame(mounted.container).style.aspectRatio)).toBe(1)
+  // The hint can arrive after the pending card mounted; nothing is shown yet.
+  mounted.rerender(<GeneratedImage aspectRatio="landscape" />)
+  expect(parseFloat(frame(mounted.container).style.aspectRatio)).toBeCloseTo(16 / 9)
   const pendingStyle = frame(mounted.container).style.cssText
   mounted.rerender(<GeneratedImage aspectRatio="landscape" result={{ success: true, image: path, pixel_size: '900x600' }} />)
 
diff --git a/apps/desktop/src/hooks/use-media-image.ts b/apps/desktop/src/hooks/use-media-image.ts
index bdb5c2e5f4..818d7efc6b 100644
--- a/apps/desktop/src/hooks/use-media-image.ts
+++ b/apps/desktop/src/hooks/use-media-image.ts
@@ -16,7 +16,12 @@ import { $connection } from '@/store/session'
 
 /** Keep a frame for one source/owner for its mounted lifetime. Hints are not
  * intrinsic dimensions: a cold image is contained in that frame, not allowed
- * to resize it at decode. The next mount can use the measured dimensions. */
+ * to resize it at decode. The next mount can use the measured dimensions.
+ *
+ * `preservePendingFrame` is for a caller whose content is all absolutely
+ * positioned (a generated image): it always gets a frame, since without one a
+ * successful retry renders into a zero-height box, and it keeps the frame
+ * shown while its tool was pending. */
 export function useMediaImage(
   path: string,
   fallbackRatio: number,
@@ -44,9 +49,10 @@ export function useMediaImage(
       key,
       ownerKey,
       path,
+      fallbackRatio,
       // A source that just failed gets no frame: it would only collapse again.
       frameStyle:
-        !dimensions && isKnownBrokenMediaImage(key)
+        !dimensions && !preservePendingFrame && isKnownBrokenMediaImage(key)
           ? undefined
           : ({
               aspectRatio: ratio,
@@ -62,7 +68,8 @@ export function useMediaImage(
 
   // Source changes must not paint the previous image/geometry even for one
   // commit. React retries this component before committing its children.
-  if (state.key !== key) {
+  // With no source yet, nothing is painted, so a hint arriving late reshapes.
+  if (state.key !== key || (!path && state.fallbackRatio !== fallbackRatio)) {
     const next = initialState()
     // A generated result fills the frame already visible while its tool was
     // pending. Media state still resets; geometry is never inherited across
@@ -83,13 +90,13 @@ export function useMediaImage(
               rememberMediaImageFailure(key)
             }
 
-            setState(current => ({ ...current, src, failed: !src }))
+            setState(current => (current.key === key ? { ...current, src, failed: !src } : current))
           }
         },
         () => {
           if (!cancelled) {
             rememberMediaImageFailure(key)
-            setState(current => ({ ...current, failed: true }))
+            setState(current => (current.key === key ? { ...current, failed: true } : current))
           }
         }
       )

From f6d0e0c20d9a4be5e13c21807344b731ecebaf86 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:37:37 -0700
Subject: [PATCH 46/61] fix(desktop): restore the remote-owner image routing
 test

The test trim dropped every assertion of the owner-routing invariant: an
image owned by a remote tile must be read through that gateway's API,
never through the local file reader, even when the foreground connection
is local. With distinct api and readFileDataUrl spies, the test fails
('data:local') when the owner branch in resolveMediaDisplaySrc is
removed, and passes with it.
---
 apps/desktop/src/lib/media-dimensions.test.ts | 21 ++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/lib/media-dimensions.test.ts b/apps/desktop/src/lib/media-dimensions.test.ts
index 72f83507a5..e1d7d18c52 100644
--- a/apps/desktop/src/lib/media-dimensions.test.ts
+++ b/apps/desktop/src/lib/media-dimensions.test.ts
@@ -1,6 +1,7 @@
-import { expect, it } from 'vitest'
+import { expect, it, vi } from 'vitest'
 
 import type { HermesConnection } from '@/global'
+import { $connection } from '@/store/session'
 
 import {
   getMediaImageDimensions,
@@ -8,9 +9,27 @@ import {
   mediaImageKey,
   rememberMediaImageDimensions,
   rememberMediaImageFailure,
+  resolveMediaDisplaySrc,
   validImageDimensions
 } from './media'
 
+it('reads a remote-owned image through its gateway, never the local file reader', async () => {
+  const readFileDataUrl = vi.fn(async () => 'data:local')
+  const api = vi.fn(async () => ({ dataUrl: 'data:remote' }))
+  vi.stubGlobal('hermesDesktop', { readFileDataUrl, api })
+  // A local foreground must not pull a remote tile's path off this disk.
+  $connection.set({ connectionId: 'local', mode: 'local', profile: 'default' } as HermesConnection)
+
+  try {
+    await expect(resolveMediaDisplaySrc('/srv/out.png', { connectionId: 'remote-1' })).resolves.toBe('data:remote')
+    expect(api).toHaveBeenCalledWith({ connectionId: 'remote-1', path: '/api/fs/read-data-url?path=%2Fsrv%2Fout.png' })
+    expect(readFileDataUrl).toHaveBeenCalledTimes(0)
+  } finally {
+    $connection.set(null)
+    vi.unstubAllGlobals()
+  }
+})
+
 it('shares proven path aliases only within an owner and bounds regenerated metadata by LRU', () => {
   const a = { connectionId: 'a', profile: 'work', mode: 'remote' } as HermesConnection
   const b = { ...a, connectionId: 'b' }

From 6828ffa70f4c715076f1033514463ab1dc75ff5e Mon Sep 17 00:00:00 2001
From: BearHuddleston <bear@bearhuddleston.dev>
Date: Tue, 22 Sep 2026 09:23:09 -0500
Subject: [PATCH 47/61] fix(desktop): persist edit previews before tool-result
 flush

---
 agent/agent_init.py                           |   2 +
 agent/display.py                              |  16 +-
 agent/tool_executor.py                        |  11 ++
 .../tool/inline-edit-persistence.test.tsx     | 175 ++++++++++++++++++
 .../src/lib/chat-messages/tool-parts.ts       |  41 ++--
 apps/desktop/src/types/hermes.ts              |   3 +
 apps/shared/src/gateway-contract.generated.ts |   4 +-
 apps/shared/src/gateway-contract.openrpc.json |  24 ++-
 run_agent.py                                  |   1 +
 tests/agent/test_inline_edit_persistence.py   | 175 ++++++++++++++++++
 tests/tui_gateway/test_tui_gateway_server.py  |   1 +
 tui_gateway/agent_callbacks.py                |   2 +
 tui_gateway/contracts/common.py               |   6 +-
 tui_gateway/session_history.py                |   5 +
 tui_gateway/tool_progress.py                  |  34 +++-
 15 files changed, 466 insertions(+), 34 deletions(-)
 create mode 100644 apps/desktop/src/components/assistant-ui/tool/inline-edit-persistence.test.tsx
 create mode 100644 tests/agent/test_inline_edit_persistence.py

diff --git a/agent/agent_init.py b/agent/agent_init.py
index 7563828d24..9b18a3d9b7 100644
--- a/agent/agent_init.py
+++ b/agent/agent_init.py
@@ -2306,6 +2306,7 @@ _GATEWAY_IDENTITY_PARAMS = (
 )
 _CALLBACK_PARAMS = (
     "tool_progress_callback", "tool_start_callback", "tool_complete_callback",
+    "tool_result_metadata_callback",
     "thinking_callback", "reasoning_callback", "clarify_callback",
     "read_terminal_callback", "read_preview_callback", "drive_preview_callback",
     "read_window_below_callback", "connection_callback", "tour_callback",
@@ -2351,6 +2352,7 @@ def init_agent(
     checkpoint_max_file_size_mb: int = 10, pass_session_id: bool = False,
     requested_provider: str = None, capabilities: Optional[Dict[str, bool]] = None, cwd: Optional[str] = None,
     side_agent: bool = False, memory_manager=None,
+    tool_result_metadata_callback: Optional[Callable[..., dict]] = None,
 ):
     _install_safe_stdio()
 
diff --git a/agent/display.py b/agent/display.py
index 4eace0251d..05c7689d85 100644
--- a/agent/display.py
+++ b/agent/display.py
@@ -643,19 +643,29 @@ def _resolve_skill_manage_paths(args: dict) -> list[Path]:
     return [skill_dir / "SKILL.md"] if action in {"edit", "patch"} else []
 
 
-def _resolve_local_edit_paths(tool_name: str, function_args: dict | None) -> list[Path]:
+def _resolve_local_edit_paths(tool_name: str, function_args: dict | None, task_id: str | None = None) -> list[Path]:
     """Resolve local filesystem targets for write-capable tools."""
     if not isinstance(function_args, dict):
         return []
     if tool_name == "skill_manage":
         return _resolve_skill_manage_paths(function_args)
     path = function_args.get("path") if tool_name in {"write_file", "patch"} else None
+    if path and task_id is not None:
+        from tools.file_tools_paths import _resolve_path_for_task, _terminal_env_type_for_task
+
+        # A remote target may happen to exist on this host too. Never persist a
+        # preview of that unrelated file; patch can still supply its own diff.
+        if _terminal_env_type_for_task(task_id) != "local":
+            return []
+        return [Path(_resolve_path_for_task(path, task_id))]
     return [_resolved_path(path)] if path else []
 
 
-def capture_local_edit_snapshot(tool_name: str, function_args: dict | None) -> LocalEditSnapshot | None:
+def capture_local_edit_snapshot(
+    tool_name: str, function_args: dict | None, *, task_id: str | None = None,
+) -> LocalEditSnapshot | None:
     """Capture before-state for local write previews."""
-    paths = _resolve_local_edit_paths(tool_name, function_args)
+    paths = _resolve_local_edit_paths(tool_name, function_args, task_id)
     if not paths:
         return None
     return LocalEditSnapshot(paths=paths, before={str(path): _snapshot_text(path) for path in paths})
diff --git a/agent/tool_executor.py b/agent/tool_executor.py
index b877a637a4..7265d18a24 100644
--- a/agent/tool_executor.py
+++ b/agent/tool_executor.py
@@ -1098,6 +1098,17 @@ def _commit_tool_result(
     # string-safe fallback so a rejected image result never poisons history.
     _tool_content = agent._tool_result_content_for_active_model(function_name, persisted_result)
     tool_message = make_tool_result_message(function_name, _tool_content, tool_call_id, effect_disposition=effect_disposition)
+    # Prepare presentation data before the append. The emitting completion callback
+    # stays below the durability fence; raw tool/model content remains unchanged.
+    prepare_metadata = getattr(agent, "tool_result_metadata_callback", None)
+    if not blocked and prepare_metadata:
+        try:
+            display_args = _redact_tool_args_for_display(function_name, function_args) or function_args
+            metadata = prepare_metadata(tool_call_id, function_name, display_args, function_result)
+            if metadata:
+                tool_message["display_metadata"] = metadata
+        except Exception as callback_error:
+            logging.debug("Tool result metadata callback error: %s", callback_error)
     messages.append(tool_message)
     if not _flush_session_db_after_tool_progress(agent, messages, stage=f"tool result {function_name}"):
         return None
diff --git a/apps/desktop/src/components/assistant-ui/tool/inline-edit-persistence.test.tsx b/apps/desktop/src/components/assistant-ui/tool/inline-edit-persistence.test.tsx
new file mode 100644
index 0000000000..3d8f2372f9
--- /dev/null
+++ b/apps/desktop/src/components/assistant-ui/tool/inline-edit-persistence.test.tsx
@@ -0,0 +1,175 @@
+import { readFileSync } from 'node:fs'
+
+import { cleanup, render, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, expect, it } from 'vitest'
+
+import { parseAnsi } from '@/lib/ansi'
+import { type ChatMessage, type GatewayEventPayload, toChatMessages, upsertToolPart } from '@/lib/chat-messages'
+import { toRuntimeMessage } from '@/lib/chat-runtime'
+import { getToolDiff } from '@/store/tool-diffs'
+import { $toolDisclosureStates, setHideCodeDiffs, setToolViewMode } from '@/store/tool-view'
+import type { SessionMessage } from '@/types/hermes'
+
+import { stubThreadEnvironment, stubThreadViewportSize, ThreadRuntime } from '../test-utils'
+import { Thread } from '../thread'
+
+stubThreadEnvironment()
+stubThreadViewportSize()
+
+interface Receipt {
+  rows: SessionMessage[]
+  projected: SessionMessage[]
+  completion: GatewayEventPayload
+  changed: boolean
+}
+
+// A self-contained wire-contract fixture. Optionally run this same invariant
+// against receipts produced by test_inline_edit_persistence.py's real tools/DB.
+const diff = "--- a/publish.py\n+++ b/publish.py\n@@ -1 +1 @@\n-print('before')\n+print('after')"
+const result = { success: true, path: 'publish.py', verified: true }
+const metadata = { tool_result_metadata: { inline_diff: diff } }
+
+const tool: SessionMessage = {
+  role: 'tool',
+  name: 'write_file',
+  tool_call_id: 'edit-call',
+  timestamp: 20,
+  content: JSON.stringify(result),
+  display_metadata: metadata
+}
+
+const fixtures: Record<string, Receipt> = {
+  write: {
+    rows: [
+      { role: 'user', content: 'Update the file' },
+      {
+        role: 'assistant',
+        content: '',
+        tool_calls: [
+          {
+            id: tool.tool_call_id,
+            type: 'function',
+            function: { name: tool.name, arguments: '{"path":"publish.py"}' }
+          }
+        ]
+      },
+      tool
+    ],
+    projected: [{ ...tool, args: { path: 'publish.py' }, context: 'publish.py' }],
+    completion: {
+      name: tool.name,
+      tool_id: tool.tool_call_id!,
+      args: { path: 'publish.py' },
+      result,
+      inline_diff: diff
+    },
+    changed: true
+  }
+}
+
+for (const [name, raw] of Object.entries({
+  legacyPatch: { ...result, diff },
+  noop: result,
+  failed: { error: 'Write refused' },
+  falseResult: false,
+  nullResult: null,
+  emptyResult: ''
+})) {
+  const seed = fixtures.write
+
+  fixtures[name] = {
+    rows: seed.rows.map(row =>
+      row.role === 'tool' ? { ...row, content: JSON.stringify(raw), display_metadata: undefined } : row
+    ),
+    projected: seed.projected.map(row => ({ ...row, content: JSON.stringify(raw), display_metadata: undefined })),
+    completion: { ...seed.completion, result: raw, inline_diff: undefined },
+    changed: name === 'legacyPatch'
+  }
+}
+
+const receipts: Record<string, Receipt> = process.env.INLINE_EDIT_RECEIPTS
+  ? JSON.parse(readFileSync(process.env.INLINE_EDIT_RECEIPTS, 'utf8'))
+  : fixtures
+
+beforeEach(() => {
+  expect(getToolDiff('edit-call')).toBe('')
+  $toolDisclosureStates.set({})
+  setHideCodeDiffs(false)
+  setToolViewMode('product')
+})
+afterEach(cleanup)
+
+it.each(Object.entries(receipts))(
+  '%s: cold tool hydration preserves raw results and edit visibility',
+  async (_name, receipt) => {
+    const live: ChatMessage = {
+      id: 'live',
+      role: 'assistant',
+      pending: false,
+      parts: upsertToolPart([], receipt.completion, 'complete')
+    }
+
+    const liveUi = render(
+      <ThreadRuntime messages={[toRuntimeMessage(live)]}>
+        <Thread />
+      </ThreadRuntime>
+    )
+
+    if (receipt.changed) {
+      await waitFor(() => expect(liveUi.container.querySelector('[data-tool-row][data-file-edit]')).not.toBeNull())
+    }
+
+    cleanup()
+
+    // Pending call, already-rendered assistant call, and orphan/RPC projection.
+    const withCommentary = receipt.rows.map(row =>
+      row.role === 'assistant' ? { ...row, content: 'Editing now' } : row
+    )
+
+    for (const rows of [receipt.rows, withCommentary, receipt.projected]) {
+      expect(getToolDiff(receipt.completion.tool_id!)).toBe('')
+
+      for (const serialized of [false, true]) {
+        const history = rows.map(row =>
+          serialized && row.display_metadata ? { ...row, display_metadata: JSON.stringify(row.display_metadata) } : row
+        )
+
+        const cold = toChatMessages(history)
+        const parts = cold.flatMap(message => message.parts).filter(part => part.type === 'tool-call')
+
+        expect(parts).toHaveLength(1)
+        expect(parts[0].toolCallId).toBe(receipt.completion.tool_id)
+        expect(parts[0].result).toEqual(receipt.completion.result)
+        expect(parts[0].toolResultMetadata?.inline_diff).toBe(receipt.completion.inline_diff)
+
+        const ui = render(
+          <ThreadRuntime messages={cold.map(toRuntimeMessage)}>
+            <Thread />
+          </ThreadRuntime>
+        )
+
+        await waitFor(() => {
+          expect(Boolean(ui.container.querySelector('[data-tool-row][data-file-edit]'))).toBe(receipt.changed)
+        })
+
+        if (receipt.changed) {
+          expect(ui.container.textContent).toContain('publish.py')
+          expect(ui.container.textContent).not.toContain('unrelated later edit')
+
+          const diffLines = receipt.completion.inline_diff ?? (receipt.completion.result as { diff: string }).diff
+
+          const addition = parseAnsi(diffLines)
+            .map(segment => segment.text)
+            .join('')
+            .split('\n')
+            .find(line => line.includes('+print('))
+
+          expect(addition).toBeDefined()
+          expect(ui.container.textContent).toContain(addition!.slice(1))
+        }
+
+        cleanup()
+      }
+    }
+  }
+)
diff --git a/apps/desktop/src/lib/chat-messages/tool-parts.ts b/apps/desktop/src/lib/chat-messages/tool-parts.ts
index 0b86cbed26..5c698ad324 100644
--- a/apps/desktop/src/lib/chat-messages/tool-parts.ts
+++ b/apps/desktop/src/lib/chat-messages/tool-parts.ts
@@ -755,6 +755,10 @@ export function textFromUnknown(value: unknown, depth = 0): string {
 }
 
 function parseStoredToolResult(content: unknown): unknown {
+  if (content === null) {
+    return null
+  }
+
   if (content && typeof content === 'object') {
     return content
   }
@@ -801,11 +805,14 @@ export function toolPartFromStoredCall(
   }
 }
 
-export function applyStoredToolResult(messages: ChatMessage[], toolMessage: SessionMessage): boolean {
-  const toolCallId = toolMessage.tool_call_id || undefined
-  const toolName = toolMessage.tool_name || toolMessage.name || 'tool'
-  const content = toolMessage.content || toolMessage.text || toolMessage.context || toolMessage.name
+function storedToolResultMetadata(toolMessage: SessionMessage): ToolResultMetadata | undefined {
+  const display = parseMaybeJsonObject(toolMessage.display_metadata)
+  const metadata = parseMaybeJsonObject(display.tool_result_metadata)
 
+  return typeof metadata.inline_diff === 'string' ? { inline_diff: metadata.inline_diff } : undefined
+}
+
+export function applyStoredToolResult(messages: ChatMessage[], toolMessage: SessionMessage): boolean {
   for (let i = messages.length - 1; i >= 0; i -= 1) {
     const message = messages[i]
 
@@ -813,24 +820,12 @@ export function applyStoredToolResult(messages: ChatMessage[], toolMessage: Sess
       continue
     }
 
-    const partIndex = message.parts.findIndex(
-      part =>
-        part.type === 'tool-call' &&
-        ((toolCallId && part.toolCallId === toolCallId) || (!toolCallId && part.toolName === toolName))
-    )
+    const parts = applyStoredToolResultToParts(message.parts, toolMessage)
 
-    if (partIndex < 0) {
+    if (!parts) {
       continue
     }
 
-    const parts = [...message.parts]
-    const existing = parts[partIndex]
-    parts[partIndex] = {
-      ...existing,
-      completedAt: toolMessage.timestamp,
-      result: parseStoredToolResult(content),
-      isError: false
-    } as ChatMessagePart
     messages[i] = { ...message, parts, serverRowSpan: (message.serverRowSpan ?? 1) + 1 }
 
     return true
@@ -845,7 +840,11 @@ export function applyStoredToolResultToParts(
 ): ChatMessagePart[] | null {
   const toolCallId = toolMessage.tool_call_id || undefined
   const toolName = toolMessage.tool_name || toolMessage.name || 'tool'
-  const content = toolMessage.content || toolMessage.text || toolMessage.context || toolMessage.name
+
+  const content =
+    toolMessage.content !== undefined
+      ? toolMessage.content
+      : (toolMessage.text ?? toolMessage.context ?? toolMessage.name)
 
   const partIndex = parts.findIndex(
     part =>
@@ -863,6 +862,7 @@ export function applyStoredToolResultToParts(
     ...existing,
     completedAt: toolMessage.timestamp,
     result: parseStoredToolResult(content),
+    toolResultMetadata: storedToolResultMetadata(toolMessage),
     isError: false
   } as ChatMessagePart
 
@@ -888,7 +888,8 @@ export function storedToolMessagePart(toolMessage: SessionMessage, fallbackIndex
     argsText: Object.keys(args).length ? JSON.stringify(args) : '',
     timestamp: toolMessage.timestamp,
     completedAt: toolMessage.timestamp,
-    result: context ? { context } : {},
+    result: toolMessage.content !== undefined ? parseStoredToolResult(toolMessage.content) : context ? { context } : {},
+    toolResultMetadata: storedToolResultMetadata(toolMessage),
     isError: false
   }
 }
diff --git a/apps/desktop/src/types/hermes.ts b/apps/desktop/src/types/hermes.ts
index 6a91ec97de..dbb9d799c7 100644
--- a/apps/desktop/src/types/hermes.ts
+++ b/apps/desktop/src/types/hermes.ts
@@ -1,5 +1,7 @@
 import type { ConnectionRequestPayload, ToolLabel } from '@hermes/shared'
 
+import type { ToolResultMetadata } from '@/lib/tool-result-metadata'
+
 export type StoredToolCallLabels = Record<string, ToolLabel[]>
 
 export interface ConfigFieldSchema {
@@ -603,6 +605,7 @@ export type TimelineDisplayMetadata =
     }
   | { display_text: string }
   | { reactions: MessageReaction[] }
+  | { tool_result_metadata: ToolResultMetadata }
 
 /** One emoji reaction on a message. One per author, iOS-Tapback style. */
 export interface MessageReaction {
diff --git a/apps/shared/src/gateway-contract.generated.ts b/apps/shared/src/gateway-contract.generated.ts
index fd32bc2ce7..434ad9f2e4 100644
--- a/apps/shared/src/gateway-contract.generated.ts
+++ b/apps/shared/src/gateway-contract.generated.ts
@@ -2788,10 +2788,12 @@ export interface SessionCreateResult {
   messages: TranscriptMessage[]
   info: SessionLiveInfo
 }
-/** One transcript row as the gateway PROJECTS it for renderers (``session_history._project_history``): ``text`` (never ``content``), display-only ``timestamp`` / ``display_kind`` / ``display_metadata``, the durable ``row_id`` rewind targets, and for tool rows ``name`` + ``context`` preview + full ``args``. Assistant detail sidecars (``reasoning``, …) ride as extra keys. */
+/** One transcript row as the gateway PROJECTS it for renderers (``session_history._project_history``): ``text``, display-only ``timestamp`` / ``display_kind`` / ``display_metadata``, the durable ``row_id`` rewind targets, and for tool rows raw ``content``, ``tool_call_id``, ``name``, ``context`` and ``args``. Assistant detail sidecars (``reasoning``, …) ride as extra keys. */
 export interface TranscriptMessage {
   role: string
   text?: string | null
+  content?: unknown | null
+  tool_call_id?: string | null
   timestamp?: number | null
   row_id?: number | null
   display_kind?: string | null
diff --git a/apps/shared/src/gateway-contract.openrpc.json b/apps/shared/src/gateway-contract.openrpc.json
index a2dfa94aad..8d8f8a0698 100644
--- a/apps/shared/src/gateway-contract.openrpc.json
+++ b/apps/shared/src/gateway-contract.openrpc.json
@@ -34672,7 +34672,7 @@
       },
       "TranscriptMessage": {
         "additionalProperties": true,
-        "description": "One transcript row as the gateway PROJECTS it for renderers (``session_history._project_history``):\n``text`` (never ``content``), display-only ``timestamp`` / ``display_kind`` / ``display_metadata``, the\ndurable ``row_id`` rewind targets, and for tool rows ``name`` + ``context`` preview + full ``args``.\nAssistant detail sidecars (``reasoning``, \u2026) ride as extra keys.",
+        "description": "One transcript row as the gateway PROJECTS it for renderers (``session_history._project_history``):\n``text``, display-only ``timestamp`` / ``display_kind`` / ``display_metadata``, the durable ``row_id``\nrewind targets, and for tool rows raw ``content``, ``tool_call_id``, ``name``, ``context`` and ``args``.\nAssistant detail sidecars (``reasoning``, \u2026) ride as extra keys.",
         "properties": {
           "role": {
             "title": "Role",
@@ -34690,6 +34690,28 @@
             "default": null,
             "title": "Text"
           },
+          "content": {
+            "anyOf": [
+              {},
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "title": "Content"
+          },
+          "tool_call_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "title": "Tool Call Id"
+          },
           "timestamp": {
             "anyOf": [
               {
diff --git a/run_agent.py b/run_agent.py
index bb01bfa06f..83f121f968 100644
--- a/run_agent.py
+++ b/run_agent.py
@@ -299,6 +299,7 @@ class AIAgent(
         pass_session_id: bool = False, requested_provider: str = None,
         capabilities: Dict[str, bool] | None = None, cwd: str | None = None,
         side_agent: bool = False, memory_manager=None,
+        tool_result_metadata_callback: Optional[Callable[..., dict]] = None,
     ):
         """Forwarder — see ``agent.agent_init.init_agent`` (same keyword parameters, minus ``tool_delay``)."""
         init_kwargs = {k: v for k, v in locals().items() if k not in ("self", "tool_delay")}
diff --git a/tests/agent/test_inline_edit_persistence.py b/tests/agent/test_inline_edit_persistence.py
new file mode 100644
index 0000000000..2398c3ea7b
--- /dev/null
+++ b/tests/agent/test_inline_edit_persistence.py
@@ -0,0 +1,175 @@
+"""Real edit -> executor -> SQLite -> history projection, without model calls.
+
+The module receipt lives in pytest's temporary root for optional cross-runtime
+renderer verification; the regression itself needs no pre-existing artifacts.
+"""
+import copy
+import contextlib
+import json
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from tests.agent.test_tool_call_incremental_persistence import (
+    _attach_real_session_db,
+    _make_agent,
+    _mock_tool_call,
+)
+
+
+@pytest.fixture(scope="module")
+def receipts(tmp_path_factory):
+    records = {}
+    yield records
+    path = tmp_path_factory.getbasetemp() / "inline-edit-receipts.json"
+    path.write_text(json.dumps(records, indent=2), encoding="utf-8")
+    print(f"INLINE_EDIT_RECEIPTS={path}")
+
+
+@pytest.mark.parametrize("executor_mode", ["sequential", "concurrent"])
+@pytest.mark.parametrize("edit", ["create", "replace", "patch", "noop", "failed"])
+def test_edit_preview_is_durable_before_emission_and_display_only(
+    tmp_path, monkeypatch, executor_mode, edit, receipts,
+):
+    from agent.context_compressor import ContextCompressor
+    from agent import secret_scope
+    from agent.turn_context import build_api_messages
+    from hermes_state import SessionDB
+    from tools.environments.local import LocalEnvironment
+    from tools.file_operations import ShellFileOperations
+    from tools.terminal_tool import register_task_env_overrides, clear_task_env_overrides
+    import tools.file_tools as file_tools
+    import model_tools
+    import tui_gateway.server as progress
+
+    assert Path(model_tools.__file__).resolve().parent == Path(__file__).resolve().parents[2]
+    monkeypatch.setattr(secret_scope, "_MULTIPLEX_ACTIVE", True)
+    monkeypatch.setattr("agent.title_generator.maybe_auto_title", lambda *a, **kw: None)
+    # Deliberately different from the execution cwd: relative previews must use
+    # the same task target as the real file tool, not today's process directory.
+    process_cwd = tmp_path / "process"
+    process_cwd.mkdir()
+    monkeypatch.chdir(process_cwd)
+    emitted = []
+    at_emission = []
+    monkeypatch.setattr(progress, "_emit_tool_lifecycle", lambda *a: emitted.append(a))
+    homes = {tag: tmp_path / tag for tag in ("alpha", "beta")}
+    for home in homes.values():
+        home.mkdir()
+        (home / "config.yaml").write_text("terminal:\n  backend: local\n", encoding="utf-8")
+
+    # Same tool identity reused in separate homes: no process-global diff cache.
+    for visit, tag in enumerate(("alpha", "beta", "alpha")):
+        home = homes[tag]
+        scope = contextlib.ExitStack()
+        scope.enter_context(progress._session_profile_runtime_scope({"profile_home": str(home)}, hydrate_secrets=False))
+        work = home / f"work-{visit}"
+        work.mkdir()
+        env = LocalEnvironment(cwd=str(work), timeout=15)
+        ops = ShellFileOperations(env, cwd=str(work))
+        monkeypatch.setattr(file_tools, "_get_file_ops", lambda task_id="default": ops)
+        path = work / "publish.py"
+        before, after = "print('before')\n", f"print('{tag}-{visit}')\n"
+        tool_name = "patch" if edit == "patch" else "write_file"
+        if edit != "create":
+            path.write_text(before, encoding="utf-8")
+        args = {"path": "publish.py", "content": before if edit == "noop" else after}
+        if edit == "patch":
+            args = {"path": "publish.py", "old_string": before.strip(), "new_string": after.strip()}
+        name = f"{executor_mode}-{edit}-{tag}-{visit}"
+        call_id = "edit-call"
+        agent = _make_agent()
+        agent.valid_tool_names = {tool_name}
+        db_path = home / "state.db"
+        db = _attach_real_session_db(agent, db_path, name)
+        register_task_env_overrides(name, {"cwd": str(work), "env_type": "local"})
+        monkeypatch.setitem(progress._sessions, name, {"agent": agent, "session_key": name})
+        # Wire the real gateway callbacks, including pre-commit preparation.
+        for key, callback in progress._agent_cbs(name).items():
+            setattr(agent, key, callback)
+        if edit in {"replace", "noop"}:
+            file_tools.read_file_tool("publish.py", task_id=name)
+        messages = [
+            {"role": "user", "content": "Update the file"},
+            {"role": "assistant", "content": "", "tool_calls": [{
+                "id": call_id, "type": "function", "function": {
+                    "name": tool_name, "arguments": json.dumps(args),
+                },
+            }]},
+        ]
+        agent._flush_messages_to_session_db(messages)
+        emitted.clear()
+        at_emission.clear()
+
+        def emit(kind, sid, name, args, payload):
+            emitted.append((kind, copy.deepcopy(payload)))
+            if kind == "tool.complete":
+                with SessionDB(db_path=db_path) as cold:
+                    at_emission.extend(cold.get_messages(sid))
+
+        monkeypatch.setattr(progress, "_emit_tool_lifecycle", emit)
+        try:
+            call = _mock_tool_call(tool_name, json.dumps(args), call_id)
+            getattr(agent, f"_execute_tool_calls_{executor_mode}")(
+                SimpleNamespace(tool_calls=[call]), messages, name,
+            )
+            completion = next(payload for kind, payload in emitted if kind == "tool.complete")
+            row = next(row for row in at_emission if row["role"] == "tool")
+            raw = json.loads(row["content"])
+            assert raw == completion["result"]
+            assert "inline_diff" not in raw
+            changed = edit not in {"noop", "failed"}
+            assert path.read_text(encoding="utf-8") == (after if changed else before)
+            assert bool(raw.get("error")) == (edit == "failed")
+            metadata = (row.get("display_metadata") or {}).get("tool_result_metadata") or {}
+            # This assertion was red on base: completion saw no persisted sidecar.
+            assert bool(metadata.get("inline_diff")) == changed
+            assert metadata.get("inline_diff") == completion.get("inline_diff")
+            if changed:
+                assert after.strip() in metadata["inline_diff"]
+            with SessionDB(db_path=db_path) as cold:
+                rows = cold.get_messages(name)
+                conversation = cold.get_messages_as_conversation(name)
+            projected = progress._history_to_messages(conversation)
+            projected_tool = next(row for row in projected if row["role"] == "tool")
+            assert projected_tool["tool_call_id"] == call_id
+            assert projected_tool["content"] == row["content"]
+            assert projected_tool.get("display_metadata") == row.get("display_metadata")
+            assert projected_tool["timestamp"] == row["timestamp"]
+
+            # Preparation never modifies provider bytes or the cached prefix.
+            agent._current_turn_timestamp = 1.0
+            frozen = copy.deepcopy(messages)
+            def wire(history):
+                return build_api_messages(
+                    agent, history, current_turn_user_idx=0, ext_prefetch_cache="",
+                    plugin_user_context="", moa_config=None, active_system_prompt="fixed prefix",
+                )
+            without_display = [{k: v for k, v in m.items() if k != "display_metadata"} for m in messages]
+            assert wire(messages) == wire(without_display)
+            before_next_turn = wire(messages)
+            assert wire(messages + [{"role": "user", "content": "Continue"}])[0][:-1] == before_next_turn[0]
+            assert messages == frozen
+
+            # Cold display does not reread the now-changed target. Exercise real
+            # compaction demotion + DB archival, preserving the original tool row.
+            path.write_text("print('unrelated later edit')\n", encoding="utf-8")
+            compacted = copy.deepcopy(conversation)
+            tool_index = next(i for i, m in enumerate(compacted) if m["role"] == "tool")
+            assert ContextCompressor._demote_tool_result_at(
+                compacted, tool_index, {call_id: (tool_name, json.dumps(args))}, 0,
+            )
+            assert compacted[tool_index].get("display_metadata") == row.get("display_metadata")
+            db.archive_and_compact(name, compacted)
+            with SessionDB(db_path=db_path) as cold:
+                archived = cold.get_messages(name, include_compacted=True)
+                active = cold.get_messages_as_conversation(name)
+            assert next(m for m in archived if m["id"] == row["id"])["content"] == row["content"]
+            assert next(m for m in active if m["role"] == "tool").get("display_metadata") == row.get("display_metadata")
+            receipts[name] = {"rows": rows, "projected": projected, "completion": completion, "changed": changed}
+        finally:
+            clear_task_env_overrides(name)
+            db.close()
+            env.cleanup()
+            scope.close()
diff --git a/tests/tui_gateway/test_tui_gateway_server.py b/tests/tui_gateway/test_tui_gateway_server.py
index 846a4828bd..ea79989614 100644
--- a/tests/tui_gateway/test_tui_gateway_server.py
+++ b/tests/tui_gateway/test_tui_gateway_server.py
@@ -2512,6 +2512,7 @@ def test_history_to_messages_preserves_tool_calls_for_resume_display():
             "context": "resume",
             "name": "search_files",
             "role": "tool",
+            "tool_call_id": history[2]["tool_call_id"],
         },
         {"role": "assistant", "text": "first answer"},
         {"role": "user", "text": "second prompt"},
diff --git a/tui_gateway/agent_callbacks.py b/tui_gateway/agent_callbacks.py
index 96ef84db68..115862386b 100644
--- a/tui_gateway/agent_callbacks.py
+++ b/tui_gateway/agent_callbacks.py
@@ -127,6 +127,8 @@ def _agent_cbs(sid: str) -> dict:
     callbacks = {
         "tool_start_callback": lambda tc_id, name, args: _on_tool_start(sid, tc_id, name, args),
         "tool_complete_callback": lambda tc_id, name, args, result: _on_tool_complete(sid, tc_id, name, args, result),
+        "tool_result_metadata_callback": lambda tc_id, name, args, result: _prepare_tool_result_metadata(
+            sid, tc_id, name, args, result),
         "tool_progress_callback": lambda event_type, name=None, preview=None, args=None, **kwargs: _on_tool_progress(
             sid, event_type, name, preview, args, **kwargs),
         "tool_gen_callback": lambda name: _tool_progress_enabled(sid) and _emit("tool.generating", sid, {"name": name}),
diff --git a/tui_gateway/contracts/common.py b/tui_gateway/contracts/common.py
index 3351a79625..434697873b 100644
--- a/tui_gateway/contracts/common.py
+++ b/tui_gateway/contracts/common.py
@@ -154,12 +154,14 @@ class ToolLabel(Payload):
 
 class TranscriptMessage(OpenModel):
     """One transcript row as the gateway PROJECTS it for renderers (``session_history._project_history``):
-    ``text`` (never ``content``), display-only ``timestamp`` / ``display_kind`` / ``display_metadata``, the
-    durable ``row_id`` rewind targets, and for tool rows ``name`` + ``context`` preview + full ``args``.
+    ``text``, display-only ``timestamp`` / ``display_kind`` / ``display_metadata``, the durable ``row_id``
+    rewind targets, and for tool rows raw ``content``, ``tool_call_id``, ``name``, ``context`` and ``args``.
     Assistant detail sidecars (``reasoning``, …) ride as extra keys."""
 
     role: str
     text: str | None = None
+    content: JsonValue | None = None
+    tool_call_id: str | None = None
     timestamp: float | None = None
     row_id: int | None = None
     display_kind: str | None = None
diff --git a/tui_gateway/session_history.py b/tui_gateway/session_history.py
index e322c24e20..27cd98efc4 100644
--- a/tui_gateway/session_history.py
+++ b/tui_gateway/session_history.py
@@ -237,6 +237,11 @@ def _history_to_messages(history: list[dict], *, profile_home=None) -> list[dict
             # `context` is an 80-char preview; ship args so a full-call renderer isn't truncated.
             labels = _bridged_tool_labels(name, args)
             messages.append({"role": "tool", "name": name, "context": _tool_ctx(name, args),
+                             # Edit cards need the original result; other tool outputs
+                             # remain omitted from this compact display projection.
+                             **({"content": m.get("content")} if name in {"write_file", "patch", "skill_manage"} else {}),
+                             **{key: m[key] for key in ("tool_call_id", "timestamp", "display_metadata")
+                                if m.get(key) is not None},
                              **({"args": args} if args else {}), **({"labels": labels} if labels else {})})
             continue
         # Assistant detail sidecars can carry the only visible reply or reasoning after resume/reload.
diff --git a/tui_gateway/tool_progress.py b/tui_gateway/tool_progress.py
index 3c8efff65c..fe2d1a55f6 100644
--- a/tui_gateway/tool_progress.py
+++ b/tui_gateway/tool_progress.py
@@ -242,7 +242,8 @@ def _on_tool_start(sid: str, tool_call_id: str, name: str, args: dict):
     if session is not None:
         with contextlib.suppress(Exception):
             from agent.display import capture_local_edit_snapshot
-            snapshot = capture_local_edit_snapshot(name, args)
+            task_id = session.get("session_key") or getattr(session.get("agent"), "session_id", None) or sid
+            snapshot = capture_local_edit_snapshot(name, args, task_id=task_id)
             if snapshot is not None:
                 session.setdefault("edit_snapshots", {})[tool_call_id] = snapshot
         session.setdefault("tool_started_at", {})[tool_call_id] = time.time()
@@ -260,6 +261,25 @@ def _on_tool_start(sid: str, tool_call_id: str, name: str, args: dict):
         _emit_tool_lifecycle("tool.start", sid, name, args, payload)
 
 
+def _prepare_tool_result_metadata(sid: str, tool_call_id: str, name: str, args: dict, result: str) -> dict:
+    """Non-emitting preview preparation for the canonical tool-result append.
+
+    Retain the exact preview for the post-flush event, including an empty preview
+    for failed/no-op edits. A cold client reads the same sidecar from SQLite.
+    """
+    session = _sessions.get(sid)
+    snapshot = session.setdefault("edit_snapshots", {}).pop(tool_call_id, None) if session is not None else None
+    metadata = {}
+    with contextlib.suppress(Exception):
+        from agent.display import render_edit_diff_with_delta
+        rendered: list[str] = []
+        if render_edit_diff_with_delta(name, result, function_args=args, snapshot=snapshot, print_fn=rendered.append):
+            metadata["inline_diff"] = "\n".join(rendered)
+    if session is not None:
+        session.setdefault("tool_result_metadata", {})[tool_call_id] = metadata
+    return {"tool_result_metadata": metadata} if metadata else {}
+
+
 def _on_tool_complete(sid: str, tool_call_id: str, name: str, args: dict, result: str):
     if _connector_lifecycle_is_stale(sid, name, args):
         return
@@ -267,7 +287,12 @@ def _on_tool_complete(sid: str, tool_call_id: str, name: str, args: dict, result
     if (labels := _tool_labels(name, args)) is not None:
         payload["labels"] = labels
     session = _sessions.get(sid)
-    snapshot = session.setdefault("edit_snapshots", {}).pop(tool_call_id, None) if session is not None else None
+    prepared = session.setdefault("tool_result_metadata", {}) if session is not None else {}
+    if tool_call_id not in prepared:
+        # Native runtimes may emit lifecycle callbacks without the tool executor.
+        metadata = _prepare_tool_result_metadata(sid, tool_call_id, name, args, result)
+        payload.update(metadata.get("tool_result_metadata", {}))
+    payload.update(prepared.pop(tool_call_id, {}))
     started_at = session.setdefault("tool_started_at", {}).pop(tool_call_id, None) if session is not None else None
     duration_s = time.time() - started_at if started_at else None
     if duration_s is not None:
@@ -286,11 +311,6 @@ def _on_tool_complete(sid: str, tool_call_id: str, name: str, args: dict, result
         payload.update(todo_state)
         if session is not None:
             _cache_todo_state(session, todo_state)
-    with contextlib.suppress(Exception):
-        from agent.display import render_edit_diff_with_delta
-        rendered: list[str] = []
-        if render_edit_diff_with_delta(name, result, function_args=args, snapshot=snapshot, print_fn=rendered.append):
-            payload["inline_diff"] = "\n".join(rendered)
     if (_tool_progress_enabled(sid) or payload.get("inline_diff") or _tool_lifecycle_required_for_ui(name)
             or name in _TODO_TOOL_NAMES or _connector_tool_lifecycle(name, args)):
         _emit_tool_lifecycle("tool.complete", sid, name, args, payload)

From caf1c3846639dceca365de9ae2650ce348e9b197 Mon Sep 17 00:00:00 2001
From: BearHuddleston <bear@bearhuddleston.dev>
Date: Tue, 22 Sep 2026 17:55:56 -0500
Subject: [PATCH 48/61] fix(desktop): only an unresolved tool part claims a
 stored result

Tool-call ids repeat across turns, so a later orphan result with a
reused id could overwrite an older completed card during hydration.
Match only parts without a result property (falsy results count as
completed).
---
 .../tool/inline-edit-persistence.test.tsx     | 49 +++++++++++++++++++
 .../src/lib/chat-messages/tool-parts.ts       |  4 ++
 2 files changed, 53 insertions(+)

diff --git a/apps/desktop/src/components/assistant-ui/tool/inline-edit-persistence.test.tsx b/apps/desktop/src/components/assistant-ui/tool/inline-edit-persistence.test.tsx
index 3d8f2372f9..50104a3862 100644
--- a/apps/desktop/src/components/assistant-ui/tool/inline-edit-persistence.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/tool/inline-edit-persistence.test.tsx
@@ -173,3 +173,52 @@ it.each(Object.entries(receipts))(
     }
   }
 )
+
+it.each([
+  ['object', JSON.stringify({ ok: true })],
+  ['false', 'false'],
+  ['null', 'null'],
+  ['empty-string', '""'],
+  ['zero', '0']
+])('does not let a completed %s result claim a later orphan with a reused id', (_name, firstContent) => {
+  const rows: SessionMessage[] = [
+    { role: 'user', content: 'Read first' },
+    {
+      role: 'assistant',
+      content: '',
+      tool_calls: [
+        {
+          id: 'reused-call',
+          type: 'function',
+          function: { name: 'read_file', arguments: '{"path":"read.py"}' }
+        }
+      ]
+    },
+    {
+      role: 'tool',
+      tool_call_id: 'reused-call',
+      tool_name: 'read_file',
+      content: firstContent,
+      timestamp: 2
+    },
+    { role: 'user', content: 'Write next' },
+    {
+      role: 'tool',
+      name: 'write_file',
+      tool_call_id: 'reused-call',
+      args: { path: 'write.py' },
+      content: JSON.stringify({ success: true, path: 'write.py' }),
+      display_metadata: { tool_result_metadata: { inline_diff: diff } },
+      timestamp: 4
+    }
+  ]
+
+  const parts = toChatMessages(rows)
+    .flatMap(message => message.parts)
+    .filter(part => part.type === 'tool-call')
+
+  expect(parts.map(part => part.toolName)).toEqual(['read_file', 'write_file'])
+  expect(parts[0].result).toEqual(JSON.parse(firstContent))
+  expect(parts[1].result).toEqual({ success: true, path: 'write.py' })
+  expect(parts[1].toolResultMetadata?.inline_diff).toBe(diff)
+})
diff --git a/apps/desktop/src/lib/chat-messages/tool-parts.ts b/apps/desktop/src/lib/chat-messages/tool-parts.ts
index 5c698ad324..2ab4b77ebf 100644
--- a/apps/desktop/src/lib/chat-messages/tool-parts.ts
+++ b/apps/desktop/src/lib/chat-messages/tool-parts.ts
@@ -846,9 +846,13 @@ export function applyStoredToolResultToParts(
       ? toolMessage.content
       : (toolMessage.text ?? toolMessage.context ?? toolMessage.name)
 
+  // Tool-call ids are not unique across turns (llama.cpp/Hermes reuse them),
+  // so only an unresolved part may own a stored result. Property presence,
+  // not truthiness: `false`/`null`/`''`/`0` are completed results too.
   const partIndex = parts.findIndex(
     part =>
       part.type === 'tool-call' &&
+      !Object.hasOwn(part, 'result') &&
       ((toolCallId && part.toolCallId === toolCallId) || (!toolCallId && part.toolName === toolName))
   )
 

From 9579930da09a99c28bfae521dbe4235b7e1a78e5 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:42:57 -0700
Subject: [PATCH 49/61] fix: consume prepared edit previews on every completion
 path

The pre-flush preview sidecar (session["tool_result_metadata"]) is stored
for every executor tool call and was only popped by a non-stale
tool.complete. Two paths skipped that pop: a connector completion dropped
as stale returned first, and a failed session-db flush returns before the
completion callback fires at all. The leftover entry then attached to the
next call reusing the same id (llama.cpp and similar local servers reuse
ids like call_0), rendering the old diff on an unrelated tool row.

Pop the entry before the stale return, and clear any orphan for a call id
when that id starts again.
---
 tui_gateway/tool_progress.py | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/tui_gateway/tool_progress.py b/tui_gateway/tool_progress.py
index fe2d1a55f6..c2d60b2107 100644
--- a/tui_gateway/tool_progress.py
+++ b/tui_gateway/tool_progress.py
@@ -247,6 +247,9 @@ def _on_tool_start(sid: str, tool_call_id: str, name: str, args: dict):
             if snapshot is not None:
                 session.setdefault("edit_snapshots", {})[tool_call_id] = snapshot
         session.setdefault("tool_started_at", {})[tool_call_id] = time.time()
+        # A preview prepared for an earlier call whose completion never fired (failed
+        # flush) must not attach to a provider that reuses the same call id.
+        session.setdefault("tool_result_metadata", {}).pop(tool_call_id, None)
     if (_tool_progress_enabled(sid) or _tool_lifecycle_required_for_ui(name)
             or _connector_tool_lifecycle(name, args)):
         payload: dict[str, object] = {"tool_id": tool_call_id, "name": name, "context": _tool_ctx(name, args)}
@@ -281,18 +284,20 @@ def _prepare_tool_result_metadata(sid: str, tool_call_id: str, name: str, args:
 
 
 def _on_tool_complete(sid: str, tool_call_id: str, name: str, args: dict, result: str):
+    session = _sessions.get(sid)
+    prepared = session.setdefault("tool_result_metadata", {}) if session is not None else {}
+    # Consume the pre-flush preview even when this completion is dropped as stale.
+    metadata = prepared.pop(tool_call_id, None)
     if _connector_lifecycle_is_stale(sid, name, args):
         return
     payload = {"tool_id": tool_call_id, "name": name, "args": args}
     if (labels := _tool_labels(name, args)) is not None:
         payload["labels"] = labels
-    session = _sessions.get(sid)
-    prepared = session.setdefault("tool_result_metadata", {}) if session is not None else {}
-    if tool_call_id not in prepared:
+    if metadata is None:
         # Native runtimes may emit lifecycle callbacks without the tool executor.
-        metadata = _prepare_tool_result_metadata(sid, tool_call_id, name, args, result)
-        payload.update(metadata.get("tool_result_metadata", {}))
-    payload.update(prepared.pop(tool_call_id, {}))
+        metadata = _prepare_tool_result_metadata(sid, tool_call_id, name, args, result).get("tool_result_metadata", {})
+        prepared.pop(tool_call_id, None)
+    payload.update(metadata)
     started_at = session.setdefault("tool_started_at", {}).pop(tool_call_id, None) if session is not None else None
     duration_s = time.time() - started_at if started_at else None
     if duration_s is not None:

From f27a0a937dd1059cb6a987ec1f30286b14594b35 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:42:58 -0700
Subject: [PATCH 50/61] test: trim salvage tests to invariants

Drop the module-scoped "receipts" fixture: it only wrote a JSON dump for
optional out-of-band renderer checks that nothing consumes, so it was test
scaffolding without an assertion. Add the reused-call-id invariant for the
preview sidecar cleanup (red on the salvaged head, green with the fix).
---
 tests/agent/test_inline_edit_persistence.py | 39 ++++++++++++---------
 1 file changed, 22 insertions(+), 17 deletions(-)

diff --git a/tests/agent/test_inline_edit_persistence.py b/tests/agent/test_inline_edit_persistence.py
index 2398c3ea7b..5b80f1f374 100644
--- a/tests/agent/test_inline_edit_persistence.py
+++ b/tests/agent/test_inline_edit_persistence.py
@@ -1,8 +1,4 @@
-"""Real edit -> executor -> SQLite -> history projection, without model calls.
-
-The module receipt lives in pytest's temporary root for optional cross-runtime
-renderer verification; the regression itself needs no pre-existing artifacts.
-"""
+"""Real edit -> executor -> SQLite -> history projection, without model calls."""
 import copy
 import contextlib
 import json
@@ -18,19 +14,10 @@ from tests.agent.test_tool_call_incremental_persistence import (
 )
 
 
-@pytest.fixture(scope="module")
-def receipts(tmp_path_factory):
-    records = {}
-    yield records
-    path = tmp_path_factory.getbasetemp() / "inline-edit-receipts.json"
-    path.write_text(json.dumps(records, indent=2), encoding="utf-8")
-    print(f"INLINE_EDIT_RECEIPTS={path}")
-
-
 @pytest.mark.parametrize("executor_mode", ["sequential", "concurrent"])
 @pytest.mark.parametrize("edit", ["create", "replace", "patch", "noop", "failed"])
 def test_edit_preview_is_durable_before_emission_and_display_only(
-    tmp_path, monkeypatch, executor_mode, edit, receipts,
+    tmp_path, monkeypatch, executor_mode, edit,
 ):
     from agent.context_compressor import ContextCompressor
     from agent import secret_scope
@@ -129,7 +116,6 @@ def test_edit_preview_is_durable_before_emission_and_display_only(
             if changed:
                 assert after.strip() in metadata["inline_diff"]
             with SessionDB(db_path=db_path) as cold:
-                rows = cold.get_messages(name)
                 conversation = cold.get_messages_as_conversation(name)
             projected = progress._history_to_messages(conversation)
             projected_tool = next(row for row in projected if row["role"] == "tool")
@@ -167,9 +153,28 @@ def test_edit_preview_is_durable_before_emission_and_display_only(
                 active = cold.get_messages_as_conversation(name)
             assert next(m for m in archived if m["id"] == row["id"])["content"] == row["content"]
             assert next(m for m in active if m["role"] == "tool").get("display_metadata") == row.get("display_metadata")
-            receipts[name] = {"rows": rows, "projected": projected, "completion": completion, "changed": changed}
         finally:
             clear_task_env_overrides(name)
             db.close()
             env.cleanup()
             scope.close()
+
+
+def test_orphaned_preview_never_attaches_to_a_reused_call_id(monkeypatch):
+    import tui_gateway.server as progress
+
+    emitted = []
+    monkeypatch.setattr(progress, "_emit_tool_lifecycle", lambda kind, sid, name, args, payload: emitted.append(payload))
+    session = {"tool_result_metadata": {"call_0": {"inline_diff": "STALE"}}}
+    monkeypatch.setitem(progress._sessions, "reuse", session)
+    # The prepared call's flush failed, so its completion never fired; a later call reuses the id.
+    progress._on_tool_start("reuse", "call_0", "todo", {})
+    progress._on_tool_complete("reuse", "call_0", "todo", {}, '{"todos": []}')
+    assert emitted and not any("inline_diff" in payload for payload in emitted)
+    assert session["tool_result_metadata"] == {}
+
+    # A completion dropped as stale still consumes its prepared entry.
+    session["tool_result_metadata"]["call_1"] = {}
+    monkeypatch.setattr(progress, "_connector_lifecycle_is_stale", lambda *a: True)
+    progress._on_tool_complete("reuse", "call_1", "todo", {}, "{}")
+    assert session["tool_result_metadata"] == {}

From 444066b82ce6027d5cc4018ebec29e083570bb68 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:37:51 -0700
Subject: [PATCH 51/61] fix: exclude display-only message fields from token
 estimates

Edit tool rows now carry display_metadata.tool_result_metadata.inline_diff
(~9KB of ANSI per edit) on the live message dict. build_api_messages strips
display_kind/display_metadata/_row_id before the wire, but the local
estimator's wire shadow only dropped PERSISTENCE_ONLY_MESSAGE_FIELDS
({"timestamp"}), so estimate_messages_tokens_rough and
estimate_request_tokens_rough priced the diff: one edit row went from 32 to
2527 estimated tokens (100 edits: 3100 -> 252600). That inflates compaction
preflight, post-tool checks and turn-overflow scoring, compacts early and
breaks the prompt cache.

PERSISTENCE_ONLY_MESSAGE_FIELDS (agent/message_metadata.py) is now the single
set of local-only fields: timestamp, display_kind, display_metadata, _row_id.
build_api_messages pops exactly that set and the estimator shadow drops it,
so the two can no longer drift. The iteration-limit summary path
(_iteration_summary_api_messages) hand-builds its wire messages and stripped
timestamp but not display_*; its key set now unions the same constant, so
the inline diff never reaches the provider there either (strict gateways
reject unknown keys). The tail-budget walk (_estimate_msg_budget_tokens) is
allowlist-based and already ignored these fields.
---
 agent/chat_completion_helpers.py   |  6 +++---
 agent/message_metadata.py          |  9 ++++++---
 agent/turn_context.py              | 11 ++++++-----
 tests/agent/test_model_metadata.py | 12 ++++++++++++
 4 files changed, 27 insertions(+), 11 deletions(-)

diff --git a/agent/chat_completion_helpers.py b/agent/chat_completion_helpers.py
index d1b4c6e4e4..9a1f83e7d7 100644
--- a/agent/chat_completion_helpers.py
+++ b/agent/chat_completion_helpers.py
@@ -39,7 +39,7 @@ from agent.gemini_native_adapter import is_native_gemini_base_url
 # misidentify and, without an api_key, return 401 on every leg (issue #89863).
 from agent.model_metadata import is_local_endpoint
 from agent.message_content import flatten_message_text
-from agent.message_metadata import append_message, stamp_message_timestamp
+from agent.message_metadata import PERSISTENCE_ONLY_MESSAGE_FIELDS, append_message, stamp_message_timestamp
 from agent.message_sanitization import (
     _sanitize_surrogates, _repair_tool_call_arguments, normalize_finish_reason as _normalize_finish_reason,
     sanitize_outbound_kwargs, strip_images_for_rejecting_model,
@@ -2129,8 +2129,8 @@ def try_activate_fallback(agent, reason: "FailoverReason | None" = None, reset_a
 # Keys outside the Chat Completions schema that strict gateways (Fireworks-backed OpenCode
 # Go, Mistral, Moonshot/Kimi) reject with 422. The transport's convert_messages() drops them
 # in the main loop; the summary path calls chat.completions.create() directly, so mirror it.
-_SUMMARY_FOREIGN_MESSAGE_KEYS = ("reasoning", "finish_reason", "tool_name", "codex_reasoning_items",
-    "codex_message_items", "timestamp", "platform_message_id")
+_SUMMARY_FOREIGN_MESSAGE_KEYS = PERSISTENCE_ONLY_MESSAGE_FIELDS | {"reasoning", "finish_reason", "tool_name",
+    "codex_reasoning_items", "codex_message_items", "platform_message_id"}
 _EMPTY_SUMMARY_RESPONSE = "I reached the iteration limit and couldn't generate a summary."
 
 
diff --git a/agent/message_metadata.py b/agent/message_metadata.py
index e13acb663f..687942156a 100644
--- a/agent/message_metadata.py
+++ b/agent/message_metadata.py
@@ -6,9 +6,12 @@ from time import time as wall_time
 from typing import Any, MutableMapping, Optional, TypeVar
 
 
-# These fields describe Hermes' durable record, not provider-visible message
-# content. They must not influence context-pressure decisions.
-PERSISTENCE_ONLY_MESSAGE_FIELDS = frozenset({"timestamp"})
+# These fields describe Hermes' durable record and timeline display, not
+# provider-visible message content. The request builder strips them from every
+# outgoing copy and the token estimator ignores them: one set, so an estimate
+# never prices bytes the provider never receives (an edit's inline_diff in
+# display_metadata is ~9KB and would trigger premature compaction).
+PERSISTENCE_ONLY_MESSAGE_FIELDS = frozenset({"timestamp", "display_kind", "display_metadata", "_row_id"})
 
 _Message = TypeVar("_Message", bound=MutableMapping[str, Any])
 
diff --git a/agent/turn_context.py b/agent/turn_context.py
index 43f8ae03b4..113527c540 100644
--- a/agent/turn_context.py
+++ b/agent/turn_context.py
@@ -22,7 +22,7 @@ from agent.iteration_budget import IterationBudget
 from agent.memory_manager import build_memory_context_block
 from agent.memory_provider import is_trivial_prompt
 from agent.message_content import flatten_message_text
-from agent.message_metadata import append_message, stamp_message_timestamp
+from agent.message_metadata import PERSISTENCE_ONLY_MESSAGE_FIELDS, append_message, stamp_message_timestamp
 from agent.model_metadata import estimate_messages_tokens_rough, estimate_request_tokens_rough
 from agent.image_token_cost import bind_image_token_cost
 from agent.usage_anchor import anchored_context_tokens, restore_usage_anchor
@@ -1220,11 +1220,12 @@ def build_api_messages(
         # persisted history via nested containers; see _clone_message_for_send.
         api_msg = _clone_message_for_send(msg)
         # api_content is bookkeeping (exact bytes sent), never a provider field — pop
-        # it from EVERY outgoing copy. display_* is display-only timeline metadata
-        # (strict OpenAI backends reject unknown keys); _row_id is the durable row id
-        # from _rows_to_conversation and only chat-completions strips underscore keys.
+        # it from EVERY outgoing copy. Persistence/display fields (display_*, _row_id,
+        # timestamp) are local bookkeeping: strict OpenAI backends reject unknown keys
+        # and only chat-completions strips underscore keys. The token estimator drops
+        # the same set, so it never prices bytes the provider never receives.
         _api_content = api_msg.pop("api_content", None)
-        for key in ("display_kind", "display_metadata", "_row_id"):
+        for key in PERSISTENCE_ONLY_MESSAGE_FIELDS:
             api_msg.pop(key, None)
 
         # Inject ephemeral context (memory prefetch + pre_llm_call user hooks)
diff --git a/tests/agent/test_model_metadata.py b/tests/agent/test_model_metadata.py
index 3d8736f3c7..76088df438 100644
--- a/tests/agent/test_model_metadata.py
+++ b/tests/agent/test_model_metadata.py
@@ -23,6 +23,7 @@ from agent.model_metadata import (
     _strip_provider_prefix,
     estimate_tokens_rough,
     estimate_messages_tokens_rough,
+    estimate_request_tokens_rough,
     get_model_context_length,
     get_next_probe_tier,
     get_cached_context_length,
@@ -70,6 +71,17 @@ class TestEstimateMessagesTokensRough:
             estimate_messages_tokens_rough([msg])
         )
 
+    def test_display_only_fields_do_not_change_estimate(self):
+        """An edit row's inline_diff rides display_metadata, which the request builder strips;
+        pricing it would compact early and break the prompt cache."""
+        wire = {"role": "tool", "tool_call_id": "call-1", "name": "write_file",
+                "content": '{"bytes_written": 18000}'}
+        rich = {**wire, "_row_id": 42, "display_kind": "tool_result",
+                "display_metadata": {"tool_result_metadata": {"inline_diff": "\x1b[32m+ line\x1b[0m\n" * 600}}}
+
+        assert estimate_messages_tokens_rough([rich]) == estimate_messages_tokens_rough([wire])
+        assert estimate_request_tokens_rough([rich]) == estimate_request_tokens_rough([wire])
+
     def test_message_with_list_content(self):
         """Vision messages with multimodal content arrays.
 

From 37e0ac0079fb413f9e48a538f9d537fa48bc8d15 Mon Sep 17 00:00:00 2001
From: BearHuddleston <bear@bearhuddleston.dev>
Date: Wed, 23 Sep 2026 20:24:46 -0500
Subject: [PATCH 52/61] fix(desktop): hold history reads behind reconnect
 replay

After a reconnect, REST history could paint a completed turn before the
socket dispatched that turn's ordered replay. The replay then appended the
same progress and final rows again, and the unchanged-history signature
shortcut left the duplicates in place. Sequence watermarks order replayed
frames against live frames, but not REST publication against replay.

JsonRpcGatewayClient now installs a per-session replay barrier before
synchronous socket-open listeners run. Each session settles on its own
once its replay and parked live frames have dispatched. Timeout and
unsupported-method fallbacks resolve true. Socket invalidation and epoch
revocation resolve false, so pending reads are abandoned. Connect still
does not await replay, and the existing replay deadline still applies.

pendingSessionReplay() inspects existing sockets without dialing. The
active, tile, fallback and warm-resume hydration paths wait on it before
activating or reading history, check again when the read returns, and
recheck selection and ownership after waiting.

Carved out of #119186; its fold/dedup half is superseded by #120809.
---
 .../contrib/hooks/replay-hydration.test.tsx   | 312 ++++++++++++++
 .../app/contrib/hooks/use-background-sync.ts  |  55 ++-
 .../hooks/use-session-actions/index.ts        |  14 +
 .../hooks/warm-resume-replay-barrier.test.tsx | 266 ++++++++++++
 apps/desktop/src/store/gateway.ts             |  17 +
 .../src/json-rpc-gateway-replay.test.ts       | 390 +++++++++++++++++-
 apps/shared/src/json-rpc-gateway.ts           | 219 ++++++----
 7 files changed, 1189 insertions(+), 84 deletions(-)
 create mode 100644 apps/desktop/src/app/contrib/hooks/replay-hydration.test.tsx
 create mode 100644 apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx

diff --git a/apps/desktop/src/app/contrib/hooks/replay-hydration.test.tsx b/apps/desktop/src/app/contrib/hooks/replay-hydration.test.tsx
new file mode 100644
index 0000000000..cdf8c4afcd
--- /dev/null
+++ b/apps/desktop/src/app/contrib/hooks/replay-hydration.test.tsx
@@ -0,0 +1,312 @@
+import { type GatewayEvent, JsonRpcGatewayClient } from '@hermes/shared'
+import { act, cleanup, waitFor } from '@testing-library/react'
+import { afterEach, expect, it, vi } from 'vitest'
+
+import type { ClientSessionState } from '@/app/types'
+import { getLatestSessionMessages } from '@/hermes'
+import { chatMessageText } from '@/lib/chat-messages'
+import { createClientSessionState } from '@/lib/chat-runtime'
+import { setPrimaryGateway } from '@/store/gateway'
+import { setActiveSessionId, setBusy, setSelectedStoredSessionId } from '@/store/session'
+import { clearAllSessionStates, publishSessionState } from '@/store/session-states'
+
+import { renderMessageStream } from '../../session/hooks/use-message-stream/test-harness'
+
+import {
+  hydrateStoredSessionTranscript,
+  reconcileActiveTranscript,
+  reconcileTileTranscripts
+} from './use-background-sync'
+
+vi.mock('@/hermes', async original => ({
+  ...(await original<Record<string, unknown>>()),
+  getLatestSessionMessages: vi.fn()
+}))
+
+const sid = 'replay-hydration-runtime'
+const stored = 'replay-hydration-stored'
+
+class Socket extends EventTarget {
+  readyState = 0
+  sent: { id: string; method: string; params: Record<string, unknown> }[] = []
+  send(data: string) {
+    this.sent.push(JSON.parse(data))
+  }
+  close() {
+    this.readyState = 3
+    this.dispatchEvent(new CloseEvent('close'))
+  }
+  open() {
+    this.readyState = 1
+    this.dispatchEvent(new Event('open'))
+  }
+  frame(frame: unknown) {
+    this.dispatchEvent(new MessageEvent('message', { data: JSON.stringify(frame) }))
+  }
+  event(event: GatewayEvent) {
+    this.frame({ jsonrpc: '2.0', method: 'event', params: event })
+  }
+}
+
+function event(seq: number, type: GatewayEvent['type'], payload: Record<string, unknown> = {}): GatewayEvent {
+  return { session_id: sid, seq, type, payload: { timestamp: seq, ...payload } } as GatewayEvent
+}
+
+async function setup(surface: 'active' | 'tile' | 'fallback') {
+  setActiveSessionId(surface === 'tile' ? 'another-runtime' : sid)
+  setSelectedStoredSessionId(stored)
+  const states = new Map<string, ClientSessionState>()
+
+  const updateSessionState = (id: string, updater: (state: ClientSessionState) => ClientSessionState) => {
+    const next = updater(states.get(id) ?? createClientSessionState(stored))
+    states.set(id, next)
+    publishSessionState(id, next)
+
+    return next
+  }
+
+  const stream = renderMessageStream(sid, { states, updateSessionState })
+  const sockets: Socket[] = []
+
+  const client = new JsonRpcGatewayClient({
+    heartbeatIntervalMs: 0,
+    heartbeatDeadlineMs: 0,
+    socketFactory: () => {
+      const socket = new Socket()
+      sockets.push(socket)
+
+      return socket as unknown as WebSocket
+    }
+  })
+
+  setPrimaryGateway(client)
+  client.onEvent(stream.handleEvent)
+
+  const connect = async () => {
+    const promise = client.connect('ws://fixture.test')
+    const socket = sockets.at(-1)!
+    socket.open()
+    await promise
+
+    return socket
+  }
+
+  const first = await connect()
+  act(() => first.event(event(1, 'session.info', { running: false })))
+  client.invalidate()
+  const second = await connect()
+  const request = second.sent.find(item => item.method === 'session.events.since')!
+  expect(request.params.last_seen).toBe(1)
+  const signatureRef = { current: new Map<string, string>() }
+  const requestSequenceRef = { current: 0 }
+  const activeSessionIdRef = { current: sid }
+  const selectedStoredSessionIdRef = { current: stored }
+
+  const refresh = () =>
+    surface === 'tile'
+      ? reconcileTileTranscripts({
+          tiles: [{ storedSessionId: stored, runtimeId: sid }],
+          signatureRef,
+          requestSequenceRef,
+          updateSessionState
+        })
+      : surface === 'fallback'
+        ? hydrateStoredSessionTranscript({
+            attempts: 1,
+            storedSessionId: stored,
+            runtimeSessionId: sid,
+            storedProfile: 'default',
+            updateSessionState
+          })
+        : reconcileActiveTranscript({
+            activeSessionIdRef,
+            selectedStoredSessionIdRef,
+            busyRef: { current: false },
+            requestSequenceRef,
+            signatureRef,
+            resolveSession: () => ({ profile: 'default' }),
+            updateSessionState
+          })
+
+  return { client, stream, refresh, second, request, connect, activeSessionIdRef, selectedStoredSessionIdRef }
+}
+
+const replay = [
+  event(2, 'message.start'),
+  event(3, 'message.delta', { text: 'Earlier progress.' }),
+  event(4, 'message.interim', { text: 'Earlier progress.', already_streamed: true }),
+  event(5, 'tool.start', { name: 'read_file', tool_id: 'old-call', args: { path: 'example.py' } }),
+  event(6, 'tool.complete', { name: 'read_file', tool_id: 'old-call', result: 'fixture contents' }),
+  event(7, 'message.delta', { text: 'Finished result.' }),
+  event(8, 'message.complete', { text: 'Finished result.' }),
+  event(9, 'session.info', { running: false })
+]
+
+function stubHistory() {
+  vi.mocked(getLatestSessionMessages).mockResolvedValue({
+    session_id: stored,
+    messages: [
+      { id: 1, role: 'user', content: 'Review example', timestamp: 1 },
+      {
+        id: 2,
+        role: 'assistant',
+        content: 'Earlier progress.',
+        timestamp: 2,
+        tool_calls: [
+          { id: 'old-call', type: 'function', function: { name: 'read_file', arguments: '{"path":"example.py"}' } }
+        ]
+      },
+      {
+        id: 3,
+        role: 'tool',
+        content: 'fixture contents',
+        timestamp: 3,
+        tool_call_id: 'old-call',
+        tool_name: 'read_file'
+      },
+      { id: 4, role: 'assistant', content: 'Finished result.', timestamp: 4 }
+    ]
+  })
+}
+
+afterEach(() => {
+  cleanup()
+  clearAllSessionStates()
+  setPrimaryGateway(null)
+  setActiveSessionId(null)
+  setSelectedStoredSessionId(null)
+  setBusy(false)
+  vi.mocked(getLatestSessionMessages).mockReset()
+})
+
+it.each(['active', 'tile', 'fallback'] as const)(
+  'orders %s history after full replay without duplicate turns',
+  async surface => {
+    const { client, stream, refresh, second, request } = await setup(surface)
+
+    try {
+      stubHistory()
+      let pending!: Promise<void>
+      await act(async () => {
+        pending = refresh()
+      })
+      // The database is already complete; publishing it ahead of the replay is
+      // precisely the race. Do not issue the read until this session catches up.
+      expect(getLatestSessionMessages).not.toHaveBeenCalled()
+      await act(async () => {
+        second.frame({ id: request.id, jsonrpc: '2.0', result: { events: replay } })
+        await pending
+      })
+      const texts = stream.state().messages.map(chatMessageText).join('\n')
+
+      expect(texts.match(/Earlier progress\./g)).toHaveLength(1)
+      expect(texts.match(/Finished result\./g)).toHaveLength(1)
+      expect(texts).toContain('Review example')
+      expect(stream.state().busy).toBe(false)
+    } finally {
+      client.close()
+    }
+  }
+)
+
+it('keeps an unseen live turn parked behind replay instead of painting an idle snapshot over it', async () => {
+  const { client, stream, refresh, second, request } = await setup('active')
+
+  try {
+    stubHistory()
+    let pending!: Promise<void>
+    await act(async () => {
+      pending = refresh()
+    })
+    act(() => {
+      second.event(event(10, 'message.start'))
+      second.event(event(11, 'message.delta', { text: 'New work.' }))
+    })
+    await act(async () => {
+      second.frame({ id: request.id, jsonrpc: '2.0', result: { events: replay } })
+      await pending
+    })
+    expect(getLatestSessionMessages).not.toHaveBeenCalled()
+    expect(stream.state().busy).toBe(true)
+    // Replay dispatch does not flush the renderer's coalesced delta timer.
+    await waitFor(() => expect(stream.state().messages.map(chatMessageText).join('\n')).toContain('New work.'))
+  } finally {
+    client.close()
+  }
+})
+
+it('abandons a queued history read when its replay socket is invalidated', async () => {
+  const { client, refresh } = await setup('active')
+  stubHistory()
+  let pending!: Promise<void>
+  await act(async () => {
+    pending = refresh()
+  })
+  await act(async () => {
+    client.invalidate()
+    await pending
+  })
+  expect(getLatestSessionMessages).not.toHaveBeenCalled()
+  client.close()
+})
+
+it('does not follow a stale selection after waiting for replay', async () => {
+  const { client, refresh, second, request, selectedStoredSessionIdRef } = await setup('active')
+
+  try {
+    stubHistory()
+    let pending!: Promise<void>
+    await act(async () => {
+      pending = refresh()
+    })
+    selectedStoredSessionIdRef.current = 'another-session'
+    await act(async () => {
+      second.frame({ id: request.id, jsonrpc: '2.0', result: { events: replay } })
+      await pending
+    })
+    expect(getLatestSessionMessages).not.toHaveBeenCalled()
+  } finally {
+    client.close()
+  }
+})
+
+it('checks replay again when a socket reconnects during an existing history read', async () => {
+  const { client, stream, refresh, second, request, connect } = await setup('active')
+
+  try {
+    await act(async () => second.frame({ id: request.id, jsonrpc: '2.0', result: { events: [] } }))
+    stubHistory()
+    const snapshot = await getLatestSessionMessages(stored)
+    vi.mocked(getLatestSessionMessages).mockReset()
+    let release!: () => void
+    vi.mocked(getLatestSessionMessages).mockReturnValue(
+      new Promise(resolve => {
+        release = () => resolve(snapshot)
+      })
+    )
+    let pending!: Promise<void>
+    await act(async () => {
+      pending = refresh()
+    })
+    expect(getLatestSessionMessages).toHaveBeenCalledTimes(1)
+    client.invalidate()
+    const next = await connect()
+    const replayRequest = next.sent.find(item => item.method === 'session.events.since')!
+    await act(async () => {
+      release()
+    })
+    // The held REST result must not paint a completed turn ahead of replay.
+    expect(stream.state().messages.map(chatMessageText).join('\n')).not.toContain('Finished result.')
+    await act(async () => {
+      next.frame({ id: replayRequest.id, jsonrpc: '2.0', result: { events: replay } })
+      await pending
+    })
+    stubHistory()
+    await act(refresh)
+    const text = stream.state().messages.map(chatMessageText).join('\n')
+    expect(text).toContain('Review example')
+    expect(text.match(/Finished result\./g)).toHaveLength(1)
+  } finally {
+    client.close()
+  }
+})
diff --git a/apps/desktop/src/app/contrib/hooks/use-background-sync.ts b/apps/desktop/src/app/contrib/hooks/use-background-sync.ts
index d34297bf12..7f4b2d0e74 100644
--- a/apps/desktop/src/app/contrib/hooks/use-background-sync.ts
+++ b/apps/desktop/src/app/contrib/hooks/use-background-sync.ts
@@ -8,6 +8,7 @@ import { type ChatMessage, preserveLocalAssistantErrors, sealOpenToolParts, toCh
 import { createClientSessionState } from '@/lib/chat-runtime'
 import { sessionMessagesSignature } from '@/lib/session-signatures'
 import { latestSessionTodos } from '@/lib/todos'
+import { pendingSessionReplay } from '@/store/gateway'
 import { $sidebarShowArchived } from '@/store/layout'
 import { $changeEventsAvailable, $cronChangeTick, $sessionsChangeTick } from '@/store/live-sync'
 import { $onBattery, batteryPollInterval } from '@/store/power'
@@ -222,12 +223,31 @@ export async function reconcileTileTranscripts({
     const profileScope = profileScopeForTranscriptSession(tile)
 
     const signatureKey = tileTranscriptSignatureKey(tile)
-    const messagesAtRequest = $sessionStates.get()[runtimeSessionId]?.messages
 
     try {
+      const replay = pendingSessionReplay(runtimeSessionId)
+
+      if (replay && !(await replay)) {
+        continue
+      }
+
+      if (
+        requestId !== requestSequenceRef.current ||
+        !tileStillPresent() ||
+        tileRuntimeOwnsLiveState(runtimeSessionId)
+      ) {
+        continue
+      }
+
+      const messagesAtRequest = $sessionStates.get()[runtimeSessionId]?.messages
       // Passive: a hidden tile's refresh must never cold-start its owner
       // backend or hold a pool slot (#103375); no warm backend = retry next tick.
       const latest = await getLatestSessionMessages(storedSessionId, profileScope, { passive: true })
+      const replayAtReturn = pendingSessionReplay(runtimeSessionId)
+
+      if (replayAtReturn && !(await replayAtReturn)) {
+        continue
+      }
 
       const current = $sessionStates.get()[runtimeSessionId]
 
@@ -295,6 +315,12 @@ export async function hydrateStoredSessionTranscript({
   storedProfile: ProfileScope
   updateSessionState: ActiveTranscriptRefreshDeps['updateSessionState']
 }): Promise<void> {
+  const replay = pendingSessionReplay(runtimeSessionId)
+
+  if (replay && !(await replay)) {
+    return
+  }
+
   const messagesAtRequest = $sessionStates.get()[runtimeSessionId]?.messages
 
   const superseded = () =>
@@ -312,6 +338,11 @@ export async function hydrateStoredSessionTranscript({
 
     try {
       const latest = await getLatestSessionMessages(storedSessionId, storedProfile)
+      const replayAtReturn = pendingSessionReplay(runtimeSessionId)
+
+      if (replayAtReturn && !(await replayAtReturn)) {
+        return
+      }
 
       // This fallback belongs to the completed turn, not any subsequent turn
       // that ran during the read or retry delay. Its todo restore is stale too.
@@ -378,6 +409,22 @@ export async function reconcileActiveTranscript({
 
   const requestId = requestSequenceRef.current + 1
   requestSequenceRef.current = requestId
+  const replay = pendingSessionReplay(runtimeSessionId)
+
+  if (replay && !(await replay)) {
+    return
+  }
+
+  if (
+    requestId !== requestSequenceRef.current ||
+    busyRef.current ||
+    tileRuntimeOwnsLiveState(runtimeSessionId) ||
+    selectedStoredSessionIdRef.current !== storedSessionId ||
+    activeSessionIdRef.current !== runtimeSessionId
+  ) {
+    return
+  }
+
   // Busy at both endpoints can be false even though an entire turn streamed
   // while HTTP was in flight. Never let that older read replace newer text.
   const messagesAtRequest = $sessionStates.get()[runtimeSessionId]?.messages
@@ -386,6 +433,12 @@ export async function reconcileActiveTranscript({
     const profileScope: ProfileScope = profileScopeForTranscriptSession(stored)
 
     const latest = await getLatestSessionMessages(storedSessionId, profileScope)
+    const replayAtReturn = pendingSessionReplay(runtimeSessionId)
+
+    if (replayAtReturn && !(await replayAtReturn)) {
+      return
+    }
+
     const current = $sessionStates.get()[runtimeSessionId]
 
     if (
diff --git a/apps/desktop/src/app/session/hooks/use-session-actions/index.ts b/apps/desktop/src/app/session/hooks/use-session-actions/index.ts
index 5dd13612a0..e87c6acdad 100644
--- a/apps/desktop/src/app/session/hooks/use-session-actions/index.ts
+++ b/apps/desktop/src/app/session/hooks/use-session-actions/index.ts
@@ -34,6 +34,7 @@ import {
   $gateway,
   openGatewayForAgent,
   openGatewayForProfile,
+  pendingSessionReplay,
   requestGatewayForAgent,
   retainGatewayForAgent
 } from '@/store/gateway'
@@ -1290,6 +1291,12 @@ export function useSessionActions({
           setSessionStartedAt(Date.now())
 
           try {
+            const replay = pendingSessionReplay(cachedRuntimeId)
+
+            if (replay && (!(await replay) || !isCurrentResume())) {
+              return
+            }
+
             let activated: SessionResumeResult | null = null
             const activateStartedAt = Date.now() / 1000
             const activateBaselineState = sessionStateByRuntimeIdRef.current.get(cachedRuntimeId) ?? cachedViewState
@@ -1463,6 +1470,13 @@ export function useSessionActions({
 
               if (persistedTranscriptPromise) {
                 const persisted = await persistedTranscriptPromise
+                const replayAtReturn = pendingSessionReplay(cachedRuntimeId)
+
+                if (replayAtReturn && !(await replayAtReturn)) {
+                  hydration.release()
+
+                  return
+                }
 
                 // Navigation only revokes foreground publication, not this
                 // runtime's display read. Edits/rebinds revoke both.
diff --git a/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx b/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
new file mode 100644
index 0000000000..78d1916fde
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
@@ -0,0 +1,266 @@
+import { type GatewayEvent, JsonRpcGatewayClient } from '@hermes/shared'
+import { QueryClient } from '@tanstack/react-query'
+import { act, cleanup, renderHook } from '@testing-library/react'
+import { useRef } from 'react'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+
+import { getLatestSessionMessages } from '@/hermes'
+import { chatMessageText, toChatMessages } from '@/lib/chat-messages'
+import { resetInFlightTurnJournalStateForTests } from '@/lib/inflight-turn-journal'
+import { setPrimaryGateway } from '@/store/gateway'
+import { $activeGatewayProfile } from '@/store/profile'
+import {
+  _resetSessionOwnerHintsForTests,
+  setActiveSessionId,
+  setAwaitingResponse,
+  setBusy,
+  setConnection,
+  setMessages,
+  setSelectedStoredSessionId,
+  setSessions
+} from '@/store/session'
+import { clearAllSessionStates } from '@/store/session-states'
+import type { SessionMessage, SessionResumeResult } from '@/types/hermes'
+
+import { useMessageStream } from './use-message-stream'
+import { useSessionActions } from './use-session-actions'
+import { useSessionStateCache } from './use-session-state-cache'
+
+vi.mock('@/hermes', async original => ({
+  ...(await original<Record<string, unknown>>()),
+  getLatestSessionMessages: vi.fn()
+}))
+vi.mock('@/store/profile', async original => ({
+  ...(await original<Record<string, unknown>>()),
+  ensureGatewayProfile: vi.fn().mockResolvedValue(undefined)
+}))
+
+const storedId = 'warm-replay-stored'
+const runtimeId = 'warm-replay-runtime'
+const noop = async () => undefined
+const user: SessionMessage = { id: 1, role: 'user', content: 'Review example', timestamp: 1 }
+
+class Socket extends EventTarget {
+  readyState = 0
+  sent: { id: string; method: string; params: Record<string, unknown> }[] = []
+  send(data: string) {
+    this.sent.push(JSON.parse(data))
+  }
+  close() {
+    this.readyState = 3
+    this.dispatchEvent(new CloseEvent('close'))
+  }
+  open() {
+    this.readyState = 1
+    this.dispatchEvent(new Event('open'))
+  }
+  frame(frame: unknown) {
+    this.dispatchEvent(new MessageEvent('message', { data: JSON.stringify(frame) }))
+  }
+  event(event: GatewayEvent) {
+    this.frame({ jsonrpc: '2.0', method: 'event', params: event })
+  }
+}
+
+function event(seq: number, type: GatewayEvent['type'], payload: Record<string, unknown> = {}): GatewayEvent {
+  return { session_id: runtimeId, seq, type, payload: { timestamp: seq, ...payload } } as GatewayEvent
+}
+
+const replay = [
+  event(2, 'message.start'),
+  event(3, 'message.delta', { text: 'Finished result.' }),
+  event(4, 'message.complete', { text: 'Finished result.' }),
+  event(5, 'session.info', { running: false })
+]
+
+const snapshot: SessionResumeResult = {
+  session_id: runtimeId,
+  resumed: storedId,
+  messages: [],
+  message_count: 0,
+  running: false
+}
+
+async function mountWithPendingReplay() {
+  const requestGateway = vi.fn().mockResolvedValue(snapshot)
+
+  const hook = renderHook(() => {
+    const busyRef = useRef(false)
+    const creatingSessionRef = useRef(false)
+    const queryClient = useRef(new QueryClient()).current
+
+    const cache = useSessionStateCache({
+      activeSessionId: null,
+      selectedStoredSessionId: null,
+      busyRef,
+      setMessages,
+      setBusy,
+      setAwaitingResponse
+    })
+
+    const actions = useSessionActions({
+      ...cache,
+      activeSessionId: null,
+      selectedStoredSessionId: null,
+      busyRef,
+      creatingSessionRef,
+      getRouteToken: () => 'A',
+      getRoutedStoredSessionId: () => null,
+      navigate: vi.fn(),
+      requestGateway
+    })
+
+    const stream = useMessageStream({
+      ...cache,
+      queryClient,
+      hydrateFromStoredSession: noop,
+      refreshHermesConfig: noop,
+      refreshSessions: noop
+    })
+
+    return { cache, actions, stream }
+  })
+
+  const sockets: Socket[] = []
+
+  const client = new JsonRpcGatewayClient({
+    heartbeatIntervalMs: 0,
+    heartbeatDeadlineMs: 0,
+    socketFactory: () => {
+      const socket = new Socket()
+      sockets.push(socket)
+
+      return socket as unknown as WebSocket
+    }
+  })
+
+  setPrimaryGateway(client)
+  client.onEvent(gatewayEvent => hook.result.current.stream.handleGatewayEvent(gatewayEvent))
+
+  const connect = async () => {
+    const promise = client.connect('ws://fixture.test')
+    const socket = sockets.at(-1)!
+    socket.open()
+    await promise
+
+    return socket
+  }
+
+  // Warm cache: the runtime is already known and has seen seq 1.
+  act(() => {
+    hook.result.current.cache.updateSessionState(
+      runtimeId,
+      state => ({ ...state, messages: toChatMessages([user]) }),
+      storedId
+    )
+  })
+  const first = await connect()
+  act(() => first.event(event(1, 'session.info', { running: false })))
+  client.invalidate()
+  const second = await connect()
+  const request = second.sent.find(item => item.method === 'session.events.since')!
+  expect(request.params).toMatchObject({ session_id: runtimeId, last_seen: 1 })
+
+  return { ...hook, client, requestGateway, second, request }
+}
+
+beforeEach(() => {
+  localStorage.clear()
+  clearAllSessionStates()
+  resetInFlightTurnJournalStateForTests()
+  _resetSessionOwnerHintsForTests()
+  $activeGatewayProfile.set('default')
+  setConnection(null)
+  setMessages([])
+  setActiveSessionId(null)
+  setSelectedStoredSessionId(null)
+  setBusy(false)
+  setAwaitingResponse(false)
+  setSessions([
+    {
+      id: storedId,
+      title: storedId,
+      source: 'desktop',
+      message_count: 3,
+      tool_call_count: 0,
+      is_active: true,
+      started_at: 1,
+      last_active: 1,
+      ended_at: null,
+      model: null,
+      preview: null,
+      input_tokens: 0,
+      output_tokens: 0
+    }
+  ])
+  vi.mocked(getLatestSessionMessages).mockReset()
+  vi.mocked(getLatestSessionMessages).mockResolvedValue({
+    session_id: storedId,
+    messages: [user, { id: 2, role: 'assistant', content: 'Finished result.', timestamp: 2 }]
+  })
+})
+
+afterEach(() => {
+  cleanup()
+  clearAllSessionStates()
+  resetInFlightTurnJournalStateForTests()
+  setPrimaryGateway(null)
+  localStorage.clear()
+  setSessions([])
+  setMessages([])
+  setActiveSessionId(null)
+  setSelectedStoredSessionId(null)
+  setBusy(false)
+  setAwaitingResponse(false)
+  vi.restoreAllMocks()
+})
+
+const activateCalls = (requestGateway: ReturnType<typeof vi.fn>) =>
+  requestGateway.mock.calls.filter(([method]) => method === 'session.activate')
+
+it('waits for reconnect replay before activating and reading warm history', async () => {
+  const { result, client, requestGateway, second, request } = await mountWithPendingReplay()
+
+  try {
+    let pending!: Promise<void>
+    await act(async () => {
+      pending = result.current.actions.resumeSession(storedId, true)
+    })
+    // The completed turn is already durable; neither the activation snapshot
+    // nor REST history may publish it ahead of the replay that carries it.
+    expect(activateCalls(requestGateway)).toHaveLength(0)
+    expect(getLatestSessionMessages).not.toHaveBeenCalled()
+
+    await act(async () => {
+      second.frame({ id: request.id, jsonrpc: '2.0', result: { events: replay } })
+      await pending
+    })
+
+    expect(activateCalls(requestGateway)).toHaveLength(1)
+    const rows = result.current.cache.sessionStateByRuntimeIdRef.current.get(runtimeId)!.messages
+    const text = rows.map(chatMessageText).join('\n')
+    expect(text).toContain('Review example')
+    expect(text.match(/Finished result\./g)).toHaveLength(1)
+  } finally {
+    client.close()
+  }
+})
+
+it('abandons a warm resume whose replay socket is invalidated', async () => {
+  const { result, client, requestGateway } = await mountWithPendingReplay()
+
+  try {
+    let pending!: Promise<void>
+    await act(async () => {
+      pending = result.current.actions.resumeSession(storedId, true)
+    })
+    await act(async () => {
+      client.invalidate()
+      await pending
+    })
+    expect(activateCalls(requestGateway)).toHaveLength(0)
+    expect(getLatestSessionMessages).not.toHaveBeenCalled()
+  } finally {
+    client.close()
+  }
+})
diff --git a/apps/desktop/src/store/gateway.ts b/apps/desktop/src/store/gateway.ts
index 0e54703c90..1c2fe56934 100644
--- a/apps/desktop/src/store/gateway.ts
+++ b/apps/desktop/src/store/gateway.ts
@@ -533,6 +533,23 @@ export function activeGateway(): HermesGateway | null {
   return g.secondaries.get(g.activeKey)?.gateway ?? null
 }
 
+/** Passive ordering barrier for a runtime's transcript reads. Inspect only
+ * existing sockets: waiting must never dial, activate, or retain a backend.
+ * Each client names its own replaying runtime IDs; no ambient route is used
+ * to decide which session's events are safe to paint over. */
+export function pendingSessionReplay(runtimeId: string): Promise<boolean> | undefined {
+  const clients = new Set([g.primaryGateway, ...[...g.secondaries.values()].map(entry => entry.gateway)])
+
+  const pending = [...clients].flatMap(client => {
+    // A dev-HMR survivor can predate the barrier method.
+    const barrier = client?.sessionReplayBarrier?.(runtimeId)
+
+    return barrier ? [barrier] : []
+  })
+
+  return pending.length ? Promise.all(pending).then(results => results.every(Boolean)) : undefined
+}
+
 /**
  * The registry connection serving the gateway the user is currently looking
  * at. A registry-backed primary takes its identity from the published primary
diff --git a/apps/shared/src/json-rpc-gateway-replay.test.ts b/apps/shared/src/json-rpc-gateway-replay.test.ts
index 33eb4fb1a9..af221edacf 100644
--- a/apps/shared/src/json-rpc-gateway-replay.test.ts
+++ b/apps/shared/src/json-rpc-gateway-replay.test.ts
@@ -48,8 +48,9 @@ class FakeWebSocket extends EventTarget {
 
 let sockets: FakeWebSocket[]
 
-const makeClient = () => {
+const makeClient = (replay = true) => {
   const client = new JsonRpcGatewayClient({
+    replay,
     socketFactory: url => new FakeWebSocket(url) as unknown as WebSocket,
     heartbeatIntervalMs: 0,
     heartbeatDeadlineMs: 0,
@@ -71,9 +72,21 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     sockets[0].open()
     await p
 
-    sockets[0].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'message.delta', session_id: 's1', seq: 4 } })
-    sockets[0].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'message.delta', session_id: 's1', seq: 2 } }) // out of order / late
-    sockets[0].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'tool.start', session_id: 's2', seq: 9 } })
+    sockets[0].serverFrame({
+      jsonrpc: '2.0',
+      method: 'event',
+      params: { type: 'message.delta', session_id: 's1', seq: 4 }
+    })
+    sockets[0].serverFrame({
+      jsonrpc: '2.0',
+      method: 'event',
+      params: { type: 'message.delta', session_id: 's1', seq: 2 }
+    }) // out of order / late
+    sockets[0].serverFrame({
+      jsonrpc: '2.0',
+      method: 'event',
+      params: { type: 'tool.start', session_id: 's2', seq: 9 }
+    })
     sockets[0].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'skin.changed' } }) // no sid/seq
 
     expect(client.getSeqWatermarks()).toEqual({ s1: 4, s2: 9 })
@@ -150,19 +163,31 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     client.close()
   })
 
-  it('does not attempt replay when nothing was ever observed', async () => {
-    const client = makeClient()
+  it.each([true, false])('has no replay barrier without watermarks or with replay disabled (%s)', async replay => {
+    const client = makeClient(replay)
+    expect(client.sessionReplayBarrier('s1')).toBeUndefined()
     const p = client.connect('ws://x')
     sockets[0].open()
     await p
-    // No events ever seen → close+reconnect must NOT fire a replay RPC.
+
+    if (!replay) {
+      sockets[0].serverFrame({
+        jsonrpc: '2.0',
+        method: 'event',
+        params: { type: 'message.delta', session_id: 's1', seq: 1 }
+      })
+    }
+
+    // No watermarks, or explicitly disabled replay, must not create a barrier.
     client.invalidate('drop')
+    expect(client.sessionReplayBarrier('s1')).toBeUndefined()
     const p2 = client.connect('ws://x')
     sockets[sockets.length - 1].open()
     await p2
     await new Promise(r => setTimeout(r, 20))
 
     expect(sockets[sockets.length - 1].sent).toHaveLength(0)
+    expect(client.sessionReplayBarrier('s1')).toBeUndefined()
     client.close()
   })
 
@@ -188,7 +213,12 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     sock.serverFrame({
       jsonrpc: '2.0',
       id: req.id,
-      result: { events: [{ type: 'status.update', session_id: 's1', seq: 2 }], latest_seq: 10, truncated: false, count: 1 }
+      result: {
+        events: [{ type: 'status.update', session_id: 's1', seq: 2 }],
+        latest_seq: 10,
+        truncated: false,
+        count: 1
+      }
     })
     await Promise.resolve()
     expect(client.getSeqWatermarks().s1).toBe(10)
@@ -249,11 +279,38 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     expect(seen).toEqual([2]) // pre-drop live frame dispatches normally
 
     client.invalidate('drop')
+    let openBarrier: Promise<boolean> | undefined
+    client.onState(state => {
+      if (state === 'open') {
+        openBarrier = client.sessionReplayBarrier?.('s1')
+        // A synchronous open listener must not advance the watermark ahead
+        // of the gap, even before connect() returns to its caller.
+        sock.serverFrame({
+          jsonrpc: '2.0',
+          method: 'event',
+          params: { type: 'message.delta', session_id: 's1', seq: 5 }
+        })
+      }
+    })
     const second = client.connect('ws://x')
     sock = sockets[sockets.length - 1]
     sock.open()
     await second
 
+    expect(openBarrier).toBeInstanceOf(Promise)
+    expect(client.sessionReplayBarrier('s1')).toBe(openBarrier)
+    expect(client.sessionReplayBarrier('unobserved')).toBeUndefined()
+    let settled = false
+
+    const barrierChecked = openBarrier!.then(valid => {
+      expect(valid).toBe(true)
+      expect(seen).toEqual([2, 3, 4, 5, 6])
+      settled = true
+    })
+
+    await Promise.resolve()
+    expect(settled).toBe(false) // connect() does not wait for replay
+
     await vi.waitFor(() => {
       expect(sock.lastRequest().method).toBe('session.events.since')
     })
@@ -285,6 +342,9 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     await vi.waitFor(() => {
       expect(seen).toEqual([2, 3, 4, 5, 6])
     })
+    await barrierChecked
+    expect(settled).toBe(true)
+    expect(client.sessionReplayBarrier('s1')).toBeUndefined()
     expect(client.getSeqWatermarks().s1).toBe(6)
     client.close()
   })
@@ -297,20 +357,35 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     const first = client.connect('ws://x')
     sockets[0].open()
     await first
-    sockets[0].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'message.delta', session_id: 's1', seq: 1 } })
+    sockets[0].serverFrame({
+      jsonrpc: '2.0',
+      method: 'event',
+      params: { type: 'message.delta', session_id: 's1', seq: 1 }
+    })
 
     client.invalidate('first drop')
+    // History can arrive in the disconnected gap, before any replay exists.
+    await expect(client.sessionReplayBarrier('s1')).resolves.toBe(false)
+    expect(client.sessionReplayBarrier('unobserved')).toBeUndefined()
     const second = client.connect('ws://x')
+    await expect(client.sessionReplayBarrier('s1')).resolves.toBe(false)
     sockets[1].open()
     await second
     await vi.waitFor(() => expect(sockets[1].lastRequest().method).toBe('session.events.since'))
+    const oldBarrier = client.sessionReplayBarrier('s1')
+    expect(oldBarrier).toBeInstanceOf(Promise)
 
     // The old request rejects asynchronously after detach. Open the
     // replacement before its cleanup runs; it must own a fresh replay.
     client.invalidate('second drop')
     const third = client.connect('ws://x')
     sockets[2].open()
+    const replacementBarrier = client.sessionReplayBarrier('s1')
     await third
+    await expect(oldBarrier).resolves.toBe(false)
+    expect(replacementBarrier).toBeInstanceOf(Promise)
+    expect(replacementBarrier).not.toBe(oldBarrier)
+    expect(client.sessionReplayBarrier('s1')).toBe(replacementBarrier)
     await vi.waitFor(() => expect(sockets[2].lastRequest().method).toBe('session.events.since'))
 
     const request = sockets[2].lastRequest()
@@ -319,21 +394,312 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     // A live frame racing the new replay is parked by the NEW hold; the stale
     // replay's cleanup must neither flush it nor advance the watermark past
     // the gap it never recovered.
-    sockets[2].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'message.delta', session_id: 's1', seq: 3 } })
+    sockets[2].serverFrame({
+      jsonrpc: '2.0',
+      method: 'event',
+      params: { type: 'message.delta', session_id: 's1', seq: 3 }
+    })
     await Promise.resolve()
     expect(seen).toEqual([1])
     expect(client.getSeqWatermarks()).toEqual({ s1: 1 })
 
     sockets[2].serverFrame({
-      jsonrpc: '2.0', id: request.id,
-      result: { events: [{ type: 'message.delta', session_id: 's1', seq: 2 }], latest_seq: 2, truncated: false, count: 1 }
+      jsonrpc: '2.0',
+      id: request.id,
+      result: {
+        events: [{ type: 'message.delta', session_id: 's1', seq: 2 }],
+        latest_seq: 2,
+        truncated: false,
+        count: 1
+      }
     })
 
     await vi.waitFor(() => expect(seen).toEqual([1, 2, 3]))
+    await expect(replacementBarrier).resolves.toBe(true)
+    expect(client.sessionReplayBarrier('s1')).toBeUndefined()
     expect(client.getSeqWatermarks()).toEqual({ s1: 3 })
     client.close()
   })
 
+  it.each(['replay', 'parked'] as const)(
+    'keeps replacement ownership when a %s handler invalidates its socket',
+    async invalidateDuring => {
+      const client = makeClient()
+
+      try {
+        const first = client.connect('ws://x')
+        sockets[0].open()
+        await first
+        sockets[0].serverFrame({
+          jsonrpc: '2.0',
+          method: 'event',
+          params: { type: 'message.delta', session_id: 's1', seq: 1 }
+        })
+        client.invalidate()
+        const second = client.connect('ws://x')
+        sockets[1].open()
+        await second
+        const oldBarrier = client.sessionReplayBarrier('s1')!
+        const seen: number[] = []
+        let replacement: Promise<void> | undefined
+        let replacementBarrier: Promise<boolean> | undefined
+        const invalidateAt = invalidateDuring === 'replay' ? 2 : 3
+        client.on('message.delta', event => {
+          seen.push(event.seq!)
+
+          if (event.seq === invalidateAt) {
+            expect(client.sessionReplayBarrier('s1')).toBe(oldBarrier)
+            client.invalidate()
+            replacement = client.connect('ws://x')
+            sockets[2].open()
+            replacementBarrier = client.sessionReplayBarrier('s1')
+            sockets[2].serverFrame({
+              jsonrpc: '2.0',
+              method: 'event',
+              params: { type: 'message.delta', session_id: 's1', seq: 6 }
+            })
+          }
+        })
+
+        for (const seq of [3, 4]) {
+          sockets[1].serverFrame({
+            jsonrpc: '2.0',
+            method: 'event',
+            params: { type: 'message.delta', session_id: 's1', seq }
+          })
+        }
+
+        sockets[1].serverFrame({
+          jsonrpc: '2.0',
+          id: sockets[1].lastRequest().id,
+          result: {
+            events: (invalidateDuring === 'replay' ? [2, 3] : [2]).map(seq => ({
+              type: 'message.delta',
+              session_id: 's1',
+              seq
+            }))
+          }
+        })
+        await expect(oldBarrier).resolves.toBe(false)
+        await replacement
+        expect(client.sessionReplayBarrier('s1')).toBe(replacementBarrier)
+        expect(seen).toEqual(invalidateDuring === 'replay' ? [2] : [2, 3])
+        const request = sockets[2].lastRequest()
+        expect(request.params.last_seen).toBe(invalidateAt)
+        sockets[2].serverFrame({
+          jsonrpc: '2.0',
+          id: request.id,
+          result: {
+            events: [{ type: 'message.delta', session_id: 's1', seq: 5 }]
+          }
+        })
+        await expect(replacementBarrier).resolves.toBe(true)
+        expect(seen).toEqual(invalidateDuring === 'replay' ? [2, 5, 6] : [2, 3, 5, 6])
+      } finally {
+        client.close()
+      }
+    }
+  )
+
+  it.each(['timeout', 'unsupported'] as const)(
+    'settles sessions independently and releases fresh frames on replay %s',
+    async fallback => {
+      vi.useFakeTimers()
+      const client = makeClient()
+      const seen: string[] = []
+      client.onEvent(event => seen.push(`${event.session_id}:${event.type}:${event.seq}`))
+
+      try {
+        const first = client.connect('ws://x')
+        sockets[0].open()
+        await first
+
+        sockets[0].serverFrame({
+          jsonrpc: '2.0',
+          method: 'event',
+          params: { type: 'gateway.ready', payload: { replay_epoch: 'stable' } }
+        })
+
+        for (const sid of ['slow', 'fast']) {
+          sockets[0].serverFrame({
+            jsonrpc: '2.0',
+            method: 'event',
+            params: { type: 'session.info', session_id: sid, seq: 1 }
+          })
+        }
+
+        seen.length = 0
+        client.invalidate()
+        const second = client.connect('ws://x')
+        sockets[1].open()
+        await second
+        const slow = client.sessionReplayBarrier('slow')!
+        const fast = client.sessionReplayBarrier('fast')!
+        expect(slow).toBeInstanceOf(Promise)
+        expect(fast).toBeInstanceOf(Promise)
+        const requests = sockets[1].sent.map(text => JSON.parse(text))
+        const slowRequest = requests.find(request => request.params.session_id === 'slow')
+        const fastRequest = requests.find(request => request.params.session_id === 'fast')
+        const slowSettled = vi.fn()
+        void slow.then(slowSettled)
+
+        // Both ordinary parked starts and wire-marked replayed starts are fresh.
+        for (const [sid, seq] of [
+          ['slow', 2],
+          ['fast', 3]
+        ] as const) {
+          sockets[1].serverFrame({
+            jsonrpc: '2.0',
+            method: 'event',
+            params: { type: 'message.start', session_id: sid, seq, replayed: sid === 'fast' }
+          })
+        }
+
+        sockets[1].serverFrame({
+          jsonrpc: '2.0',
+          method: 'event',
+          params: { type: 'message.start', session_id: 'new', seq: 1 }
+        })
+        expect(seen).toEqual(['new:message.start:1'])
+
+        const fastSettled = fast.then(valid => {
+          expect(valid).toBe(true)
+          expect(seen).toEqual(['new:message.start:1', 'fast:message.complete:2', 'fast:message.start:3'])
+        })
+
+        sockets[1].serverFrame({
+          jsonrpc: '2.0',
+          id: fastRequest.id,
+          result: {
+            epoch: 'stable',
+            events: [{ type: 'message.complete', session_id: 'fast', seq: 2 }]
+          }
+        })
+        await fastSettled
+        expect(client.sessionReplayBarrier('fast')).toBeUndefined()
+        expect(client.sessionReplayBarrier('slow')).toBe(slow)
+        expect(slowSettled).not.toHaveBeenCalled()
+        sockets[1].serverFrame({
+          jsonrpc: '2.0',
+          method: 'event',
+          params: { type: 'message.delta', session_id: 'fast', seq: 4 }
+        })
+        expect(seen.at(-1)).toBe('fast:message.delta:4')
+
+        if (fallback === 'timeout') {
+          // The replay deadline is bounded independently of the 120s RPC default.
+          await vi.advanceTimersByTimeAsync(9_999)
+          expect(slowSettled).not.toHaveBeenCalled()
+          await vi.advanceTimersByTimeAsync(1)
+        } else {
+          sockets[1].serverFrame({
+            jsonrpc: '2.0',
+            id: slowRequest.id,
+            error: { code: -32601, message: 'method not found' }
+          })
+        }
+
+        await expect(slow).resolves.toBe(true)
+        expect(seen.at(-1)).toBe('slow:message.start:2')
+        expect(client.sessionReplayBarrier('slow')).toBeUndefined()
+        // Late replies after fallback cannot resurrect the old replay window.
+        sockets[1].serverFrame({
+          jsonrpc: '2.0',
+          id: slowRequest.id,
+          result: {
+            events: [{ type: 'message.delta', session_id: 'slow', seq: 99 }]
+          }
+        })
+        await Promise.resolve()
+        expect(client.getSeqWatermarks()).toEqual({ slow: 2, fast: 4, new: 1 })
+      } finally {
+        client.close()
+        vi.useRealTimers()
+      }
+    }
+  )
+
+  it.each(['ready', 'response'] as const)(
+    'revokes old epoch barriers via %s without dropping parked fresh events',
+    async via => {
+      const client = makeClient()
+      const seen: number[] = []
+      client.on('message.delta', event => seen.push(event.seq!))
+
+      try {
+        const first = client.connect('ws://x')
+        sockets[0].open()
+        await first
+        sockets[0].serverFrame({
+          jsonrpc: '2.0',
+          method: 'event',
+          params: { type: 'gateway.ready', payload: { replay_epoch: 'A' } }
+        })
+
+        for (const sid of ['s1', 's2']) {
+          sockets[0].serverFrame({
+            jsonrpc: '2.0',
+            method: 'event',
+            params: { type: 'message.delta', session_id: sid, seq: 97 }
+          })
+        }
+
+        client.invalidate()
+        const second = client.connect('ws://x')
+        sockets[1].open()
+        await second
+        const barriers = ['s1', 's2'].map(sid => client.sessionReplayBarrier(sid))
+        expect(barriers.every(barrier => barrier instanceof Promise)).toBe(true)
+        const requests = sockets[1].sent.map(text => JSON.parse(text))
+        sockets[1].serverFrame({
+          jsonrpc: '2.0',
+          method: 'event',
+          params: { type: 'message.delta', session_id: 's1', seq: 1 }
+        })
+        expect(seen).toEqual([97, 97])
+
+        if (via === 'ready') {
+          sockets[1].serverFrame({
+            jsonrpc: '2.0',
+            method: 'event',
+            params: { type: 'gateway.ready', payload: { replay_epoch: 'B' } }
+          })
+        } else {
+          sockets[1].serverFrame({ jsonrpc: '2.0', id: requests[0].id, result: { events: [], epoch: 'B' } })
+        }
+
+        await expect(Promise.all(barriers)).resolves.toEqual([false, false])
+        expect(client.sessionReplayBarrier('s1')).toBeUndefined()
+        expect(client.sessionReplayBarrier('s2')).toBeUndefined()
+        expect(seen).toEqual([97, 97, 1])
+        expect(client.getSeqWatermarks()).toEqual({ s1: 1 })
+
+        // Neither a late old-epoch response nor its cleanup can restore A.
+        for (const request of requests) {
+          sockets[1].serverFrame({
+            jsonrpc: '2.0',
+            id: request.id,
+            result: {
+              events: [{ type: 'message.delta', session_id: request.params.session_id, seq: 98 }],
+              epoch: 'A'
+            }
+          })
+        }
+
+        await Promise.resolve()
+        sockets[1].serverFrame({
+          jsonrpc: '2.0',
+          method: 'event',
+          params: { type: 'message.delta', session_id: 's1', seq: 2 }
+        })
+        expect(seen).toEqual([97, 97, 1, 2])
+        expect(client.getSeqWatermarks()).toEqual({ s1: 2 })
+      } finally {
+        client.close()
+      }
+    }
+  )
+
   it('clears stale watermarks when the backend epoch changes (restart poisoning)', async () => {
     const client = makeClient()
 
diff --git a/apps/shared/src/json-rpc-gateway.ts b/apps/shared/src/json-rpc-gateway.ts
index 71374ee5a3..730d5eec9a 100644
--- a/apps/shared/src/json-rpc-gateway.ts
+++ b/apps/shared/src/json-rpc-gateway.ts
@@ -50,7 +50,9 @@ const DEFAULT_CONNECT_TIMEOUT_MS = 15_000
 
 /** True for a `ws://` / `wss://` URL string — the only thing `JsonRpcGatewayClient.connect()` will dial. */
 export function isGatewayWebSocketUrl(value: unknown): value is string {
-  if (typeof value !== 'string') {return false}
+  if (typeof value !== 'string') {
+    return false
+  }
 
   try {
     const protocol = new URL(value).protocol
@@ -105,6 +107,12 @@ export class GatewayEventHub {
  */
 const socketTransport = (socket: WebSocketLike): JsonRpcTransport => ({ send: text => socket.send(text) })
 
+interface SessionReplay {
+  events: GatewayEvent[]
+  promise: Promise<boolean>
+  resolve: (valid: boolean) => void
+}
+
 export class JsonRpcGatewayClient {
   private socket: WebSocketLike | null = null
   private state: ConnectionState = 'idle'
@@ -112,8 +120,6 @@ export class JsonRpcGatewayClient {
   private readonly events = new GatewayEventHub()
   /** Last observed event seq per session_id — drives lossless reconnect replay. */
   private lastSeenSeq = new Map<string, number>()
-  /** Set while a post-reconnect replay fetch is in flight (dedup guard). */
-  private replayInFlight = false
   /** Invalidates an interrupted replay so its async cleanup cannot own a replacement socket. */
   private replayGeneration = 0
   /**
@@ -123,7 +129,7 @@ export class JsonRpcGatewayClient {
    * twice (once live, once when the replay returns the same seq) or, worse,
    * advances the watermark so the gap events the replay carries get skipped.
    */
-  private replayHold: Map<string, GatewayEvent[]> | null = null
+  private replayHold: Map<string, SessionReplay> | null = null
   /**
    * Server process identity for the replay contract (from gateway.ready /
    * session.events.since). Seq counters are in-process on the backend, so a
@@ -245,12 +251,11 @@ export class JsonRpcGatewayClient {
         settled = true
         cleanup()
         this.channel.attach(transport)
+        // Install session barriers before open listeners can start history
+        // reads. Replay stays fire-and-forget; connect latency is unchanged.
+        this.fetchReplay()
         this.setState('open')
         resolve()
-        // Lossless resume: drain events emitted while we were disconnected.
-        // Fire-and-forget so connect() latency is unaffected; only runs when
-        // we actually observed seq'd events before the drop.
-        void this.fetchReplay()
       }
 
       // Every rejection below names its failure class. The boot overlay renders this message verbatim, and
@@ -396,7 +401,13 @@ export class JsonRpcGatewayClient {
       return Promise.reject(new Error(this.options.notConnectedErrorMessage))
     }
 
-    return this.channel.request<T>(method, params, timeoutMs, signal, () => new Error(this.options.notConnectedErrorMessage))
+    return this.channel.request<T>(
+      method,
+      params,
+      timeoutMs,
+      signal,
+      () => new Error(this.options.notConnectedErrorMessage)
+    )
   }
 
   private handleEvent(event: GatewayEvent): void {
@@ -418,7 +429,7 @@ export class JsonRpcGatewayClient {
     if (this.replayHold && sid && typeof seqValue === 'number' && this.replayHold.has(sid)) {
       // Replay in flight for this session: park the frame; flushReplayHold
       // dispatches it after the replayed gap, gated on seq.
-      this.replayHold.get(sid)?.push(event)
+      this.replayHold.get(sid)?.events.push(event)
 
       return
     }
@@ -451,44 +462,75 @@ export class JsonRpcGatewayClient {
     return Object.fromEntries(this.lastSeenSeq)
   }
 
+  /**
+   * Wait for this session's reconnect replay AND parked live frames to dispatch.
+   * True includes bounded timeout/unsupported-method fallback; false means the
+   * socket/epoch owner was lost and a pending history read must be abandoned.
+   * Unobserved sessions and replay-disabled feeds have no barrier.
+   */
+  sessionReplayBarrier(sessionId: string): Promise<boolean> | undefined {
+    const pending = this.replayHold?.get(sessionId)?.promise
+
+    if (pending) {
+      return pending
+    }
+
+    // A history response can beat the replacement connection itself. Don't
+    // publish ahead of a replay that will only be installed on the next open.
+    if (this.options.replay && this.lastSeenSeq.has(sessionId) && this.socket?.readyState !== WebSocket.OPEN) {
+      return Promise.resolve(false)
+    }
+
+    return undefined
+  }
+
   /**
    * After a reconnect, ask the gateway to replay every event newer than our
    * per-session watermarks. Replayed frames go through the SAME dispatchEvent
-   * path as live frames — dedupe happens naturally because recordSeq ignores
-   * non-increasing seqs and downstream stores key on event identity.
+   * path as live frames, gated on seq to avoid dispatching duplicates.
    * Best-effort: failures are swallowed (the next reconnect retries).
    */
-  private async fetchReplay(): Promise<void> {
-    if (!this.options.replay || this.replayInFlight || this.lastSeenSeq.size === 0) {
+  private fetchReplay(): void {
+    if (!this.options.replay || this.replayHold || this.lastSeenSeq.size === 0) {
       return
     }
 
-    this.replayInFlight = true
     const replayGeneration = ++this.replayGeneration
     // Park live frames for the sessions we're about to replay so a frame
     // racing the replay response can't dispatch ahead of (or duplicate) the
     // gap events. Sessions without watermarks are unaffected.
-    const hold = new Map<string, GatewayEvent[]>()
+    const entries = [...this.lastSeenSeq]
+    const hold = new Map<string, SessionReplay>()
 
-    for (const sid of this.lastSeenSeq.keys()) {
-      hold.set(sid, [])
+    for (const [sid] of entries) {
+      let resolve!: (valid: boolean) => void
+
+      const promise = new Promise<boolean>(settle => {
+        resolve = settle
+      })
+
+      hold.set(sid, { events: [], promise, resolve })
     }
 
     this.replayHold = hold
 
-    try {
-      const entries = Object.entries(this.getSeqWatermarks())
+    // A hung background session must not hold a ready session's transcript.
+    for (const [sid, lastSeen] of entries) {
+      void this.fetchSessionReplay(sid, lastSeen, replayGeneration)
+    }
+  }
 
-      // One RPC per known session keeps params flat; sessions are few (<20).
-      const results = await Promise.allSettled(
-        entries.map(([sid, lastSeen]) =>
-          // `open_requests` on the answer are re-delivered by the channel itself.
-          this.request<{ events?: Array<{ type: string; session_id?: string; seq?: number; payload?: unknown }> }>(
-            'session.events.since',
-            { session_id: sid, last_seen: lastSeen },
-            REPLAY_REQUEST_TIMEOUT_MS
-          )
-        )
+  private async fetchSessionReplay(sid: string, lastSeen: number, replayGeneration: number): Promise<void> {
+    if (this.replayGeneration !== replayGeneration) {
+      return
+    }
+
+    try {
+      // `open_requests` on the answer are re-delivered by the channel itself.
+      const result = await this.request<{ events?: GatewayEvent[]; epoch?: string }>(
+        'session.events.since',
+        { session_id: sid, last_seen: lastSeen },
+        REPLAY_REQUEST_TIMEOUT_MS
       )
 
       // The socket that owned this replay was dropped while its requests were
@@ -498,40 +540,38 @@ export class JsonRpcGatewayClient {
         return
       }
 
-      for (const result of results) {
-        if (result.status !== 'fulfilled' || !Array.isArray(result.value?.events)) {
-          continue
+      const epoch = result?.epoch
+
+      if (typeof epoch === 'string' && epoch && this.replayEpoch && epoch !== this.replayEpoch) {
+        // The old cursor no longer describes this process's numbering.
+        this.adoptReplayEpoch(epoch)
+
+        return
+      }
+
+      if (typeof epoch === 'string' && epoch && !this.replayEpoch) {
+        this.replayEpoch = epoch
+      }
+
+      if (!Array.isArray(result?.events)) {
+        return
+      }
+
+      for (const event of result.events) {
+        // Event handlers can synchronously invalidate and replace the socket.
+        if (this.replayGeneration !== replayGeneration) {
+          return
         }
 
-        const epoch = (result.value as { epoch?: unknown }).epoch
-
-        if (typeof epoch === 'string' && epoch && this.replayEpoch && epoch !== this.replayEpoch) {
-          // Backend restarted: its seq numbering reset, so our watermarks —
-          // and this replay window — are meaningless. Drop them and start
-          // fresh under the new epoch.
-          this.adoptReplayEpoch(epoch)
-
-          continue
-        }
-
-        if (typeof epoch === 'string' && epoch && !this.replayEpoch) {
-          this.replayEpoch = epoch
-        }
-
-        for (const event of result.value.events) {
-          if (!event?.type) {
-            continue
-          }
-
-          this.dispatchIfNewer({ ...event, replayed: true } as GatewayEvent)
+        if (event?.type) {
+          this.dispatchIfNewer({ ...event, replayed: true })
         }
       }
     } catch {
       // Replay is an optimization over lossy-reconnect; never surface errors.
     } finally {
       if (this.replayGeneration === replayGeneration) {
-        this.flushReplayHold()
-        this.replayInFlight = false
+        this.flushReplayHold(sid, replayGeneration)
       }
     }
   }
@@ -567,27 +607,66 @@ export class JsonRpcGatewayClient {
       return
     }
 
-    if (this.replayEpoch !== null) {
-      this.lastSeenSeq.clear()
-    }
-
+    const changed = this.replayEpoch !== null
     this.replayEpoch = epoch
+
+    if (changed) {
+      this.lastSeenSeq.clear()
+      // Revoke requests/cursors from the old numbering, but retain live
+      // frames already received on this still-open socket.
+      const hold = this.cancelReplay()
+      const generation = this.replayGeneration
+
+      for (const replay of hold?.values() ?? []) {
+        for (const event of replay.events) {
+          if (this.replayGeneration !== generation) {
+            return
+          }
+
+          this.dispatchIfNewer({ ...event, replayed: true })
+        }
+      }
+    }
   }
 
   /** Release frames parked during a replay fetch, seq-gated against dupes. */
-  private flushReplayHold(): void {
-    const hold = this.replayHold
-    this.replayHold = null
+  private flushReplayHold(sid: string, generation: number): void {
+    const replay = this.replayHold?.get(sid)
 
-    if (!hold) {
+    if (!replay) {
       return
     }
 
-    for (const parked of hold.values()) {
-      for (const event of parked) {
-        this.dispatchIfNewer({ ...event, replayed: true })
-      }
+    // Keep the barrier visible through dispatch, including synchronous live
+    // frames emitted by a handler. Remove consumed frames before callbacks
+    // can revoke this epoch and flush the remainder.
+    while (this.replayGeneration === generation && replay.events.length) {
+      this.dispatchIfNewer({ ...replay.events.shift()!, replayed: true })
     }
+
+    if (this.replayGeneration !== generation) {
+      return
+    }
+
+    this.replayHold?.delete(sid)
+
+    if (this.replayHold?.size === 0) {
+      this.replayHold = null
+    }
+
+    replay.resolve(true)
+  }
+
+  private cancelReplay(): Map<string, SessionReplay> | null {
+    const hold = this.replayHold
+    this.replayGeneration += 1
+    this.replayHold = null
+
+    for (const replay of hold?.values() ?? []) {
+      replay.resolve(false)
+    }
+
+    return hold
   }
 
   /** Forget the current socket generation, fail its calls, and go 'closed'. */
@@ -595,9 +674,7 @@ export class JsonRpcGatewayClient {
     // A replay belongs to the socket that started it. Detaching that socket
     // rejects its requests asynchronously, so clear its ownership now; the
     // next open can immediately schedule a replay of its own.
-    this.replayGeneration += 1
-    this.replayInFlight = false
-    this.replayHold = null
+    this.cancelReplay()
     this.socket = null
     this.channel.detach(error)
     this.setState('closed')

From 9e664181dd521ff94d4da72b427436df4d8dfbea Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:09:03 -0700
Subject: [PATCH 53/61] test: trim salvage tests to invariants

Keep the two files that pin the ordering contract: the shared client's
replay barrier (installed before open listeners run, resolves only after
replayed and parked frames dispatch, false when its socket is lost) and
the warm-resume ordering. Drop the renderer hydration suite and the
formatting-only churn in the replay test; the barrier contract they
exercised is covered at the client boundary.
---
 .../contrib/hooks/replay-hydration.test.tsx   | 312 ---------------
 .../hooks/warm-resume-replay-barrier.test.tsx |  19 -
 .../src/json-rpc-gateway-replay.test.ts       | 368 +-----------------
 3 files changed, 18 insertions(+), 681 deletions(-)
 delete mode 100644 apps/desktop/src/app/contrib/hooks/replay-hydration.test.tsx

diff --git a/apps/desktop/src/app/contrib/hooks/replay-hydration.test.tsx b/apps/desktop/src/app/contrib/hooks/replay-hydration.test.tsx
deleted file mode 100644
index cdf8c4afcd..0000000000
--- a/apps/desktop/src/app/contrib/hooks/replay-hydration.test.tsx
+++ /dev/null
@@ -1,312 +0,0 @@
-import { type GatewayEvent, JsonRpcGatewayClient } from '@hermes/shared'
-import { act, cleanup, waitFor } from '@testing-library/react'
-import { afterEach, expect, it, vi } from 'vitest'
-
-import type { ClientSessionState } from '@/app/types'
-import { getLatestSessionMessages } from '@/hermes'
-import { chatMessageText } from '@/lib/chat-messages'
-import { createClientSessionState } from '@/lib/chat-runtime'
-import { setPrimaryGateway } from '@/store/gateway'
-import { setActiveSessionId, setBusy, setSelectedStoredSessionId } from '@/store/session'
-import { clearAllSessionStates, publishSessionState } from '@/store/session-states'
-
-import { renderMessageStream } from '../../session/hooks/use-message-stream/test-harness'
-
-import {
-  hydrateStoredSessionTranscript,
-  reconcileActiveTranscript,
-  reconcileTileTranscripts
-} from './use-background-sync'
-
-vi.mock('@/hermes', async original => ({
-  ...(await original<Record<string, unknown>>()),
-  getLatestSessionMessages: vi.fn()
-}))
-
-const sid = 'replay-hydration-runtime'
-const stored = 'replay-hydration-stored'
-
-class Socket extends EventTarget {
-  readyState = 0
-  sent: { id: string; method: string; params: Record<string, unknown> }[] = []
-  send(data: string) {
-    this.sent.push(JSON.parse(data))
-  }
-  close() {
-    this.readyState = 3
-    this.dispatchEvent(new CloseEvent('close'))
-  }
-  open() {
-    this.readyState = 1
-    this.dispatchEvent(new Event('open'))
-  }
-  frame(frame: unknown) {
-    this.dispatchEvent(new MessageEvent('message', { data: JSON.stringify(frame) }))
-  }
-  event(event: GatewayEvent) {
-    this.frame({ jsonrpc: '2.0', method: 'event', params: event })
-  }
-}
-
-function event(seq: number, type: GatewayEvent['type'], payload: Record<string, unknown> = {}): GatewayEvent {
-  return { session_id: sid, seq, type, payload: { timestamp: seq, ...payload } } as GatewayEvent
-}
-
-async function setup(surface: 'active' | 'tile' | 'fallback') {
-  setActiveSessionId(surface === 'tile' ? 'another-runtime' : sid)
-  setSelectedStoredSessionId(stored)
-  const states = new Map<string, ClientSessionState>()
-
-  const updateSessionState = (id: string, updater: (state: ClientSessionState) => ClientSessionState) => {
-    const next = updater(states.get(id) ?? createClientSessionState(stored))
-    states.set(id, next)
-    publishSessionState(id, next)
-
-    return next
-  }
-
-  const stream = renderMessageStream(sid, { states, updateSessionState })
-  const sockets: Socket[] = []
-
-  const client = new JsonRpcGatewayClient({
-    heartbeatIntervalMs: 0,
-    heartbeatDeadlineMs: 0,
-    socketFactory: () => {
-      const socket = new Socket()
-      sockets.push(socket)
-
-      return socket as unknown as WebSocket
-    }
-  })
-
-  setPrimaryGateway(client)
-  client.onEvent(stream.handleEvent)
-
-  const connect = async () => {
-    const promise = client.connect('ws://fixture.test')
-    const socket = sockets.at(-1)!
-    socket.open()
-    await promise
-
-    return socket
-  }
-
-  const first = await connect()
-  act(() => first.event(event(1, 'session.info', { running: false })))
-  client.invalidate()
-  const second = await connect()
-  const request = second.sent.find(item => item.method === 'session.events.since')!
-  expect(request.params.last_seen).toBe(1)
-  const signatureRef = { current: new Map<string, string>() }
-  const requestSequenceRef = { current: 0 }
-  const activeSessionIdRef = { current: sid }
-  const selectedStoredSessionIdRef = { current: stored }
-
-  const refresh = () =>
-    surface === 'tile'
-      ? reconcileTileTranscripts({
-          tiles: [{ storedSessionId: stored, runtimeId: sid }],
-          signatureRef,
-          requestSequenceRef,
-          updateSessionState
-        })
-      : surface === 'fallback'
-        ? hydrateStoredSessionTranscript({
-            attempts: 1,
-            storedSessionId: stored,
-            runtimeSessionId: sid,
-            storedProfile: 'default',
-            updateSessionState
-          })
-        : reconcileActiveTranscript({
-            activeSessionIdRef,
-            selectedStoredSessionIdRef,
-            busyRef: { current: false },
-            requestSequenceRef,
-            signatureRef,
-            resolveSession: () => ({ profile: 'default' }),
-            updateSessionState
-          })
-
-  return { client, stream, refresh, second, request, connect, activeSessionIdRef, selectedStoredSessionIdRef }
-}
-
-const replay = [
-  event(2, 'message.start'),
-  event(3, 'message.delta', { text: 'Earlier progress.' }),
-  event(4, 'message.interim', { text: 'Earlier progress.', already_streamed: true }),
-  event(5, 'tool.start', { name: 'read_file', tool_id: 'old-call', args: { path: 'example.py' } }),
-  event(6, 'tool.complete', { name: 'read_file', tool_id: 'old-call', result: 'fixture contents' }),
-  event(7, 'message.delta', { text: 'Finished result.' }),
-  event(8, 'message.complete', { text: 'Finished result.' }),
-  event(9, 'session.info', { running: false })
-]
-
-function stubHistory() {
-  vi.mocked(getLatestSessionMessages).mockResolvedValue({
-    session_id: stored,
-    messages: [
-      { id: 1, role: 'user', content: 'Review example', timestamp: 1 },
-      {
-        id: 2,
-        role: 'assistant',
-        content: 'Earlier progress.',
-        timestamp: 2,
-        tool_calls: [
-          { id: 'old-call', type: 'function', function: { name: 'read_file', arguments: '{"path":"example.py"}' } }
-        ]
-      },
-      {
-        id: 3,
-        role: 'tool',
-        content: 'fixture contents',
-        timestamp: 3,
-        tool_call_id: 'old-call',
-        tool_name: 'read_file'
-      },
-      { id: 4, role: 'assistant', content: 'Finished result.', timestamp: 4 }
-    ]
-  })
-}
-
-afterEach(() => {
-  cleanup()
-  clearAllSessionStates()
-  setPrimaryGateway(null)
-  setActiveSessionId(null)
-  setSelectedStoredSessionId(null)
-  setBusy(false)
-  vi.mocked(getLatestSessionMessages).mockReset()
-})
-
-it.each(['active', 'tile', 'fallback'] as const)(
-  'orders %s history after full replay without duplicate turns',
-  async surface => {
-    const { client, stream, refresh, second, request } = await setup(surface)
-
-    try {
-      stubHistory()
-      let pending!: Promise<void>
-      await act(async () => {
-        pending = refresh()
-      })
-      // The database is already complete; publishing it ahead of the replay is
-      // precisely the race. Do not issue the read until this session catches up.
-      expect(getLatestSessionMessages).not.toHaveBeenCalled()
-      await act(async () => {
-        second.frame({ id: request.id, jsonrpc: '2.0', result: { events: replay } })
-        await pending
-      })
-      const texts = stream.state().messages.map(chatMessageText).join('\n')
-
-      expect(texts.match(/Earlier progress\./g)).toHaveLength(1)
-      expect(texts.match(/Finished result\./g)).toHaveLength(1)
-      expect(texts).toContain('Review example')
-      expect(stream.state().busy).toBe(false)
-    } finally {
-      client.close()
-    }
-  }
-)
-
-it('keeps an unseen live turn parked behind replay instead of painting an idle snapshot over it', async () => {
-  const { client, stream, refresh, second, request } = await setup('active')
-
-  try {
-    stubHistory()
-    let pending!: Promise<void>
-    await act(async () => {
-      pending = refresh()
-    })
-    act(() => {
-      second.event(event(10, 'message.start'))
-      second.event(event(11, 'message.delta', { text: 'New work.' }))
-    })
-    await act(async () => {
-      second.frame({ id: request.id, jsonrpc: '2.0', result: { events: replay } })
-      await pending
-    })
-    expect(getLatestSessionMessages).not.toHaveBeenCalled()
-    expect(stream.state().busy).toBe(true)
-    // Replay dispatch does not flush the renderer's coalesced delta timer.
-    await waitFor(() => expect(stream.state().messages.map(chatMessageText).join('\n')).toContain('New work.'))
-  } finally {
-    client.close()
-  }
-})
-
-it('abandons a queued history read when its replay socket is invalidated', async () => {
-  const { client, refresh } = await setup('active')
-  stubHistory()
-  let pending!: Promise<void>
-  await act(async () => {
-    pending = refresh()
-  })
-  await act(async () => {
-    client.invalidate()
-    await pending
-  })
-  expect(getLatestSessionMessages).not.toHaveBeenCalled()
-  client.close()
-})
-
-it('does not follow a stale selection after waiting for replay', async () => {
-  const { client, refresh, second, request, selectedStoredSessionIdRef } = await setup('active')
-
-  try {
-    stubHistory()
-    let pending!: Promise<void>
-    await act(async () => {
-      pending = refresh()
-    })
-    selectedStoredSessionIdRef.current = 'another-session'
-    await act(async () => {
-      second.frame({ id: request.id, jsonrpc: '2.0', result: { events: replay } })
-      await pending
-    })
-    expect(getLatestSessionMessages).not.toHaveBeenCalled()
-  } finally {
-    client.close()
-  }
-})
-
-it('checks replay again when a socket reconnects during an existing history read', async () => {
-  const { client, stream, refresh, second, request, connect } = await setup('active')
-
-  try {
-    await act(async () => second.frame({ id: request.id, jsonrpc: '2.0', result: { events: [] } }))
-    stubHistory()
-    const snapshot = await getLatestSessionMessages(stored)
-    vi.mocked(getLatestSessionMessages).mockReset()
-    let release!: () => void
-    vi.mocked(getLatestSessionMessages).mockReturnValue(
-      new Promise(resolve => {
-        release = () => resolve(snapshot)
-      })
-    )
-    let pending!: Promise<void>
-    await act(async () => {
-      pending = refresh()
-    })
-    expect(getLatestSessionMessages).toHaveBeenCalledTimes(1)
-    client.invalidate()
-    const next = await connect()
-    const replayRequest = next.sent.find(item => item.method === 'session.events.since')!
-    await act(async () => {
-      release()
-    })
-    // The held REST result must not paint a completed turn ahead of replay.
-    expect(stream.state().messages.map(chatMessageText).join('\n')).not.toContain('Finished result.')
-    await act(async () => {
-      next.frame({ id: replayRequest.id, jsonrpc: '2.0', result: { events: replay } })
-      await pending
-    })
-    stubHistory()
-    await act(refresh)
-    const text = stream.state().messages.map(chatMessageText).join('\n')
-    expect(text).toContain('Review example')
-    expect(text.match(/Finished result\./g)).toHaveLength(1)
-  } finally {
-    client.close()
-  }
-})
diff --git a/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx b/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
index 78d1916fde..42702125d9 100644
--- a/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
+++ b/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
@@ -245,22 +245,3 @@ it('waits for reconnect replay before activating and reading warm history', asyn
     client.close()
   }
 })
-
-it('abandons a warm resume whose replay socket is invalidated', async () => {
-  const { result, client, requestGateway } = await mountWithPendingReplay()
-
-  try {
-    let pending!: Promise<void>
-    await act(async () => {
-      pending = result.current.actions.resumeSession(storedId, true)
-    })
-    await act(async () => {
-      client.invalidate()
-      await pending
-    })
-    expect(activateCalls(requestGateway)).toHaveLength(0)
-    expect(getLatestSessionMessages).not.toHaveBeenCalled()
-  } finally {
-    client.close()
-  }
-})
diff --git a/apps/shared/src/json-rpc-gateway-replay.test.ts b/apps/shared/src/json-rpc-gateway-replay.test.ts
index af221edacf..c45e8e1e23 100644
--- a/apps/shared/src/json-rpc-gateway-replay.test.ts
+++ b/apps/shared/src/json-rpc-gateway-replay.test.ts
@@ -48,9 +48,8 @@ class FakeWebSocket extends EventTarget {
 
 let sockets: FakeWebSocket[]
 
-const makeClient = (replay = true) => {
+const makeClient = () => {
   const client = new JsonRpcGatewayClient({
-    replay,
     socketFactory: url => new FakeWebSocket(url) as unknown as WebSocket,
     heartbeatIntervalMs: 0,
     heartbeatDeadlineMs: 0,
@@ -72,21 +71,9 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     sockets[0].open()
     await p
 
-    sockets[0].serverFrame({
-      jsonrpc: '2.0',
-      method: 'event',
-      params: { type: 'message.delta', session_id: 's1', seq: 4 }
-    })
-    sockets[0].serverFrame({
-      jsonrpc: '2.0',
-      method: 'event',
-      params: { type: 'message.delta', session_id: 's1', seq: 2 }
-    }) // out of order / late
-    sockets[0].serverFrame({
-      jsonrpc: '2.0',
-      method: 'event',
-      params: { type: 'tool.start', session_id: 's2', seq: 9 }
-    })
+    sockets[0].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'message.delta', session_id: 's1', seq: 4 } })
+    sockets[0].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'message.delta', session_id: 's1', seq: 2 } }) // out of order / late
+    sockets[0].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'tool.start', session_id: 's2', seq: 9 } })
     sockets[0].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'skin.changed' } }) // no sid/seq
 
     expect(client.getSeqWatermarks()).toEqual({ s1: 4, s2: 9 })
@@ -163,31 +150,19 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     client.close()
   })
 
-  it.each([true, false])('has no replay barrier without watermarks or with replay disabled (%s)', async replay => {
-    const client = makeClient(replay)
-    expect(client.sessionReplayBarrier('s1')).toBeUndefined()
+  it('does not attempt replay when nothing was ever observed', async () => {
+    const client = makeClient()
     const p = client.connect('ws://x')
     sockets[0].open()
     await p
-
-    if (!replay) {
-      sockets[0].serverFrame({
-        jsonrpc: '2.0',
-        method: 'event',
-        params: { type: 'message.delta', session_id: 's1', seq: 1 }
-      })
-    }
-
-    // No watermarks, or explicitly disabled replay, must not create a barrier.
+    // No events ever seen → close+reconnect must NOT fire a replay RPC.
     client.invalidate('drop')
-    expect(client.sessionReplayBarrier('s1')).toBeUndefined()
     const p2 = client.connect('ws://x')
     sockets[sockets.length - 1].open()
     await p2
     await new Promise(r => setTimeout(r, 20))
 
     expect(sockets[sockets.length - 1].sent).toHaveLength(0)
-    expect(client.sessionReplayBarrier('s1')).toBeUndefined()
     client.close()
   })
 
@@ -213,12 +188,7 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     sock.serverFrame({
       jsonrpc: '2.0',
       id: req.id,
-      result: {
-        events: [{ type: 'status.update', session_id: 's1', seq: 2 }],
-        latest_seq: 10,
-        truncated: false,
-        count: 1
-      }
+      result: { events: [{ type: 'status.update', session_id: 's1', seq: 2 }], latest_seq: 10, truncated: false, count: 1 }
     })
     await Promise.resolve()
     expect(client.getSeqWatermarks().s1).toBe(10)
@@ -282,14 +252,10 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     let openBarrier: Promise<boolean> | undefined
     client.onState(state => {
       if (state === 'open') {
-        openBarrier = client.sessionReplayBarrier?.('s1')
-        // A synchronous open listener must not advance the watermark ahead
-        // of the gap, even before connect() returns to its caller.
-        sock.serverFrame({
-          jsonrpc: '2.0',
-          method: 'event',
-          params: { type: 'message.delta', session_id: 's1', seq: 5 }
-        })
+        // Synchronous open listeners start history reads; the barrier must
+        // already exist, and a live frame here must not beat the gap.
+        openBarrier = client.sessionReplayBarrier('s1')
+        sock.serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'message.delta', session_id: 's1', seq: 5 } })
       }
     })
     const second = client.connect('ws://x')
@@ -298,11 +264,11 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     await second
 
     expect(openBarrier).toBeInstanceOf(Promise)
-    expect(client.sessionReplayBarrier('s1')).toBe(openBarrier)
     expect(client.sessionReplayBarrier('unobserved')).toBeUndefined()
     let settled = false
 
     const barrierChecked = openBarrier!.then(valid => {
+      // Resolves only after replayed AND parked frames have dispatched.
       expect(valid).toBe(true)
       expect(seen).toEqual([2, 3, 4, 5, 6])
       settled = true
@@ -343,7 +309,6 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
       expect(seen).toEqual([2, 3, 4, 5, 6])
     })
     await barrierChecked
-    expect(settled).toBe(true)
     expect(client.sessionReplayBarrier('s1')).toBeUndefined()
     expect(client.getSeqWatermarks().s1).toBe(6)
     client.close()
@@ -357,23 +322,16 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     const first = client.connect('ws://x')
     sockets[0].open()
     await first
-    sockets[0].serverFrame({
-      jsonrpc: '2.0',
-      method: 'event',
-      params: { type: 'message.delta', session_id: 's1', seq: 1 }
-    })
+    sockets[0].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'message.delta', session_id: 's1', seq: 1 } })
 
     client.invalidate('first drop')
     // History can arrive in the disconnected gap, before any replay exists.
     await expect(client.sessionReplayBarrier('s1')).resolves.toBe(false)
-    expect(client.sessionReplayBarrier('unobserved')).toBeUndefined()
     const second = client.connect('ws://x')
-    await expect(client.sessionReplayBarrier('s1')).resolves.toBe(false)
     sockets[1].open()
     await second
     await vi.waitFor(() => expect(sockets[1].lastRequest().method).toBe('session.events.since'))
     const oldBarrier = client.sessionReplayBarrier('s1')
-    expect(oldBarrier).toBeInstanceOf(Promise)
 
     // The old request rejects asynchronously after detach. Open the
     // replacement before its cleanup runs; it must own a fresh replay.
@@ -382,10 +340,10 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     sockets[2].open()
     const replacementBarrier = client.sessionReplayBarrier('s1')
     await third
+    // A read waiting on the lost socket is abandoned; the replacement owns a new barrier.
     await expect(oldBarrier).resolves.toBe(false)
     expect(replacementBarrier).toBeInstanceOf(Promise)
     expect(replacementBarrier).not.toBe(oldBarrier)
-    expect(client.sessionReplayBarrier('s1')).toBe(replacementBarrier)
     await vi.waitFor(() => expect(sockets[2].lastRequest().method).toBe('session.events.since'))
 
     const request = sockets[2].lastRequest()
@@ -394,312 +352,22 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     // A live frame racing the new replay is parked by the NEW hold; the stale
     // replay's cleanup must neither flush it nor advance the watermark past
     // the gap it never recovered.
-    sockets[2].serverFrame({
-      jsonrpc: '2.0',
-      method: 'event',
-      params: { type: 'message.delta', session_id: 's1', seq: 3 }
-    })
+    sockets[2].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'message.delta', session_id: 's1', seq: 3 } })
     await Promise.resolve()
     expect(seen).toEqual([1])
     expect(client.getSeqWatermarks()).toEqual({ s1: 1 })
 
     sockets[2].serverFrame({
-      jsonrpc: '2.0',
-      id: request.id,
-      result: {
-        events: [{ type: 'message.delta', session_id: 's1', seq: 2 }],
-        latest_seq: 2,
-        truncated: false,
-        count: 1
-      }
+      jsonrpc: '2.0', id: request.id,
+      result: { events: [{ type: 'message.delta', session_id: 's1', seq: 2 }], latest_seq: 2, truncated: false, count: 1 }
     })
 
     await vi.waitFor(() => expect(seen).toEqual([1, 2, 3]))
     await expect(replacementBarrier).resolves.toBe(true)
-    expect(client.sessionReplayBarrier('s1')).toBeUndefined()
     expect(client.getSeqWatermarks()).toEqual({ s1: 3 })
     client.close()
   })
 
-  it.each(['replay', 'parked'] as const)(
-    'keeps replacement ownership when a %s handler invalidates its socket',
-    async invalidateDuring => {
-      const client = makeClient()
-
-      try {
-        const first = client.connect('ws://x')
-        sockets[0].open()
-        await first
-        sockets[0].serverFrame({
-          jsonrpc: '2.0',
-          method: 'event',
-          params: { type: 'message.delta', session_id: 's1', seq: 1 }
-        })
-        client.invalidate()
-        const second = client.connect('ws://x')
-        sockets[1].open()
-        await second
-        const oldBarrier = client.sessionReplayBarrier('s1')!
-        const seen: number[] = []
-        let replacement: Promise<void> | undefined
-        let replacementBarrier: Promise<boolean> | undefined
-        const invalidateAt = invalidateDuring === 'replay' ? 2 : 3
-        client.on('message.delta', event => {
-          seen.push(event.seq!)
-
-          if (event.seq === invalidateAt) {
-            expect(client.sessionReplayBarrier('s1')).toBe(oldBarrier)
-            client.invalidate()
-            replacement = client.connect('ws://x')
-            sockets[2].open()
-            replacementBarrier = client.sessionReplayBarrier('s1')
-            sockets[2].serverFrame({
-              jsonrpc: '2.0',
-              method: 'event',
-              params: { type: 'message.delta', session_id: 's1', seq: 6 }
-            })
-          }
-        })
-
-        for (const seq of [3, 4]) {
-          sockets[1].serverFrame({
-            jsonrpc: '2.0',
-            method: 'event',
-            params: { type: 'message.delta', session_id: 's1', seq }
-          })
-        }
-
-        sockets[1].serverFrame({
-          jsonrpc: '2.0',
-          id: sockets[1].lastRequest().id,
-          result: {
-            events: (invalidateDuring === 'replay' ? [2, 3] : [2]).map(seq => ({
-              type: 'message.delta',
-              session_id: 's1',
-              seq
-            }))
-          }
-        })
-        await expect(oldBarrier).resolves.toBe(false)
-        await replacement
-        expect(client.sessionReplayBarrier('s1')).toBe(replacementBarrier)
-        expect(seen).toEqual(invalidateDuring === 'replay' ? [2] : [2, 3])
-        const request = sockets[2].lastRequest()
-        expect(request.params.last_seen).toBe(invalidateAt)
-        sockets[2].serverFrame({
-          jsonrpc: '2.0',
-          id: request.id,
-          result: {
-            events: [{ type: 'message.delta', session_id: 's1', seq: 5 }]
-          }
-        })
-        await expect(replacementBarrier).resolves.toBe(true)
-        expect(seen).toEqual(invalidateDuring === 'replay' ? [2, 5, 6] : [2, 3, 5, 6])
-      } finally {
-        client.close()
-      }
-    }
-  )
-
-  it.each(['timeout', 'unsupported'] as const)(
-    'settles sessions independently and releases fresh frames on replay %s',
-    async fallback => {
-      vi.useFakeTimers()
-      const client = makeClient()
-      const seen: string[] = []
-      client.onEvent(event => seen.push(`${event.session_id}:${event.type}:${event.seq}`))
-
-      try {
-        const first = client.connect('ws://x')
-        sockets[0].open()
-        await first
-
-        sockets[0].serverFrame({
-          jsonrpc: '2.0',
-          method: 'event',
-          params: { type: 'gateway.ready', payload: { replay_epoch: 'stable' } }
-        })
-
-        for (const sid of ['slow', 'fast']) {
-          sockets[0].serverFrame({
-            jsonrpc: '2.0',
-            method: 'event',
-            params: { type: 'session.info', session_id: sid, seq: 1 }
-          })
-        }
-
-        seen.length = 0
-        client.invalidate()
-        const second = client.connect('ws://x')
-        sockets[1].open()
-        await second
-        const slow = client.sessionReplayBarrier('slow')!
-        const fast = client.sessionReplayBarrier('fast')!
-        expect(slow).toBeInstanceOf(Promise)
-        expect(fast).toBeInstanceOf(Promise)
-        const requests = sockets[1].sent.map(text => JSON.parse(text))
-        const slowRequest = requests.find(request => request.params.session_id === 'slow')
-        const fastRequest = requests.find(request => request.params.session_id === 'fast')
-        const slowSettled = vi.fn()
-        void slow.then(slowSettled)
-
-        // Both ordinary parked starts and wire-marked replayed starts are fresh.
-        for (const [sid, seq] of [
-          ['slow', 2],
-          ['fast', 3]
-        ] as const) {
-          sockets[1].serverFrame({
-            jsonrpc: '2.0',
-            method: 'event',
-            params: { type: 'message.start', session_id: sid, seq, replayed: sid === 'fast' }
-          })
-        }
-
-        sockets[1].serverFrame({
-          jsonrpc: '2.0',
-          method: 'event',
-          params: { type: 'message.start', session_id: 'new', seq: 1 }
-        })
-        expect(seen).toEqual(['new:message.start:1'])
-
-        const fastSettled = fast.then(valid => {
-          expect(valid).toBe(true)
-          expect(seen).toEqual(['new:message.start:1', 'fast:message.complete:2', 'fast:message.start:3'])
-        })
-
-        sockets[1].serverFrame({
-          jsonrpc: '2.0',
-          id: fastRequest.id,
-          result: {
-            epoch: 'stable',
-            events: [{ type: 'message.complete', session_id: 'fast', seq: 2 }]
-          }
-        })
-        await fastSettled
-        expect(client.sessionReplayBarrier('fast')).toBeUndefined()
-        expect(client.sessionReplayBarrier('slow')).toBe(slow)
-        expect(slowSettled).not.toHaveBeenCalled()
-        sockets[1].serverFrame({
-          jsonrpc: '2.0',
-          method: 'event',
-          params: { type: 'message.delta', session_id: 'fast', seq: 4 }
-        })
-        expect(seen.at(-1)).toBe('fast:message.delta:4')
-
-        if (fallback === 'timeout') {
-          // The replay deadline is bounded independently of the 120s RPC default.
-          await vi.advanceTimersByTimeAsync(9_999)
-          expect(slowSettled).not.toHaveBeenCalled()
-          await vi.advanceTimersByTimeAsync(1)
-        } else {
-          sockets[1].serverFrame({
-            jsonrpc: '2.0',
-            id: slowRequest.id,
-            error: { code: -32601, message: 'method not found' }
-          })
-        }
-
-        await expect(slow).resolves.toBe(true)
-        expect(seen.at(-1)).toBe('slow:message.start:2')
-        expect(client.sessionReplayBarrier('slow')).toBeUndefined()
-        // Late replies after fallback cannot resurrect the old replay window.
-        sockets[1].serverFrame({
-          jsonrpc: '2.0',
-          id: slowRequest.id,
-          result: {
-            events: [{ type: 'message.delta', session_id: 'slow', seq: 99 }]
-          }
-        })
-        await Promise.resolve()
-        expect(client.getSeqWatermarks()).toEqual({ slow: 2, fast: 4, new: 1 })
-      } finally {
-        client.close()
-        vi.useRealTimers()
-      }
-    }
-  )
-
-  it.each(['ready', 'response'] as const)(
-    'revokes old epoch barriers via %s without dropping parked fresh events',
-    async via => {
-      const client = makeClient()
-      const seen: number[] = []
-      client.on('message.delta', event => seen.push(event.seq!))
-
-      try {
-        const first = client.connect('ws://x')
-        sockets[0].open()
-        await first
-        sockets[0].serverFrame({
-          jsonrpc: '2.0',
-          method: 'event',
-          params: { type: 'gateway.ready', payload: { replay_epoch: 'A' } }
-        })
-
-        for (const sid of ['s1', 's2']) {
-          sockets[0].serverFrame({
-            jsonrpc: '2.0',
-            method: 'event',
-            params: { type: 'message.delta', session_id: sid, seq: 97 }
-          })
-        }
-
-        client.invalidate()
-        const second = client.connect('ws://x')
-        sockets[1].open()
-        await second
-        const barriers = ['s1', 's2'].map(sid => client.sessionReplayBarrier(sid))
-        expect(barriers.every(barrier => barrier instanceof Promise)).toBe(true)
-        const requests = sockets[1].sent.map(text => JSON.parse(text))
-        sockets[1].serverFrame({
-          jsonrpc: '2.0',
-          method: 'event',
-          params: { type: 'message.delta', session_id: 's1', seq: 1 }
-        })
-        expect(seen).toEqual([97, 97])
-
-        if (via === 'ready') {
-          sockets[1].serverFrame({
-            jsonrpc: '2.0',
-            method: 'event',
-            params: { type: 'gateway.ready', payload: { replay_epoch: 'B' } }
-          })
-        } else {
-          sockets[1].serverFrame({ jsonrpc: '2.0', id: requests[0].id, result: { events: [], epoch: 'B' } })
-        }
-
-        await expect(Promise.all(barriers)).resolves.toEqual([false, false])
-        expect(client.sessionReplayBarrier('s1')).toBeUndefined()
-        expect(client.sessionReplayBarrier('s2')).toBeUndefined()
-        expect(seen).toEqual([97, 97, 1])
-        expect(client.getSeqWatermarks()).toEqual({ s1: 1 })
-
-        // Neither a late old-epoch response nor its cleanup can restore A.
-        for (const request of requests) {
-          sockets[1].serverFrame({
-            jsonrpc: '2.0',
-            id: request.id,
-            result: {
-              events: [{ type: 'message.delta', session_id: request.params.session_id, seq: 98 }],
-              epoch: 'A'
-            }
-          })
-        }
-
-        await Promise.resolve()
-        sockets[1].serverFrame({
-          jsonrpc: '2.0',
-          method: 'event',
-          params: { type: 'message.delta', session_id: 's1', seq: 2 }
-        })
-        expect(seen).toEqual([97, 97, 1, 2])
-        expect(client.getSeqWatermarks()).toEqual({ s1: 2 })
-      } finally {
-        client.close()
-      }
-    }
-  )
-
   it('clears stale watermarks when the backend epoch changes (restart poisoning)', async () => {
     const client = makeClient()
 

From bb7788c6266050d5147add58d4ac96193b76b363 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:09:03 -0700
Subject: [PATCH 54/61] fix(desktop): let history reads proceed when the replay
 epoch changes

A backend restart announces a new replay_epoch over the still-open
socket (gateway.ready or the replay response). adoptReplayEpoch revoked
the pending replay holds by resolving their barriers false, which every
caller treats as "socket lost, abandon the read". Nothing re-arms that
read: the socket never dropped, so no new open follows. The reconnect
backstop read (#94779) was silently discarded and turns the old backend
committed while Desktop was disconnected never reached the transcript.

On an epoch change no replay can cover the old numbering, so REST is the
only recovery left: resolve the waiting barriers true. Their
continuations still run after the parked live frames dispatch. Socket
invalidation keeps resolving false, since the next open re-reads.
---
 .../src/json-rpc-gateway-replay.test.ts       | 59 +++++++++++++++++++
 apps/shared/src/json-rpc-gateway.ts           | 19 +++---
 2 files changed, 71 insertions(+), 7 deletions(-)

diff --git a/apps/shared/src/json-rpc-gateway-replay.test.ts b/apps/shared/src/json-rpc-gateway-replay.test.ts
index c45e8e1e23..89316692ec 100644
--- a/apps/shared/src/json-rpc-gateway-replay.test.ts
+++ b/apps/shared/src/json-rpc-gateway-replay.test.ts
@@ -368,6 +368,65 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     client.close()
   })
 
+  // A backend restart announces a new epoch over the still-open socket. No
+  // replay can cover the old numbering, so waiting history reads must proceed
+  // (the reconnect backstop read, #94779) instead of being silently dropped.
+  it.each(['ready', 'response'] as const)(
+    'lets waiting history reads proceed when %s announces a new epoch, after parked frames',
+    async via => {
+      const client = makeClient()
+      const seen: number[] = []
+      client.on('message.delta', event => seen.push(event.seq!))
+
+      try {
+        const first = client.connect('ws://x')
+        sockets[0].open()
+        await first
+        sockets[0].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'gateway.ready', payload: { replay_epoch: 'A' } } })
+
+        for (const sid of ['s1', 's2']) {
+          sockets[0].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'message.delta', session_id: sid, seq: 97 } })
+        }
+
+        client.invalidate()
+        const second = client.connect('ws://x')
+        sockets[1].open()
+        await second
+        const barriers = ['s1', 's2'].map(sid => client.sessionReplayBarrier(sid))
+        const requests = sockets[1].sent.map(text => JSON.parse(text))
+        // A fresh live frame parked behind the replay must survive the revoke.
+        sockets[1].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'message.delta', session_id: 's1', seq: 1 } })
+        expect(seen).toEqual([97, 97])
+
+        const seenAtResolve = Promise.all(barriers).then(valid => ({ valid, seen: [...seen] }))
+
+        if (via === 'ready') {
+          sockets[1].serverFrame({ jsonrpc: '2.0', method: 'event', params: { type: 'gateway.ready', payload: { replay_epoch: 'B' } } })
+        } else {
+          sockets[1].serverFrame({ jsonrpc: '2.0', id: requests[0].id, result: { events: [], epoch: 'B' } })
+        }
+
+        await expect(seenAtResolve).resolves.toEqual({ valid: [true, true], seen: [97, 97, 1] })
+        expect(client.sessionReplayBarrier('s1')).toBeUndefined()
+        expect(client.getSeqWatermarks()).toEqual({ s1: 1 })
+
+        // A late old-epoch response cannot restore the revoked window.
+        for (const request of requests) {
+          sockets[1].serverFrame({
+            jsonrpc: '2.0',
+            id: request.id,
+            result: { events: [{ type: 'message.delta', session_id: request.params.session_id, seq: 98 }], epoch: 'A' }
+          })
+        }
+
+        await Promise.resolve()
+        expect(seen).toEqual([97, 97, 1])
+      } finally {
+        client.close()
+      }
+    }
+  )
+
   it('clears stale watermarks when the backend epoch changes (restart poisoning)', async () => {
     const client = makeClient()
 
diff --git a/apps/shared/src/json-rpc-gateway.ts b/apps/shared/src/json-rpc-gateway.ts
index 730d5eec9a..c355f12c52 100644
--- a/apps/shared/src/json-rpc-gateway.ts
+++ b/apps/shared/src/json-rpc-gateway.ts
@@ -464,8 +464,10 @@ export class JsonRpcGatewayClient {
 
   /**
    * Wait for this session's reconnect replay AND parked live frames to dispatch.
-   * True includes bounded timeout/unsupported-method fallback; false means the
-   * socket/epoch owner was lost and a pending history read must be abandoned.
+   * True includes bounded timeout/unsupported-method fallback and an epoch
+   * change on the still-open socket (backend restart: nothing will replay, so
+   * REST is authoritative); false means the socket was lost and a pending
+   * history read must be abandoned (the next open re-reads).
    * Unobserved sessions and replay-disabled feeds have no barrier.
    */
   sessionReplayBarrier(sessionId: string): Promise<boolean> | undefined {
@@ -613,8 +615,11 @@ export class JsonRpcGatewayClient {
     if (changed) {
       this.lastSeenSeq.clear()
       // Revoke requests/cursors from the old numbering, but retain live
-      // frames already received on this still-open socket.
-      const hold = this.cancelReplay()
+      // frames already received on this still-open socket. The socket is
+      // still ours and no replay can cover the old numbering, so waiting
+      // history reads proceed: REST is the only recovery left (#94779).
+      // Their continuations run after the parked frames below dispatch.
+      const hold = this.cancelReplay(true)
       const generation = this.replayGeneration
 
       for (const replay of hold?.values() ?? []) {
@@ -657,13 +662,13 @@ export class JsonRpcGatewayClient {
     replay.resolve(true)
   }
 
-  private cancelReplay(): Map<string, SessionReplay> | null {
+  private cancelReplay(readsMayProceed: boolean): Map<string, SessionReplay> | null {
     const hold = this.replayHold
     this.replayGeneration += 1
     this.replayHold = null
 
     for (const replay of hold?.values() ?? []) {
-      replay.resolve(false)
+      replay.resolve(readsMayProceed)
     }
 
     return hold
@@ -674,7 +679,7 @@ export class JsonRpcGatewayClient {
     // A replay belongs to the socket that started it. Detaching that socket
     // rejects its requests asynchronously, so clear its ownership now; the
     // next open can immediately schedule a replay of its own.
-    this.cancelReplay()
+    this.cancelReplay(false)
     this.socket = null
     this.channel.detach(error)
     this.setState('closed')

From 32cf269d9153ff0c2f52ecc6e25e1a9980ae5039 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:09:12 -0700
Subject: [PATCH 55/61] fix(desktop): settle a warm resume through activate
 when replay is lost

The warm path returned before session.activate when its replay barrier
resolved false (socket lost while waiting). That skipped every branch
activate owns: publishDegradedWarmCache on a transport error and the
session-gone fallback to a cold resume. The view was left on an
unrebound warm cache with nothing to recover it.

The barrier only orders the read; it is not evidence about the runtime.
Await it and fall through to activate, which already decides between
degraded cache, cold resume and a normal rebind. A redialed socket's
history publication stays gated by the post-read barrier.
---
 .../hooks/use-session-actions/index.ts        | 13 ++++++--
 .../hooks/warm-resume-replay-barrier.test.tsx | 33 +++++++++++++++++++
 2 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/apps/desktop/src/app/session/hooks/use-session-actions/index.ts b/apps/desktop/src/app/session/hooks/use-session-actions/index.ts
index e87c6acdad..3feafb7f13 100644
--- a/apps/desktop/src/app/session/hooks/use-session-actions/index.ts
+++ b/apps/desktop/src/app/session/hooks/use-session-actions/index.ts
@@ -1293,8 +1293,17 @@ export function useSessionActions({
           try {
             const replay = pendingSessionReplay(cachedRuntimeId)
 
-            if (replay && (!(await replay) || !isCurrentResume())) {
-              return
+            // Only ordering matters here. A lost socket (false) still goes on
+            // to session.activate so its existing branches own the outcome:
+            // degraded warm cache on a transport error, cold resume when the
+            // runtime is gone, or a normal rebind on a redialed socket (whose
+            // history publication is re-gated after the REST read below).
+            if (replay) {
+              await replay
+
+              if (!isCurrentResume()) {
+                return
+              }
             }
 
             let activated: SessionResumeResult | null = null
diff --git a/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx b/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
index 42702125d9..b348449d2c 100644
--- a/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
+++ b/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
@@ -245,3 +245,36 @@ it('waits for reconnect replay before activating and reading warm history', asyn
     client.close()
   }
 })
+
+it('still settles a warm resume through session.activate when its replay socket is lost', async () => {
+  const { result, client, requestGateway } = await mountWithPendingReplay()
+
+  requestGateway.mockImplementation(async (method: string) => {
+    if (method === 'session.activate') {
+      throw new Error('session not found')
+    }
+
+    return snapshot
+  })
+
+  try {
+    let pending!: Promise<void>
+    await act(async () => {
+      pending = result.current.actions.resumeSession(storedId, true)
+    })
+    expect(activateCalls(requestGateway)).toHaveLength(0)
+
+    await act(async () => {
+      client.invalidate()
+      await pending
+    })
+
+    // A lost socket is not proof the runtime is alive or gone: activation
+    // decides, and a gone runtime falls back to a cold resume instead of
+    // leaving the view on an unrebound warm cache.
+    expect(activateCalls(requestGateway)).toHaveLength(1)
+    expect(requestGateway.mock.calls.some(([method]) => method === 'session.resume')).toBe(true)
+  } finally {
+    client.close()
+  }
+})

From 1a0b6ff786aed8f9c0d458f020a6c26bb7c086e6 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:09:22 -0700
Subject: [PATCH 56/61] fix(desktop): hold a reconnect re-resume behind its
 runtime's replay

On reconnect the route re-resumes the selected session. When the warm
mapping is gone (for example a chat started in this window), that is the
cold path: it clears the active runtime, reads REST and paints it, then
binds the runtime from session.resume. With the replay slower than the
REST read, REST painted the finished turn first, the replayed rows then
streamed in as live rows, and the turn showed twice until a later
reconcile (reproduced live in Electron: the final reply and the tool row
each counted 2 in the transcript DOM). The hydration barriers only
guarded background-sync and warm-resume reads, not this one.

Gating only the cold paint is not enough: the replay then lands after
session.resume snapshots the runtime baseline, and its rows are overlaid
as concurrent runtime changes, so the duplicate persists. Instead wait
for the viewed runtime's replay at resume entry, while that runtime
still owns the view, before any read or RPC. Only same-session
re-resumes with a pending replay wait; the barrier is bounded.
---
 .../hooks/use-session-actions/index.ts        | 18 ++++++++-
 .../hooks/warm-resume-replay-barrier.test.tsx | 38 +++++++++++++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/app/session/hooks/use-session-actions/index.ts b/apps/desktop/src/app/session/hooks/use-session-actions/index.ts
index 3feafb7f13..f43d424879 100644
--- a/apps/desktop/src/app/session/hooks/use-session-actions/index.ts
+++ b/apps/desktop/src/app/session/hooks/use-session-actions/index.ts
@@ -1016,13 +1016,29 @@ export function useSessionActions({
       const routeToken = getRouteToken()
       resumeRequestRef.current = requestId
       const resumedSameSelectedSession = selectedStoredSessionIdRef.current === storedSessionId
-      const resumeStartMessages = resumedSameSelectedSession ? $messages.get() : []
 
       const isCurrentResume = () =>
         resumeRequestRef.current === requestId &&
         selectedStoredSessionIdRef.current === storedSessionId &&
         getRouteToken() === routeToken
 
+      // A reconnect re-resumes the runtime this view is streaming. Let its
+      // replay land while that runtime still owns the view. Otherwise the REST
+      // read paints the finished turn first and the replayed rows are then
+      // overlaid onto it as concurrent runtime changes: the turn shows twice.
+      const viewRuntimeId = resumedSameSelectedSession ? activeSessionIdRef.current : null
+      const viewReplay = viewRuntimeId ? pendingSessionReplay(viewRuntimeId) : undefined
+
+      if (viewReplay) {
+        await viewReplay
+
+        if (!isCurrentResume()) {
+          return
+        }
+      }
+
+      const resumeStartMessages = resumedSameSelectedSession ? $messages.get() : []
+
       // Paint the click before the profile-resolve / gateway-swap awaits below,
       // so there's zero dead air: highlight the row instantly (the sidebar reads
       // $selectedStoredSessionId) and, for a cold target, drop the previous
diff --git a/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx b/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
index b348449d2c..c54fd479a7 100644
--- a/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
+++ b/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
@@ -10,6 +10,7 @@ import { resetInFlightTurnJournalStateForTests } from '@/lib/inflight-turn-journ
 import { setPrimaryGateway } from '@/store/gateway'
 import { $activeGatewayProfile } from '@/store/profile'
 import {
+  $messages,
   _resetSessionOwnerHintsForTests,
   setActiveSessionId,
   setAwaitingResponse,
@@ -278,3 +279,40 @@ it('still settles a warm resume through session.activate when its replay socket
     client.close()
   }
 })
+
+it('holds a reconnect re-resume of the selected session behind its replay (cold path)', async () => {
+  const { result, client, requestGateway, second, request } = await mountWithPendingReplay()
+  const { activeSessionIdRef, runtimeIdByStoredSessionIdRef, selectedStoredSessionIdRef } = result.current.cache
+
+  // The view is streaming this runtime, but the warm mapping is gone, so the
+  // route's reconnect re-resume takes the cold REST + session.resume path.
+  selectedStoredSessionIdRef.current = storedId
+  activeSessionIdRef.current = runtimeId
+  runtimeIdByStoredSessionIdRef.current.delete(storedId)
+
+  try {
+    let pending!: Promise<void>
+    await act(async () => {
+      pending = result.current.actions.resumeSession(storedId, true)
+    })
+    expect(getLatestSessionMessages).not.toHaveBeenCalled()
+    expect(requestGateway).not.toHaveBeenCalled()
+
+    await act(async () => {
+      second.frame({ id: request.id, jsonrpc: '2.0', result: { events: replay } })
+      await pending
+    })
+
+    expect(getLatestSessionMessages).toHaveBeenCalledTimes(1)
+    expect(requestGateway.mock.calls.some(([method]) => method === 'session.resume')).toBe(true)
+    expect(
+      $messages
+        .get()
+        .map(chatMessageText)
+        .join('\n')
+        .match(/Finished result\./g)
+    ).toHaveLength(1)
+  } finally {
+    client.close()
+  }
+})

From 04b61d17db0569904534a1f1813e777fed1437fc Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:09:22 -0700
Subject: [PATCH 57/61] fix(desktop): ignore retired secondaries in the replay
 barrier

pendingSessionReplay AND-ed the barrier of every secondary client. A
pruned (wantOpen false) or pool-retired secondary keeps the watermarks of
its closed socket, so its barrier resolves false for any runtime it had
seen, and it will never reopen to replay them. One such client made
every read for that runtime abandon. Only consult clients that can
still reconnect.
---
 apps/desktop/src/store/gateway.ts | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/apps/desktop/src/store/gateway.ts b/apps/desktop/src/store/gateway.ts
index 1c2fe56934..e7f7a10b23 100644
--- a/apps/desktop/src/store/gateway.ts
+++ b/apps/desktop/src/store/gateway.ts
@@ -536,9 +536,12 @@ export function activeGateway(): HermesGateway | null {
 /** Passive ordering barrier for a runtime's transcript reads. Inspect only
  * existing sockets: waiting must never dial, activate, or retain a backend.
  * Each client names its own replaying runtime IDs; no ambient route is used
- * to decide which session's events are safe to paint over. */
+ * to decide which session's events are safe to paint over. A pruned or
+ * pool-retired secondary keeps its closed socket's watermarks but will never
+ * reopen to replay them, so it must not veto reads forever. */
 export function pendingSessionReplay(runtimeId: string): Promise<boolean> | undefined {
-  const clients = new Set([g.primaryGateway, ...[...g.secondaries.values()].map(entry => entry.gateway)])
+  const reconnectable = [...g.secondaries.values()].filter(entry => entry.wantOpen && !entry.retiredByPool)
+  const clients = new Set([g.primaryGateway, ...reconnectable.map(entry => entry.gateway)])
 
   const pending = [...clients].flatMap(client => {
     // A dev-HMR survivor can predate the barrier method.

From 4d58c3a84bd5596483723511cb75e78a880fe6e3 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:39:33 -0700
Subject: [PATCH 58/61] fix(desktop): re-check the replay barrier after a cold
 re-resume REST read

The cold re-resume path waited on the view runtime's replay barrier only
before starting. If the replay socket dropped (barrier false, so the cold
REST read starts) and redialed while that read was in flight, REST painted
the finished turn and the new socket's replay then appended it again: the
turn showed twice.

Mirror the warm path: after the prefetch returns, wait on the view
runtime's barrier again. True means the replay landed first and REST
reconciles onto it; false means the socket was lost again, so the read is
dropped and session.resume binds without painting it.

Review follow-up on #121061.
---
 .../hooks/use-session-actions/index.ts        |  9 ++++
 .../hooks/warm-resume-replay-barrier.test.tsx | 47 ++++++++++++++++++-
 2 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/app/session/hooks/use-session-actions/index.ts b/apps/desktop/src/app/session/hooks/use-session-actions/index.ts
index f43d424879..e67942d39d 100644
--- a/apps/desktop/src/app/session/hooks/use-session-actions/index.ts
+++ b/apps/desktop/src/app/session/hooks/use-session-actions/index.ts
@@ -1805,6 +1805,15 @@ export function useSessionActions({
           // Non-fatal: gateway resume below can still hydrate the session.
         }
 
+        // The socket can drop and redial while REST is in flight. Painting now
+        // would let the new socket's replay append the same turn again; a lost
+        // socket (false) drops this read and the resume below binds without it.
+        const viewReplayAtReturn = viewRuntimeId ? pendingSessionReplay(viewRuntimeId) : undefined
+
+        if (prefetchedResult && viewReplayAtReturn && !(await viewReplayAtReturn)) {
+          prefetchedResult = null
+        }
+
         // A completed read still warms its exact durable scope after navigation.
         // It must not adopt a runtime or touch the foreground on that path.
         if (
diff --git a/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx b/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
index c54fd479a7..db3e3c56d4 100644
--- a/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
+++ b/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
@@ -162,7 +162,7 @@ async function mountWithPendingReplay() {
   const request = second.sent.find(item => item.method === 'session.events.since')!
   expect(request.params).toMatchObject({ session_id: runtimeId, last_seen: 1 })
 
-  return { ...hook, client, requestGateway, second, request }
+  return { ...hook, client, connect, requestGateway, second, request }
 }
 
 beforeEach(() => {
@@ -316,3 +316,48 @@ it('holds a reconnect re-resume of the selected session behind its replay (cold
     client.close()
   }
 })
+
+it('does not paint a cold re-resume read ahead of a replay redialed while REST was in flight', async () => {
+  const { result, client, connect } = await mountWithPendingReplay()
+  const { activeSessionIdRef, runtimeIdByStoredSessionIdRef, selectedStoredSessionIdRef } = result.current.cache
+  let releaseRest!: () => void
+  const restGate = new Promise<void>(resolve => (releaseRest = resolve))
+  const latest = vi.mocked(getLatestSessionMessages).getMockImplementation()!
+  vi.mocked(getLatestSessionMessages).mockImplementation(async (...args) => restGate.then(() => latest(...args)))
+  selectedStoredSessionIdRef.current = storedId
+  activeSessionIdRef.current = runtimeId
+  runtimeIdByStoredSessionIdRef.current.delete(storedId)
+
+  try {
+    let pending!: Promise<void>
+    await act(async () => {
+      pending = result.current.actions.resumeSession(storedId, true)
+    })
+    // The replay socket drops (barrier false: cold resume starts its REST read)
+    // and redials before that read returns, owning a fresh replay of the turn.
+    let third!: Awaited<ReturnType<typeof connect>>
+    await act(async () => {
+      client.invalidate()
+      third = await connect()
+    })
+    expect(getLatestSessionMessages).toHaveBeenCalledTimes(1)
+    const request = third.sent.find(item => item.method === 'session.events.since')!
+
+    await act(async () => {
+      releaseRest()
+      await new Promise(resolve => setTimeout(resolve, 0))
+      third.frame({ id: request.id, jsonrpc: '2.0', result: { events: replay } })
+      await pending
+    })
+
+    expect(
+      $messages
+        .get()
+        .map(chatMessageText)
+        .join('\n')
+        .match(/Finished result\./g)
+    ).toHaveLength(1)
+  } finally {
+    client.close()
+  }
+})

From 716db852fe31571f3b48eaacea153caa29a3156e Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:39:33 -0700
Subject: [PATCH 59/61] test: restore replay-barrier fallback and
 background-sync coverage

Sabotage showed the barrier's bounds were unguarded: making the
timeout/unsupported-method fallback never settle, or lifting the 10s
replay deadline, left every suite green, as did deleting the pre-read
barrier await in reconcileActiveTranscript.

Restore Bear's original timeout/unsupported it.each from 8ee10f65931
(both must resolve true and release parked frames within the bound), and
add one reconcileActiveTranscript case proving a background refresh does
not read REST until the reconnect replay has dispatched.
---
 .../hooks/warm-resume-replay-barrier.test.tsx |  37 ++++++
 .../src/json-rpc-gateway-replay.test.ts       | 118 ++++++++++++++++++
 2 files changed, 155 insertions(+)

diff --git a/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx b/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
index db3e3c56d4..9857fbc9b7 100644
--- a/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
+++ b/apps/desktop/src/app/session/hooks/warm-resume-replay-barrier.test.tsx
@@ -4,6 +4,7 @@ import { act, cleanup, renderHook } from '@testing-library/react'
 import { useRef } from 'react'
 import { afterEach, beforeEach, expect, it, vi } from 'vitest'
 
+import { reconcileActiveTranscript } from '@/app/contrib/hooks/use-background-sync'
 import { getLatestSessionMessages } from '@/hermes'
 import { chatMessageText, toChatMessages } from '@/lib/chat-messages'
 import { resetInFlightTurnJournalStateForTests } from '@/lib/inflight-turn-journal'
@@ -361,3 +362,39 @@ it('does not paint a cold re-resume read ahead of a replay redialed while REST w
     client.close()
   }
 })
+
+it('holds a background active-transcript refresh behind the reconnect replay', async () => {
+  const { result, client, second, request } = await mountWithPendingReplay()
+
+  const { activeSessionIdRef, selectedStoredSessionIdRef, sessionStateByRuntimeIdRef, updateSessionState } =
+    result.current.cache
+
+  selectedStoredSessionIdRef.current = storedId
+  activeSessionIdRef.current = runtimeId
+
+  try {
+    const refresh = reconcileActiveTranscript({
+      activeSessionIdRef,
+      busyRef: { current: false },
+      requestSequenceRef: { current: 0 },
+      resolveSession: () => ({ profile: 'default' }),
+      selectedStoredSessionIdRef,
+      signatureRef: { current: new Map() },
+      updateSessionState
+    })
+
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(getLatestSessionMessages).not.toHaveBeenCalled()
+
+    await act(async () => {
+      second.frame({ id: request.id, jsonrpc: '2.0', result: { events: replay } })
+      await refresh
+    })
+
+    expect(getLatestSessionMessages).toHaveBeenCalledTimes(1)
+    const text = sessionStateByRuntimeIdRef.current.get(runtimeId)!.messages.map(chatMessageText).join('\n')
+    expect(text.match(/Finished result\./g)).toHaveLength(1)
+  } finally {
+    client.close()
+  }
+})
diff --git a/apps/shared/src/json-rpc-gateway-replay.test.ts b/apps/shared/src/json-rpc-gateway-replay.test.ts
index 89316692ec..884bf37b26 100644
--- a/apps/shared/src/json-rpc-gateway-replay.test.ts
+++ b/apps/shared/src/json-rpc-gateway-replay.test.ts
@@ -368,6 +368,124 @@ describe('JsonRpcGatewayClient event-seq tracking + replay resume', () => {
     client.close()
   })
 
+  it.each(['timeout', 'unsupported'] as const)(
+    'settles sessions independently and releases fresh frames on replay %s',
+    async fallback => {
+      vi.useFakeTimers()
+      const client = makeClient()
+      const seen: string[] = []
+      client.onEvent(event => seen.push(`${event.session_id}:${event.type}:${event.seq}`))
+
+      try {
+        const first = client.connect('ws://x')
+        sockets[0].open()
+        await first
+
+        sockets[0].serverFrame({
+          jsonrpc: '2.0',
+          method: 'event',
+          params: { type: 'gateway.ready', payload: { replay_epoch: 'stable' } }
+        })
+
+        for (const sid of ['slow', 'fast']) {
+          sockets[0].serverFrame({
+            jsonrpc: '2.0',
+            method: 'event',
+            params: { type: 'session.info', session_id: sid, seq: 1 }
+          })
+        }
+
+        seen.length = 0
+        client.invalidate()
+        const second = client.connect('ws://x')
+        sockets[1].open()
+        await second
+        const slow = client.sessionReplayBarrier('slow')!
+        const fast = client.sessionReplayBarrier('fast')!
+        expect(slow).toBeInstanceOf(Promise)
+        expect(fast).toBeInstanceOf(Promise)
+        const requests = sockets[1].sent.map(text => JSON.parse(text))
+        const slowRequest = requests.find(request => request.params.session_id === 'slow')
+        const fastRequest = requests.find(request => request.params.session_id === 'fast')
+        const slowSettled = vi.fn()
+        void slow.then(slowSettled)
+
+        // Both ordinary parked starts and wire-marked replayed starts are fresh.
+        for (const [sid, seq] of [
+          ['slow', 2],
+          ['fast', 3]
+        ] as const) {
+          sockets[1].serverFrame({
+            jsonrpc: '2.0',
+            method: 'event',
+            params: { type: 'message.start', session_id: sid, seq, replayed: sid === 'fast' }
+          })
+        }
+
+        sockets[1].serverFrame({
+          jsonrpc: '2.0',
+          method: 'event',
+          params: { type: 'message.start', session_id: 'new', seq: 1 }
+        })
+        expect(seen).toEqual(['new:message.start:1'])
+
+        const fastSettled = fast.then(valid => {
+          expect(valid).toBe(true)
+          expect(seen).toEqual(['new:message.start:1', 'fast:message.complete:2', 'fast:message.start:3'])
+        })
+
+        sockets[1].serverFrame({
+          jsonrpc: '2.0',
+          id: fastRequest.id,
+          result: {
+            epoch: 'stable',
+            events: [{ type: 'message.complete', session_id: 'fast', seq: 2 }]
+          }
+        })
+        await fastSettled
+        expect(client.sessionReplayBarrier('fast')).toBeUndefined()
+        expect(client.sessionReplayBarrier('slow')).toBe(slow)
+        expect(slowSettled).not.toHaveBeenCalled()
+        sockets[1].serverFrame({
+          jsonrpc: '2.0',
+          method: 'event',
+          params: { type: 'message.delta', session_id: 'fast', seq: 4 }
+        })
+        expect(seen.at(-1)).toBe('fast:message.delta:4')
+
+        if (fallback === 'timeout') {
+          // The replay deadline is bounded independently of the 120s RPC default.
+          await vi.advanceTimersByTimeAsync(9_999)
+          expect(slowSettled).not.toHaveBeenCalled()
+          await vi.advanceTimersByTimeAsync(1)
+        } else {
+          sockets[1].serverFrame({
+            jsonrpc: '2.0',
+            id: slowRequest.id,
+            error: { code: -32601, message: 'method not found' }
+          })
+        }
+
+        await expect(slow).resolves.toBe(true)
+        expect(seen.at(-1)).toBe('slow:message.start:2')
+        expect(client.sessionReplayBarrier('slow')).toBeUndefined()
+        // Late replies after fallback cannot resurrect the old replay window.
+        sockets[1].serverFrame({
+          jsonrpc: '2.0',
+          id: slowRequest.id,
+          result: {
+            events: [{ type: 'message.delta', session_id: 'slow', seq: 99 }]
+          }
+        })
+        await Promise.resolve()
+        expect(client.getSeqWatermarks()).toEqual({ slow: 2, fast: 4, new: 1 })
+      } finally {
+        client.close()
+        vi.useRealTimers()
+      }
+    }
+  )
+
   // A backend restart announces a new epoch over the still-open socket. No
   // replay can cover the old numbering, so waiting history reads must proceed
   // (the reconnect backstop read, #94779) instead of being silently dropped.

From defb7033ff4e4507d38d769d20e406300f6a8790 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:39:33 -0700
Subject: [PATCH 60/61] fix(desktop): don't let a closed secondary veto a
 runtime an open socket serves

pendingSessionReplay() ANDs every reconnectable client's barrier. A
closed-but-wantOpen secondary that still holds a watermark for the runtime
answers false (it cannot replay yet), which vetoed history reads even when
another client had an open socket serving that runtime and already
ordering its events.

When some open client holds a watermark for the runtime, skip closed
clients' barriers; with no open client serving it the closed client's
false still drops the read as before.

Review follow-up on #121061.
---
 apps/desktop/src/store/gateway.ts | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/apps/desktop/src/store/gateway.ts b/apps/desktop/src/store/gateway.ts
index e7f7a10b23..37cad24405 100644
--- a/apps/desktop/src/store/gateway.ts
+++ b/apps/desktop/src/store/gateway.ts
@@ -543,7 +543,15 @@ export function pendingSessionReplay(runtimeId: string): Promise<boolean> | unde
   const reconnectable = [...g.secondaries.values()].filter(entry => entry.wantOpen && !entry.retiredByPool)
   const clients = new Set([g.primaryGateway, ...reconnectable.map(entry => entry.gateway)])
 
+  // A closed socket's false means only that IT cannot replay yet. When another
+  // open socket already serves this runtime, that socket orders the read.
+  const servedOpen = [...clients].some(client => isOpen(client) && client?.getSeqWatermarks?.()[runtimeId] != null)
+
   const pending = [...clients].flatMap(client => {
+    if (servedOpen && !isOpen(client)) {
+      return []
+    }
+
     // A dev-HMR survivor can predate the barrier method.
     const barrier = client?.sessionReplayBarrier?.(runtimeId)
 

From 58c896ea4ebaff5425a068f461b6c6fedadb8b40 Mon Sep 17 00:00:00 2001
From: "hermes-seaeye[bot]"
 <307254004+hermes-seaeye[bot]@users.noreply.github.com>
Date: Thu, 24 Sep 2026 05:53:55 +0000
Subject: [PATCH 61/61] fmt(js): `npm run fix` on merge (#121111)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
---
 apps/desktop/src/components/chat/image-geometry.test.tsx | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/apps/desktop/src/components/chat/image-geometry.test.tsx b/apps/desktop/src/components/chat/image-geometry.test.tsx
index 9ccc41b489..9792228124 100644
--- a/apps/desktop/src/components/chat/image-geometry.test.tsx
+++ b/apps/desktop/src/components/chat/image-geometry.test.tsx
@@ -123,7 +123,9 @@ it('keeps the pending generated-image frame when its result arrives', async () =
   mounted.rerender(<GeneratedImage aspectRatio="landscape" />)
   expect(parseFloat(frame(mounted.container).style.aspectRatio)).toBeCloseTo(16 / 9)
   const pendingStyle = frame(mounted.container).style.cssText
-  mounted.rerender(<GeneratedImage aspectRatio="landscape" result={{ success: true, image: path, pixel_size: '900x600' }} />)
+  mounted.rerender(
+    <GeneratedImage aspectRatio="landscape" result={{ success: true, image: path, pixel_size: '900x600' }} />
+  )
 
   // Must hold before the file read settles, not just after img.onload.
   expect(frame(mounted.container).style.cssText).toBe(pendingStyle)
@@ -141,7 +143,9 @@ it('keys inline data sources by a bounded digest so they are remembered', async
   first.unmount()
 
   expect(parseFloat(frame(render(<MarkdownImage alt="inline" src={big('A')} />).container).style.aspectRatio)).toBe(1.5)
-  expect(parseFloat(frame(render(<MarkdownImage alt="inline" src={big('B')} />).container).style.aspectRatio)).not.toBe(1.5)
+  expect(parseFloat(frame(render(<MarkdownImage alt="inline" src={big('B')} />).container).style.aspectRatio)).not.toBe(
+    1.5
+  )
 })
 
 it.each(['markdown', 'generated'])('%s dimensions follow owner and source, not stale reads or hints', async kind => {